Documentation
¶
Overview ¶
Package stubserver provides a configurable HTTP test server for provider testing. It supports SSE fixture replay and fault injection over real HTTP connections, exercising the full client stack (headers, auth, timeouts).
Provider-agnostic: the fixture format is raw SSE text, so it works for Anthropic, OpenAI, and Google streaming formats without modification.
Index ¶
- func NewHandler(opts ...Option) http.Handler
- type CapturedRequest
- type Fault
- type FaultMode
- type Option
- func WithFault(fixture string, fault Fault) Option
- func WithFixture(fixture string) Option
- func WithFixtureFunc(fn func(r *http.Request) string) Option
- func WithHandler(h http.HandlerFunc) Option
- func WithJSONFault(fixture string, fault Fault) Option
- func WithJSONFixture(fixture string) Option
- func WithJSONFixtureFunc(fn func(r *http.Request) string) Option
- type Server
- func New(opts ...Option) *Server
- func NewBackpressureServer(fixture string, eventDelay time.Duration) *Server
- func NewEmptyBodyServer(statusCode int) *Server
- func NewJSONFaultServer(fixture string, fault Fault) *Server
- func NewJSONServer(fixture string) *Server
- func NewMalformedServer(fixture string, afterEvents int, malformedData string) *Server
- func NewSequenceServer(responses []func(w http.ResponseWriter, r *http.Request)) *Server
- func NewStatusCodeServer(statusCode int, body string) *Server
- func NewTCPResetServer(fixture string, afterEvents int) *Server
- func NewThrottleServer(retryAfter string) *Server
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewHandler ¶
NewHandler creates an http.Handler using the same option behavior as New, but without starting an httptest.Server. The caller owns listener lifecycle.
Types ¶
type CapturedRequest ¶
CapturedRequest stores an incoming request for later verification.
type Fault ¶
type Fault struct {
// Mode selects the fault type.
Mode FaultMode
// AfterEvents specifies the fault injection point in the event stream.
// For TCPReset: disconnects after this many events have been sent.
// For Malformed: replaces the event at this index with corrupt data.
// For Backpressure: not used (delay applies to all events).
AfterEvents int
// StatusCode for non-2xx faults (Throttle, EmptyBody).
StatusCode int
// RetryAfter sets the Retry-After header for Throttle faults.
RetryAfter string
// MalformedData is the corrupt payload to inject for Malformed faults.
MalformedData string
// EventDelay adds per-event delay for Backpressure faults.
EventDelay time.Duration
}
Fault defines fault injection behavior for a stub server.
type FaultMode ¶
type FaultMode int
FaultMode enumerates the supported fault injection modes.
const ( // NoFault serves the fixture normally. NoFault FaultMode = iota // TCPReset (F1) — close the TCP connection after AfterEvents SSE events. TCPReset // Malformed (F2) — inject MalformedData as a corrupt SSE event after // AfterEvents events, then continue or close. Malformed // Throttle (F3) — return StatusCode (default 429) with optional // Retry-After header. Does not serve SSE data. Throttle // Backpressure (F4) — serve events with EventDelay between each, // simulating a slow server to test client timeout behavior. Backpressure // EmptyBody (F6) — return StatusCode with an empty response body. // Tests error classification from status code alone. EmptyBody )
type Option ¶
type Option func(*Server)
Option configures a Server.
func WithFixture ¶
WithFixture configures the server to replay an SSE fixture string. The fixture should be raw SSE text (e.g., "event: message_start\ndata: {...}\n\n").
func WithFixtureFunc ¶
WithFixtureFunc configures the server to call fn for each request to get the fixture to serve. Useful for per-request fixture selection.
func WithHandler ¶
func WithHandler(h http.HandlerFunc) Option
WithHandler configures a fully custom handler.
func WithJSONFault ¶
WithJSONFault configures the server to inject a fault while serving a JSON response. For TCPReset, AfterEvents is reinterpreted as byte count: the connection is closed after writing that many bytes of the response body.
func WithJSONFixture ¶
WithJSONFixture configures the server to serve a canned JSON response. The fixture should be a valid JSON string.
type Server ¶
type Server struct {
// URL is the base URL of the running test server.
URL string
// contains filtered or unexported fields
}
Server is a configurable HTTP test server for provider testing.
func New ¶
New creates a stub server with the given handler options. The server starts immediately and must be closed with Close().
func NewBackpressureServer ¶
NewBackpressureServer creates a server that sends events with a delay between each to simulate slow server responses.
func NewEmptyBodyServer ¶
NewEmptyBodyServer creates a server that returns a non-2xx status with an empty response body.
func NewJSONFaultServer ¶
NewJSONFaultServer creates a server that injects a fault while serving JSON.
func NewJSONServer ¶
NewJSONServer creates a server that serves a canned JSON response.
func NewMalformedServer ¶
NewMalformedServer creates a server that injects a malformed SSE event after afterEvents normal events.
func NewSequenceServer ¶
func NewSequenceServer(responses []func(w http.ResponseWriter, r *http.Request)) *Server
NewSequenceServer creates a server that serves different responses for sequential requests. Useful for testing retry behavior.
func NewStatusCodeServer ¶
NewStatusCodeServer creates a server that returns the given status code with an optional body.
func NewTCPResetServer ¶
NewTCPResetServer creates a server that sends AfterEvents SSE events from fixture then kills the TCP connection.
func NewThrottleServer ¶
NewThrottleServer creates a server that returns HTTP 429 with optional Retry-After header.
func (*Server) ClearRequests ¶
func (s *Server) ClearRequests()
ClearRequests resets the captured request log.
func (*Server) Requests ¶
func (s *Server) Requests() []CapturedRequest
Requests returns a copy of all captured requests.
Source Files