data

Documentation

Overview

package data provides wrappers for response data, optionally including response headers such as ETag and Cache-Control.

Index

• func GetContentAndApplyExtraHeaders(rw http.ResponseWriter, req *http.Request, d Data, template, language string) (interface{}, error)
• type Data
• type Metadata
• type Value
  • func Lazy(...) *Value
  • func Of(v interface{}, etag ...string) *Value
  • func (v *Value) Content(template, language string, dataRequired bool) (result interface{}, meta *Metadata, err error)
  • func (v Value) ETag(hash string) *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) MaxAge(max time.Duration) *Value
  • func (v Value) NoCache() *Value
  • func (v Value) With(hdr string, value string, others ...string) *Value

Functions

func GetContentAndApplyExtraHeaders

func GetContentAndApplyExtraHeaders(rw http.ResponseWriter, req *http.Request, d Data, template, language string) (interface{}, error)

GetContentAndApplyExtraHeaders applies all lazy functions to produce the resulting content to be rendered; this value is returned. It also sets any extra response headers.

Types

type Data

type Data interface {
	// 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 hash that will be used as the entity tag (if required),
	// and an error if arising.
	Content(template, language string, dataRequired bool) (data interface{}, meta *Metadata, err 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.

When preparing to render, Content will be called once or twice. The first time, the dataRequired flag is false; this gives an opportunity to obtain the entity tag with or without the data. At this stage, data may be returned only if it is convenient.

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 etag will be ignored.

The hash should be blank 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(fn func(template, language string, dataRequired bool) (interface{}, *Metadata, error)) *Value

Lazy wraps a function that supplies a data value, but only fetches te data when it is needed.

func Of

func Of(v interface{}, etag ...string) *Value

Of wraps a data value. An optional entity tag can also be passed in. This is often the MD5 sum of the content, or something similar. If this is non-blank, the ETag response header will be sent on responses to GET/HEAD requests.

func (*Value) Content

func (v *Value) Content(template, language string, dataRequired bool) (result interface{}, meta *Metadata, 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) 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) 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) 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.