httpcache

package module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

README

httpcache

Go Reference Go version

httpcache makes your Go client's repeated GET requests cost less: when the server answers 304 Not Modified, the answer comes from memory.

It replaces the hand-written ETag bookkeeping a polling client keeps beside its requests. It needs Go 1.27 or later, depends only on the httpclient module, and is licensed under Apache-2.0.

Why use it

httpcache is built for clients that read the same resources again and again, such as a poller of a rate-limited API.

  • It never serves an answer on age. Every read reaches the server, and only the server's 304 in the same exchange serves the held copy, so a read never returns an answer the server has changed.
  • Its key includes a digest of the request's Authorization lines, so requests with different credentials never share an answer, and the credential itself is never held.
  • It holds at most 32 MiB by default and evicts the least recently used answer, and one answer may take at most a quarter of the bound.
  • A round tripper between the cache and the wire that changes a request or an answer cannot make the cache serve the wrong copy.

Consider bartventer/httpcache if you want answers served on age from Cache-Control freshness under RFC 9111, or a disk-backed store.

Install

go get github.com/cplieger/go/httpcache@latest

Usage

cache := httpcache.NewRoundTripper(nil, httpcache.Config{})
client := &http.Client{Transport: cache, Timeout: 30 * time.Second}

To retry as well, put httpclient's RetryRoundTripper beneath the cache, as its next. ExampleNewRoundTripper on pkg.go.dev is runnable, and go test keeps it true.

API

  • On a client: NewRoundTripper and the RoundTripper it returns, configured by Config with its HeldField entries, reporting a State.
  • For code that reads its own answers: New returns a Cache, whose Begin returns one Read configured by ReadConfig, sent through a Guard.

The full reference is on pkg.go.dev.

Documentation

  • Revalidation cache covers what is kept, when a 304 serves it, the key, the bound and the owner-read API.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md.

Disclaimer

This project is built with care and follows security best practices, but it is intended for personal / self-hosted use. No guarantees of fitness for production environments. Use at your own risk.

This project was built with AI-assisted tooling using Claude, GPT, and Kiro. The human maintainer defines architecture, supervises implementation, and makes all final decisions.

License

Apache-2.0. See LICENSE.

Documentation

Overview

Package httpcache is an in-memory revalidation cache for HTTP GET requests. It keeps earlier answers and replays each one's validator (If-None-Match or If-Modified-Since), and serves a held answer only when the server answers 304 Not Modified in the same exchange. Nothing is served on age.

NewRoundTripper puts the cache beneath any net/http.Client. New with Cache.Begin is the same cache for code that sends, reads and decodes its own answers, sent through a Guard. Retries are not this package's job: put github.com/cplieger/go/httpclient's RetryRoundTripper beneath the cache.

docs/caching.md holds the full contract: what is kept, when a 304 serves it, the key and the memory bound.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Guard

func Guard(next http.RoundTripper) http.RoundTripper

Guard is the round tripper a Cache.Begin read is sent through, beneath every round tripper that may change a request or an answer. A request that differs from the one prepare keyed leaves without validators, and an answer it did not get from next as next gave it, or that reports another request, is neither served nor kept. A read that reaches no guard is never served or kept. A RoundTripper guards its own next; do not put another guard inside it. Nil next means http.DefaultTransport.

Types

type Cache

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

Cache is a byte-bounded, in-memory revalidation cache for an owner that sends, reads and decodes its own answers through Cache.Begin. It is safe for concurrent use. A held answer is served only where the server answers its validator with 304 Not Modified in the same exchange; nothing is served on age. The zero Cache holds nothing and every read passes through it; build one with New to hold answers.

func New

func New(cfg Config) *Cache

New builds a Cache from cfg.

func (*Cache) Begin

func (c *Cache) Begin(cfg ReadConfig) *Read

Begin starts one read.

func (*Cache) Clear

func (c *Cache) Clear()

Clear empties the cache; a read begun before it keeps nothing and its 304 is not served.

func (*Cache) State

func (c *Cache) State() State

State is what the cache has done since it was built, and what it holds now.

type Config

type Config struct {
	// Held are the response header fields the owner reads from a served answer.
	// A name is matched canonically; a name given twice is held once, required
	// if either entry is.
	Held []HeldField
	// MaxBytes bounds what the cache holds, evicting the least recently used
	// entry first. Zero means 32 MiB. A negative value holds nothing and adds no
	// validator, though a 304 is still sent once more without one.
	MaxBytes int64
	// FreeNotModified says the server bills nothing for a 304 answering a
	// conditional request that carries an Authorization header, as GitHub's REST
	// API does. It decides only what State.Saved counts.
	FreeNotModified bool
}

Config configures a Cache or a RoundTripper. The zero value is ready to use: 32 MiB, no held fields, and Saved counts nothing.

type HeldField

type HeldField struct {
	Name     string
	Required bool
}

HeldField is one response header field a served answer carries from the held copy. A field the 304 carries takes the 304's lines; one it omits keeps the held lines, which the 304 did not confirm. Where Required is set and the 304 omits a field the entry holds, the held copy is not served and the read is sent once more without a validator.

type Read

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

Read is one read through a Cache, begun by Cache.Begin. It is not safe for concurrent use.

