Repository navigation
Let setup finish when the hosted service cannot be reached - #24
Merged
Merged
Conversation
jbwinters
force-pushed
the
fix/offline-setup-20261115
branch
from
November 15, 2026 18:48
194cb94 to
1c0ba31
Compare
jbwinters
changed the base branch from
feat/scoped-onboarding-20261114
to
main
November 15, 2026 18:48
Setup signed in to the hosted service before it saved the profile, so `quickstart`, `keygen --setup` and `setup` all failed with "fetch failed" on a machine with no route to it: a sandbox with restricted egress, a CI job, a laptop offline. Capture and recall are local-first and already worked for a profile with no session, so nothing else needed the sign-in at that moment. When the service is unreachable (no route, refused connection, timeout), setup now saves the profile with no session and reports `registration: deferred`. The client signs in on its first hosted request, as it already does when a session expires. A response that refuses the sign-in, or a challenge that fails validation, still fails setup. Also documents the local-only profile (`--api-base http://127.0.0.1:0`), which existed and was used by tests but appeared in no help or README text.
jbwinters
force-pushed
the
fix/offline-setup-20261115
branch
from
November 15, 2026 18:52
1c0ba31 to
aebfee3
Compare
Classify sign-in failures by the fetch error's cause code: refused, unreachable, reset and timed-out connections defer; redirects, certificate and proxy errors, and an unknown host name (except crosshead.sh) fail setup. The deferral line names the network error, guided project setup now reports it, and doctor says when a profile has never signed in and why the sign-in failed.
…therwise An allowlisting proxy (the sandbox case that prompted the change) reports UND_ERR_ABORTED 'Proxy response (403) !== 200 when HTTP Tunneling'; treat it as unreachable. When setup does fail on a fetch error, say which: the cause code and message plus a hint to check --api-base. Doctor no longer reports hosted reach or sign-in failures for a local-only profile.
Defer also for sandbox connect() denials (EPERM, EACCES) and EAI_FAIL / EADDRNOTAVAIL. Fail instead of deferring for a refused loopback address, a listener that drops the connection (UND_ERR_SOCKET), and proxy responses other than 403. Errors name the cause once, mention HTTPS_PROXY for proxy failures, and explain a 404 from a non-Crosshead address. Doctor reports a network failure's cause and an HTTP failure's status and code only, never server-chosen text, and no longer claims a profile whose session was cleared has never signed in. keygen, quickstart and guided setup now all report registrationDeferred: true with registrationDeferredReason. The CLI test runs the real CLI with fetch stubbed before load.
…pback Fetch failures are described by error code (with a short label), undici's own fixed messages, or a proxy status only: free-text causes can carry text chosen by the other end, such as names in a mismatched TLS certificate. Any failure to reach a loopback address (localhost, *.localhost, 127/8, 0.0.0.0, ::1), including a timeout, fails setup instead of deferring. The 404 explanation keeps HostedOnlyBotsRequestError so --json still reports the status and code. setup gains --json with the deferral fields; plain quickstart text says 'registration: deferred'. README notes that Node uses HTTPS_PROXY only with NODE_USE_ENV_PROXY=1.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Setup signed in to the hosted service before saving the profile. On a machine with no route to it (a sandbox with restricted egress, a CI job, a laptop offline),
quickstart,keygen --setupandsetupall failed with "fetch failed", so Crosshead could not be installed there at all. Local capture and recall already work for a profile with no session.Change
EAI_AGAIN,EAI_FAIL), a sandbox denyingconnect()(EPERM,EACCES), no usable source address, and an egress proxy refusing the destination with 403 defer. The profile is saved with no session and setup printsregistration: deferred (<cause>);--jsoncarriesregistrationDeferredandregistrationDeferredReason.--api-base(and the proxy settings, for proxy errors); a 404 keeps its HTTP status and code in--jsonoutput. A proxy that intercepts TLS is not recognised, and Node usesHTTPS_PROXYonly withNODE_USE_ENV_PROXY=1; the README says both.keygen --setup,setup, quickstart and the guided project setup all showregistration: deferred; their--jsonoutput carriesregistrationDeferred: trueandregistrationDeferredReason(guided setup addsregistrationDeferredProfiles).--api-base http://127.0.0.1:0).Verification
npm test: 63 files, 564 tests pass (tests/runtime/offline-setup.test.tshas 14, including the exact error Node 26 raises when a proxy refuses the tunnel, and guided project setup run as a real CLI process, text and--json, with fetch stubbed before load so nothing leaves the machine).npm run plugins:checkandnpm run check:boundarypass.Not tested: Node 22/24 error shapes (only Node 26 was available locally; CI runs the hand-built cases on 22 and 24), a deferred profile later signing in against the real service, and a real restricted-egress sandbox. Offline setup can still wait up to 15 s on a network that silently drops packets, and a timeout after the service has answered the challenge also defers.