httpcache

httpcache-kit

中文文档

An RFC 7234-compliant HTTP cache handler for Go. Wraps any http.Handler — typically a httputil.ReverseProxy — with memory or disk storage, Cache-Control parsing, conditional revalidation, RFC 7234 invalidation and optional Prometheus metrics.

Evolved from lox/httpcache (MIT).

Features

• RFC 7234 caching: freshness, heuristic expiration, revalidation, Vary
• Invalidation: an unsafe method invalidates the request URI and the URIs named by the response's Location / Content-Location
• Private and shared profiles: a shared cache refuses private responses and strips private headers
• Memory, disk and VFS backends: disk storage goes through vfs-kit
• Bounded: configurable TTL, max size, cleanup interval, LRU eviction
• Observable: optional Prometheus metrics via metrics-kit, debug logging via logger-kit
• Graceful shutdown: background cache writes are tracked and can be awaited

Requirements

• Go 1.27+ (go.mod declares go 1.27.0)
• github.com/prometheus/client_golang for metrics

The v2 module line uses the Fiber v3-compatible logger-kit/v2 and metrics-kit/v2 types exposed by the cache API. Applications still on the v1 kit ecosystem should remain on github.com/soulteary/httpcache-kit v1.

Installation

go get github.com/soulteary/httpcache-kit/v2

Quick Start

Shared cache (reverse proxy)

package main

import (
    "log"
    "net/http"
    "net/http/httputil"

    httpcache "github.com/soulteary/httpcache-kit/v2"
)

func main() {
    proxy := &httputil.ReverseProxy{
        Director: func(r *http.Request) {},
    }

    // NewSharedHandler, not NewHandler: this cache serves more than one user.
    handler := httpcache.NewSharedHandler(httpcache.NewMemoryCache(), proxy)

    log.Print("proxy listening on http://localhost:8080")
    log.Fatal(http.ListenAndServe(":8080", handler))
}

Private cache (single user)

handler := httpcache.NewHandler(httpcache.NewMemoryCache(), upstream)

Disk-backed, with options

cache, err := httpcache.NewDiskCacheWithConfig("/var/cache/myproxy",
    httpcache.DefaultCacheConfig().
        WithMaxSize(2 * 1024 * 1024 * 1024).
        WithTTL(24 * time.Hour).
        WithCleanupInterval(30 * time.Minute))
if err != nil {
    log.Fatal(err)
}
defer cache.Close()

handler := httpcache.NewHandlerWithOptions(cache, proxy, &httpcache.HandlerOptions{
    Logger: myLogger,
})
handler.Shared = true

Shared vs Private

This is the one decision to get right, because the unsafe default is the one a field can be forgotten in.

A shared cache running with Shared: false will serve one user's private response to another. Prefer the constructor over setting the field — a constructor cannot be forgotten.

Backends

httpcache.NewMemoryCache()                              // Cache
httpcache.NewMemoryCacheWithConfig(cfg)                 // ExtendedCache
httpcache.NewDiskCache("/var/cache/x")                  // Cache
httpcache.NewDiskCacheWithConfig("/var/cache/x", cfg)   // ExtendedCache
httpcache.NewVFSCache(fs)                               // Cache
httpcache.NewVFSCacheWithConfig(fs, cfg)                // ExtendedCache

Cache is the minimum the handler needs:

type Cache interface {
    Header(key string) (Header, error)
    Retrieve(key string) (*Resource, error)
    Store(res *Resource, keys ...string) error
    Freshen(res *Resource, keys ...string) error
    Invalidate(keys ...string)
}

ExtendedCache adds management, and is what the *WithConfig constructors return:

type ExtendedCache interface {
    Cache
    Stats() CacheStats
    Cleanup() CleanupResult
    Purge() error
    Close() error
}

stats := cache.Stats()
log.Printf("items=%d bytes=%d hits=%d misses=%d stale=%d",
    stats.ItemCount, stats.TotalSize, stats.HitCount, stats.MissCount, stats.StaleCount)

result := cache.Cleanup()
log.Printf("removed %d items (%d bytes, %d stale markers) in %s",
    result.RemovedItems, result.RemovedBytes, result.RemovedStaleEntries, result.Duration)

Retrieve returns ErrNotFoundInCache for a miss — match it with errors.Is. A *Resource it returns owns a file handle on the disk backend, so close it.

On-disk layout

The disk backend keeps four things under its directory:

body/v1/<hashed-key>      response body
header/v1/<hashed-key>    status line, headers, and the store timestamp
staging/v1/               entries being written, empty when idle
stale-markers.json        invalidation state

