horse-app-structure

name	horse-app-structure
description	Guide for setting up Horse applications, bootstrap program (.dpr), basic console initialization, and registering modules.

Horse App Structure

Application Bootstrap (.dpr)

A standard Horse application is typically configured as a Delphi Console Application ({$APPTYPE CONSOLE}).

program MyHorseApp;

{$APPTYPE CONSOLE}

uses
  System.SysUtils,
  Horse,
  Horse.Jhonson,
  Horse.CORS;

begin
  // 1. Opt-in for the High-Performance Radix Tree Router (highly recommended)
  THorse.UseRadixRouter;

  // 2. Register Global Middlewares
  THorse
    .Use(CORS)
    .Use(Jhonson);

  // 3. Register Routes / Controllers
  THorse.Get('/ping',
    procedure(Req: THorseRequest; Res: THorseResponse; Next: TProc)
    begin
      Res.Send('pong');
    end);

  // 4. Start Server with Listen Callback (prevents sequential execution blocking)
  THorse.Listen(9000,
    procedure
    begin
      Writeln('Server is running on port ' + THorse.Port.ToString);
    end);
end.

---

Modular Architecture

For production grade projects, keep the .dpr file clean by delegating route definitions to specialized Controller classes:

1. Keep Controllers stateless: Do not store request-specific variables as fields in a controller class unless they are thread-safe.
2. Uses Sequence: Ensure modules containing business services or repository layers are decoupled from the HTTP transport layer (Horse units).

---

Thread-Safe Data Access & Database Connections

Horse is inherently multithreaded (each request runs on a separate worker thread). Accessing a database inside a route handler requires strict thread safety to avoid memory corruption, race conditions, or application crashes (Access Violations):

1. NEVER share connection components globally: Do not put a global or query component in your Controller or DataModule and share it across handlers.