mocactl: login failures hide the control plane and the API error; no way to capture failure details

Aperta
  • Qualcosa non va?
#700 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
node.js, typescript
Ambito
backend-api-design, cli, observability

Direzione di ricerca

Start with packages/mocactl/src/api/errors.ts and packages/mocactl/src/core/messages.ts, then trace the login requests and control-plane response handling to see where URL sources and request details are available. The proposal spans client errors, request logging, report generation, and server response IDs; check the related server code and tests before estimating the full scope. Done means the acceptance criteria are met, including redaction and distinct messages for the listed failure causes.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

enhancement

Problem

1. A failed login doesn't say where it went or what came back

When the control plane answers with a 5xx, mocactl sbx login (and mocactl login, and the TUI) prints only:

sbx: the control plane is unavailable — try again shortly

classify() (packages/mocactl/src/api/errors.ts:136) maps every status ≥ 500, plus redis_unavailable, credential_unavailable and internal_error, to unavailable and keeps only the source. describeError() (packages/mocactl/src/core/messages.ts:46) then prints a fixed sentence. mocactl parses the status, the server's error code and message, and Retry-After into the ApiError, then drops them.

So the user can't tell:

  • Which control plane was tried. The URL comes from --control-plane-url, MOCACTL_SBX_URL, the bound sandbox, or the one saved at an earlier login (sbxControlPlaneUrl in config.json). A user may not remember which one is in effect, and the message doesn't say.

  • Why it failed. These all look alike:

    • the control plane is down for maintenance
    • a firewall or corporate proxy answered instead (a non-JSON page is reported as http_<status>, or as "unavailable" when it is a 5xx)
    • the control plane has moved
    • a real server bug

    "Try again shortly" only helps in the maintenance case.

  • Which step failed: GET /v1/discovery, POST /v1/auth/device, or POST /v1/auth/device/token.

2. API failure details can't be seen or reported

mocactl has no --verbose or --debug flag and no env var for one. The only MOCACTL_* variables it reads are MOCACTL_SBX_URL and MOCACTL_VERSION. The only way to see a failing response today is to replay the requests with curl.

  • Developers need these details for each request: method, URL, status, error code and message, Retry-After, the network cause code (ECONNREFUSED, UND_ERR_HEADERS_TIMEOUT, …), and timing.
  • Users need a way to send those details to developers without leaking tokens. The control plane also returns no request ID, so there's nothing in a client-side report to match against the server logs.

Proposal

Error messages

  • Name the control-plane URL and its source (flag, env, sandbox, saved config) in every login failure and every "unavailable" or "cannot reach" message.
  • Put the HTTP status and the server's error code, plus message when present, in the one-line error. For example: sbx: the control plane at https://… is unavailable (503 redis_unavailable) — try again shortly.
  • Give different advice for different causes:
    • 503 with Retry-After or a maintenance code: down for maintenance, retry in N seconds.
    • A non-JSON response: something other than the control plane answered (a proxy or firewall?).
    • A DNS failure, a 404 at /v1/discovery, or a redirect to another host: the control plane may have moved, so check the URL.
    • A 500: a server error to report (see below).
  • Server side: add a maintenance signal the client can recognize, such as a 503 with Retry-After and {"error":"maintenance"}. There is none today.

Logging and reporting

  • An opt-in debug switch (--debug and/or MOCACTL_DEBUG=1) that writes one line per request to stderr: method, URL, status, code, message, timing, and cause code.
  • A local, rotated log of failed requests under $XDG_STATE_HOME/mocactl/, with the same fields. It should be 0600 like the sbx flight recorder (<state>/sbx/<id>.log). It must never record tokens, Authorization headers, device codes, or any body content other than the error JSON.
  • A command that builds a redacted report for a bug ticket, such as mocactl doctor --report. It would include the mocactl version, Node version, platform, the effective control-plane URLs and their sources, and the recent failures from the log.
  • A request ID on every control-plane response (such as X-Request-Id). The server logs it, and the client includes it in the error line and its log, so a user's report can be matched to the server's logs.

Acceptance criteria

  • A login that fails with a 5xx prints the URL, its source, the step that failed, the status, and the server's error code.
  • Maintenance, proxy/firewall, moved-control-plane, and server-error failures each get their own message.
  • With the debug switch on, the outcome of every request appears on stderr. With it off, output is unchanged.
  • A user can produce a redacted report file with one command and attach it to an issue.
Lingua principale
TypeScript
Stelle
12
Fork
12
Merge medio
9h 27m
PR unite (30g)
164

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di rossoctl/moca

Tutte le issue di rossoctl/moca

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.