about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-08 13:28:27 +0000
committerPjotr <wrk@bosa.lan>2026-11-08 13:28:27 +0000
commit875d680a9c3cfe7f3b5a92f86ce211b5a5dfcbb4 (patch)
tree4b1790d6eeb321c0e5ca2fdb0acfe0a68b508865 /docs
parente5c2aa0ab1e568fe91c63cd5257aee7ff08ebed9 (diff)
downloadgenenetwork4-875d680a9c3cfe7f3b5a92f86ce211b5a5dfcbb4.tar.gz
compute: one gemma job at a time, per caller, via #[compute_gate]
`POST /compute/gemma` now takes a single slot: one job runs at a time
across all callers, a second submission from the same token is refused
immediately with `409 compute_busy` (whatever it would have waited for,
its own job is already in the way), and a submission from another token
waits for the running job and then runs. Nothing else is gated -- ravanan
and /compute/rqtl are untouched.

The gate is one `tokio::sync::Semaphore(1)` (fair: waiters take the
permit in arrival order) plus a `Mutex<HashSet<String>>` of subjects
holding the slot or queued for it, in a per-process static. The claim is
moved into the spawned job task, so a client disconnect -- which does not
kill the child process -- cannot hand the slot to somebody else while the
CPU is still busy.

The endpoint carries none of that: `#[compute_gate(gemma, run_id =
params.id.as_deref())]` expands to a claim and a run, and requires the
handler to take `Ctx` and `AuthToken` (every compute endpoint is
token-only, and the token's sub is the key), so an endpoint that is not
token-gated cannot be decorated. The policy -- the 409's status, code,
wording and next link -- stays in plain Rust (`Gate::claim_or_busy`), so
the gate's own tests cover it; the attribute is decoration over two calls.

* src/compute_gate.rs: new. Gate, Claim (released on drop, including a
panic), Busy, claim/claim_or_busy/run, and four tests, two of them on a
four-thread runtime (the earlier ones ran single-threaded and so never
exercised the cross-thread hand-off; one now asserts at most one task
inside the slot across eight tasks).
* gnauth-macros/src/lib.rs: the `compute_gate` attribute, alongside the
`gnauth` markers it shares `syn`/`quote` with; arguments documented
(gate, endpoint, status, run_id) for the endpoints still to be gated.
* src/routes/gemma.rs: the decorator replaces 57 lines of claim and
spawn plumbing in compute_gemma.
* docs/www/ai-instruction.md (4a, 5): one job at a time per caller, and
that a `compute_busy` 409 means poll, not resubmit.
Diffstat (limited to 'docs')
-rw-r--r--docs/www/ai-instruction.md11
1 files changed, 10 insertions, 1 deletions
diff --git a/docs/www/ai-instruction.md b/docs/www/ai-instruction.md
index 794167b..4e8498b 100644
--- a/docs/www/ai-instruction.md
+++ b/docs/www/ai-instruction.md
@@ -447,6 +447,15 @@ against a genome-wide threshold. (gemma-wrapper itself can shuffle
 phenotypes with `--permutate n`; this API does not pass it — see
 docs/genotypes.md.)
 
+**One job at a time, per caller.** `/compute/gemma` runs one job at a
+time across all callers: a second submission from *your* token while your
+job is still running — or still queued — is refused at once with
+`409 compute_busy`, naming the run and linking its status endpoint; a
+submission from *another* token waits for the running job to finish and
+then runs. So a 409 here is not a retry-able failure: poll
+`/compute/gemma/status/{id}`, and only then submit the next job. Map one
+trait, read it, submit the next.
+
 Results are **cached** by input, so running the same request twice costs
 little the second time (a cached GEMMA run on the BXD fixtures comes back
 in ~2 s against ~20 s cold). That is another reason not to compute
@@ -609,7 +618,7 @@ Errors are RFC 7807-style JSON (`type`, `title`, `status`, `code`,
 | 403 | `forbidden` | the data is not public: do not retry |
 | 404 | `not_found` | check the name; `next` often lists the valid values |
 | 422 | `invalid_query`, `invalid_lmm` | fix the query or parameter; do not retry |
-| 409 | `run_id_in_use` | the `?id=` you chose is already in use: pick another, or poll `/compute/{rqtl,gemma}/status/{id}` |
+| 409 | `run_id_in_use`, `compute_busy` | the `?id=` you chose is taken (`run_id_in_use`: pick another), or your own compute job is still running (`compute_busy`: poll the status endpoint it links — do **not** resubmit) |
 | 413 | — (plain text, **not** JSON) | the request body is over the 64 MiB limit: send fewer values, or none at all (§4a's `case_attribute`) |
 | 429 | — | back off, honour `Retry-After` (not currently emitted, but written into the API's contract) |
 | 500 | `database_error` | if the `detail` mentions a connection (`Broken pipe`, `Connection reset`, `server has gone away`) it is transient: retry **once**, then report; otherwise treat it as a bug and report it with the `request_id` |