README

# Hefesto

Simple, efficient background job processing for Delphi.

Hefesto is a Delphi framework for processing jobs asynchronously, reliably and efficiently. It replaces manual queue polling loops with a declarative, fluent API that handles concurrency, retry, observability and lifecycle — so you focus on business logic, not plumbing.

Performance

Real-world benchmark consuming 200 SQS messages via LocalStack, each job performing 50ms of simulated work:

The manual loop pattern (Get(1) + Sleep(15s)) represents the actual consumption strategy found in production Delphi SQS workers. Hefesto's improvement comes from batching, concurrency, and long-polling — with zero changes to the job handler itself.

Getting Started

1. Installation

Clone and add src/ to your Delphi project search path:

git clone https://github.com/herlondf/hefesto.git

Search path: hefesto\src\

2. Define a job handler

type
  TEmailHandler = class(TInterfacedObject, IHefestoJobHandler)
    function CanHandle(const AJob: IHefestoJobEnvelope): Boolean;
    procedure Perform(const AContext: IHefestoJobContext);
  end;

procedure TEmailHandler.Perform(const AContext: IHefestoJobContext);
begin
  SendEmail(AContext.Job.Body);
end;

3. Configure and run

THefestoServer.New
  .UseQueue(MySQSAdapter)
  .Concurrency(4)
  .BatchSize(10)
  .RetryPolicy(THefestoSimpleRetryPolicy.New(5, 30))
  .Telemetry(THefestoConsoleTelemetry.New)
  .RegisterHandler('send_email', TEmailHandler.Create)
  .Run;

That's it. Batch, long-polling, concurrency, retry, dead-letter and telemetry — all configured in 8 lines.

Requirements

• Delphi 11 Alexandria or later
• No mandatory external dependencies

Optional (adapter-specific):

• Redis4D — for Redis state store, locks, scheduled store
• FireDAC (included in Delphi) — for SQLite/Postgres state store
• Synapse (included in src/vendor/synalist/) — for TCP adapter

Queue Adapters

All adapters use HTTP only — no external SDK required. Implement IHefestoQueueAdapter (5 methods) to add your own.

Features

Core

• Configurable batch size (1-10 per fetch)
• Long-polling support
• Global, per-queue and per-action concurrency limits
• Retry policies: THefestoSimpleRetryPolicy (fixed delay) and THefestoExponentialRetryPolicy (base × n²)
• Automatic dead-letter queue
• Graceful shutdown (no lost jobs)

Pro-level

• Scheduled jobs — EnqueueIn(delay) / EnqueueAt(datetime)
• Periodic jobs — native cron scheduling (5-field expressions)
• Batch jobs — OnComplete / OnSuccess callbacks
• Unique jobs — deduplication strategies
• Rate limiting — token-bucket per key
• Idempotency — duplicate execution prevention

Enterprise-level

• Leader election — cluster-wide singleton operations
• Client reliability — outbox pattern for crash recovery
• Server reliability — heartbeat + stale execution recovery
• Rolling restarts — graceful drain and resume
• Pause/resume — operational queue control
• Circuit breaker — external provider protection
• Job Graph (DAG) — declarative job dependencies, parallel execution, cascade cancellation
• OpenTelemetry — OTLP trace exporter for Jaeger, Grafana Tempo, Honeycomb, Datadog
• Dashboard Web — SPA with real-time metrics (SSE), /health, /metrics (Prometheus scrape), cancel scheduled jobs

All features included. No paid tiers.

Hefesto vs Hefesto Ruby

Middlewares

Chainable pipeline — runs before publish (client) or before execution (server):

Implement IHefestoServerMiddleware (1 method) to add your own.

State Stores

Exemplos

Project Structure

src/                ~35 framework units
src/adapters/       ~35 adapter units (queues, middlewares, providers, telemetry)
src/vendor/         Synapse (bundled)
samples/           25 runnable demos
tests/              DUnitX unit tests (11 fixtures) + thread-safety + Redis smoke
docs/               Presentation (md + pptx)
docker/             docker-compose for local Redis, Postgres and Jaeger

Contributing

See CONTRIBUTING.md for guidelines on adapters, middleware, state stores, tests, and pull request flow. Also available in Portuguese: CONTRIBUTING_pt-br.md

The Olympian Family

Poseidon comanda os mares — transporte bruto, a força das ondas. Triton guarda as águas do pai — gerencia o que flui, retém o que não pode se perder. Pégaso voa pelos céus — nasceu do sangue de Medusa, pela espada que Hermes deu a Perseu. Hermes percorre todos os reinos — carrega mensagens entre deuses, mortais e monstros, mais rápido que qualquer onda. Hefesto forja nas profundezas — invisível, incansável, transformando matéria bruta em obra acabada.

Inspiration

Hefesto is inspired by Sidekiq, the battle-tested background job framework for Ruby. The same core ideas — reliable queues, concurrency, retry with backoff, dead-letter, observability — brought natively to Delphi.

License

MIT — use freely in commercial and open-source projects.

🇧🇷 Leia este documento em português: README_pt-br.md