desk-ops

With follow=1: Server-Sent Events output, then end (the job as it ended), interrupted (following stopped; the job goes on) or error, each event's data one JobLogEvent object. A failure after the stream started is its last event, error (no job by that name, the desk lost, …), and the call's audit event records that failure, not the 200. Output buffered for a JSON answer is capped at 8 MB.

Answers the job as it ended (timed_out: false) or, when timeout ran out first, as it stands, still running (timed_out: true). The job object is what gaiadesk-cli wait --json prints. No such job answers 422 failed, as the CLI does.

A wait is held at most 870 seconds, under the 15-minute limit of every call; wait again for longer. Keep-alive aware: an answer that takes longer than a moment (1.5 s) starts its 200 at once, with GaiaDesk-Held: 1, and holds the body open, sending one space every 15 seconds (whitespace before a JSON value is still JSON) until the outcome, so proxies never see a silent connection. A status cannot change once sent, so a held body is either the result ({"job", "timed_out"}) or, should the desk fail after that point, the error envelope ({"error"}, with error.status the status it would have had): read the body, and treat error as the failure. An answer within the first moments is an ordinary one, its failures real HTTP errors. Either way, the call's audit event records the outcome (ok, failed, …, or cancelled when the caller hung up first), not the 200.

Why not 202 and polling, or 102 Processing: a job is already the resource a caller polls (timeout=0 answers at once), so a 202 would add a second resource for nothing; 102 is a WebDAV interim response that fetch, most HTTP clients and proxies never surface; and trailers are dropped by browsers and most proxies. The held 200 is one request, with the outcome always in a body every client reads.