Client¶
Async client for the Durable Workflow server's control and worker planes.
The :class:Client wraps the server's HTTP/JSON protocol. Control-plane
methods (start_workflow, signal_workflow, describe_workflow,
schedule management, …) are what callers use to drive workflows from outside.
Worker-plane methods (register_worker, poll_workflow_task,
poll_query_task, complete_activity_task, …) are what the
:class:~durable_workflow.Worker
uses to run tasks; they are public so advanced users can build custom
workers, but most applications should not call them directly.
The module also defines the returned-value dataclasses (WorkflowExecution,
WorkflowList, ScheduleSpec, ScheduleDescription, …) and the
ergonomic handle classes (:class:WorkflowHandle, :class:ScheduleHandle)
that bind a workflow or schedule id to a :class:Client so you can call
methods without repeating the id on every call.
dataclass
¶
WorkflowExecution(workflow_id, run_id, workflow_type, status=None, namespace=None, task_queue=None, input=None, output=None, payload_codec=None)
Current server view of one workflow execution.
dataclass
¶
One page of workflow visibility results.
dataclass
¶
NamespaceDescription(name, description=None, retention_days=None, status=None, created_at=None, updated_at=None, deleted=None, external_payload_storage=None)
Server configuration for one workflow namespace.
dataclass
¶
Namespaces visible to the current control-plane identity.
dataclass
¶
Result for one payload size exercised by the server storage probe.
dataclass
¶
StorageTestResult(status, namespace=None, driver=None, small_payload=None, large_payload=None, raw=None)
Server response for an external payload storage probe.
dataclass
¶
WorkflowRun(workflow_id, run_id, workflow_type, status=None, namespace=None, task_queue=None, run_number=None, run_count=None, is_current_run=None, status_bucket=None, business_key=None, compatibility=None, payload_codec=None, input=None, output=None, memo=None, search_attributes=None, actions=None, started_at=None, closed_at=None, last_progress_at=None, closed_reason=None, wait_kind=None, wait_reason=None, execution_timeout_seconds=None, run_timeout_seconds=None, execution_deadline_at=None, run_deadline_at=None)
Current server view of one durable run in a workflow execution chain.
dataclass
¶
Machine-readable outcome returned by workflow control commands.
dataclass
¶
All known durable runs for one workflow execution, oldest first.
dataclass
¶
StandaloneActivityExecution(activity_id, workflow_run_id, activity_execution_id, workflow_type, activity_type, activity_class, task_queue, namespace, status, activity_status, closed_reason, business_key, payload_codec, started_at, closed_at, last_progress_at, last_heartbeat_at, schedule_to_start_deadline_at, schedule_to_close_deadline_at, attempt_count, result=None)
Server view of one standalone activity execution.
Standalone activities run as top-level durable jobs anchored by a server-managed host run; this dataclass collapses the host-run state and the underlying activity execution state into one description so callers do not need to navigate between two surfaces to inspect a single job.
dataclass
¶
One page of standalone activity executions returned by the server.
dataclass
¶
Search attribute definitions available in the current namespace.
dataclass
¶
TaskQueueTaskAdmission(status=None, budget_source=None, server_budget_source=None, active_worker_count=None, configured_slot_count=None, leased_count=None, ready_count=None, available_slot_count=None, server_max_active_leases_per_queue=None, server_active_lease_count=None, server_remaining_active_lease_capacity=None, server_max_active_leases_per_namespace=None, server_namespace_active_lease_count=None, server_remaining_namespace_active_lease_capacity=None, server_max_dispatches_per_minute=None, server_dispatch_count_this_minute=None, server_remaining_dispatch_capacity=None, server_max_dispatches_per_minute_per_namespace=None, server_namespace_dispatch_count_this_minute=None, server_remaining_namespace_dispatch_capacity=None, server_dispatch_budget_group=None, server_max_dispatches_per_minute_per_budget_group=None, server_budget_group_dispatch_count_this_minute=None, server_remaining_budget_group_dispatch_capacity=None, server_lock_required=None, server_lock_supported=None)
Workflow/activity admission state for one task queue.
dataclass
¶
TaskQueueQueryAdmission(status=None, budget_source=None, max_pending_per_queue=None, approximate_pending_count=None, remaining_pending_capacity=None, lock_required=None, lock_supported=None)
Worker-routed query-task admission state for one task queue.
dataclass
¶
Server-side admission budgets for workflow, activity, and query tasks.
dataclass
¶
TaskQueueDescription(name, namespace=None, stats=None, admission=None, pollers=None, current_leases=None, raw=None)
Current server visibility and admission state for one task queue.
dataclass
¶
One task-queue visibility page returned by the server.
dataclass
¶
TaskQueueBuildIdCohort(build_id, rollout_status, active_worker_count, draining_worker_count, stale_worker_count, total_worker_count, runtimes, sdk_versions, last_heartbeat_at=None, first_seen_at=None, drain_intent=None, drained_at=None, promoted_at=None, rolled_back_at=None, new_start_selected=False, workflow_definition_fingerprint_count=0, workflow_definition_fingerprint_conflicts=None, raw=None)
Per-build-id rollout state for one task queue.
build_id is None for the cohort of workers that registered
without a build identifier (the legacy unversioned default).
dataclass
¶
Build-id rollout snapshot returned by the server for one task queue.
dataclass
¶
TaskQueueBuildIdRolloutState(namespace, task_queue, build_id, drain_intent, drained_at, promoted_at=None, rolled_back_at=None, new_start_selected=False, deployment=None, raw=None)
Operator-recorded drain intent for one (task_queue, build_id) cohort.
Returned by drain_task_queue_build_id,
promote_task_queue_build_id, and resume_task_queue_build_id.
build_id is None for the unversioned cohort (workers registered
without a build identifier). drain_intent is "active" or
"draining". drained_at is set only when drain_intent is
"draining"; repeated drains do not shift the timestamp.
promoted_at and new_start_selected identify the cohort currently
selected for fresh workflow starts.
dataclass
¶
WorkerDescription(worker_id, task_queue=None, runtime=None, namespace=None, sdk_version=None, build_id=None, status=None, max_concurrent_workflow_tasks=None, max_concurrent_activity_tasks=None, supported_workflow_types=None, supported_activity_types=None, last_heartbeat_at=None, registered_at=None, updated_at=None, task_slots=None, process_metrics=None, heartbeat_interval_seconds=None, raw=None)
Current server view of one registered worker.
dataclass
¶
Registered worker roster for one namespace.
dataclass
¶
Calendar or interval rules for a scheduled workflow.
dataclass
¶
ScheduleAction(workflow_type, task_queue=None, input=None, execution_timeout_seconds=None, run_timeout_seconds=None)
Workflow start request issued whenever a schedule fires.
dataclass
¶
ScheduleDescription(schedule_id, status=None, spec=None, action=None, overlap_policy=None, note=None, memo=None, search_attributes=None, jitter_seconds=None, max_runs=None, remaining_actions=None, fires_count=0, failures_count=0, next_fire_at=None, last_fired_at=None, latest_workflow_instance_id=None, paused_at=None, created_at=None, updated_at=None, info=None)
Current server view of a schedule and its recent execution state.
dataclass
¶
One page of schedule visibility results.
dataclass
¶
ScheduleTriggerResult(schedule_id, outcome, workflow_id=None, run_id=None, reason=None, buffer_depth=None)
Outcome returned after manually triggering a schedule.
dataclass
¶
Outcome returned after asking a schedule to backfill missed fires.
dataclass
¶
ScheduleHistoryEvent(sequence, event_type=None, recorded_at=None, workflow_instance_id=None, workflow_run_id=None, payload=None, id=None)
One entry in a schedule's audit history stream.
Each event corresponds to a lifecycle transition recorded by the
server (ScheduleCreated, SchedulePaused, ScheduleResumed,
ScheduleUpdated, ScheduleTriggered, ScheduleTriggerSkipped, or
ScheduleDeleted). The payload mirrors what the workflow engine
recorded, including command-context attribution when the transition
came from a mutating API call.
dataclass
¶
One page of a schedule's audit history stream.
next_cursor is the after_sequence value to request the next
page when has_more is True; it is None on the final page.
dataclass
¶
BridgeAdapterOutcome(schema, version, adapter, action, accepted, outcome, idempotency_key=None, reason=None, target=None, correlation=None, workflow_id=None, run_id=None, workflow_type=None, control_plane_outcome=None, raw=None)
Machine-readable result returned by a bridge adapter event.
Convenience wrapper for operating on one workflow ID.
async
¶
Block until this workflow terminates and return its result. See :meth:Client.get_result.
async
¶
Return the server's current view of this workflow. See :meth:Client.describe_workflow.
async
¶
Export this run's history as a replay bundle. See :meth:Client.export_history.
async
¶
List all runs in this workflow execution chain. See :meth:Client.list_workflow_runs.
async
¶
Return one run's detailed status. See :meth:Client.describe_workflow_run.
async
¶
Deliver an external signal to this workflow. See :meth:Client.signal_workflow.
async
¶
Execute a read-only query against this workflow. See :meth:Client.query_workflow.
async
¶
Request graceful cancellation of this workflow. See :meth:Client.cancel_workflow.
async
¶
Forcefully stop this workflow. See :meth:Client.terminate_workflow.
async
¶
Move this terminal workflow into the archive tier. See :meth:Client.archive_workflow.
async
¶
Send a synchronous update to this workflow and wait for the result. See :meth:Client.update_workflow.
StandaloneActivityHandle(client, activity_id, *, workflow_run_id=None, activity_execution_id=None, workflow_type='', activity_type='')
Convenience wrapper for operating on one standalone activity job.
Returned by :meth:Client.start_activity. The underlying execution is
a top-level durable job — the server records the activity inside its
own host run so retries, deadlines, cancellation, and history surface
through the existing activity infrastructure. The handle exposes the
job-style operations (describe, result, cancel) without
having to know that there is a host workflow run behind the scenes.
async
¶
Fetch the server's current view of this standalone activity.
See :meth:Client.describe_activity.
async
¶
Block until the activity reaches a terminal outcome and return its result.
See :meth:Client.get_activity_result.
async
¶
Request graceful cancellation of this standalone activity.
Cancellation flows through the host run's workflow cancellation path; the next heartbeat or attempt boundary observes the request.
Convenience wrapper for operating on one schedule ID.
async
¶
Return the server's current view of this schedule. See :meth:Client.describe_schedule.
async
¶
update(*, spec=None, action=None, overlap_policy=None, jitter_seconds=None, max_runs=None, memo=None, search_attributes=None, note=None)
Update one or more fields of this schedule. See :meth:Client.update_schedule.
async
¶
Pause this schedule so it stops firing. See :meth:Client.pause_schedule.
async
¶
Fire this schedule immediately. See :meth:Client.trigger_schedule.
async
¶
Fire this schedule for every moment in a past time range. See :meth:Client.backfill_schedule.
async
¶
Return one page of this schedule's audit history. See :meth:Client.get_schedule_history.
Iterate every audit event for this schedule. See :meth:Client.iter_schedule_history.
Client(base_url, *, token=None, control_token=None, worker_token=None, namespace='default', timeout=60.0, retry_policy=None, metrics=None, payload_size_limit_bytes=serializer.DEFAULT_PAYLOAD_SIZE_BYTES, payload_size_warning_threshold_percent=serializer.DEFAULT_WARNING_THRESHOLD_PERCENT, payload_size_warnings=True, external_storage=None, external_storage_threshold_bytes=None, external_storage_cache=None)
Async HTTP client for Durable Workflow control-plane and worker APIs.
The client owns one httpx.AsyncClient connection pool. Use it as an async
context manager or call aclose() when finished.
async
¶
Close the underlying httpx connection pool.
Equivalent to exiting the async-context-manager form of the client. Safe to call multiple times.
async
¶
Fetch server build identity, capabilities, and protocol manifests.
Return a :class:WorkflowHandle bound to an existing workflow instance.
Does not round-trip to the server. Pass run_id to pin the handle to
a specific run, otherwise the handle resolves to whichever run is
current at the time each method is called. workflow_type is
optional and used only in error messages.
async
¶
List namespaces visible to the current control-plane identity.
async
¶
Return configuration and status for one namespace.
async
¶
Create a workflow namespace and return the server representation.
async
¶
Update namespace metadata. Only provided fields are sent.
async
¶
Delete a namespace through the server lifecycle surface.
async
¶
set_namespace_external_storage(name=None, *, driver, enabled=True, threshold_bytes=None, config=None, namespace=None)
Configure external payload storage for a namespace.
The first positional argument is the namespace name, matching
:meth:describe_namespace, :meth:create_namespace, and
:meth:update_namespace. The namespace= keyword is accepted as a
deprecated alias from the 0.4.0 release and emits a
:class:DeprecationWarning; it will be removed in a future release.
async
¶
Ask the server to verify its configured external payload storage.
async
¶
Return the current task repair policy and candidate snapshot.
Mirrors dw system:repair-status. Operator surface; the caller
must be authenticated with admin scope.
async
¶
Run one task repair sweep on the server.
Mirrors dw system:repair-pass. Without filters the server runs
a full-scope pass; pass run_ids or instance_id to narrow
the sweep. Operator surface; requires admin scope.
async
¶
Return history-retention diagnostics for the current namespace.
Mirrors dw system:retention-status. The response reports the
namespace retention window, the cutoff, and the run IDs currently
eligible for pruning up to the server's scan limit. Operator
surface; requires admin scope.
async
¶
Run one history-retention enforcement sweep on the server.
Mirrors dw system:retention-pass. Without filters the server
prunes expired terminal runs from the namespace up to its scan
limit; pass run_ids to narrow the sweep or limit to bound
how many runs a single pass processes. Operator surface; requires
admin scope.
async
¶
Return activity-timeout diagnostics for the current namespace.
Mirrors dw system:activity-timeout-status. The response lists
activity execution IDs that have passed their start-to-close or
schedule-to-close deadline and are eligible for forced timeout.
Operator surface; requires admin scope.
async
¶
Run one activity-timeout enforcement sweep on the server.
Mirrors dw system:activity-timeout-pass. Without filters the
server enforces timeouts for any expired activity executions up
to its scan limit; pass execution_ids to narrow the sweep or
limit to bound how many executions a single pass processes.
Operator surface; requires admin scope.
async
¶
List task queues with server-side admission status.
Admission data describes server budgets and observed backlog. Worker constructor limits remain local semaphores that are advertised during registration.
async
¶
Return backlog, poller, lease, and admission detail for name.
async
¶
Return the build-id rollout snapshot for task_queue.
Use this before draining or removing an older build to confirm which
build cohorts can still claim work on the queue. Unversioned workers
are grouped under a cohort whose build_id is None.
async
¶
Mark a build-id cohort as draining so it stops claiming new tasks.
Workers registered under build_id keep running their in-flight
work but are blocked from claiming fresh tasks, and future workers
that heartbeat under the same build_id land as draining too.
Pass None to drain the unversioned cohort (workers registered
without a build identifier). Idempotent: repeated drains do not
shift the recorded drained_at timestamp.
async
¶
Select a build-id cohort for fresh workflow starts on a task queue.
New workflow starts pin to build_id after promotion. Existing
workflow runs keep their stamped compatibility marker and continue
routing only to compatible workers. Pass None to promote the
unversioned cohort.
async
¶
Revert a previous drain so a build-id cohort can claim work again.
Resuming clears both drain_intent and drained_at for the
cohort and flips any still-running workers back to active.
Pass None to resume the unversioned cohort. Idempotent:
resuming an already-active cohort is a no-op.
async
¶
List system and custom search attribute definitions for this namespace.
async
¶
Register a custom search attribute and return the server response.
async
¶
Remove a custom search attribute and return the server response.
async
¶
List registered workers in the current namespace.
async
¶
Return runtime, capacity, heartbeat, and type support for one worker.
async
¶
Remove a stale or retired worker from the server roster.
async
¶
start_workflow(*, workflow_type, task_queue, workflow_id, input=None, execution_timeout_seconds=3600, run_timeout_seconds=600, duplicate_policy=None, memo=None, search_attributes=None, priority=None, fairness_key=None, fairness_weight=None)
Start a new workflow instance and return a handle bound to it.
workflow_type is the language-neutral type key registered via
:func:durable_workflow.workflow.defn. task_queue selects which
worker pool picks up the workflow. workflow_id is the
caller-supplied instance id — if it collides with an existing
workflow, behavior depends on duplicate_policy
(reject | allow | terminate_existing).
input is a list of positional arguments passed to the workflow's
run method; the SDK encodes the list with the default payload
codec (Avro). execution_timeout_seconds covers the entire workflow
execution across all runs (including continue-as-new), while
run_timeout_seconds applies to this single run only.
memo and search_attributes attach operator-facing metadata to
the instance; see the main docs site for the key/value rules.
priority is an integer in the range 0..9 (lower numbers run
first when workers on a shared task queue are saturated; default
5). fairness_key tags the workload class — typically a
tenant id, team name, or workflow type — so dispatch on a shared
task queue can be rebalanced across declared classes under
contention; tasks without a key share one class. fairness_weight
(1..1000, default 1) lets a class take a proportionally
larger share of dispatch slots versus other classes on the same
queue.
async
¶
Return the server's current view of a workflow instance.
Resolves to the newest durable run in the instance's chain (including
any continue-as-new runs). Decodes the recorded input and
output envelopes when present.
async
¶
list_workflows(*, workflow_type=None, status=None, query=None, page_size=None, next_page_token=None)
Page through workflow instances, optionally filtered by type, status, or query string.
Pass the returned :attr:WorkflowList.next_page_token as
next_page_token on the next call to fetch the following page; the
token is None when there are no more pages.
async
¶
Fetch the full durable history for one specific run of a workflow.
async
¶
Export one workflow run history as a replay bundle.
async
¶
List all durable runs in one workflow execution chain, oldest first.
async
¶
Return detailed status, payload, and actionability for one specific workflow run.
async
¶
start_activity(*, activity_type, task_queue, activity_id=None, activity_class=None, input=None, business_key=None, retry_policy=None, start_to_close_timeout_seconds=None, schedule_to_start_timeout_seconds=None, schedule_to_close_timeout_seconds=None, heartbeat_timeout_seconds=None)
Start a standalone activity and return a handle bound to it.
activity_type is the language-neutral activity type key
registered via :func:durable_workflow.activity.defn. The same
activity definition can be invoked inside a workflow with the
worker's activity() call and also dispatched here as a
top-level durable job — there is no separate "job activity"
decorator. task_queue selects the worker pool that will run
the activity.
activity_id is an optional caller-supplied identifier (must be
URL-safe; same character rules as workflow_id). When omitted,
the server generates one. activity_class is an optional
free-form label that surfaces on the listing/show endpoints — it
does not affect dispatch.
input is a list of positional arguments passed to the
activity, encoded with the default payload codec.
retry_policy follows the same shape used inside a workflow
(max_attempts, backoff_seconds,
non_retryable_error_types). The four timeout knobs map
one-to-one onto the same fields applied to activities scheduled
from inside a workflow.
Returns a :class:StandaloneActivityHandle so the caller can
inspect the activity, await its result, or cancel it without
having to know that the server records the work inside a host
workflow run.
get_activity_handle(activity_id, *, workflow_run_id=None, activity_execution_id=None, activity_type='')
Return a :class:StandaloneActivityHandle bound to an existing
standalone activity. Does not round-trip to the server.
async
¶
Return the server's current view of one standalone activity.
The returned result field is decoded from the server's payload
envelope when the activity has completed; for not-yet-terminal
activities it is None.
async
¶
Page through standalone activities visible to the calling namespace.
status filters on the host-run status bucket and accepts
running, completed, or failed.
async
¶
Poll a standalone activity until it reaches a terminal outcome.
Returns the decoded activity result on success, raises
:class:~durable_workflow.errors.WorkflowFailed on failure (the
host run carries the activity's failure as its terminal state),
:class:~durable_workflow.errors.WorkflowCancelled /
:class:~durable_workflow.errors.WorkflowTerminated for the
respective lifecycle outcomes, or :class:TimeoutError if the
activity is still running after timeout seconds.
async
¶
send_webhook_bridge_event(adapter, *, action, idempotency_key, target, input=None, correlation=None)
Send one bounded webhook bridge event and return its contract outcome.
The bridge endpoint intentionally returns machine-readable rejected
outcomes as HTTP 422. This method returns those outcomes instead of
raising :class:InvalidArgument, while auth and unexpected server
failures still use the normal SDK exception mapping.
async
¶
Deliver an external signal to a running workflow.
Signals are fire-and-forget: the server records the signal in durable history and returns immediately. They do not wait for the workflow to observe the signal. See the main docs for how to declare the allowed signal names on a workflow type.
async
¶
Execute a named read-only query against a workflow and return the result.
Queries are synchronous and non-mutating. The server runs the named
query handler inside the workflow process and returns the decoded
result. Raises :class:~durable_workflow.errors.QueryFailed if the
query was rejected or the handler errored.
async
¶
Request graceful cancellation of a workflow's current run.
Cancellation is cooperative: the server delivers a cancellation signal
that the workflow can observe and handle (e.g. to roll back via a
saga). Compare with :meth:terminate_workflow, which is forceful.
async
¶
Forcefully stop a workflow without giving it a chance to clean up.
Prefer :meth:cancel_workflow when the workflow code can implement
graceful shutdown. Termination is an operator escape hatch.
async
¶
Ask the server to repair a stalled workflow, returning the command outcome.
async
¶
Move a terminal workflow into the archive tier, returning the command outcome.
async
¶
update_workflow(workflow_id, update_name, *, args=None, wait_for=None, wait_timeout_seconds=None, request_id=None)
Send a synchronous update to a running workflow and wait for the result.
Updates are request/response calls to a named handler on the workflow;
the handler may mutate durable workflow state and return a value.
wait_for selects how long the server waits before returning —
typically completed to block until the handler finishes, or
accepted to return once the validator has approved it.
request_id lets the caller deduplicate retries. Raises
:class:~durable_workflow.errors.UpdateRejected when the workflow's
validator rejects the update.
async
¶
Poll a workflow until it reaches a terminal state and return its result.
Raises :class:~durable_workflow.errors.WorkflowFailed,
:class:~durable_workflow.errors.WorkflowCancelled, or
:class:~durable_workflow.errors.WorkflowTerminated if the workflow
ended in a non-success state, or :class:TimeoutError if timeout
seconds elapse before the workflow terminates.
Return a :class:ScheduleHandle bound to an existing schedule.
Does not round-trip to the server. Use :meth:describe_schedule via
the handle when you need to verify the schedule actually exists.
async
¶
create_schedule(*, schedule_id=None, spec, action, overlap_policy=None, jitter_seconds=None, max_runs=None, memo=None, search_attributes=None, paused=False, note=None)
Create a new schedule and return a handle bound to it.
spec describes when the schedule fires (cron expressions,
intervals, calendars); action describes what it starts (typically
a workflow). overlap_policy controls what happens when a fire
would overlap an already-running action — skip, buffer_one,
buffer_all, cancel_other, or terminate_other. Pass
paused=True to create the schedule in a paused state and resume
it later with :meth:resume_schedule.
async
¶
Return the server's current view of a schedule, including status and fire counters.
async
¶
update_schedule(schedule_id, *, spec=None, action=None, overlap_policy=None, jitter_seconds=None, max_runs=None, memo=None, search_attributes=None, note=None)
Update one or more fields of an existing schedule.
Pass None for any field you don't want to change. Unknown fields
are ignored by the server.
async
¶
Pause a schedule so it stops firing until resumed.
Optional note is recorded as operator metadata on the pause
event. Pausing does not cancel workflows that are already running.
async
¶
Resume a paused schedule so it begins firing again.
async
¶
Fire a schedule immediately, outside its normal schedule.
The overlap_policy override applies only to this one manual fire.
The returned :class:ScheduleTriggerResult reports whether the fire
was accepted or skipped (e.g. due to overlap).
async
¶
Delete a schedule. Running workflows the schedule already started are unaffected.
async
¶
Fire a schedule for every would-have-been moment in [start_time, end_time].
Times are ISO-8601 strings. Useful to replay a period the schedule
was paused or to seed historical runs. The returned
:class:ScheduleBackfillResult reports how many fires were attempted
and the outcome of each.
async
¶
Return one page of the audit history stream for a schedule.
The page is ordered by sequence ascending. Use
after_sequence=page.next_cursor to request the next page while
page.has_more is True, or call :meth:iter_schedule_history
to walk every remaining event with paging hidden.
History is available for deleted schedules: the audit stream
records ScheduleDeleted and survives the schedule's removal
exactly so operators can review what happened.
limit is clamped by the server between 1 and 500 (default
100). after_sequence must be a non-negative integer; invalid
values raise :class:~durable_workflow.errors.InvalidArgument
through the shared 4xx mapping.
async
¶
Yield every audit event for a schedule, paging under the hood.
Each element is a :class:ScheduleHistoryEvent. Paging stops once
the server reports has_more=False.
async
¶
register_worker(*, worker_id, task_queue, supported_workflow_types=None, workflow_definition_fingerprints=None, supported_activity_types=None, max_concurrent_workflow_tasks=None, max_concurrent_activity_tasks=None, runtime='python', sdk_version=None, build_id=None, capabilities=None, task_slots=None, process_metrics=None, heartbeat_interval_seconds=None)
Register this process with the server as a worker for task_queue.
Called by :class:~durable_workflow.Worker at startup. Most
applications should not call this directly — create a
:class:~durable_workflow.Worker instead.
async
¶
heartbeat_worker(*, worker_id, task_slots=None, process_metrics=None, heartbeat_interval_seconds=None)
Send a worker-fleet heartbeat to refresh liveness and report state.
Workers should call this on a steady cadence (default 60s, advertised by the server in the register/heartbeat acknowledgement) so operators can answer "what workers are polling task queue X right now, what's their slot capacity, when did each last check in" via the worker management API, the CLI worker listing, and the operator Worker Status view.
task_slots is an optional dict with any subset of
workflow_available, activity_available, session_available
— the count of currently free slots for each family. The server
clamps each value into [0, max_concurrent_*].
process_metrics is an optional dict with any subset of
cpu_percent, memory_bytes, process_uptime_seconds,
process_id, process_started_at, and host — the SDK
reports only what it has cheap access to, and the server records
exactly what was reported.
Returns the server acknowledgement, which includes the advertised
heartbeat_interval_seconds and stale_after_seconds so the
worker can adapt its cadence on the fly.
Most applications create a :class:~durable_workflow.Worker, which
runs this on a background asyncio task — call this directly only when
driving the worker protocol by hand (smoke tests, custom runtimes).
async
¶
Long-poll for the next workflow task on task_queue.
Returns the task payload, or None on poll timeout. Worker-plane
endpoint — most applications use :class:~durable_workflow.Worker
rather than calling this directly.
async
¶
Report successful execution of a workflow task with its emitted commands.
Worker-plane endpoint, called by :class:~durable_workflow.Worker.
commands is the list of serialized commands the workflow yielded
for this task.
async
¶
fail_workflow_task(*, task_id, lease_owner, workflow_task_attempt, message, failure_type=None, stack_trace=None)
Report a workflow task failure so the server can schedule a retry.
Worker-plane endpoint. Task failures (e.g. non-determinism) are
distinct from workflow failures (FailWorkflow commands).
async
¶
workflow_task_history(*, task_id, next_history_page_token=None, page_token=None, lease_owner, workflow_task_attempt)
Page through extra history events while the worker is executing a long task.
Worker-plane endpoint. The first page of history is delivered inline with the workflow task; this endpoint fetches subsequent pages.
async
¶
Long-poll for the next workflow query task on task_queue.
Query tasks are ephemeral worker-plane requests created when the server must route a control-plane query to a non-PHP workflow runtime.
async
¶
complete_query_task(*, query_task_id, lease_owner, query_task_attempt, result, codec=serializer.AVRO_CODEC, workflow_id=None, run_id=None, query_name=None, external_storage=None, external_storage_threshold_bytes=None)
Submit the successful result for a worker-routed query task.
async
¶
fail_query_task(*, query_task_id, lease_owner, query_task_attempt, message, reason='query_rejected', failure_type=None, stack_trace=None)
Report a failed worker-routed query task.
async
¶
Long-poll for the next activity task on task_queue.
Returns the task payload, or None on poll timeout. Worker-plane
endpoint — typically used by :class:~durable_workflow.Worker.
async
¶
complete_activity_task(*, task_id, activity_attempt_id, lease_owner, result, codec=serializer.AVRO_CODEC, activity_name=None, external_storage=None, external_storage_threshold_bytes=None)
Report successful activity execution and submit the encoded result.
async
¶
fail_activity_task(*, task_id, activity_attempt_id, lease_owner, message, failure_type=None, stack_trace=None, non_retryable=False, details=None, codec=serializer.AVRO_CODEC, activity_name=None)
Report a failed activity attempt.
Pass non_retryable=True to signal that this class of error will
not be fixed by retrying — the server then surfaces the failure to
the workflow immediately instead of scheduling another attempt.
async
¶
Send a liveness heartbeat for a running activity attempt.
Worker-plane endpoint. Most code calls
:meth:~durable_workflow.ActivityContext.heartbeat instead, which
additionally raises :class:~durable_workflow.errors.ActivityCancelled
when the server reports the activity should stop.