httpcache

README

httpcache

Package httpcache implements functions related to HTTP caching based on RFC 9111.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT

Documentation

Overview

Package httpcache implements functions related to HTTP caching based on RFC 9111.

Index

• Variables
• func ParseAge(s string) (time.Duration, error)
• func ParseExpires(s string) (time.Time, error)
• type Config
  • func (c Config) CanStore(req Request, resp Response) bool
  • func (c Config) RemoveUnstorableHeaders(headers http.Header)
• type ExtensionDirective
  • func (e ExtensionDirective) String() string
• type Request
  • func (r Request) Authorized() bool
  • func (r Request) Directives() (RequestDirectives, error)
• type RequestDirectives
  • func ParseRequestDirectives(header string) (RequestDirectives, error)
  • func (d RequestDirectives) String() string
• type Response
  • func (r Response) Age() (time.Duration, error)
  • func (r Response) Directives() (ResponseDirectives, error)
  • func (r Response) Expires() (time.Time, error)
  • func (r Response) Vary() []string
• type ResponseDirectives
  • func ParseResponseDirectives(header string) (ResponseDirectives, error)
  • func (d ResponseDirectives) String() string

Variables

var HeuristicallyCacheableStatusCodes = []int{
	http.StatusOK,
	http.StatusNonAuthoritativeInfo,
	http.StatusNoContent,
	http.StatusPartialContent,
	http.StatusMultipleChoices,
	http.StatusMovedPermanently,
	http.StatusPermanentRedirect,
	http.StatusNotFound,
	http.StatusMethodNotAllowed,
	http.StatusGone,
	http.StatusRequestURITooLong,
	http.StatusNotImplemented,
}

HeuristicallyCacheableStatusCodes contains HTTP response codes specified in RFC 9110 that are allowed to be cached by default.

Functions

func ParseAge

func ParseAge(s string) (time.Duration, error)

ParseAge parses a duration in seconds from the HTTP Age header.

func ParseExpires

func ParseExpires(s string) (time.Time, error)

ParseExpires parses a time and date from the HTTP Expires header.

Types

type Config

type Config struct {
	// CacheableByExtension can be used to mark a response as cacheable even if it does not match any of the other
	// criteria specified in RFC 9111.
	//
	// If nil, only the criteria from RFC 9111 is applied to determine cacheability.
	CacheableByExtension func(Request, Response) bool

	// CanUnderstandResponseCode is used to check if a response with status code 206 or 304, or with must-understand cache
	// directive should be cached.
	//
	// If nil, such responses are not cached.
	CanUnderstandResponseCode func(code int) bool

	// IgnoreRequestDirectiveNoStore can be set to disable checking of the no-store Cache-Control request directive.
	//
	// Note that while RFC 9111 specifies that the no-store directive should prevent responses from being cached, the
	// steps for determining whether a response can be stored do not actually say anything about the directive.
	//
	// The [Config.CanStore] method by default respects the directive, but caches may want to ignore it.
	IgnoreRequestDirectiveNoStore bool

	// IsHeuristicallyCacheableStatusCode is called to check if a status code can be cached without explicit opt-in via
	// cache directives.
	//
	// If nil, the status codes from [HeuristicallyCacheableStatusCodes] are allowed.
	IsHeuristicallyCacheableStatusCode func(code int) bool

	// Private configures the cache to be private, as understood by RFC 9111.
	Private bool

	// RespectPrivateHeaders can be set to true to enable caches to be stored even when private is specified in the
	// response, as long as the private directive has specified at least one header in its value.
	//
	// It also causes [Config.RemoveUnstorableHeaders] to remove headers specified for the "private" response directive,
	// but not for the "no-cache" directive (as those are still usable depending on the request).
	//
	// If false, the directive is treated as if it had no value.
	RespectPrivateHeaders bool

	// StoreProxyHeaders, if set, causes [Config.RemoveUnstorableHeaders] to not remove the following headers:
	//
	// - Proxy-Authenticate
	// - Proxy-Authentication-Info
	// - Proxy-Authorization
	StoreProxyHeaders bool

	// SupportedRequestMethod is called to check if the request method can be cached,
	//
	// If nil, only GET, HEAD and QUERY methods can be cached.
	SupportedRequestMethod func(method string) bool
}

Config defines characteristics of the cache based on which cacheability can be calculated.

func (Config) CanStore

func (c Config) CanStore(req Request, resp Response) bool

CanStore checks if a response can be cached and for how long.

func (Config) RemoveUnstorableHeaders

func (c Config) RemoveUnstorableHeaders(headers http.Header)

RemoveUnstorableHeaders removes response headers that must not be stored.

type ExtensionDirective

type ExtensionDirective struct {
	// Name of the directive. May be empty if HasValue is true.
	Name string

	// Value of the directive, if any. May be empty. CanStore HasValue to differentiate between an empty and no value.
	Value string

	// HasValue is true if Value is set.
	HasValue bool
}

ExtensionDirective represents a non-standard Cache-Control directive.

func (ExtensionDirective) String

func (e ExtensionDirective) String() string

String implements the fmt.Stringer interface.

type Request

