stuber

package
v3.7.7 Latest Latest
Warning

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

Go to latest
Published: Feb 19, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// EmptySpecificity is returned when no fields match.
	EmptySpecificity = 0
	// MinStreamLength is the minimum length for stream calculations.
	MinStreamLength = 0
)

Specificity calculation constants.

View Source
const MethodTitle features.Flag = iota

MethodTitle is a feature flag for using title casing in the method field of a Query struct.

View Source
const PriorityMultiplier = 10.0

PriorityMultiplier is used to boost stub priority in ranking calculations. Higher values give more weight to explicit priority settings.

View Source
const (
	// RequestInternalFlag is a feature flag for internal requests.
	RequestInternalFlag features.Flag = iota
)

Variables

View Source
var ErrLeftNotFound = errors.New("left not found")

ErrLeftNotFound is returned when the left value is not found.

View Source
var ErrMethodNotFound = errors.New("method not found")

ErrMethodNotFound is returned when the method is not found.

View Source
var ErrRightNotFound = errors.New("right not found")

ErrRightNotFound is returned when the right value is not found.

View Source
var ErrServiceNotFound = errors.New("service not found")

ErrServiceNotFound is returned when the service is not found.

View Source
var ErrStubNotFound = errors.New("stub not found")

ErrStubNotFound is returned when the stub is not found.

Functions

func ClearAllCaches

func ClearAllCaches()

ClearAllCaches clears all LRU caches (for testing purposes).

Types

type BidiResult

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

BidiResult holds matching stubs for bidirectional streaming.

func (*BidiResult) GetMessageIndex

func (br *BidiResult) GetMessageIndex() int

GetMessageIndex returns the current message index in the bidirectional stream.

func (*BidiResult) Next

func (br *BidiResult) Next(messageData map[string]any) (*Stub, error)

Next processes the next message in the bidirectional stream and returns the matching stub.

type Budgerigar

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

Budgerigar is the main struct for the stuber package. It contains a searcher and toggles.

func NewBudgerigar

func NewBudgerigar(toggles features.Toggles) *Budgerigar

NewBudgerigar creates a new Budgerigar with the given features.Toggles.

func (*Budgerigar) All

func (b *Budgerigar) All() []*Stub

All returns all Stub values.

func (*Budgerigar) Clear

func (b *Budgerigar) Clear()

Clear removes all Stub values.

func (*Budgerigar) DeleteByID

func (b *Budgerigar) DeleteByID(ids ...uuid.UUID) int

DeleteByID deletes the Stub values with the given IDs from the Budgerigar's searcher.

func (*Budgerigar) DeleteSession added in v3.7.1

func (b *Budgerigar) DeleteSession(session string) int

DeleteSession deletes all stubs that belong to the provided session. Empty session is treated as global and is not deleted by this method.

func (*Budgerigar) FindBy

func (b *Budgerigar) FindBy(service, method string) ([]*Stub, error)

FindBy retrieves all Stub values that match the given service and method from the Budgerigar's searcher, sorted by priority score in descending order.

func (*Budgerigar) FindByID

func (b *Budgerigar) FindByID(id uuid.UUID) *Stub

FindByID retrieves the Stub value associated with the given ID.

func (*Budgerigar) FindByQuery

func (b *Budgerigar) FindByQuery(query Query) (*Result, error)

FindByQuery retrieves the Stub value associated with the given Query.

func (*Budgerigar) FindByQueryBidi

func (b *Budgerigar) FindByQueryBidi(query QueryBidi) (*BidiResult, error)

FindByQueryBidi retrieves a BidiResult for bidirectional streaming.

func (*Budgerigar) PutMany

func (b *Budgerigar) PutMany(values ...*Stub) []uuid.UUID

PutMany inserts the given Stub values. Assigns UUIDs to stubs without IDs.

func (*Budgerigar) Unused

func (b *Budgerigar) Unused() []*Stub

