Files

61 lines
3.0 KiB
Go

// Package gserver implements a combined gRPC, gRPC-Web and REST server that
// listens on one or more URLs and multiplexes all three protocols on each
// listener.
//
// A Server is created with Start from a Config, a dig dependency container and
// a map of ServiceFactory functions. Each factory builds a Service; a Service
// that also implements RouteRegistrator gets its REST routes registered, and one
// that implements GRPCRegistrator gets its gRPC services registered. Plain
// HTTP/1.1 traffic is routed to the REST router, HTTP/2 "application/grpc"
// traffic to the gRPC server, and "application/grpc-web+proto" /
// "application/grpc-web-text" requests are translated to gRPC and their
// trailers are encoded into the gRPC-Web response body.
//
// Every REST request passes through a fixed middleware chain: rate limiting
// (optional), correlation ID, the handler deadline (Config.Timeouts.Handler,
// when set), request metrics, CORS (optional), identity extraction
// (roles.IdentityProvider built from Config.IdentityMap), a nested metrics
// handler that reports the caller role, request logging, authorization
// (restserver/authz built from Config.Authz), and a readiness check. gRPC
// and gRPC-Web calls go through the equivalent interceptor chain: panic
// recovery, correlation ID, logging (streams: logging, then correlation ID,
// which recovers panics), the handler deadline (when set), rate limiting
// and, for unary calls, NewRequestValidationUnaryInterceptor before identity
// extraction. Without Config.Timeouts.Handler a request or call runs as long
// as the client's deadline allows; with it, the request context expires
// after that duration unless the client asked for an earlier deadline.
// Each listener has one limiter: a limited REST request gets
// HTTP 429 and a limited call ResourceExhausted, logged and counted like any
// other response of its protocol; with RateLimit.LogRejections set, a
// WARNING line adds the limiter key, the socket peer and the forwarding
// headers. gRPC log lines carry the client IP as remote and the User-Agent
// as agent, like the REST access lines, and the gRPC metrics carry the role
// that identity extraction resolved.
//
// Minimal usage:
//
// cfg := &gserver.Config{
// ListenURLs: []string{"https://0.0.0.0:8443"},
// Services: []string{"status"},
// ServerTLS: &gserver.TLSInfo{
// CertFile: "server.pem",
// KeyFile: "server-key.pem",
// },
// }
// factories := map[string]gserver.ServiceFactory{
// "status": func(s gserver.GServer) any {
// return func() error { s.AddService(newStatusService(s)); return nil }
// },
// }
// srv, err := gserver.Start("api", cfg, container, factories)
// if err != nil {
// return err
// }
// defer srv.Close()
// <-srv.Err() // or wait for a signal
//
// The container must provide discovery.Discovery and, when Config.IdentityMap
// enables JWT or DPoP authentication, a jwt.Parser. Config is typically loaded
// from YAML; see the yaml tags on Config for the field names.
package gserver