proxy

Documentation

Overview

Package proxy implements the gateway's HTTP pipeline: route, forward, meter. It holds no state beyond config and hooks — no database.

Index

• Constants
• Variables
• func CheckCapability(p config.Provider, providerName, modality string) error
• func CheckCapabilityErr(p config.Provider, providerName, modality string) error
• type CachingTokenSource
  • func (c *CachingTokenSource) Invalidate()
  • func (c *CachingTokenSource) Token(ctx context.Context) (string, error)
• type CapabilityError
  • func (e *CapabilityError) Error() string
• type FileTokenSource
  • func (f FileTokenSource) Token(context.Context) (string, error)
• type FuncTokenSource
  • func (f FuncTokenSource) Token(ctx context.Context) (string, error)
• type OAuth2TokenSource
  • func NewOAuth2TokenSource(o *config.OAuthConfig) (*OAuth2TokenSource, error)
  • func (o *OAuth2TokenSource) Token(ctx context.Context) (string, error)
  • func (o *OAuth2TokenSource) TokenWithExpiry(ctx context.Context) (string, time.Time, error)
• type Route
  • func Resolve(cfg *config.Config, dialect, model string) (Route, error)
  • func ResolveForModality(cfg *config.Config, dialect, model, modality string) (Route, error)
  • func ResolveProvider(cfg *config.Config, name string) (Route, error)
• type Server
  • func NewServer(cfg *config.Config, hook hooks.Hook) *Server
  • func (s *Server) Handler() http.Handler
  • func (s *Server) SetTokenSource(provider string, ts TokenSource)
• type ServiceAccountJWTSource
  • func NewServiceAccountJWTSourceFromFile(path string, scopes []string) (*ServiceAccountJWTSource, error)
  • func NewServiceAccountJWTSourceFromJSON(raw []byte, scopes []string) (*ServiceAccountJWTSource, error)
  • func (s *ServiceAccountJWTSource) Token(ctx context.Context) (string, error)
  • func (s *ServiceAccountJWTSource) TokenWithExpiry(ctx context.Context) (string, time.Time, error)
• type StaticTokenSource
  • func (s StaticTokenSource) Token(context.Context) (string, error)
• type TokenSource

Constants

const (
	DialectOpenAI    = "openai"
	DialectAnthropic = "anthropic"
	DialectGoogle    = "google"
)

Dialect names used for default-provider lookup and usage events.

const (
	CodeUnsupportedProviderCapability = "unsupported_provider_capability"
	CodeUnsupportedModality           = "unsupported_modality"
	CodeUnsupportedRealtimeBridge     = "unsupported_realtime_bridge"
	CodeInvalidRequest                = "invalid_request_error"
	CodeInvalidMediaRequest           = "invalid_media_request"
	CodeUpstreamError                 = "upstream_error"
)

Gateway logical error codes mapped into dialect envelopes.

const DefaultGoogleTokenURL = "https://oauth2.googleapis.com/token"

DefaultGoogleTokenURL is used when the SA JSON omits token_uri.

const DefaultOAuthSkew = 30 * time.Second

DefaultOAuthSkew is subtracted from expires_in when caching so tokens are refreshed slightly before absolute expiry.

const ModalityEmbedding = "embedding"

ModalityEmbedding is the UsageEvent.Modality value for embedding requests.

Variables

var DefaultGoogleSAScopes = []string{"https://www.googleapis.com/auth/cloud-platform"}

DefaultGoogleSAScopes is used when no scopes are configured.

Functions

func CheckCapability

func CheckCapability(p config.Provider, providerName, modality string) error

CheckCapability fails closed when the provider cannot serve modality. Callers map a non-nil error into a dialect envelope with type unsupported_provider_capability and must not call upstream.

func CheckCapabilityErr

func CheckCapabilityErr(p config.Provider, providerName, modality string) error

CheckCapability returns a CapabilityError when unsupported.

Types

type CachingTokenSource

type CachingTokenSource struct {
	Inner TokenSource
	TTL   time.Duration // default 5m when zero and inner has no expiry
	// contains filtered or unexported fields
}

CachingTokenSource wraps a source and reuses tokens until Expiry (or a fixed TTL when the inner source does not expose expiry). Concurrent callers share one in-flight refresh via singleflight-style mutex.

When Inner implements tokenWithExpiry, the real expires_in-derived expiry is used; otherwise TTL (default 5m) applies.

func (*CachingTokenSource) Invalidate

func (c *CachingTokenSource) Invalidate()

Invalidate clears the cache so the next Token() call refreshes (401 retry).

func (*CachingTokenSource) Token

func (c *CachingTokenSource) Token(ctx context.Context) (string, error)

type CapabilityError

type CapabilityError struct {
	Msg string
}

func (*CapabilityError) Error

func (e *CapabilityError) Error() string

type FileTokenSource

type FileTokenSource struct {
	Path string
}

