http

Documentation

Overview

Package http — stream_transform_prototype.go

THROWAWAY / DESIGN SPIKE ONLY (milestone 2.5.G3.M2 / ADR-0045). This file is intentionally NOT wired into forwardSSEStream, copySSEEvents, bootstrap, or any production request path. It validates token-window buffering latency and fail-closed overflow behavior before Phase 3 commits to a design.

Index

• Constants
• Variables
• func AgentFromContext(ctx context.Context) (auth.AgentRecord, bool)
• func AgentVerificationMiddleware(verifier AgentVerifier, log *logger.Logger) func(http.Handler) http.Handler
• func AuthLatencyMsFromContext(ctx context.Context) uint16
• func AuthMiddleware(validator TokenValidator, log *logger.Logger, opts AuthOptions) func(http.Handler) http.Handler
• func BodySizeLimitMiddleware(maxBytes int64, docsBase string) func(http.Handler) http.Handler
• func ChatParseMiddleware(opts chatParseOpts) func(http.Handler) http.Handler
• func ContentTypeMiddleware(docsBase string) func(http.Handler) http.Handler
• func DirectiveLatencyMsFromContext(ctx context.Context) uint16
• func DirectiveResolveMiddleware(resolver directive.Resolver, log *logger.Logger) func(http.Handler) http.Handler
• func ErrorDocsBaseFromContext(ctx context.Context) string
• func IsMaxBytesError(err error) bool
• func NewRouter(deps RouterDeps) (http.Handler, error)
• func PathOrgUUIDMiddleware(docsBase string) func(http.Handler) http.Handler
• func ProviderRoutingMiddleware(opts providerRoutingOpts) func(http.Handler) http.Handler
• func RateLimitMiddleware(limiter ratelimit.Limiter, log *logger.Logger, reg *metrics.ProxyRegistry) func(http.Handler) http.Handler
• func RequestContextMiddleware(cfg config.Config) func(http.Handler) http.Handler
• func RequestIDFromContext(ctx context.Context) string
• func RequestStartFromContext(ctx context.Context) (time.Time, bool)
• func ResolvedDirectiveFromContext(ctx context.Context) (directive.Resolved, bool)
• func ResolvedSessionFromContext(ctx context.Context) (httpsession.Resolved, bool)
• func ResponseHeadersMiddleware(cfg config.Config) func(http.Handler) http.Handler
• func TraceIDFromContext(ctx context.Context) string
• func WithAgent(ctx context.Context, rec auth.AgentRecord) context.Context
• func WithAuthLatencyMs(ctx context.Context, ms uint16) context.Context
• func WithDirectiveLatencyMs(ctx context.Context, ms uint16) context.Context
• func WithErrorDocsBase(ctx context.Context, base string) context.Context
• func WithRequestID(ctx context.Context, id string) context.Context
• func WithRequestStart(ctx context.Context, start time.Time) context.Context
• func WithResolvedDirective(ctx context.Context, resolved directive.Resolved) context.Context
• func WithTraceID(ctx context.Context, id string) context.Context
• type AgentVerifier
• type AuthOptions
• type PrototypeWindowBuffer
  • func NewPrototypeWindowBuffer(cfg PrototypeWindowConfig) (*PrototypeWindowBuffer, error)
  • func (w *PrototypeWindowBuffer) Feed(chunk string) (string, error)
  • func (w *PrototypeWindowBuffer) Flush() (string, error)
  • func (w *PrototypeWindowBuffer) RetainedRunes() int
• type PrototypeWindowConfig
• type RouterDeps
• type TokenValidator
• type TraceWriter

Constants

const ResolveTimeout = 100 * time.Millisecond

ResolveTimeout budgets Redis GET plus a Postgres miss on the chat hot path. Cache SET after a miss uses a detached context so it is not starved by this deadline.

const (
	// ResponsePipelineTimeout bounds non-streaming pipeline stage execution on the success path.
	ResponsePipelineTimeout = 50 * time.Millisecond
)

Variables

var ErrPrototypeBufferOverflow = errors.New("stream transform prototype: buffer overflow")

ErrPrototypeBufferOverflow is returned when the window would exceed MaxBufferRunes. Callers that eventually wire this must abort the stream (fail-closed), never leak.

var ErrPrototypeInvalidConfig = errors.New("stream transform prototype: invalid config")

ErrPrototypeInvalidConfig is returned for non-positive holdback/max or holdback > max.

Functions

func AgentFromContext

func AgentFromContext(ctx context.Context) (auth.AgentRecord, bool)

AgentFromContext returns the verified agent record when agent middleware ran.

func AgentVerificationMiddleware

