Skip to content

Let setup finish when the hosted service cannot be reached - #24

Merged
jbwinters merged 5 commits into
mainfrom
fix/offline-setup-20261115
Nov 15, 2026
Merged

jbwinters merged 5 commits into
mainfrom
fix/offline-setup-20261115

Conversation

@jbwinters

@jbwinters jbwinters commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

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 --setup and setup all 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

  • Deferral only for real network failures. Node reports almost every transport failure as "fetch failed", so setup classifies by the underlying cause: refused, unreachable, reset or timed-out connections, DNS unavailable (EAI_AGAIN, EAI_FAIL), a sandbox denying connect() (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 prints registration: deferred (<cause>); --json carries registrationDeferred and registrationDeferredReason.
  • Wrong addresses still fail. A response refusing sign-in, a failed challenge, a redirect, a certificate error, any failure to reach a loopback address (including a timeout), a listener that drops the connection, a proxy answering 407/502/504, or an unknown host name (other than crosshead.sh) fails setup and saves nothing. The error names the cause by code only (never text from the other end, such as certificate names) and suggests checking --api-base (and the proxy settings, for proxy errors); a 404 keeps its HTTP status and code in --json output. A proxy that intercepts TLS is not recognised, and Node uses HTTPS_PROXY only with NODE_USE_ENV_PROXY=1; the README says both.
  • Every setup path reports it, the same way. keygen --setup, setup, quickstart and the guided project setup all show registration: deferred; their --json output carries registrationDeferred: true and registrationDeferredReason (guided setup adds registrationDeferredProfiles).
  • Doctor explains a profile with no session. It says the profile has not signed in yet or its session was cleared, and why the attempt failed: the network cause by code, or only the HTTP status and code (never text chosen by the other end). A local-only profile no longer reports hosted reach or sign-in failures.
  • The client signs in on its next hosted request, the same path it uses when a session expires.
  • README and help document the local-only profile (--api-base http://127.0.0.1:0).

Verification

  • npm test: 63 files, 564 tests pass (tests/runtime/offline-setup.test.ts has 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:check and npm run check:boundary pass.

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.

@jbwinters
jbwinters force-pushed the fix/offline-setup-20261115 branch from 194cb94 to 1c0ba31 Compare November 15, 2026 18:48
@jbwinters
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
jbwinters force-pushed the fix/offline-setup-20261115 branch from 1c0ba31 to aebfee3 Compare November 15, 2026 18:52
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.
@jbwinters
jbwinters merged commit 515945f into main Nov 15, 2026
8 checks passed
@jbwinters
jbwinters deleted the fix/offline-setup-20261115 branch November 15, 2026 20:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant