Skip to content

13-exit-codes.md

Latest commit

 

History

History
74 lines (53 loc) · 3.63 KB

13-exit-codes.md

File metadata and controls

74 lines (53 loc) · 3.63 KB
Raw

13 — Exit codes

13.1 Why this matters

The client's exit code is the only thing an automated caller sees. It must distinguish, unambiguously:

  • the command ran and succeeded;
  • the command ran and failed;
  • the command was refused;
  • the command never ran because nothing was listening;
  • the client gave up waiting, and the command may still be running.

Collapsing any two of these produces a wrong next action. "Nothing was listening" means install or start the bridge. "Refused" means change the request or the configuration. "Gave up waiting" means go and look at the host, and above all do not retry, because a retry may duplicate a long-running mutation.

13.2 Normative table

CHB-601 A client MUST exit with the following codes.

Code Meaning Correct next action
0 Terminal state done. Continue.
64 Client-side usage error: unknown verb, malformed or missing argument. The request was never written. Fix the invocation.
69 No acknowledgement within the acknowledgement timeout and the request is no longer in the spool, or was never accepted: the bridge is unavailable. Ask the operator to install or start it.
70 Terminal state denied or expired. Read detail. Usually a configuration gap; see 03.
75 The client stopped polling before a terminal state. The command may still be running on the host. Inspect the host. Do not retry.
76 An acknowledgement was seen but the bridge is busy and the client chose not to keep waiting. Wait and re-check; the bridge is healthy.
other Terminal state failed: the underlying command's own exit code. Read the captured output.

CHB-602 A client MUST NOT report code 69 while its request is still present in the request directory. A pending request proves the spool is reachable, and an implementation that is merely busy will reach it. See 15.

CHB-603 Code 75 MUST NOT be treated as retryable by any automated caller.

13.3 Collision with the underlying command's codes

The "other" row is a genuine hazard: the orchestration script is free to exit with any code, including 64, 69, 70, 75 or 76.

CHB-604 A client MUST disambiguate an underlying command's exit code that collides with a bridge-reserved code.

CHB-605 The RECOMMENDED disambiguation is to add a fixed offset — 128 — to a colliding underlying code, and to document that mapping.

So an underlying command exiting 70 surfaces as 198, while a bridge denial surfaces as 70. A caller can then distinguish them, and a reader of the documentation can invert the mapping.

CHB-606 Whatever disambiguation is chosen, it MUST be documented and MUST be lossless: the original code MUST be recoverable, and MUST also be recorded verbatim in the response document's exit_code field.

CHB-607 The response document's exit_code MUST be the underlying command's own code, unmapped. The mapping is a client-side concern only.

13.4 Timeouts and budgets

CHB-608 A client MUST have a short acknowledgement timeout, distinct from its overall polling budget.

CHB-609 A client MUST have a per-verb polling budget sized for that verb. A status call and an image rebuild do not deserve the same patience.

CHB-610 The longest per-verb polling budget MUST be shorter than the freshness lifetime configured on the host. See 15.

CHB-611 On exceeding the polling budget, the client MUST exit 75 and MUST print where to look: the response document, the captured output, and the audit log.