Rename the worker idle_time surface to idle — Closes #368

[conradbzura]

Summary

Unify the worker idle-reporting surface introduced by #253 on the single name idle. 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. IdleUnavailable keeps its name.

The RPC name itself is untouched, so the gRPC method path is identical and seconds keeps tag 1. The surface has only shipped in v0.14.0-rc0, so renaming the Python API before v0.14.0 avoids a deprecation cycle.

Behavior is unchanged — this is a pure rename, so it adds no tests. The 17 existing tests that exercise the idle surface all still apply and none became stale; twelve were renamed to track the method name, and the five in test_service.py needed no edit at all because they drive the handler through stub.idle(protocol.Void()) and never name the renamed message.

Closes #368

Proposed changes

Rename the wire message

Rename message IdleTime to message Idle in wool/proto/wire.proto, so the service reads rpc idle (Void) returns (Idle). The seconds field, its tag, and its comment are unchanged — the message name carries the concept and the field carries the unit. Generated stubs are gitignored and rebuilt by the hatch-protobuf build hook, so no generated artifact is committed.

Rename the protocol re-export

Re-export the message as wool.protocol.Idle from _wire.py and protocol/__init__.py, in both the import block and each __all__. Both keep their alphabetical slot, so the diff is one line per list.

Rename the connection method

Rename WorkerConnection.idle_time to WorkerConnection.idle. The body is untouched: the timeout validation, the channel acquisition, and the mapping of UNIMPLEMENTED to IdleUnavailable and of transient codes to TransientRpcError all behave exactly as before. Update the docstring references in the IdleUnavailable and WorkerConnection class docstrings, and reflow the two paragraphs the shorter name left ragged.

Update the service handler

Point WorkerService.idle at the renamed message — the return annotation, the constructed response, and the :returns: docstring line. The handler name, its idle accounting, and its monotonic-clock measurement are unchanged.

Track the rename through the tests

Update the three test files that named the old symbols: the export list and two message tests in test_wire.py, six method tests in test_connection.py, and the call sites and names in the integration suite. Test names follow the method's __name__, so test_idle_time_should_* becomes test_idle_should_*.

Test cases

#	Test Suite	Given	When	Then	Coverage Target
1	TestExports	The expected message export list naming Idle	Each name is looked up on wool.protocol	The attribute should resolve and appear in __all__	Renamed export surface
2	TestMessageConstruction	A seconds value, and the default construction	An Idle message is constructed with and without a value	The seconds field should hold the value and default to 0.0	Renamed message fields
3	TestMessageConstruction	Any finite double for the idle duration	An Idle message is serialized and re-parsed	The seconds field should equal the original exactly	Wire-format round-trip
4	TestWorkerConnection	A connection whose worker answers the idle RPC with an Idle	idle is awaited	It should return the reported seconds as a float	Renamed method, happy path
5	TestWorkerConnection	A worker answering the idle RPC with gRPC UNIMPLEMENTED	idle is awaited	It should raise IdleUnavailable	Absent-capability signal
6	TestWorkerConnection	Any gRPC error status code and any details	idle is awaited	It should raise IdleUnavailable, TransientRpcError, or RpcError per the code, carrying details	Status-code mapping
7	TestWorkerConnection	Any non-positive timeout	idle is awaited with that timeout	It should raise ValueError without calling the stub	Timeout validation
8	TestWorkerConnection	None or any positive timeout	idle is awaited with that timeout	It should call the stub with a Void request and that deadline	Timeout forwarding
9	TestWorkerConnection	A worker answering with any double value	idle is awaited	It should return exactly that value	Lossless seconds
10	TestWorkerIdleReporting	A real worker over each transport, freshly started	idle is polled twice with a wait between	It should report a positive, non-decreasing duration	Renamed method over the real wire
11	TestWorkerIdleReporting	A real worker executing a dispatched routine	idle is polled	It should report zero while the task is in flight	In-flight reporting
12	TestWorkerIdleReporting	A real worker whose in-flight set drains	idle is polled before and after the drain	It should count from the drain, not from startup	Drain reset
13	TestWorkerIdleReporting	A real server whose servicer does not implement idle	idle is polled against it	It should raise IdleUnavailable and not an RpcError	Legacy-worker path
14	TestWorkerControlSurface	A real worker polled for idle then stopped	idle is polled again after the stop	It should become unreachable with a TransientRpcError	Poll-then-retire flow