wt-runner

wt-runner provides an HTTP API for executing compiled workflows using wt-invokers. It supports multiple invoker backends and integrates with OpenTelemetry for distributed tracing.

Modules: app · tracing

HTTP API

Common Query Parameters

Parameter	Type	Default	Description
`matchspec`	`str`	(required)	Rattler matchspec identifying the workflow package
`invoker_type`	`str`	`"BlockingLocalSubprocessInvoker"`	Invoker backend to use

Invoker Registry

`invoker_type` string	Invoker class
`"BlockingLocalSubprocessInvoker"`	`LocalSubprocessInvoker`
`"AsyncLocalSubprocessInvoker"`	`LocalSubprocessInvoker`
`"CloudBatchInvoker"`	`CloudBatchInvoker`

Endpoints

`GET /`

Health check. Returns 200 OK.

`POST /`

Run a workflow with configuration and parameters.

Query parameters:

Parameter	Type	Default	Description
`workflow_run_id`	`str`	`""`	Unique identifier for this run
`timeout`	`float \\| None`	`None`	Maximum execution time in seconds
`docker_image_uri`	`str \\| None`	`None`	Container image URI (Cloud Batch only)

Headers:

Header	Type	Default	Description
`traceparent`	`str \\| None`	`None`	W3C trace context parent
`tracestate`	`str \\| None`	`None`	W3C trace context state

JSON body:

Field	Type	Required	Description
`params`	`dict[str, Any]`	yes	Task parameters keyed by task instance ID
`execution_mode`	`"async" \\| "sequential"`	yes	Execution mode
`mock_io`	`bool`	yes	Use mock I/O for testing
`results_url`	`str`	yes	URL for results output (resolved via dependency)
`data_connections_env_vars`	`dict[str, SecretStr] \\| None`	no	Environment variables for data connections
`lithops_config`	`LithopsConfig \\| None`	no	Lithops configuration for serverless execution

Response:

{
  "result": { ... },
  "error": null,
  "trace": null
}

On failure, error contains the exception message and trace contains the full traceback.

`POST /run-from-pubsub`

Process RunWorkflow messages from Google Cloud Pub/Sub. Used for event-driven workflow execution in GCP deployments.

`GET /rjsf`

Retrieve the React JSON Schema Form configuration for a workflow. Used by web UIs to render parameter forms.

`GET /data-connection-property-names`

Get data connection property names from workflow metadata.

`POST /formdata-to-params`

Convert hierarchical form data to flat workflow parameters.

On schema-validation failure, returns 422 with a ValidationErrorResponse body.

`POST /params-to-formdata`

Convert flat workflow parameters to hierarchical form data.

On schema-validation failure, returns 422 with a ValidationErrorResponse body.

Validation error shape

Both conversion endpoints surface jsonschema-native error entries directly (no FastAPI/pydantic-shape translation):

class ValidationErrorItem(BaseModel):
    message: str
    path: list[str | int]
    schema_path: list[str | int]
    validator: str
    input: Any  # the failing instance value


class ValidationErrorResponse(BaseModel):
    detail: list[ValidationErrorItem]

Both models are exported from wt_contracts.

Response Model

class ResponseModel(BaseModel):
    result: dict[str, Any] | None = None
    error: str | None = None
    trace: str | None = None

Middleware

CORS: Allows all origins and credentials; methods restricted to POST.
GZip: Compresses responses larger than 1000 bytes.

Tracing

OpenTelemetry tracing for distributed observability across the workflow execution chain.

Environment Variables

Variable	Values	Default	Description
`ECOSCOPE_WORKFLOWS_OTEL_EXPORTER`	`"console"`, `"gcp"`, or unset	unset (disabled)	Exporter type
`ECOSCOPE_WORKFLOWS_OTEL_CONSOLE_EXPORTER_DST`	`"stdout"`, `"file"`	`"file"`	Console exporter destination
`ECOSCOPE_WORKFLOWS_OTEL_CONSOLE_EXPORTER_FILE_DST_TARGET_DIR`	directory path	—	Directory for trace files (required when using file destination)

Functions

Function	Description
`configure_tracer()`	Configure the global OpenTelemetry tracer provider
`attach_context()`	Attach trace context from W3C headers
`build_context_headers()`	Extract current trace context as W3C headers
`otel_span_formatter()`	Format a span as single-line JSON

Trace Propagation

Traces propagate through the execution chain using W3C trace context headers:

HTTP request → wt-runner → workflow subprocess → wt-task

Testing Utilities

Name	Description
`Case`	Pydantic model describing a test case (parameters + expected output)
`CaseRunner`	Dataclass that executes a `Case` via FastAPI test client or CLI