strategy

Documentation

Overview

Package strategy provides a framework for implementing and registering different caching strategies.

Index

• Variables
• func Register[Config any, S Strategy](r *Registry, id, description string, factory Factory[Config, S])
• func RegisterAPIV1(r *Registry)
• func RegisterArtifactory(r *Registry)
• func RegisterGitHubReleases(r *Registry, tokenManagerProvider githubapp.TokenManagerProvider)
• func RegisterHTTPProxy(r *Registry)
• func RegisterHermit(r *Registry)
• func RegisterHost(r *Registry)
• type APIV1
  • func NewAPIV1(ctx context.Context, _ struct{}, cache cache.Cache, mux Mux) (*APIV1, error)
  • func (d *APIV1) String() string
• type Artifactory
  • func NewArtifactory(ctx context.Context, config ArtifactoryConfig, cache cache.Cache, mux Mux) (*Artifactory, error)
  • func (a *Artifactory) String() string
• type ArtifactoryConfig
• type Factory
• type GitHubReleases
  • func NewGitHubReleases(ctx context.Context, config GitHubReleasesConfig, cache cache.Cache, mux Mux, ...) (*GitHubReleases, error)
  • func (g *GitHubReleases) String() string
• type GitHubReleasesConfig
• type HTTPProxy
  • func NewHTTPProxy(ctx context.Context, c cache.Cache, _ Mux) (*HTTPProxy, error)
  • func (p *HTTPProxy) Intercept(next http.Handler) http.Handler
  • func (p *HTTPProxy) String() string
• type Hermit
  • func NewHermit(ctx context.Context, config HermitConfig, _ jobscheduler.Scheduler, ...) (*Hermit, error)
  • func (s *Hermit) String() string
• type HermitConfig
• type Host
  • func NewHost(_ context.Context, config HostConfig, cache cache.Cache, mux Mux) (*Host, error)
  • func (d *Host) String() string
• type HostConfig
• type Interceptor
• type Mux
• type ProxyConfig
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) Create(ctx context.Context, name string, config *hcl.Block, c cache.Cache, mux Mux, ...) (Strategy, error)
  • func (r *Registry) Exists(name string) bool
  • func (r *Registry) Schema() *hcl.AST
• type Strategy

Variables

var ErrNotFound = errors.New("strategy not found")

ErrNotFound is returned when a strategy is not found.

Functions

func Register

func Register[Config any, S Strategy](r *Registry, id, description string, factory Factory[Config, S])

Register a new proxy strategy.

func RegisterAPIV1

func RegisterAPIV1(r *Registry)

func RegisterArtifactory

func RegisterArtifactory(r *Registry)

func RegisterGitHubReleases

func RegisterGitHubReleases(r *Registry, tokenManagerProvider githubapp.TokenManagerProvider)

func RegisterHTTPProxy

func RegisterHTTPProxy(r *Registry)

RegisterHTTPProxy registers a caching HTTP proxy strategy. It intercepts absolute-form proxy requests (e.g. from sdkmanager with --proxy_host / --proxy_port) where the client sends:

GET http://dl.google.com/some/path HTTP/1.1

The request URI is upgraded to HTTPS and the response is fetched and cached. Only GET requests are intercepted; other methods are passed through.

func RegisterHermit

func RegisterHermit(r *Registry)

func RegisterHost

func RegisterHost(r *Registry)

Types

type APIV1

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

The APIV1 strategy represents v1 of the proxy API.

func NewAPIV1

func NewAPIV1(ctx context.Context, _ struct{}, cache cache.Cache, mux Mux) (*APIV1, error)

func (*APIV1) String

func (d *APIV1) String() string

type Artifactory

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

The Artifactory Strategy forwards all GET requests to the specified Artifactory instance, caching the response payloads.

Key features: - Sets X-JFrog-Download-Redirect-To header to prevent redirects - Passes through authentication headers - Supports both host-based and path-based routing simultaneously.

func NewArtifactory

func NewArtifactory(ctx context.Context, config ArtifactoryConfig, cache cache.Cache, mux Mux) (*Artifactory, error)

func (*Artifactory) String

func (a *Artifactory) String() string

type ArtifactoryConfig

type ArtifactoryConfig struct {
	Target string   `hcl:"target,label" help:"The target Artifactory URL to proxy requests to."`
	Hosts  []string `hcl:"hosts,optional" help:"List of hostnames to accept for host-based routing. If empty, uses path-based routing only."`
}

ArtifactoryConfig represents the configuration for the Artifactory strategy.

In HCL it looks something like this:

artifactory "https://example.jfrog.io" {
  hosts = ["maven.example.com", "npm.example.com"]
}

