httpcache

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
}

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
}

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
}

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
}

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
}

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
}