transparent

Documentation

Overview

Package transparent implements transparent content negotiation as defined in RFC2295.

Construction

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

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

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

constructs a transparent negotiator with the provided options.
p := transparent.New(
	transparent.MaximumVariantListSize(5),
)

See Also

➣ https://tools.ietf.org/html/rfc2295

Index

• Variables
• func RVSA1() 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 (
	// MaximumVariantListSize specifies the maximum allowable size of the
	// variant list used within transparent negotiation. Variant lists larger
	// than this number will result in an error. If a value less than 1 is
	// provided, it will be set to 1.
	MaximumVariantListSize = func(size int) Option {
		if size < 1 {
			size = 1
		}
		return func(o *Options) {
			o.MaximumVariantListSize = size
		}
	}

	// RVSA defines the remove variant selection algorithm (RVSA) to leverage
	// for transparant negotiation.
	RVSA = func(c representation.Chooser) Option {
		return func(o *Options) {
			o.Chooser = c
		}
	}

	// ListRepresentation defines the representation to utilize when
	// returning list responses.
	ListRepresentation = func(c representation.ListConstructor) Option {
		return func(o *Options) {
			o.ListRepresentationConstructor = c
		}
	}

	// GuessSmallThreshold specifies the threshold in bytes that the choice
	// response can exceed the list response in a 'guess-small' request.
	GuessSmallThreshold = func(threshold int) Option {
		return func(o *Options) {
			o.GuessSmallThreshold = threshold
		}
	}

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

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

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

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

Defines the default transparent negotiator.

The default configuration is as follows:

➣ The algorithm used for serving choice responses is the RVSA 1.0 algorithm.

➣ For guess-small responses, the choice response can be no more than 50 bytes larger than the list response.

➣ The representation for list responses utilizes the JSON (application/json) media type.

➣ No more than 10 representations can be used in the negotiation process.

var (
	// ErrVariantListSizeExceeded represents an error encountered when the
	// provided variant list exceeds the maximum allowed.pr
	ErrVariantListSizeExceeded = errors.New("number of representations exceeds the maximum")
)

Errors that can be thrown from options.

Functions

func RVSA1

func RVSA1() representation.Chooser

RVSA1 provides the Remote Variant Selection Algorithm 1.0 as defined in RFC2296.

Types

type Negotiator

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

Negotiator represents the negotiator responsible for performing transparent negotiation.

func New

func New(options ...Option) Negotiator

New constructs a negotiatior capable of performing transparent negotiation with the options provided.

func (Negotiator) Negotiate

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

Negotiate performs transparent content negotiation with the representations provided.

type Option

type Option func(*Options)

Option represents a configurable option for transparent content negotiation.

type Options

type Options struct {
	MaximumVariantListSize        int
	Chooser                       representation.Chooser
	ListRepresentationConstructor representation.ListConstructor
	Logger                        *zap.Logger
	Scope                         tally.Scope
	GuessSmallThreshold           int
}

Options represents the configuration options for transparent content negotiation.