Handler Overview

Implement the line-delimited JSON handler protocol

Handler Overview

Handlers are persistent containerized programs. They read one task per line from stdin and write exactly one JSON response per task to stdout. The process remains alive for subsequent tasks.

Request and Response

{"task_id":"550e8400-e29b-41d4-a716-446655440000","task_type":"process","task_data":{"key":"value"},"attempt":1}

The handler request uses attempt = stored attempts + 1, starting at attempt: 1. API attempts starts at zero and increments on retry scheduling or a Failed marking; successful completion does not increment it. An initial success therefore has request attempt: 1 and API attempts: 0, while an initial terminal failure stores attempts: 1. Recovery can repeat the same request attempt, so this number is not a unique execution counter. task_id remains the same across retries and recovery. Deduplicate external effects by this ID when needed.

{"status":"success","result":{"processed":true}}

{"status":"error","error":"Temporarily unavailable","retryable":true}

A valid retryable error schedules another execution only when the task has remaining retry budget. Default retry delays are 1, 2, and 4 seconds. Timeouts, invalid responses, and broken transport are terminal failures; the daemon stops an unusable stream before another task can use it. See retry and recovery settings.

SDKs

SDK source is in TaskDaemon-Handlers. The Python package taskdaemon==0.1.0 is published on PyPI. Go module github.com/jona62/TaskDaemon-Handlers/go@v0.1.2 is published and verified through the public Go proxy. npm, crates.io, Maven Central, and NuGet uploads are pending; their guides use source installation.

Language	Guide
Python	Python SDK
Node.js	Node.js SDK
Go	Go SDK, module github.com/jona62/TaskDaemon-Handlers/go
Rust	Rust SDK
C++	C++ SDK, header-only
Java	Java SDK
C#	C# SDK
Any other language	Raw protocol

Minimal Handler

import json
import sys

for line in sys.stdin:
    task = json.loads(line)
    print(json.dumps({"status":"success","result":task["task_data"]}), flush=True)

FROM python:3.11-slim
COPY handler.py /app/
WORKDIR /app
CMD ["python", "-u", "handler.py"]

Logging and Output

Send logs to stderr. The daemon may skip non-JSON stdout text, but JSON-formatted logs can be parsed as protocol responses, so stdout is not a safe general logging channel.

print("Processing task", file=sys.stderr)

console.error("Processing task");

log.Println("Processing task") // Go's standard logger defaults to stderr.

eprintln!("Processing task");

Always flush each response and keep processing input until stdin closes. A timeout stops the handler stream and can interrupt side effects, so design for at-least-once execution rather than assuming a single uninterrupted run.

Register the Image

Build the image before daemon startup, then add:

[handlers.process]
image = "my-handler:latest"
instances = 2
timeout = 30

Startup has no readiness handshake. Test a representative task and wait for a completed result before relying on the pool. See handlers.toml for all options.