Skip to content

Workflow and host ports

Ports let an application exchange messages with a running workflow. Declare inputs and outputs in a PortSet. Inside the workflow, receive inputs and emit outputs through ctx.port(...). In the application, use run.port(...) to send inputs and read outputs.

import asyncio

import duron


class Ports(duron.PortSet):
    names = duron.Input[str]()
    events = duron.Output[str]()


@duron.workflow(ports=Ports)
async def greet(ctx: duron.WorkflowContext) -> str:
    name = await ctx.port(Ports.names).receive()
    message = f"Hello, {name}!"
    await ctx.port(Ports.events).emit(message)
    return message


async def main() -> None:
    async with duron.SQLiteScheduler(":memory:", workflows=[greet]) as scheduler:
        run = await scheduler.submit(greet, "greeting")
        await run.port(Ports.names).send("Alice", idempotency_key="name")
        await run.port(Ports.names).close()
        async for message in run.port(Ports.events):
            print(message)
        assert await run.result() == "Hello, Alice!"


asyncio.run(main())

Send and close inputs

Input send() and close() return after durable enqueueing; they do not wait for the workflow to accept the message. The active owner processes messages in insertion order. Messages for closed inputs or terminal runs are discarded. Processing rejections are logged rather than returned to the sender. Local encoding and contract validation still raise immediately.

Reusing an idempotency_key with the same encoded value deduplicates delivery; conflicting reuse raises PostConflictError. Omit the key to send a new message each time.

Closing an input preserves queued values. Receiving after it drains raises PortClosedError. Use receive_many(max_items=..., wait=...) for batches.

Read and resume outputs

Each call to run.port(Ports.events).reader(after=cursor, prefetch=64) creates an independent reader. Direct iteration creates a fresh reader. Persist reader.cursor alongside the consumer's committed work, then pass it as after on reconnection. prefetch bounds reader buffering; it does not apply producer backpressure.

Readers drain committed output before ending. A blocked run can still provide committed output, but its reader may then wait indefinitely. Await run.result() to observe the result or failure.

Disconnecting a reader does not close workflow ports. To reconnect, reopen the run and create a reader with the saved cursor. An unfinished effect blocks the run, but committed output remains readable.

Select inputs and operations

Use ctx.select to wait for a named input or operation, optionally with a timeout. Inside the workflow above, you could replace the input receive with:

choice = await ctx.select(name=ctx.port(Ports.names), timeout=60)
if choice.name == "timeout":
    return "No name received"
return f"Hello, {choice.value}!"

The returned Selection has name and value. A timeout has name="timeout" and value=None. Pass input endpoints directly to consume only the selected message. Losing inputs remain available. Awaitable losers are cancelled and drained before return. A winning failure is raised after cleanup. A closed, drained input is ready and raises PortClosedError if selected.

Selection journals its decision. Replay observes the same choice, and a suspended timeout retains its original absolute deadline. Branch declaration order resolves simultaneous observed readiness. This is observation order, not a global ordering of storage commits. Inputs are exclusively claimed during selection; overlapping receive or interruption consumers are rejected.

Interrupt a block with input

For a block that should be interrupted by one input, use async with ctx.port(Ports.names).interruptible():. A queued or future value is consumed and raised as duron.errors.Interrupted, with its value payload. The input remains exclusively claimed until the scope exits.