data

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, template, language string) (sendContent bool, err error)
• type Data
• type Metadata
• type Value
  • func Lazy(supplier func(template, language string) (interface{}, error)) *Value
  • func Of(v interface{}) *Value
  • func Sequence(supplier func(template, language string) (interface{}, error)) *Value
  • func (v *Value) Content(template, language string) (result interface{}, more bool, err error)
  • func (v Value) ETag(hash string) *Value
  • func (v Value) ETagUsing(fn func(template, language string) (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(template, language string) (time.Time, error)) *Value
  • func (v Value) MaxAge(max time.Duration) *Value
  • func (v *Value) Meta(template, language string) (meta *Metadata, err error)
  • func (v Value) NoCache() *Value
  • func (v Value) With(hdr string, value string, others ...string) *Value

Functions

func ConditionalRequest

func ConditionalRequest(rw http.ResponseWriter, req *http.Request, d Data, template, language string) (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(template, language string) (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 arising. For chunked data, this method
	// will be called repeatedly until the boolean yields false or an error arises.
	Content(template, language string) (interface{}, 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.

If necessary, Content will be called a second time, this time with dataRequired=true. The data must always be returned in this case. However the metadata will be ignored.

The metadata can be nil if not needed.

type Metadata

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.

type Value

type Value struct {
	// contains filtered or unexported fields
}

Value is a simple implementation of Data.

func Lazy

func Lazy(supplier func(template, language string) (interface{}, error)) *Value

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 ETag method should be used. Likewise, if a last-modified timestamp is known, the LastModified method should also be used.

func Of

func Of(v interface{}) *Value

Of wraps a data value.

If an entity tag is known, the ETag method should be used. Likewise, if a last-modified timestamp is known, the LastModified method should also be used.

func Sequence

func Sequence(supplier func(template, language string) (interface{}, error)) *Value

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 ETag method should be used. Likewise, if a last-modified timestamp is known, the LastModified method should also be used.

func (*Value) Content

func (v *Value) Content(template, language string) (result interface{}, more bool, err error)

func (Value) ETag

func (v Value) ETag(hash string) *Value

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

func (v Value) ETagUsing(fn func(template, language string) (string, error)) *Value

ETag lazily sets the entity tag for the content. This allows for conditional requests, possibly avoiding network traffic.

func (Value) Expires

func (v Value) Expires(at time.Time) *Value

Expires sets the time at which the response becomes stale. MaxAge takes precedence.

func (Value) Headers

func (v Value) Headers() map[string]string

func (Value) LastModified

func (v Value) LastModified(at time.Time) *Value

LastModified sets the time at which the content was last modified. This allows for conditional requests, possibly avoiding network traffic, although ETag takes precedence. This is not necessary if Lazy was used and the function returns metadata.

func (Value) LastModifiedUsing

func (v Value) LastModifiedUsing(fn func(template, language string) (time.Time, error)) *Value

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

func (v Value) MaxAge(max time.Duration) *Value

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) Meta

func (v *Value) Meta(template, language string) (meta *Metadata, err error)

func (Value) NoCache

func (v Value) NoCache() *Value

NoCache sets cache control headers to prevent the response being cached.

func (Value) With

func (v Value) With(hdr string, value string, others ...string) *Value

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. Or they can be func(interface{}) string, in which case they will be called using the result of Content.