Horse Files Streams
Developmenthorse-files-streamsHorse 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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
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
.FreeorFreeAndNilon a stream after passing it toRes.SendFile,Res.Download, orRes.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.