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 (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
- func (a *App) Tx(ctx context.Context, fn func(tx *gorm.DB) error) error
- type Hook
- type Option
- func WithCSRFExemptPaths(paths ...string) 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 WithRawBodyPaths(paths ...string) 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.
Variables ¶
This section is empty.
Functions ¶
func GetRequestID ¶
GetRequestID returns the request ID stored in the Gin context.
func GetRequestIDFromContext ¶
GetRequestIDFromContext reads the request ID from a request context.
func GetTraceID ¶
GetTraceID returns the trace ID stored in the Gin context.
func GetTraceIDFromContext ¶
GetTraceIDFromContext reads the trace ID from a request context.
Types ¶
type App ¶
type App struct {
// contains filtered or unexported fields
}
App owns Gombit's runtime lifecycle and HTTP router.
func (*App) Tx ¶ added in v0.1.7
Tx runs fn inside a single database transaction: it commits when fn returns nil and rolls back on any error or panic. It is the framework home for transactional multi-model writes (atomically update A + B + C) and for cross-row invariants that must read and write consistently. Model Validate hooks (database.Validator) run inside this transaction too. Use struct writes (Create/Save/Updates(struct)) so Validate sees the values being written — an invariant checked in Validate then cannot commit alongside a change that violates it.
err := app.Tx(ctx, func(tx *gorm.DB) error {
if err := tx.Create(&a).Error; err != nil { return err }
b.Count++
return tx.Save(&b).Error
})
type Option ¶
Option configures an App.
func WithCSRFExemptPaths ¶ added in v0.1.6
WithCSRFExemptPaths marks exact request paths that opt out of cookie-mode CSRF enforcement on unsafe methods. Use it for non-browser endpoints that cannot participate in the double-submit defense — webhooks, server-to-server callbacks — which must authenticate themselves by other means (e.g. HMAC signature verification). Paths match the request path exactly, including the API prefix, e.g. "/api/v1/webhooks/github". No effect in JWT mode or when a custom router is supplied via WithRouter.
func WithCache ¶
WithCache attaches a cache implementation the caller opened. Unlike the cache App opens for itself via cache.Open (closed automatically on shutdown), App does not call Close on a cache attached this way — the caller keeps ownership and is responsible for closing it, including stopping a cache.Memory janitor goroutine started with cache.WithJanitor.
func WithConfig ¶
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 ¶
WithDatabase attaches an opened database handle to the app.
func WithEmbeddedFrontend ¶
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 ¶
WithLogger attaches a Zap logger to the app.
func WithRawBodyPaths ¶ added in v0.1.7
WithRawBodyPaths marks exact request paths whose request body must reach the handler byte-for-byte unmodified — webhooks and other server-to-server endpoints that verify a signature over the raw body (e.g. GitHub's X-Hub-Signature-256 HMAC). The XSS input sanitizer, which otherwise re-encodes JSON request bodies, is skipped for these paths.
Such an endpoint also cannot participate in the cookie CSRF double-submit, so raw-body paths are additionally CSRF-exempt (the union with WithCSRFExemptPaths) — declaring a webhook path here is enough. The handler must authenticate the caller itself. Paths match the request path exactly, including the API prefix, e.g. "/api/v1/webhooks/github". No effect when a custom router is supplied via WithRouter.
func WithShutdownTimeout ¶
WithShutdownTimeout sets the bounded shutdown timeout.
Source Files