func AgentVerificationMiddleware(
	verifier AgentVerifier,
	log *logger.Logger,
) func(http.Handler) http.Handler

AgentVerificationMiddleware validates X-IBEX-Agent-ID against the authenticated org. Must run after AuthMiddleware and before RateLimitMiddleware.

func AuthLatencyMsFromContext

func AuthLatencyMsFromContext(ctx context.Context) uint16

AuthLatencyMsFromContext returns auth stage latency when recorded.

func AuthMiddleware

func AuthMiddleware(validator TokenValidator, log *logger.Logger, opts AuthOptions) func(http.Handler) http.Handler

AuthMiddleware validates bearer tokens and attaches auth context.

func BodySizeLimitMiddleware

func BodySizeLimitMiddleware(maxBytes int64, docsBase string) func(http.Handler) http.Handler

BodySizeLimitMiddleware caps the request body size (must run before reads).

func ChatParseMiddleware

func ChatParseMiddleware(opts chatParseOpts) func(http.Handler) http.Handler

ChatParseMiddleware parses and validates the chat completion body once, then attaches llm.ChatCompletionRequest so downstream middleware and handlers consume the typed request without re-parsing the body.

func ContentTypeMiddleware

func ContentTypeMiddleware(docsBase string) func(http.Handler) http.Handler

ContentTypeMiddleware requires JSON Content-Type on POST requests.

func DirectiveLatencyMsFromContext

func DirectiveLatencyMsFromContext(ctx context.Context) uint16

DirectiveLatencyMsFromContext returns directive stage latency when recorded.

func DirectiveResolveMiddleware

func DirectiveResolveMiddleware(
	resolver directive.Resolver,
	log *logger.Logger,
) func(http.Handler) http.Handler

DirectiveResolveMiddleware resolves the agent directive after verification. On infrastructure failure (including timeout): fail open with a warning. Does not mutate the LLM messages array (injection is milestone 2.3.3).

func ErrorDocsBaseFromContext

func ErrorDocsBaseFromContext(ctx context.Context) string

ErrorDocsBaseFromContext returns the error docs base URL.

func IsMaxBytesError

func IsMaxBytesError(err error) bool

IsMaxBytesError reports whether err is from http.MaxBytesReader.

func NewRouter

func NewRouter(deps RouterDeps) (http.Handler, error)

NewRouter builds the proxy HTTP handler. A non-nil error means the router was not fully initialized and must not be served.

func PathOrgUUIDMiddleware

func PathOrgUUIDMiddleware(docsBase string) func(http.Handler) http.Handler

PathOrgUUIDMiddleware validates org_id path segment before auth.

func ProviderRoutingMiddleware

func ProviderRoutingMiddleware(opts providerRoutingOpts) func(http.Handler) http.Handler

ProviderRoutingMiddleware selects the LLM provider for the request model. On lookup failure it short-circuits with 501 PROVIDER_NOT_CONFIGURED (or an internal error). After a successful lookup it attaches provider.Provider so the handler can forward without touching the registry. Required after ChatParseMiddleware.

func RateLimitMiddleware

func RateLimitMiddleware(limiter ratelimit.Limiter, log *logger.Logger, reg *metrics.ProxyRegistry) func(http.Handler) http.Handler

RateLimitMiddleware enforces org-level rate limits after authentication. On Redis failure: fail open (allow request) with warning log.

func RequestContextMiddleware

func RequestContextMiddleware(cfg config.Config) func(http.Handler) http.Handler

RequestContextMiddleware assigns request/trace IDs and request start time.

func RequestIDFromContext

func RequestIDFromContext(ctx context.Context) string

RequestIDFromContext returns the request ID when present.

func RequestStartFromContext

func RequestStartFromContext(ctx context.Context) (time.Time, bool)

RequestStartFromContext returns the request start time when present.

func ResolvedDirectiveFromContext

func ResolvedDirectiveFromContext(ctx context.Context) (directive.Resolved, bool)

ResolvedDirectiveFromContext returns the resolved directive when present. Absence is expected on fail-open resolve errors; injection must treat missing as "no directive" rather than an error.

func ResolvedSessionFromContext

func ResolvedSessionFromContext(ctx context.Context) (httpsession.Resolved, bool)

ResolvedSessionFromContext returns the session resolved for this request. Lifecycle sets it after sticky external_id mint/lookup (and upgrades it when GetOrCreate succeeds). Absence means session features are off or sticky id was rejected; callers must not assume a durable SessionID is present.

func ResponseHeadersMiddleware

func ResponseHeadersMiddleware(cfg config.Config) func(http.Handler) http.Handler

