Decompose: Documented concurrency contract (throughput, per-request bounds, failure semantics) — Phase 1: Throughput answers (questions 1, 5, 6) #69

New issue

Closed

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

Mark commented

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

Owner

Phase 1: Throughput answers (questions 1, 5, 6)

Goal: Lock the throughput policy.

Specifically:

Max concurrent digitize requests? Answer: 4 (= N CPU cores on
the target box; configurable via WORKER_POOL_SIZE).
Queue ordering? Answer: FIFO. No priority by user or by input
size.
Backpressure signal? Answer: HTTP 503 with Retry-After: N
header, where N is the p50 queue wait time. Document the exact
header shape.

Files:

New: docs/concurrency.md (initial version with these 3 questions
answered; the other 4 follow in P2/P3)
Modify: docs/service/operations.md (issue #40 P2) to reference
the concurrency policy

Acceptance:

docs/concurrency.md has a section per answered question with the
value, the rationale, and the source (benchmark, calculation, or
decision doc).
The values are testable: a load test can assert "5 concurrent
requests get 503 with Retry-After" against the spec.
The ThreadCraft team agrees on the values.

Why first: throughput answers constrain the design of the worker
pool and the request queue. They should be locked before any service
code is written.

Decomposed from easystitch#43

## Phase 1: Throughput answers (questions 1, 5, 6) **Goal:** Lock the throughput policy. **Specifically:** 1. **Max concurrent digitize requests?** Answer: 4 (= N CPU cores on the target box; configurable via `WORKER_POOL_SIZE`). 5. **Queue ordering?** Answer: FIFO. No priority by user or by input size. 6. **Backpressure signal?** Answer: HTTP 503 with `Retry-After: N` header, where N is the p50 queue wait time. Document the exact header shape. **Files:** - New: `docs/concurrency.md` (initial version with these 3 questions answered; the other 4 follow in P2/P3) - Modify: `docs/service/operations.md` (issue #40 P2) to reference the concurrency policy **Acceptance:** - `docs/concurrency.md` has a section per answered question with the value, the rationale, and the source (benchmark, calculation, or decision doc). - The values are testable: a load test can assert "5 concurrent requests get 503 with Retry-After" against the spec. - The ThreadCraft team agrees on the values. **Why first:** throughput answers constrain the design of the worker pool and the request queue. They should be locked before any service code is written. --- --- _Decomposed from [easystitch#43](https://forgejo.tail018ac4.ts.net/Mark/easystitch/issues/43)_