offer

Documentation

Overview

Package offer provides the means to offer various permutations of data, content type and language to the content negotiation matching algorithm. It also provides Match, the result type from the matching algorithm.

Index

• Variables
• type JSONEncoder
• type Match
  • func (m Match) ApplyHeaders(rw http.ResponseWriter) io.Writer
  • func (m Match) String() string
• type Offer
  • func CSV(comma ...rune) Offer
  • func ImageJPEG() Offer
  • func ImagePNG() Offer
  • func JSON(indent ...string) Offer
  • func Of(processor Processor, contentType string) Offer
  • func TextPlain() Offer
  • func XML(root string, indent ...string) Offer
  • func (o Offer) BuildFallbackMatch() *Match
  • func (o Offer) BuildMatch(acceptedCT header.ContentType, lang string, statusCodeOverride int) *Match
  • func (o Offer) CanHandle406As(statusCode int) Offer
  • func (o Offer) Data(lang string) datapkg.Data
  • func (o Offer) IsEmpty() bool
  • func (o Offer) String() string
  • func (o Offer) ToSlice() Offers
  • func (o Offer) With(data interface{}, language string, otherLanguages ...string) Offer
• type Offers
  • func (offers Offers) AllEmpty() bool
  • func (offers Offers) CanHandle406() Offers
  • func (offers Offers) Filter(typ, subtype string) Offers
• type Processor
  • func BinaryProcessor() Processor
  • func CSVProcessor(comma ...rune) Processor
  • func JSONProcessor(indent ...string) Processor
  • func TXTProcessor() Processor
  • func XMLProcessor(root string, indent ...string) Processor

Variables

var NewJSONEncoder = func(w io.Writer) JSONEncoder { return json.NewEncoder(w) }

NewJSONEncoder is a pluggable JSON encoder, initialised with the standard library implementation.

Types

type JSONEncoder

type JSONEncoder interface {
	SetIndent(string, string)
	Encode(interface{}) error
}

JSONEncoder summarises the key methods of the standard JSON encoder.

type Match

type Match struct {
	header.ContentType
	Language           string
	Charset            string
	Vary               []string
	Data               data.Data
	Render             Processor
	StatusCodeOverride int
}

Match holds the best-matched offer after content negotiation and is used for response rendering.

func (Match) ApplyHeaders

func (m Match) ApplyHeaders(rw http.ResponseWriter) io.Writer

ApplyHeaders sets response headers so that the user agent is notified of the content negotiation decisions made. Four headers may be set, depending on context.

• Content-Type is always set.
• Content-Language is set when a language was selected.
• Content-Encoding is set when the character set is being transcoded
• Vary is set to list the accept headers that led to the three decisions above.

func (Match) String

func (m Match) String() string

type Offer

type Offer struct {
	// ContentType is the content type that is to be matched.
	// Wildcard values may be used.
	header.ContentType

	// Langs lists the language(s) provided by this offer.
	Langs []string

	// Handle406As enables this offer to be a handler for any 406-not-acceptable case that arises.
	// Normally, this field will be left zero. However, if non-zero, the offer can be rendered
	// even when no acceptable match has been found. This overrides the acceptable.NoMatchAccepted
	// handler, providing a means to supply bespoke error responses.
	//
	// The value will be the required status code (e.g. 400 for Bad Request, or 406 for Not
	// Acceptable).
	Handle406As int
	// contains filtered or unexported fields
}

Offer holds information about one particular resource representation that can potentially provide an acceptable response.

func CSV

func CSV(comma ...rune) Offer

CSV constructs a CSV Offer easily.

func ImageJPEG

func ImageJPEG() Offer

ImageJPEGPNG is an Offer for image/jpeg content using BinaryProcessor.

func ImagePNG

func ImagePNG() Offer

ImagePNG is an Offer for image/png content using BinaryProcessor.

func JSON

func JSON(indent ...string) Offer

JSON constructs a JSON Offer easily.

func Of

func Of(processor Processor, contentType string) Offer

Of constructs an Offer easily, given a content type. The contentType can be a partial wildcard "type/*".

Also, if the content type is blank, it is assumed to be the full wildcard "*/*". However, in this catch-all situation, the best matching MIME type will be determined from the Accept header and the response Content-Type will be set to this value, even if it is inappropriate for the actual content. Therefore this should be used sparingly or not at all. The correct behaviour is a 406 when no match can be made.

func TextPlain

func TextPlain() Offer

TextPlain returns an Offer for text/plain content using TXTProcessor.

func XML

func XML(root string, indent ...string) Offer

XML constructs an XML Offer easily.

func (Offer) BuildFallbackMatch

func (o Offer) BuildFallbackMatch() *Match

func (Offer) BuildMatch

func (o Offer) BuildMatch(acceptedCT header.ContentType, lang string, statusCodeOverride int) *Match

