proactive

Documentation

Overview

Package proactive implements proactive content negotiation as defined in RFC7231 Section 3.4.1.

Construction

For out of the box proactive negotiation support, use proactive.Default, which is the default proactive negotiator.

//retrieves the default proactive negotiator.
p := proactive.Default

In situations where more customization is required, use the proactive.New constructor function and specify options as arguments.

 //constructs a proactive negotiator with the provided options.
 p := proactive.New(
		proactive.DisableStrictMode(),
		proactive.DisableNotAcceptableRepresentation(),
 )

Strict Mode

According to RFC7231, when none of the representations match the values provided for a particular proactive content negotiation header, the origin server can honor that header and return 406 Not Acceptable, or disregard the header field by treating the resource as if it is not subject to content negotiation.

The behavior of honoring the header in these scenarios is what we refer to as strict mode. It is possible to configure strict mode for each individual proactive negotiation header, or disable strict mode for all. Strict mode is enabled for all headers by default.

See Also

➣ https://tools.ietf.org/html/rfc7231#section-3.4.1

➣ https://httpd.apache.org/docs/2.4/content-negotiation.html

Index

• Variables
• func ApacheHTTPD() representation.Chooser
• type Negotiator
  • func New(options ...Option) Negotiator
  • func (n Negotiator) Negotiate(ctx negotiator.NegotiationContext, reps ...representation.Representation) (err error)
• type Option
• type Options

Variables

var (
	// DisableStrictAccept deactivates strict mode for the Accept header,
	// meaning that a 406 HTTP status code is not returned if none of the
	// representations have a media type that is acceptable.
	DisableStrictAccept = func() Option {
		return func(o *Options) {
			o.StrictAccept = false
		}
	}

	// DisableStrictAcceptLanguage deactivates strict mode for the
	// Accept-Language header, meaning that a 406 HTTP status code is not
	// returned if none of the representations have a language that is
	// acceptable.
	DisableStrictAcceptLanguage = func() Option {
		return func(o *Options) {
			o.StrictAcceptLanguage = false
		}
	}

	// DisableStrictAcceptCharset deactivates strict mode for the
	// Accept-Charset header, meaning that a 406 HTTP status code is not
	// returned if none of the representations have a charset that is
	// acceptable.
	DisableStrictAcceptCharset = func() Option {
		return func(o *Options) {
			o.StrictAcceptCharset = false
		}
	}

	// DisableStrictMode deactivates strict mode for all Accept-* headers,
	// meaning that a 406 HTTP status code will not be returned if none of the
	// representations are acceptable for any of the headers.
	DisableStrictMode = func() Option {
		return func(o *Options) {
			o.StrictAccept = false
			o.StrictAcceptLanguage = false
			o.StrictAcceptCharset = false
		}
	}

	// Algorithm defines the algorithm to leverage for proactive negotiation.
	Algorithm = func(c representation.Chooser) Option {
		return func(o *Options) {
			o.Chooser = c
		}
	}

	// DisableNotAcceptableRepresentation deactivates functionality that
	// provides a representation in body of responses having a 406 HTTP
	// status code.
	DisableNotAcceptableRepresentation = func() Option {
		return func(o *Options) {
			o.NotAcceptableRepresentation = false
		}
	}

	// DefaultRepresentation defines the representation to utilize when
	// returning responses with the 406 HTTP status code.
	DefaultRepresentation = func(constructor representation.ListConstructor) Option {
		return func(o *Options) {
			o.DefaultRepresentationConstructor = constructor
		}
	}

	// Representations defines the set of representations to consider when
	// returning responses with the 406 HTTP status code. These the algorithm
	// that the proactive negotiator is configured with is utilized to select
	// the 'best' representation.
	Representations = func(constructors ...representation.ListConstructor) Option {
		return func(o *Options) {
			o.RepresentationConstructors = constructors
		}
	}

	// Logger specifies the logger for the proactive negotiator.
	Logger = func(l *zap.Logger) Option {
		return func(o *Options) {
			o.Logger = l
		}
	}

	// Scope specifies the metric scope to leverage for the proactive
	// negotiator.
	Scope = func(s tally.Scope) Option {
		return func(o *Options) {
			o.Scope = s
		}
	}
)

Options that can be used to configure and extend proactive negotiators.

var (
	// Default is the default proactive negotiator.
	Default = New()
)

Defines the default proactive negotiator.

The default configuration is as follows:

➣ Strict mode is enabled for all proactive negotiation headers

➣ A representation containing information about available representations is returned with a 406 Not Acceptable response.

➣ The algorithm used to choose the 'best' representation is the Apache httpd algorithm.

➣ Representation candidates for 406 Not Acceptable responses support JSON (application/json), XML (application/xml), and YAML (application/yaml, text/yaml) media types.

➣ The fallback representation for 406 Not Acceptable responses utilizes the JSON (application/json) media type.

Functions

func ApacheHTTPD

func ApacheHTTPD() representation.Chooser

ApacheHTTPD provides the Apache HTTP server proactive content negotation algorithm.

Types

type Negotiator

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

Negotiator represents the negotiator responsible for performing proactive (server-driven) negotiation.

func New

func New(options ...Option) Negotiator

New constructs a negotiator capable of performing proactive (server-driven) negotiation with the options provided.

func (Negotiator) Negotiate

func (n Negotiator) Negotiate(
	ctx negotiator.NegotiationContext, reps ...representation.Representation) (err error)

Negotiate performs proactive (server-driven) content negotiation with the representations provided.

type Option

type Option func(*Options)

Option represents a configurable option for proactive (server-driven) content negotiation.

type Options

type Options struct {
	StrictAccept                     bool
	StrictAcceptLanguage             bool
	StrictAcceptCharset              bool
	NotAcceptableRepresentation      bool
	DefaultRepresentationConstructor representation.ListConstructor
	RepresentationConstructors       []representation.ListConstructor
	Chooser                          representation.Chooser
	Logger                           *zap.Logger
	Scope                            tally.Scope
}

Options represents the configuration options for proactive (server-driven) content negotiation.