Unused returns all Stub values that have not been used.

func (*Budgerigar) UpdateMany

func (b *Budgerigar) UpdateMany(values ...*Stub) []uuid.UUID

UpdateMany updates stubs that have non-nil IDs.

func (*Budgerigar) Used

func (b *Budgerigar) Used() []*Stub

Used returns all Stub values that have been used.

type InputData

type InputData struct {
	IgnoreArrayOrder bool           `json:"ignoreArrayOrder,omitempty"` // Whether to ignore the order of arrays in the input data.
	Equals           map[string]any `json:"equals"`                     // The data to match exactly.
	Contains         map[string]any `json:"contains"`                   // The data to match partially.
	Matches          map[string]any `json:"matches"`                    // The data to match using regular expressions.
}

InputData represents the input data of a gRPC request.

func (InputData) GetContains

func (i InputData) GetContains() map[string]any

GetContains returns the data to match partially.

func (InputData) GetEquals

func (i InputData) GetEquals() map[string]any

GetEquals returns the data to match exactly.

func (InputData) GetMatches

func (i InputData) GetMatches() map[string]any

GetMatches returns the data to match using regular expressions.

type InputHeader

type InputHeader struct {
	Equals   map[string]any `json:"equals"`   // The headers to match exactly.
	Contains map[string]any `json:"contains"` // The headers to match partially.
	Matches  map[string]any `json:"matches"`  // The headers to match using regular expressions.
}

InputHeader represents the headers of a gRPC request.

func (InputHeader) GetContains

func (i InputHeader) GetContains() map[string]any

GetContains returns the headers to match partially.

func (InputHeader) GetEquals

func (i InputHeader) GetEquals() map[string]any

GetEquals returns the headers to match exactly.

func (InputHeader) GetMatches

func (i InputHeader) GetMatches() map[string]any

GetMatches returns the headers to match using regular expressions.

func (InputHeader) Len

func (i InputHeader) Len() int

Len returns the total number of headers to match.

type Output

type Output struct {
	Headers map[string]string `json:"headers"`          // The headers of the response.
	Data    map[string]any    `json:"data,omitempty"`   // The data of the response.
	Stream  []any             `json:"stream,omitempty"` // The stream data for server-side streaming.
	// Each element represents a message to be sent.
	Error string         `json:"error"`           // The error message of the response.
	Code  *codes.Code    `json:"code,omitempty"`  // The status code of the response.
	Delay types.Duration `json:"delay,omitempty"` // The delay of the response or error.
}

Output represents the output data of a gRPC response.

type Query

type Query struct {
	ID      *uuid.UUID       `json:"id,omitempty"`      // The unique identifier of the stub (optional).
	Service string           `json:"service"`           // The service name to search for.
	Method  string           `json:"method"`            // The method name to search for.
	Session string           `json:"session,omitempty"` // Session ID (empty = global only).
	Headers map[string]any   `json:"headers"`           // The headers to match.
	Input   []map[string]any `json:"input"`             // The input data to match (unary or streaming).
	// contains filtered or unexported fields
}

Query represents a query for finding stubs. Supports both unary (Input with one element) and streaming (Input with multiple elements). JSON accepts "data" (legacy, maps to Input[0]) or "input" (array). Prefer "input".

func NewQuery

func NewQuery(r *http.Request) (Query, error)

NewQuery creates a new Query from an HTTP request. Supports both legacy "data" (single object) and "input" (array) in JSON body.

func NewQueryFromInput added in v3.6.0

func NewQueryFromInput(service, method string, input []map[string]any, headers map[string]any) Query

NewQueryFromInput creates a Query with the given input data (convenience for programmatic use).

func (*Query) Data

func (q *Query) Data() map[string]any

Data returns the first input element for backward compatibility with legacy unary API. Returns nil if Input is empty.

func (*Query) RequestInternal

func (q *Query) RequestInternal() bool

