README

pascal-api-infra-faa

Infrastructure for REST APIs on Horse, for Delphi and Free Pascal / Lazarus (FPC 3.2.2+, {$MODE DELPHI}), from one source tree.

It ports the ideas of delphi-api-infra-faa (Delphi only) to both compilers, on top of pascal-common-faa (optional types, clocks, threading), pascal-jsonmapper-faa (JSON ⇄ DTO) and pascal-db-faa (database layer, paging). It is not a drop-in replacement for the Delphi library: DTOs map published properties, because FPC 3.2.2's RTTI sees nothing else.

Version 0.32.1 (see the changelog): the core, the Horse middlewares, OpenAPI, an MCP server (protocol 2026-07-28), W3C trace context, metrics (Prometheus), health endpoints, spans exported to an OpenTelemetry collector (OTLP), opt-in multi-tenancy (docs/multitenancy-design.md), JWT signing keys that rotate by themselves, per tenant, sealed in their store (guide), and refresh tokens used once, a copy that comes back ending its login (guide), ETag/If-Match against lost updates and Idempotency-Key for retried POSTs (guide), the tenant from a public path, signed links, and a package without pascal-db-faa for a client program. The tenant catalog's cache is pascal-common-faa's IPcCache, in memory or shared by every instance through Redis. Observability plan: docs/observability-design.md. See docs/plan.md.

Guides

How to build an API with the library, one topic at a time (configuration, errors, DTOs, authentication, database, observability, OpenAPI, MCP, multi-tenancy...): docs/guide, which lists every guide and when to read it. Start with getting started; to keep your own code on both Delphi and Lazarus/FPC, read your project on both compilers.

The guides say how; the design documents (docs/*-design.md) say why each decision was taken and what was measured.

Contents

A quick look

TErrorHandlerMiddleware.Register(LOnError);            // {"error": ...} + status for any exception
THorse.Use(TLoggerMiddleware.New);                      // one access line per request; X-Request-Id = W3C trace id
THorse.Use(TMetricsMiddleware.New);                     // http.server.request.duration, .active_requests
THorse.Use(TCorsMiddleware.New('https://app.example.com'));
THorse.Use(TJwtMiddleware.New(TAppConfig.Get('JWT_SECRET'), ['/health', '/metrics', '/auth/login']));
THorse.Use('/reports', TRateLimitMiddleware.New(60, 60));

THorse.Get('/cities', GetCities);   // raise ENotFoundException / EValidationException freely;
                                    // answer with TJsonSend.Send(Res, Json) (UTF-8 on both compilers)
TMetricsEndpoint.Register('/metrics');                  // Prometheus scrape
THealthEndpoint.AddCheck('database', LChecks.Database); // a function: Boolean (method on FPC)
THealthEndpoint.Register('/health');                    // /health/live, /health/ready (200 or 503)
TPcTracing.Start(TPcTracingOptions.FromEnvironment('cities-api', '1.0.0', ReadAppConfig),
  TOtlpHttpExporter.FromEnvironment);                   // spans to an OpenTelemetry collector
THorse.Listen(9000);

Documented routes, Swagger UI and MCP tools come from the same declarations:

TRouteDoc.Get('/cities').Summary('List cities').Tag('cities')
  .QueryParams<ICityFind>.ResponsePaged<ICity>(200).Register(GetCities);
TRouteDoc.Serve('/swagger', 'Cities API', '1.0.0');
TMcpEndpoint.Register('/mcp', 'http://127.0.0.1:9000', 'cities-api', '1.0.0');  // after every route

An MCP client (protocol 2026-07-28) then lists list_citie with a JSON Schema of its arguments (state, page, limit, orderBy...) and calls it: the call is a GET /cities?state=SC to the API itself, with the client's token, through every middleware.

On FPC a Horse callback is a plain procedure, so each middleware keeps its settings in the unit: one configuration per process.

Messaging, Redis and IPC

Not in this library: use the sibling libraries, same author and dual-compiler rules, sharing pascal-common-faa with this one. They are the first choice for an API built on pascal-api-infra-faa.

How to add them to an application, minimum versions and short examples: docs/related-libraries.md; using them inside an API (one client per process, spans, a server that is down): docs/guide/messaging.md.

Samples

Samples 01-03 run with one source on Delphi and Lazarus/FPC. On FPC for Windows, samples 02 and 03 need sqlite.org's sqlite3.dll next to the executable (see tools/test_http.sh).

Using it

Add the library's src and its dependencies to the project, each from your single copy (git submodules of your project), never from this repository's external/:

• Delphi: search path with src, pascal-common-faa/src, pascal-common-faa/bridges/jsonmapper, pascal-jsonmapper-faa/src, pascal-db-faa/src; for the middlewares also src/horse and Horse's src.
• Lazarus: require packages/pascal_api_infra_faa.lpk (it requires pascal_common_faa, pascaljsonmapper_pkg and pascal_db_faa); for DTO JSON, also pascal_common_faa_jsonmapper. The middlewares are not in the package (Horse has none): add src/horse and Horse's src to the project's search path; for the Redis key store, src/redis and your pascal-redis-faa. pascal-common-faa 1.29.0 or later (the package compiles PascalApi.Tenancy, whose catalog cache is PascalCommon.Cache; on Delphi, without PascalApi.Tenancy, 1.26.0 is enough). Use Horse 3.3.3 or later: 3.3.2 doesn't compile on FPC 3.2.2 for Windows (fixed upstream in 3.3.3). Tested with 3.3.12.
• A program that talks to an API and has no database (a desktop client): on Lazarus require packages/pascal_api_infra_faa_client.lpk instead (0.31.0; it requires pascal_common_faa and pascaljsonmapper_pkg only): PascalApi.Dto, OpenApi, OrderBy, Text, Config, HttpTypes, HttpTransport (and its fake), Otlp, Version. It is a subset of pascal_api_infra_faa: a project requires one of the two, never both. On Delphi, the search path without pascal-db-faa/src. tests/Deps/ClientNoDb is the check.

Console and service programs on FPC call SetMultiByteConversionCodePage(CP_UTF8) at startup (LCL programs already run in UTF-8); on Unix, put cthreads and cwstring first in the program's uses.

Tests

git submodule update --init
sh tools/test_fpc.sh            # FPC on Windows (lazbuild)
sh tools/test_fpc_docker.sh     # FPC 3.2.2 on Linux, in Docker
sh tools/test_http.sh           # the samples over HTTP (FPC on Windows)
sh tools/test_http_docker.sh    # the same on Linux, in Docker
sh tools/ci-test.sh             # what CI runs

On Delphi, open PascalApi.groupproj and run PascalApi.UnitTests (Win32 and Win64; "Build All" builds only the active platform). Every suite must end with 0 leaks.

License

MIT. See LICENSE.