cacheobject

Documentation

Index

• Variables
• func CachableObject(obj *Object, rv *ObjectResults)
• func CachableRequestObject(obj *Object, rv *ObjectResults)
• func CachableResponseObject(obj *Object, rv *ObjectResults)
• func ExpirationObject(obj *Object, rv *ObjectResults)
• func UsingRequestResponseWithObject(req *http.Request, statusCode int, respHeaders http.Header, privateCache bool) ([]Reason, time.Time, []Warning, *Object, error)
• type DeltaSeconds
• type FieldNames
• type Object
• type ObjectResults
• type Reason
  • func UsingRequestResponse(req *http.Request, statusCode int, respHeaders http.Header, privateCache bool) ([]Reason, time.Time, error)
  • func (r Reason) String() string
• type RequestCacheDirectives
  • func ParseRequestCacheControl(value string) (*RequestCacheDirectives, error)
• type ResponseCacheDirectives
  • func ParseResponseCacheControl(value string) (*ResponseCacheDirectives, error)
• type Warning
  • func (w Warning) HeaderString(agent string, date time.Time) string
  • func (w Warning) String() string

Variables

var (
	ErrQuoteMismatch         = errors.New("Missing closing quote")
	ErrMaxAgeDeltaSeconds    = errors.New("Failed to parse delta-seconds in `max-age`")
	ErrSMaxAgeDeltaSeconds   = errors.New("Failed to parse delta-seconds in `s-maxage`")
	ErrMaxStaleDeltaSeconds  = errors.New("Failed to parse delta-seconds in `max-stale`")
	ErrMinFreshDeltaSeconds  = errors.New("Failed to parse delta-seconds in `min-fresh`")
	ErrNoCacheNoArgs         = errors.New("Unexpected argument to `no-cache`")
	ErrNoStoreNoArgs         = errors.New("Unexpected argument to `no-store`")
	ErrNoTransformNoArgs     = errors.New("Unexpected argument to `no-transform`")
	ErrOnlyIfCachedNoArgs    = errors.New("Unexpected argument to `only-if-cached`")
	ErrMustRevalidateNoArgs  = errors.New("Unexpected argument to `must-revalidate`")
	ErrPublicNoArgs          = errors.New("Unexpected argument to `public`")
	ErrProxyRevalidateNoArgs = errors.New("Unexpected argument to `proxy-revalidate`")
	// Experimental
	ErrImmutableNoArgs                  = errors.New("Unexpected argument to `immutable`")
	ErrStaleIfErrorDeltaSeconds         = errors.New("Failed to parse delta-seconds in `stale-if-error`")
	ErrStaleWhileRevalidateDeltaSeconds = errors.New("Failed to parse delta-seconds in `stale-while-revalidate`")
)

Functions

func CachableObject

func CachableObject(obj *Object, rv *ObjectResults)

LOW LEVEL API: Check if a object is cachable.

func CachableRequestObject

func CachableRequestObject(obj *Object, rv *ObjectResults)

LOW LEVEL API: Check if a request is cacheable. This function doesn't reset the passed ObjectResults.

func CachableResponseObject

func CachableResponseObject(obj *Object, rv *ObjectResults)

LOW LEVEL API: Check if a response is cacheable. This function doesn't reset the passed ObjectResults.

func ExpirationObject

func ExpirationObject(obj *Object, rv *ObjectResults)

LOW LEVEL API: Update an objects expiration time.

func UsingRequestResponseWithObject

func UsingRequestResponseWithObject(req *http.Request,
	statusCode int,
	respHeaders http.Header,
	privateCache bool) ([]Reason, time.Time, []Warning, *Object, error)

Evaluate cachability based on an HTTP request, and parts of the response. Returns the parsed Object as well.

Types

type DeltaSeconds

type DeltaSeconds int32

DeltaSeconds specifies a non-negative integer, representing time in seconds: http://tools.ietf.org/html/rfc7234#section-1.2.1

When set to -1, this means unset.

type FieldNames

type FieldNames map[string]bool

Fields present in a header.

type Object

