registry: tell a package's fault from the environment's in documentation renders

orion commented

2026-10-08 22:38:45 +00:00

Collaborator

Follow-up of #17.

The documentation worker reads exit code 1 of torb doc as the package's verdict and marks the version failed with no retry. Some failures of the environment also exit with 1 and so become permanent:

a full disk,
a write over the file-size limit,
a decode error of a dependency file.

At start the worker re-queues failed versions only when the toolchain string changes, and that string is the same for every build of a version.

Proposal:

Classify these failures as retryable (Interrupted), e.g. by the output of torb, or let torb doc exit with a distinct code for I/O failures.
Add a build identity to the toolchain string the worker records.
While at it, decide the remaining points of the review of #17:
- Fair queue order per owner, so one account's timeouts do not delay everyone.
- The race between an operator's re-queue and an in-flight render.
- Re-render without a window of 404s (stage, then swap).
- Report a worker that did not start in /api/1/health.
- Measure whether unpacking and walking on the server's tasks stalls API requests.
- A nested project.trb such as an example's now has to carry an owner/name name: skip nested manifests instead, or check the name at upload so authors learn it when they publish.

Acceptance: a render that fails for disk or limit reasons is retried and does not end failed at once; each other point is either done or closed as decided.

Epic checklist (a step becomes its own issue only when it starts next):

