delphi-replicant

This project was created with the KAI plugin version 1.0.2 inside RAD Studio 13.1, with code generated by GPT-5.5 XHigh.

The cache design is based on the MIT-licensed Replicant source repository by Simon Cropp:

https://github.com/SimonCropp/Replicant

Replicant is a .NET HttpClient disk-cache library. This project ports the core idea to Delphi using the built-in RTL HTTP client stack in System.Net.HttpClient.

Available Functionality

The repository is split into reusable source and a small demo project:

• source\: reusable Delphi cache units.
• projects\console-compare\: Win32 console demo project.

The reusable cache implementation is split into these units:

• source\Replicant.HttpCache.pas: public HTTP cache API.
• source\Replicant.CacheStore.pas: disk storage, metadata, cache lookup, safe filenames, and purge logic.
• source\Replicant.Engine.pas: reusable demo/benchmark wrapper used by the console program.

Implemented cache behavior includes:

• GET response caching to disk.
• Response metadata stored as JSON next to the cached body.
• Expires and Cache-Control: max-age freshness support.
• Cache-Control: no-store and no-cache handling.
• Conditional requests using If-Modified-Since and If-None-Match.
• 304 Not Modified cache reuse.
• Optional stale fallback on HTTP/network errors.
• Optional 404 response caching.
• Retry support for transient status codes: 408, 500, 502, 503, and 504.
• Safe ETag-derived filename tokens instead of raw ETags in file paths.
• Explicit lastAccessUtc metadata for purge ordering instead of relying only on filesystem last-access time.

Basic Usage

Download a URL through the cache and copy the cached body to a target file:

uses
  Replicant.HttpCache,
  System.IOUtils,
  System.SysUtils;

var
  Cache: TReplicantHttpCache;
  CacheDir: string;
  OutputFile: string;
  ResultInfo: TReplicantCacheResult;
begin
  CacheDir := TPath.Combine(ExtractFilePath(ParamStr(0)), 'cache');
  OutputFile := TPath.Combine(CacheDir, 'httpbin.json');

  Cache := TReplicantHttpCache.Create(CacheDir);
  try
    Cache.GetToFile('https://httpbin.org/json', OutputFile, ResultInfo);
    Writeln(Format('HTTP %d from %d', [ResultInfo.StatusCode, Ord(ResultInfo.Source)]));
  finally
    Cache.Free;
  end;
end;

Repeated Timing Demo

Use the engine wrapper to run the same download multiple times:

uses
  Replicant.Engine,
  System.SysUtils;

var
  Run: TReplicantDownloadRun;
  Runs: TReplicantDownloadRunArray;
begin
  Runs := TReplicantEngine.DownloadRepeated(
    ReplicantDefaultSourceUrl,
    TReplicantEngine.DefaultCacheDirectory,
    TReplicantEngine.DefaultOutputFileName);

  for Run in Runs do
    Writeln(Format('Run %d: %d ms (%s, HTTP %d)',
      [Run.RunNumber,
       Run.ElapsedMilliseconds,
       TReplicantEngine.CacheSourceText(Run.ResultInfo.Source),
       Run.ResultInfo.StatusCode]));
end;

Cache Options

Configure retry, stale fallback, and 404 caching:

uses
  Replicant.HttpCache,
  System.IOUtils,
  System.SysUtils;

var
  Cache: TReplicantHttpCache;
  ResultInfo: TReplicantCacheResult;
begin
  Cache := TReplicantHttpCache.Create(TPath.Combine(ExtractFilePath(ParamStr(0)), 'cache'));
  try
    Cache.MaxRetries := 2;
    Cache.Cache404 := True;
    Cache.MinFreshness := 1 / 24; // one hour

    Cache.GetToFile(
      'https://httpbin.org/json',
      TPath.Combine(ExtractFilePath(ParamStr(0)), 'cache\httpbin.json'),
      ResultInfo,
      nil,
      True); // staleIfError
  finally
    Cache.Free;
  end;
end;

Building

The project targets Debug|Win32 by default. Build it in RAD Studio 13.1 or from a configured Delphi command prompt with:

cd projects\console-compare
dcc32 -B -CC -EWin32\Debug -NUWin32\Debug ConsoleCompare.dpr

Run:

Win32\Debug\ConsoleCompare.exe

Expected shape of output:

Run 1: 150 ms (network, HTTP 200)
Run 2: 1 ms (cache, HTTP 200)
Run 3: 10 ms (cache, HTTP 200)
Downloaded https://httpbin.org/json
Saved to ...\cache\httpbin.json

Exact timings depend on network and disk conditions.

---

See the blog article for the prompts used to create this functionality:

• Using Kai Inside RAD Studio to Generate Delphi Projects

---

Part of Continuous Delphi

This tool is part of the Continuous-Delphi ecosystem, dedicated to the long-term success of Delphi applications.

---

Built with Delphi