framework

Documentation

Overview

Package framework provides Gombit's runtime application lifecycle and HTTP surfaces (Gin router escape hatch and Huma contract API).

Index

• Constants
• func GetRequestID(c *gin.Context) string
• func GetRequestIDFromContext(ctx context.Context) string
• func GetTraceID(c *gin.Context) string
• func GetTraceIDFromContext(ctx context.Context) string
• func Run(app *App) error
• func RunContext(ctx context.Context, app *App) error
• type App
  • func New(options ...Option) (*App, error)
  • func (a *App) API() huma.API
  • func (a *App) Addr() string
  • func (a *App) Cache() cache.Cache
  • func (a *App) Config() config.Config
  • func (a *App) DB() *gorm.DB
  • func (a *App) Database() *database.DB
  • func (a *App) Logger() *zap.Logger
  • func (a *App) OnStart(hook Hook)
  • func (a *App) OnStop(hook Hook)
  • func (a *App) Redis() *redis.Client
  • func (a *App) Router() *gin.Engine
• type Hook
• type Option
  • func WithCache(c cache.Cache) Option
  • func WithConfig(cfg config.Config) Option
  • func WithDatabase(db *database.DB) Option
  • func WithEmbeddedFrontend(fsys fs.FS) Option
  • func WithLogger(logger *zap.Logger) Option
  • func WithRedis(client *redis.Client) Option
  • func WithRouter(router *gin.Engine) Option
  • func WithShutdownTimeout(timeout time.Duration) Option

Constants

const RequestIDHeader = "X-Request-Id"

RequestIDHeader is the HTTP header carrying a stable per-request ID.

const TraceIDHeader = "X-Trace-Id"

TraceIDHeader exposes the active trace ID for logs, diagnostics, and tests.

const TraceparentHeader = "Traceparent"

TraceparentHeader is the W3C trace context header.

Functions

func GetRequestID

func GetRequestID(c *gin.Context) string

GetRequestID returns the request ID stored in the Gin context.

func GetRequestIDFromContext

func GetRequestIDFromContext(ctx context.Context) string

GetRequestIDFromContext reads the request ID from a request context.

func GetTraceID

func GetTraceID(c *gin.Context) string

GetTraceID returns the trace ID stored in the Gin context.

func GetTraceIDFromContext

func GetTraceIDFromContext(ctx context.Context) string

GetTraceIDFromContext reads the trace ID from a request context.

func Run

func Run(app *App) error

Run runs app until an interrupt or terminate signal is received.

func RunContext

func RunContext(ctx context.Context, app *App) error

RunContext runs app until ctx is canceled or the HTTP server fails.

Types

type App

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

App owns Gombit's runtime lifecycle and HTTP router.

func New

func New(options ...Option) (*App, error)

New creates an application using process configuration and the default router.

func (*App) API

func (a *App) API() huma.API

API returns the Huma API used for contract-typed route registration.

func (*App) Addr

func (a *App) Addr() string

Addr returns the bound HTTP address after the app has started.

func (*App) Cache

func (a *App) Cache() cache.Cache

Cache returns the configured cache implementation.

func (*App) Config

func (a *App) Config() config.Config

Config returns the typed app configuration.

func (*App) DB

func (a *App) DB() *gorm.DB

DB returns the underlying GORM database escape hatch.

func (*App) Database

func (a *App) Database() *database.DB

Database returns the opened database handle with driver metadata.

func (*App) Logger

func (a *App) Logger() *zap.Logger

Logger returns the app's Zap logger.

func (*App) OnStart

func (a *App) OnStart(hook Hook)

OnStart registers a start hook. Hooks run in registration order.

func (*App) OnStop

func (a *App) OnStop(hook Hook)

OnStop registers a stop hook. Hooks run in reverse registration order.

func (*App) Redis

func (a *App) Redis() *redis.Client

Redis returns the underlying go-redis client when Redis is enabled.

func (*App) Router

func (a *App) Router() *gin.Engine

Router returns the underlying Gin router escape hatch.

type Hook

type Hook func(context.Context) error

Hook is an application lifecycle callback.

type Option

type Option func(*App) error

Option configures an App.

func WithCache

func WithCache(c cache.Cache) Option

WithCache attaches an application-owned cache implementation to the app.

func WithConfig

func WithConfig(cfg config.Config) Option

WithConfig sets the app configuration. DocsEnabled is taken as given: Default() leaves /docs on even if you later set Environment to production. Use config.DefaultFor(env) or set API.DocsEnabled yourself.

func WithDatabase

func WithDatabase(db *database.DB) Option

WithDatabase attaches an opened database handle to the app.

func WithEmbeddedFrontend

func WithEmbeddedFrontend(fsys fs.FS) Option

WithEmbeddedFrontend stores fsys and, when it contains index.html at its root, installs a Gin NoRoute handler after framework routes so unmatched GET paths serve the SPA. Huma /api/*, /openapi.json, /docs, and the probe routes still win because they are registered before NoRoute runs.

If fsys has no index.html (the gombit new placeholder embed), NoRoute is not installed and unknown paths keep their current 404. Split deploy is the default (C5); embedding is opt-in via gombit build --embed.

func WithLogger

func WithLogger(logger *zap.Logger) Option

WithLogger attaches a Zap logger to the app.

func WithRedis

func WithRedis(client *redis.Client) Option

WithRedis attaches an application-owned Redis client as the app cache.

func WithRouter

func WithRouter(router *gin.Engine) Option

WithRouter sets the app router.

func WithShutdownTimeout

func WithShutdownTimeout(timeout time.Duration) Option

WithShutdownTimeout sets the bounded shutdown timeout.