FileTokenSource reads a bearer access token from a filesystem path. Intended for WIF sidecars / projected volume tokens that refresh the file out-of-band (#164). The file is re-read on every Token() call; wrap with CachingTokenSource when a short TTL is desired.

func (FileTokenSource) Token

func (f FileTokenSource) Token(context.Context) (string, error)

type FuncTokenSource

type FuncTokenSource func(ctx context.Context) (string, error)

FuncTokenSource adapts a function to TokenSource.

func (FuncTokenSource) Token

func (f FuncTokenSource) Token(ctx context.Context) (string, error)

type OAuth2TokenSource

type OAuth2TokenSource struct {
	TokenURL     string
	GrantType    string // client_credentials | refresh_token
	ClientID     string
	ClientSecret string
	RefreshToken string
	Scopes       []string
	Audience     string
	Extra        map[string]string
	HTTPClient   *http.Client // optional; default http.DefaultClient
	Skew         time.Duration
}

OAuth2TokenSource obtains access tokens via RFC 6749 form POST to TokenURL. Supports client_credentials and refresh_token grants. Stdlib only (no x/oauth2).

func NewOAuth2TokenSource

func NewOAuth2TokenSource(o *config.OAuthConfig) (*OAuth2TokenSource, error)

NewOAuth2TokenSource builds a TokenSource from provider OAuth config. Values are resolved from env at construction time (and re-read for refresh tokens only if you rebuild — secrets are snapshotted for the process).

func (*OAuth2TokenSource) Token

func (o *OAuth2TokenSource) Token(ctx context.Context) (string, error)

func (*OAuth2TokenSource) TokenWithExpiry

func (o *OAuth2TokenSource) TokenWithExpiry(ctx context.Context) (string, time.Time, error)

type Route

type Route struct {
	ProviderName  string
	Provider      config.Provider
	UpstreamModel string
}

Route is the result of resolving a public model id.

func Resolve

func Resolve(cfg *config.Config, dialect, model string) (Route, error)

Resolve maps a public model id to a provider and upstream model id.

Resolution order:

1. alias table (exact match)
2. "provider/model" prefix
3. bare id -> the dialect's default provider

func ResolveForModality

func ResolveForModality(cfg *config.Config, dialect, model, modality string) (Route, error)

ResolveForModality resolves a model then enforces capability for modality.

func ResolveProvider

func ResolveProvider(cfg *config.Config, name string) (Route, error)

type Server

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

func NewServer

func NewServer(cfg *config.Config, hook hooks.Hook) *Server

func (*Server) Handler

func (s *Server) Handler() http.Handler

func (*Server) SetTokenSource

func (s *Server) SetTokenSource(provider string, ts TokenSource)

SetTokenSource registers a TokenSource for a provider name (e.g. "vertex"). Used when provider.auth is adc, service_account, or oauth2. Overrides any auto-wired source from config.

type ServiceAccountJWTSource

type ServiceAccountJWTSource struct {
	Email      string
	PrivateKey *rsa.PrivateKey
	TokenURL   string
	Scopes     []string
	HTTPClient *http.Client
	Skew       time.Duration
	// KeyID is optional kid header claim.
	KeyID string
}

ServiceAccountJWTSource exchanges a Google-style service-account JWT for an access token (urn:ietf:params:oauth:grant-type:jwt-bearer). Stdlib only.

func NewServiceAccountJWTSourceFromFile

func NewServiceAccountJWTSourceFromFile(path string, scopes []string) (*ServiceAccountJWTSource, error)

NewServiceAccountJWTSourceFromFile loads a GCP service-account JSON key file.

func NewServiceAccountJWTSourceFromJSON

func NewServiceAccountJWTSourceFromJSON(raw []byte, scopes []string) (*ServiceAccountJWTSource, error)

NewServiceAccountJWTSourceFromJSON parses SA JSON bytes.

func (*ServiceAccountJWTSource) Token

func (s *ServiceAccountJWTSource) Token(ctx context.Context) (string, error)

func (*ServiceAccountJWTSource) TokenWithExpiry

func (s *ServiceAccountJWTSource) TokenWithExpiry(ctx context.Context) (string, time.Time, error)

type StaticTokenSource

type StaticTokenSource struct {
	AccessToken string
}

StaticTokenSource always returns the same token. Useful for tests and for short-lived tokens refreshed outside the gateway process.

func (StaticTokenSource) Token

func (s StaticTokenSource) Token(context.Context) (string, error)

type TokenSource

type TokenSource interface {
	Token(ctx context.Context) (string, error)
}

TokenSource supplies OAuth2-style access tokens for providers using auth: adc, service_account, or oauth2 (and optionally bearer with a server-held token). Real Google ADC is optional: inject a source via Server.SetTokenSource, set service_account_file / GOOGLE_APPLICATION_CREDENTIALS, or use auth: oauth2. The gateway does not pull in cloud SDKs by default.