proxies

type CacheProxy ¶

type CacheProxy interface {
	// Start begins serving the proxy. Returns after the listener is bound.
	Start() error

	// Stop shuts down the proxy and optionally cleans up the cache.
	Stop() error

	// Addr returns the address the proxy is listening on (host:port).
	Addr() string

	// EnvVars returns environment variables to inject into job containers
	// so they use this proxy (e.g., GOPROXY=http://10.88.0.1:8082,direct).
	EnvVars() []string

	// Name returns a human-readable name for logging (e.g., "go", "npm").
	Name() string
}

CacheProxy is a language-specific caching proxy that sits between job containers and an upstream package registry. Implementations handle protocol-specific caching (e.g., Go module proxy, npm registry).

type Mount ¶ added in v0.2.2

type Mount struct {
	// Source is an absolute host path (a directory).
	Source string
	// Destination is the absolute path inside the container.
	Destination string
	// ReadOnly mounts the source read-only. Config material should always
	// be read-only: a job must never be able to rewrite what the next job
	// on this host will read.
	ReadOnly bool
}

Mount is a host→container bind mount a cache proxy needs in every job container. Env vars are enough for toolchains that take their proxy from the environment (Go, rustup); Cargo is not one of them — its source replacement is only read from a config file, never from CARGO_* env vars (verified empirically; see pkg/proxies/cargo). Such proxies generate the file on the host and declare it here.

type MountProvider ¶ added in v0.2.2

type MountProvider interface {
	// Mounts returns the bind mounts to add to every job container spec.
	Mounts() []Mount
}

MountProvider is an OPTIONAL interface a CacheProxy may implement when env vars alone cannot point a toolchain at the proxy. Callers type-assert for it; a proxy that does not implement it needs no mounts.

type Server ¶ added in v0.2.2

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

Server is the HTTP server every cache proxy runs.

It exists because the obvious spelling —

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
err := srv.Shutdown(ctx)

does not reliably stop. Two separate problems:

1. UNREAD CONNECTIONS. Go's http.Transport dials speculatively: under a burst of parallel requests it opens more connections than it ends up using, and the spares land in the client's idle pool having never sent a single byte. On the server side those are ConnState "new" and stay that way. http.Server.Shutdown will not close a "new" connection until it has sat in that state for more than five seconds (net/http's issue-22682 heuristic), so Shutdown busy-polls for the full five seconds and a caller with a five-second deadline gets context.DeadlineExceeded rather than a clean stop. That is exactly the intermittent CI failure this type was written for: "Stop: shutting down cargo proxy: context deadline exceeded" after 5.01s, with a single connection stuck in "new". A connection that has not sent a request has nothing to drain, so Shutdown closes those up front and finishes in microseconds instead.

2. UNBOUNDED HANDLERS. A handler blocked on a slow upstream keeps its connection active, and http.Server.Shutdown neither cancels request contexts nor gives up on its own. Every request context here derives from Context(), so when the grace window closes, cancelling it unblocks the in-flight upstream fetches, and Close() then drops what is left. Shutdown always returns; the daemon never hangs on a wedged proxy.

Shutdown also joins the accept goroutine, so no goroutine outlives it.

func NewServer(name string, ln net.Listener, h http.Handler, log *slog.Logger) *Server

func (s *Server) Addr() net.Addr

func (s *Server) Context() context.Context

func (s *Server) ProbeAddr() string

func (s *Server) Serve()

func (s *Server) Shutdown(grace time.Duration) error