server

Documentation

Overview

Package server owns the HTTP listeners for the jetstream process.

We expose two listeners:

• Public (default :8080): the protocol surface.

• Debug (disabled by default): operations endpoints — /metrics, /healthz, /debug/pprof, etc. Should not be exposed to the public internet when the system is deployed.

Index

• type Config
• type Server
  • func New(cfg Config, logger *slog.Logger, metrics *obs.Metrics) *Server
  • func (s *Server) DebugAddr() string
  • func (s *Server) PublicAddr() string
  • func (s *Server) RegisterPublicRoute(pattern string, h http.Handler)
  • func (s *Server) Run(ctx context.Context) error

Types

type Config

type Config struct {
	// PublicAddr is the bind address for the public listener (e.g. ":8080").
	PublicAddr string

	// DebugAddr is the bind address for the metrics/pprof listener (e.g. ":6060").
	// Empty disables the listener unless DebugListener is supplied.
	DebugAddr string

	// ShutdownTimeout bounds how long graceful shutdown is allowed to take.
	// After this elapses, in-flight requests are abandoned.
	ShutdownTimeout time.Duration

	// StatusHandler, if non-nil, is mounted at GET /status and HEAD
	// /status on the public listener. cmd/jetstream constructs this via
	// the web package; tests can pass any http.Handler.
	StatusHandler http.Handler

	// PublicListener and DebugListener, when non-nil, are served instead of
	// binding a TCP socket for PublicAddr/DebugAddr. Production leaves them
	// nil (bind TCP); the in-process oracle harness passes pipe-backed
	// listeners so the server runs with no socket inside a synctest bubble.
	PublicListener net.Listener
	DebugListener  net.Listener
}

Config controls the listeners. PublicAddr and ShutdownTimeout should be populated explicitly from CLI flags. Empty DebugAddr disables the debug listener unless DebugListener is supplied.

type Server

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

Server bundles the public and debug HTTP servers and the readiness flag they share. It is constructed via New and driven via Run.

func New

func New(cfg Config, logger *slog.Logger, metrics *obs.Metrics) *Server

New wires up the muxes for both listeners. It does not bind any sockets; that happens in Run.

func (*Server) DebugAddr

func (s *Server) DebugAddr() string

DebugAddr returns the bound debug listener address, or "" if Run has not yet bound it.

func (*Server) PublicAddr

func (s *Server) PublicAddr() string

PublicAddr returns the bound public listener address, or "" if Run has not yet bound it.

func (*Server) RegisterPublicRoute

func (s *Server) RegisterPublicRoute(pattern string, h http.Handler)

RegisterPublicRoute attaches an additional handler to the public mux. Must be called before Run; routes registered after Run starts are not observed. Pattern uses Go 1.22+ ServeMux syntax (e.g. "GET /subscribe").

func (*Server) Run

func (s *Server) Run(ctx context.Context) error

Run binds both listeners and serves until ctx is cancelled, at which point it triggers graceful shutdown bounded by ShutdownTimeout. Run returns nil if shutdown completed cleanly, or the first error encountered.

The public listener and optional debug listener are bound synchronously before serve goroutines start, so callers can rely on PublicAddr/DebugAddr having concrete addresses (if they used :0) by the time Run is observable to be running. DebugAddr remains empty when the debug listener is disabled.