Decompose: Documented concurrency contract (throughput, per-request bounds, failure semantics) — Phase 3: Failure semantics (questions 7, plus the "what if stage N fails?" case) #71

New issue

Closed

opened 2026-06-22 16:31:52 +00:00 by Mark · 0 comments

Mark commented

2026-06-22 16:31:52 +00:00

Owner

Phase 3: Failure semantics (questions 7, plus the "what if stage N fails?" case)

Goal: Lock the failure-mode behavior.

Specifically:

Failure mode on partial completion? Answer: if a stage fails,
the response is 503 with body {"error": "...", "failed_stage": "...", "completed_stages": [...], "request_id": "..."}. The
pipeline cleans up any partial state (temp files, half-built
stitch objects).

Plus: what happens on invalid input (malformed PNG, oversize
upload, unsupported format)? Answer: 400 Bad Request with a
specific error code per failure mode (NOT 500).
Plus: what's the log format on errors? Answer: structured JSON
with request_id, stage, error, stack (configurable).

Files:

Modify: docs/concurrency.md (add failure-mode section)
Modify: docs/service/operations.md (cross-link from the error
response shape)

Acceptance:

All failure modes documented with response shape and HTTP code.
A test for each documented failure mode asserts the response.
An integration test simulates a stage failure mid-pipeline and
asserts the partial-state cleanup happened (no orphan temp files).

Depends on: P1, P2.

Out of scope

The actual implementation of the worker pool, queue, timeout, and
cancellation logic. Those go in the relevant service tickets
(issue #31 P2 for the handlers, P5 for the worker pool).
Operational concerns beyond the request lifecycle (rolling deploys,
A/B testing, blue-green) — separate doc, separate ticket.
Per-user rate limiting — not in scope for v1 (single-user Tailnet).
If multi-user support is added later, a rate-limit section can be
added to docs/concurrency.md.

Decomposed from easystitch#43

## Phase 3: Failure semantics (questions 7, plus the "what if stage N fails?" case) **Goal:** Lock the failure-mode behavior. **Specifically:** 7. **Failure mode on partial completion?** Answer: if a stage fails, the response is 503 with body `{"error": "...", "failed_stage": "...", "completed_stages": [...], "request_id": "..."}`. The pipeline cleans up any partial state (temp files, half-built stitch objects). - **Plus:** what happens on invalid input (malformed PNG, oversize upload, unsupported format)? Answer: 400 Bad Request with a specific error code per failure mode (NOT 500). - **Plus:** what's the log format on errors? Answer: structured JSON with `request_id`, `stage`, `error`, `stack` (configurable). **Files:** - Modify: `docs/concurrency.md` (add failure-mode section) - Modify: `docs/service/operations.md` (cross-link from the error response shape) **Acceptance:** - All failure modes documented with response shape and HTTP code. - A test for each documented failure mode asserts the response. - An integration test simulates a stage failure mid-pipeline and asserts the partial-state cleanup happened (no orphan temp files). **Depends on:** P1, P2. ## Out of scope - The actual implementation of the worker pool, queue, timeout, and cancellation logic. Those go in the relevant service tickets (issue #31 P2 for the handlers, P5 for the worker pool). - Operational concerns beyond the request lifecycle (rolling deploys, A/B testing, blue-green) — separate doc, separate ticket. - Per-user rate limiting — not in scope for v1 (single-user Tailnet). If multi-user support is added later, a rate-limit section can be added to `docs/concurrency.md`. --- _Decomposed from [easystitch#43](https://forgejo.tail018ac4.ts.net/Mark/easystitch/issues/43)_