Serializer

serializer

Payload serialization for the Durable Workflow worker protocol.

Every payload on the wire carries a payload_codec tag alongside its opaque blob.

Supported codec:

• "avro" — the blob is standard Avro single-object encoding for the fixed recursive durable_workflow.protocol.Value schema (see durable_workflow._avro). It is the default for new v2 workflows and preserves distinct null, boolean, signed integer, finite double, bytes, text, list, and string-keyed map branches. 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 supported branch before encode; IntEnum and StrEnum round-trip as their scalar value, 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 fixed Avro Value kinds.

This helper is the explicit boundary for class-carrying values: callers opt in before encode and the returned canonical value becomes part of durable history.

to_avro_payload_values

to_avro_payload_values(values)

Convert several values with 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 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. Untagged raw durable payload blobs are rejected. 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 AvroNotInstalledError when the Avro runtime dependency is missing from a broken or partial installation.