type Object struct {
	CacheIsPrivate bool

	RespDirectives         *ResponseCacheDirectives
	RespHeaders            http.Header
	RespStatusCode         int
	RespExpiresHeader      time.Time
	RespDateHeader         time.Time
	RespLastModifiedHeader time.Time

	ReqDirectives *RequestCacheDirectives
	ReqHeaders    http.Header
	ReqMethod     string

	NowUTC time.Time
}

LOW LEVEL API: Represents a potentially cachable HTTP object.

This struct is designed to be serialized efficiently, so in a high performance caching server, things like Date-Strings don't need to be parsed for every use of a cached object.

type ObjectResults

type ObjectResults struct {
	OutReasons        []Reason
	OutWarnings       []Warning
	OutExpirationTime time.Time
	OutErr            error
}

LOW LEVEL API: Represents the results of examining an Object with CachableObject and ExpirationObject.

TODO(pquerna): decide if this is a good idea or bad

type Reason

type Reason int

Repersents a potential Reason to not cache an object.

Applications may wish to ignore specific reasons, which will make them non-RFC compliant, but this type gives them specific cases they can choose to ignore, making them compliant in as many cases as they can.

const (

	// The request method was POST and an Expiration header was not supplied.
	ReasonRequestMethodPOST Reason = iota

	// The request method was PUT and PUTs are not cachable.
	ReasonRequestMethodPUT

	// The request method was DELETE and DELETEs are not cachable.
	ReasonRequestMethodDELETE

	// The request method was CONNECT and CONNECTs are not cachable.
	ReasonRequestMethodCONNECT

	// The request method was OPTIONS and OPTIONS are not cachable.
	ReasonRequestMethodOPTIONS

	// The request method was TRACE and TRACEs are not cachable.
	ReasonRequestMethodTRACE

	// The request method was not recognized by cachecontrol, and should not be cached.
	ReasonRequestMethodUnknown

	// The request included an Cache-Control: no-store header
	ReasonRequestNoStore

	// The request included an Authorization header without an explicit Public or Expiration time: http://tools.ietf.org/html/rfc7234#section-3.2
	ReasonRequestAuthorizationHeader

	// The response included an Cache-Control: no-store header
	ReasonResponseNoStore

	// The response included an Cache-Control: private header and this is not a Private cache
	ReasonResponsePrivate

	// The response failed to meet at least one of the conditions specified in RFC 7234 section 3: http://tools.ietf.org/html/rfc7234#section-3
	ReasonResponseUncachableByDefault
)

func UsingRequestResponse

func UsingRequestResponse(req *http.Request,
	statusCode int,
	respHeaders http.Header,
	privateCache bool) ([]Reason, time.Time, error)

Evaluate cachability based on an HTTP request, and parts of the response.

func (Reason) String

func (r Reason) String() string

type RequestCacheDirectives

type RequestCacheDirectives struct {

	// max-age(delta seconds): http://tools.ietf.org/html/rfc7234#section-5.2.1.1
	//
	// The "max-age" request directive indicates that the client is
	// unwilling to accept a response whose age is greater than the
	// specified number of seconds.  Unless the max-stale request directive
	// is also present, the client is not willing to accept a stale
	// response.
	MaxAge DeltaSeconds

	// max-stale(delta seconds): http://tools.ietf.org/html/rfc7234#section-5.2.1.2
	//
	// The "max-stale" request directive indicates that the client is
	// willing to accept a response that has exceeded its freshness
	// lifetime.  If max-stale is assigned a value, then the client is
	// willing to accept a response that has exceeded its freshness lifetime
	// by no more than the specified number of seconds.  If no value is
	// assigned to max-stale, then the client is willing to accept a stale
	// response of any age.
	MaxStale    DeltaSeconds
	MaxStaleSet bool

	// min-fresh(delta seconds): http://tools.ietf.org/html/rfc7234#section-5.2.1.3
	//
	// The "min-fresh" request directive indicates that the client is
	// willing to accept a response whose freshness lifetime is no less than
	// its current age plus the specified time in seconds.  That is, the
	// client wants a response that will still be fresh for at least the
	// specified number of seconds.
	MinFresh DeltaSeconds

	// no-cache(bool): http://tools.ietf.org/html/rfc7234#section-5.2.1.4
	//
	// The "no-cache" request directive indicates that a cache MUST NOT use
	// a stored response to satisfy the request without successful
	// validation on the origin server.
	NoCache bool

	// no-store(bool): http://tools.ietf.org/html/rfc7234#section-5.2.1.5
	//
	// The "no-store" request directive indicates that a cache MUST NOT
	// store any part of either this request or any response to it.  This
	// directive applies to both private and shared caches.
	NoStore bool

	// no-transform(bool): http://tools.ietf.org/html/rfc7234#section-5.2.1.6
	//
	// The "no-transform" request directive indicates that an intermediary
	// (whether or not it implements a cache) MUST NOT transform the
	// payload, as defined in Section 5.7.2 of RFC7230.
	NoTransform bool

	// only-if-cached(bool): http://tools.ietf.org/html/rfc7234#section-5.2.1.7
	//
	// The "only-if-cached" request directive indicates that the client only
	// wishes to obtain a stored response.
	OnlyIfCached bool

	// stale-if-error(delta seconds): https://datatracker.ietf.org/doc/html/rfc5861#section-4
	StaleIfError DeltaSeconds

	// Extensions: http://tools.ietf.org/html/rfc7234#section-5.2.3
	//
	// The Cache-Control header field can be extended through the use of one
	// or more cache-extension tokens, each with an optional value.  A cache
	// MUST ignore unrecognized cache directives.
	Extensions []string
}

