wool-protocol

Wool's wire protocol definitions — protobuf schemas, generated Python bindings, gRPC service wrappers, and the service registry.

Importable as wool.protocol.

Installation

From PyPI

pip install wool-protocol

From source

git clone https://github.com/wool-labs/wool-protocol.git
cd wool-protocol
pip install .

Running tests

git clone https://github.com/wool-labs/wool-protocol.git
cd wool-protocol
pip install '.[dev]'
pytest

Wire protocol

Wool uses a binary wire protocol built on Protocol Buffers and gRPC for all communication between clients and workers.

Dispatch sequence

The Worker.dispatch RPC uses a server-streaming pattern. The client sends a single Task message and receives a stream of Response messages:

sequenceDiagram
    Client->>Worker: Task
    alt accepted
        Worker-->>Client: Response(Ack)
        alt coroutine
            Worker-->>Client: Response(Result)
        else async generator
            loop each iteration
                Worker-->>Client: Response(Result)
            end
        else failure
            Worker-->>Client: Response(Exception)
        end
    else rejected
        Worker-->>Client: Response(Nack)
    end

Task fields

Response types

1. Ack — The worker accepted the task and started processing. Carries the worker's version string for observability.
2. Nack — The worker rejected the task. The reason field describes why (e.g., major version mismatch, unparseable version). No further responses follow a Nack.
3. Result — A cloudpickle-serialized return value. Coroutine tasks yield exactly one result; async generator tasks yield one per iteration.
4. Exception — A cloudpickle-serialized exception from the remote execution. Terminates the stream.

Serialization

Wool uses a hybrid serialization approach:

• Protobuf envelope — Structured metadata fields (id, version, caller, timeout, etc.) are native protobuf fields for efficient parsing and forward compatibility.
• cloudpickle payloads — The callable, args, kwargs, and proxy fields are serialized with cloudpickle and stored as bytes fields. This allows arbitrary Python objects to be transmitted without schema changes.
• Results and exceptions — Result.dump and Exception.dump are cloudpickle-serialized bytes.

Version compatibility

The wire protocol follows PEP 440 versioning. A servicer accepts tasks from any client whose protocol version is less than or equal to its own within the same major version. For example, a servicer running 1.3.0 will accept tasks from a client running 1.0.0, but not from one running 1.4.0. There is no forward compatibility guarantee from client to servicer.

• Minor and patch releases are backwards compatible. New fields may be appended with new field numbers; existing field numbers and types never change within the same major version.
• Major releases may introduce breaking schema changes (field renumbering, type changes, removal). A major version mismatch between client and worker is treated as incompatible.
• Fields 1–4 are the envelope. The Task message reserves fields 1–4 (version, id, caller, tag) for lightweight metadata, enabling pre-deserialization extraction via TaskEnvelope.

Implementations are responsible for enforcing version compatibility.

Release coordination

The wool and wool-protocol packages are developed in parallel but released independently: wool pins a specific wool-protocol version in its pyproject.toml, and wool's CI gates merges on the pinned version being available as a stable PyPI release. A separate non-blocking CI job tests against pre-releases for early signal.

On publish, wool-protocol dispatches a wool-protocol-released event to wool via GitHub's repository_dispatch API, triggering automatic re-runs of failing checks on open PRs that depend on the newly released version.