admin

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 30, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package admin is the admin API of a mock server: a RESTful HTTP server of its own, on its own address, that lists, adds and changes the server's mocks, and reads its journal, while it runs. A mock server serves none unless it is given one:

m := mockhttp.MustNew(mockhttp.Setup().Admin(admin.MustNew(admin.Addr("127.0.0.1:8081"))))

The same works for gRPC with mockgrpc. An Admin serves one mock server.

With MCP, the admin API serves its operations to AI agents too, over the Model Context Protocol: a tool per operation, at POST /mcp of the admin API, and over stdio with [Admin.ServeMCP].

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrServing is the error of an Admin given to a second mock server: it serves one.
	ErrServing = errors.New("admin: the admin API serves a mock server already")
)

Functions

This section is empty.

Types

type Admin

type Admin = adminapi.API

Admin is the built-in admin API a mock server opts into, with ConfigBuilder.Admin of mockhttp or mockgrpc. Create one with New or MustNew: its zero value is uninitialized. An Admin serves one mock server.

func MustNew

func MustNew(options ...Option) *Admin

MustNew is like New, but panics on an error.

func New

func New(options ...Option) (*Admin, error)

New creates an admin API. It fails on an address that is neither host:port, :port nor a port, on a docs version that isn't one, such as 1.80.0, on empty credentials, a username with a colon, credentials with control characters, a token an Authorization header can't carry, and a TLS config without a certificate. Its errors never hold a secret.

type Option

type Option func(a *api)

Option configures an Admin.

func Addr

func Addr(addr string) Option

Addr sets the address the admin API listens on: host:port, :port or a port. Empty, the default, is a random local port: the mock server's AdminURL returns where it listens.

func BasicAuth

func BasicAuth(username, password string) Option

BasicAuth asks every HTTP request of the admin API for username and password, with HTTP Basic authentication, but those of its Kubernetes probes, GET /livez, /readyz and /startupz, which answer their status alone. A browser shows its sign-in prompt for them, and sends them on with the requests of the admin pages. With BearerToken, a request passes with either. Basic sends them in plain text: serve the admin API over TLS beyond the local host.

func BearerToken

func BearerToken(token string) Option

BearerToken asks every HTTP request of the admin API for token, in an Authorization: Bearer header, or as the password of Basic, with any username, which is how a browser sends it from its sign-in prompt, but those of its Kubernetes probes, as BasicAuth does. A query parameter doesn't carry it: URLs end up in logs and histories. With BasicAuth, a request passes with either.

func DocsVersion

func DocsVersion(version string) Option

DocsVersion sets the version of Scalar, the npm package @scalar/api-reference, that the documentation page of the admin API, at /docs, loads from jsDelivr, such as 1.80.0: a newer one than vlatte pins, before vlatte ships it. Empty, the default, is the version vlatte pins. The page checks the pinned version against the hash of its file; it loads another unchecked, as its hash isn't known.

func MCP

func MCP() Option

MCP serves the admin operations over the Model Context Protocol too, for AI agents: Streamable HTTP at POST /mcp of the admin API, without sessions, and stdio with [Admin.ServeMCP]. Off, POST /mcp answers 501.

func TLS

func TLS(c *tls.Config) Option

TLS serves the admin API over HTTPS, with the certificates of c, which New fails without. The mock server's AdminURL starts with https then.

func Use

func Use(middlewares ...func(http.Handler) http.Handler) Option

Use adds middlewares that wrap every HTTP request of the admin API, such as one that answers CORS preflights. They run in the order they are added, across calls, before the credentials of BasicAuth and BearerToken are checked and the admin API routes the request: one that answers without calling the next handler answers in place of the admin API, credentials or not. Requests that come once the mock server closes get a 503 without reaching them. MCP over stdio, with [Admin.ServeMCP], doesn't go through them.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL