Request-FP

Zero‑memory‑leak, high‑level HTTP client for Free Pascal. Built on top of FPC's HTTP stack with a clean API and zero boilerplate.

❓ Why Request-FP?

Request-FP is a thin, high-level wrapper around the Free Pascal HTTP client. If you like the built-in client but want fewer lines of code and safer lifetimes, this library gives you:

• Less boilerplate with expressive, procedural helpers.
• RAII-style advanced records for automatic cleanup (no leaks).
• A consistent, predictable API for common tasks (headers, params, JSON, multipart).

Use it when you want the power of FPC's HTTP client without the repetitive setup and manual memory management.

✨ Features

• Zero memory leaks: RAII-style advanced records handle cleanup for you.
• High-level API over FPC: Built on the stock Free Pascal HTTP client—no extra runtime deps.
• Stateless or session-based: Http.Get(...) for quick calls, THttpSession for cookies/state.
• Headers, params, JSON, multipart: First-class helpers for common patterns.
• Simple error handling: Exceptions or try-pattern results—your choice.
• Battle-tested: Cross-platform with a comprehensive test suite.

⚡ Getting Started in 30 Seconds

uses Request;
var
  R: TResponse;
begin
  R := Http.Get('https://httpbin.org/get');
  WriteLn(R.Text);
end;

That's it! No manual memory management, no setup headaches.

Usage Styles

Request-FP offers two ways to make HTTP requests:

If you want...	Use this style	Example
The simplest, one-off requests	Stateless API	Http.Get(...)
To keep cookies/headers across calls	Session API	THttpSession

• Start with the stateless API for quick scripts, demos, or simple tools.
• Use the session API if you need to log in, reuse cookies, or make many related requests.

Most users only need the stateless API. The session API is there for advanced needs—use it when you need more control or state.

Note: THttpSession is an advanced record—call Session.Init before using methods like Session.Get(...).

Examples

Simple GET

Response := Http.Get('https://api.example.com/data');
WriteLn(Response.Text);

GET with custom headers and query parameters

Response := Http.Get('https://api.example.com/data',
  [TKeyValue.Create('X-Api-Key', 'my-secret-key')],
  [TKeyValue.Create('search', 'pascal')]);
WriteLn(Response.Text);

POST with data

Response := Http.Post('https://api.example.com/data', 'foo=bar');

POST with custom headers and params

Response := Http.Post('https://api.example.com/data', 'foo=bar',
  [TKeyValue.Create('Authorization', 'Bearer token')],
  [TKeyValue.Create('debug', '1')]);

POST JSON

Response := Http.PostJSON('https://api.example.com/data', '{"foo": "bar"}');

Multipart upload

Response := Http.PostMultipart('https://api.example.com/upload',
  [TKeyValue.Create('field1', 'value1')],
  [TKeyValue.Create('file1', 'myfile.txt')]);

Error handling

try
  Response := Http.Get('https://api.example.com/secure');
except
  on E: ERequestError do
    WriteLn('HTTP Error: ', E.Message);
end;

Try-pattern (no exceptions)

Result := Http.TryGet('https://api.example.com/secure');
if Result.Success then
  WriteLn('Status: ', Result.Response.StatusCode)
else
  WriteLn('Error: ', Result.Error);

Behavior: Try* vs Exceptions

• Procedural methods (Http.Get/Post/...): Raise ERequestError on transport failures (network/SSL) and may still return non-2xx responses (e.g., 404/500) without raising.
• Try-pattern methods (Http.TryGet/TryPost/...): Never raise; return TRequestResult with Success, Response, and Error populated. Non-2xx status codes are treated as successful transports.
• JSON parsing: Accessing Response.JSON on non-JSON content raises ERequestError with a clear "JSON Parse Error" prefix.

Reading response headers

var CT: string;
CT := Response.HeaderValue('Content-Type');
if Pos('application/json', LowerCase(CT)) > 0 then
  WriteLn('Looks like JSON');

🧪 Testing

Request-FP includes a comprehensive test suite that ensures reliability and catches regressions.

First, compile the test suite using Lazarus IDE or lazbuild.

Running Tests

# Navigate to the tests directory
cd tests

# Run all tests
./TestRunner.exe -a --format=plain

# On Linux
./TestRunner -a --format=plain

Test Coverage

• ✅ Comprehensive tests for HTTP methods, headers/params, JSON, multipart, and error handling
• ✅ Cross-platform: Windows and Linux
• ✅ Memory-safe by construction: advanced records manage lifetimes; JSON parse errors raise ERequestError

CI / Network Requirements

• Tests target https://httpbin.org and assume outbound network access.
• Some endpoints can intermittently return 502 from httpbin's upstream. Tests include a minimal 1x retry on 502 to reduce flakiness. No core library behavior is altered by this.

📚 Documentation

Quick References

