snapshot

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jul 27, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	PolicyActionAllow         = "allow"
	PolicyActionDeny          = "deny"
	PolicyActionSetHeader     = "set_header"
	PolicyActionUseCredential = "use_credential"
)

Policy action kinds (THEN clause) — keep in sync with gatewayconfig.

View Source 
const (
	BackoffFixed       = "fixed"
	BackoffExponential = "exponential"
)

Backoff strategies for route retry (compiled snapshot).

View Source 
const (
	ScopeOrganization = "organization"
	ScopeTeam         = "team"
	ScopeProject      = "project"
	ScopeUser         = "user"
	ScopeAPIKey       = "api_key"

	MetricRequests = "requests"
	MetricTokens   = "tokens"

	WindowTotal  = "total"
	WindowMinute = "minute"
	WindowHour   = "hour"
	WindowDay    = "day"

	KeyKindPersonal       = "personal"
	KeyKindServiceAccount = "service_account"

	CredentialStorageEnv         = "env"
	CredentialStorageEncryptedDB = "encrypted_db"
	CredentialStorageVault       = "vault"
	CredentialStatusActive       = "active"
	CredentialStatusDisabled     = "disabled"
)

Snapshot is an immutable compiled gateway configuration.

View Source 
const (
	WasmPhaseBeforeCall = "before_call"
	WasmPhaseBeforeChat = "before_chat"
	WasmPhaseAfterCall  = "after_call"
)

Wasm hook phases in the compiled snapshot.

Variables

View Source 
var RequestWindows = []string{WindowMinute, WindowHour, WindowDay, WindowTotal}

RequestWindows are checked on every request (rate limits + lifetime).

Functions

func AssignmentKey 

func AssignmentKey(providerType, scopeType, scopeID string) string

AssignmentKey builds the snapshot assignment index key.

func DefaultAPIKeyEnv 

func DefaultAPIKeyEnv(typ string) string

DefaultAPIKeyEnv returns the usual env var name for a provider type.

func HashKey 

func HashKey(raw string) string

HashKey returns a hex-encoded SHA-256 of the raw virtual API key.

func ValidQuotaWindow 

func ValidQuotaWindow(window string) bool

ValidQuotaWindow reports whether window is supported.

Types

type A2AAgent 

type A2AAgent struct {
	ID             string          `json:"id"`
	OrganizationID string          `json:"organization_id"`
	Alias          string          `json:"alias"`
	Name           string          `json:"name"`
	UpstreamURL    string          `json:"upstream_url"`
	CardURL        string          `json:"card_url,omitempty"`
	CardCache      json.RawMessage `json:"card_cache,omitempty"`
	APIKeyEnv      string          `json:"api_key_env"`
	AuthScheme     string          `json:"auth_scheme,omitempty"`
	Enabled        bool            `json:"enabled"`
	InlineAPIKey   string          `json:"-"`
}

A2AAgent is a compiled A2A upstream agent.

type APIKey 

type APIKey struct {
	KeyHash        string `json:"key_hash"`
	KeyPrefix      string `json:"key_prefix"`
	ProjectID      string `json:"project_id,omitempty"`
	TeamID         string `json:"team_id,omitempty"`
	EnvironmentID  string `json:"environment_id,omitempty"`
	OrganizationID string `json:"organization_id"`
	Name           string `json:"name"`
	ID             string `json:"id,omitempty"`
	Kind           string `json:"kind,omitempty"`
	OwnerUserID    string `json:"owner_user_id,omitempty"`
}

type BackoffConfig 

type BackoffConfig struct {
	Strategy   string  `json:"strategy"`
	BaseDelay  string  `json:"base_delay"`
	MaxDelay   string  `json:"max_delay,omitempty"`
	Multiplier float64 `json:"multiplier,omitempty"`
}

BackoffConfig selects the delay between retry attempts.

type Credential 

type Credential struct {
	ID               string `json:"id"`
	OrganizationID   string `json:"organization_id,omitempty"`
	Name             string `json:"name,omitempty"`
	ProviderType     string `json:"provider_type"`
	StorageKind      string `json:"storage_kind"`
	SecretRef        string `json:"secret_ref,omitempty"`
	EncryptedPayload []byte `json:"encrypted_payload,omitempty"`
	KeyVersion       int    `json:"key_version,omitempty"`
	Status           string `json:"status"`
}

Credential is a compiled upstream secret reference (never plaintext for encrypted_db).

type CredentialAssignment 

type CredentialAssignment struct {
	CredentialID string
	ProviderType string
	ScopeType    string
	ScopeID      string
}

CredentialAssignment is a compile-time binding of credential → scope.

type MCPBackend 

type MCPBackend struct {
	ID              string   `json:"id"`
	OrganizationID  string   `json:"organization_id"`
	Alias           string   `json:"alias"`
	Name            string   `json:"name"`
	BaseURL         string   `json:"base_url"`
	APIKeyEnv       string   `json:"api_key_env"`
	MethodAllowlist []string `json:"method_allowlist,omitempty"`
	Enabled         bool     `json:"enabled"`
	// InlineAPIKey is request-scoped; set by the gateway after secret resolution.
	InlineAPIKey string `json:"-"`
}

