The web server receives transform requests, but the execution runner is the component that actually schedules and tracks transform runs. The runner also invokes middleware hooks, stores intermediate results, and cleans up stale run state.
Runner types
The SDK supports two runner modes through maltego.server.TransformRunnerType:
| Runner | When to use it |
|---|---|
TransformRunnerType.THREADED | Default. Use it when transforms or dependencies contain blocking code. The server starts worker threads and each worker runs its own asyncio loop. |
TransformRunnerType.ASYNC | Use it when your transforms and middleware are fully async and you want lower overhead on the main event loop. |
Configuration
Configure the runner through MaltegoServerSettings:
from maltego.server import MaltegoServerSettings, TransformRunnerType
settings = MaltegoServerSettings(
server_name="Acme Transforms",
ns="acme",
author="dev@acme.com",
transform_runner=TransformRunnerType.THREADED,
num_worker=4,
transform_execution_timeout=900,
middleware_execution_timeout=120,
scheduled_cleanup_seconds=60,
)The important settings are:
transform_runner: selects threaded vs async executionnum_worker: only used by the threaded runnertransform_execution_timeout: maximum runtime for a transformmiddleware_execution_timeout: maximum runtime for each middleware hookscheduled_cleanup_seconds: cleanup interval for inactive execution state
Execution lifecycle
At a high level, a transform run goes through these steps:
- the server parses input and normalizes transform settings
before_transform(...)middleware hooks run- the transform executes
after_transform(...)middleware hooks run- the runner keeps the result available until the cleanup window expires
The cleanup loop marks inactive runs as timed out and removes them on later passes, which is why scheduled_cleanup_seconds also acts as the runner's retention window for stale executions.
Related guides
- See the Server Configuration article.
- See the Transform Middlewares article.