• 📋 Cheat Sheet - Quick reference for common patterns
• 📖 API Reference - Complete API documentation
• 📖 Session API - Session-based HTTP client guide
• 🔧 Technical Details - Implementation details

Examples

Explore practical examples in the examples/ directory:

• Basic GET - Simple HTTP GET request
• Custom Headers - Headers and query parameters
• Authentication - Basic authentication
• JSON POST - POST requests with JSON
• File Upload - Multipart file uploads
• File Download - Download files
• Error Handling - Robust error handling
• Sessions - Session-based requests

🚀 Installation

1. Clone the repository:

   git clone https://github.com/iwank/request-fp.git
   cd request-fp

2. Add to your project:

   • Copy src/Request.pas and src/Request.Session.pas to your project
   • Add the src directory to your unit search path
   • Include uses Request; in your code

3. Dependencies:

   • Free Pascal 3.2.2+ or Lazarus 4.0+
   • OpenSSL (for HTTPS support)
     • Windows: Install via Chocolatey (choco install openssl), Scoop (scoop install openssl), or download the Win64 OpenSSL installer. Copy libssl-*.dll and libcrypto-*.dll into your executable folder or add their location to PATH.
     • Linux: sudo apt-get install libssl-dev (Ubuntu/Debian) or sudo dnf install openssl-devel (Fedora/RHEL)

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: cd tests && ./TestRunner.exe -a --format=plain
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

📋 Requirements

• Free Pascal 3.2.2+ or Lazarus 4.0+
• OpenSSL libraries (for HTTPS) - see Installation for platform-specific setup
• Windows or Linux (cross-platform)

🔧 Troubleshooting

OpenSSL Errors on Windows

If you encounter OpenSSL initialization errors on Windows (e.g., "OpenSSL initialization failed"), you need to install the OpenSSL DLLs.

IMPORTANT: The DLL architecture (32-bit vs 64-bit) must match your FPC installation:

• fpcupdeluxe defaults to 32-bit FPC (common choice for lower memory footprint and smaller executables)
• If you have 32-bit FPC, you need 32-bit OpenSSL DLLs (no -x64 suffix)
• If you have 64-bit FPC, you need 64-bit OpenSSL DLLs (with -x64 suffix)
• Use examples/ssl_debug to check your executable architecture

Required DLL Files:

FPC automatically tries multiple OpenSSL versions in priority order (newest first):

• 64-bit: libssl-3-x64.dll → libssl-1_1-x64.dll → older versions
• 32-bit: libssl-3.dll → libssl-1_1.dll → older versions

Important: While FPC prefers newer versions, Windows DLL search order may override this. If you have multiple OpenSSL versions installed (e.g., in System32), Windows may load an older version due to Known DLLs registry or search path priority. Use the ssl_debug example to verify which version actually loads.

Install either OpenSSL 3.x (recommended) or 1.1.x:

• OpenSSL 3.x: libssl-3-x64.dll and libcrypto-3-x64.dll (64-bit) or libssl-3.dll / libcrypto-3.dll (32-bit)
• OpenSSL 1.1.x: libssl-1_1-x64.dll and libcrypto-1_1-x64.dll (64-bit) or libssl-1_1.dll / libcrypto-1_1.dll (32-bit)

Installation Options:

1. Via Package Manager (Recommended):

   • Chocolatey: choco install openssl
   • Scoop: scoop install openssl

2. Manual Installation:

   • Download from Shining Light Productions
   • Choose the appropriate installer for your architecture (Win64 or Win32)
   • Install to a location like C:\OpenSSL-Win64\

3. Deploy DLLs:

   • Option A: Copy the DLL files to the same folder as your executable
   • Option B: Add the OpenSSL bin directory to your system PATH environment variable

Verifying Installation:

# Check if OpenSSL DLLs are accessible
where libssl-3-x64.dll
where libcrypto-3-x64.dll

OpenSSL Errors on Linux

If you encounter OpenSSL errors on Linux, install the development libraries:

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install libssl-dev

Fedora/RHEL:

sudo dnf install openssl-devel

Network and Certificate Errors

• Certificate validation failures: Ensure your system's CA certificates are up to date
• Connection timeouts: Check firewall settings and network connectivity
• 502 errors from httpbin: Some test endpoints may intermittently return 502; this is a known httpbin upstream issue and does not indicate a library problem

📄 License

This project is licensed under the MIT License - see the LICENSE.md file for details.

🙏 Acknowledgments

• Free Pascal Dev Team for the Pascal compiler
• Lazarus IDE Team for such an amazing IDE
• The kind and helpful individuals on various online platforms such as:
  • Unofficial Free Pascal discord server
  • Free Pascal & Lazarus forum
  • Tweaking4All Delphi, Lazarus, Free Pascal forum
  • Laz Planet - Blogspot / Laz Planet - GitLab
  • Delphi Basics
• All contributors who have helped improve this project