client: detach, attach, and finish a transaction by bare id (#13)

[sshaplygin]

Closes #13.

What

A transaction can now outlive the handle that started it, and a process holding only an id is a real participant rather than a binding.

• Transaction::detach(self) -> String — disarms Drop, stops the keep-alive and waits for it, returns the id. Nothing is sent to the cluster.
• Client::attach_transaction(id) — a real Transaction (bound client, keep-alive, working commit/abort/ping) with Origin::Attached. It reads #<id>/@timeout for the ping interval, and that round trip doubles as existence validation.
• Ping / commit / abort by bare id on Client, so a process that has only the id string can finish someone else's transaction. commit carries a mutation id (it is not idempotent); ping and abort carry none (abort is forgiving on the cluster's own account).
• Drop for an attached handle detaches, copying the C++ destructor: an attacher's ? must not destroy work the owner still holds a handle to. Drop for a started handle still aborts, unchanged — that is what makes ? safe inside a transaction, and the existing tests still prove it.
• Transaction::is_lost() — the keep-alive raises a flag before giving up, so a handle that has stopped pinging can be seen to have stopped rather than discovered later on an unrelated command.

The bug found while building it

attach used to read @timeout and then wait a full ping interval before its first ping. @timeout is the configured timeout and says nothing about remaining life, so any handoff taking longer than timeout × 2/3 lost the transaction — silently, because the keep-alive's exit was quiet. Demonstrated live, both ways, on a 9 s transaction handed over after 7 s:

with the fix     attached at t+5s; is_lost=false at t+20s; COMMIT OK; the node is visible outside
without it       attach reports success; is_lost=true at t+20s;
                 COMMIT FAILED: No such transaction 1-5ee45-10001-d148

attach now pings before it returns, so the clock restarts at the attach and a transaction that died during the handoff becomes this call's error.

Where the promise stops, stated rather than hidden

detach waits for the keep-alive through an mpsc::recv_timeout handshake — the timed join std lacks — bounded at five seconds. That bound is reachable, and the docs now say so instead of promising more than it delivers:

• the ping budget is min(interval/2, 120 s) and the interval is timeout/3, so five seconds covers the whole budget only while the timeout is at or under the 30 s default;
• above the default, detach returns with a stalled ping still in flight; that ping can reach the master afterwards and restart the expiry clock, so the transaction lives a full timeout from wherever it landed;
• at most one ping is outstanding and its thread exits inside its own budget, so nothing leaks.

Bounding the join by the ping budget instead was considered and rejected in the commit message: it would make detach block up to two minutes on exactly the hour-long launcher transaction this module is written around. ureq offers no way to cancel another thread's in-flight request, so there is no third option — the honest sentence is the deliverable.

Acceptance criteria → tests

• Started drop still aborts; attached drop does not — a_started_handles_drop_still_aborts and only_a_started_handles_drop_reaches_for_the_cluster, the latter contrast-based on a connection-counting socket.
• Detach sends nothing and stops the pings — a_detached_transaction_is_neither_aborted_nor_pinged_again (1.6 s of silence against a 1 s interval).
• The join is real — detach_with_a_ping_in_flight_waits_for_it asserts wall clock ≥ 250 ms against a stub answering 500 ms late. Under the non-waiting mutation detach returns in 8 µs and the test fails. The earlier version of this test passed either way, because the stub recorded requests on arrival and both assertions only asked whether a new request had started.
• The bound is real — stop_and_join_gives_up_on_a_ping_that_outlasts_the_bound, against a proxy that accepts and never answers with a 30 s request budget. Degrading the bounded join back to an unbounded one gives 30.0006 s and fails; it is the only test in the workspace that catches that.
• Attach — reads the timeout, pings before returning, its drop does not abort, a refused ping fails the attach and leaves no thread, and a nonexistent id names itself in the error.
• By-id triple — verb, path and id for all three; mutation_id asserted absent on ping and abort, so demoting abort's retry class fails.

Validation

Four independent passes — a critic, a test validator, and two verification rounds. The verifier measured rather than reasoned: the panic path (recv_timeout disconnects in 2.5 µs, join returns Err in 18.5 µs, discarded), the post-disconnect join window (worst of 200 idle runs 384 µs; worst of 50 after a real ping 2.2 ms), and the timing tests' safety — they assert lower bounds on a stub-controlled delay, so CPU load pushes the measurement away from the threshold, structurally the opposite of the fix/test-port-race scar. The one upper-bound test overshoots its 5 s bound by 0.3–6.0 ms at load average 71, against 2 s of headroom.

Flakiness: 12/12 clean, six of them at load average 91 on ten cores. Gates: cargo fmt --check, cargo clippy --workspace --all-targets -- -D warnings, cargo test --workspace (652 passed), cargo test --workspace --doc (64 passed). New examples/detach.rs runs green end to end.

Follow-up candidates (out of scope)

• Above a 30 s timeout detach remains best-effort about the in-flight ping. Now stated, not fixed; the rejected alternative is written down should anyone revisit it.
• is_lost has two false negatives — a panicked keep-alive thread and a failed spawn. Nothing on the ping path panics today; both are documented, and a tri-state was rejected because the remedy for either is the same (ping, or attach afresh).
• start_transaction under retry has the same stale-clock exposure attach now closes, but needs a lost answer and retries slower than the timeout.
• Prerequisite transaction ids and a pushed Tx.Finished()-style watcher remain unbuilt; is_lost is polled.