Domains
Each middleware root receives a different context object. Those context models define what a middleware can inspect or mutate.
Task Middleware
@dataclass
class TaskMiddlewareContext:
task: BaseTaskEntered by BaseTask.run().
The task's per-invocation working directory
is created at the innermost point of this chain, immediately before
_run(). Every middleware's before hook has therefore already run by the time
the directory exists.
That ordering is what makes retargeting possible. A middleware may repoint
context.task.target in before — an orchestrator re-anchoring a task the
engine added mid-run, for instance, such as a horus_map clone or an inlined
subworkflow body — and the directory is then created under the new target. If it
were created before the chain were entered, the retarget would land too late:
the directory would exist at the old path and the executor would launch with a
cwd that was never created.
No built-in middleware relies on the directory existing during before. If
yours does, create it yourself rather than assuming.
Bound Task Middleware
@dataclass
class BoundTaskMiddlewareContext:
task: BaseTask
target: BaseTarget
input_digests: InputDigestsEntered by the scheduler for each attempt of a task on its acquired target, after the task is bound to it and before the completion check. It wraps the check, the input transfers, dispatch and wait.
Unlike Task Middleware, it runs for every placed task, including tasks that end up skipped as complete, on every target kind. Use it for work that has to land on the target before Horus decides whether the task is complete, such as restoring cached outputs.
context.target is context.task.target. On a node that is provisioned on first use, the first command inbeforeprovisions it.- A node lost during the attempt re-binds the task and wraps the retry again,
so
beforeruns once per node. RaiseTargetLostErrorfrombeforeto get that retry instead of swallowing it. input_digestsreturns the input digests the completion check uses. It is computed on the first await and shared with the check. Pass it totask.manifest_matches(manifest, input_digests)to know whether a stored completion manifest still matches before downloading anything.aftermust not raise: its exception would replace the attempt's.
Register it under the horus.middleware.bound_task entry point group.
Task Skip Middleware
@dataclass
class TaskSkipMiddlewareContext:
task: BaseTask
workflow: BaseWorkflow
input_digests: InputDigests
complete: bool = FalseEntered by the scheduler once per placed task, before its lease slot, placement and pool slot. Use it to skip a task from metadata alone, such as a cached task whose outputs are only fetched when a running task consumes them.
- Set
context.complete = Trueinbeforeto skip the task as complete. It is ignored whentask.skip_if_completeis false. - Only skip a task whose outputs can be read without it, for example relocated
with
workflow.relocate_output. The task never reaches its machine. input_digestsdigests inputs at their source. It is shared with the bound-task middleware and the first completion check. A pinned input is digested ontask.target, which is not bound yet, so don't await it for a task with one.- Not entered again on a node-loss retry. An exception fails the task.
Register it under the horus.middleware.task_skip entry point group.
Workflow Middleware
@dataclass
class WorkflowMiddlewareContext:
workflow: BaseWorkflowEntered by BaseWorkflow.run().
Runtime Middleware
@dataclass
class RuntimeMiddlewareContext:
runtime: BaseRuntime
task: BaseTaskEntered by BaseRuntime.setup_runtime().
Executor Middleware
@dataclass
class ExecutorMiddlewareContext:
executor: BaseExecutor
task: BaseTaskEntered by BaseExecutor.execute().
Target Middleware
@dataclass
class TargetMiddlewareContext:
target: BaseTarget
task: BaseTaskEntered by BaseTarget.dispatch().
Transfer Middleware
@dataclass
class TransferMiddlewareContext:
transfer_strategy: BaseTransferStrategy[Any, Any]
artifact: BaseArtifact
source: BaseTarget
destination: BaseTargetEntered by BaseTransferStrategy.transfer().
Interaction Middleware
@dataclass
class InteractionMiddlewareContext:
transport: BaseInteractionTransport
interaction: BaseInteraction
renderer: BaseInteractionRenderer[Any, Any]
attempt: intEntered by BaseInteractionTransport.ask() once per render attempt.
This context is intentionally mutable. Middleware can replace the transport, interaction, or renderer before the render call happens.
Built-in Middleware
Horus currently ships two built-in middleware implementations:
TaskTimeMiddlewareWorkflowTimeMiddleware
Both record elapsed wall-clock time and emit timing information on the event bus after execution completes.