httpserver

Documentation

Overview

Package httpserver serves every HTTP route group, such as the codec server, on one port separate from the gateway's.

A route group contributes its handlers as Route values through AsRoutes, and owns everything specific to its callers, including CORS and authentication. This package owns only the listener: its address, TLS, and lifecycle. With no group enabled, nothing binds.

A Server is single-use and is not restartable after Server.Stop.

Index

• Variables
• func AsRoutes(constructor any) any
• type Params
• type Route
• type Server
  • func New(hostPort string, h http.Handler, tlsCfg *tls.Config, log logger.Logger, ...) *Server
  • func (s *Server) Addr() net.Addr
  • func (s *Server) Start(ctx context.Context) error
  • func (s *Server) Stop(ctx context.Context) error

Variables

var Module = fx.Options(
	fx.Provide(newFromParams),
	fx.Invoke(func(*Server) {}),
)

Module provides the HTTP server and forces its construction, since nothing else depends on it. Include it unconditionally: with no routes contributed, it yields a nil Server and no lifecycle hook, so the module is inert.

Functions

func AsRoutes

func AsRoutes(constructor any) any

AsRoutes annotates constructor, which must return []Route and optionally an error, so its routes are mounted on the shared server. A disabled group returns none.

Types

type Params

type Params struct {
	fx.In
	Shutdowner fx.Shutdowner

	Config    *config.Config
	Logger    logger.Logger
	Lifecycle fx.Lifecycle
	Routes    []Route `group:"http_routes"`
}

Params collects the fx-provided dependencies the HTTP server needs. Routes holds whatever the enabled route groups contributed, and may be empty.

type Route

type Route struct {
	Pattern string
	Handler http.Handler
}

Route mounts one route group's handler on the shared mux at Pattern, an http.ServeMux pattern. Patterns from different groups must not overlap, or building the server panics.

type Server

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

Server serves the HTTP route groups on one port, separate from the gateway's.

func New

func New(
	hostPort string,
	h http.Handler,
	tlsCfg *tls.Config,
	log logger.Logger,
	abort func(error),
) *Server

New returns a Server that serves h on hostPort. It binds nothing, Server.Start does that.

func (*Server) Addr

func (s *Server) Addr() net.Addr

Addr is the address the server is accepting on, including the port chosen for a port-zero hostPort, or nil before Server.Start returns successfully. Safe for concurrent use.

func (*Server) Start

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

Start binds the listener and serves in a background goroutine until Server.Stop, returning once the listener is accepting. It returns an error only if the bind fails; a serving failure after that reaches the abort function given to New instead.

Call it at most once. A Server is not restartable after Server.Stop.

func (*Server) Stop

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

Stop closes the listener and waits for in-flight requests to finish, without calling the abort function. Returns ctx's error if the drain does not finish in time, nil otherwise.