Serializer

serializer

Payload serialization for the Durable Workflow worker protocol.

The server exposes a language-neutral payload envelope (see issue #164 and docs/configuration/worker-protocol.md in the docs repo). Every payload on the wire carries a payload_codec tag alongside its opaque blob.

Supported codecs:

• "json" — the blob is a UTF-8 JSON document. Supported for decoding existing data only, not used for new workflows.
• "avro" — the blob is a base64-encoded Avro generic-wrapper payload (see :mod:durable_workflow._avro). Default for all new v2 workflows. The wrapper carries JSON-native values only. Class-carrying values such as dataclasses, attrs classes, pydantic models, pendulum values, datetimes, UUIDs, Decimal, and plain Enum values need an explicit adapter to a dictionary or scalar before encode; JSON-subclass values such as IntEnum and StrEnum round-trip as their JSON scalar, not as the original class.

PayloadSizeWarningConfig dataclass

PayloadSizeWarningConfig(limit_bytes=DEFAULT_PAYLOAD_SIZE_BYTES, threshold_percent=DEFAULT_WARNING_THRESHOLD_PERCENT)

Configuration for pre-flight payload-size warnings.

PayloadSizeWarningContext dataclass

PayloadSizeWarningContext(kind, workflow_id=None, workflow_type=None, run_id=None, activity_name=None, signal_name=None, update_name=None, query_name=None, schedule_id=None, task_queue=None, namespace=None)

Structured context attached to payload-size warning logs.

to_avro_payload_value

to_avro_payload_value(value)

Convert common rich Python values to JSON-native Avro wrapper values.

The SDK's default Avro codec is a language-neutral envelope around a JSON document. This helper is the explicit boundary for class-carrying values: callers opt in before encode and the returned value becomes part of durable history.

to_avro_payload_values

to_avro_payload_values(values)

Convert several values with :func:to_avro_payload_value.

encode

encode(value, codec=AVRO_CODEC, *, size_warning=DEFAULT_PAYLOAD_SIZE_WARNING, warning_context=None)

Encode a Python value as a payload blob for codec.

Raises ValueError for unknown codecs and :class:~durable_workflow.errors.AvroNotInstalledError when the Avro runtime dependency is missing from a broken or partial installation.

encode_many

encode_many(values, codec=AVRO_CODEC, *, size_warning=DEFAULT_PAYLOAD_SIZE_WARNING, warning_context=None)

Encode several payload blobs through one codec hook.

The default implementation intentionally preserves the single-value encoder semantics and warning behavior. Codecs that can safely batch or parallelize work can specialize behind this boundary without changing call sites.

envelope

envelope(value, codec=AVRO_CODEC, *, size_warning=DEFAULT_PAYLOAD_SIZE_WARNING, warning_context=None)

Wrap a value in a {codec, blob} payload envelope.

external_storage_envelope

external_storage_envelope(value, *, external_storage, threshold_bytes, codec=AVRO_CODEC, size_warning=DEFAULT_PAYLOAD_SIZE_WARNING, warning_context=None)

Wrap a value in a normal envelope or an external-payload reference.

Payloads whose encoded UTF-8 size is greater than threshold_bytes are stored through external_storage and represented as {codec, external_storage} so workflow history carries a stable reference instead of the large payload bytes.

external_storage_envelope_many

external_storage_envelope_many(values, *, external_storage, threshold_bytes, codec=AVRO_CODEC, size_warning=DEFAULT_PAYLOAD_SIZE_WARNING, warning_context=None)

Wrap several values, offloading payloads above threshold_bytes.

envelope_many

envelope_many(values, codec=AVRO_CODEC, *, size_warning=DEFAULT_PAYLOAD_SIZE_WARNING, warning_context=None)

Wrap several values in {codec, blob} payload envelopes.

warn_if_json_payload_near_limit

warn_if_json_payload_near_limit(value, *, size_warning=DEFAULT_PAYLOAD_SIZE_WARNING, warning_context=None)

Warn when a raw JSON request payload approaches the configured limit.

warn_if_payload_near_limit

warn_if_payload_near_limit(blob, *, codec, size_warning=DEFAULT_PAYLOAD_SIZE_WARNING, warning_context=None)

Emit a structured warning when an encoded payload is close to the server limit.

decode_envelope

decode_envelope(value, codec=None, *, external_storage=None, external_storage_cache=None)

Decode a value that may be a {codec, blob} envelope or a raw blob.

When value is an envelope, its inner codec takes precedence over the codec argument. When value is a raw blob, codec selects the decoder (defaulting to JSON). External payload references require an external_storage driver and verify size/hash before decode.

decode_envelopes

decode_envelopes(values, codec=None, *, external_storage=None, external_storage_cache=None)

Decode several raw blobs or {codec, blob} envelopes in order.

decode_many

decode_many(blobs, codec=None)

Decode several payload blobs with one codec visit when possible.

decode

decode(blob, codec=None)

Decode a payload blob into a Python value.

Raises ValueError for unknown codecs or malformed blobs, and :class:~durable_workflow.errors.AvroNotInstalledError when the Avro runtime dependency is missing from a broken or partial installation.