MCPBackend is a compiled MCP Streamable HTTP upstream.

type ObjectStoreConfig 

type ObjectStoreConfig struct {
	Enabled           bool   `json:"enabled"`
	Endpoint          string `json:"endpoint,omitempty"`
	Region            string `json:"region,omitempty"`
	Bucket            string `json:"bucket,omitempty"`
	UseSSL            bool   `json:"use_ssl"`
	PathStyle         bool   `json:"path_style"`
	CredentialID      string `json:"credential_id,omitempty"`
	AccessKeyEnv      string `json:"access_key_env,omitempty"`
	SecretKeyEnv      string `json:"secret_key_env,omitempty"`
	PresignTTLSeconds int    `json:"presign_ttl_seconds,omitempty"`
}

ObjectStoreConfig is compiled per-org optional S3 asset persistence.

type Policy 

type Policy struct {
	ID             string         `json:"id"`
	OrganizationID string         `json:"organization_id"`
	Name           string         `json:"name"`
	Expression     string         `json:"expression"`
	Actions        []PolicyAction `json:"actions"`
	Enabled        bool           `json:"enabled"`
	Priority       int            `json:"priority"`
}

Policy is a when/then CEL rule compiled into the gateway snapshot. WHEN Expression is true, THEN Actions run in order.

func (Policy) EffectiveActions 

func (p Policy) EffectiveActions() []PolicyAction

EffectiveActions returns Then steps for evaluation.

type PolicyAction 

type PolicyAction struct {
	Type   string `json:"type"`
	Config []byte `json:"config,omitempty"`
}

PolicyAction is one Then step compiled into the snapshot.

type Provider 

type Provider struct {
	ID           string               `json:"id"`
	Type         string               `json:"type"` // openai | anthropic | gemini | openai_compatible | …
	BaseURL      string               `json:"base_url"`
	APIKeyEnv    string               `json:"api_key_env"`
	Name         string               `json:"name"`
	Capabilities ProviderCapabilities `json:"capabilities"`
	// Config is opaque provider-type settings (e.g. azure_openai api_style).
	Config json.RawMessage `json:"config,omitempty"`
	// InlineAPIKey is request-scoped; set by the gateway after credential resolution.
	// Never persisted in snapshots (json:"-").
	InlineAPIKey string `json:"-"`
}

type ProviderCapabilities 

type ProviderCapabilities struct {
	Chat      bool `json:"chat"`
	Stream    bool `json:"stream"`
	TTS       bool `json:"tts"`
	STT       bool `json:"stt"`
	Embedding bool `json:"embedding"`
	Image     bool `json:"image"`
}

ProviderCapabilities describes what a provider adapter can do.

func DefaultCapabilities 

func DefaultCapabilities(typ string) ProviderCapabilities

DefaultCapabilities returns catalog defaults for a provider type.

func NormalizeCapabilities 

func NormalizeCapabilities(typ string, c ProviderCapabilities) ProviderCapabilities

NormalizeCapabilities fills empty capabilities from the type catalog.

type Quota 

type Quota struct {
	ID             string `json:"id"`
	OrganizationID string `json:"organization_id"`
	ScopeType      string `json:"scope_type"`
	ScopeID        string `json:"scope_id"`
	Metric         string `json:"metric"`
	LimitValue     int64  `json:"limit_value"`
	Window         string `json:"window"`
}

type RetryConfig 

type RetryConfig struct {
	MaxAttempts int           `json:"max_attempts"`
	Backoff     BackoffConfig `json:"backoff"`
}

RetryConfig controls same-target retries before failover. Nil means no same-target retries (single attempt per route target).

func (*RetryConfig) Delay 

func (c *RetryConfig) Delay(n int) time.Duration

Delay returns the wait before retry attempt index n (0 = first retry after the initial failure).

type Route 

type Route struct {
	OrganizationID  string        `json:"organization_id"`
	Model           string        `json:"model"`
	ProviderID      string        `json:"provider_id"`
	TargetModel     string        `json:"target_model"`
	Fallbacks       []RouteTarget `json:"fallbacks,omitempty"`
	Retry           *RetryConfig  `json:"retry,omitempty"`
	RoutingStrategy string        `json:"routing_strategy,omitempty"`
	Weight          int           `json:"weight,omitempty"`
}

type RouteTarget 

type RouteTarget struct {
	ProviderID  string `json:"provider_id"`
	TargetModel string `json:"target_model"`
	Weight      int    `json:"weight,omitempty"`
}

RouteTarget is a provider + model pair used for primary routing or failover.

type Snapshot 

type Snapshot struct {
	Version        int64                         `json:"version"`
	CreatedAt      time.Time                     `json:"created_at"`
	APIKeys        map[string]APIKey             `json:"api_keys"`    // keyed by key hash
	Providers      map[string]Provider           `json:"providers"`   // keyed by provider id
	Routes         map[string]Route              `json:"routes"`      // keyed by orgID + "::" + model
	Credentials    map[string]Credential         `json:"credentials"` // keyed by credential id
	Assignments    map[string]string             `json:"assignments"` // providerType::scopeType::scopeID → credential id
	Quotas         []Quota                       `json:"quotas"`
	Policies       []Policy                      `json:"policies"`
	WasmHooks      []WasmHook                    `json:"wasm_hooks"`
	MCPBackends    map[string]MCPBackend         `json:"mcp_backends,omitempty"`    // keyed by backend id
	MCPRoutes      map[string]string             `json:"mcp_routes,omitempty"`      // orgID::alias → backend id
	A2AAgents      map[string]A2AAgent           `json:"a2a_agents,omitempty"`      // keyed by agent id
	A2ARoutes      map[string]string             `json:"a2a_routes,omitempty"`      // orgID::alias → agent id
	DefaultRetries map[string]*RetryConfig       `json:"default_retries,omitempty"` // orgID → default retry
	ObjectStores   map[string]*ObjectStoreConfig `json:"object_stores,omitempty"`   // orgID → optional asset store
}

func Compile 

func Compile(src Source) *Snapshot

Compile builds an immutable snapshot payload (version assigned by store on Put).

func (*Snapshot) LookupA2AAgent 

func (s *Snapshot) LookupA2AAgent(orgID, alias string) (A2AAgent, bool)

LookupA2AAgent resolves an org-scoped A2A alias to a compiled agent.

func (*Snapshot) LookupCredentialByName 

func (s *Snapshot) LookupCredentialByName(orgID, providerType, name string) (Credential, bool)

LookupCredentialByName finds an active credential in the org by display name + provider type. Names are matched case-sensitively after trim (same uniqueness as provider_credentials).

func (*Snapshot) LookupKey 

func (s *Snapshot) LookupKey(raw string) (APIKey, bool)

func (*Snapshot) LookupMCPBackend 

func (s *Snapshot) LookupMCPBackend(orgID, alias string) (MCPBackend, bool)

LookupMCPBackend resolves an org-scoped MCP alias to a compiled backend.

func (*Snapshot) LookupRoute 

func (s *Snapshot) LookupRoute(orgID, model string) (Route, Provider, bool)

func (*Snapshot) ResolveCredential 

func (s *Snapshot) ResolveCredential(providerType string, key APIKey) (Credential, bool)

ResolveCredential picks the most specific active credential for a provider type (api_key → project → organization). Returns false when no assignment matches.

func (*Snapshot) ResolveCredentialForCall 

func (s *Snapshot) ResolveCredentialForCall(providerType string, key APIKey, overrideName string) (cred Credential, ok bool, missingOverride bool)

ResolveCredentialForCall resolves BYOK for a call. When overrideName is non-empty (from a matching select-credential policy), that name selects a credential in the org for the provider type. Otherwise falls back to assignment scopes: api_key → project → organization.

If overrideName is set but no matching credential exists, ok=false and missingOverride=true so the gateway can fail closed instead of using the platform key.

func (*Snapshot) ResolveObjectStore 

func (s *Snapshot) ResolveObjectStore(orgID string) *ObjectStoreConfig

ResolveObjectStore returns the org object-store config when present.

func (*Snapshot) ResolveQuota 

func (s *Snapshot) ResolveQuota(key APIKey, metric, window string) (Quota, bool)

ResolveQuota picks the most specific matching quota for the metric and window (api_key > user > project > team > organization).

func (*Snapshot) ResolveRetry 

func (s *Snapshot) ResolveRetry(route Route) *RetryConfig

ResolveRetry returns the effective retry for a route: route-specific, else org default, else nil.

type Source 

type Source struct {
	APIKeys        []APIKey
	Providers      []Provider
	Routes         []Route
	Credentials    []Credential
	Assignments    []CredentialAssignment
	Quotas         []Quota
	Policies       []Policy
	WasmHooks      []WasmHook
	MCPBackends    []MCPBackend
	A2AAgents      []A2AAgent
	DefaultRetries map[string]*RetryConfig       // orgID → default
	ObjectStores   map[string]*ObjectStoreConfig // orgID → optional asset store
}

Source is the control-plane view used to compile a snapshot.

type Store 

type Store interface {
	Put(ctx context.Context, snap *Snapshot) (int64, error)
	Latest(ctx context.Context) (*Snapshot, error)
	Watch(ctx context.Context, pollInterval time.Duration, onUpdate func(*Snapshot)) error
}

Store is the persistence port for compiled gateway snapshots. Adapters live under internal/adapters (e.g. postgres).

type WasmHook 

type WasmHook struct {
	ID             string          `json:"id"`
	OrganizationID string          `json:"organization_id"`
	Name           string          `json:"name"`
	Phase          string          `json:"phase"` // before_call | before_chat | after_call
	ModuleURI      string          `json:"module_uri"`
	Digest         string          `json:"digest,omitempty"` // sha256 hex; empty skips verify
	Enabled        bool            `json:"enabled"`
	Priority       int             `json:"priority"`
	Config         json.RawMessage `json:"config,omitempty"`
}

WasmHook is a compiled sandboxed lifecycle binding for the gateway.

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.