OpenParable
Skip to content
← Back to skills

Horse Files Streams

Development
horse-files-streams

Horse Files Streams 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 handling file uploads (multipart), downloads, and stream lifetime management in the Horse framework.

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-files-streams/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/horse-files-streams, 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 Files & Streams

1. File Uploads (Multipart FormData)

When clients upload files via multipart form data, you can retrieve the file as a stream or save it directly to the disk using the THorseCoreParamField helper from Req.ContentFields:

procedure UploadHandler(Req: THorseRequest; Res: THorseResponse; Next: TProc);
var
  LFileField: THorseCoreParamField;
  LStream: TStream;
begin
  // 1. Get the file field
  LFileField := Req.ContentFields.Field('file');
  
  if not Assigned(LFileField) then
    raise EHorseException.New
      .Status(THTTPStatus.BadRequest)
      .Error('No file was uploaded');

  // 2. Save it directly to disk
  LFileField.SaveToFile('C:\uploads\' + LFileField.FieldName);
  
  // 3. Or access the raw TStream
  LStream := LFileField.AsStream;
  // Note: DO NOT free LStream if it is owned by the request lifecycle.
  
  Res.Status(THTTPStatus.OK).Send('File uploaded successfully');
end;

2. File Downloads & Streaming

To send files or custom data streams to the client, use Res.SendFile or Res.Download.

  • SendFile: Sends the file stream to the client (displays inline in the browser if supported).
  • Download: Forces the browser to download the file with the specified filename.
procedure DownloadHandler(Req: THorseRequest; Res: THorseResponse; Next: TProc);
var
  LStream: TStream;
begin
  LStream := TFileStream.Create('C:\data\report.pdf', fmOpenRead or fmShareDenyWrite);
  
  // Sends the stream and instructs the client to download as "report_2026.pdf"
  Res.Status(THTTPStatus.OK).Download(LStream, 'report_2026.pdf');
  
  // CRITICAL MEMORY RULE: DO NOT FREE LStream here.
end;

3. Critical Memory Rule (Stream Ownership)

The THorseResponse object takes ownership of any stream passed into SendFile, Download, or Render.

  • Rule: NEVER call .Free or FreeAndNil on a stream after passing it to Res.SendFile, Res.Download, or Res.Render.
  • Reason: The framework will automatically destroy the stream object once the HTTP response is written to the socket. Freeing it manually in your handler will cause a Double-Free memory corruption (Access Violation) when the response lifecycle terminates.