ResponseHeadersMiddleware sets IBEX response headers on every response.

func TraceIDFromContext

func TraceIDFromContext(ctx context.Context) string

TraceIDFromContext returns the trace ID when present.

func WithAgent

func WithAgent(ctx context.Context, rec auth.AgentRecord) context.Context

WithAgent stores the verified agent record on the context.

func WithAuthLatencyMs

func WithAuthLatencyMs(ctx context.Context, ms uint16) context.Context

WithAuthLatencyMs stores auth middleware wall time in milliseconds.

func WithDirectiveLatencyMs

func WithDirectiveLatencyMs(ctx context.Context, ms uint16) context.Context

WithDirectiveLatencyMs stores directive resolve wall time in milliseconds.

func WithErrorDocsBase

func WithErrorDocsBase(ctx context.Context, base string) context.Context

WithErrorDocsBase stores the optional error docs URL base.

func WithRequestID

func WithRequestID(ctx context.Context, id string) context.Context

WithRequestID stores the request ID on the context.

func WithRequestStart

func WithRequestStart(ctx context.Context, start time.Time) context.Context

WithRequestStart stores the request start time for response-time headers.

func WithResolvedDirective

func WithResolvedDirective(ctx context.Context, resolved directive.Resolved) context.Context

WithResolvedDirective stores a successfully resolved directive on the request context for downstream injection (2.3.3). Call only after Resolve succeeds.

func WithTraceID

func WithTraceID(ctx context.Context, id string) context.Context

WithTraceID stores the trace ID on the context.

Types

type AgentVerifier

type AgentVerifier interface {
	Verify(ctx context.Context, bearer, agentID, orgID string) (*auth.AgentRecord, error)
}

AgentVerifier is the HTTP consumer port for agent ownership checks. Concrete adapters live in services/proxy/internal/auth.

type AuthOptions

type AuthOptions struct {
	RequireProxyChatCompletion bool
	PathOrgID                  string
	Metrics                    *metrics.ProxyRegistry
}

AuthOptions configures auth middleware behavior per route.

type PrototypeWindowBuffer

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

PrototypeWindowBuffer holds a trailing rune window so pattern matches that straddle chunk boundaries are not emitted until complete (or stream end). Not goroutine-safe; one buffer per stream.

func NewPrototypeWindowBuffer

func NewPrototypeWindowBuffer(cfg PrototypeWindowConfig) (*PrototypeWindowBuffer, error)

NewPrototypeWindowBuffer constructs a buffer. Zero values use prototype defaults.

func (*PrototypeWindowBuffer) Feed

func (w *PrototypeWindowBuffer) Feed(chunk string) (string, error)

Feed appends a content chunk, redacts complete prototype matches, and returns only the prefix that is safe to flush (retaining a holdback tail).

func (*PrototypeWindowBuffer) Flush

func (w *PrototypeWindowBuffer) Flush() (string, error)

Flush redacts any remaining complete matches and emits the entire buffer (stream end — no further chunks can complete a partial match).

func (*PrototypeWindowBuffer) RetainedRunes

func (w *PrototypeWindowBuffer) RetainedRunes() int

RetainedRunes reports runes currently held (for benchmarks / metrics sketches).

type PrototypeWindowConfig

type PrototypeWindowConfig struct {
	HoldbackRunes  int
	MaxBufferRunes int
}

PrototypeWindowConfig configures the throwaway holdback buffer.

type RouterDeps

type RouterDeps struct {
	Config             config.Config
	Logger             *logger.Logger
	Metrics            *metrics.ProxyRegistry
	Tracer             trace.Tracer
	Validator          TokenValidator
	AgentVerifier      AgentVerifier
	Limiter            ratelimit.Limiter
	DirectiveResolver  directive.Resolver
	SessionStore       session.Store
	SessionCache       *sessioncache.Cache
	CheckpointPool     *asyncpool.Pool
	GetOrCreateTimeout time.Duration
	Health             *healthcheck.Server
	ProviderRegistry   *provider.Registry
	ResponsePipeline   *responsepipeline.Pipeline
	TraceWriter        TraceWriter
	IdempotencyStore   idempotency.Store
}

RouterDeps wires the proxy HTTP handler and middleware chain.

type TokenValidator

type TokenValidator interface {
	Validate(ctx context.Context, accessToken string) (*auth.ValidateResult, error)
}

TokenValidator is the HTTP consumer port for bearer validation. Concrete adapters live in services/proxy/internal/auth (gRPC + cache wrap).

type TraceWriter

type TraceWriter = httptrace.TraceWriter

Type aliases keep call sites readable while types live in subpackages.