RequestInternal returns true if the query is marked as internal.

func (*Query) UnmarshalJSON added in v3.6.0

func (q *Query) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler to support both "data" and "input" in request body.

type QueryBidi

type QueryBidi struct {
	ID      *uuid.UUID     `json:"id,omitempty"`      // The unique identifier of the stub (optional).
	Service string         `json:"service"`           // The service name to search for.
	Method  string         `json:"method"`            // The method name to search for.
	Session string         `json:"session,omitempty"` // Session ID (empty = global only).
	Headers map[string]any `json:"headers"`           // The headers to match.
	// contains filtered or unexported fields
}

QueryBidi represents a query for bidirectional streaming. In bidirectional streaming, each message is treated as a separate unary request. The server can respond with multiple messages for each request.

func NewQueryBidi

func NewQueryBidi(r *http.Request) (QueryBidi, error)

NewQueryBidi creates a new QueryBidi from an HTTP request.

func (QueryBidi) RequestInternal

func (q QueryBidi) RequestInternal() bool

RequestInternal returns true if the query is marked as internal.

type Result

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

Result holds the search result: exact match (Found) or best similar (Similar).

func (*Result) Found

func (r *Result) Found() *Stub

Found returns the exact match found in the search.

func (*Result) Similar

func (r *Result) Similar() *Stub

Similar returns the most similar match found in the search.

type Stub

type Stub struct {
	ID       uuid.UUID   `json:"id"`                                               // The unique identifier of the stub.
	Service  string      `json:"service"           validate:"required"`            // The name of the service.
	Method   string      `json:"method"            validate:"required"`            // The name of the method.
	Session  string      `json:"session,omitempty"`                                // Session ID for isolation (empty = global).
	Priority int         `json:"priority"`                                         // The priority score of the stub.
	Options  StubOptions `json:"options,omitempty"`                                //nolint:modernize
	Headers  InputHeader `json:"headers"`                                          // The headers of the request.
	Input    InputData   `json:"input"             validate:"valid_input_config"`  // Unary input (mutually exclusive with Inputs).
	Inputs   []InputData `json:"inputs,omitempty"  validate:"valid_input_config"`  // Client streaming inputs (mutually exclusive with Input).
	Output   Output      `json:"output"            validate:"valid_output_config"` // The output data of the response.
}

Stub represents a gRPC service method and its associated data.

func (*Stub) EffectiveTimes added in v3.7.0

func (s *Stub) EffectiveTimes() int

EffectiveTimes returns the stub's max match count; 0 means unlimited.

func (*Stub) IsBidirectional

func (s *Stub) IsBidirectional() bool

IsBidirectional returns true if this stub can handle bidirectional streaming. For bidirectional streaming, the stub should have Inputs data (for input matching) and Output.Stream data (for output).

func (*Stub) IsClientStream

func (s *Stub) IsClientStream() bool

IsClientStream returns true if this stub is for client streaming requests (has Inputs data).

func (*Stub) IsServerStream

func (s *Stub) IsServerStream() bool

IsServerStream returns true if this stub is for server streaming responses (has Output.Stream data).

func (*Stub) IsUnary

func (s *Stub) IsUnary() bool

IsUnary returns true if this stub is for unary requests (has Input data).

func (*Stub) Key

func (s *Stub) Key() uuid.UUID

Key returns the unique identifier of the stub.

func (*Stub) Left

func (s *Stub) Left() string

Left returns the service name of the stub.

func (*Stub) Right

func (s *Stub) Right() string

Right returns the method name of the stub.

func (*Stub) Score

func (s *Stub) Score() int

Score returns the priority score of the stub.

type StubOptions added in v3.7.0

type StubOptions struct {
	Times int `json:"times,omitempty" validate:"gte=0"` // Max number of matches; 0 = unlimited.
}

StubOptions holds optional behavior settings for a stub.

Jump to

Keyboard shortcuts

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