Skip to content

README.pt-BR.md

Latest commit

 

History

History
257 lines (200 loc) · 24.3 KB

README.pt-BR.md

File metadata and controls

257 lines (200 loc) · 24.3 KB
Raw

Horse


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

🤖 AI Coding Skills

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.

Versões do Delphi

O Horse funciona com Delphi 13 Florence, Delphi 12 Athens, Delphi 11 Alexandria, Delphi 10.4 Sydney, Delphi 10.3 Rio, Delphi 10.2 Tokyo, Delphi 10.1 Berlin, Delphi 10 Seattle, Delphi XE8 e Delphi XE7.

Para a matriz completa de plataformas por provider, veja Suporte de Compilador.

🤝 Contribuindo

Veja CONTRIBUTING.pt-BR.md para reportar bugs, sugerir features e enviar mudanças de código ou documentação. Os docs bilíngues EN / PT-BR são mantidos sincronizados — ao editar um idioma, edite o outro no mesmo PR.

💻 Contribuidores

⚠️ Licença

O Horse é software livre e de código aberto, licenciado sob a Licença MIT.

📐 Testes

tests Console Coverage VCL Coverage