Documentation
¶
Overview ¶
Package data provides wrappers for response data, optionally including response headers such as ETag and Cache-Control. Type Data provides the means to wrap data with its metadata and to obtain these lazily when required. When the response data is provided lazily, this can be either a single item or a sequence of items. In both cases, a supplier function provided by the caller is used.
Index ¶
- func ConditionalRequest(rw http.ResponseWriter, req *http.Request, d Data, chosen Chosen) (sendContent bool, err error)
- type Chosen
- type Data
- type Metadata
- type Supplier
- type Value
- func (v *Value) Content(chosen Chosen) (result any, more bool, err error)
- func (v Value) ETag(hash string) *Value
- func (v Value) ETagUsing(fn func(chosen Chosen) (string, error)) *Value
- func (v Value) Expires(at time.Time) *Value
- func (v Value) Headers() map[string]string
- func (v Value) LastModified(at time.Time) *Value
- func (v Value) LastModifiedUsing(fn func(chosen Chosen) (time.Time, error)) *Value
- func (v Value) MaxAge(max time.Duration) *Value
- func (v *Value) Meta(chosen Chosen) (meta *Metadata, err error)
- func (v Value) NoCache() *Value
- func (v Value) With(hdr string, value string, others ...string) *Value
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ConditionalRequest ¶ added in v0.18.0
func ConditionalRequest(rw http.ResponseWriter, req *http.Request, d Data, chosen Chosen) (sendContent bool, err error)
ConditionalRequest checks the headers for conditional requests and returns a flag indicating whether content should be rendered or skipped.
If the returned result value is false, the response has been set to 304-Not Modified, so the response processor does not need to do anything further.
Data d must not be nil.
Types ¶
type Data ¶
type Data interface {
// Meta returns the metadata that will be used to set response headers automatically.
// The headers are ETag and Last-Modified.
Meta(chosen Chosen) (meta *Metadata, err error)
// Content returns the data as a value that can be processed by encoders such as "encoding/json"
// The returned values are
// - the data itself,
// - a boolean that is true if the data is in chunks and there is more data to follow, and
// - an error if one occurs.
// For chunked data, this method will be called repeatedly until the boolean yields false
// or an error arises.
Content(chosen Chosen) (any, bool, error)
// Headers returns response headers relating to the data (optional)
Headers() map[string]string
}
Data provides a source for response content. It is optimised for lazy evaluation, avoiding wasted processing as much as possible.
type Metadata ¶ added in v0.11.0
type Metadata struct {
Hash string // used as entity tag; blank if not required
LastModified time.Time // used for Last-Modified header; zero if not required
}
Metadata provides optional entity tag and last modified information about some data. This can be sent with a response such thath the client can make conditional requests in future.
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
Value is a simple implementation of Data.
func Lazy ¶
Lazy wraps a function that supplies a data value, but only fetches the data when it is needed.
If an entity tag is known, the Value.ETag method should be used on the result. Likewise, if a last-modified timestamp is known, the Value.LastModified method should also be used.
func Of ¶
Of wraps a data value.
If an entity tag is known, the Value.ETag method should be used on the result. Likewise, if a last-modified timestamp is known, the Value.LastModified method should also be used.
func Sequence ¶ added in v0.18.0
Sequence wraps a function that supplies data values in a sequence chunk by chunk. This function will not be not called until it is needed. When it is called, it will be called repeatedly until the returned value is nil or an error arises.
Typical use might be where a response contains many database records that are obtained one by one to avoid the need to cache all results in memory before rendering.
If an entity tag is known, the Value.ETag method should be used on the result. Likewise, if a last-modified timestamp is known, the Value.LastModified method should also be used.
func (Value) ETag ¶ added in v0.9.0
ETag sets the entity tag for the content. This allows for conditional requests, possibly avoiding network traffic. This is not necessary if Lazy was used and the function returns metadata.
func (Value) ETagUsing ¶ added in v0.18.0
ETagUsing lazily sets the entity tag for the content. This allows for conditional requests, possibly avoiding some network traffic.
func (Value) Expires ¶ added in v0.9.0
Expires sets the time at which the response becomes stale. MaxAge takes precedence.
func (Value) LastModified ¶ added in v0.9.0
LastModified sets the time at which the content was last modified. This allows for conditional requests, possibly avoiding network traffic, although Value.ETag takes precedence. This is not necessary if Lazy was used and the function returns metadata.
func (Value) LastModifiedUsing ¶ added in v0.18.0
LastModifiedUsing lazily sets the time at which the content was last modified. This allows for conditional requests, possibly avoiding network traffic, although ETag takes precedence.
func (Value) MaxAge ¶ added in v0.9.0
MaxAge sets the max-age header on the response. This is used to allow caches to avoid repeating the request until the max age has expired, after which time the resource is considered stale.
func (Value) NoCache ¶ added in v0.9.0
NoCache sets cache control headers to prevent the response being cached.
func (Value) With ¶
With returns a copy of v with extra headers attached. These are passed in as key+value pairs. The header names should be in normal form, e.g. "Last-Modified" instead of "last-modified", but this is not mandatory. The values are simple strings, numbers etc. The others contain more key/value pairs; there should be an even number of them.
Source Files