Documentation
¶
Overview ¶
Package setup wires the full standard stack in one call with correct ordering, eliminating the "register everything in the right order" footgun.
Usage:
mgr := gscore.New(gscore.Config{})
result, err := setup.New().
WithLogger(logcore.Options{Service: "my-service"}).
WithOTel(ctx).
WithGORM(db).
Build(mgr)
if err != nil {
log.Fatal(err)
}
Index ¶
- type Builder
- func (b *Builder) Build(mgr *gscore.Manager) (*Result, error)
- func (b *Builder) WithAutobatch(p *autobatch.Plugin) *Builder
- func (b *Builder) WithAutobatchConfig(cfg autobatch.Config) *Builder
- func (b *Builder) WithFiberV2(app *fiberv2.App) *Builder
- func (b *Builder) WithFiberV3(app *fiberv3.App) *Builder
- func (b *Builder) WithGORM(db *gorm.DB) *Builder
- func (b *Builder) WithGORMCache(p *caches.Caches) *Builder
- func (b *Builder) WithGORMCacheConfig(cfg caches.Config) *Builder
- func (b *Builder) WithHTTPClientLogging() *Builder
- func (b *Builder) WithHealthProbesV2(cfg HealthProbesConfig) *Builder
- func (b *Builder) WithHealthProbesV3(cfg HealthProbesConfig) *Builder
- func (b *Builder) WithLogger(opts logcore.Options) *Builder
- func (b *Builder) WithOTel(ctx context.Context) *Builder
- func (b *Builder) WithProcessStart(t time.Time) *Builder
- func (b *Builder) WithRedis(client redis.UniversalClient, name string) *Builder
- func (b *Builder) WithRueidis(client rueidis.Client, name string) *Builder
- func (b *Builder) WithStartupFn(fn func() error) *Builder
- type HealthProbesConfig
- type Result
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder accumulates configuration via functional options before wiring everything in Build. The zero value is valid; calling Build with no options registers nothing and returns an empty Result.
func (*Builder) Build ¶
Build wires all configured components onto mgr in the required order:
- gsfiber.RegisterApp / gsfiberv3.RegisterApp (if WithFiberV2 / WithFiberV3) 0a. liveness + readiness + startup probe routes (if WithHealthProbesV2 / WithHealthProbesV3)
- apmcore.SetupOTelSDK (if WithOTel)
- logcore.New + logcore.SetGlobal (if WithLogger)
- apmcore.NewGormPlugin via db.Use (if WithGORM + WithOTel)
- mgr.RegisterDB (if WithGORM)
- txcore.RegisterWithManager (if WithGORM)
- apmcore.RegisterDBPoolMetricsWithManager (if WithGORM + WithOTel)
- autobatch.RegisterWithManager (if WithAutobatch or WithAutobatchConfig) 7b. gormcache plugin via db.Use (if WithGORMCache or WithGORMCacheConfig)
- go-redis closers + optional OTel hooks (if WithRedis)
- rueidis closers + optional OTel wrapping (if WithRueidis)
- apmcore.RegisterWithManager (if WithOTel)
- logcore.InstallHTTPClientHook (if WithHTTPClientLogging)
- startupFn() + mgr.MarkStarted() (if WithStartupFn)
Build returns an error if apmcore.SetupOTelSDK, logcore.New, db.Use(apmcore.NewGormPlugin()), or the startup function fails, or if WithHealthProbesV2/V3 is set without a corresponding WithFiberV2/V3.
func (*Builder) WithAutobatch ¶
WithAutobatch configures the builder to register p.Close() as a PhasePostDrain closer on the Manager, draining batched writes before the DB pool closes.
func (*Builder) WithAutobatchConfig ¶
WithAutobatchConfig configures the builder to create an autobatch plugin from cfg and register it with the Manager. When WithOTel is also set, Build automatically injects cfg.SpanEmitter = apmcore.BatchSpanEmitter() before creating the plugin so batched writes appear in APM traces.
func (*Builder) WithFiberV2 ¶
WithFiberV2 registers a Fiber v2 app on the Manager so it is drained during the drain phase of graceful shutdown. Multiple calls are not supported; only the last supplied app is registered.
func (*Builder) WithFiberV3 ¶
WithFiberV3 registers a Fiber v3 app on the Manager so it is drained during the drain phase of graceful shutdown. Multiple calls are not supported; only the last supplied app is registered.
func (*Builder) WithGORM ¶
WithGORM configures the builder to register txcore with the Manager so that in-flight transactions are drained before the DB pool is closed.
func (*Builder) WithGORMCache ¶ added in v0.8.0
WithGORMCache configures the builder to register a pre-built gormcache plugin via db.Use during Build. Use WithGORMCacheConfig instead when you want Build to construct the plugin and wire OTel instrumentation automatically.
func (*Builder) WithGORMCacheConfig ¶ added in v0.8.0
WithGORMCacheConfig configures the builder to create a gormcache plugin from cfg and register it with GORM during Build. When WithOTel is also set, Build automatically wraps cfg.Cacher with apmcore.InstrumentCacher so cache operations appear as OTel spans.
func (*Builder) WithHTTPClientLogging ¶
WithHTTPClientLogging configures the builder to install the global logcore HTTP client hook via logcore.InstallHTTPClientHook. The hook is installed after the logger is set up so it inherits the configured global logger.
func (*Builder) WithHealthProbesV2 ¶ added in v0.7.1
func (b *Builder) WithHealthProbesV2(cfg HealthProbesConfig) *Builder
WithHealthProbesV2 registers the three Kubernetes probe handlers (liveness, readiness, startup) on the Fiber v2 app. Must be called after WithFiberV2. cfg may be zero-valued to use the default paths:
GET /healthz/live → always 200 (liveness) GET /healthz/ready → 200 while ready, 503 during shutdown (readiness) GET /healthz/startup → 503 until mgr.MarkStarted(), then 200 (startup)
func (*Builder) WithHealthProbesV3 ¶ added in v0.7.1
func (b *Builder) WithHealthProbesV3(cfg HealthProbesConfig) *Builder
WithHealthProbesV3 registers the three Kubernetes probe handlers (liveness, readiness, startup) on the Fiber v3 app. Must be called after WithFiberV3. cfg may be zero-valued to use the default paths:
GET /healthz/live → always 200 (liveness) GET /healthz/ready → 200 while ready, 503 during shutdown (readiness) GET /healthz/startup → 503 until mgr.MarkStarted(), then 200 (startup)
func (*Builder) WithLogger ¶
WithLogger configures the builder to create a logcore.Logger using opts and set it as the process-global logger.
func (*Builder) WithOTel ¶
WithOTel configures the builder to call apmcore.SetupOTelSDK(ctx) during Build. ctx is typically the application root context or context.Background().
func (*Builder) WithProcessStart ¶ added in v0.8.3
WithProcessStart sets the wall-clock time used as the boot origin for app.startup.duration_ms. Pass time.Now() as early as possible in main — before any other setup runs — so the metric covers the full boot sequence.
When WithOTel is also configured and the Manager is a *gscore.Manager, Build automatically calls apmcore.RegisterStartupMetricsWithManager using this timestamp. If WithProcessStart is not called, startup metrics are not registered even when WithOTel is set.
func (*Builder) WithRedis ¶
func (b *Builder) WithRedis(client redis.UniversalClient, name string) *Builder
WithRedis registers a go-redis UniversalClient for graceful shutdown at PhasePostDB and, if WithOTel was also called, instruments it with OTel tracing and metrics. Multiple calls accumulate; each client is registered independently. name is used in shutdown log lines.
func (*Builder) WithRueidis ¶
WithRueidis registers a rueidis Client for graceful shutdown at PhasePostDB and, if WithOTel was also called, wraps it with OTel tracing and metrics. Multiple calls accumulate; each client is registered independently. name is used in shutdown log lines.
func (*Builder) WithStartupFn ¶ added in v0.7.1
WithStartupFn registers a boot function that runs at the end of Build, after all components are wired. If fn returns nil, mgr.MarkStarted() is called automatically, flipping the startup probe to 200. If fn returns an error, Build returns that error and MarkStarted is never called.
This is the recommended way to run migrations and warm-up logic, as it makes the relationship between boot completion and startup probe explicit:
setup.New().
WithFiberV2(app).
WithHealthProbesV2(setup.HealthProbesConfig{}).
WithGORM(db).
WithStartupFn(func() error {
if err := runMigrations(db); err != nil {
return err
}
return warmUpCache(ctx)
}).
Build(mgr)
// mgr.MarkStarted() was called automatically — startup probe is now 200.
type HealthProbesConfig ¶ added in v0.7.1
type HealthProbesConfig struct {
// LivenessPath is the path for the liveness probe (default: /healthz/live).
LivenessPath string
// ReadinessPath is the path for the readiness probe (default: /healthz/ready).
ReadinessPath string
// StartupPath is the path for the startup probe (default: /healthz/startup).
StartupPath string
}
HealthProbesConfig holds the HTTP paths for the three Kubernetes probe endpoints. Zero values fall back to the defaults below.
type Result ¶
type Result struct {
// Logger is the logcore.Logger created by WithLogger; nil if not configured.
Logger *logcore.Logger
// Shutdown is the OTel/APM shutdown function registered by WithOTel; nil
// if not configured.
Shutdown apmcore.ShutdownFunc
}
Result is returned by Build and carries handles to the resources that were created. Fields are nil/zero when the corresponding With-option was not set.
Source Files