app

package
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 16, 2026 License: AGPL-3.0 Imports: 21 Imported by: 0

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

Constants

View Source 
const PlaygroundMaxRows = 1000

PlaygroundMaxRows is the row cap the built-in web playground renders. Wrappers building their own playground should pass this (or smaller) to ExecuteQuery so they get the same bounded, in-memory behavior.

Variables

View Source 
var (
	ErrQueryEmptySQL           = query.ErrEmptySQL
	ErrQueryRowLimitExceeded   = query.ErrRowLimitExceeded
	ErrQuerySettingsNotAllowed = query.ErrSettingsNotAllowed
)

Query error sentinels re-exported so wrappers can branch on them with errors.Is without importing internal packages.

Functions

func Run 

func Run(ctx context.Context, opts ...Option) error

Run = Build + ListenAndServe + the three-phase SIGTERM choreography. The passed ctx is augmented with SIGINT/SIGTERM handling, so a plain context.Background() from the entry point is enough.

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 

func Build(ctx context.Context, opts ...Option) (_ *App, err error)

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 

func (a *App) Close() error

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) ExecuteQuery added in v0.1.2 

func (a *App) ExecuteQuery(ctx context.Context, projectID, sql string, maxRows int) (QueryResult, error)

ExecuteQuery runs read-only SQL against the project's analytics data through the same bounded, tenant-isolated executor that powers the built-in playground. The result is buffered in memory and capped at maxRows. Tenant isolation (project scoping) and SQL-safety checks stay entirely in the core; the projectID the caller passes is the only scoping input.

func (*App) Handler 

func (a *App) Handler() http.Handler

Handler returns the assembled root handler, for serve-it-yourself / httptest callers (and Build-only tests).

func (*App) QuerySchema added in v0.1.2 

func (a *App) QuerySchema(ctx context.Context) (QueryCatalog, error)

QuerySchema returns the curated catalog of queryable tables/columns — the same catalog the API and MCP surfaces expose. It is not project-specific.

func (*App) Run 

func (a *App) Run(ctx context.Context) error

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 

func WithHandlerMiddleware(mw ...func(http.Handler) http.Handler) Option

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 

func WithLogger(l *slog.Logger) Option

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 

func WithUpgradeURL(url string) Option

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 

func WithUsageSink(us extension.UsageSink) Option

WithUsageSink injects the ingest metering seam. Defaults to the no-op extension.Discard.

func WithVersion 

func WithVersion(v string) Option

WithVersion sets the build stamp surfaced in the /healthz body. cmd/server forwards its -ldflags Version here.

type QueryCatalog added in v0.1.2 

type QueryCatalog struct {
	Tables []SchemaTable
}

type QueryColumn added in v0.1.2 

type QueryColumn struct {
	Name string
	Type string
}

QueryColumn / QueryStats / QueryResult mirror the internal query result shape so wrappers can render results without importing internal/query.

type QueryResult added in v0.1.2 

type QueryResult struct {
	Columns []QueryColumn
	Rows    [][]any
	Stats   QueryStats
}

type QueryStats added in v0.1.2 

type QueryStats struct {
	Rows      int64
	ElapsedMS int64
}

type SchemaColumn added in v0.1.2 

type SchemaColumn struct {
	Name        string
	Type        string
	Description string
}

SchemaColumn / SchemaTable / QueryCatalog mirror the curated schema catalog (table + column names, types, and descriptions) for the same reason.

type SchemaTable added in v0.1.2 

type SchemaTable struct {
	Name        string
	Description string
	Columns     []SchemaColumn
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.