func (*Read) Answered

func (r *Read) Answered() bool

Answered records that the owner read the answer Send returned in full, and reports whether State counts this read, as a hit or a miss.

func (*Read) Finish

func (r *Read) Finish(ctx context.Context, ok bool) (hit bool, err error)

Finish settles the read once, whether it succeeded (ok) or not. A context ended by then fails the read, which keeps nothing, and its error is returned. hit reports whether the held answer served the read. A second call changes nothing and returns the first's result.

func (*Read) Keep

func (r *Read) Keep(resp *http.Response, body []byte, kept func() ([]byte, error))

Keep keeps what kept returns for resp, a 200 the owner read in full as body, where the wire vouches for resp, body is the wire's body byte for byte, the answer carries a well-formed validator and no no-store, and kept succeeds. It keeps nothing otherwise, so nothing is kept from a body a round tripper above the guard replaced.

func (*Read) Send

func (r *Read) Send(send func(prepare func(*http.Request) *http.Request) (*http.Response, error)) (*http.Response, error)

Send runs the read's attempts through send: the first, and with Resend the one a 304 nothing held may serve forces. send builds the request, calls prepare on it after every other header is set, and sends what prepare returns, beneath a Guard. prepare keys the request and, on the first attempt, sets the held entry's validator. Send answers the last attempt's response and error as send returned them, a refused redirect's response beside its error included; a 304 whose body fails to read, with Resend unset or on the resend, fails with that read's error. A read is sent once; a second Send sends nothing and fails.

func (*Read) Serve

func (r *Read) Serve(live http.Header) (header http.Header, body []byte, ok bool)

Serve answers a 304 the held copy serves: the 304's header with each held field it omits, a copy of the held body, and ok. ok is false for any other answer, a 304 the cache refused included, which the owner treats as the 304 it is. A served 304 carrying no-store forgets the entry once the read finishes.

type ReadConfig

type ReadConfig struct {
	// Discarded takes the header of an answer the read drops: a resent 304's,
	// and a 304 that fails the read. Nil ignores them.
	Discarded func(http.Header)
	// Variant names what the owner keeps of an answer, such as the Go type it
	// decodes into. Reads that differ only in Variant never serve each other.
	Variant string
	// Store looks the read up and keeps its answer, for a GET only: a request
	// sent by another method is neither looked up nor kept. It is false on a
	// cache that holds nothing.
	Store bool
	// Resend sends a 304 nothing held may serve once more without a validator.
	Resend bool
}

ReadConfig is what one read begins with.

type RoundTripper

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

RoundTripper is an http.RoundTripper that revalidates the GET requests it carries, with a Cache of its own. A served answer reaches the caller as a 200 with the held body, the 304's headers but its Content-Length and Content-Encoding, and the held fields. It is safe for concurrent use. The zero RoundTripper is not usable; build one with NewRoundTripper.

func NewRoundTripper

func NewRoundTripper(next http.RoundTripper, cfg Config) *RoundTripper

NewRoundTripper builds a RoundTripper sending through next, which an attempt observer wraps to see each request that reaches the server. An answer from next is served from or kept only where its Request reports the request next was given, as http.Transport does, with its method, URL, host and every header unchanged, so a round tripper that sets a credential or any other header wraps the RoundTripper instead. Nil next means http.DefaultTransport.

Example
package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"
	"time"

	"github.com/cplieger/go/httpcache"
)

func main() {
	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if r.Header.Get("If-None-Match") == `"v1"` {
			w.WriteHeader(http.StatusNotModified)
			return
		}
		w.Header().Set("ETag", `"v1"`)
		_, _ = w.Write([]byte("hello"))
	}))
	defer srv.Close()

	cache := httpcache.NewRoundTripper(nil, httpcache.Config{})
	client := &http.Client{Transport: cache, Timeout: 5 * time.Second}
	for range 2 {
		resp, err := client.Get(srv.URL)
		if err != nil {
			fmt.Println(err)
			return
		}
		_ = resp.Body.Close()
	}
	// The second GET carried the validator, the server answered 304, and the
	// cache served the held copy.
	fmt.Println(cache.State().Hits)
}
Output:
1

func (*RoundTripper) CloseIdleConnections

func (t *RoundTripper) CloseIdleConnections()

CloseIdleConnections closes next's idle connections where next can, so http.Client.CloseIdleConnections reaches them.

func (*RoundTripper) RoundTrip

func (t *RoundTripper) RoundTrip(orig *http.Request) (*http.Response, error)

RoundTrip revalidates a GET carrying no validator of its own and sends every other request through next as given. A read whose context has ended by the time its answer is read keeps nothing and fails with the context's error. A response a next that breaks the RoundTripper contract returns beside an error is returned beside that error with its body closed; http.Client ignores it.

func (*RoundTripper) State

func (t *RoundTripper) State() State

State is what the cache has done since it was built, and what it holds now.

type State

type State struct {
	Hits   int   // reads a held answer served after a 304
	Misses int   // every other stored read the server answered in full
	Saved  int   // served 304s on a server that bills none (FreeNotModified)
	Bytes  int64 // what the cache holds now
}

State is what a cache has done since it was built, and what it holds now.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL