OpenParable
Skip to content
← Back to skills

Horse Request Response

Development
horse-request-response

Horse Request Response is an Agent Skill for development published in the HashLoad/horse repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Guide to interacting with THorseRequest (body, query, params, headers) and THorseResponse (Send, Status, ContentType).

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/HashLoad/horse/blob/HEAD/doc/skills/horse-request-response/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/horse-request-response, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Horse Request & Response

THorseRequest (Reading Request Data)

The THorseRequest object contains all details of the incoming HTTP request.

  • Body: To read the raw text payload, use Req.Body. If the Jhonson middleware is active, you can read the parsed JSON directly:
    var
      LBody: TJSONObject;
    begin
      LBody := Req.Body<TJSONObject>;
    end;
    
  • Params: For path parameters (defined with :name), use Req.Params.Items['name'] (or Req.Params['name']).
  • Query: For query parameters (e.g., ?page=1&limit=10), use Req.Query.Items['page'] (or Req.Query['page']).
  • Headers: Read request headers using Req.Headers.Items['Authorization'].

Safe Parameter Parsing & Validation (THorseCoreParamField)

Instead of accessing raw string dictionary values (e.g., Req.Params['id']) and converting them manually, always prefer using the .Field() method to obtain a THorseCoreParamField. This provides type-safe conversions and declarative parameter validation:

  • Type Conversion: Convert parameters to the target type without manually calling StrToInt or StrToBool:
    var
      LId: Integer;
      LActive: Boolean;
      LDate: TDateTime;
    begin
      LId := Req.Params.Field('id').AsInteger;
      LActive := Req.Query.Field('active').AsBoolean;
      LDate := Req.Query.Field('since').AsISO8601DateTime;
    end;
    
  • Required Check: Automatically halt execution and return a 400 Bad Request with a custom error message if the parameter is missing:
    var
      LEmail: string;
    begin
      // Automatically raises EHorseException if 'email' query param is empty
      LEmail := Req.Query.Field('email').Required.RequiredMessage('The "email" parameter is required.').AsString;
    end;
    
  • Supported Converters: AsInteger, AsInt64, AsBoolean, AsFloat, AsCurrency, AsDateTime, AsISO8601DateTime, AsStream (for multipart uploads), and AsString.

Cookies Management

Horse provides a provider-agnostic, typed API to read cookies from requests and write them back in responses (RFC 6265 compliant).

  • Reading Cookies: Read incoming cookies safely using the .Field() helper:

    var
      LSessionToken: string;
    begin
      LSessionToken := Req.Cookie.Field('session_token').AsString;
    end;
    
  • Writing Cookies (Set-Cookie): Write response cookies using Res.Cookie and configure properties fluently:

    uses Horse.Core.Cookie;
    
    procedure SetCookieHandler(Req: THorseRequest; Res: THorseResponse; Next: TProc);
    begin
      // Creates, registers, and configures the cookie fluently (XE7 compatible)
      Res.Cookie('session_id', 'xyz789')
        .Path('/')
        .HttpOnly(True)
        .Secure(True)
        .SameSite(TSameSite.ssLax);
    
      Res.Send('Cookie has been set');
    end;
    

THorseResponse (Sending HTTP Responses)

The THorseResponse object is used to build and send the HTTP response back to the client.

  • Send: Returns text or objects. It supports method chaining:
    // Sending simple text with Status 200 (OK)
    Res.Send('Success');
    
    // Setting Status 201 (Created) and sending an object (MUST set status BEFORE calling Send)
    Res.Status(THTTPStatus.Created).Send<TJSONObject>(LJson);
    
  • Status: Set the HTTP status code using integer values or the THTTPStatus enum:
    Res.Status(400); // Bad Request
    Res.Status(THTTPStatus.NoContent);
    
  • ContentType: Set custom content type headers if you are not returning standard JSON:
    Res.ContentType('text/html').Send('<h1>HTML Content</h1>');
    

Structured Error Handling (EHorseException)

To return error responses with custom HTTP statuses and error details, raise EHorseException. The framework captures this exception and formats it as a structured JSON error response:

uses Horse.Exception, Horse.Commons;

procedure GetProduct(Req: THorseRequest; Res: THorseResponse; Next: TProc);
var
  LId: Integer;
  LProduct: TProduct;
begin
  LId := Req.Params.Field('id').AsInteger;
  if LId <= 0 then
    raise EHorseException.New
      .Status(THTTPStatus.BadRequest)
      .Error('Invalid product ID');

  LProduct := FindProduct(LId);
  if not Assigned(LProduct) then
    raise EHorseException.New
      .Status(THTTPStatus.NotFound)
      .Error('Product not found')
      .Code(4041)
      .Detail('The requested product does not exist in our catalog.');

  Res.Send(LProduct);
end;

When EHorseException is raised, it automatically serializes to a clean JSON response containing fields like error, code, and detail.