proxy

type ArtifactKind int

type CommitRequest struct {
	// Key is the canonical cache key (and object path under the root).
	Key string
	// Data is the object content to store.
	Data io.Reader
	// Kind classifies the object for freshness policy.
	Kind ArtifactKind
	// ContentType is recorded in the sidecar and used when serving.
	ContentType string
	// Verify, when non-nil, validates the computed SHA-256 before the object is
	// committed; a non-nil error rejects it.
	Verify func(sha256Hex string) error
}

type Doer interface {
	Do(req *http.Request) (*http.Response, error)
}

type Fetcher func(ctx context.Context, up UpstreamRequest) (*http.Response, error)

type FileStore struct {
	// contains filtered or unexported fields
}

type Meta struct {
	Size        int64
	SHA256      string
	FetchedAt   time.Time
	Kind        ArtifactKind
	ContentType string
}

type Mirror interface {
	// Handles reports whether this mirror owns the request path.
	Handles(r *http.Request) bool
	// Route computes the cache key, upstream request, kind, and rewrite/verify hooks.
	Route(r *http.Request) (Route, error)
}

type Options struct {
	// Mirrors are consulted in order; the first whose Handles returns true owns the
	// request.
	Mirrors []Mirror
	// Store is the cache backend.
	Store Store
	// Client performs upstream fetches. Defaults to pkg/http.NewDefaultClient().
	Client Doer
	// MetadataTTL is how long KindMetadata stays fresh. Zero serves metadata as
	// fresh forever (no revalidation).
	MetadataTTL time.Duration
	// StaleWhileRevalidate is the window past MetadataTTL during which stale
	// metadata is served while a background revalidation runs.
	StaleWhileRevalidate time.Duration
	// ReadHeaderTimeout bounds slow-header attacks. Defaults to 30s.
	ReadHeaderTimeout time.Duration
	// TLSCertificate, when set, makes the proxy serve HTTPS with this certificate and
	// the base URL uses the https scheme. Terraform/OpenTofu require provider network
	// mirrors to be https, so the cache always sets this. Nil serves plain HTTP.
	TLSCertificate *tls.Certificate
}

type Route struct {
	// Key is the canonical cache key, which is also the backend object name. Empty
	// for KindPassthrough.
	Key string
	// Kind classifies the object for caching and freshness.
	Kind ArtifactKind
	// Upstream is the single upstream fetch performed on a miss (or always, for
	// passthrough). Ignored when Produce is set.
	Upstream UpstreamRequest
	// Produce, when non-nil, composes the (KindMetadata) response from one or more
	// upstream calls via the provided Fetcher — used when a single Upstream+Rewrite
	// cannot express the translation (e.g. building a provider <version>.json from
	// per-platform registry download calls). Returns the body and its content type.
	Produce func(ctx context.Context, fetch Fetcher, proxyBaseURL string) (body []byte, contentType string, err error)
	// ProduceArtifact, when non-nil, streams a generated KindArtifact body produced by
	// an operation rather than a single upstream HTTP GET (e.g. taring a go-getter
	// resolved module source tree). The returned reader is committed to the cache and
	// closed by the proxy. Takes precedence over Upstream and Produce.
	ProduceArtifact func(ctx context.Context) (body io.ReadCloser, contentType string, err error)
	// Rewrite, when non-nil, post-processes a KindMetadata body before it is cached
	// and served — e.g. rewriting provider download URLs back through the proxy.
	// proxyBaseURL is the proxy's own base URL ("http://127.0.0.1:<port>/").
	Rewrite func(body []byte, proxyBaseURL string) ([]byte, error)
	// Verify, when non-nil, checks artifact integrity before commit. It receives the
	// hex-encoded SHA-256 of the downloaded bytes (sufficient to verify a provider
	// zip's zh: hash). Returning an error rejects the object.
	Verify func(sha256Hex string) error
	// HeaderRewrite, when non-nil on a KindPassthrough route, may modify the upstream
	// response headers before they are written back — e.g. rewriting a module's
	// HTTP-archive X-Terraform-Get to route the archive back through the proxy while
	// leaving git:: sources untouched.
	HeaderRewrite func(h http.Header, proxyBaseURL string)
	// Serve, when non-nil, fully renders the served response from a cached object
	// instead of the default (200 + body). The mirror receives the cached body and the
	// live proxy base URL, so a value cached in a prior run (when the proxy bound a
	// different ephemeral port) is rewritten to the current run's URL at serve time —
	// e.g. a module download resolution caches the upstream source and emits
	// 204 + X-Terraform-Get pointing at the current-run _source route. Invoked on both
	// the hit and post-fill serve paths.
	Serve func(w http.ResponseWriter, body io.Reader, proxyBaseURL string) error
	// ContentType for the served response. Falls back to the upstream Content-Type.
	ContentType string
}

type Server struct {
	// contains filtered or unexported fields
}

type Stats struct {
	// contains filtered or unexported fields
}

type StatsSnapshot struct {
	Hits          int
	Misses        int
	BytesSaved    int64
	ObjectsCached int
	BytesCached   int64
}

type Store interface {
	// Lock returns the per-key file lock (one writer, many readers).
	Lock(key string) cache.FileLock
	// Stat returns metadata for key and whether it exists.
	Stat(key string) (Meta, bool, error)
	// Open returns a reader for the cached object plus its metadata.
	Open(key string) (io.ReadCloser, Meta, error)
	// Commit streams the request data to a temp file (hashing as it goes), runs
	// Verify against the computed SHA-256, then atomically renames it into place and
	// writes the sidecar. A non-nil Verify error rejects the object (nothing is committed).
	Commit(ctx context.Context, req CommitRequest) (Meta, error)
	// Root returns the cache root directory.
	Root() string
}

type UpstreamRequest struct {
	// URL is the absolute upstream URL to fetch.
	URL string
	// Method defaults to GET when empty.
	Method string
	// Header carries mirror-supplied headers (e.g. Accept). The proxy merges
	// credential and User-Agent headers on top, never dropping the Atmos UA.
	Header http.Header
}