LOW LEVEL API: Representation of possible request directives in a `Cache-Control` header: http://tools.ietf.org/html/rfc7234#section-5.2.1

Note: Many fields will be `nil` in practice.

func ParseRequestCacheControl

func ParseRequestCacheControl(value string) (*RequestCacheDirectives, error)

LOW LEVEL API: Parses a Cache Control Header from a Request into a set of directives.

type ResponseCacheDirectives

type ResponseCacheDirectives struct {

	// must-revalidate(bool): http://tools.ietf.org/html/rfc7234#section-5.2.2.1
	//
	// The "must-revalidate" response directive indicates that once it has
	// become stale, a cache MUST NOT use the response to satisfy subsequent
	// requests without successful validation on the origin server.
	MustRevalidate bool

	// no-cache(FieldName): http://tools.ietf.org/html/rfc7234#section-5.2.2.2
	//
	// The "no-cache" response directive indicates that the response MUST
	// NOT be used to satisfy a subsequent request without successful
	// validation on the origin server.
	//
	// If the no-cache response directive specifies one or more field-names,
	// then a cache MAY use the response to satisfy a subsequent request,
	// subject to any other restrictions on caching.  However, any header
	// fields in the response that have the field-name(s) listed MUST NOT be
	// sent in the response to a subsequent request without successful
	// revalidation with the origin server.
	NoCache FieldNames

	// no-cache(cast-to-bool): http://tools.ietf.org/html/rfc7234#section-5.2.2.2
	//
	// While the RFC defines optional field-names on a no-cache directive,
	// many applications only want to know if any no-cache directives were
	// present at all.
	NoCachePresent bool

	// no-store(bool): http://tools.ietf.org/html/rfc7234#section-5.2.2.3
	//
	// The "no-store" request directive indicates that a cache MUST NOT
	// store any part of either this request or any response to it.  This
	// directive applies to both private and shared caches.
	NoStore bool

	// no-transform(bool): http://tools.ietf.org/html/rfc7234#section-5.2.2.4
	//
	// The "no-transform" response directive indicates that an intermediary
	// (regardless of whether it implements a cache) MUST NOT transform the
	// payload, as defined in Section 5.7.2 of RFC7230.
	NoTransform bool

	// public(bool): http://tools.ietf.org/html/rfc7234#section-5.2.2.5
	//
	// The "public" response directive indicates that any cache MAY store
	// the response, even if the response would normally be non-cacheable or
	// cacheable only within a private cache.
	Public bool

	// private(FieldName): http://tools.ietf.org/html/rfc7234#section-5.2.2.6
	//
	// The "private" response directive indicates that the response message
	// is intended for a single user and MUST NOT be stored by a shared
	// cache.  A private cache MAY store the response and reuse it for later
	// requests, even if the response would normally be non-cacheable.
	//
	// If the private response directive specifies one or more field-names,
	// this requirement is limited to the field-values associated with the
	// listed response header fields.  That is, a shared cache MUST NOT
	// store the specified field-names(s), whereas it MAY store the
	// remainder of the response message.
	Private FieldNames

	// private(cast-to-bool): http://tools.ietf.org/html/rfc7234#section-5.2.2.6
	//
	// While the RFC defines optional field-names on a private directive,
	// many applications only want to know if any private directives were
	// present at all.
	PrivatePresent bool

	// proxy-revalidate(bool): http://tools.ietf.org/html/rfc7234#section-5.2.2.7
	//
	// The "proxy-revalidate" response directive has the same meaning as the
	// must-revalidate response directive, except that it does not apply to
	// private caches.
	ProxyRevalidate bool

	// max-age(delta seconds): http://tools.ietf.org/html/rfc7234#section-5.2.2.8
	//
	// The "max-age" response directive indicates that the response is to be
	// considered stale after its age is greater than the specified number
	// of seconds.
	MaxAge DeltaSeconds

	// s-maxage(delta seconds): http://tools.ietf.org/html/rfc7234#section-5.2.2.9
	//
	// The "s-maxage" response directive indicates that, in shared caches,
	// the maximum age specified by this directive overrides the maximum age
	// specified by either the max-age directive or the Expires header
	// field.  The s-maxage directive also implies the semantics of the
	// proxy-revalidate response directive.
	SMaxAge DeltaSeconds

	// immutable(cast-to-bool): experimental feature
	Immutable bool

	// stale-if-error(delta seconds): experimental feature
	StaleIfError DeltaSeconds

	// stale-while-revalidate(delta seconds): experimental feature
	StaleWhileRevalidate DeltaSeconds

	// Extensions: http://tools.ietf.org/html/rfc7234#section-5.2.3
	//
	// The Cache-Control header field can be extended through the use of one
	// or more cache-extension tokens, each with an optional value.  A cache
	// MUST ignore unrecognized cache directives.
	Extensions []string
}

