class

AptLarder::Proxy

Inherits Reference / Object

HTTP handler that resolves incoming APT requests to a cache key and an upstream URL, ensures the file is cached, then streams it to the client.

Two URL forms are supported:

  • Proxy mode — the request resource is an absolute URL (GET http://deb.debian.org/…). APT uses this when Acquire::http::Proxy is set.
  • Host-in-path mode — the upstream host is embedded as the first path segment (GET /deb.debian.org/debian/…). Used when sources.list entries are rewritten to point directly at apt-larder.

Immutability heuristic: .deb, .udeb, .ddeb files and paths containing /pool/ or /by-hash/ are cached forever and verified with SHA256 on first serve. All other paths are treated as index files and refreshed after index_ttl minutes using conditional GET.

Constants

Log = ::Log.for("apt-larder.proxy")
USER_AGENT = "apt-larder/#{AptLarder::VERSION}"

Pre-computed at compile time; avoids string interpolation on every download.

Constructors

new(cache : Cache, sf : SingleFlight, max_redirects : Int32, index_ttl : Int32, connect_timeout : Int32, read_timeout : Int32, quiet : Bool = false, remaps : Hash(String, String) = {} of String => String)

Creates a new proxy.

  • cache — cache store shared with the eviction loop
  • sf — single-flight coordinator shared across all concurrent requests
  • index_ttl — minutes before index files are revalidated (0 = always stale)
  • max_redirects — maximum number of upstream redirects to follow
  • connect_timeout / read_timeout — upstream timeouts in seconds
  • quiet — when true, only MISS and ERR are logged
Source

Instance methods

handle(ctx : HTTP::Server::Context) : Nil

Handles a single HTTP request from an APT client.

Rejects CONNECT, non-GET/HEAD methods, path traversal, and unmappable URLs with appropriate 4xx codes. For valid requests, ensures the resource is cached (downloading it if necessary) and streams it to the client. Returns 502 on upstream failure or cache loss.

Source
stats

Returns cumulative counters since the process started.

  • hits — requests served directly from cache
  • misses — requests that triggered an upstream download
  • revalidations — index-file requests answered with 304 Not Modified
  • errors — requests that resulted in a 4xx or 5xx response
  • bytes — total bytes written to clients
  • tunnels — CONNECT tunnels successfully established (HTTPS passthrough)
Source