model

package
v0.52.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 6, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package model is SPECTRE's data model: the traffic that crosses a service's boundary through its proxies, and why a candidate was quarantined.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DifferenceLines added in v0.52.0 

func DifferenceLines(differences []Difference, truncated bool) []string

DifferenceLines writes differences as diff lines, ending with "… more" when they were truncated.

Types

type Calls added in v0.49.0 

type Calls struct {
	Routes map[Route]uint64 `json:"routes,omitempty"`
	// Other counts requests to routes beyond the most a mirror counts.
	Other uint64 `json:"other,omitzero"`
}

Calls counts the requests the ingress proxy received on each route since the mirror started.

func (Calls) Equal added in v0.49.0 

func (c Calls) Equal(other Calls) bool

Equal reports whether both count the same requests.

type Change added in v0.52.0 

type Change string

Change is how the candidate's value at a path differs from the reference's. 

const (
	// ChangeMissing means the reference has a value at the path and the candidate does not.
	ChangeMissing Change = "missing"
	// ChangeAdded means the candidate has a value at the path and the reference does not.
	ChangeAdded Change = "added"
	// ChangeChanged means both have values of the same JSON type that differ.
	ChangeChanged Change = "changed"
	// ChangeRetyped means both have values, of different JSON types.
	ChangeRetyped Change = "retyped"
)

type Difference added in v0.52.0 

type Difference struct {
	// Path names declared fields; payload keys and merged list indexes are [*].
	Path   string `json:"path"`
	Change Change `json:"change"`
	// Retype is present only when Change is ChangeRetyped.
	Retype Option[Retype] `json:"retype,omitzero"`
	// Count is how many keys or list elements the path stands for.
	Count int `json:"count"`
}

Difference is where and how a candidate's response differs from the reference's. It names only schema fields and JSON types, never values.

func (Difference) String added in v0.52.0 

func (d Difference) String() string

String writes the difference as a diff line, e.g. "! $.currency string → null".

type Direction 

type Direction string

Direction names the proxy that carries traffic: ingress into the service, or egress from it to a dependency. 

const (
	// Ingress traffic is requests to the proxied service.
	Ingress Direction = "ingress"
	// Egress traffic is requests from the service to a dependency.
	Egress Direction = "egress"
)

type Divergence 

type Divergence struct {
	Service     string `json:"service"`
	Environment string `json:"environment"`
	// Revision is the commit of the candidate the mirror ran.
	Revision string `json:"revision"`
	// Direction is the proxy that quarantined the candidate.
	Direction  Direction  `json:"direction"`
	Quarantine Quarantine `json:"quarantine"`
}

Divergence is the latest quarantine that the mirror of a service environment reported for one of its directions. It outlives the mirror run.

type DivergenceFilter 

type DivergenceFilter struct {
	Service     Option[string]
	Environment Option[string]
	Revision    Option[string]
	// Node matches only quarantines on routes of that migration state node.
	Node Option[string]
}

DivergenceFilter selects mirror states and divergences. An absent field matches every value.

func (DivergenceFilter) Matches 

func (f DivergenceFilter) Matches(divergence Divergence) bool

Matches reports whether divergence passes every field of the filter.

func (DivergenceFilter) MatchesState added in v0.47.0 

func (f DivergenceFilter) MatchesState(state State) bool

MatchesState reports whether state passes every field of the filter. A node filter needs one of its quarantines to match.

type IOKind 

type IOKind struct {
	Direction Direction
	Protocol  Protocol
}

IOKind is one kind of IO that a proxy intercepts, written "ingress[http]".

func (IOKind) String 

func (k IOKind) String() string

String returns the kind as written in the migration state, e.g. "ingress[http]".

type JSONType added in v0.52.0 

type JSONType string

JSONType is the type of a JSON value. 

const (
	JSONNull    JSONType = "null"
	JSONBoolean JSONType = "boolean"
	JSONNumber  JSONType = "number"
	JSONString  JSONType = "string"
	JSONObject  JSONType = "object"
	JSONList    JSONType = "list"
)

JSON types. A value's type never reveals the value itself.

type Protocol 

type Protocol string

Protocol names the protocol that a proxy intercepts, e.g. "http". 

const ProtocolHTTP Protocol = "http"

ProtocolHTTP is the protocol of HTTP servers, including gRPC and Connect.

type Quarantine 