type Request struct {
	// Method contains the HTTP method of the request.
	Method string

	// URL is the requested URL.
	URL *url.URL

	// Header contains the request headers.
	Header http.Header
}

Request contains HTTP request information related to caching. It can be used with Config to check if a request is cacheable or not.

func (Request) Authorized

func (r Request) Authorized() bool

Authorized returns true if the request contains the Authorization header.

func (Request) Directives

func (r Request) Directives() (RequestDirectives, error)

Directives returns the parsed Cache-Control header for this request.

type RequestDirectives

type RequestDirectives struct {
	// https://www.rfc-editor.org/rfc/rfc9111#name-max-age
	MaxAge time.Duration

	// https://www.rfc-editor.org/rfc/rfc9111#name-max-stale
	MaxStale time.Duration

	// https://www.rfc-editor.org/rfc/rfc9111#name-min-fresh
	MinFresh time.Duration

	// https://www.rfc-editor.org/rfc/rfc9111#name-no-cache
	NoCache bool

	// https://www.rfc-editor.org/rfc/rfc9111#name-no-store
	NoStore bool

	// https://www.rfc-editor.org/rfc/rfc9111#name-no-transform
	NoTransform bool

	// https://www.rfc-editor.org/rfc/rfc9111#name-only-if-cached
	OnlyIfCached bool

	// Extensions contains all non-standard directives in the order encountered.
	//
	// The directive names are always lower cased.
	//
	// If the parsed header contained duplicate directives, this slice will also contain these duplicate directives.
	Extensions []ExtensionDirective
}

RequestDirectives contains parsed cache directives from a Cache-Control header for a request.

func ParseRequestDirectives

func ParseRequestDirectives(header string) (RequestDirectives, error)

ParseRequestDirectives parses a Cache-Control request header and returns a struct of the parsed directives.

Any errors during parsing are collected and returned as one using errors.Join together with the struct containing all parseable data.

func (RequestDirectives) String

func (d RequestDirectives) String() string

String implements the fmt.Stringer interface.

type Response

type Response struct {
	// StatusCode is the final HTTP response code used for the response.
	StatusCode int

	// Header contains the response headers.
	Header http.Header

	// Trailer contains the response trailers.
	Trailer http.Header
}

Response contains HTTP response information related to caching. It can be used with Config to check if a response is cacheable or not.

func (Response) Age

func (r Response) Age() (time.Duration, error)

Age returns the response age in seconds.

func (Response) Directives

func (r Response) Directives() (ResponseDirectives, error)

Directives returns the parsed Cache-Control header for this response.

func (Response) Expires

func (r Response) Expires() (time.Time, error)

Expires returns the time at which the response expires, if any.

func (Response) Vary

func (r Response) Vary() []string

Vary returns the parsed header names from the Vary header.

Duplicates are removed and the result is sorted.

type ResponseDirectives

type ResponseDirectives struct {
	// https://www.rfc-editor.org/rfc/rfc9111#name-max-age-2
	MaxAge time.Duration

	// https://www.rfc-editor.org/rfc/rfc9111#name-must-revalidate
	MustRevalidate bool

	// https://www.rfc-editor.org/rfc/rfc9111#name-must-understand
	MustUnderstand bool

	// https://www.rfc-editor.org/rfc/rfc9111#name-no-cache-2
	NoCache bool

	// NoCacheHeaders contains the header names set via the no-cache directive, when the directive has a value.
	//
	// If the last no-cache directive had no value, this will be nil. Otherwise, the slice will be non-nil, even if empty.
	//
	// https://www.rfc-editor.org/rfc/rfc9111#name-no-cache-2
	NoCacheHeaders []string

	// https://www.rfc-editor.org/rfc/rfc9111#name-no-store-2
	NoStore bool

	// https://www.rfc-editor.org/rfc/rfc9111#name-no-transform-2
	NoTransform bool

	// https://www.rfc-editor.org/rfc/rfc9111#name-private
	Private bool

	// https contains the header names set via the private a directive, when the directive has a value.
	//
	// If the last private directive had no value, this will be nil. Otherwise, the slice will be non-nil, even if empty.
	//
	// https://www.rfc-editor.org/rfc/rfc9111#name-no-cache-2
	PrivateHeaders []string

	// https://www.rfc-editor.org/rfc/rfc9111#name-proxy-revalidate
	ProxyRevalidate bool

	// https://www.rfc-editor.org/rfc/rfc9111#name-public
	Public bool

	// https://www.rfc-editor.org/rfc/rfc9111#name-s-maxage
	SMaxAge time.Duration

	// Extensions contains all non-standard directives in the order encountered.
	//
	// The directive names are always lower cased.
	//
	// If the parsed header contained duplicate directives, this slice will also contain these duplicate directives.
	Extensions []ExtensionDirective
}

ResponseDirectives contains parsed cache directives from a Cache-Control header for a response.

func ParseResponseDirectives

func ParseResponseDirectives(header string) (ResponseDirectives, error)

ParseResponseDirectives parses a Cache-Control response header and returns a struct of the parsed directives.

Any errors during parsing are collected and returned as one using errors.Join together with the struct containing all parseable data.

func (ResponseDirectives) String

func (d ResponseDirectives) String() string

String implements the fmt.Stringer interface.