Skip to content

docs: minimalist readme #464

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ViniAbreu wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs: minimalist readme #464

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
283ce2c
docs: minimalist readme
ViniAbreu Jun 6, 2026
d9b57e5
fix: donate link
ViniAbreu Jun 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 4 additions & 108 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,117 +77,13 @@ The full guide lives in [`doc/`](./doc/index.md) — a small wiki that complemen
| Full middleware catalogue with extended descriptions | [Middleware Ecosystem](./doc/middleware-ecosystem.md) |
| Supported Delphi / FPC versions and platforms | [Compiler Support](./doc/compiler-support.md) |

## 🔌 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.

| 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](https://github.com/freitasjca/horse-provider-crosssocket)** | `HORSE_CROSSSOCKET` |    ✔️ |     ✔️ |
| 🆕 **[horse-provider-mormot](https://github.com/freitasjca/horse-provider-mormot)** | `HORSE_PROVIDER_MORMOT` |    ✔️ |     ✔️ |

> **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](./doc/providers.md) for the full model.

> **Delphi-Cross-Socket installation** — clone [`winddriver/Delphi-Cross-Socket`](https://github.com/winddriver/Delphi-Cross-Socket) (upstream) **plus** [`cnpack/cnvcl/.../Crypto`](https://github.com/cnpack/cnvcl/tree/master/Source/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`](https://github.com/freitasjca/Delphi-Cross-Socket/releases/tag/v1.0.3) — single clone, CnPack bundled, mTLS APIs (`SetCACertificateFile` + `SetVerifyPeer`) ready to use. See [horse-provider-crosssocket Installation](./doc/providers.md#crosssocket-optional) for the full two-path breakdown.

## 🎯 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](./doc/providers.md) _(default)_ | _(none)_ |    ✔️ |     ✔️ |
| [VCL](./doc/providers.md) | `HORSE_VCL` |    ✔️ |     ❌ |
| [Daemon — Windows Service](./doc/providers.md) | `HORSE_DAEMON` |    ✔️ |     n/a |
| [Daemon — Linux daemon (systemd)](./doc/providers.md) | `HORSE_DAEMON` |    ✔️ |     ✔️ |
| [LCL](./doc/providers.md) (Lazarus GUI) | `HORSE_LCL` |    ❌ |     ✔️ |
| [HTTPApplication](./doc/providers.md) (FPC) | _(FPC default)_ |    ❌ |     ✔️ |
| _**Host-managed** (the web server owns the socket; Provider above is unused)_ |
| [Apache module](./doc/providers.md) | `HORSE_APACHE` |    ✔️ |     ✔️ |
| [ISAPI](./doc/providers.md) (IIS) | `HORSE_ISAPI` |    ✔️ |     ❌ |
| [CGI](./doc/providers.md) | `HORSE_CGI` |    ✔️ |     ✔️ |
| [FastCGI](./doc/providers.md) | `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](./doc/providers.md) 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](https://github.com/HashLoad/jhonson) |    ✔️ |     ✔️ |
| [horse/basic-auth](https://github.com/HashLoad/horse-basic-auth) |    ✔️ |     ✔️ |
| [horse/cors](https://github.com/HashLoad/horse-cors) |    ✔️ |     ✔️ |
| [horse/stream](https://github.com/HashLoad/horse-octet-stream) |    ✔️ |     ✔️ |
| [horse/jwt](https://github.com/HashLoad/horse-jwt) |    ✔️ |     ✔️ |
| [horse/exception](https://github.com/HashLoad/handle-exception) |    ✔️ |     ✔️ |
| [horse/logger](https://github.com/HashLoad/horse-logger) |    ✔️ |     ✔️ |
| [horse/compression](https://github.com/HashLoad/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](https://github.com/bittencourtthulio/Horse-ETag) |    ✔️ |     ✔️ |
| [bittencourtthulio/paginate](https://github.com/bittencourtthulio/Horse-Paginate) |    ✔️ |     ✔️ |
| [bittencourtthulio/cachecontrol](https://github.com/bittencourtthulio/horse-cachecontrol) |    ✔️ |     ❌ |
| [gabrielbaltazar/gbswagger](https://github.com/gabrielbaltazar/gbswagger) |    ✔️ |     ❌ |
| [willhubner/socketIO](https://github.com/WillHubner/Horse-SocketIO) |    ✔️ |     ❌ |
| [dliocode/ratelimit](https://github.com/dliocode/horse-ratelimit) |    ✔️ |     ❌ |
| [dliocode/slowdown](https://github.com/dliocode/horse-slowdown) |    ✔️ |     ❌ |
| [giorgiobazzo/upload](https://github.com/giorgiobazzo/horse-upload) |    ✔️ |     ❌ |
| [dliocode/query](https://github.com/dliocode/horse-query) |    ✔️ |     ❌ |
| [CarlosHe/healthcheck](https://github.com/CarlosHe/horse-healthcheck) |    ✔️ |     ❌ |
| [CarlosHe/staticfiles](https://github.com/CarlosHe/horse-staticfiles) |    ✔️ |     ❌ |
| [CachopaWeb/horse-server-static](https://github.com/CachopaWeb/horse-server-static) |    ✔️ |     ✔️ |
| [arvanus/horse-exception-logger](https://github.com/arvanus/horse-exception-logger) |    ✔️ |     ✔️ |
| [claudneysessa/Horse-CSResponsePagination](https://github.com/claudneysessa/Horse-CSResponsePagination) |    ✔️ |     ❌ |
| [claudneysessa/Horse-XSuperObjects](https://github.com/claudneysessa/Horse-XSuperObjects) |    ✔️ |     ❌ |
| [andre-djsystem/horse-bearer-auth](https://github.com/andre-djsystem/horse-bearer-auth) |    ✔️ |     ✔️ |
| [andre-djsystem/horse-manipulate-request](https://github.com/andre-djsystem/horse-manipulate-request) |    ✔️ |     ✔️ |
| [andre-djsystem/horse-manipulate-response](https://github.com/andre-djsystem/horse-manipulate-response) |    ✔️ |     ✔️ |
| [antoniojmsjr/Horse-IPGeoLocation](https://github.com/antoniojmsjr/Horse-IPGeoLocation) |    ✔️ |     ❌ |
| [antoniojmsjr/Horse-XMLDoc](https://github.com/antoniojmsjr/Horse-XMLDoc) |    ✔️ |     ❌ |
| [isaquepinheiro/horse-jsonbr](https://github.com/HashLoad/JSONBr) |    ✔️ |     ❌ |
| [IagooCesaar/Horse-JsonInterceptor](https://github.com/IagooCesaar/Horse-JsonInterceptor) |    ✔️ |     ❌ |
| [dliocode/horse-datalogger](https://github.com/dliocode/horse-datalogger) |    ✔️ |     ❌ |
| [marcobreveglieri/horse-prometheus-metrics](https://github.com/marcobreveglieri/horse-prometheus-metrics) |    ✔️ |     ❌ |
| [weslleycapelari/horse-documentation](https://github.com/weslleycapelari/horse-documentation) |    ✔️ |     ❌ |
| [weslleycapelari/horse-validator](https://github.com/weslleycapelari/horse-validator) |    ✔️ |     ❌ |

## 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](./doc/compiler-support.md).
## Donate
The HashLoad organization develops and supports Horse. In order to grow the community of contributors and users, and
allow the maintainers to devote more time to the projects, [please
donate today](https://opencollective.com/hashload).

## 🤝 Contributing

See [CONTRIBUTING.md](./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

<a href="https://github.com/Hashload/horse/graphs/contributors">
<img src="https://contrib.rocks/image?repo=Hashload/horse" />
</a>

## ⚠️ License

`Horse` is free and open-source software licensed under the [MIT License](https://github.com/HashLoad/horse/blob/master/LICENSE).

## 📐 Tests

![tests](https://github.com/GlerystonMatos/horse/workflows/tests/badge.svg) ![Console Coverage ](https://img.shields.io/badge/console%20coverage-45%25-blue) ![VCL Coverage ](https://img.shields.io/badge/vcl%20coverage-43%25-blue)
Loading