Skip to content

Replay, recovery, and application services

Duron recovers a workflow by replaying recorded operations and continuing where it left off. Workflow control flow must stay deterministic, and recorded effect outcomes must be reused. The sections below explain how to write workflows and configure their services for recovery.

Use durable time and randomness

Inside workflows, use await ctx.now() for deterministic UTC time and ctx.random() for a replay-stable random generator. Calculate elapsed seconds with ((await ctx.now()) - started_at).total_seconds(), where started_at is an earlier await ctx.now() value. Use await ctx.sleep(seconds) for a durable deadline. A restart waits only for the remainder of that deadline. Durations must be finite nonnegative numbers; booleans, negatives, NaN, and infinities raise ValueError.

Inside effects and host tasks, use ordinary clocks, random generators, and asyncio.sleep.

Handle interrupted effects

When replay finds an effect call without a final outcome, Duron reports the interrupted effect and does not invoke it again. A scheduled run becomes BLOCKED; start a new run with a new ID after resolving any external work. Completed effects replay their recorded outcomes. Success, failure, and cancellation are each final.

Result validation or encoding failures that raise TypeError or ValueError are recorded as application failures. Duron does not retry the effect.

For external mutations, pass stable application operation IDs as effect arguments so the external service can identify work whose outcome was lost.

Scheduler failures and cancellation

Transient storage failures, including during replay or cancellation, use the scheduler's bounded infrastructure retry policy. These retries do not make an effect with a missing outcome safe to invoke again.

If cancellation encounters incompatible or corrupt history, the scheduler records a failure for that run without rewriting its history. Other runs continue. Use run.status() for scheduling diagnostics and run.result() to observe the error. See runtime failures.

Supply typed application services

An effect can close over an application service. Construct the definition with the service it will use:

from typing import Protocol

import duron
import duron.execution


class OrderClient(Protocol):
    async def fetch(self, key: str) -> str: ...


def make_fetch(
    client: OrderClient, executor: duron.execution.Executor | None = None
) -> duron.Effect[[str], str]:
    @duron.effect(name="orders.fetch", executor=executor)
    async def fetch(_ctx: duron.EffectContext, key: str) -> str:
        return await client.fetch(key)

    return fetch

The application that constructs the effect also manages the client's lifetime. Omit executor to run the effect locally. Pass a custom executor to make_fetch(client, executor) to choose a different execution adapter for this effect. Each effect definition selects its own executor. Register the workflow that calls it with SQLiteScheduler(path, workflows=[...]).

AsyncExecutor runs the registered Python function by default. A remote executor uses invocation.arguments, metadata, and port(...), then returns its result or raises ApplicationFailure(error). See the execution reference.

Use a custom codec

Implement duron.codec.Codec.encode_json(value, annotated_type) and decode_json(encoded, expected_type). Encoded values must be finite JSON values. Select your codec instance with @duron.workflow(codec=application_codec).

The workflow codec handles application values throughout the run, including workflow and effect arguments and results and port payloads. Effects use the calling workflow's codec.

The default codec accepts only finite JSON values: None, booleans, numbers, strings, lists, and dictionaries with string keys. It does not reconstruct dataclasses, tuples, dates, or other Python objects from annotations. See the codec reference for a complete custom codec example.

Change definitions and codecs

Names identify workflow and effect definitions; Duron does not fingerprint their code. Keep changes compatible with existing runs, or choose a new name and run ID for incompatible workflows. Keep old definitions and codecs available to finish existing runs. Evolve decode_json to accept previously persisted values, using in-band version tags when needed.