mockmodel

Documentation

Overview

Package mockmodel is a programmable, loopback-bound, OpenAI-compatible mock inference server for tests and end-to-end runs. It lets the whole serving stack be exercised in CI without a real GGUF: a test queues canned chat completions (or supplies a handler), runs the loop against URL(), and then asserts on the requests the server recorded.

It is standard-library-only (net/http/httptest) and binds to 127.0.0.1 on an ephemeral port, preserving the loopback-only / zero-egress invariant. It is a test helper: it ships in no production code path and links no third-party dependency.

Index

• type Message
• type ModelEntry
• type Options
• type RecordedRequest
• type Response
• type Server
  • func New(opts Options) *Server
  • func (s *Server) Close()
  • func (s *Server) Enqueue(resps ...Response)
  • func (s *Server) LastRequest() (RecordedRequest, bool)
  • func (s *Server) Requests() []RecordedRequest
  • func (s *Server) URL() string

Types

type Message

type Message struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

Message is one OpenAI chat message.

type ModelEntry

type ModelEntry struct {
	ID     string
	Digest string
}

ModelEntry is one model reported by GET /v1/models.

type Options

type Options struct {
	// Responses is the queue of scripted replies, consumed in order, one per
	// chat-completion request. When the queue is empty a default reply is
	// returned (or Handler is consulted, if set).
	Responses []Response
	// Handler, when set, is consulted for each chat-completion request before
	// the queue. Returning ok=false falls through to the queue/default.
	Handler func(RecordedRequest) (resp Response, ok bool)
	// ModelID is the id reported by GET /v1/models. Defaults to "mock-model".
	ModelID string
	// ModelDigest is the digest reported by GET /v1/models. Defaults to
	// "sha256:0000".
	ModelDigest string
	// Models, when non-empty, makes GET /v1/models report this full list (for
	// multi-model backends like Ollama). Overrides ModelID/ModelDigest.
	Models []ModelEntry
}

Options configures a mock server.

type RecordedRequest

type RecordedRequest struct {
	// Path is the request URL path (e.g. "/v1/chat/completions").
	Path string
	// Method is the HTTP method.
	Method string
	// Model is the requested model id.
	Model string
	// Messages are the chat messages sent by the client.
	Messages []Message
	// Stream is the request's stream flag.
	Stream bool
	// Temperature is the requested sampling temperature.
	Temperature float64
	// RawBody is the verbatim request body.
	RawBody []byte
}

RecordedRequest captures the salient fields of a received chat-completion request so a test can assert on what the client actually sent.

type Response

type Response struct {
	// Content is the assistant reply text.
	Content string
	// FinishReason is the choice finish_reason; defaults to "stop".
	FinishReason string
	// Status, when non-zero, overrides the HTTP status code so a test can
	// drive the non-2xx error path. The Body field is then returned verbatim.
	Status int
	// Body, when Status is set, is the raw error body returned to the client.
	Body string
	// ChunkWords, when true, streams the content word-by-word (one SSE chunk
	// per whitespace-separated token) instead of a single content chunk. It
	// only affects streaming requests.
	ChunkWords bool
}

Response is a single scripted chat-completion reply. Content is returned as the assistant message; when the request asks for streaming it is split into SSE chunks (see ChunkWords).

type Server

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

Server is a running mock model server.

func New

func New(opts Options) *Server

New starts a loopback-bound mock model server. Call Close when done.

func (*Server) Close

func (s *Server) Close()

Close shuts the server down.

func (*Server) Enqueue

func (s *Server) Enqueue(resps ...Response)

Enqueue appends scripted responses to the reply queue.

func (*Server) LastRequest

func (s *Server) LastRequest() (RecordedRequest, bool)

LastRequest returns the most recent chat-completion request and whether one has been received.

func (*Server) Requests

func (s *Server) Requests() []RecordedRequest

Requests returns a copy of every chat-completion request received so far, in order.

func (*Server) URL

func (s *Server) URL() string

URL returns the loopback base URL the server is listening on (no trailing slash), e.g. "http://127.0.0.1:54321".