An entry is its body plus its header, and the two are published together by rename, so a reader sees the whole previous entry or the whole new one. That holds between goroutines sharing one live cache, and no further:

• The two renames are sequential. A process that exits between them leaves the new body beside the old header, and startup removes the leftover staging file rather than repairing the pair.
• The lock is per-instance. Two caches opened on one directory do not coordinate, and their publications can interleave.

Nothing under staging/v1 is a cache entry: it is never scanned, and whatever an interrupted process left there is removed at startup.

Only body/v1 and header/v1 count toward MaxSize and Stats().TotalSize. The other Stats() fields are independent of these directories — StaleCount tracks stale-markers.json, and HitCount/MissCount are counters.

Configuration

cfg := httpcache.DefaultCacheConfig().
    WithMaxSize(10 * 1024 * 1024 * 1024).
    WithTTL(7 * 24 * time.Hour).
    WithCleanupInterval(1 * time.Hour).
    WithStaleMapTTL(24 * time.Hour).
    Validate()

Validate() clamps negatives to zero and restores StaleMapTTL to its default if it is non-positive. It mutates and returns the same config, so it chains.

Handler options

handler := httpcache.NewHandlerWithOptions(cache, upstream, &httpcache.HandlerOptions{
    Logger:         myLogger,          // *logger.Logger; nil uses the package logger
    StaleMarkerTTL: 7 * 24 * time.Hour,
})

StaleMarkerTTL is how long the handler remembers an invalidation for a Cache that does not track staleness itself. It must be at least as long as that cache retains entries: the marker is the only record that older entries are pre-mutation, so expiring it first republishes them as fresh. Zero means DefaultCacheTTL. A cache that keeps its own record ignores this.

Cache Keys and Vary

A key is derived from the effective request URI and the method:

key := httpcache.NewRequestKey(r)           // from a request
key = httpcache.NewKey("GET", u, r.Header)  // explicitly
key = key.ForMethod("HEAD")                 // the sibling key for another method
key = key.Vary(resp.Header.Get("Vary"), r)  // the variant key
keyString := key.String()

The request's own Content-Location does not affect the key. RFC 7234 uses Content-Location, but the response's, and only for invalidation — letting a request choose its key allows a client to park its response under another URL's key, or read another URL's entry.

Key.String() is injective: the Vary section uses a control-byte separator with each value quoted, and since url.URL.String percent-encodes control bytes while strconv.Quote escapes them, neither side of the boundary can contain the delimiter. Keys without Vary are plain and unchanged.

Invalidation

An unsafe method (POST, PUT, DELETE, PATCH) invalidates, per RFC 7234 section 4.4:

• the effective request URI,
• the URI in the response's Location header,
• the URI in the response's Content-Location header,

for both the GET and HEAD keys. Cross-origin targets are ignored, so a response cannot evict another origin's entries.

Metrics

import metrics "github.com/soulteary/metrics-kit/v2"

registry := metrics.NewRegistry("myproxy")
m := httpcache.NewCacheMetrics(registry)
handler.SetMetrics(m)

// Or register a process-wide default
httpcache.SetDefaultMetrics(m)
m = httpcache.GetDefaultMetrics()

// Feed gauges from a cache's own view
m.UpdateCacheStats(cache.Stats())

CacheMetrics exposes hits, misses, skips, evictions, store and retrieve operations, item count, size in bytes, stale count, cleanup duration, and upstream duration and errors.

Logging

import logger "github.com/soulteary/logger-kit/v2"

httpcache.SetLogger(myLogger)     // package-level logger
httpcache.SetDebugLogging(true)   // verbose cache decisions
on := httpcache.IsDebugLogging()

Response Headers

Cache-Control

cc, err := httpcache.ParseCacheControl("max-age=3600, s-maxage=60, private")
cc, err = httpcache.ParseCacheControlHeaders(resp.Header)

cc.Has("no-store")
value, ok := cc.Get("max-age")
d, err := cc.Duration("max-age")
cc.Add("stale-while-revalidate", "30")
header := cc.String()

Resources

res := httpcache.NewResourceBytes(200, body, header)
res = httpcache.NewResource(200, readSeekCloser, header)

res.Status()
res.Header()
res.Age()
res.Expires()
res.MaxAge(shared)
res.HasExplicitExpiration()
res.HeuristicFreshness()
res.HasValidators()
res.MustValidate(shared)
res.IsStale()
res.MarkStale()
res.LastModified()
res.RemovePrivateHeaders()
res.Via()

Graceful Shutdown