When hosts are configured, the strategy supports both host-based routing (clients connect to maven.example.com) and path-based routing (clients connect to /example.jfrog.io). Both modes share the same cache.

type Factory

type Factory[Config any, S Strategy] func(ctx context.Context, config Config, cache cache.Cache, mux Mux) (S, error)

type GitHubReleases

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

The GitHubReleases strategy fetches private (and public) release binaries from GitHub.

func NewGitHubReleases

func NewGitHubReleases(ctx context.Context, config GitHubReleasesConfig, cache cache.Cache, mux Mux, tokenManagerProvider githubapp.TokenManagerProvider) (*GitHubReleases, error)

NewGitHubReleases creates a Strategy that fetches private (and public) release binaries from GitHub.

func (*GitHubReleases) String

func (g *GitHubReleases) String() string

type GitHubReleasesConfig

type GitHubReleasesConfig struct {
	Token       string   `hcl:"token,optional" help:"GitHub token for authentication."`
	PrivateOrgs []string `hcl:"private-orgs" help:"List of private GitHub organisations."`
}

type HTTPProxy

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

HTTPProxy is a caching HTTP proxy strategy that handles standard HTTP proxy requests in absolute form (GET http://host/path HTTP/1.1).

It implements the Interceptor interface rather than registering on the mux directly, so that absolute-form request detection happens before ServeMux route matching. This prevents overlap with more-specific routes such as /api/v1/ or /admin/ when the proxied upstream path happens to match them.

func NewHTTPProxy

func NewHTTPProxy(ctx context.Context, c cache.Cache, _ Mux) (*HTTPProxy, error)

func (*HTTPProxy) Intercept

func (p *HTTPProxy) Intercept(next http.Handler) http.Handler

Intercept returns an http.Handler that intercepts absolute-form GET proxy requests before they reach the ServeMux, delegating all other requests to next. This ensures that a proxied path like /api/v1/... is not accidentally routed to cachew's own API handler.

func (*HTTPProxy) String

func (p *HTTPProxy) String() string

type Hermit

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

Hermit caches Hermit package downloads. Acts as a smart router: GitHub releases redirect to github-releases strategy, all other sources are handled directly.

func NewHermit

func NewHermit(ctx context.Context, config HermitConfig, _ jobscheduler.Scheduler, c cache.Cache, mux Mux) (*Hermit, error)

func (*Hermit) String

func (s *Hermit) String() string

type HermitConfig

type HermitConfig struct {
	GitHubBaseURL string `hcl:"github-base-url" help:"Base URL for GitHub release redirects" default:"http://127.0.0.1:8080/github.com"`
}

type Host

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

The Host Strategy forwards all GET requests to the specified host, caching the response payloads.

func NewHost

func NewHost(_ context.Context, config HostConfig, cache cache.Cache, mux Mux) (*Host, error)

func (*Host) String

func (d *Host) String() string

type HostConfig

type HostConfig struct {
	Target  string            `hcl:"target,label" help:"The target URL to proxy requests to."`
	Headers map[string]string `hcl:"headers,optional" help:"Headers to add to upstream requests."`
}

HostConfig represents the configuration for the Host strategy.

In HCL it looks something like this:

host {
	target = "https://github.com/"
}

In this example, the strategy will be mounted under "/github.com".

type Interceptor

type Interceptor interface {
	Strategy
	// Intercept wraps next, returning a handler that intercepts matching
	// requests and delegates all others to next.
	Intercept(next http.Handler) http.Handler
}

Interceptor is an optional interface a Strategy may implement to intercept incoming HTTP requests before ServeMux route matching. This is necessary for strategies like the HTTP proxy that need to inspect r.RequestURI rather than r.URL.Path — registering a "/" catch-all on the mux is insufficient because more-specific routes (e.g. /api/v1/) still win for overlapping paths.

type Mux

type Mux interface {
	Handle(pattern string, handler http.Handler)
	HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))
}

type ProxyConfig

type ProxyConfig struct{}

ProxyConfig holds configuration for the HTTP proxy strategy. Currently no options are required.

type Registry

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

func NewRegistry

func NewRegistry() *Registry

func (*Registry) Create

func (r *Registry) Create(
	ctx context.Context,
	name string,
	config *hcl.Block,
	c cache.Cache,
	mux Mux,
	vars map[string]string,
) (Strategy, error)

Create a new proxy strategy.

Will return "ErrNotFound" if the strategy is not found.

func (*Registry) Exists

func (r *Registry) Exists(name string) bool

func (*Registry) Schema

func (r *Registry) Schema() *hcl.AST

Schema returns the schema for all registered strategies. Each entry is wrapped as a "strategy <name> { ... }" block.

type Strategy

type Strategy interface {
	String() string
}