serverd

Documentation

Overview

Package serverd assembles and runs a quicSQL server from a validated config: secrets → meta store → reconcile (config ∪ meta) → backends → registry (warm, fail-fast) → sessions → auth/authz → metrics + limiter → HTTP handler → transports. It is the single wiring shared by the cmd/quicsql daemon and the in-process example/tests, so the assembly lives in one place.

Composing the engine

The SQLite engine quicSQL exposes is composed by the BINARY, not the wire: what extensions, custom functions, and VFS backends the process registers is what clients can use, through SQL. A client cannot add or change any of this over the network. Register everything BEFORE calling Run:

import (
    _ "quicsql.net/extensions"   // the curated, network-safe bundle
    sqlite "gosqlite.org"
    "quicsql.net/serverd"
)

func main() {
    // Application-defined SQL functions/collations register globally, on every
    // connection the server opens. (A client Go closure can never execute in
    // this engine — it must be registered here, server-side.)
    sqlite.RegisterAutoHook(func(c *sqlite.Conn) error { return myext.Register(c) })
    cfg, _ := config.Load("quicsql.yaml")
    srv, _ := serverd.Run(cfg, slog.Default())
    // …wait, then srv.Shutdown(ctx)
}

Per-database storage and connection settings (backend/VFS, pragmas via PragmasPreset + Pragmas, grants) live in the config, also server-side.

Index

• type Instance
  • func Run(cfg *config.Config, log *slog.Logger) (*Instance, error)
  • func (in *Instance) Servers() int
  • func (in *Instance) Shutdown(ctx context.Context)

Types

type Instance

type Instance struct {

	// Metrics is the live registry, exposed for tests/introspection.
	Metrics *obs.Registry
	// contains filtered or unexported fields
}

Instance is a running server: its listeners are up and serving. The caller owns its lifetime and must call Shutdown to stop it cleanly.

func Run

func Run(cfg *config.Config, log *slog.Logger) (*Instance, error)

Run assembles and starts the server described by cfg. It returns once every listener is up (or an error if any stage — a bad seed key, a taken port — fails). Seed databases are opened eagerly (fail-fast). The caller drives the lifetime and calls Shutdown.

func (*Instance) Servers

func (in *Instance) Servers() int

Servers reports how many listeners are running.

func (*Instance) Shutdown

func (in *Instance) Shutdown(ctx context.Context)

Shutdown stops the listeners (draining in-flight requests within ctx), then the sessions (rolling back open transactions and returning connections), then the registry (WAL checkpoint on handle close) and the meta store — in that order, so nothing closes a resource still in use.