README

Poseidon

Deus dos mares - poder bruto, velocidade incomparavel.

Framework HTTP assincrono nativo, zero dependencias, para Delphi e Free Pascal.

IOCP/RIO no Windows, io_uring/epoll no Linux - HTTP/1.1, HTTP/2, WebSocket e 22 middlewares integrados de fabrica.

128k RPS, zero erros com 500 conexoes simultaneas.

Inicio Rapido

program MyServer;
{$APPTYPE CONSOLE}
uses
  System.SysUtils,
  Poseidon.Native.Types,
  Poseidon.Native.Server;

var
  App: TPoseidonServer;
begin
  App := TPoseidonServer.Create;
  try
    App.Get('/ping',
      procedure(var Ctx: TNativeRequestContext)
      begin
        Ctx.Status := 200;
        Ctx.ContentType := 'application/json';
        Ctx.Body := TEncoding.UTF8.GetBytes('{"message":"pong"}');
      end);

    App.Get('/hello/:name',
      procedure(var Ctx: TNativeRequestContext)
      begin
        Ctx.Status := 200;
        Ctx.ContentType := 'application/json';
        Ctx.Body := TEncoding.UTF8.GetBytes('{"hello":"' + Ctx.Param('name') + '"}');
      end);

    App.Listen(9000, '0.0.0.0',
      procedure
      begin
        Writeln('Servidor pronto em http://localhost:9000');
        Readln;
        App.Stop;
      end);
  finally
    App.Free;
  end;
end.

Por que Poseidon

Arquitetura: Shared-Nothing Per-Core

Cada core faz tudo: accept, recv, parse, executa handler, envia resposta. Sem filas, sem locks, sem contencao. Escalamento linear com o numero de cores.

O backend de I/O e selecionado uma unica vez na inicializacao, com fallback automatico: IOCP (padrao no Windows) ou RIO (opt-in, polling sem syscall via FORCE_RIO); io_uring >= 5.1 (padrao no Linux) ou epoll (fallback / opt-in via FORCE_EPOLL).

Performance vs. o Mercado

Treze servidores HTTP, um de cada vez, na mesma máquina e na mesma janela - sete frameworks já conhecidos deste comparativo mais seis representantes clássicos de outros ecossistemas (Node.js, Python, Ruby, PHP, Java), pra responder de forma direta: um framework HTTP em Object Pascal compete de igual pra igual com os nomes mais conhecidos do mercado?

Cenário. Carga mista: 40% /plaintext (13 B), 30% /json (27 B), 30% /json-large (63 KB), gerada por wrk -t4 -c200 durante 300 s por framework, após 20 s de aquecimento descartado. Cada servidor rodou em Docker com --cpuset-cpus fixando 2 núcleos físicos dedicados (--cpus=2.0, limite de 1 GB de memória); o gerador de carga ficou isolado em outros 2 núcleos físicos dedicados, numa rede bridge dedicada (não --network host, pra funcionar em Windows+Docker Desktop também - ver métodologia completa e as trocas envolvidas em benchmark/README.md). Os treze serviram payloads byte a byte idênticos e o mix medido saiu 40,0/30,0/30,0 em todos. Host: debian-bench (4 núcleos físicos totais). Reproduza você mesmo com benchmark/scripts/run-all.sh (ou .ps1 no Windows) - constrói e mede todos os treze a partir do código-fonte real de cada framework, sem nada vendorizado.

uWebSockets (uws) não entra nesta tabela. Não é um framework HTTP de propósito geral: é uma biblioteca de sockets/event-loop sem backpressure, sem timeout de conexão, sem headers de segurança e sem upgrade de protocolo embutidos - nenhuma das features que todo outro concorrente aqui (Poseidon incluso) paga no caminho quente. Medir throughput contra ela responde "quão rápido é um event loop nu", não "quão rápido é este framework", que é a pergunta que esta tabela quer responder.

