serve

Documentation

Overview

Package serve wires the registry's handlers onto a go/transport HTTP server.

This module does not own a server. gitlab.com/phpboyscout/go/transport already provides one with TLS, body limits, security headers, health endpoints and go/controls lifecycle, and a registry that reimplemented those would be a second answer to a question the estate has answered once. What lives here is the mux: which handler is mounted where, and what has to sit in front of the privileged one.

The package is separate so that a service which only embeds and validates schemas does not pull a server into its binary to do it.

Index

• Variables
• func Mount(reader httpapi.Reader, publisher httpapi.Publisher, opts ...Option) (http.Handler, error)
• func Register(ctx context.Context, id string, controller controls.Controllable, ...) (*http.Server, error)
• type Option
  • func AllowAnonymousPublishing() Option
  • func Authenticate(mw func(http.Handler) http.Handler) Option

Variables

var ErrNoAuthentication = errors.NewSentinel("schema.no_authentication",
	"schema: publishing requires authentication middleware; pass Authenticate or AllowAnonymousPublishing")

ErrNoAuthentication is returned when a publisher is supplied with nothing in front of it.

Publishing is privileged and reading is not, and the whole reason the two handlers are separate is so that difference survives wiring. Mounting an unauthenticated write path is not a configuration this module will produce by omission — if it is genuinely wanted, AllowAnonymousPublishing says so out loud and leaves a grep-able string in the source.

Functions

func Mount

func Mount(reader httpapi.Reader, publisher httpapi.Publisher, opts ...Option) (http.Handler, error)

Mount builds the registry's mux.

The read handler is mounted at the root. The write handler is mounted under /publish, wrapped in whatever middleware Authenticate supplied, so that a reverse proxy or a policy engine has one prefix to protect rather than a method to discriminate on.

func Register

func Register(
	ctx context.Context,
	id string,
	controller controls.Controllable,
	logger *slog.Logger,
	reader httpapi.Reader,
	publisher httpapi.Publisher,
	settings transporthttp.ServerSettings,
	opts ...Option,
) (*http.Server, error)

Register mounts the registry and registers an HTTP server with the controller, returning the server go/transport built.

Types

type Option

type Option func(*config)

Option configures the mux.

func AllowAnonymousPublishing

func AllowAnonymousPublishing() Option

AllowAnonymousPublishing mounts the publish handler with nothing in front of it.

For a test, or for a registry on a network where the boundary is somewhere else entirely. It exists so that decision is written down at the call site rather than reached by forgetting to pass anything.

func Authenticate

func Authenticate(mw func(http.Handler) http.Handler) Option

Authenticate wraps the publish handler in middleware.