README.pt-BR.md

July 16, 2026 · View on GitHub

Horse é um framework web para Delphi e Lazarus inspirado no Express.
Projetado para facilitar o desenvolvimento rápido, de forma minimalista e com alta performance.

Leia em English ou Português (BR).

⚙️ Instalação

A instalação é feita pelo comando boss install:

boss install horse

(Opcional) Instale o Horse Wizard para integração com a IDE.

⚡️ Início rápido — Delphi

uses Horse;

begin
  THorse.Get('/ping',
    procedure(Req: THorseRequest; Res: THorseResponse)
    begin
      Res.Send('pong');
    end);

  THorse.Listen(9000);
end.

⚡️ Início rápido — Lazarus

{$MODE DELPHI}{$H+}

uses Horse;

procedure GetPing(Req: THorseRequest; Res: THorseResponse);
begin
  Res.Send('Pong');
end;

begin
  THorse.Get('/ping', GetPing);
  THorse.Listen(9000);
end.

📖 Documentação

O guia completo fica em doc/ — um pequeno wiki que complementa a referência rápida abaixo:

Tópico	Leia
Primeiro servidor, instalação, configuração no Delphi/Lazarus	Primeiros passos
Definir rotas, parâmetros de rota, grupos de rotas, query strings	Roteamento
`THorseRequest` / `THorseResponse` — body, headers, cookies, sessions, status, streaming	Request e Response
Suporte nativo a conexões bidirecionais WebSocket (RFC 6455)	WebSockets
Suporte nativo a transmissões streaming (Web Streams / SSE)	Streaming
Usar middleware, ordem de registro, o `Next` proc	Middleware
Ganchos de Ciclo de Vida — onRequest, preParsing, preValidation, onSend, onResponse	Ganchos de Ciclo de Vida
Desligamento Suave (Graceful Shutdown) — escoamento de tráfego, telemetria ActiveRequests e IsShuttingDown	Desligamento Suave
Multi-Instance — executar e isolar múltiplos servidores HTTP independentes concorrentemente dentro do mesmo processo	Multi-Instance
Pool de Buffers — otimização de memória usando reciclagem de buffers thread-safe para eliminar alocações de heap	Pool de Buffers
Criar e publicar o seu próprio middleware — esqueleto, thread safety, neutralidade de Provider, empacotamento Boss	Criando um Middleware
Escolher um provider de transporte — Indy (padrão), CrossSocket, mORMot2, ICS, HttpSys, gRPC, Apache, ISAPI, CGI, daemons	Providers
Deploy como Console / VCL / Daemon / Serviço Windows / LCL / HTTPApplication — receita de uma página	Cheatsheet de Deploy
Catálogo completo de middlewares com descrições estendidas	Ecossistema de Middlewares
Observabilidade, rastreamento (OpenTelemetry) e coleta de métricas (Prometheus)	Observabilidade e Telemetria
Testes de integração automatizados, resiliência (Access Violation) e limites de Stack	Testes de Integridade
Versões suportadas de Delphi / FPC e plataformas	Suporte de Compilador
Planejamento arquitetural de longo prazo e backlog técnico	Roadmap

Para ajudar seu agente de IA (como Antigravity, GitHub Copilot ou Claude) a entender e escrever código Horse idiomático, thread-safe e livre de vazamento de memória, fornecemos arquivos de instrução pré-empacotados em doc/skills/.

Para utilizá-los:

Copilot / Claude / IAs Customizadas: Mencione os arquivos em doc/skills/ para alimentar o contexto do seu agente.
Antigravity IDE: Adicione o caminho do diretório doc/ do repositório do Horse no arquivo .agents/skills.json do seu projeto para carregar todas as skills automaticamente:
```
{
  "entries": [
    { "path": "caminho/para/horse/doc" }
  ]
}
```
Ou copie as pastas das skills diretamente para o diretório .agents/skills/ do seu projeto.

🔌 Providers (camada de transporte)

Um provider é o transporte HTTP que é dono do socket e entrega requisições aos seus handlers de rota. O mesmo código de handler roda em qualquer provider — você seleciona um em tempo de compilação via uma Conditional Define. O Provider padrão depende do compilador: Indy no Delphi (para Console / VCL / Daemon), fphttpserver no FPC (para Daemon / HTTPApplication / LCL). Os Providers opcionais CrossSocket e mORMot2 substituem ambos por E/S assíncrona IOCP / epoll / kqueue; o Provider opcional ICS (Delphi; Windows + Linux64/macOS) traz a pilha moderna OpenSSL 3.x / 4.x do OverbyteICS — TLS 1.3, SNI, mTLS. O Provider HttpSys (Windows) é nativo do Horse — usa a pilha HTTP em modo kernel http.sys do sistema (a mesma do IIS), sem biblioteca externa.

Provider	Define de compilação	Delphi	Lazarus
Indy (padrão Delphi para self-hosted)	(nenhum)	✔️	n/a
`fphttpserver` (padrão FPC para self-hosted)	(nenhum)	n/a	✔️
🆕 horse-provider-crosssocket	`HORSE_CROSSSOCKET`	✔️	✔️
🆕 horse-provider-mormot	`HORSE_PROVIDER_MORMOT`	✔️	✔️
🆕 horse-provider-ics (Delphi; Win + Linux/macOS)	`HORSE_PROVIDER_ICS`	✔️	❌
🆕 HTTP.sys (driver de modo kernel do Windows para ultra-baixa latência)	`HORSE_PROVIDER_HTTPSYS`	✔️	✔️
🆕 epoll (event loop assíncrono nativo do Linux)	`HORSE_PROVIDER_EPOLL`	✔️	✔️
🆕 horse-provider-ics (Delphi; Win + Linux/macOS)	`HORSE_PROVIDER_ICS`	✔️	❌
🆕 IOCP (portas de conclusão de E/S assíncronas nativas do Windows)	`HORSE_PROVIDER_IOCP`	✔️	✔️

Nota — Os tipos de aplicação Apache / ISAPI / CGI / FastCGI (abaixo) não usam nenhum desses Providers. O processo host (Apache, IIS, o webserver) é dono do socket; o Horse roda in-process. Veja Providers e Tipos de aplicação para o modelo completo.

Instalação do Delphi-Cross-Socket — clone winddriver/Delphi-Cross-Socket (upstream) junto com cnpack/cnvcl/.../Crypto para as units CnPack/Crypto exigidas, e adicione os search paths ao seu projeto. Três correções que antes eram exclusivas do fork já foram incorporadas ao upstream desde o 2º trimestre de 2026, então o mainline do upstream é adequado para uso geral. Para mTLS do lado servidor (SSLVerifyPeer = True + SSLCACertFile = ...) use o release pré-empacotado freitasjca/Delphi-Cross-Socket v1.0.3 — um único clone, CnPack já incluso, APIs de mTLS (SetCACertificateFile + SetVerifyPeer) prontas para uso. Veja Instalação do horse-provider-crosssocket para o detalhamento completo dos dois caminhos.

Instalação do OverbyteICS — o Provider ICS requer o OverbyteICS (v9.x). Instale o ICS seguindo as instruções oficiais do ICS — baixe/clone o ICS e adicione a pasta Source/ ao search path do seu projeto (o ICS não é instalável via Boss). Para TLS, as bibliotecas OpenSSL acompanham o ICS (DLLs no Windows, .so no Linux). O Provider ICS é somente Delphi — Windows e POSIX (Linux64 / macOS) via o pump de mensagens próprio do ICS (Ics.Posix.*) (no Linux use HORSE_APPTYPE_DAEMON + THorseICSLinuxDaemonApp.Run); um port para Lazarus/FPC não é viável — a camada POSIX do ICS usa a RTL POSIX do Delphi e o ICS desativa o OpenSSL no FPC. Seu diferencial é a pilha OpenSSL 3.x / 4.x do ICS (TLS 1.3, SNI, mTLS). Veja horse-provider-ics para configuração, a suíte de testes A–K e limitações conhecidas.

