Help us shape the future of Go! Take the 2026 Go Developer Survey

virtualkey

package
v0.7.0 Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source 
const GeneratedKeyPrefix = "vk-"

Variables

View Source 
var (
	ErrVirtualKeyNotCarried    = errors.New("virtual key is not carried")
	ErrVirtualKeyNotConfigured = errors.New("virtual key is not configured")
)

Functions

func DecodeStoredVirtualKey 

func DecodeStoredVirtualKey(data []byte) (any, error)

DecodeStoredVirtualKey decodes virtual key records.

func ExtractAPIKeys added in v0.2.0 

func ExtractAPIKeys(r *http.Request) []string

ExtractAPIKeys returns every candidate virtual-key value carried by the request, in precedence order. A request may legitimately present a key in both the `x-api-key` header and the `Authorization: Bearer` header (Claude Code, for example, always sends both — the gateway virtual key in one and an unrelated upstream key in the other), so callers must try each candidate rather than trusting a single header. Empty and duplicate values are omitted.

func GenerateKey 

func GenerateKey() (string, error)

Types

type Admission added in v0.5.0 

type Admission struct {
	BackendID         string
	BackendType       string
	Degraded          bool
	Allowed           bool
	RetryAfterSeconds int
	RequestsPerMinute int
	Burst             int
}

type Clock added in v0.5.0 

type Clock interface {
	Now() time.Time
}

type LimiterLabels added in v0.7.0 

type LimiterLabels struct{ Dimension, Outcome, BackendType string }

LimiterLabels contain bounded dimension, outcome and backend type only.

type RateLimit added in v0.5.0 

type RateLimit struct {
	RequestsPerMinute int `json:"requests_per_minute"`
	Burst             int `json:"burst"`
}

func (*RateLimit) UnmarshalJSON added in v0.5.0 

func (limit *RateLimit) UnmarshalJSON(data []byte) error

type RateLimitDimension added in v0.5.0 

type RateLimitDimension string
const (
	RateLimitDimensionLLM RateLimitDimension = "llm"
	RateLimitDimensionMCP RateLimitDimension = "mcp"
	// RateLimitDimensionAgent is the unified kind=agent ingress bucket.
	RateLimitDimensionAgent RateLimitDimension = "agent"
)

type VirtualKey 

type VirtualKey struct {
	ID          string `json:"id"`
	Key         string `json:"key"`
	Tag         string `json:"tag,omitempty"`
	Description string `json:"description,omitempty"`
	Disabled    bool   `json:"disabled"`

	AllowedRouteIDs []string              `json:"allowed_route_ids,omitempty"`
	RateLimits      *VirtualKeyRateLimits `json:"rate_limits,omitempty"`

	StatusMessage string    `json:"status_message,omitempty"`
	CreatedAt     time.Time `json:"created_at"`
	UpdatedAt     time.Time `json:"updated_at"`
	ExpiresAt     time.Time `json:"expires_at,omitempty"`
}

VirtualKey represents a gateway consumer identity, not an upstream provider credential.

func (*VirtualKey) NormalizeTimestamps 

func (key *VirtualKey) NormalizeTimestamps(now time.Time)

func (VirtualKey) Validate 

func (key VirtualKey) Validate() error

func (VirtualKey) ValidateConfiguration added in v0.5.0 

func (key VirtualKey) ValidateConfiguration() error

ValidateConfiguration validates policy fields independently of whether the key is currently enabled or expired.

func (VirtualKey) ValidateForRoute 

func (key VirtualKey) ValidateForRoute(routeID string) error

type VirtualKeyListOptions 

type VirtualKeyListOptions struct {
	Tag string
}

type VirtualKeyManager 

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

func NewVirtualKeyManager 

func NewVirtualKeyManager(store configstore.ConfigStore) *VirtualKeyManager

func NewVirtualKeyManagerWithClock added in v0.5.0 

func NewVirtualKeyManagerWithClock(store configstore.ConfigStore, clock Clock) *VirtualKeyManager

func (*VirtualKeyManager) Admit added in v0.5.0 

func (m *VirtualKeyManager) Admit(ctx context.Context, key VirtualKey, dimension RateLimitDimension) (Admission, error)

func (*VirtualKeyManager) Close added in v0.7.0 

func (m *VirtualKeyManager) Close(ctx context.Context) error

Close stops new admission and shares the caller's deadline with active calls.

func (*VirtualKeyManager) Create 

func (m *VirtualKeyManager) Create(ctx context.Context, key VirtualKey) error

func (*VirtualKeyManager) Delete 

func (m *VirtualKeyManager) Delete(ctx context.Context, id string) error

func (*VirtualKeyManager) GetByID 

func (m *VirtualKeyManager) GetByID(ctx context.Context, id string) (VirtualKey, error)

func (*VirtualKeyManager) GetByKey 

func (m *VirtualKeyManager) GetByKey(ctx context.Context, key string) (VirtualKey, error)

func (*VirtualKeyManager) LimiterCounters added in v0.7.0 

func (m *VirtualKeyManager) LimiterCounters() map[LimiterLabels]uint64

LimiterCounters returns an owned low-cardinality snapshot.

func (*VirtualKeyManager) List 

func (m *VirtualKeyManager) List(ctx context.Context, opts VirtualKeyListOptions) ([]VirtualKey, error)

func (*VirtualKeyManager) Reset 

func (m *VirtualKeyManager) Reset()

func (*VirtualKeyManager) SetExtensions added in v0.7.0 

func (m *VirtualKeyManager) SetExtensions(e *extension.Manager)

SetExtensions binds the already assembled extension manager during bootstrap.

func (*VirtualKeyManager) SetPublisher added in v0.7.0 

func (m *VirtualKeyManager) SetPublisher(p event.Publisher)

SetPublisher injects the existing event authority at bootstrap.

func (*VirtualKeyManager) Update 

func (m *VirtualKeyManager) Update(ctx context.Context, id string, key VirtualKey) error

type VirtualKeyRateLimits added in v0.5.0 

type VirtualKeyRateLimits struct {
	LLM   *RateLimit `json:"llm,omitempty"`
	MCP   *RateLimit `json:"mcp,omitempty"`
	Agent *RateLimit `json:"agent,omitempty"`
}

func (*VirtualKeyRateLimits) UnmarshalJSON added in v0.5.0 

func (limits *VirtualKeyRateLimits) UnmarshalJSON(data []byte) error

Source Files

View all Source files

Directories

Path Synopsis
Package limiter owns the candidate protected VirtualKey admission SPI.
 Package limiter owns the candidate protected VirtualKey admission SPI.
contracttest
Package contracttest provides reusable protected limiter conformance suites.
 Package contracttest provides reusable protected limiter conformance suites.

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.