metadata

Documentation

Overview

Package metadata provides immutable request metadata and explicit propagation policies.

Index

• Constants
• Variables
• func WithInbound(ctx context.Context, metadata Metadata) context.Context
• func WithLocal(ctx context.Context, metadata Metadata) context.Context
• func WithOutbound(ctx context.Context, metadata Metadata) context.Context
• type Carrier
• type MapCarrier
  • func (c MapCarrier) Set(key string, values []string)
  • func (c MapCarrier) Values(key string) []string
• type Metadata
  • func Inbound(ctx context.Context) (Metadata, bool)
  • func Local(ctx context.Context) (Metadata, bool)
  • func New(values map[string][]string, options ...Option) (Metadata, error)
  • func Outbound(ctx context.Context) (Metadata, bool)
  • func (m Metadata) Clone() Metadata
  • func (m Metadata) IsSensitive(key string) bool
  • func (m Metadata) Keys() []string
  • func (m Metadata) Redacted(replacement string) map[string][]string
  • func (m Metadata) Values(key string) []string
• type Option
  • func WithMaxBytes(maxBytes int) Option
  • func WithSensitive(keys ...string) Option
• type Policy
  • func NewPolicy(allowed []string, options ...PolicyOption) (Policy, error)
  • func (p Policy) Extract(carrier Carrier) (Metadata, error)
  • func (p Policy) Inject(metadata Metadata, carrier Carrier) error
• type PolicyOption
  • func WithPolicyMaxBytes(maxBytes int) PolicyOption
  • func WithSensitiveKeys(keys ...string) PolicyOption

Constants

const (
	// DefaultMaxBytes is the default metadata key/value budget.
	DefaultMaxBytes = 8 * 1024
)

Variables

var (
	// ErrInvalidKey means a metadata key cannot be normalized safely.
	ErrInvalidKey = errors.New("metadata: invalid key")
	// ErrTooLarge means metadata exceeds its configured byte budget.
	ErrTooLarge = errors.New("metadata: size limit exceeded")
	// ErrInvalidOption means a metadata option is invalid.
	ErrInvalidOption = errors.New("metadata: invalid option")
	// ErrNilCarrier means a propagation Carrier is nil.
	ErrNilCarrier = errors.New("metadata: nil carrier")
)

Functions

func WithInbound

func WithInbound(ctx context.Context, metadata Metadata) context.Context

WithInbound attaches immutable inbound Metadata to ctx.

func WithLocal

func WithLocal(ctx context.Context, metadata Metadata) context.Context

WithLocal attaches local-only Metadata to ctx.

func WithOutbound

func WithOutbound(ctx context.Context, metadata Metadata) context.Context

WithOutbound attaches immutable outbound Metadata to ctx.

Types

type Carrier

type Carrier interface {
	Values(string) []string
	Set(string, []string)
}

Carrier is the minimal multi-value transport carrier used by Policy.

type MapCarrier

type MapCarrier map[string][]string

MapCarrier adapts a normalized map to Carrier.

Callers that inject metadata must initialize the map.

func (MapCarrier) Set

func (c MapCarrier) Set(key string, values []string)

Set writes a defensive copy under a normalized key.

func (MapCarrier) Values

func (c MapCarrier) Values(key string) []string

Values returns a defensive copy of a normalized carrier value.

type Metadata

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

Metadata is an immutable collection of normalized multi-value metadata.

func Inbound

func Inbound(ctx context.Context) (Metadata, bool)

Inbound returns an independent copy of inbound Metadata.

func Local

func Local(ctx context.Context) (Metadata, bool)

Local returns an independent copy of local-only Metadata.

func New

func New(values map[string][]string, options ...Option) (Metadata, error)

New constructs immutable Metadata and enforces its byte budget.

func Outbound

func Outbound(ctx context.Context) (Metadata, bool)

Outbound returns an independent copy of outbound Metadata.

func (Metadata) Clone

func (m Metadata) Clone() Metadata

Clone returns a deep immutable copy.

func (Metadata) IsSensitive

func (m Metadata) IsSensitive(key string) bool

IsSensitive reports whether key must be redacted in diagnostic output.

func (Metadata) Keys

func (m Metadata) Keys() []string

Keys returns normalized keys in lexical order.

func (Metadata) Redacted

func (m Metadata) Redacted(replacement string) map[string][]string

Redacted returns an independent map with sensitive values replaced.

func (Metadata) Values

func (m Metadata) Values(key string) []string

Values returns an independent copy of every value for key.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option configures Metadata construction.

func WithMaxBytes

func WithMaxBytes(maxBytes int) Option

WithMaxBytes sets the maximum combined key/value bytes.

func WithSensitive

func WithSensitive(keys ...string) Option

WithSensitive marks keys for redaction without granting propagation rights.

type Policy

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

Policy is an immutable allowlist and byte budget for transport propagation.

func NewPolicy

func NewPolicy(allowed []string, options ...PolicyOption) (Policy, error)

NewPolicy constructs an immutable default-deny propagation policy.

func (Policy) Extract

func (p Policy) Extract(carrier Carrier) (Metadata, error)

Extract copies only allowlisted fields from carrier.

func (Policy) Inject

func (p Policy) Inject(metadata Metadata, carrier Carrier) error

Inject copies only allowlisted fields into carrier.

type PolicyOption

type PolicyOption interface {
	// contains filtered or unexported methods
}

PolicyOption configures a propagation Policy.

func WithPolicyMaxBytes

func WithPolicyMaxBytes(maxBytes int) PolicyOption

WithPolicyMaxBytes sets the maximum propagated key/value bytes.

func WithSensitiveKeys

func WithSensitiveKeys(keys ...string) PolicyOption

WithSensitiveKeys marks allowed propagation keys as sensitive.