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 |
| Versioning, release validation, tags, and test dependency lockfiles |
Release Checklist |
| 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:
🔌 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 (ICS V9.x)) 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_PROVIDER_CROSSSOCKET |
✔️ |
✔️ |
| 🆕 horse-provider-mormot |
HORSE_PROVIDER_MORMOT |
✔️ |
✔️ |
| 🆕 horse-provider-ics (Delphi; Windows / ICS V9.x) |
HORSE_PROVIDER_ICS |
✔️ |
❌ |
| 🆕 HTTP.sys (Windows kernel-mode driver for ultra-low latency) |
HORSE_PROVIDER_HTTPSYS |
✔️ |
✔️ |
| 🆕 epoll (Linux-native asynchronous event loop) |
HORSE_PROVIDER_EPOLL |
✔️ |
✔️ |
| 🆕 IOCP (Windows-native asynchronous I/O completion ports) |
HORSE_PROVIDER_IOCP |
✔️ |
✔️ |
| 🆕 horse-provider-nghttp2 (HTTP/2 + gRPC; requires Delphi-nghttp2) |
HORSE_PROVIDER_NGHTTP2 |
✔️ |
✔️ |
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 and Delphi on Windows (Win32/Win64). Install ICS following its official instructions and add Source/ to the search path; ICS is not Boss-installable. ICS V9.x does not support POSIX; ICS V10 requires a provider port and does not imply current Linux/macOS support. With ICS V9.7 defaults (OpenSSL_Resource_Files), OpenSSL DLLs are embedded as resources and extracted on first use to C:\ProgramData\ICS-OpenSSL\<version>\; the service account needs write permission there on first use. If resource loading is disabled, configure and deploy external DLLs according to the ICS documentation. Lazarus/FPC is not supported. See horse-provider-ics for setup, tests and limitations.
Delphi-nghttp2 installation — boss install github.com/freitasjca/horse-provider-nghttp2 pulls the provider and its Delphi-nghttp2 dependency automatically. At runtime, libnghttp2 ≥ 1.59 must be present (dynamic-loaded — no link-time dependency): on Windows, download the prebuilt DLL from the curl for Windows bundle; on Linux, sudo apt install libnghttp2-14; on macOS, brew install nghttp2. For TLS and gRPC, OpenSSL 3.x or 1.1 is auto-detected. FPC 3.2.2 and trunk 3.3.1 are both supported for the HTTP/2 transport; gRPC requires trunk 3.3.1 — build on 3.2.2 with -dHORSE_NGHTTP2_NO_GRPC. See horse-provider-nghttp2 for the full setup guide, TLS/mTLS config, and gRPC samples.
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.
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:
🌱 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!
📊 Telemetry
These are middlewares focused on application observability, metrics, and tracing:
🤖 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
评论