The handler stores responses in the background. Await them before closing the backend, or an in-flight write hits a closed cache:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

if err := handler.Shutdown(ctx); err != nil {
    log.Printf("cache shutdown: %v", err)
}
cache.Close()

httpcache.Writes is a package-level sync.WaitGroup covering every handler's background writes, for tests that need to wait on all of them.

Caveats

• Conditional requests carrying Range are not cached.
• Clock is a package-level variable, swappable in tests.

Upgrade Notes (v2.5.0)

No API was added, removed or changed. The disk backend writes entries differently, and there is a new directory inside the cache directory.

• Entries are published by rename on the disk backend. The previous write opened the target with O_CREATE|O_TRUNC, so new contents were never visible as a unit: on a first store an empty file appeared before any bytes reached it, and on a re-store a perfectly readable entry was emptied for as long as the copy took. Replacing a 128 KiB entry under eight concurrent readers produced 2 misses and 258 reads that saw neither the old nor the new body in full; a watcher caught the header file empty 4543 times across 200 re-stores. A reader sharing the cache now sees the whole previous entry or the whole new one — see the on-disk layout section for the two limits on that, a crash between the two renames and two instances on one directory.
• A body and its header change together. Retrieve opens the body first and reads the header second, so a publish landing between those two steps used to hand back one version's payload with the other's status and headers — a Content-Length or Content-Encoding describing a body that was no longer there. Under load, 148 of 600 retrievals mismatched. Both files are now renamed under one lock that Retrieve holds across both lookups.
• staging/v1 is new inside the cache directory. Entries are written there before being renamed into place. It is outside everything that is scanned, so nothing in it is ever mistaken for an entry, and it is swept at startup — a process killed mid-write leaves a file behind that nothing else would reclaim. If you size, back up or rsync the cache directory, include it; it is empty when the cache is idle.
• Storing costs more, mostly on small entries. Measured per store against v2.4.0: 4 KiB went 193µs → 967µs, 2 MiB went 1.66ms → 2.03ms. Large entries are close to free; the small-entry cost is the extra syscalls against a very short write. Numbers are from a container filesystem and will differ elsewhere.
• Entry files are not fsynced. Rename is what makes publication atomic; durability across a crash is not what a cache needs, and an entry lost that way is a miss. stale-markers.json is still fsynced, because losing invalidation state would republish superseded content.
• Memory and other VFS backends are unchanged. The VFS interface has no rename, so they keep the in-place write. The header-completeness check added in v2.4.0 still turns that window into a miss for them.

Upgrade Notes (v2.2.0)

This release changes which entries are served and how they are keyed. One constructor and one option were added; nothing was removed.

• Invalidation now happens. invalidateResource()'s entire body was a debug log call, so a resource that had been POSTed to, PUT or DELETEd kept being served from cache until its own freshness lifetime expired. It now invalidates the request URI and the same-origin URIs named by the response's Location and Content-Location, for both the GET and HEAD keys. Expect more upstream traffic after unsafe methods — that is the bug being fixed.
• A request's Content-Location no longer selects the cache key. It did, while the upstream request still used the original URL, so a client could park its own response under a different URL's key (shared cache poisoning) or read another URL's entry. If you deliberately relied on that to alias entries, there is no replacement — it was not a feature.
• Key.String() changed for keys with Vary. It joined a raw URL and raw header values with ":" and "::", so a crafted URL could collide with a different URL carrying Vary values. The Vary section now uses a quoted, control-byte-separated encoding. Existing cached entries with Vary will miss once and be re-fetched; keys without Vary are unchanged.
• NewSharedHandler is the constructor for a reverse proxy. Shared defaults to false, which is the correct private-cache profile and the wrong one for a shared cache — and a field can be forgotten in a way a constructor cannot. If you set handler.Shared = true by hand, nothing breaks; new code should use the constructor.
• The disk backend no longer leaks a file handle per Vary lookup. The primary Resource was overwritten without being closed.
• CacheControl.String() no longer emits empty entries. It allocated its key slice with make([]string, len(cc)) and then appended, so the output began with len(cc) empty fields.
• HandlerOptions.StaleMarkerTTL is new. Set it to at least your cache's retention when the cache does not track staleness itself; otherwise an expired marker republishes pre-mutation entries as fresh.

Testing

go test ./...

# With coverage
go test ./... -coverprofile=coverage.out -covermode=atomic
go tool cover -func=coverage.out

References

• RFC 7234 — HTTP/1.1 Caching
• lox/httpcache — the original library (MIT)

License

Apache License 2.0 — see LICENSE. Portions derive from lox/httpcache, MIT licensed.