Documentation
¶
Overview ¶
Package pubproxy implements proxies.CacheProxy for the Dart/Flutter ecosystem (pub.dev).
It is a pull-through cache for the two request shapes `dart pub get` and `flutter pub get` make:
GET /api/packages/<name> the version listing — MUTABLE GET /api/archives/<file> a package archive — IMMUTABLE
WHAT IS CACHED AND WHY ¶
Archives are the bytes. A published (package, version) archive on pub.dev is immutable — the version listing ships an archive_sha256 for each one and pub verifies it — so archives are cached permanently and never revalidated.
The version listing is not immutable: it grows on every publish and its "latest" moves. It is cached with a short TTL (default 5 minutes) and then revalidated with a conditional GET, so a package published minutes ago is resolvable and an unchanged listing costs one 304.
WHY THE LISTING IS REWRITTEN ¶
Each entry in a version listing carries an ABSOLUTE archive_url. Left alone, pub would take the listing from the cache and the archives from pub.dev. archive_url is therefore rewritten to this proxy's artifact route; archive_sha256 is untouched and still checked by pub against the bytes we serve.
PUBLISHING IS NOT PROXIED. The publish flow starts at /api/packages/versions/new and continues with a multipart upload; this proxy serves GET and HEAD only, and its routing does not recognise that path at all. Publish from CI against the real pub.dev.
Index ¶
Constants ¶
const ( // DefaultUpstream is the public pub.dev registry. DefaultUpstream = "https://pub.dev" // DefaultListingTTL is how long a cached version listing is served // before revalidation. DefaultListingTTL = 5 * time.Minute )
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/pub).
CacheDir string
// Upstream is the pub server to pull through to.
Upstream string
// ListenAddr is the address to bind and advertise.
ListenAddr string
// ListingTTL is the revalidation interval for version listings. Zero
// takes DefaultListingTTL; negative means "revalidate every request".
ListingTTL time.Duration
// MaxBytes is the cache disk budget.
MaxBytes int64
// AllowedHosts extends the artifact-fetch allowlist.
AllowedHosts []string
// Cleanup wipes the cache on Stop. Default false.
Cleanup bool
Log *slog.Logger
}
Config for the pub caching proxy.
type Proxy ¶
type Proxy struct {
// contains filtered or unexported fields
}
Proxy is the pub.dev caching proxy.
func (*Proxy) EnvVars ¶
EnvVars returns the environment variables to inject into job containers.
PUB_HOSTED_URL is the documented way to point the pub client at a mirror, and both `dart pub` and `flutter pub` honour it. No trailing slash: pub concatenates paths onto it directly.
NOT covered, and documented as such: a dependency declared with an explicit `hosted:` URL in pubspec.yaml, which wins over the environment; git and path dependencies, which never touch a registry; the Flutter SDK's own artifact downloads, which follow FLUTTER_STORAGE_BASE_URL rather than PUB_HOSTED_URL; and authenticated private pub servers.
Source Files