Documentation
¶
Index ¶
- Constants
- type CacheKeyParts
- type Handler
- func (h *Handler) CacheKey(f func(*http.Request) string) *Handler
- func (h *Handler) InternalForward() *Handler
- func (h *Handler) Metrics(strategy, registry string) *Handler
- func (h *Handler) OnError(f func(error, http.ResponseWriter, *http.Request)) *Handler
- func (h *Handler) ParallelFetch(chunkSize int64, concurrency int) *Handler
- func (h *Handler) Revalidate(header string, freshFor func(*http.Request) time.Duration) *Handler
- func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (h *Handler) TTL(f func(*http.Request) time.Duration) *Handler
- func (h *Handler) Transform(f func(*http.Request) (*http.Request, error)) *Handler
- func (h *Handler) Vary(f func(*http.Request) map[string]string) *Handler
- func (h *Handler) Verify(f func(*http.Request) Verifier) *Handler
- type Verifier
Constants ¶
const ( // CacheHit is a response from the cache, including a conditional 304. CacheHit = "hit" // CacheMiss is a response fetched from the upstream for this request. CacheMiss = "miss" // CacheCoalesced is a miss that shared another request's upstream fetch. CacheCoalesced = "coalesced" // CacheError is a cache lookup failure answered with an error. CacheError = "error" )
const CacheResultAttribute = "cachew.cache.result"
CacheResultAttribute labels the request's HTTP server metrics with how the cache answered it, so a strategy's hit ratio can be read in requests and bytes.
const CacheSourceAttribute = "cachew.cache.source"
CacheSourceAttribute labels a cache hit with the backend that served it, such as disk, s3 or remote, so local and shared hits can be told apart.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CacheKeyParts ¶
CacheKeyParts holds the components used to build a cache key. Path is the primary identifier (typically the upstream URL) and Vary captures request-derived dimensions like Accept-Encoding.
func NewCacheKeyParts ¶
func NewCacheKeyParts(path string) CacheKeyParts
func (CacheKeyParts) Key ¶
func (p CacheKeyParts) Key() cache.Key
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler provides a fluent API for creating cache-backed HTTP handlers.
Example usage:
h := handler.New(client, cache).
CacheKey(func(r *http.Request) string {
return "custom-key"
}).
Transform(func(r *http.Request) (*http.Request, error) {
// Modify request before fetching
return modifiedRequest, nil
})
func New ¶
New creates a new Handler with the given HTTP client and cache. Concurrent cache misses for the same key share one upstream fetch through a spool group. All upstream requests of the handler, including requests its transform makes, fallbacks, redirects and parallel chunks, share one 429 cooldown. By default: - Cache key is derived from the request URL - No request transformation is performed - Standard error handling is used.
func (*Handler) CacheKey ¶
CacheKey sets the function used to determine the cache key for a request. The function receives the original incoming request.
func (*Handler) InternalForward ¶ added in v0.8.0
InternalForward excludes delegation to another cache route from external-origin and fill metrics.
func (*Handler) Metrics ¶ added in v0.8.0
Metrics labels requests with a strategy and configured registry; dynamic hosts must use a bounded fallback.
func (*Handler) OnError ¶
OnError sets a custom error handler for the built handler. If not set, a default error handler is used.
func (*Handler) ParallelFetch ¶ added in v0.7.0
ParallelFetch speeds up cold fills of large objects from upstreams that limit throughput per connection. It is opt-in because it multiplies upstream requests and only helps some upstreams. Objects that fit in one chunk cost a single request. Ranges are reassembled in order, so caching, streaming and verification are unaffected.
func (*Handler) Revalidate ¶ added in v0.7.0
Revalidate caches mutable upstream resources without serving them stale indefinitely or refetching unchanged content. Unlike TTL expiry, a stale entry is kept: it is revalidated with a cheap HEAD and served as-is when the upstream is unchanged or unavailable.
header names the response header that identifies the content (e.g. Docker-Content-Digest). It cannot be ETag, which the cache replaces with its own. freshFor returns how long an entry may be served without revalidation; zero marks it as immutable.
func (*Handler) ServeHTTP ¶
func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP implements http.Handler. The handler will: 1. Determine the cache key using the configured function 2. Check if the content exists in cache 3. If cached, stream from cache 4. If not cached, transform the request and fetch from upstream 5. Cache the response while streaming to the client.
HEAD misses are forwarded upstream without caching, so metadata probes never trigger full downloads.
func (*Handler) TTL ¶
TTL sets the function used to determine the cache TTL for a request. The function receives the original incoming request. If not set or returns 0, the cache's default/maximum TTL is used.
func (*Handler) Transform ¶
Transform sets the function used to transform the incoming request before fetching. This is where you can modify the request URL, headers, etc. The function receives the original incoming request and should return the request that will be sent to the upstream server.
func (*Handler) Vary ¶ added in v0.7.0
Vary keys the cache on request headers that change the upstream response, so a variant fetched for one client is never served to a client that asked for another. Accept-Encoding is always included.
Source Files