O que os números dizem

Segundo de treze, a 7,2% do primeiro - um servidor Rust escrito à mão continua na frente, mas por uma margem pequena. O que essa tabela realmente mostra é a distância pros nomes que a maioria associa a "framework web de produção":

• 2,3x o Kestrel (C#/.NET), 3,4x o Spring Boot (Java, o framework enterprise mais usado do mundo Java) e 5,1x o Horse (o outro framework Object Pascal da lista).
• 9,8x o Express (o framework Node.js mais usado que existe), 16,8x o FastAPI (Python), 39x o Django (Python) e 42x o Rails com Puma (Ruby, o app server padrão do Rails desde a v5).
• 158x o Laravel (PHP) - mas isso reflete o PHP-FPM padrão saturando sob carga sustentada (1.414 erros no meio de 300 s), não uma comparação particularmente informativa por si só.
• Ainda na frente do Go Fiber, mORMot2 e nginx - os três mais próximos depois do Actix.

Rails e Django rodam sem banco de dados (nenhum dos três endpoints precisa de persistência) e Express/FastAPI/Spring Boot/Kestrel usam o próprio servidor padrão de cada framework, sem tuning de produção além do default - ver as trocas completas e o motivo de cada uma em benchmark/README.md (em inglês).

Duas correções entraram no Poseidon durante uma medição anterior neste mesmo comparativo (num host diferente, 16 núcleos): um relógio do idle sweep que estourava em UInt64 e fechava justamente as conexões mais movimentadas (6.405 erros de socket espúrios, agora zero, e +12% de throughput de brinde), e o dimensionamento de IO workers que ignorava o orçamento de CPU do contêiner (p99 31% menor em A/B pareado, 67% com 4 CPUs). Detalhes adicionais de metodologia em docs/playbook_pt-br/07-benchmarking; um harness de benchmark em Delphi standalone (sem Docker) está em samples/08-benchmark/ - os números desta tabela vêm do harness Docker reproduzível em benchmark/.

Toda mudanca no caminho quente e validada com uma comparacao controlada antes/depois antes de ser mergeada - mesmo binario, uma mudanca por vez. A rodada de parser/dispatcher de 2026-08-07 (removeu uma alocacao redundante no header Connection, pulou a varredura de deteccao de upgrade em GETs sem upgrade) mediu +1,7% de throughput, com toda repeticao do lado "depois" superando toda repeticao do lado "antes".

Funcionalidades

Engine - HTTP/1.1 keep-alive · HTTP/2 (ALPN h2, h2c, server push, flow control) · WebSocket (RFC 6455, permessage-deflate) · Server-Sent Events · HTTPS com OpenSSL nativo (SNI, mTLS) · Compressao gzip + Brotli · Proxy Protocol v1/v2 · Graceful reload (PID file, SIGTERM, zero-downtime) · Windows 64-bit (IOCP/RIO) + Linux 64-bit (io_uring/epoll) · Delphi 11+ e Free Pascal 3.3.1

Framework - Router hash-map, lookup O(1), suporte a :param · Registro fluente de rotas (Get/Post/Put/Delete/Patch/Head/All) · Contexto de requisicao zero-copy, stack-allocated · Binding de DTO com atributos de validacao · OpenAPI 3.x + Swagger UI · RFC 7807 Problem Details · Cookies assinados (HMAC-SHA256)

Engenharia de performance - Contadores atomicos com padding de cache-line · I/O vetorizado (writev/WSASend) · Arquivos registrados no io_uring + multishot accept · Reciclagem de sockets via DisconnectEx (Windows) · Arena de headers thread-local · Buffer pool de 8 KB (Acquire/Release)

22 middlewares integrados - CORS, JWT, Logger, RateLimit, Compression, Timeout, BodyLimit, RequestID, CircuitBreaker, Metrics, Static, HealthCheck, Security, Proxy, Digest, Guard, Validation, ProblemDetails, OpenAPI, Cache, Tracing, OTLP

Requisitos

• Delphi 11 Alexandria ou superior, ou Free Pascal 3.3.1 (trunk)
• Windows 64-bit ou Linux 64-bit
• OpenSSL no PATH (apenas para HTTPS/HTTP2)

Instalacao

Adicione src/, src/compat/ e middlewares/ ao search path do projeto:

<poseidon>\src
<poseidon>\src\compat
<poseidon>\middlewares

Free Pascal / Lazarus

O Poseidon compila e serve sob FPC 3.3.1 no Win64 (IOCP) e Linux (io_uring/epoll) alem do Delphi. Notas:

• Requer FPC 3.3.1 (trunk) - reference to / metodos anonimos e RTTI de atributos nao existem no release 3.2.2. Compile com -MDELPHIUNICODE -Mfunctionreferences -Manonymousfunctions -Mprefixedattributes.
• No Linux, cthreads deve ser a primeira unit do programa ({$IFDEF UNIX}) para ativar o RTL com threads.
• Sob FPC o servidor usa SyncDispatch por padrao (dispatch inline); o modo async (worker pool) e best-effort no trunk atual do FPC.
• Gates de referencia: tests/fpc/build-server-fpc.ps1 (Windows), tests/fpc/build-linux-fpc.sh (Linux).

Exemplos de Uso

Middleware

uses
  Poseidon.Native.Types,
  Poseidon.Native.Server,
  Poseidon.Middleware.CORS,
  Poseidon.Middleware.JWT,
  Poseidon.Middleware.Logger;

var
  App: TPoseidonServer;
begin
  App := TPoseidonServer.Create;

  App.Use(CORSMiddleware);
  App.Use(LoggerMiddleware);
  App.Use(JWTMiddleware('meu-segredo'));

  App.Get('/api/dados',
    procedure(var Ctx: TNativeRequestContext)
    begin
      Ctx.Status := 200;
      Ctx.ContentType := 'application/json';
      Ctx.Body := TEncoding.UTF8.GetBytes('{"dados":"protegidos"}');
    end);

  App.Listen(9000);
end.

WebSocket

App.WebSocket('/ws',
  procedure(Conn: IPoseidonWSConn; MsgType: Byte; Data: TBytes)
  begin
    Conn.Send(Data);  // echo
  end);

Server-Sent Events

App.Get('/eventos',
  procedure(var Ctx: TNativeRequestContext)
  var
    LStream: IPoseidonEventStream;
  begin
    LStream := Ctx.EventStream;  // 200 + text/event-stream na hora
    TTask.Run(
      procedure
      begin
        LStream.Send('pronto', 'status');
        LStream.Close;
      end);
  end);

Detalhes em docs/playbook_pt-br/03-protocolos/sse.md.

SSL/TLS

App.ConfigureSSL('cert.pem', 'key.pem');
App.AddSSLCert('api.exemplo.com', 'api-cert.pem', 'api-key.pem');  // SNI
App.EnableHTTP2;
App.Listen(443);

Mais receitas (grupos de rotas, graceful reload, hardening de seguranca, metricas) vivem no playbook.

Documentacao

• Referência de API · API Reference (EN)
• Playbook (English)
• Playbook (Portugues)
• FuzzRunner - fuzzing contínuo dos parsers
• Contributing
• Como contribuir (pt-BR)

A Familia Olimpica

Poseidon comanda os mares - poder bruto, a engine assíncrona sob as ondas. Triton, seu filho, guarda as profundezas - retém as conexões que não podem se perder. Hermes percorre todos os reinos - carrega mensagens, mais rápido que qualquer onda. Hefesto forja nas profundezas - invisível, incansável, transformando matéria bruta em obra acabada. Apollo é o deus da luz e da verdade - traz tudo à luz.

Licenca

MIT

🇺🇸 Read this document in English: README_en.md