LOW LEVEL API: Repersentation of possible response directives in a `Cache-Control` header: http://tools.ietf.org/html/rfc7234#section-5.2.2

Note: Many fields will be `nil` in practice.

func ParseResponseCacheControl

func ParseResponseCacheControl(value string) (*ResponseCacheDirectives, error)

LOW LEVEL API: Parses a Cache Control Header from a Response into a set of directives.

type Warning

type Warning int

Repersents an HTTP Warning: http://tools.ietf.org/html/rfc7234#section-5.5

const (
	// Response is Stale
	// A cache SHOULD generate this whenever the sent response is stale.
	WarningResponseIsStale Warning = 110

	// Revalidation Failed
	// A cache SHOULD generate this when sending a stale
	// response because an attempt to validate the response failed, due to an
	// inability to reach the server.
	WarningRevalidationFailed Warning = 111

	// Disconnected Operation
	// A cache SHOULD generate this if it is intentionally disconnected from
	// the rest of the network for a period of time.
	WarningDisconnectedOperation Warning = 112

	// Heuristic Expiration
	//
	// A cache SHOULD generate this if it heuristically chose a freshness
	// lifetime greater than 24 hours and the response's age is greater than
	// 24 hours.
	WarningHeuristicExpiration Warning = 113

	// Miscellaneous Warning
	//
	// The warning text can include arbitrary information to be presented to
	// a human user or logged.  A system receiving this warning MUST NOT
	// take any automated action, besides presenting the warning to the
	// user.
	WarningMiscellaneousWarning Warning = 199

	// Transformation Applied
	//
	// This Warning code MUST be added by a proxy if it applies any
	// transformation to the representation, such as changing the
	// content-coding, media-type, or modifying the representation data,
	// unless this Warning code already appears in the response.
	WarningTransformationApplied Warning = 214

	// Miscellaneous Persistent Warning
	//
	// The warning text can include arbitrary information to be presented to
	// a human user or logged.  A system receiving this warning MUST NOT
	// take any automated action.
	WarningMiscellaneousPersistentWarning Warning = 299
)

func (Warning) HeaderString

func (w Warning) HeaderString(agent string, date time.Time) string

func (Warning) String

func (w Warning) String() string