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 JobPropagator() jobs.Propagator
- func Run(app *App) error
- func RunContext(ctx context.Context, app *App) error
- func RunWorker(ctx context.Context, app *App, opts jobs.WorkerOptions) error
- func SanitizeHTML(s string) string
- func WorkerKillAfter(args []string) time.Duration
- 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) JobMetrics() *jobs.Metrics
- func (a *App) Jobs() *jobs.Dispatcher
- 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 WithJobs(dispatcher *jobs.Dispatcher) 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 WithShutdownDrainDelay(delay time.Duration) Option
- func WithShutdownTimeout(timeout time.Duration) Option
- type WorkerFlags
Constants ¶
const ( JobMetadataRequestID = "gombit.request_id" JobMetadataTraceID = "gombit.trace_id" )
Envelope metadata keys JobPropagator writes.
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.
const WorkerCommand = "worker"
WorkerCommand is the first argument that makes Run start a jobs worker instead of the HTTP server: `./server worker --queue mail --concurrency 8`. One binary deploys as both the web and the worker process.
Variables ¶
This section is empty.
Functions ¶
func GetRequestID ¶
GetRequestID returns the request ID for the current request. It reads the value requestContextMiddleware propagated through the request context, so it agrees with GetRequestIDFromContext by construction.
func GetRequestIDFromContext ¶
GetRequestIDFromContext reads the request ID from a request context.
func GetTraceID ¶
GetTraceID returns the trace ID for the current request. It reads the value requestContextMiddleware propagated through the request context, so it agrees with GetTraceIDFromContext by construction.
func GetTraceIDFromContext ¶
GetTraceIDFromContext reads the trace ID from a request context.
func JobPropagator ¶ added in v0.5.0
func JobPropagator() jobs.Propagator
JobPropagator carries the request and trace IDs of the request that dispatched a job into the job handler's context, so GetRequestIDFromContext / GetTraceIDFromContext (and the logs that use them) correlate a job with the request that queued it.
func Run ¶
Run runs app until an interrupt or terminate signal is received: the HTTP server, or, when the process's first argument is "worker", the jobs worker (see RunWorker; `./server worker --help` lists its flags). Other arguments are ignored, as before.
func RunContext ¶
RunContext runs app until ctx is canceled or the HTTP server fails.
func RunWorker ¶ added in v0.5.0
RunWorker runs app as a jobs worker until ctx is canceled: the start hooks, a jobs.Worker over App.Jobs(), then the stop hooks. It serves no HTTP. opts.Queues defaults to the dispatcher's default queue and opts.Logger to the app's logger.
func SanitizeHTML ¶ added in v0.2.0
SanitizeHTML strips HTML tags from s and discards the content of dangerous elements (script, style, iframe, object, embed, noscript, textarea), returning plain text. It is the per-value function the optional input sanitizer applies, exported (issue #271 / PERF-13) so an app can strip a specific field from a handler without re-enabling ingress sanitization for the whole request pipeline (Security.SanitizeInput).
A string with no HTML tag is returned unchanged, and so is one that holds a bare "<"/">" without forming a complete tag ("a<b") — see the stripHTML doc for the #118 comparison-text handling. Sanitization is an output-encoding backstop, not a substitute for escaping on output.
func WorkerKillAfter ¶ added in v0.5.0
WorkerKillAfter is how long a process supervisor should wait after asking a worker started with args to stop before killing it: its shutdown timeout plus workerShutdownGrace (28s).
Types ¶
type App ¶
type App struct {
// contains filtered or unexported fields
}
App owns Gombit's runtime lifecycle and HTTP router.
func (*App) JobMetrics ¶ added in v0.5.0
JobMetrics returns the metrics workers in this process record into.
func (*App) Jobs ¶ added in v0.5.0
func (a *App) Jobs() *jobs.Dispatcher
Cache returns the configured cache implementation. Jobs returns the job dispatcher: register jobs on Jobs().Registry() at startup, and dispatch with Jobs().Dispatch. The driver comes from Config.Jobs (GOMBIT_JOBS_DRIVER, sync by default), and the registry carries request and trace IDs into job handlers (JobPropagator).
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 WithJobs ¶ added in v0.5.0
func WithJobs(dispatcher *jobs.Dispatcher) Option
WithJobs attaches a job dispatcher the caller opened, instead of the one App opens from Config.Jobs. App does not close a dispatcher attached this way.
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 WithShutdownDrainDelay ¶ added in v0.1.13
WithShutdownDrainDelay sets a delay between the start of graceful shutdown — when /readyz begins returning 503 (HOST-2 / ADR-015) — and the moment the HTTP listener stops accepting connections. During the delay the server keeps serving, so a host that gates traffic on /readyz observes the 503 and deregisters the instance before any request is connection-refused. Without a delay (the default, 0) the flag still sheds in-flight and keep-alive pollers during the shutdown grace period, but a host opening a fresh probe connection after shutdown begins sees connection-refused rather than a 503. Set this to a host's readiness poll interval (a few seconds) for a clean drain.
func WithShutdownTimeout ¶
WithShutdownTimeout sets the bounded shutdown timeout.
type WorkerFlags ¶ added in v0.5.0
type WorkerFlags struct {
jobs.WorkerOptions
// MetricsAddr, when set, serves /metrics (job outcomes and queue depth)
// and /livez on that address while the worker runs.
MetricsAddr string
}
WorkerFlags are the parsed worker flags: the worker's options, plus where to serve its metrics.
func ParseWorkerFlags ¶ added in v0.5.0
func ParseWorkerFlags(args []string, output io.Writer) (WorkerFlags, error)
ParseWorkerFlags parses the worker flags `gombit worker` and `./server worker` share: --queue (repeatable or comma-separated, in priority order), --concurrency, --lease, --shutdown-timeout, and --metrics-addr.
Source Files