HttpSys — sem instalação: a unit Horse.Provider.HttpSys acompanha o Horse e usa diretamente a httpapi.dll do Windows (http.sys), portanto não há biblioteca externa. Defina HORSE_PROVIDER_HTTPSYS (Windows; Delphi ou Lazarus). Como o http.sys é uma pilha HTTP em modo kernel e de escopo da máquina, vincular um host diferente de localhost ou uma porta privilegiada exige uma reserva de URL única (netsh http add urlacl url=http://+:9000/ user=Everyone) ou direitos de Administrador; o HTTPS usa o repositório de certificados do Windows via netsh http add sslcert. É mutuamente exclusivo com os Providers CrossSocket / mORMot / ICS (um transporte por build).

IOCP — sem instalação: a unit Horse.Provider.IOCP acompanha o Horse e se vincula diretamente às portas de conclusão de E/S (Input/Output Completion Ports) do Windows utilizando a API Winsock2 para altíssimo desempenho e escalabilidade em tipos de aplicação self-hosted no Windows. Defina HORSE_PROVIDER_IOCP (Windows; Delphi ou Lazarus). É mutuamente exclusivo com Indy, HttpSys e outros providers de socket (um transporte por build).

🎯 Tipos de aplicação

Como o binário é empacotado e iniciado. Tipos self-hosted rodam sob o Provider escolhido acima; tipos host-managed delegam o socket ao webserver, que se torna o transporte.

Tipo de aplicação	Define de compilação	Delphi	Lazarus
Self-hosted (usa o Provider selecionado)
Console (padrão)	(nenhum)	✔️	✔️
VCL	`HORSE_VCL`	✔️	❌
Daemon — Serviço Windows	`HORSE_DAEMON`	✔️	n/a
Daemon — daemon Linux (systemd)	`HORSE_DAEMON`	✔️	✔️
LCL (GUI Lazarus)	`HORSE_LCL`	❌	✔️
HTTPApplication (FPC)	(padrão FPC)	❌	✔️
Host-managed (o webserver é dono do socket; Provider acima não é usado)
Módulo Apache	`HORSE_APACHE`	✔️	✔️
ISAPI (IIS)	`HORSE_ISAPI`	✔️	❌
CGI	`HORSE_CGI`	✔️	✔️
FastCGI	`HORSE_FCGI`	✔️	✔️

Nota – HORSE_DAEMON é um tipo de aplicação adaptável à plataforma:

No Windows → compila como um Serviço Windows (Vcl.SvcMgr.TService + SCM)

No Linux → compila como um daemon systemd (utiliza signal(SIGTERM) + systemd)

“Daemon” é o termo nativo do Unix; o Windows não possui um equivalente exato, por isso o mesmo nome da definição é usado em ambas as plataformas.

Veja Providers para a matriz de compatibilidade completa e como combinar Provider × Tipo de aplicação.

🧬 Middlewares oficiais

Para um ecossistema de middlewares mais sustentável, colocamos os middlewares oficiais em repositórios separados:

Middleware	Delphi	Lazarus
horse/json	✔️	✔️
horse/basic-auth	✔️	✔️
horse/cors	✔️	✔️
horse/stream	✔️	✔️
horse/jwt	✔️	✔️
horse/exception	✔️	✔️
horse/logger	✔️	✔️
horse/compression	✔️	✔️

🌱 Middlewares de terceiros

Esta é uma lista de middlewares criados pela comunidade Horse — abra um PR se quiser ver o seu aqui!

Middleware	Delphi	Lazarus
bittencourtthulio/etag	✔️	✔️
bittencourtthulio/paginate	✔️	✔️
bittencourtthulio/cachecontrol	✔️	❌
gabrielbaltazar/gbswagger	✔️	❌
willhubner/socketIO	✔️	❌
dliocode/ratelimit	✔️	❌
dliocode/slowdown	✔️	❌
giorgiobazzo/upload	✔️	❌
dliocode/query	✔️	❌
CarlosHe/healthcheck	✔️	❌
CarlosHe/staticfiles	✔️	❌
CachopaWeb/horse-server-static	✔️	✔️
arvanus/horse-exception-logger	✔️	✔️
claudneysessa/Horse-CSResponsePagination	✔️	❌
claudneysessa/Horse-XSuperObjects	✔️	❌
andre-djsystem/horse-bearer-auth	✔️	✔️
andre-djsystem/horse-manipulate-request	✔️	✔️
andre-djsystem/horse-manipulate-response	✔️	✔️
antoniojmsjr/Horse-IPGeoLocation	✔️	❌
antoniojmsjr/Horse-XMLDoc	✔️	❌
isaquepinheiro/horse-jsonbr	✔️	❌
IagooCesaar/Horse-JsonInterceptor	✔️	❌
dliocode/horse-datalogger	✔️	❌
weslleycapelari/horse-documentation	✔️	❌
weslleycapelari/horse-validator	✔️	❌
regyssilveira/horse-rate-limit	✔️	✔️
regyssilveira/horse-compression-v2	✔️	✔️
regyssilveira/horse-static	✔️	✔️
regyssilveira/horse-dto	✔️	✔️
regyssilveira/horse-rbac	✔️	✔️
regyssilveira/horse-schema-validation	✔️	✔️
regyssilveira/horse-multipart	✔️	✔️
regyssilveira/horse-helmet	✔️	✔️
regyssilveira/horse-ssl-redirect	✔️	✔️
regyssilveira/horse-crud	✔️	✔️
regyssilveira/horse-request-id	✔️	✔️
regyssilveira/horse-sanitize	✔️	✔️

📊 Telemetria

Estes são middlewares focados em observabilidade, métricas e rastreamento de aplicações:

Middleware	Delphi	Lazarus
marcobreveglieri/horse-prometheus-metrics	✔️	❌
regyssilveira/horse-opentelemetry	✔️	✔️
regyssilveira/horse-prometheus	✔️	✔️

🤖 Habilidades de IA (Agent Skills)

Este repositório possui suporte nativo para agentes de inteligência artificial (como Gemini, Claude, ChatGPT e GitHub Copilot) por meio de regras locais e guias de modelagem (skills).

Diretrizes de IA: Veja .agents/AGENTS.md contendo os padrões arquiteturais de injeção de dependência, lifecycle hooks, concorrência e telemetria.
Skills de IA: Veja doc/skills/README.pt-BR.md para a lista completa de habilidades de IA (Agent Skills) e guias de desenvolvimento assistido.