Documentation
¶
Overview ¶
Package bootstrap composes common contrib adapters and core middleware into application profiles.
System endpoints and pprof profiles -----------------------------------
`MountSystemEndpoints` and `MountSystemEndpointsTo` use production-safe defaults where pprof is disabled unless explicitly enabled.
Development wiring example:
bootstrap.MountSystemEndpointsToWithProfile(router, bootstrap.SystemEndpoints{
Health: health.NewHandler(nil),
Pprof: pprof.Handler(),
Version: version.NewHandler(version.Config{}),
}, "development")
Production wiring example:
bootstrap.MountSystemEndpointsToWithProfile(router, bootstrap.SystemEndpoints{
Health: health.NewHandler(nil),
Pprof: pprof.Handler(),
}, "production")
In production profiles, pass `bootstrap.SystemEndpointOptions{EnablePprof:true}` when there is an explicit policy decision to expose profiling.
Index ¶
- func HardenedServer(addr string, handler http.Handler, opts ...ServerOption) *http.Server
- func MountSystemEndpoints(r ports.HTTPRouter, se SystemEndpoints)
- func MountSystemEndpointsTo(r ports.MethodRouteRegistrar, se SystemEndpoints)
- func MountSystemEndpointsToWithOptions(r ports.MethodRouteRegistrar, se SystemEndpoints, opts SystemEndpointOptions)
- func MountSystemEndpointsToWithProfile(r ports.MethodRouteRegistrar, se SystemEndpoints, profile string)
- func NewDefaultRouter(log ports.Logger) (ports.HTTPRouter, error)
- func NewDefaultRouterWithConfig(log ports.Logger, cfg DefaultRouterConfig) (ports.HTTPRouter, error)
- func NewMigrator(dsn, table string, lockKey int64, allowDown bool, log ports.Logger, ...) (ports.Migrator, error)
- func NewMigratorWithContext(ctx context.Context, dsn, table string, lockKey int64, allowDown bool, ...) (ports.Migrator, error)
- func OpenAndPingDB(ctx context.Context, dsn string, timeout time.Duration) (ports.DatabasePool, error)
- func OpenPoolOrExit(ctx context.Context, dsn string, timeout time.Duration, log ports.Logger) ports.DatabasePool
- func PrometheusMetricsHandler() http.Handler
- func RunDown(ctx context.Context, m ports.Migrator, dir string) error
- func RunMigrations(ctx context.Context, cfg config.Config, log ports.Logger, embedded []fs.FS) (err error)
- func RunMigrationsOrExit(ctx context.Context, cfg config.Config, log ports.Logger, embedded []fs.FS)
- func RunUp(ctx context.Context, m ports.Migrator, dir string) error
- func StartServer(ctx context.Context, addr string, handler http.Handler, log ports.Logger) error
- func StartServerOrExit(ctx context.Context, addr string, handler http.Handler, log ports.Logger)
- func Status(ctx context.Context, m ports.Migrator, dir string) (string, error)
- func WithTimeout(parent context.Context, d time.Duration) (context.Context, context.CancelFunc)
- type DefaultRouterConfig
- type Profile
- type ProfileOption
- func WithCORSOptions(opts ports.CORSOptions) ProfileOption
- func WithIdentityResolver(resolver identity.Resolver) ProfileOption
- func WithJSONStrict(strict bool) ProfileOption
- func WithMaxBodyBytes(n int64) ProfileOption
- func WithMetricsRecorder(rec metricsmw.MetricsRecorder) ProfileOption
- func WithOTelOptions(opts oteltrace.Options) ProfileOption
- func WithQueryLimitsDisabled() ProfileOption
- func WithQueryLimitsOptions(opts querylimits.Options) ProfileOption
- func WithRateLimitDisabled() ProfileOption
- func WithRateLimitOptions(opts rateln.Options) ProfileOption
- func WithRequestLogOptions(opts ...requestlog.Option) ProfileOption
- func WithRequestTimeout(d time.Duration) ProfileOption
- func WithSecureOptions(opts ...securemw.Option) ProfileOption
- type ServerOption
- type SystemEndpointOptions
- type SystemEndpointProfile
- type SystemEndpoints
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HardenedServer ¶
HardenedServer builds an http.Server with safe defaults and optional overrides.
func MountSystemEndpoints ¶
func MountSystemEndpoints(r ports.HTTPRouter, se SystemEndpoints)
MountSystemEndpoints registers health, docs, version, and metrics endpoints.
func MountSystemEndpointsTo ¶ added in v2.1.0
func MountSystemEndpointsTo(r ports.MethodRouteRegistrar, se SystemEndpoints)
MountSystemEndpointsTo registers system endpoints on a minimal GET-only surface.
func MountSystemEndpointsToWithOptions ¶ added in v2.1.0
func MountSystemEndpointsToWithOptions(r ports.MethodRouteRegistrar, se SystemEndpoints, opts SystemEndpointOptions)
MountSystemEndpointsToWithOptions mounts system endpoints with explicit runtime options.
func MountSystemEndpointsToWithProfile ¶ added in v2.1.0
func MountSystemEndpointsToWithProfile(r ports.MethodRouteRegistrar, se SystemEndpoints, profile string)
MountSystemEndpointsToWithProfile mounts system endpoints only if the profile explicitly opts pprof in. This keeps production/staging defaults off by default.
func NewDefaultRouter ¶
func NewDefaultRouter(log ports.Logger) (ports.HTTPRouter, error)
NewDefaultRouter constructs a router with a sensible default middleware stack.
func NewDefaultRouterWithConfig ¶ added in v2.1.0
func NewDefaultRouterWithConfig(log ports.Logger, cfg DefaultRouterConfig) (ports.HTTPRouter, error)
NewDefaultRouterWithConfig constructs a router from explicit configuration.
func NewMigrator ¶
func NewMigrator(dsn, table string, lockKey int64, allowDown bool, log ports.Logger, dirs []string, embedded []fs.FS) (ports.Migrator, error)
NewMigrator builds a migrator with either directories or embedded FS sources.
func NewMigratorWithContext ¶
func NewMigratorWithContext(ctx context.Context, dsn, table string, lockKey int64, allowDown bool, log ports.Logger, dirs []string, embedded []fs.FS) (ports.Migrator, error)
NewMigratorWithContext builds a migrator with either directories or embedded FS sources.
func OpenAndPingDB ¶
func OpenAndPingDB(ctx context.Context, dsn string, timeout time.Duration) (ports.DatabasePool, error)
OpenAndPingDB opens a DB pool and verifies connectivity with a short timeout.
func OpenPoolOrExit ¶
func OpenPoolOrExit(ctx context.Context, dsn string, timeout time.Duration, log ports.Logger) ports.DatabasePool
OpenPoolOrExit opens a DB pool and terminates the process if it fails.
func PrometheusMetricsHandler ¶ added in v2.1.0
PrometheusMetricsHandler returns the standard Prometheus metrics handler for explicit mounting on specs.Metrics.
func RunMigrations ¶ added in v2.1.0
func RunMigrations(ctx context.Context, cfg config.Config, log ports.Logger, embedded []fs.FS) (err error)
RunMigrations runs startup migrations using config defaults and returns errors to the caller. Reusable library code should prefer this function.
func RunMigrationsOrExit ¶
func RunMigrationsOrExit(ctx context.Context, cfg config.Config, log ports.Logger, embedded []fs.FS)
RunMigrationsOrExit runs startup migrations using config defaults or exits on failure. This helper is intended for binaries; reusable library code should prefer RunMigrations.
func StartServer ¶
StartServer runs an HTTP server and performs graceful shutdown when the context is canceled.
func StartServerOrExit ¶
StartServerOrExit runs the HTTP server and exits the process when it fails.
func WithTimeout ¶
WithTimeout derives a context with a default timeout for long-running migration ops.
Types ¶
type DefaultRouterConfig ¶ added in v2.1.0
type DefaultRouterConfig struct {
RateLimit rateln.Options
TrustedProxies []netip.Prefix
Metrics metricsmw.MetricsRecorder
}
DefaultRouterConfig defines the inputs used by NewDefaultRouterWithConfig.
func DefaultRouterConfigFromEnv ¶ added in v2.1.0
func DefaultRouterConfigFromEnv(env ports.EnvVar) (DefaultRouterConfig, error)
DefaultRouterConfigFromEnv loads router defaults from environment variables.
type Profile ¶
type Profile struct {
Middlewares []func(http.Handler) http.Handler
ServerOptions []ServerOption
}
Profile describes a middleware stack and server options.
func ProfileDev ¶
func ProfileDev(log ports.Logger, opts ...ProfileOption) (Profile, error)
ProfileDev builds a developer-friendly profile with relaxed protections.
func ProfileStrictAPI ¶
func ProfileStrictAPI(log ports.Logger, opts ...ProfileOption) (Profile, error)
ProfileStrictAPI builds a hardened API profile.
func (Profile) Apply ¶
func (p Profile) Apply(r ports.HTTPRouter)
Apply attaches the profile middlewares to the router.
func (Profile) ApplyTo ¶ added in v2.1.0
func (p Profile) ApplyTo(r ports.MiddlewareChain)
ApplyTo attaches the profile middlewares to a minimal middleware chain.
type ProfileOption ¶
type ProfileOption func(*profileConfig)
ProfileOption customizes profile defaults.
func WithCORSOptions ¶
func WithCORSOptions(opts ports.CORSOptions) ProfileOption
WithCORSOptions overrides CORS options.
func WithIdentityResolver ¶
func WithIdentityResolver(resolver identity.Resolver) ProfileOption
WithIdentityResolver sets the trusted proxy resolver used by middleware.
func WithJSONStrict ¶
func WithJSONStrict(strict bool) ProfileOption
WithJSONStrict toggles strict JSON parsing.
func WithMaxBodyBytes ¶
func WithMaxBodyBytes(n int64) ProfileOption
WithMaxBodyBytes overrides max request body size.
func WithMetricsRecorder ¶
func WithMetricsRecorder(rec metricsmw.MetricsRecorder) ProfileOption
WithMetricsRecorder sets the metrics recorder.
func WithOTelOptions ¶
func WithOTelOptions(opts oteltrace.Options) ProfileOption
WithOTelOptions overrides OpenTelemetry middleware options.
func WithQueryLimitsDisabled ¶ added in v2.1.0
func WithQueryLimitsDisabled() ProfileOption
WithQueryLimitsDisabled disables query parameter guardrails.
func WithQueryLimitsOptions ¶ added in v2.1.0
func WithQueryLimitsOptions(opts querylimits.Options) ProfileOption
WithQueryLimitsOptions overrides query parameter limits.
func WithRateLimitDisabled ¶
func WithRateLimitDisabled() ProfileOption
WithRateLimitDisabled disables rate limiting.
func WithRateLimitOptions ¶
func WithRateLimitOptions(opts rateln.Options) ProfileOption
WithRateLimitOptions overrides rate limiting settings.
func WithRequestLogOptions ¶
func WithRequestLogOptions(opts ...requestlog.Option) ProfileOption
WithRequestLogOptions appends request log options.
func WithRequestTimeout ¶
func WithRequestTimeout(d time.Duration) ProfileOption
WithRequestTimeout overrides per-request timeout.
func WithSecureOptions ¶
func WithSecureOptions(opts ...securemw.Option) ProfileOption
WithSecureOptions appends secure middleware options.
type ServerOption ¶
ServerOption configures an http.Server instance.
func WithIdleTimeout ¶
func WithIdleTimeout(d time.Duration) ServerOption
WithIdleTimeout overrides IdleTimeout.
func WithMaxHeaderBytes ¶
func WithMaxHeaderBytes(n int) ServerOption
WithMaxHeaderBytes overrides MaxHeaderBytes.
func WithReadHeaderTimeout ¶
func WithReadHeaderTimeout(d time.Duration) ServerOption
WithReadHeaderTimeout overrides ReadHeaderTimeout.
func WithReadTimeout ¶
func WithReadTimeout(d time.Duration) ServerOption
WithReadTimeout overrides ReadTimeout.
func WithWriteTimeout ¶
func WithWriteTimeout(d time.Duration) ServerOption
WithWriteTimeout overrides WriteTimeout.
type SystemEndpointOptions ¶ added in v2.1.0
type SystemEndpointOptions struct {
EnablePprof bool
}
type SystemEndpointProfile ¶ added in v2.1.0
type SystemEndpointProfile string
const ( SystemProfileProduction SystemEndpointProfile = "production" SystemProfileStaging SystemEndpointProfile = "staging" SystemProfileDevelopment SystemEndpointProfile = "development" SystemProfileTest SystemEndpointProfile = "test" )
Source Files