type Quarantine struct {
	Reason QuarantineReason `json:"reason"` //nolint:narrowdeps // Other packages read the whole reason.
	Since  time.Time        `json:"since"`
}

Quarantine is a quarantine in effect: why it began and when.

type QuarantineKind 

type QuarantineKind string

QuarantineKind is why the candidate was quarantined. 

const (
	// QuarantineDivergent means the candidate's responses differ from the reference's.
	QuarantineDivergent QuarantineKind = "divergent"
	// QuarantineUnable means the mirror could not compare or replay traffic.
	QuarantineUnable QuarantineKind = "unable"
	// QuarantineUnmatched means the candidate made a dependency request the reference did not.
	QuarantineUnmatched QuarantineKind = "unmatched"
	// QuarantineUnlisted means an ingress route is in no node of the migration state.
	QuarantineUnlisted QuarantineKind = "unlisted"
	// QuarantineCapacity means candidate work exceeded a concurrency or buffer limit.
	QuarantineCapacity QuarantineKind = "capacity"
	// QuarantinePairing means the mirror could not pair candidate and reference traffic.
	QuarantinePairing QuarantineKind = "pairing"
)

type QuarantineReason 

type QuarantineReason struct {
	Kind QuarantineKind `json:"kind"`
	// Traffic is the request that triggered quarantine.
	Traffic Option[Traffic] `json:"traffic,omitzero"`
	// Node is the migration state node that owns an ingress route.
	Node Option[string] `json:"node,omitzero"`
	// Differences are where and how the responses of a divergence differ, without values.
	Differences []Difference `json:"differences,omitempty"`
	// Truncated means the responses had more differences than are listed.
	Truncated bool   `json:"truncated,omitzero"`
	Detail    string `json:"detail,omitempty"`
}

QuarantineReason is why the candidate was quarantined. Detail and Differences must never quote payload values, because reasons are reported outside the mirror.

func (QuarantineReason) String 

func (r QuarantineReason) String() string

String describes the reason for logs.

type QuarantineUpdate added in v0.48.0 

type QuarantineUpdate struct {
	Direction  Direction
	Quarantine Quarantine
}

QuarantineUpdate adds the quarantine of the proxy in Direction to the state.

type Retype added in v0.52.0 

type Retype struct {
	Reference JSONType `json:"reference"`
	Candidate JSONType `json:"candidate"`
}

Retype is the JSON types of a value whose type differs between the responses.

func (*Retype) UnmarshalJSON added in v0.52.0 

func (r *Retype) UnmarshalJSON(data []byte) error

UnmarshalJSON rejects unknown fields. Option decodes with json.Unmarshal, so a difference's retype must enforce strict decoding itself.

type Route 

type Route string

Route is a protocol's canonical request route, e.g. "GET forecasts.example/v1/forecasts/{location}". Equal routes must have identical text, because egress pairing hashes it.

type State added in v0.47.0 

type State struct {
	Service     string `json:"service"`
	Environment string `json:"environment"`
	// Revision is the commit of the candidate the mirror runs.
	Revision       string `json:"revision"`
	SpectreVersion string `json:"spectre_version"`
	// Uptime is how long the mirror has run. Without quarantines, the candidate
	// has been healthy that long, because quarantine lasts for the process.
	Uptime time.Duration `json:"uptime"`
	// Quarantines holds the quarantine of each direction whose proxy has one.
	Quarantines map[Direction]Quarantine `json:"quarantines,omitempty"`
	Calls       Calls                    `json:"calls,omitzero"`
}

State is what the mirror of a service environment runs and holds, as its latest update reported it.

func (State) Quarantined added in v0.48.0 

func (s State) Quarantined(direction Direction, quarantine Quarantine) State

Quarantined returns the state with the quarantine of the proxy in direction.

type Traffic 

type Traffic struct {
	Direction Direction `json:"direction"`
	Protocol  Protocol  `json:"protocol"`
	Route     Route     `json:"route"`
}

Traffic identifies one request route of a kind of IO.

func (*Traffic) UnmarshalJSON 

func (t *Traffic) UnmarshalJSON(data []byte) error

UnmarshalJSON rejects unknown fields. Option decodes with json.Unmarshal, so a reason's traffic must enforce strict decoding itself.

type Update added in v0.48.0 

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

Update is one message of the stream a mirror sends the SPECTRE server. Every stream begins with the mirror's whole State, and Calls replaces its counts.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.