Skip to content

middleware-ecosystem.md

Latest commit

 

History

History
142 lines (108 loc) · 11.3 KB

middleware-ecosystem.md

File metadata and controls

142 lines (108 loc) · 11.3 KB
Raw

Middleware Ecosystem

Read this in English or Português (BR).

Horse keeps a small core. Almost everything you'd associate with a "web framework" — JSON parsing, CORS, JWT, compression, logging — lives in separate, opt-in middleware packages. This page catalogues the official ones (maintained by HashLoad) and the community list.

For how middleware actually works, see Middleware.

Official middleware (HashLoad/*)

For a more maintainable ecosystem, the official middleware lives in separate repositories rather than the Horse core. Install with Boss:

boss install <repo>
Middleware What it does Delphi Lazarus
horse/jhonson Parses JSON request bodies, serialises JSON responses ✔️ ✔️
horse/basic-auth HTTP Basic authentication ✔️ ✔️
horse/cors Cross-Origin Resource Sharing headers + preflight ✔️ ✔️
horse/stream application/octet-stream body handling ✔️ ✔️
horse/jwt JSON Web Token authentication ✔️ ✔️
horse/exception Convert raised exceptions to consistent JSON error responses ✔️ ✔️
horse/logger Per-request access log ✔️ ✔️
horse/compression gzip / deflate response compression ✔️ ✔️

Typical composition

uses
  Horse,
  Horse.Jhonson,
  Horse.CORS,
  Horse.HandleException,
  Horse.Logger,
  Horse.JWT;

begin
  THorse
    .Use(Horse.HandleException.New)    // outermost — turn errors into clean responses
    .Use(Horse.Logger.New)             // log every request
    .Use(CORS)                         // CORS headers + OPTIONS preflight
    .Use(Jhonson)                      // parse JSON bodies
    .Use(JWT('secret'));               // require a valid token (innermost)

  // routes …

  THorse.Listen(9000);
end.

Registration order matters — see Middleware.

Third-party middleware (community)

These are not maintained by HashLoad but are listed here because they're commonly used. The list grows over time — open a PR against this doc if yours should be here.

Middleware Description Delphi Lazarus
bittencourtthulio/etag ETag generation ✔️ ✔️
bittencourtthulio/paginate List response pagination ✔️ ✔️
bittencourtthulio/cachecontrol Cache-Control response headers ✔️ ❌
gabrielbaltazar/gbswagger Swagger / OpenAPI generation ✔️ ❌
willhubner/socketIO Socket.IO server ✔️ ❌
dliocode/ratelimit Rate limiting ✔️ ❌
dliocode/slowdown Progressive request delay ✔️ ❌
giorgiobazzo/upload File upload helpers ✔️ ❌
dliocode/query Query-string DSL helpers ✔️ ❌
CarlosHe/healthcheck /healthz endpoint ✔️ ❌
CarlosHe/staticfiles Static file serving ✔️ ❌
CachopaWeb/horse-server-static Static file serving (alternative) ✔️ ✔️
arvanus/horse-exception-logger Exception logging ✔️ ✔️
claudneysessa/Horse-CSResponsePagination Response pagination ✔️ ❌
claudneysessa/Horse-XSuperObjects XSuperObject integration ✔️ ❌
andre-djsystem/horse-bearer-auth Bearer-token authentication ✔️ ✔️
andre-djsystem/horse-manipulate-request Request mutation helpers ✔️ ✔️
andre-djsystem/horse-manipulate-response Response mutation helpers ✔️ ✔️
antoniojmsjr/Horse-IPGeoLocation IP geolocation lookup ✔️ ❌
antoniojmsjr/Horse-XMLDoc XML documentation generation ✔️ ❌
isaquepinheiro/horse-jsonbr JSON helpers ✔️ ❌
IagooCesaar/Horse-JsonInterceptor JSON request/response interceptor ✔️ ❌
dliocode/horse-datalogger Structured data logger ✔️ ❌
weslleycapelari/horse-documentation Auto-generated API docs ✔️ ❌
weslleycapelari/horse-validator Request payload validation ✔️ ❌
regyssilveira/horse-rate-limit Rate limiting control with support for multiple backends and storages ✔️ ✔️
regyssilveira/horse-compression-v2 High-performance response compression with Gzip, Deflate, and Brotli support ✔️ ✔️
regyssilveira/horse-static High-performance static file serving with Range, Cache, and SPA Fallback support ✔️ ✔️
regyssilveira/horse-dto Auto-binding and declarative validation middleware ✔️ ✔️
regyssilveira/horse-rbac Role-Based Access Control (RBAC) and scopes middleware ✔️ ✔️
regyssilveira/horse-schema-validation Request payload schema validation middleware ✔️ ✔️
regyssilveira/horse-multipart Multipart/form-data request body parser middleware ✔️ ✔️
regyssilveira/horse-helmet Security headers middleware for HTTP response protection ✔️ ✔️
regyssilveira/horse-ssl-redirect Redirection of insecure HTTP requests to HTTPS with proxy and localhost bypass support ✔️ ✔️
regyssilveira/horse-crud Automatic and dynamic CRUD routes generation middleware for Horse framework from decorated entities ✔️ ✔️
regyssilveira/horse-request-id Request ID (Correlation ID) generation and tracking middleware for the Horse framework ecosystem ✔️ ✔️
regyssilveira/horse-sanitize Middleware to sanitize request parameters from the Horse ecosystem against XSS and harmful injections ✔️ ✔️

Telemetry

These are middlewares focused on application observability, metrics, and tracing:

Middleware Description Delphi Lazarus
marcobreveglieri/horse-prometheus-metrics Prometheus metrics endpoint ✔️ ❌
regyssilveira/horse-opentelemetry OpenTelemetry integration for distributed tracing ✔️ ✔️
regyssilveira/horse-prometheus Prometheus integration for metrics collection ✔️ ✔️

Third-party transport Providers

Beyond middleware, the community has produced alternative transport Providers — the layer Horse uses to own the socket and parse HTTP. This is a separate axis from the middleware list above (see Providers & Application types for the full conceptual model). The actively maintained third-party Providers are:

Provider Description License Repository
horse-provider-crosssocket Async IOCP / epoll / kqueue transport. Replaces the default Indy Provider with Delphi-Cross-Socket. Installation is manual (mirrors mORMot2): clone winddriver/Delphi-Cross-Socket + cnpack/cnvcl and add search paths. Supported alternative for mTLS users or single-dependency convenience: freitasjca/Delphi-Cross-Socket v1.0.3 (bundles CnPack + mTLS APIs). Targets high-concurrency deployments. Activated by HORSE_PROVIDER_CROSSSOCKET. Requires Delphi 10.2+ / FPC 3.2+. Baseline test score: 80 passed / 1 failed (the documented Set-Cookie multi-value Horse-core limitation). MIT freitasjca/horse-provider-crosssocket
horse-provider-mormot Async IOCP / epoll transport. Replaces the default Indy Provider with mORMot2's THttpServer — pure Pascal, no compiled C deps for standard HTTP. Optional swap to THttpApiServer for Windows kernel-mode http.sys. Activated by HORSE_PROVIDER_MORMOT. Compatible with Delphi 7 through 12.3 Athens and FPC 3.2+. Ships cross-product convenience units for Console, VCL, Daemon (Windows TService + POSIX runner), Lazarus LCL, and FPC HTTPApplication. MIT freitasjca/horse-provider-mormot

Both Providers use the same hybrid-interface architecture (IHorseRawRequest / IHorseRawResponse), so every Horse middleware works unchanged under either. The two Provider defines are mutually exclusive — exactly one transport per build.

See Providers & Application types for when to switch off the default Indy transport, the compatibility matrix vs. each Application type, and how to combine the two choices.

Adding your middleware to this list

  1. Publish your package with a Boss-compatible boss.json.
  2. Open a PR against doc/middleware-ecosystem.md adding a row in the appropriate table.
  3. Confirm it compiles on the matrix you're claiming (Delphi / Lazarus).

There's no exclusivity — anyone can publish a Horse-compatible package without coordination.

See also

  • Middleware — the model, how to write your own, registration order.
  • Providers — middleware works across all transports; this is why.