proxy

Documentation

Overview

Package proxy is the request path: a pass-through HTTP proxy that meters every inference call, prices it, and refuses to forward when the budget guard says spend is paused. Bytes are forwarded unmodified — burnban observes traffic, it never rewrites it.

Index

• func DefaultUpstreams() map[string]Upstream
• func Shapes() []string
• type HealthSnapshot
• type Proxy
  • func New(s *store.Store, t *pricing.Table, upstreams map[string]Upstream) (*Proxy, error)
  • func (p *Proxy) Handler() http.Handler
  • func (p *Proxy) Health() HealthSnapshot
  • func (p *Proxy) ProbeHealth() HealthSnapshot
• type Upstream

Functions

func DefaultUpstreams

func DefaultUpstreams() map[string]Upstream

DefaultUpstreams maps URL path prefixes to provider APIs. Each can be overridden by env var, which is also how tests point burnban at fakes.

func Shapes

func Shapes() []string

Shapes lists the usage dialects the meter can parse.

Types

type HealthSnapshot

type HealthSnapshot struct {
	Service       string     `json:"service"`
	OK            bool       `json:"ok"`
	State         string     `json:"state"`
	Detail        string     `json:"detail,omitempty"`
	PersistenceOK bool       `json:"persistence_ok"`
	InFlight      int        `json:"in_flight"`
	ReservedUSD   float64    `json:"reserved_usd"`
	LastFailure   *time.Time `json:"last_failure,omitempty"`
}

HealthSnapshot is the proxy's runtime safety state. Persistence failures latch fail-closed; in-flight reservation fields make bounded overshoot visible to health/doctor/dashboard consumers.

type Proxy

type Proxy struct {
	Store     *store.Store
	Prices    *pricing.Table
	Guard     *budget.Guard
	Policy    *policy.Engine
	Downshift *downshift.Runtime
	Logf      func(format string, v ...any)
	// contains filtered or unexported fields
}

func New

func New(s *store.Store, t *pricing.Table, upstreams map[string]Upstream) (*Proxy, error)

func (*Proxy) Handler

func (p *Proxy) Handler() http.Handler

func (*Proxy) Health

func (p *Proxy) Health() HealthSnapshot

Health returns a non-mutating snapshot of the proxy's persistence and admission state.

func (*Proxy) ProbeHealth

func (p *Proxy) ProbeHealth() HealthSnapshot

ProbeHealth performs a durable store write and clears a persistence latch only after that write commits successfully.

type Upstream

type Upstream struct {
	URL   string
	Shape string
}

Upstream is one forwarding target. Shape names the usage dialect its responses speak — "anthropic", "gemini", or "openai" (the default and the de-facto standard that Groq, Mistral, DeepSeek, OpenRouter, Ollama, vLLM and friends all emit) — so metering follows the wire format, not the route name.