proxy

Documentation

Index

• func NewServer(config *Config) (http.Handler, error)
• func RecoveryHandler(next http.Handler) http.Handler
• func SecurityChecks() []string
• func Serve(l net.Listener, handler http.Handler, certFile, keyFile string) (net.Listener, error)
• func Start(handler http.Handler, certFile, keyFile string) (net.Listener, error)
• func ValidateTLSConfig(certFile, keyFile string) error
• type Config
• type TokenSource
• type WebSearchSettings

Functions

func NewServer

func NewServer(config *Config) (http.Handler, error)

NewServer returns an http.Handler that routes requests to the inference upstream (default) and the OTEL upstream (/otel/).

Inference route behaviour:

• WebSocket upgrade requests (used by databricks-codex / Codex CLI) are handled via handleWebSocket with bidirectional piping and fresh token injection.
• All other requests (used by databricks-claude / Claude Code, which speaks HTTP + SSE) are handled by httputil.ReverseProxy.

OTEL route (/otel/):

• /v1/logs paths → UCLogsTable header
• /v1/traces paths → UCTracesTable header
• all other paths → UCMetricsTable header (omitted if the chosen table is empty)

func RecoveryHandler

func RecoveryHandler(next http.Handler) http.Handler

RecoveryHandler wraps h with panic recovery, returning 502 on panic.

func SecurityChecks

func SecurityChecks() []string

SecurityChecks returns a list of human-readable warnings for risky startup conditions. Returns nil when no issues are detected.

func Serve

func Serve(l net.Listener, handler http.Handler, certFile, keyFile string) (net.Listener, error)

Serve starts the proxy on an existing listener. The listener is wrapped in a TLS listener when certFile and keyFile are both non-empty. Returns the (possibly wrapped) listener that is actively serving.

func Start

func Start(handler http.Handler, certFile, keyFile string) (net.Listener, error)

Start binds to 127.0.0.1:0, starts serving, and returns the listener. Callers read l.Addr() to discover the assigned port. When certFile and keyFile are both non-empty, the listener serves TLS.

func ValidateTLSConfig

func ValidateTLSConfig(certFile, keyFile string) error

ValidateTLSConfig returns an error if the TLS configuration is incomplete (one of cert/key set but not the other). Both empty is valid (TLS disabled).

Types

type Config

type Config struct {
	InferenceUpstream string
	OTELUpstream      string
	// UCMetricsTable is the Unity Catalog table for OTEL metrics.
	// Leave empty if the caller does not emit metrics (e.g. databricks-codex,
	// which has no native metrics support). When empty the
	// X-Databricks-UC-Table-Name header is omitted for metrics requests.
	UCMetricsTable string
	UCLogsTable    string
	// UCTracesTable is the Unity Catalog table for OTEL traces (Claude Code's
	// enhanced telemetry beta). When empty the X-Databricks-UC-Table-Name
	// header is omitted for /v1/traces requests.
	UCTracesTable string
	TokenSource   TokenSource
	Verbose       bool
	// ToolName identifies this proxy in /health responses (e.g. "databricks-claude").
	ToolName string
	// Version is the build version reported by /health.
	Version string
	// APIKey, when non-empty, requires all incoming requests to present
	// Authorization: Bearer <APIKey>. Leave empty to disable auth.
	APIKey string
	// TLSCertFile and TLSKeyFile enable TLS on the listener when both are set.
	TLSCertFile string
	TLSKeyFile  string
	// WebSearch (--with-websearch) bundles the optional local-fulfillment
	// settings for Anthropic's web_search/web_fetch server-side tools when
	// Databricks FMAPI doesn't yet support them. When Enabled is false,
	// inference requests are forwarded byte-identically and this struct
	// has no effect — see pkg/proxy/websearch_handler.go.
	WebSearch WebSearchSettings
	// Daemon, when true, indicates this proxy is running as a long-lived daemon
	// (databricks-claude serve). The /health response includes daemon-specific
	// fields; /shutdown is not registered (serve.go never wraps with lifecycle).
	Daemon bool
	// Profile is the Databricks config profile name, reported in /health when Daemon=true.
	Profile string
}

Config holds the configuration for the proxy server.

WebSocket note: databricks-claude (Claude Code) uses HTTP with SSE for streaming and never issues WebSocket upgrades. databricks-codex (Codex CLI) uses WebSocket for its inference connection. The proxy handles both transparently — WebSocket upgrades are detected per-request and routed through handleWebSocket; plain HTTP falls through to httputil.ReverseProxy. Centralising this here avoids maintaining a forked proxy in databricks-codex.

type TokenSource

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

TokenSource provides tokens for upstream authentication.

type WebSearchSettings

type WebSearchSettings struct {
	Enabled     bool
	Backend     websearch.Backend
	Robots      websearch.RobotsChecker
	FetchBudget int
}

WebSearchSettings bundles the optional --with-websearch knobs. Embedded in Config; when Enabled is false the websearch path is fully bypassed and the proxy forwards bytes verbatim (regression-tested for byte-identity).