Skip to content

index.md

Latest commit

 

History

History
94 lines (76 loc) · 7 KB

index.md

File metadata and controls

94 lines (76 loc) · 7 KB
Raw

Horse Documentation

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

Welcome. This is the documentation hub for Horse — an Express-inspired web framework for Delphi and Lazarus.

If you're new, start with Getting Started. If you have a working server and want to make a specific change, jump straight to the relevant topic below.

Middleware Execution Flow

When an HTTP request reaches the Horse server, it flows through the middleware layers in the following precedence order:

graph TD
    A[HTTP Request] --> B[Global Middlewares<br>ex: CORS, Johnson]
    B --> C{Belongs to a Group?}
    C -- Yes --> D[Group Middlewares<br>ex: Restricted Auth]
    C -- No --> E{Has Route-level Middlewares?}
    D --> E
    E -- Yes --> F[Route-level Middlewares<br>ex: Logs, Custom Checks]
    E -- No --> G[Final Route Handler<br>Executes logic]
    F --> G
    G --> H[HTTP Response]
Loading

Reading order for newcomers

  1. Getting Started — install, write a hello-world server, run it.
  2. Routing — declare endpoints, path parameters, route groups, query strings.
  3. Request & Response — read the request, write the response, headers, cookies, sessions, file uploads/downloads.
  4. Middleware — chain handlers, registration order, write your own. For publishing reusable middleware, see Writing a Middleware.
  5. Providers & Application types — pick the transport Provider (Indy default; CrossSocket, mORMot2, and ICS optional; HttpSys, epoll and IOCP built-in) and the Application type (Console default, VCL, Daemon, LCL, HTTPApplication) — or a host-managed application type (Apache, ISAPI, CGI, FastCGI).

Reference

Document What you'll find
Getting Started Install via Boss; minimal Delphi and Lazarus examples; project structure conventions.
Routing THorse.Get / Post / Put / Delete / Patch / Head / Use; path params; route groups; wildcards; HTTP method enum.
Request & Response THorseRequest (body, params, query, headers, cookies, sessions, multipart). THorseResponse (Send, Status, ContentType, AddHeader, RedirectTo, SendFile, Download, RawWebResponse).
WebSockets Native bi-directional WebSocket connection support (RFC 6455) with shared port, fail-fast detection, and broadcasts.
Middleware The Next proc model; built-in vs custom; registration order; per-route vs global.
Lifecycle Hooks Request lifecycle hooks (onRequest, preParsing, preValidation, onSend, onResponse) to extend and intercept request/response pipelines.
Dependency Injection Lifecycle management and IoC on request scope (direct and lazy injectors).
Graceful Shutdown Coordinated connection shutdown in production environments (cloud/Kubernetes); telemetry properties ActiveRequests and flag IsShuttingDown.
Multi-Instance Run and isolate multiple independent HTTP servers, routing tables, and middlewares on different ports concurrently within the same process.
Memory Buffer Pool High-performance memory optimization using thread-safe buffer recycling to eliminate heap allocation.
Writing a Middleware Authoring a production-quality middleware: skeleton, configuration patterns, thread safety, Provider-neutral coding, cross-compiler pitfalls, testing matrix, Boss packaging, publishing.
Providers & Application types The two-axis model: Provider (transport — Indy default; CrossSocket, mORMot2, ICS optional; HttpSys, epoll and IOCP built-in) × Application type (Console / VCL / Daemon / LCL / HTTPApplication, plus host-managed Apache / ISAPI / CGI / FCGI). Compatibility matrix and selection guidance.
Middleware Ecosystem Official HashLoad/* packages and the community-maintained list.
Observability & Telemetry Setting up distributed tracing (OpenTelemetry) and metrics collection (Prometheus).
Compiler Support Tested Delphi releases, FPC versions, target platforms, compiler-version guards.
Deployment Cheatsheet One-page reference for shipping a CrossSocket or mORMot2 binary as any of the seven Application shapes (Console / VCL / Daemon / Windows Service / FPC daemon / LCL / FPC HTTPApplication).
Integrity Testing Automated integration, resilience (Access Violation) and SO limit testing.

How the docs are organised

README.md                      ← landing page; one-paragraph intro and links here
doc/
├── index.md                   ← this file
├── getting-started.md         ← first 30 minutes with Horse
├── routing.md                 ← URL → handler binding
├── request-response.md        ← THorseRequest and THorseResponse API
├── websocket.md               ← native WebSocket connection support (RFC 6455)
├── streaming.md               ← native streaming transmission support (Web Streams / SSE)
├── middleware.md              ← chaining handlers
├── lifecycle-hooks.md         ← request lifecycle hooks (onRequest, etc.)
├── dependency-injection.md    ← contextual dependency injection on request scope
├── graceful-shutdown.md       ← graceful connection shutdown in production
├── multi-instance.md          ← running multiple concurrent servers
├── memory-buffer-pool.md      ← memory buffer pooling and recycling
├── providers.md               ← choosing a transport
├── iocp.md                    ← Windows async I/O completion ports
├── epoll.md                   ← Linux async event loop
├── telemetry.md               ← OpenTelemetry & Prometheus integration
├── middleware-ecosystem.md    ← package catalogue
├── integrity-testing.md       ← integrity and resilience testing
└── compiler-support.md        ← versions / platforms

Each document is self-contained and cross-links to the others where relevant. There is no required reading order beyond the newcomer flow above.

Contributing to the docs

Edits welcome — open a PR against master modifying the relevant file under doc/. Keep each page focused on one topic; if a section grows beyond a few hundred lines, split it into a sibling document and link from index.md.

Got stuck?

  • Telegram channel: @hashload
  • GitHub Issues: HashLoad/horse/issues
  • Source code is short and readable — when in doubt, Horse.pas, Horse.Request.pas, and Horse.Response.pas together total under 2 000 lines.