HashLoad/horse
Fast, opinionated, minimalist web framework for Delphi - HashLoad/horse
1.4k stars · 243 forks · Pascal Topics: lazarus, api, delphi, framework, web, rest, restful, freepascal, middlewares, fpc, minimalist, horse, webservices, embarcadero
README
Horse is an Express-inspired web framework for Delphi and Lazarus. Designed to ease things up for fast development in a minimalist way and with high performance.
Read this in English or Português (BR).
⚙️ Installation Installation is done using the boss install command: boss install horse (Optional) Install the Horse Wizard for IDE integration. ⚡️ Quickstart Delphi uses Horse;
begin THorse.Get('/ping', procedure(Req: THorseRequest; Res: THorseResponse) begin Res.Send('pong'); end);
THorse.Listen(9000); end. ⚡️ Quickstart 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. 📖 Documentation The full guide lives in doc/ — a small wiki that complements the quick reference below:
Topic Read
First server, install paths, Delphi/Lazarus setup Getting Started
Defining routes, route params, route groups, query strings Routing
THorseRequest / THorseResponse — body, headers, cookies, sessions, status, streaming Request & Response
Native bi-directional WebSocket connection support (RFC 6455) WebSockets
Native streaming (Web Streams / SSE) connection support Streaming
Using middleware, registration order, the Next proc Middleware
Request lifecycle hooks — onRequest, preParsing, preValidation, onSend, onResponse Lifecycle Hooks
Graceful Shutdown — draining active connections, telemetry ActiveRequests and flag IsShuttingDown Graceful Shutdown
Multi-Instance — running and isolating multiple independent HTTP servers concurrently inside the same process Multi-Instance
Memory Buffer Pool — high-performance thread-safe buffer recycling to eliminate heap allocation Memory Buffer Pool
Writing & publishing your own middleware — skeleton, thread safety, Provider neutrality, Boss packaging Writing a Middleware
Choosing a transport provider — Indy (default), CrossSocket, mORMot2, ICS, HttpSys, gRPC, Apache, ISAPI, CGI, daemons Providers
Deploy as Console / VCL / Daemon / Windows Service / LCL / HTTPApplication — one-page recipe Deployment Cheatsheet
Full middleware catalogue with extended descriptions Middleware Ecosystem
Observability, distributed tracing (OpenTelemetry) and metrics collection (Prometheus) Observability & Telemetry
Automated integration, resilience (Access Violation) and SO limit testing Integrity Testing
Supported Delphi / FPC versions and platforms Compiler Support
Long-term architecture roadmap and technical backlog Roadmap
🤖 AI Coding Skills To help your AI agent (like Antigravity, GitHub Copilot, or Claude) understand and write idiomatic, thread-safe, and memory-safe Horse code, we provide pre-packaged instruction files in doc/skills/. To use them:
Copilot / Claude / Custom AIs: Refer to the files in doc/skills/ to feed context to your agent. Antigravity IDE: Add the path to the doc/ directory of the Horse repository in your local .agents/skills.json file to load all skills automatically: { "entries": [ { "path": "path/to/horse/doc" } ] } Or copy the skill folders directly into your project's .agents/skills/ directory.
🔌 Providers (transport layer) A provider is the HTTP transport that owns the socket and hands requests to your route handlers. The same handler code runs under any provider — you select one at compile time via a Conditional Define. The default Provider depends on the compiler: Indy on Delphi (for Console / VCL / Daemon), fphttpserver on FPC (for Daemon / HTTPApplication / LCL). The optional CrossSocket and mORMot2 Providers replace both with async IOCP / epoll / kqueue I/O; the optional ICS Provider (Delphi; Windows + Linux64/macOS) swaps in OverbyteICS's modern OpenSSL 3.x / 4.x stack — TLS 1.3, SNI, mTLS. The HttpSys Provider (Windows) is built into Horse — it drives the OS's http.sys kernel-mode HTTP stack (the same one IIS uses) with no external library.
Provider Compiler define Delphi Lazarus
Indy (Delphi default for self-hosted) (none) ✔️ n/a
fphttpserver (FPC default for self-hosted) (none) n/a ✔️
🆕 horse-provider-crosssocket HORSE_CROSSSOCKET ✔️ ✔️
🆕 horse-provider-mormot HORSE_PROVIDER_MORMOT ✔️ ✔️
🆕 HTTP.sys (Windows kernel-mode driver for ultra-low latency) HORSE_PROVIDER_HTTPSYS ✔️ ✔️
🆕 epoll (Linux-native asynchronous event loop) HORSE_PROVIDER_EPOLL ✔️ ✔️
🆕 horse-provider-ics (Delphi; Win + Linux/macOS) HORSE_PROVIDER_ICS ✔️ ❌
🆕 IOCP (Windows-native asynchronous I/O completion ports) HORSE_PROVIDER_IOCP ✔️ ✔️
Note — Apache / ISAPI / CGI / FastCGI Application types (below) do not use any of these Providers. The host process (Apache, IIS, the web server) owns the socket; Horse runs in-process. See Providers & Application types for the full model.
Delphi-Cross-Socket installation — clone winddriver/Delphi-Cross-Socket (upstream) plus cnpack/cnvcl/.../Crypto for the required CnPack/Crypto units, and add search paths to your project. Three previously-fork-only bug fixes have been merged into upstream as of 2026-Q2, so the upstream mainline is correct for general use. For server-side mutual TLS (SSLVerifyPeer = True + SSLCACertFile = ...) use the pre-built release freitasjca/Delphi-Cross-Socket v1.0.3 — single clone, CnPack bundled, mTLS APIs (SetCACertificateFile + SetVerifyPeer) ready to use. See horse-provider-crosssocket Installation for the full two-path breakdown.
OverbyteICS installation — the ICS Provider requires OverbyteICS (v9.x). Install ICS following the official ICS instructions — download/clone ICS and add its Source/ folder to your project search path (ICS is not Boss-installable). For TLS, the OpenSSL libraries ship with ICS (DLLs on Windows, .so on Linux). The ICS Provider is Delphi only — Windows and POSIX (Linux64 / macOS) via ICS's own Ics.Posix.* message pump (on Linux use HORSE_APPTYPE_DAEMON + THorseICSLinuxDaemonApp.Run); a Lazarus/FPC port is not viable — ICS's POSIX layer rides the Delphi POSIX RTL and ICS compiles out OpenSSL under FPC. Its distinctive value is ICS's OpenSSL 3.x / 4.x stack (TLS 1.3, SNI, mTLS). See horse-provider-ics for setup, the A–K test suite, and known limitations.
HttpSys — no install: the Horse.Provider.HttpSys unit ships with Horse and binds directly to Windows' httpapi.dll (http.sys), so there's no external library. Set HORSE_PROVIDER_HTTPSYS (Windows; Delphi or Lazarus). Because http.sys is a kernel-mode, machine-wide HTTP stack, binding a non-localhost host or a privileged port needs a one-time URL reservation (netsh http add urlacl url=http://+:9000/ user=Everyone) or Administrator rights; HTTPS uses the Windows certificate store via netsh http add sslcert. It is mutually exclusive with the CrossSocket / mORMot / ICS Providers (one transport per build).
IOCP — no install: the Horse.Provider.IOCP unit ships with Horse and binds directly to Windows' input/output completion ports using Winsock2 API for extremely high performance and scalability on Windows self-hosted application types. Set HORSE_PROVIDER_IOCP (Windows; Delphi or Lazarus). It is mutually exclusive with Indy, HttpSys and other socket providers (one transport per build).
🎯 Application types How the binary is packaged and started. Self-hosted types run under the chosen Provider above; host-managed types delegate the socket to the web server, which then becomes the transport.
Application type Compiler define Delphi Lazarus
Self-hosted (uses the selected Provider)
Console (default) (none) ✔️ ✔️
VCL HORSE_VCL ✔️ ❌
Daemon — Windows Service HORSE_DAEMON ✔️ n/a
Daemon — Linux daemon (systemd) HORSE_DAEMON ✔️ ✔️
LCL (Lazarus GUI) HORSE_LCL ❌ ✔️
HTTPApplication (FPC) (FPC default) ❌ ✔️
Host-managed (the web server owns the socket; Provider above is unused)
Apache module HORSE_APACHE ✔️ ✔️
ISAPI (IIS) HORSE_ISAPI ✔️ ❌
CGI HORSE_CGI ✔️ ✔️
FastCGI HORSE_FCGI ✔️ ✔️
Note – HORSE_DAEMON is a platform‑adaptive application type:
On Windows → compiles as a Windows Service (Vcl.SvcMgr.TService + SCM) On Linux → compiles as a systemd daemon (uses signal(SIGTERM) + systemd)
“Daemon” is the Unix‑native term; Windows has no exact equivalent, so the same define name is used across platforms.
See Providers for the full compatibility matrix and how to combine Provider × Application type. 🧬 Official Middlewares For a more maintainable middleware ecosystem, we've put official middlewares into separate repositories:
Middleware Delphi Lazarus
horse/json ✔️ ✔️
horse/basic-auth ✔️ ✔️
horse/cors ✔️ ✔️
horse/stream ✔️ ✔️
horse/jwt ✔️ ✔️
horse/exception ✔️ ✔️
horse/logger ✔️ ✔️
horse/compression ✔️ ✔️
🌱 Third Party Middlewares This is a list of middlewares that are created by the Horse community, please create a PR if you want to see yours!
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 ✔️ ✔️
📊 Telemetry These are middlewares focused on application observability, metrics, and tracing:
Middleware Delphi Lazarus
marcobreveglieri/horse-prometheus-metrics ✔️ ❌
regyssilveira/horse-opentelemetry ✔️ ✔️
regyssilveira/horse-prometheus ✔️ ✔️
🤖 AI Agent Skills This repository includes native instructions and model skills designed to guide AI agents (such as Gemini, Claude, ChatGPT, and GitHub Copilot) during development.
AI Guidelines: See .agents/AGENTS.md for core architectural rules on dependency injection, lifecycle hooks, concurrency, and telemetry. Agent Skills: See doc/skills/README.md for the complete directory of optimized AI skills and development guides.
Delphi Versions Horse works with 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 and Delphi XE7. For the full platform matrix per provider, see Compiler Support. 🤝 Contributing See CONTRIBUTING.md for how to report bugs, suggest features, and submit code or documentation changes. Bilingual EN / PT-BR docs are kept in sync — when editing one language, edit the other in the same PR. 💻 Code Contributors
⚠️ License Horse is free and open-source software licensed under the MIT License. 📐 Tests