directive

Documentation

Overview

Package directive defines the public wire contract shared by directive producers and the directive proxy data plane.

It owns Payload and RemoteSpec schemas, strict JSON decoding, validation, normalization, and target-less Payload templates. Token signing and proxy runtime behavior intentionally remain private to the directive proxy.

Index

• Constants
• Variables
• func CanonicalTemplate(raw []byte) ([]byte, error)
• func EncodeRemote(hmacSecret string, spec RemoteSpec) (string, error)
• func ValidatePayload(payload Payload) error
• func ValidateRemoteSpec(spec RemoteSpec) error
• type BodyStoreSpec
• type FileRemoteSpec
• type HTTPRemoteSpec
• type HeaderAction
• type HeaderMutation
• type HeaderPolicy
• type HeaderSide
• type ModuleSpec
• type ModuleSpecs
• type Payload
  • func DecodePayload(raw []byte) (Payload, error)
  • func DecodeTemplate(raw []byte) (Payload, error)
  • func NormalizePayload(payload Payload) (Payload, error)
• type RecoveryBudgetSpec
• type RecoveryControllerSpec
• type RecoverySpec
• type RecoveryStatusRangeSpec
• type RecoveryTriggerSpec
• type RecoveryUnexpectedStatusSpec
• type RedisRemoteSpec
• type RemoteSpec
  • func DecodeRemote(hmacSecret, encoded string) (RemoteSpec, error)
  • func DecodeRemoteSpec(raw []byte) (RemoteSpec, error)
  • func NormalizeRemoteSpec(spec RemoteSpec) (RemoteSpec, error)
• type TargetSection
  • func (target *TargetSection) UnmarshalJSON(raw []byte) error

Constants

const (
	TokenFamily  = "dp"
	TokenVersion = "22"
	TokenInline  = "inline"
	TokenRemote  = "remote"
)

const (
	RemoteTypeHTTP  = "http"
	RemoteTypeRedis = "redis"
	RemoteTypeFile  = "file"

	MaxRemoteKeyBytes      = 256
	MaxRemoteFilePathBytes = 4096
)

Variables

var ErrInvalidPayload = errors.New("invalid directive payload")

Functions

func CanonicalTemplate

func CanonicalTemplate(raw []byte) ([]byte, error)

func EncodeRemote

func EncodeRemote(hmacSecret string, spec RemoteSpec) (string, error)

EncodeRemote signs a normalized RemoteSpec using the public dp.22.remote token format. It is intentionally exposed so control-plane components can sign at runtime without depending on the proxy's internal packages.

func ValidatePayload

func ValidatePayload(payload Payload) error

func ValidateRemoteSpec

func ValidateRemoteSpec(spec RemoteSpec) error

Types

type BodyStoreSpec

type BodyStoreSpec struct {
	MaxBodyBytes *int64  `json:"max_body_bytes,omitempty"`
	QueueWait    *string `json:"queue_wait,omitempty"`
	ReadTimeout  *string `json:"read_timeout,omitempty"`
	ChunkBytes   *int    `json:"chunk_bytes,omitempty"`
}

type FileRemoteSpec

type FileRemoteSpec struct {
	Path string `json:"path"`
}

type HTTPRemoteSpec

type HTTPRemoteSpec struct {
	URL     string        `json:"url"`
	Headers *HeaderPolicy `json:"headers,omitempty"`
}

type HeaderAction

type HeaderAction string

const (
	HeaderActionAdd HeaderAction = "add"
	HeaderActionSet HeaderAction = "set"
	HeaderActionDel HeaderAction = "del"
)

type HeaderMutation

type HeaderMutation struct {
	Side   HeaderSide   `json:"side"`
	Action HeaderAction `json:"action"`
	Name   string       `json:"name,omitempty"`
	Glob   string       `json:"glob,omitempty"`
	Values []string     `json:"values,omitempty"`
}

type HeaderPolicy

type HeaderPolicy struct {
	PreserveProxyDisclosure bool             `json:"preserve_proxy_disclosure,omitzero"`
	Mutations               []HeaderMutation `json:"mutations,omitempty"`
}

