Skip to content

Implement wire protocol version compatibility semantics #102

@conradbzura

Description

@conradbzura

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:

  1. 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.

  2. Version handshake in the dispatch RPC — add wool's package version to the Ack response for observability. As a best-effort fallback, workers Nack tasks 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 the Nack path.

  3. README for wool/src/wool/runtime/protobuf/ — document the dispatch wire protocol (TaskAckResult/Exception sequence), 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 handling
  • wool/protobuf/worker.proto — add version field to Ack
  • wool/src/wool/runtime/worker/service.py — populate version in ack responses, best-effort Nack on major mismatch
  • wool/src/wool/runtime/worker/connection.py — check version in ack handling
  • wool/src/wool/runtime/protobuf/README.md (new) — subpackage documentation

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationIndicates that a PR includes changes to documentationfeatureNew feature or capability

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions