snapshot

package
v0.3.1 Latest Latest
Warning

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

 Go to latest Published: Aug 2, 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"
	AuthMethodAPIKey             = "api_key"
	AuthMethodSignedRequest      = "signed_request"
)

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 Principal added in v0.3.0 

type Principal struct {
	OrganizationID string `json:"organization_id"`
	ProjectID      string `json:"project_id,omitempty"`
	TeamID         string `json:"team_id,omitempty"`
	EnvironmentID  string `json:"environment_id,omitempty"`
	APIKeyID       string `json:"api_key_id,omitempty"`
	SigningKeyID   string `json:"signing_key_id,omitempty"`
	KeyID          string `json:"key_id,omitempty"`
	AuthMethod     string `json:"auth_method"`
	Kind           string `json:"kind,omitempty"`
	OwnerUserID    string `json:"owner_user_id,omitempty"`
	Name           string `json:"name,omitempty"`
}

Principal is the normalized gateway identity after authentication.

func PrincipalFromAPIKey added in v0.3.0 

func PrincipalFromAPIKey(key APIKey) Principal

func PrincipalFromSigningKey added in v0.3.0 

func PrincipalFromSigningKey(key SigningKey) Principal

func (Principal) PolicyKey added in v0.3.0 

func (p Principal) PolicyKey() APIKey

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 SigningKey added in v0.3.0 

type SigningKey struct {
	ID             string `json:"id"`
	KeyID          string `json:"key_id"`
	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"`
	Algorithm      string `json:"algorithm"`
	PublicKeyPEM   string `json:"public_key_pem"`
	Status         string `json:"status"`
}

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
	SigningKeys    map[string]SigningKey         `json:"signing_keys"` // keyed by key id
	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
	// AllowedOrganizationIDs is set on region-scoped snapshots. Nil means unrestricted (global snapshot).
	AllowedOrganizationIDs []string `json:"allowed_organization_ids,omitempty"`
}

func Compile 

func Compile(src Source) *Snapshot

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

func CompileRegion added in v0.3.0 

func CompileRegion(src Source, allowedOrgIDs []string) *Snapshot

CompileRegion builds a snapshot and sets the org allowlist (always non-nil, may be empty).

func (*Snapshot) AllowsOrganization added in v0.3.0 

func (s *Snapshot) AllowsOrganization(orgID string) bool

AllowsOrganization reports whether orgID may use this snapshot. Nil allowlist (global snapshot) allows all; non-nil enforces membership.

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) LookupSigningKey added in v0.3.0 

func (s *Snapshot) LookupSigningKey(keyID string) (SigningKey, 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
	SigningKeys    []SigningKey
	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.