Step 1: I/O failures retried, build identity in the toolchain string (#498)
Fair queue order per owner (round-robin on package owner in the next query)
Re-queue versus in-flight render (the re-queue must not be overwritten by the running attempt's recorded)
Re-render without a window of 404s (stage under a new prefix, then swap)
Worker that did not start in /api/1/health
Measure whether unpacking and walking stalls API requests (measure in forge CI first, then decide)
Nested project.trb: skip nested manifests (decided, see the comment)

Acceptance (epic): every box is ticked or closed with a recorded decision.

Follow-up of #17. The documentation worker reads exit code 1 of `torb doc` as the package's verdict and marks the version `failed` with no retry. Some failures of the environment also exit with 1 and so become permanent: - a full disk, - a write over the file-size limit, - a decode error of a dependency file. At start the worker re-queues failed versions only when the toolchain string changes, and that string is the same for every build of a version. **Proposal:** - Classify these failures as retryable (`Interrupted`), e.g. by the output of `torb`, or let `torb doc` exit with a distinct code for I/O failures. - Add a build identity to the toolchain string the worker records. - While at it, decide the remaining points of the review of #17: - Fair queue order per owner, so one account's timeouts do not delay everyone. - The race between an operator's re-queue and an in-flight render. - Re-render without a window of 404s (stage, then swap). - Report a worker that did not start in `/api/1/health`. - Measure whether unpacking and walking on the server's tasks stalls API requests. - A nested `project.trb` such as an example's now has to carry an `owner/name` name: skip nested manifests instead, or check the name at upload so authors learn it when they publish. **Acceptance:** a render that fails for disk or limit reasons is retried and does not end `failed` at once; each other point is either done or closed as decided. **Epic checklist** (a step becomes its own issue only when it starts next): - [ ] Step 1: I/O failures retried, build identity in the toolchain string (#498) - [ ] Fair queue order per owner (round-robin on `package` owner in the `next` query) - [ ] Re-queue versus in-flight render (the re-queue must not be overwritten by the running attempt's `recorded`) - [ ] Re-render without a window of 404s (stage under a new prefix, then swap) - [ ] Worker that did not start in `/api/1/health` - [ ] Measure whether unpacking and walking stalls API requests (measure in forge CI first, then decide) - [ ] Nested `project.trb`: skip nested manifests (decided, see the comment) **Acceptance (epic):** every box is ticked or closed with a recorded decision.

orion added the

loop

label

2026-10-08 22:38:45 +00:00

orion referenced this issue

2026-10-08 22:39:01 +00:00

feat(registry): render each published version's documentation with torb doc --no-run #237

orion referenced this issue

2026-10-09 00:18:46 +00:00

registry: the documentation worker that runs torb doc for every version #17

orion referenced this issue

2026-10-09 01:26:41 +00:00

doc: generate the ## Declarations sections of the standard library pages #32

orion commented

2026-10-09 05:46:21 +00:00

Author

Collaborator

[loop:torbscript] intake: in scope (author orion, label loop), follow-up of #17, not a duplicate. Documentation worker should tell a package's fault from an environment failure. next: waiting (refine queued, ready buffer full) until 2026-10-10T04:00:00Z

orion commented

2026-10-26 09:56:08 +00:00

Author

Collaborator

[loop:torbscript] claim refine by session:loop-torbscript-20261026-1044 until 2026-10-26T11:56:08Z

orion referenced this issue

2026-10-26 09:57:19 +00:00

registry: run the documentation worker's renders in bubblewrap (step 1 of #233) #497

orion referenced this issue

2026-10-26 09:57:25 +00:00

registry: retry documentation renders that fail for I/O reasons (step 1 of #236) #498

orion referenced this issue

2026-10-26 09:57:33 +00:00

registry: isolate the documentation worker's runs from the service #233

orion commented

2026-10-26 09:57:50 +00:00

Author

Collaborator

[loop:torbscript] decided by the loop:

Classification by a distinct exit code, not by parsing torb output: torb doc exits 74 (EX_IOERR) on an IoError, 1 stays the verdict on the package. Output parsing breaks with every wording change; the exit code is one line in the caller of endWith and testable. A decode error of a dependency file is an IoError of the toolchain reading it, so it counts as the environment.
Build identity: the worker appends the first 12 hex of the sha-256 of the torb executable to the recorded toolchain. No compiler change or version plumbing, differs for every build; the start-up query toolchain != ... then re-queues failed versions after each new build.
Nested project.trb: the worker skips nested manifests (not the package's own); the root manifest keeps its name check. Publishers lose nothing and no existing package gets a new upload refusal.
Re-render without 404s: stage under a separate prefix and swap by writing the index last; the exact scheme is decided in that step.
Remaining points stay on the checklist, filed just in time.
Size: eight points across worker, compiler and docs are more than one PR, so #236 is an epic without ready; step 1 is #498 (ready).

[loop:torbscript] decided by the loop: - Classification by a distinct exit code, not by parsing `torb` output: `torb doc` exits 74 (EX_IOERR) on an `IoError`, 1 stays the verdict on the package. Output parsing breaks with every wording change; the exit code is one line in the caller of `endWith` and testable. A decode error of a dependency file is an `IoError` of the toolchain reading it, so it counts as the environment. - Build identity: the worker appends the first 12 hex of the sha-256 of the `torb` executable to the recorded toolchain. No compiler change or version plumbing, differs for every build; the start-up query `toolchain != ...` then re-queues failed versions after each new build. - Nested `project.trb`: the worker skips nested manifests (not the package's own); the root manifest keeps its name check. Publishers lose nothing and no existing package gets a new upload refusal. - Re-render without 404s: stage under a separate prefix and swap by writing the index last; the exact scheme is decided in that step. - Remaining points stay on the checklist, filed just in time. - Size: eight points across worker, compiler and docs are more than one PR, so #236 is an epic without `ready`; step 1 is #498 (`ready`).

orion commented

2026-10-26 09:57:50 +00:00

Author

Collaborator

[loop:torbscript] refine: too large for one PR, so #236 is an epic (checklist in the body, no ready). First step filed as #498 with loop and ready (keyword search of all issues for "documentation worker" found no duplicate; touches no seed). Technical points decided above; no dependency on unmerged work. next: waiting (epic; #498 goes through implement, later steps are filed just in time). Claim of session:loop-torbscript-20261026-1044 released. Tokens: ~70k.

[loop:torbscript] refine: too large for one PR, so #236 is an epic (checklist in the body, no `ready`). First step filed as #498 with `loop` and `ready` (keyword search of all issues for "documentation worker" found no duplicate; touches no seed). Technical points decided above; no dependency on unmerged work. next: waiting (epic; #498 goes through implement, later steps are filed just in time). Claim of session:loop-torbscript-20261026-1044 released. Tokens: ~70k.

orion referenced this issue from a commit

2026-10-26 13:20:29 +00:00

fix(compiler): exit 74 when torb doc ends with an I/O error

orion referenced this issue from a commit

2026-10-26 13:22:56 +00:00

fix(registry): retry documentation renders that fail with exit 74

orion referenced this issue

2026-10-26 13:22:59 +00:00

fix(registry): retry documentation renders that fail with exit 74 #501

orion referenced this issue from a commit

2026-10-26 14:54:47 +00:00

fix(registry): retry documentation renders that fail with exit 74