BuildMatch implements the transition between a selected Offer and the resulting Match. The result is based on the best-matched media type and language.

func (Offer) CanHandle406As

func (o Offer) CanHandle406As(statusCode int) Offer

CanHandle406As sets the Handle406As status code.

func (Offer) Data

func (o Offer) Data(lang string) datapkg.Data

Data gets the data lodged for a given language (or language group).

func (Offer) IsEmpty

func (o Offer) IsEmpty() bool

IsEmpty returns true if no data has been attached to this offer.

func (Offer) String

func (o Offer) String() string

String is merely for information purposes.

func (Offer) ToSlice

func (o Offer) ToSlice() Offers

ToSlice returns the offer as a single-item slice.

func (Offer) With

func (o Offer) With(data interface{}, language string, otherLanguages ...string) Offer

With attaches response data to an offer. The returned offer is a clone of the original offer, which is unchanged. This allows base offers to be derived from.

The data can be a value (struct, slice, etc) or a data.Data. It may also be nil, which means the method merely serves to add the language to the Offer's supported languages.

The language parameter specifies what language (or language group such as "en-GB") the data represents and that the offer will therefore match. It can be "*" to match every language.

The method panics if language is blank. Other languages can also be specified, but these must not be "*" (or blank). Duplicates are not allowed.

Language matching is described further in IETF BCP 47.

type Offers

type Offers []Offer

Offers holds a slice of Offer.

func (Offers) AllEmpty

func (offers Offers) AllEmpty() bool

AllEmpty returns true if all offers are empty (see offer.IsEmpty). In other words, it returns false if any offer is non-empty. If they are all empty, this typically represents a 'no content' response.

func (Offers) CanHandle406

func (offers Offers) CanHandle406() Offers

CanHandle406 filters offers to retunr only those with non-zero status codes in the Handle406As field.

func (Offers) Filter

func (offers Offers) Filter(typ, subtype string) Offers

Filter returns only the offers that match specified type and subtype. The type and subtype parameters can be a wildcard, "*".

type Processor

type Processor func(w io.Writer, req *http.Request, data datapkg.Data, template, language string) error

Processor is a function that renders content according to the matched result.

func BinaryProcessor

func BinaryProcessor() Processor

BinaryProcessor creates an output processor that outputs binary data in a form suitable for image/* and similar responses. Model values should be one of the following:

* []byte * io.WriterTo * io.Reader * nil

Because it handles io.Reader and io.WriterTo, BinaryProcessor can be used to stream large responses (without any further encoding).

func CSVProcessor

func CSVProcessor(comma ...rune) Processor

CSVProcessor creates an output processor that serialises a dataModel in CSV form. With no arguments, the default format is comma-separated; you can supply any rune to be used as an alternative separator. The underlying encoder is provided by the standard library and so correctly handles quote marks etc.

Model values should be one of the following:

* string or []string, written as a single row

* [][]string or [][]fmt.Stringer, written as many rows

* fmt.Stringer or []fmt.Stringer, written as a single row

* []int or similar (bool, int8, int16, int32, int64, uint8, uint16, uint32, uint63, float32, float64, complex), written as a single row

* [][]int or similar (bool, int8, int16, int32, int64, uint8, uint16, uint32, uint63, float32, float64, complex), written as many rows

* struct for which all the fields are exported and of simple types (as above), written as a single row

* []struct for some struct in which all the fields are exported and of simple types (as above), written as many rows

func JSONProcessor

func JSONProcessor(indent ...string) Processor

JSONProcessor creates a new processor for JSON with a specified indentation. This converts a data item (or a sequence of data items) into JSON using the standard Go encoder.

When writing a sequence of items, the overall result is a JSON array starting with "[" and ending with "]", including commas where necessary.

The optional indent argument is a string usually of zero or more space characters.

func TXTProcessor

func TXTProcessor() Processor

TXTProcessor creates an output processor that serialises strings in a form suitable for text/* responses (especially text/plain and text/html). It is also useful for JSON, XML etc that is already encoded.

As required by IETF RFC, the response will always be sent with a trailing newline, even if the supplied content doesn't end with a newline.

Model values should be one of the following:

* string * []byte * fmt.Stringer * encoding.TextMarshaler * io.WriterTo * io.Reader * nil

Because it handles io.Reader and io.WriterTo, TXTProcessor can be used to stream large responses (without any further encoding).

func XMLProcessor

func XMLProcessor(root string, indent ...string) Processor

XMLProcessor creates a new processor for XML with root element and optional indentation. This converts a data item (or a sequence of data items) into XML using the standard Go encoder.

The root element is used only when processing content that is a sequence of data items. It can be a name such as "root" or an XML element such as "<html lang='en'>".

The optional indent argument is a string usually of zero or more space characters.