-
Notifications
You must be signed in to change notification settings - Fork 2
Description
Summary
Wool has no runtime protocol version negotiation — WorkerMetadata.version is informational only. Additionally, the protobuf subpackage lacks a README documenting the dispatch wire protocol, schema layout, and version compatibility semantics.
This issue covers three related pieces of work:
-
Discovery-time version filtering — filter out workers with incompatible major versions during discovery by default, similar to the existing security compatibility filter. This is the primary defense against version mismatches — incompatible workers never enter the load balancer context.
-
Version handshake in the dispatch RPC — add wool's package version to the
Ackresponse for observability. As a best-effort fallback, workersNacktasks from clients with an incompatible major version. This only helps when the protobuf envelope is still parseable despite a major version bump (e.g., semantic breaks without wire format changes); truly incompatible wire formats will fail before reaching theNackpath. -
README for
wool/src/wool/runtime/protobuf/— document the dispatch wire protocol (Task→Ack→Result/Exceptionsequence), serialization strategy (protobuf envelope + cloudpickle payloads), Python binding layout, schema evolution rules, and version compatibility semantics.
Motivation
As the wire protocol evolves, mismatched client and worker versions will produce silent corruption or confusing errors rather than a clear incompatibility message. Documenting the protocol and formalizing compatibility rules now — while still in greenfield — establishes the discipline before it becomes a breaking concern.
The versioning policy: within a major version, all wire protocol changes must be additive only (new optional fields, new oneof variants, new RPC methods). A major version bump signals an intentionally incompatible wire format. Workers accept dispatches from any client within the same major version — older, equal, or newer.
Affected code
wool/src/wool/runtime/worker/proxy.py— add major-version filter to discovery event handlingwool/protobuf/worker.proto— addversionfield toAckwool/src/wool/runtime/worker/service.py— populate version in ack responses, best-effortNackon major mismatchwool/src/wool/runtime/worker/connection.py— check version in ack handlingwool/src/wool/runtime/protobuf/README.md(new) — subpackage documentation