Documentation
¶
Overview ¶
Package composerproxy implements proxies.CacheProxy for PHP Composer.
It is a pull-through cache for the Packagist metadata repository and the distribution archives that metadata points at.
INTERCEPTION ¶
Composer honours COMPOSER_REPO_PACKAGIST, so pointing every job container at this proxy is a single env var — no workflow change, and a build off-fleet keeps working because the variable is simply absent.
WHAT IS CACHED ¶
Metadata (packages.json and the per-package p2/<vendor>/<name>.json files) is MUTABLE: a package gains a version on every release. It is cached with a short TTL and then revalidated with a conditional GET, so a release published minutes ago is never invisible for long and an unchanged document costs one 304 — the same treatment the npm and pip proxies give their index documents.
Distribution archives are IMMUTABLE and are the bytes that actually matter. A Packagist dist URL names an exact commit:
https://api.github.com/repos/<vendor>/<pkg>/zipball/<40-char sha>
A given SHA cannot come back with different contents, so archives are cached permanently and never revalidated.
WHY DIST URLS ARE REWRITTEN ¶
This is the difference between a cache that saves seconds and one that saves the download. The previous implementation of this proxy cached metadata only and said so plainly: "distribution zips come from mirrors and GitHub, which this proxy does not front". That leaves Composer taking a few kilobytes of JSON from the LAN and every megabyte of actual code from the WAN, on every job.
So each dist URL in a metadata document is rewritten to this proxy's archive route, exactly as the pip proxy rewrites the file links on a project page. Everything else in the document is left alone: rewriting is done on decoded JSON rather than by string replacement, because a blind substitution would also corrupt homepage/source/support fields that merely look like URLs.
Index ¶
Constants ¶
const ( // DefaultUpstream is the Packagist metadata repository. DefaultUpstream = "https://repo.packagist.org" // DefaultMetadataTTL is how long a metadata document is served before it // is revalidated. Matches the npm/pip index default. DefaultMetadataTTL = 5 * time.Minute // DefaultPort continues the sequence npm 8084, pip 8085, pub 8086, // ghrel 8087. DefaultPort = 8088 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// CacheDir is the on-disk cache root (e.g. <data>/cache/composer).
CacheDir string
// Upstream overrides the Packagist metadata repository.
Upstream string
// ListenAddr is the address to bind and advertise.
ListenAddr string
// MetadataTTL is the revalidation interval for metadata documents.
// Zero takes DefaultMetadataTTL; negative revalidates every request.
MetadataTTL time.Duration
// MaxBytes is the cache disk budget.
MaxBytes int64
// AllowedHosts extends the archive-fetch allowlist.
AllowedHosts []string
// Cleanup wipes the cache on Stop. Default false.
Cleanup bool
Log *slog.Logger
}
Config configures the proxy.
type Proxy ¶
type Proxy struct {
// contains filtered or unexported fields
}
Proxy is the Packagist caching proxy.
Source Files