Documentation
¶
Overview ¶
Package app is the importable composition root: the single exported entry point that builds and runs the fully-wired mere application. Everything else stays under internal/. A wrapper module depends on exactly two exported packages — this one to build + run, and extension for the seam types — and never imports the internals directly (see docs/extending.md).
The boot sequence and the three-phase SIGTERM choreography are core behavior, so they live here rather than in cmd/server, which collapses to a thin shim.
Index ¶
- func Run(ctx context.Context, opts ...Option) error
- type App
- type Option
- func WithEntitlement(e extension.Entitlement) Option
- func WithHandlerMiddleware(mw ...func(http.Handler) http.Handler) Option
- func WithLogger(l *slog.Logger) Option
- func WithRateLimiter(rl extension.RateLimiter) Option
- func WithUpgradeURL(url string) Option
- func WithUsageSink(us extension.UsageSink) Option
- func WithVersion(v string) Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type App ¶
type App struct {
// contains filtered or unexported fields
}
App is a wired, not-yet-listening application: the http.Server plus the closers for its Postgres/ClickHouse pools and ingest pipeline.
func Build ¶
Build runs the full boot sequence (config load, DB open, migrations, CH bootstrap, service construction, handler assembly) and returns a wired App that is not yet listening. Config is read from the environment. On any failure, partially-opened resources are released before returning.
func (*App) Close ¶
Close releases the pools and ingest pipeline for Build-only callers (e.g. tests that use Handler without Run). It first drains the ingest goroutines so they don't touch a closed ClickHouse pool, then closes the pools in reverse open order. Idempotent: a second call (e.g. after Run already drained ingest) is a no-op for the pipeline.
func (*App) Handler ¶
Handler returns the assembled root handler, for serve-it-yourself / httptest callers (and Build-only tests).
func (*App) Run ¶
Run serves until ctx is cancelled (SIGTERM) or the listener fails, then runs the three-phase shutdown so no event is silently dropped:
phase 1 — ingest.SetDisabled(true) ; new ingest POSTs → 503 phase 2 — http.Shutdown ; in-flight handlers finish enqueue phase 3 — ingest.Shutdown(grace) ; drain → CH, residual → DLQ
Pools/pipeline are released on return via Close.
type Option ¶
type Option func(*options)
Option configures Build/Run. Adding options is public API and a potential breaking change for wrappers; keep the surface small.
func WithEntitlement ¶
func WithEntitlement(e extension.Entitlement) Option
WithEntitlement injects the analysis gate consulted on the query/schema/MCP and web-playground surfaces after the project resolves. Defaults to the no-op extension.Unlimited, so the open-source build never gates analysis. A hosted wrapper injects a real implementation to lock a project's analysis once it is over quota (ingest is never gated).
func WithHandlerMiddleware ¶
WithHandlerMiddleware wraps the assembled root handler with edge middleware (e.g. a hosted layer's IP-level limiter or WAF). The first middleware listed is outermost: request flows mw[0] → mw[1] → … → core handler.
func WithLogger ¶
WithLogger sets the structured logger. Defaults to slog.Default().
func WithRateLimiter ¶
func WithRateLimiter(rl extension.RateLimiter) Option
WithRateLimiter injects the ingest/query/MCP rate-limit seam. Defaults to the no-op extension.AllowAll.
func WithUpgradeURL ¶
WithUpgradeURL sets where the web query playground redirects when the Entitlement seam denies an over-quota project — the wrapper's branded billing/upgrade page. Has no effect under the default extension.Unlimited (which never denies); the API and MCP surfaces always answer 402 regardless.
func WithUsageSink ¶
WithUsageSink injects the ingest metering seam. Defaults to the no-op extension.Discard.
func WithVersion ¶
WithVersion sets the build stamp surfaced in the /healthz body. cmd/server forwards its -ldflags Version here.
Source Files