Release v0.14.0 - #367
Merged
Merged
Conversation
Add an idle unary RPC returning a new IdleTime message (a double seconds field) to the Worker gRPC service, and re-export IdleTime from wool.protocol alongside the other wire messages.
WorkerService records a monotonic timestamp of when its in-flight task set last became empty, with worker startup counting as the initial empty state, and answers the idle RPC with the seconds elapsed since, or zero while any task is in flight. The timestamp flips on the docket's empty and non-empty edges, so polling never enters the docket and cannot disturb the measurement it reads.
Give the direct single-worker connection an idle_time poll that returns the worker's continuous idle seconds (validating a positive deadline) and a stop control that sends the stop RPC with a shutdown grace period. A worker predating the idle RPC answers UNIMPLEMENTED, which surfaces as the new IdleUnavailable; it descends from WoolError rather than RpcError so an absent capability is not mistaken for an RPC-health fault and does not evict a healthy worker. Export IdleUnavailable from the wool package.
Rename the stop() shutdown grace period from timeout to grace on Worker and WorkerLike so it no longer reads as a client-side deadline and no longer collides with the dispatch and idle timeout on the same surface. The old timeout keyword is kept as a deprecated alias — passing it still works and emits a DeprecationWarning — so existing callers are not broken. The wire field StopRequest.timeout and the startup deadline _start keep the name timeout.
LocalWorker._stop now issues the stop RPC through a WorkerConnection, reusing its credential handling, secure-channel construction, and channel pooling instead of building a one-off stub, and releases the pooled channel afterward.
Add unit and property-based coverage for the IdleTime wire message, WorkerService idle tracking across concurrent drains and pre-tracking rejections, WorkerConnection.idle_time and stop (status-code mapping, timeout validation, and value fidelity), IdleUnavailable's WoolError lineage and public export, and the LocalWorker stop routing. Track the grace rename across the worker suite and cover the deprecated timeout alias on Worker.stop.
Exercise idle accrual from startup, zero-while-busy, reset-on-drain, IdleUnavailable against a servicer without the RPC, and the poll-then-retire and LocalWorker.stop flows against real subprocess workers across the insecure, mTLS, and one-way-TLS transports.
The surface spelled one concept three ways: the wire RPC and the service handler said idle, the caller-facing method said idle_time, and the message said IdleTime. WorkerConnection.idle now mirrors the RPC it wraps, and the unit stays explicit where it matters: the message's seconds field and the method docstring. The RPC name itself is untouched, so the gRPC method path and the seconds field tag are identical and the change is wire-compatible with v0.14.0-rc0 workers. The surface has only shipped in that pre-release, so renaming the Python API before v0.14.0 final avoids a deprecation cycle. IdleUnavailable keeps its name.
The idle surface shipped without documentation in either README, and the top-level README additionally described the worker as hosting two RPCs, which has contradicted wire.proto since idle landed. The worker package README owns the contract: what the poll returns and what its timeout means, how idle is measured, why polling cannot perturb the measurement, how worker idleness differs from the channel idleness discussed alongside it, and why IdleUnavailable descends from WoolError rather than RpcError. The top-level README carries the narrative and links there, matching how it already defers to the worker package on discovery-plane trust and credential rotation.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Auto-generated by the cut release workflow.