comparison

package
v0.23.1 Latest Latest
Warning

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

Go to latest
Published: Oct 7, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Overview

Package comparison compares paired unary RPC responses and hashes RPC requests.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Comparator

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

Comparator compares ingress response pairs with the ingress script endpoints.

func New

func New(ctx context.Context, config Config, log *slog.Logger) (*Comparator, error)

New constructs a response comparator from its parsed configuration.

func (*Comparator) Compare

func (c *Comparator) Compare(
	ctx context.Context,
	requestMethod string,
	requestPath string,
	requestContentType string,
	reference Response,
	candidate Response,
) (result Result)

Compare compares one response pair without exposing response values in its result. requestPath must be escaped, as endpoints match it the way ServeMux does.

func (*Comparator) Configure

Configure activates the comparator against the wire descriptors.

func (*Comparator) MaxResponseBytes

func (c *Comparator) MaxResponseBytes() int

MaxResponseBytes returns the per-backend response capture limit.

type Config

type Config struct {
	// ScriptsDir holds the normaliser scripts, which are all loaded as one set.
	ScriptsDir string `` /* 165-byte string literal not displayed */
	// Schema types every payload the scripts register for.
	Schema schema.Config `embed:""`
	// ComparisonTimeout limits one response comparison.
	ComparisonTimeout time.Duration `default:"1s" help:"Maximum duration of one response comparison."`
	// ComparisonMaxBodyBytes limits each captured request or response body.
	ComparisonMaxBodyBytes int `default:"1048576" help:"Maximum captured body bytes per request or response."`
}

Config contains the command-line configuration for response comparison.

func NewConfig

func NewConfig() Config

NewConfig returns the default response comparison configuration.

func (Config) Validate

func (c Config) Validate() error

Validate checks that the comparison configuration is usable.

type Outcome

type Outcome string

Outcome describes whether a response pair could be compared and matched.

const (
	// Equivalent means the supported response pair matched.
	Equivalent Outcome = "equivalent"
	// Divergent means the supported response pair did not match.
	Divergent Outcome = "divergent"
	// Skipped means the request is outside the supported protocol scope.
	Skipped Outcome = "skipped"
	// Unable means a supported request could not be compared safely.
	Unable Outcome = "unable"
)

type Request added in v0.14.0

type Request struct {
	// Method is the HTTP request method.
	Method string
	// Host selects the destination's endpoints. Any port is ignored.
	Host string
	// Path is escaped, as endpoints match it the way ServeMux does.
	Path string
	// RawQuery is the encoded query string without the leading "?".
	RawQuery string
	// Header holds the request headers.
	Header http.Header
	// Body contains at most the configured capture limit.
	Body []byte
	// Overflow reports that Body is truncated and must not be hashed.
	Overflow bool
	// Side labels log records, such as "reference" or "candidate". It is not hashed.
	Side string
}

Request is one captured request to a dependency.

type RequestHash added in v0.14.0

type RequestHash [sha256.Size]byte

RequestHash identifies a request by its endpoint and normalised input, so equivalent requests share a hash.

type RequestHasher added in v0.14.0

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

RequestHasher identifies egress requests by their normalised input, using the egress script endpoints.

func NewRequestHasher added in v0.14.0

func NewRequestHasher(ctx context.Context, config Config, log *slog.Logger) (*RequestHasher, error)

NewRequestHasher constructs a request hasher from its parsed configuration.

func (*RequestHasher) Configure added in v0.14.0

Configure validates endpoint types and bindings before activating the hasher.

func (*RequestHasher) Hash added in v0.14.0

func (h *RequestHasher) Hash(ctx context.Context, request Request) (RequestHash, error)

Hash returns SHA-256 over the endpoint or method name and the canonical JSON of the normalised input. An error means the request cannot be identified.

func (*RequestHasher) MaxRequestBytes added in v0.15.0

func (h *RequestHasher) MaxRequestBytes() int

MaxRequestBytes returns the request body capture limit.

type Response

type Response struct {
	// StatusCode is the backend's HTTP status before RPC-level status handling.
	StatusCode int
	// Header includes response trailers promoted by the HTTP transport.
	Header http.Header
	// Body contains at most the configured capture limit.
	Body []byte
	// Overflow reports that Body is truncated and must not be compared.
	Overflow bool
}

Response is the captured result from one backend.

type Result

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

Result is the value-safe result of comparing two responses.

func NewDifferenceResult

func NewDifferenceResult(differences ...string) Result

NewDifferenceResult constructs a divergent result without exposing response values.

func Resultf

func Resultf(outcome Outcome, format string, args ...any) Result

Resultf constructs a result with a printf-formatted reason.

func (Result) Differences

func (r Result) Differences() []string

Differences returns a copy of the divergent JSON paths.

func (Result) Outcome

func (r Result) Outcome() Outcome

Outcome returns the comparison classification.

func (Result) Reason

func (r Result) Reason() string

Reason returns why comparison was skipped or could not be completed.

Directories

Path Synopsis
Package javascript evaluates Spectre payload normaliser scripts.
Package javascript evaluates Spectre payload normaliser scripts.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL