cenk1cenk2/hermes-bridge-runs repository overview

⁠hermes-bridge-runs

A broker in front of a Hermes⁠ API server that speaks its own /v1/runs API. Every create becomes a job with an id of its own, held in Redis while Hermes is busy or down and resubmitted when a run is interrupted, so a caller that polls the job keeps getting an answer through Hermes restarts and broker rollouts. Talks directly to any deployment that exposes /v1/runs, and authenticates nobody: the gateway in front of it does.

⁠Image

docker run --rm -p 8080:8080 cenk1cenk2/hermes-bridge-runs:latest

⁠Environment

Durations are milliseconds unless noted.

⁠Routes

Errors answer the Hermes envelope {"error":{"message","type","code"}}.

⁠Runs

The broker enqueues every create as a durable job in Redis instead of calling Hermes inline: a create answers immediately with the job id, the job survives Hermes restarts and rollouts, and RUNS_PROXY_ENABLED additionally exposes runs that were created on Hermes directly. RUNS_EVENT_BLOCK bounds how long an event stream waits for its next event before it verifies the client is still connected; raise it on high-latency links if streams close early.

Every job is a thread of its own, runs-<run_id>, that never batches or steers, so one job is one Hermes run at a time and a stop stops only that job. The job id is the idempotency key of its first Hermes create and <run_id>#<attempt> of each resubmit. A session_id in the body is passed to Hermes as the session of the run and nothing else.

attempts counts the Hermes runs of the job. A job, its idempotency key and its events are kept for RUNS_RETENTION after their last change.

⁠Logs

Every line carries a message that is a complete sentence fixed per event, its source class as context, and its ids, numbers and reasons as fields at the root of the JSON object ({"level":"log","message":"Created a job.","context":"RunsJobService","job":"job_...","key":"...","hold":2400000,"resubmit":3}); text prints the same fields inline. Durations are durationMs; bodies are never logged.

• info: one line per HTTP request (method, path, status, duration, remote address; /healthz and /readyz only at debug), each created, replayed, held, accepted, stopped and finished job, each proxied run, run creation, busy backoff, follows and takeovers, finished runs with status and duration, Redis connections, the drain on shutdown and the runs, threads and event streams it hands over or ends.
• debug: every appended job event, opened and closed event stream, run stream event, Hermes call (method, path, status, duration), thread lock and run lease acquire, renew and release, and Redis transaction retry.
• warn and error: anything retried, rejected, dropped or failed, with its error.

⁠Development

The application lives in apps/runs of the workspace and runs on the shared core in packages/core; see the repository README.

pnpm install
pnpm lint
pnpm test
pnpm build
pnpm --filter @kilic.dev/hermes-bridge-runs start