Engine
The engine (IMARSEngine, implemented by TMARSEngine in MARS.Core.Engine.pas) is the top of the server hierarchy. It owns global configuration, holds the applications, and routes every incoming HTTP request to the right application and resource. You create exactly one engine per process.
Creating the engine
The recommended pattern is a class with a class-constructor (see Your First Server):
uses MARS.Core.Engine, MARS.Core.Engine.Interfaces;
FEngine := TMARSEngine.Create;
FEngine.Parameters.LoadFromIniFile; // Port, BasePath, ThreadPoolSize, ...
FEngine.AddApplication('DefaultApp', '/default', ['Server.Resources.*']);The engine is reference-counted through IMARSEngine; release it by setting your reference to nil.
Configuration via Parameters
Engine settings live in FEngine.Parameters, a name/value store that can be loaded from an .ini file with LoadFromIniFile. Common engine parameters:
| Parameter | Meaning | Typical default |
|---|---|---|
Port | HTTP port | 8080 |
PortSSL | HTTPS port | 0 (disabled) |
ThreadPoolSize | Worker threads | 75 |
BasePath | Engine root path stripped from every URL | /rest |
[Engine]
Port=8080
ThreadPoolSize=75
BasePath=/restYou can read any parameter in code with FEngine.Parameters.ByName('Port').AsInteger, and inject parameters into resources with [EngineParam].
Registering applications
function AddApplication(const AName, ABasePath: string;
const AResources: TArray<string>): IMARSApplication;AName— unique application name (e.g. used byApplicationByName).ABasePath— the URL segment that selects this application (e.g./default).AResources— resource class names or wildcards.'Server.Resources.*'registers every resource declared in matching units; you can also pass fully-qualified class names.
FEngine.AddApplication('DefaultApp', '/default', ['Server.Resources.*']);
FEngine.AddApplication('Admin', '/admin', ['Admin.Resources.*']);Look up applications later with ApplicationByName, ApplicationByBasePath, or iterate them with EnumerateApplications. See Applications.
Request routing
The HTTP host calls Engine.HandleRequest(ARequest, AResponse) for each request. The engine then:
- Parses the URL and strips its
BasePath. - Applies CORS handling if enabled.
- Calls the
BeforeHandleRequesthook (which may pre-handle or abort the request). - Matches the next path segment to an application's base path.
- Calls the
OnGetApplicationhook (optional custom application selection). - Creates a
TMARSActivationand runs the request lifecycle. - Calls the
AfterHandleRequesthook.
You don't call HandleRequest yourself; the host does.
Engine hooks
The engine exposes anonymous-method hooks you assign during ignition.
BeforeHandleRequest
Runs before application matching. Return False (and set Handled) to short-circuit. A common use is skipping favicon.ico and answering CORS pre-flight OPTIONS:
FEngine.BeforeHandleRequest :=
function (const AEngine: IMARSEngine; const AURL: TMARSURL;
const ARequest: IMARSRequest; const AResponse: IMARSResponse;
var Handled: Boolean): Boolean
begin
Result := True;
if SameText(AURL.Document, 'favicon.ico') then
begin
Result := False;
Handled := True;
end;
if FEngine.IsCORSEnabled and SameText(ARequest.Method, 'OPTIONS') then
begin
Handled := True; // answer pre-flight
Result := False;
end;
end;OnGetApplication
Lets you override which application serves a request — useful for multi-tenant routing or a fallback application:
FEngine.OnGetApplication :=
procedure (const AEngine: IMARSEngine; const AURL: TMARSURL;
const ARequest: IMARSRequest; const AResponse: IMARSResponse;
var AApplication: IMARSApplication)
begin
if AApplication = nil then
AApplication := FEngine.ApplicationByName('DefaultApp');
end;AfterHandleRequest
Runs after the activation completes — handy for logging or post-processing.
HTTPS
The self-hosted servers can serve HTTPS directly, without a reverse proxy in front. Port is the HTTP port and PortSSL the HTTPS one; either can be 0 to disable it.
Delphi Cross Socket (TMARShttpServerDCS, Demos/MARSTemplateDCS):
[DefaultEngine]
Port=0
PortSSL=443
DCS.SSL.CertFile=fullchain.pem
DCS.SSL.KeyFile=privkey.pem- The certificate and its private key are PEM files; the certificate file can hold the whole chain (e.g.
fullchain.pemof Let's Encrypt). Relative paths are relative to the folder of the executable. Defaults:localhost.crtandlocalhost.key. - OpenSSL is loaded at run time:
libssl-3-x64.dllandlibcrypto-3-x64.dll(Win64) orlibssl-3.dllandlibcrypto-3.dll(Win32), next to the executable or in thePATH(1.1 works too); on Linux thelibsslpackage of the distribution. - In code:
SSLPort,CertificateFile,PrivateKeyFile, orCertificate/PrivateKeywith the PEM content. A missing certificate or OpenSSL library makesActive := TrueraiseEMARSDCSServerException, with the reason. - HTTP and HTTPS are two DCS servers sharing the same engine (
HttpServer,HttpsServerproperties, for fine tuning).
Indy (TMARShttpServerIndy): Indy.SSL.CertFile, Indy.SSL.KeyFile, Indy.SSL.RootCertFile, Indy.SSL.Version, Indy.SSL.Mode, see the parameters reference. With HTTPS, enable keep-alive too (Indy.KeepAlive=true): without it every request costs a new TLS handshake.
By default the Indy server uses Indy's TIdServerIOHandlerSSLOpenSSL, which needs OpenSSL 1.0.2 (see HTTPS without a proxy).
Another SSL IOHandler for Indy
The Indy server can use any SSL server IOHandler derived from Indy's TIdServerIOHandlerSSLBase (unit IdSSL), i.e. the one of a library bringing OpenSSL 3 to Indy. MARS does not depend on that library: your project uses it and gives MARS a factory that creates and configures the IOHandler.
// Server.Ignition: for every host flavor (console, VCL, FMX, service, daemon)
TMARShttpServerIndy.DefaultSSLIOHandlerFactory :=
function (const AServer: TMARShttpServerIndy): TIdServerIOHandlerSSLBase
var
LIOHandler: TMyOpenSSL3ServerIOHandler; // the class of the library
begin
LIOHandler := TMyOpenSSL3ServerIOHandler.Create(AServer);
// configure it, i.e. from the Indy.SSL.* parameters
LIOHandler.CertificateFile := AServer.Engine.Parameters.ByName('Indy.SSL.CertFile', 'localhost.crt').AsString;
LIOHandler.PrivateKeyFile := AServer.Engine.Parameters.ByName('Indy.SSL.KeyFile', 'localhost.key').AsString;
Result := LIOHandler;
end;How the server chooses the IOHandler when it starts with a PortSSL:
SSLIOHandlerFactory: the factory of that server, if assigned.DefaultSSLIOHandlerFactory: otherwise the class-wide factory, convenient inServer.Ignitionbecause the host flavors create their servers in different places.- Indy's OpenSSL IOHandler: otherwise, configured with the
Indy.SSL.*parameters, as before.
A few rules:
- Configuration: the factory configures its IOHandler; MARS applies the
Indy.SSL.*parameters only to the OpenSSL IOHandler it creates itself. - Ownership: the server owns the IOHandler the factory returns and frees it when it stops; the next start calls the factory again. A factory returning
nilmakesActive := Trueraise. - Your own instance: an IOHandler you assign to the
IOHandlerproperty before starting is used as it is, kept when the server stops and freed by you. SSLIOHandler: theSSLIOHandlerproperty is Indy's OpenSSL IOHandler only; with another IOHandler useIOHandler.- Secure requests:
Request.IsSecureworks with any IOHandler derived from Indy's SSL classes.
Request.IsSecure tells whether the request came in over TLS to this server; the URL of the request (TMARSURL) and the OAuth metadata of MCP use it. Behind a reverse proxy terminating TLS it is False, and the X-Forwarded-Proto header tells the original scheme.
CORS
When CORS is enabled (via parameters such as CORS.Origin, CORS.Methods, CORS.Headers), the engine adds the appropriate Access-Control-* headers. Check FEngine.IsCORSEnabled and handle the OPTIONS pre-flight in BeforeHandleRequest as shown above.
Rate limiting
The engine can limit the requests of each client, before any routing (a client over the limit costs as little as possible, also when it calls paths that do not exist). It is off by default; set the engine parameters:
[DefaultEngine]
; 120 requests per 60 seconds for each client, bursts up to 120
RateLimit.Requests=120
RateLimit.Window=60
; behind a reverse proxy only: the client is the first address of this header
;RateLimit.ClientIPHeader=X-Forwarded-ForThe limit is a token bucket: a client can send RateLimit.Requests requests at once, then one every RateLimit.Window / RateLimit.Requests seconds. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the full limit is back); a request over the limit gets 429 Too Many Requests with Retry-After (seconds).
The client is the remote IP of the connection. Behind a reverse proxy every request comes from the proxy: set RateLimit.ClientIPHeader to the header where the proxy writes the address of the client (X-Forwarded-For, X-Real-IP). Set it only behind a proxy you trust, that overwrites the header: otherwise any client can send its own value and get a new limit at every request.
The counters live in memory, per engine: each server of a farm counts its own requests. For other keys or other limits (per user, per route), use TMARSRateLimiter (MARS.Utils.RateLimiter) in a middleware or in BeforeHandleRequest:
var
GLoginLimiter: TMARSRateLimiter; // created at startup
R.Post('login', ...).Use('login-limit',
procedure (const C: TMARSRouteContext; const ANext: TProc)
begin
// 5 attempts per minute for each client
if GLoginLimiter.Check(C.Request.RemoteIP, 5, 60).Allowed then
ANext()
else
C.Response.StatusCode := 429;
end);Cross-cutting concerns at the engine level
Two facilities are commonly configured during ignition:
- Global activation hooks —
TMARSActivation.RegisterBeforeInvoke/RegisterAfterInvoke/RegisterInvokeErrorapply to every request across all applications. See Request Lifecycle. - Response compression — register an
AfterInvokehook that gzips the response stream when the client sendsAccept-Encoding: gzip:
if FEngine.Parameters.ByName('Compression.Enabled').AsBoolean then
TMARSActivation.RegisterAfterInvoke(
procedure (const AActivation: IMARSActivation)
var LOut: TBytesStream;
begin
if ContainsText(AActivation.Request.GetHeaderParamValue('Accept-Encoding'), 'gzip')
and Assigned(AActivation.Response.ContentStream)
and (AActivation.Response.ContentStream.Size > 0) then
begin
LOut := TBytesStream.Create(nil);
try
AActivation.Response.ContentStream.Position := 0;
ZipStream(AActivation.Response.ContentStream, LOut, 15 + 16);
AActivation.Response.ContentStream.Free;
AActivation.Response.ContentStream := LOut;
AActivation.Response.ContentEncoding := 'gzip';
except
LOut.Free; raise;
end;
end;
end);Next
- Applications — grouping resources and per-app configuration.
- Resources & Methods — defining endpoints.
- Request Lifecycle — what happens inside an activation.
