Documentation
¶
Overview ¶
Package boot is the framework layer for this repo: every server implements the Service contract below, and pkg/boot/grpcserver and pkg/boot/httpserver build one from a service's handlers plus a declarative Config, so a service package never touches net.Listen, grpc.NewServer, or an interceptor chain directly. The one thing this package deliberately does not own is which services exist — each cmd/<name>/main.go supplies its own service's factory directly, since that mapping is different for every binary in the monorepo.
Index ¶
- Constants
- func ListenAndServe(s Service) error
- func MustInit(ctx context.Context, name string) (context.Context, *config.PlatformConfig)
- func Run[T config.ServiceConfig](name string, factory ComponentsFactory[T])
- func RunWithConfig[T config.ServiceConfig](name string, load func() (*config.RuntimeConfig[T], error), ...)
- func WithRuntimeConfig[T config.ServiceConfig](ctx context.Context, name string, cfg *config.RuntimeConfig[T]) context.Context
- type Components
- type ComponentsFactory
- type HostedService
- type Platform
- type Service
- func Boot[T config.ServiceConfig](ctx context.Context, name string, factory ComponentsFactory[T]) ([]Service, error)
- func BootAll(ctx context.Context, name string, platform config.PlatformConfig, ...) ([]Service, error)
- func BootWithConfig[T config.ServiceConfig](ctx context.Context, name string, cfg *config.RuntimeConfig[T], ...) ([]Service, error)
- type ServiceManager
- type Signaled
Constants ¶
const ( ConfigKey contextKey = "boot.config" IdentityKey contextKey = "boot.identity" )
const ( // PerServiceShutdownTimeout is what each service gets to drain, not a // budget split between them: services drain one at a time, so the process // can take this long per registered service. PerServiceShutdownTimeout = 15 * time.Second // PodTerminationGracePeriod is how long the kubelet waits after SIGTERM // before SIGKILL — hardcoded in fairway's deployment template, not this // repo, so verify it against a rendered Deployment rather than assuming // it. See .ai/components.md for the shutdown-timeout invariant this pins. PodTerminationGracePeriod = 60 * time.Second )
const SignalLogField = "signal"
SignalLogField is the log key both entry points attach a Signaled cause under. LabKit's fields package has no standard key for a terminating signal, so it is defined once here rather than repeated per call site.
Variables ¶
This section is empty.
Functions ¶
func ListenAndServe ¶
func MustInit ¶
MustInit loads the platform block of name's YAML config file and returns a context carrying it and name itself, so a service's handlers can identify themselves (e.g. in logging or telemetry) without name being threaded through every call.
func Run ¶
func Run[T config.ServiceConfig](name string, factory ComponentsFactory[T])
Run is every binary's main(): initialize logging, Boot name's Components via factory, and run the resulting services until one exits or the process is signaled. Each cmd/<name>/main.go calls this directly with its own service's NewComponents — there is no registry to look name up in; a binary only ever boots the one service it was built for.
func RunWithConfig ¶ added in v1.82.0
func RunWithConfig[T config.ServiceConfig](name string, load func() (*config.RuntimeConfig[T], error), factory ComponentsFactory[T])
RunWithConfig is Run with the caller's config loader. load runs after logging is initialised, so a config that does not load is logged like every other boot failure.
func WithRuntimeConfig ¶ added in v1.59.0
func WithRuntimeConfig[T config.ServiceConfig](ctx context.Context, name string, cfg *config.RuntimeConfig[T]) context.Context
WithRuntimeConfig stores an already-loaded config under the keys MustInit sets, so a loader outside this package can hand storage.MustConnect its config without repeating the keys. It also names the service's database connections after name.
Types ¶
type Components ¶
type Components struct {
GRPC *grpcserver.Registration
HTTP *httpserver.Registration
// DBPools names each of the service's database pools for automatic
// pool-stats registration (see registerDBPools). Leave nil if unused.
DBPools map[string]any
}
Components is what a service registers with the platform: its gRPC and/or HTTP surface, declaratively. Boot — not the service — decides which of them actually run, based on which addresses the service's own config sets. A service never constructs a *grpc.Server or *http.Server itself.
type ComponentsFactory ¶
type ComponentsFactory[T config.ServiceConfig] func(ctx context.Context, cfg config.RuntimeConfig[T], m *metrics.Metrics, tracer *trace.Tracer) (Components, error)
ComponentsFactory builds a service's Components. m and tracer are always available — every service gets a metrics registry and, when GITLAB_TRACING is configured, a tracer — so a factory can register its own instruments (e.g. DB pool gauges) without owning telemetry's lifecycle.
type HostedService ¶ added in v1.105.0
type HostedService struct {
// contains filtered or unexported fields
}
HostedService is one service of a process that hosts several: how to build its Components on the process's Platform. Host makes one from a service's factory, so BootAll can take services whose configs are of different types.
func Host ¶ added in v1.105.0
func Host[T config.ServiceConfig](name string, factory ComponentsFactory[T]) HostedService
Host wraps name's factory for BootAll. The service's `[services.<name>]` table is loaded and validated as for a standalone binary except its own service token, which is not required, and its Components are built as Boot builds them. Its own listen addresses and token are not read: BootAll binds on the addresses it is given, behind the platform's token.
type Platform ¶ added in v1.90.1
type Platform struct {
Metrics *metrics.Metrics
Tracer *trace.Tracer
// contains filtered or unexported fields
}
Platform is what a Boot owns and hands its service: the metrics registry with build info, and the tracer. A service never builds these itself.
func NewPlatform ¶ added in v1.90.1
NewPlatform builds the telemetry one process owns. Boot calls it once for a standalone binary; BootAll once for every service `iam serve all` hosts.
type Service ¶
type Service interface {
Name() string
Address() string
Serve() error
Shutdown(ctx context.Context) error
Logger() *logrus.Entry
}
Service is the lifecycle contract every server in this repo implements, gRPC or HTTP. ServiceManager drives a []Service without knowing which transport backs any of them.
func Boot ¶
func Boot[T config.ServiceConfig](ctx context.Context, name string, factory ComponentsFactory[T]) ([]Service, error)
Boot loads name's config from the TOML files and wires name into a running []Service; assemble decides which transports that includes.
func BootAll ¶ added in v1.105.0
func BootAll(ctx context.Context, name string, platform config.PlatformConfig, serviceAuth serviceauth.Config, listen config.ListenConfig, hosted ...HostedService) ([]Service, error)
BootAll runs every hosted service in one process on exactly three listeners, however many services there are: one gRPC server for every service's handlers, grpc.health.v1 and reflection; one HTTP server for every route and the merged /health; one metrics server. Every gRPC service sits behind the one token in serviceAuth, accepted under each hosted service's own header name, so a caller built against one service alone keeps working. The health checks fold into one status. A hosted service's own token, listen addresses and server options are not read; tracing is wired once for the whole server. On error nothing stays open.
func BootWithConfig ¶ added in v1.82.0
func BootWithConfig[T config.ServiceConfig](ctx context.Context, name string, cfg *config.RuntimeConfig[T], factory ComponentsFactory[T]) ([]Service, error)
BootWithConfig is Boot for a config the caller has already loaded, so a binary can choose the config source before booting.
type ServiceManager ¶
type ServiceManager struct {
// contains filtered or unexported fields
}
func NewServiceManager ¶
func NewServiceManager(services ...Service) *ServiceManager
func (*ServiceManager) RunAll ¶
func (m *ServiceManager) RunAll(ctx context.Context, cancel context.CancelCauseFunc) <-chan error
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package grpcserver builds the gRPC transport every service in this repo runs on: the interceptor chain, server reflection, the standard gRPC health service, and the Serve/Shutdown lifecycle pkg/boot.Service expects.
|
Package grpcserver builds the gRPC transport every service in this repo runs on: the interceptor chain, server reflection, the standard gRPC health service, and the Serve/Shutdown lifecycle pkg/boot.Service expects. |
|
Package httpserver builds the HTTP transport every service in this repo runs on: CORS, access logging with correlation IDs, panic recovery, and the Serve/Shutdown lifecycle pkg/boot.Service expects.
|
Package httpserver builds the HTTP transport every service in this repo runs on: CORS, access logging with correlation IDs, panic recovery, and the Serve/Shutdown lifecycle pkg/boot.Service expects. |