Description
A Wool worker should report how long it has been continuously idle, so that the process which spawned it can poll that value and decide when to shut it down. Idle is measured as the number of seconds since the worker's in-flight task set last became empty, with worker startup counting as the initial empty state. While any task is in flight the reported idle time is zero, and the count resets whenever work resumes. The measurement uses a monotonic clock so that a wall-clock adjustment cannot distort it.
The idle reading is reached through a new method on the Worker service and surfaced on the public WorkerConnection — Wool's direct, single-worker client — as a plain Python call returning a floating-point number of seconds. A caller connects to a specific worker by address and polls it; the worker never polls itself. The same direct client also surfaces the existing ability to stop a worker, so the poll-then-retire flow lives on one stable surface. The build-generated protobuf stub stays an internal implementation detail rather than the surface callers depend on, so users inherit WorkerConnection's credential and secure-channel handling and channel pooling rather than reconstructing them by hand.
Motivation
A worker that sits idle still holds the resources it was given — a container, a process, a reserved slot — and Wool offers no way today to notice that a worker has gone quiet. A worker exposes no idle signal, and the only direct single-worker client, WorkerConnection, can dispatch tasks but cannot ask a worker how long it has been inactive or stop it. Operators who want elastic, scale-to-zero-style fleets — spin a worker up for a burst of work, retire it once the work drains — must track activity out of band or terminate workers blindly.
Exposing idle as an observable signal, while leaving the polling cadence and the shutdown decision to the caller, keeps the worker a simple primitive and lets each deployment encode its own retirement policy. This mirrors how elastic compute systems generally separate the reporting of inactivity from the decision to reclaim capacity.
Expected outcome
- A worker reports its continuous idle duration in seconds: the time since its in-flight task set last emptied, with startup counting as empty, zero while any task is in flight, reset whenever activity resumes, and measured against a monotonic clock.
- The idle reading is reachable as a method on the Worker service, callable against a single worker by address.
WorkerConnection exposes idle as a plain Python method returning seconds, and exposes stopping a worker, so the direct single-worker control surface is complete without dropping to the generated stub.- The generated protobuf stub and gRPC channel construction remain internal; callers reach idle and stop through
WorkerConnection, which continues to encapsulate the credential and secure-channel partition and channel pooling.
- The capability is additive: existing deployments behave unchanged, and a worker that predates the idle method answers in a way a polling client can detect and treat as idle reporting being unavailable.
- Routine execution is unaffected. Idle is a fleet-management concern that never enters the routine path, so code run locally without a worker pool behaves exactly as before — there is no worker to poll.
- Wool ships no built-in idle-timeout or auto-shutdown policy on the worker; the polling cadence and the decision to retire a worker belong to the caller, or to an optional, thin pool-side helper.
Description
A Wool worker should report how long it has been continuously idle, so that the process which spawned it can poll that value and decide when to shut it down. Idle is measured as the number of seconds since the worker's in-flight task set last became empty, with worker startup counting as the initial empty state. While any task is in flight the reported idle time is zero, and the count resets whenever work resumes. The measurement uses a monotonic clock so that a wall-clock adjustment cannot distort it.
The idle reading is reached through a new method on the Worker service and surfaced on the public
WorkerConnection— Wool's direct, single-worker client — as a plain Python call returning a floating-point number of seconds. A caller connects to a specific worker by address and polls it; the worker never polls itself. The same direct client also surfaces the existing ability to stop a worker, so the poll-then-retire flow lives on one stable surface. The build-generated protobuf stub stays an internal implementation detail rather than the surface callers depend on, so users inheritWorkerConnection's credential and secure-channel handling and channel pooling rather than reconstructing them by hand.Motivation
A worker that sits idle still holds the resources it was given — a container, a process, a reserved slot — and Wool offers no way today to notice that a worker has gone quiet. A worker exposes no idle signal, and the only direct single-worker client,
WorkerConnection, can dispatch tasks but cannot ask a worker how long it has been inactive or stop it. Operators who want elastic, scale-to-zero-style fleets — spin a worker up for a burst of work, retire it once the work drains — must track activity out of band or terminate workers blindly.Exposing idle as an observable signal, while leaving the polling cadence and the shutdown decision to the caller, keeps the worker a simple primitive and lets each deployment encode its own retirement policy. This mirrors how elastic compute systems generally separate the reporting of inactivity from the decision to reclaim capacity.
Expected outcome
WorkerConnectionexposes idle as a plain Python method returning seconds, and exposes stopping a worker, so the direct single-worker control surface is complete without dropping to the generated stub.WorkerConnection, which continues to encapsulate the credential and secure-channel partition and channel pooling.