hcache

Documentation

Overview

Package hcache is a small on-disk cache for registry and advisory HTTP responses. Repeat runs of lockvet re-ask the same registries the same questions (running `lockvet`, then `lockvet -md`, then `lockvet -json` refetches everything three times); caching answers for a short window makes repeat runs fast and stays inside tight anonymous rate limits (hex.pm allows 100 req/min, Bitbucket ~60/hr, npm and PyPI throttle too).

Scope — metadata only, never code under review:

• Cached: OSV.dev and deps.dev answers, and the package-registry documents lockvet reads (npm, PyPI, crates.io, RubyGems, Packagist, NuGet, Hex, Go proxy, pub.dev, CocoaPods, Terraform, Maven, JSR, Conan), plus taglink's git ref advertisements and GitHub release notes.
• Never cached: forge API responses (PR state, compared files, file contents) — those must always be live, or lockvet could vet a stale diff.

Only 200 responses are stored. 404s are part of lockvet's evidence for the ▲ unlisted flag (version absent from its registry) and must be re-proven on every run — a just-published version has to clear the flag immediately, so negative answers are never cached.

Entries expire after the configured TTL (default 1h; `-cache-ttl 0` or `-no-cache` disables). The default window means advisory data can be up to an hour old on repeat runs — comparable to OSV's own propagation latency; pass -no-cache when it matters. Files live under os.UserCacheDir()/lockvet/http (override: LOCKVET_CACHE_DIR), are user-private (0700/0600), and a best-effort background sweep removes entries older than max(24h, 2×TTL).

Index

• Constants
• func Client(timeout time.Duration) *http.Client
• func ClientHTTP1(timeout time.Duration) *http.Client
• func Configure(off bool, d time.Duration)

Constants

const AnonAuthHeader = "X-Lockvet-Anon-Auth"

AnonAuthHeader marks a request whose Authorization header carries an ANONYMOUS, short-lived token for public data (e.g. a Docker registry anonymous pull token): the answer is exactly what any anonymous client would get, so the cache keys the entry as anonymous — otherwise every rotated token would orphan the previous run's entries. The marker is stripped before the request goes on the wire. Never set it on requests carrying user credentials.

const (
	// DefaultTTL is how long a cached answer is served before refetching.
	DefaultTTL = time.Hour
)

Functions

func Client

func Client(timeout time.Duration) *http.Client

Client returns an *http.Client with the given timeout whose GET (and allowlisted POST) responses are served from / stored in the on-disk cache.

func ClientHTTP1

func ClientHTTP1(timeout time.Duration) *http.Client

ClientHTTP1 is Client with HTTP/1.1 forced on the underlying transport. Some CDN fronts (Docker Hub's) challenge Go's HTTP/2 fingerprint while serving the same request fine over HTTP/1.1.

func Configure

func Configure(off bool, d time.Duration)

Configure sets cache behaviour; the CLI calls it once after flag parsing, before any requests. Until then every Client is pass-through. A non-positive ttl disables the cache entirely.