baggage

README

Baggage

Documentation

Overview

Package baggage provides functionality for storing and retrieving baggage items in Go context. For propagating the baggage, see the go.opentelemetry.io/otel/propagation package.

Index

• func ContextWithBaggage(parent context.Context, b Baggage) context.Context
• func ContextWithoutBaggage(parent context.Context) context.Context
• type Baggage
  • func FromContext(ctx context.Context) Baggage
  • func New(members ...Member) (Baggage, error)
  • func Parse(bStr string) (Baggage, error)
  • func (b Baggage) DeleteMember(key string) Baggage
  • func (b Baggage) Len() int
  • func (b Baggage) Member(key string) Member
  • func (b Baggage) Members() []Member
  • func (b Baggage) SetMember(member Member) (Baggage, error)
  • func (b Baggage) String() string
• type Member
  • func NewMember(key, value string, props ...Property) (Member, error)
  • func NewMemberRaw(key, value string, props ...Property) (Member, error)
  • func (m Member) Key() string
  • func (m Member) Properties() []Property
  • func (m Member) String() string
  • func (m Member) Value() string
• type Property
  • func NewKeyProperty(key string) (Property, error)
  • func NewKeyValueProperty(key, value string) (Property, error)
  • func NewKeyValuePropertyRaw(key, value string) (Property, error)
  • func (p Property) Key() string
  • func (p Property) String() string
  • func (p Property) Value() (string, bool)

Functions

func ContextWithBaggage

func ContextWithBaggage(parent context.Context, b Baggage) context.Context

ContextWithBaggage returns a copy of parent with baggage.

func ContextWithoutBaggage

func ContextWithoutBaggage(parent context.Context) context.Context

ContextWithoutBaggage returns a copy of parent with no baggage.

Types

type Baggage

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

Baggage is a list of baggage members representing the baggage-string as defined by the W3C Baggage specification.

func FromContext

func FromContext(ctx context.Context) Baggage

FromContext returns the baggage contained in ctx.

func New

func New(members ...Member) (Baggage, error)

New returns a new valid Baggage. It returns an error if it results in a Baggage exceeding limits set in that specification.

It expects all the provided members to have already been validated.

func Parse

func Parse(bStr string) (Baggage, error)

Parse attempts to decode a baggage-string from the passed string. It returns an error if the input is invalid according to the W3C Baggage specification.

If there are duplicate list-members contained in baggage, the last one defined (reading left-to-right) will be the only one kept. This diverges from the W3C Baggage specification which allows duplicate list-members, but conforms to the OpenTelemetry Baggage specification.

func (Baggage) DeleteMember

func (b Baggage) DeleteMember(key string) Baggage

DeleteMember returns a copy of the Baggage with the list-member identified by key removed.

func (Baggage) Len

func (b Baggage) Len() int

Len returns the number of list-members in the Baggage.

func (Baggage) Member

func (b Baggage) Member(key string) Member

Member returns the baggage list-member identified by key.

If there is no list-member matching the passed key the returned Member will be a zero-value Member. The returned member is not validated, as we assume the validation happened when it was added to the Baggage.

func (Baggage) Members

func (b Baggage) Members() []Member

Members returns all the baggage list-members. The order of the returned list-members is not significant.

The returned members are not validated, as we assume the validation happened when they were added to the Baggage.

func (Baggage) SetMember

func (b Baggage) SetMember(member Member) (Baggage, error)

SetMember returns a copy of the Baggage with the member included. If the baggage contains a Member with the same key, the existing Member is replaced.

If member is invalid according to the W3C Baggage specification, an error is returned with the original Baggage.

func (Baggage) String

func (b Baggage) String() string

String encodes Baggage into a header string compliant with the W3C Baggage specification. It would ignore members where the member key is invalid with the W3C Baggage specification. This could happen for a UTF-8 key, as it may contain invalid characters.

type Member

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

Member is a list-member of a baggage-string as defined by the W3C Baggage specification.

func NewMember

func NewMember(key, value string, props ...Property) (Member, error)

NewMember returns a new Member from the passed arguments.

The passed key must be compliant with W3C Baggage specification. The passed value must be percent-encoded as defined in W3C Baggage specification.

Notice: Consider using NewMemberRaw instead that does not require percent-encoding of the value.

func NewMemberRaw

func NewMemberRaw(key, value string, props ...Property) (Member, error)

NewMemberRaw returns a new Member from the passed arguments.

The passed key must be valid, non-empty UTF-8 string. The passed value must be valid UTF-8 string. However, the specific Propagators that are used to transmit baggage entries across component boundaries may impose their own restrictions on baggage key. For example, the W3C Baggage specification restricts the baggage keys to strings that satisfy the token definition from RFC7230, Section 3.2.6. For maximum compatibility, alphanumeric value are strongly recommended to be used as baggage key.

func (Member) Key

func (m Member) Key() string

Key returns the Member key.

func (Member) Properties

func (m Member) Properties() []Property

Properties returns a copy of the Member properties.

func (Member) String

func (m Member) String() string

String encodes Member into a header string compliant with the W3C Baggage specification. It would return empty string if the key is invalid with the W3C Baggage specification. This could happen for a UTF-8 key, as it may contain invalid characters.

func (Member) Value

func (m Member) Value() string

Value returns the Member value.

type Property

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

Property is an additional metadata entry for a baggage list-member.

func NewKeyProperty

func NewKeyProperty(key string) (Property, error)

NewKeyProperty returns a new Property for key.

The passed key must be valid, non-empty UTF-8 string. If key is invalid, an error will be returned. However, the specific Propagators that are used to transmit baggage entries across component boundaries may impose their own restrictions on Property key. For example, the W3C Baggage specification restricts the Property keys to strings that satisfy the token definition from RFC7230, Section 3.2.6. For maximum compatibility, alphanumeric value are strongly recommended to be used as Property key.

func NewKeyValueProperty

func NewKeyValueProperty(key, value string) (Property, error)

NewKeyValueProperty returns a new Property for key with value.

The passed key must be compliant with W3C Baggage specification. The passed value must be percent-encoded as defined in W3C Baggage specification.

Notice: Consider using NewKeyValuePropertyRaw instead that does not require percent-encoding of the value.

func NewKeyValuePropertyRaw

func NewKeyValuePropertyRaw(key, value string) (Property, error)

NewKeyValuePropertyRaw returns a new Property for key with value.

The passed key must be valid, non-empty UTF-8 string. The passed value must be valid UTF-8 string. However, the specific Propagators that are used to transmit baggage entries across component boundaries may impose their own restrictions on Property key. For example, the W3C Baggage specification restricts the Property keys to strings that satisfy the token definition from RFC7230, Section 3.2.6. For maximum compatibility, alphanumeric value are strongly recommended to be used as Property key.

func (Property) Key

func (p Property) Key() string

Key returns the Property key.

func (Property) String

func (p Property) String() string

String encodes Property into a header string compliant with the W3C Baggage specification. It would return empty string if the key is invalid with the W3C Baggage specification. This could happen for a UTF-8 key, as it may contain invalid characters.

func (Property) Value

func (p Property) Value() (string, bool)

Value returns the Property value. Additionally, a boolean value is returned indicating if the returned value is the empty if the Property has a value that is empty or if the value is not set.