Skip to content

duron.codec module

A codec converts application values to JSON for persistence and reconstructs them when read. Select a codec on the workflow; its effects and ports use the same codec.

Default codec

DefaultCodec encodes finite JSON values and returns decoded JSON unchanged. It accepts None, bool, int, finite float, str, lists of JSON values, and dictionaries with string keys. Tuples, bytes, dates, dataclasses, and model objects require a custom codec. NaN and infinities are rejected, including inside containers. Only exact built-in JSON types are accepted; subclasses such as enums need a custom codec. Strings must be valid UTF-8. Cyclic containers, nesting beyond 64 container levels, and integers exceeding 4096 bits are rejected.

Type validation

The default codec itself does not validate annotations or reconstruct Python types. The runtime wraps the selected codec with checks at workflow, effect, and port boundaries. Values must match their declared types. Missing annotations and Any allow arbitrary values supported by the codec.

Codec.decode_json is generic: given TypeHint[T], it must return T or raise if it cannot decode the value. Duron validates decoded values and checks that encoded values can be decoded to the declared type before committing them. A custom codec must reconstruct external data as needed; its decoder can run during encoding and must be free of external side effects. Validation checks type conformance, not equality of the original and reconstructed objects.

Implement a custom codec

A codec must encode every value it handles as finite JSON and reconstruct values according to the supplied type hint. Select one codec on the workflow; it handles workflow and effect arguments and results and port payloads. Duron handles its own runtime metadata separately.

from dataclasses import dataclass
from typing import TypeVar, cast

import duron
from duron.codec import DefaultCodec, JSONValue, TypeHint

T = TypeVar("T")


@dataclass(frozen=True)
class Order:
    number: str


class OrderCodec:
    def encode_json(
        self, value: object, annotated_type: TypeHint[object], /
    ) -> JSONValue:
        if isinstance(value, Order):
            return {"number": value.number}
        return DefaultCodec.encode_json(value, annotated_type)

    def decode_json(self, encoded: JSONValue, expected_type: TypeHint[T], /) -> T:
        if expected_type is Order:
            if not isinstance(encoded, dict) or not isinstance(
                encoded.get("number"), str
            ):
                raise TypeError("invalid encoded order")
            return cast(T, Order(encoded["number"]))
        return DefaultCodec.decode_json(encoded, expected_type)


@duron.workflow(codec=OrderCodec())
async def echo(ctx: duron.WorkflowContext, order: Order) -> Order:
    return order


async def example() -> None:
    async with duron.SQLiteScheduler(":memory:", workflows=[echo]) as scheduler:
        for _ in range(2):
            run = await scheduler.submit(echo, "order", Order("A-1"))
            assert await run.result() == Order("A-1")

This codec handles an Order as a directly annotated value. Supporting list[Order], unions, or nested models requires recursive handling of those type hints; the fallback to DefaultCodec does not add it.

Evolve a codec

Effects can be reused by workflows with different codecs. Make decode_json accept previously persisted wire values as the format evolves, using in-band version tags when needed. Duron does not fingerprint codec implementations. Choose a new workflow name and run ID for incompatible changes. Remote adapters must preserve the active workflow's serialization contract.

Encode failure details

For structured failure details, explicitly encode a value with the codec and pass the JSON to ApplicationError(..., details=...). When catching the error, decode error.details with the application schema. Exception objects are never passed to the workflow codec.

Serialization contracts: the Codec protocol and the default JSON codec.

JSONValue module-attribute

JSONValue: TypeAlias

Recursive type representing any valid JSON value.

TypeHint module-attribute

TypeHint

A type expression or the internal unspecified-type sentinel.

_MAX_DEPTH module-attribute

_MAX_DEPTH

_MAX_INT_BITS module-attribute

_MAX_INT_BITS

_T module-attribute

_T

__all__ module-attribute

__all__

Codec

Protocol for encoding/decoding Python objects to/from JSON-serializable values.

Implement this protocol to provide custom serialization for types not supported by the default codec (e.g., dataclasses, Pydantic models, custom objects). Select it on the workflow to encode application values throughout that run. Runtime framing uses fixed JSON. Incompatible encoding changes require a new workflow name. Decoding must return the type described by the supplied hint or raise; workflow code trusts this generic contract. The codec can be used explicitly for structured ApplicationError.details. Runtime error metadata uses fixed JSON; exception objects are never passed to the codec.

decode_json

decode_json(
    encoded: JSONValue, expected_type: TypeHint[_T]
) -> _T

Reconstruct a Python object from a JSON value during log replay.

Parameters:

  • encoded (JSONValue) –

    The JSON value to decode

  • expected_type (TypeHint[_T]) –

    Type hint for the expected return type

Returns:

  • _T –

    The reconstructed Python object

encode_json

encode_json(
    result: object, annotated_type: TypeHint[object]
) -> JSONValue

Convert a Python object to a JSON-serializable value for persistence.

Parameters:

  • result (object) –

    The object to encode (e.g., operation result or argument)

  • annotated_type (TypeHint[object]) –

    Type hint for the object's type

Returns:

  • JSONValue –

    A JSON-serializable value (None, bool, int, float, str, list, or dict)

Raises:

  • TypeError –

    If the object cannot be serialized

DefaultCodec

Encode finite JSON values and return decoded values unchanged.

Supports None, booleans, numbers, strings, lists, and dictionaries with string keys. Annotations do not trigger type validation or reconstruction. Use a custom Codec for other Python types.

decode_json staticmethod

decode_json(
    encoded: JSONValue, _expected_type: TypeHint[_T]
) -> _T

encode_json staticmethod

encode_json(
    result: object, _annotated_type: TypeHint[object]
) -> JSONValue

_check_json

_check_json(
    x: object, depth: int, active: set[int]
) -> bool

_is_json_value

_is_json_value(x: object) -> TypeGuard[JSONValue]

Return whether x is a finite, canonical JSON-serializable value.

Only exact builtin types qualify, so enum and other subclasses are rejected rather than silently decoded as their base type. Strings must be valid UTF-8 (no lone surrogates), integers are bounded, nesting is limited to a fixed depth, and cyclic containers are rejected.

Returns:

  • TypeGuard[JSONValue] –

    True if x contains only canonical JSON values and finite floats.

_is_utf8

_is_utf8(value: str) -> bool