type HeaderSide

type HeaderSide string

const (
	HeaderSideRequest  HeaderSide = "request"
	HeaderSideResponse HeaderSide = "response"
)

type ModuleSpec

type ModuleSpec struct {
	Module string         `json:"module"`
	Config jsontext.Value `json:"config,omitempty"`
}

type ModuleSpecs

type ModuleSpecs []ModuleSpec

type Payload

type Payload struct {
	Metadata  map[string]string `json:"metadata,omitempty"`
	Target    TargetSection     `json:"target"`
	Proxy     string            `json:"proxy,omitempty"`
	Headers   *HeaderPolicy     `json:"headers,omitempty"`
	Modules   ModuleSpecs       `json:"modules,omitempty"`
	Recovery  *RecoverySpec     `json:"recovery,omitempty"`
	BodyStore *BodyStoreSpec    `json:"body_store,omitempty"`
}

func DecodePayload

func DecodePayload(raw []byte) (Payload, error)

func DecodeTemplate

func DecodeTemplate(raw []byte) (Payload, error)

DecodeTemplate decodes a Payload fragment that deliberately omits target. Templates are suitable for control-plane policy storage and must be completed with a target before they can be consumed by the data plane.

func NormalizePayload

func NormalizePayload(payload Payload) (Payload, error)

type RecoveryBudgetSpec

type RecoveryBudgetSpec struct {
	MaxRoundTrips int    `json:"max_round_trips"`
	MaxElapsed    string `json:"max_elapsed,omitempty"`
}

type RecoveryControllerSpec

type RecoveryControllerSpec struct {
	URL     string            `json:"url"`
	Headers map[string]string `json:"headers,omitempty"`
	Timeout string            `json:"timeout,omitempty"`
}

type RecoverySpec

type RecoverySpec struct {
	Controller RecoveryControllerSpec `json:"controller"`
	Triggers   RecoveryTriggerSpec    `json:"triggers"`
	Budget     RecoveryBudgetSpec     `json:"budget"`
}

type RecoveryStatusRangeSpec

type RecoveryStatusRangeSpec struct {
	From int `json:"from"`
	To   int `json:"to"`
}

type RecoveryTriggerSpec

type RecoveryTriggerSpec struct {
	ResponseHeaderTimeout string                        `json:"response_header_timeout,omitempty"`
	UnexpectedStatus      *RecoveryUnexpectedStatusSpec `json:"unexpected_status,omitempty"`
	TransportError        bool                          `json:"transport_error,omitzero"`
}

type RecoveryUnexpectedStatusSpec

type RecoveryUnexpectedStatusSpec struct {
	Expected         []RecoveryStatusRangeSpec `json:"expected"`
	CaptureBodyBytes int64                     `json:"capture_body_bytes,omitzero"`
}

type RedisRemoteSpec

type RedisRemoteSpec struct {
	URL string `json:"url"`
	Key string `json:"key"`
}

type RemoteSpec

type RemoteSpec struct {
	UUID  string           `json:"uuid,omitempty"`
	HTTP  *HTTPRemoteSpec  `json:"http,omitempty"`
	Redis *RedisRemoteSpec `json:"redis,omitempty"`
	File  *FileRemoteSpec  `json:"file,omitempty"`
}

func DecodeRemote

func DecodeRemote(hmacSecret, encoded string) (RemoteSpec, error)

DecodeRemote verifies and decodes a dp.22.remote token.

func DecodeRemoteSpec

func DecodeRemoteSpec(raw []byte) (RemoteSpec, error)

func NormalizeRemoteSpec

func NormalizeRemoteSpec(spec RemoteSpec) (RemoteSpec, error)

type TargetSection

type TargetSection struct {
	BaseURL  string `json:"base_url,omitempty"`
	ExactURL string `json:"exact_url,omitempty"`
}

func (*TargetSection) UnmarshalJSON

func (target *TargetSection) UnmarshalJSON(raw []byte) error