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 ¶
- func Guard(next http.RoundTripper) http.RoundTripper
- type Cache
- type Config
- type HeldField
- type Read
- func (r *Read) Answered() bool
- func (r *Read) Finish(ctx context.Context, ok bool) (hit bool, err error)
- func (r *Read) Keep(resp *http.Response, body []byte, kept func() ([]byte, error))
- func (r *Read) Send(send func(prepare func(*http.Request) *http.Request) (*http.Response, error)) (*http.Response, error)
- func (r *Read) Serve(live http.Header) (header http.Header, body []byte, ok bool)
- type ReadConfig
- type RoundTripper
- type State
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.
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.