lidza

README

Līdza is a web framework with a Go control plane (HTTP routing, dev proxy, CLI, MCP server), an optional Rust compute plane (packs compiled to WASM, run by wazero in a bounded, deadlined pool, for code that must be contained), and any frontend (Vite, Astro, Svelte, HTMX, Flutter). It is built for AI agents as the primary developers: machine-readable contracts, structured diagnostics, no implicit magic.

Name

• Līdza in prose, docs and branding.
• lidza in every identifier: CLI binary, Go module, crate prefix, config file, npm scope.

Quick start

curl -fsSL https://raw.githubusercontent.com/agim/lidza/master/install.sh | sh -s -- --services
lidza new myapp --packs db,auth,mail --agent claude && cd myapp
lidza dev
claude        # or: codex, gemini

Releases are tags (CHANGELOG.md): the installer installs the release it was tested with, go install github.com/agim/lidza/cmd/lidza@v0.1.2 a specific one, and an app's go.mod pins the version of the CLI that created it.

The installer sets up Go, Rust with wasm targets, the helper tools and the lidza CLI, skipping what you already have. lidza new writes the agent instructions once, in AGENTS.md, with CLAUDE.md and GEMINI.md importing it, so Claude Code, Codex and Gemini CLI can start building at once. Full guide: docs/getting-started.md.

Frontend

Default template: Vite + React + TypeScript. svelte, astro (static) and htmx (Go-rendered) are selectable at lidza new --template <name>. All follow the same contract: Go owns /api, types come from the generated client, production is one binary.

Deploying

lidza build makes one binary; docs/deploy.md covers running it yourself (systemd, Docker, TLS built in or behind a proxy). For managed deploys from a portal, Līdza Deploy is a deployment agent and web control panel for Līdza apps: deploys from GitHub on push, many apps per server, each on its own domain with automatic HTTPS, health checks before traffic switches, logs, history and rollback, and team roles.

Status

Phases 1 to 9 done: lidza new with the react, svelte, astro and htmx templates, lidza dev (Go and frontend hot reload behind one port), lidza build (one binary), the agent interface (lidza check --json, lidza context, lidza mcp, /llms.txt), schema.lidza with generated Go, SQL, migrations and Rust, typed handlers, OpenAPI and the generated @lidza/client, the middleware pipeline, and packs: Rust capabilities run as WASM in a bounded pool, official db, realtime, geo and media; scale primitives: /metrics, /healthz, /readyz, rate limiting, circuit breaker, lidza check rules for unbounded state, lidza benchmark on k6; application services: auth (sessions, sign-in with email and password or with Google, GitHub, Microsoft and any OIDC issuer), jobs, cache, i18n packs and lidza test; frontend depth: prerendered routes, accessibility in lidza check, useLive, client-side validators; teams and invitations, full-text search, outbound webhooks and Stripe billing; production readiness: fuzzed parsers, migrations without downtime, OpenTelemetry tracing, a configuration reference, Kubernetes manifests. Every roadmap phase is delivered. See docs/roadmap.md; docs/features.md maps every capability to a phase.

Developing the framework

The mail pack sends through Mailgun, SendGrid, Postmark, Resend or SMTP, with To/Reply-To lists, Cc/Bcc and byte attachments. Set ContentID on an attachment and reference cid:<ID> in HTML to embed it; the ID and filename stay independent. Queued delivery and retries preserve these fields and custom headers. SendTx commits the outbox and delivery job with application writes. Default limits are 50 recipients, 10 files and 10 MiB of decoded attachment data; set MAIL_MAX_RECIPIENTS, MAIL_MAX_ATTACHMENTS and MAIL_MAX_ATTACHMENT_BYTES to change them. MAIL_SMTP_TIMEOUT bounds the entire SMTP exchange (default 30 seconds). The generated guide's Send an email recipe covers the API and safety checks.

go vet ./... && staticcheck ./... && go test ./...
(cd core && cargo test)
go build -o bin/lidza ./cmd/lidza
bin/lidza new demo --lidza-dir "$PWD"   # an app pointed at this checkout

docs/environment.md has the full check list and the host setup.

Docs

• docs/getting-started.md: install, create an app, build it with Claude Code, Codex or Gemini CLI.
• docs/environment.md: host inventory, toolchain plan, services, layout, naming, verification.
• docs/roadmap.md: phases and acceptance checks.
• docs/features.md: feature matrix, what is done, what comes when, open decisions.
• docs/scalability.md: the scalable-by-default primitives and the rules every change follows.
• docs/design.md: why Līdza is built the way it is.
• docs/configuration.md: every setting an app reads, generated from the source.
• docs/security.md: what Līdza defends against and what it leaves to the app.
• CONTRIBUTING.md: how to propose a change, the checks, the conventions.
• docs/versioning.md: what the public API is, how releases may change it before v1.0, and the v1.0 freeze.
• docs/deploy.md: deploying an app; managed deploys with Līdza Deploy.

License

Apache License 2.0. See LICENSE.

Documentation

Overview

Package lidza is the runtime a Līdza application links against. The app's main.go embeds its frontend build and calls Run; `lidza dev` starts the same binary in dev mode with the frontend proxied from its dev server.

Index

• Constants
• func DirFS(dir string) (fs.FS, error)
• func HTTPClient(ctx context.Context) *http.Client
• func Handler(app App) (http.Handler, error)
• func Log(ctx context.Context) *slog.Logger
• func NewLogger() *slog.Logger
• func Now(ctx context.Context) time.Time
• func Optional[T any](ctx context.Context) (T, bool)
• func Provide[T any](s *Services, v T)
• func Reconfigure(ctx context.Context, s *Services) error
• func Run(app App)
• func Serve(ctx context.Context, app App) error
• func Service[T any](ctx context.Context) T
• func Sub(fsys fs.FS, dir string) fs.FS
• func WithServices(ctx context.Context, s *Services) context.Context
• type App
• type Booted
  • func Boot(ctx context.Context, app App) (*Booted, error)
  • func (b *Booted) Close(ctx context.Context) error
• type Clock
• type Head
• type HeadMeta
• type LocaleNegotiator
• type Middlewarer
• type Pack
• type RealClock
  • func (RealClock) Now() time.Time
• type Reconfigurable
• type Services
  • func NewServices() *Services
  • func ServicesFrom(ctx context.Context) *Services
  • func (s *Services) Each(f func(any))
  • func (s *Services) Lookup(t reflect.Type) (any, bool)
• type TLSHost
• type TLSRefusal
• type TLSReporter
• type TLSSnapshot
• type Tool
  • func ToolFunc[In, Out any](name, description string, fn func(ctx context.Context, in In) (Out, error)) Tool

Constants

const (
	MetricsPath = "/metrics"
	HealthzPath = "/healthz"
	ReadyzPath  = "/readyz"
	// TLSAllowPath answers a TLS terminator in front of the binary
	// (Caddy's on-demand TLS "ask") whether a hostname may get a
	// certificate: GET /tls-allow?domain=<host> is 200 for a name in
	// LIDZA_TLS_DOMAINS or one App.TLSHosts approves, 404 otherwise. It
	// is served when the app has either, and like /metrics it is for
	// the operator: keep it off the public side of the proxy.
	TLSAllowPath = "/tls-allow"
)

Paths every app serves besides /api and the frontend.

const (
	// EnvLog selects the format: "json" or "text". Default: text under
	// lidza dev and lidza test, json otherwise.
	EnvLog = "LIDZA_LOG"
	// EnvLogLevel is debug, info, warn or error; default info.
	EnvLogLevel = "LIDZA_LOG_LEVEL"
)

Logging environment.

const (
	// EnvTLSDomains lists the domains to serve, comma-separated; the first
	// is the app's public name (APP_URL when unset).
	EnvTLSDomains = "LIDZA_TLS_DOMAINS"
	// EnvTLSEmail is the ACME account contact (expiry warnings).
	EnvTLSEmail = "LIDZA_TLS_EMAIL"
	// EnvTLSAddr and EnvTLSHTTPAddr are the HTTPS and HTTP listen
	// addresses, :443 and :80 by default.
	EnvTLSAddr     = "LIDZA_TLS_ADDR"
	EnvTLSHTTPAddr = "LIDZA_TLS_HTTP_ADDR"
	// EnvTLSCacheDir stores certificates on disk instead of Postgres:
	// one node only.
	EnvTLSCacheDir = "LIDZA_TLS_CACHE_DIR"
	// EnvTLSDirectory is the ACME directory URL; Let's Encrypt by
	// default, its staging directory for rehearsals.
	EnvTLSDirectory = "LIDZA_TLS_DIRECTORY"
)

TLS from the environment: with LIDZA_TLS_DOMAINS set the binary serves HTTPS itself, with certificates from Let's Encrypt (ACME) obtained and renewed by golang.org/x/crypto/acme/autocert, and answers plain HTTP only to redirect to HTTPS and to prove domain ownership. No proxy is needed in front. The certificates live in Postgres through the db pack, so every node of the app shares them, as the stateless rule requires; a single node without the db pack names a directory in LIDZA_TLS_CACHE_DIR instead.

const (
	// EnvMCP set to "stdio" makes the binary serve its tools over stdio
	// instead of HTTP; `lidza mcp` uses it.
	EnvMCP = "LIDZA_MCP"
	// EnvMCPToken enables /mcp on the running binary for clients that
	// send it as a bearer token.
	EnvMCPToken = "LIDZA_MCP_TOKEN" //nolint:gosec // G101: a setting's name, not its value
	// MCPPath is the Streamable HTTP endpoint.
	MCPPath = "/mcp"
)

Environment for app tools.

const DefaultStreamTimeout = 10 * time.Minute

DefaultStreamTimeout is the deadline for streamed operations and WebSockets.

const DefaultTimeout = 30 * time.Second

DefaultTimeout is the per-request deadline for API handlers.

const SecurityTxtPath = "/.well-known/security.txt"

SecurityTxtPath is where the app says how to report a vulnerability (RFC 9116), served when SECURITY_CONTACT is set.

Functions

func DirFS

func DirFS(dir string) (fs.FS, error)

DirFS serves a directory on disk as an fs.FS that cannot leave it: a symlink inside pointing elsewhere, or any path that would escape, is refused (os.Root). For App.Dist from disk instead of the embedded build; os.DirFS follows symlinks out of the directory.

func HTTPClient

func HTTPClient(ctx context.Context) *http.Client

HTTPClient returns the client for outbound HTTP calls: the services' http.RoundTripper (a recorder or replayer under test) behind a 30-second timeout, or a plain client. Handlers use it for every external call so tests run offline against recorded fixtures.

func Handler

func Handler(app App) (http.Handler, error)

Handler builds the app's http.Handler: the API router under /api with the standard pipeline and, for every other path, the proxy to the frontend dev server (dev mode), the embedded build, or the app's own Frontend. Packs are not started; Serve does that.

func Log

func Log(ctx context.Context) *slog.Logger

Log returns the app logger for a request, with the request id attached so every line of one request can be found together. Outside a request it is the app logger.

func NewLogger

func NewLogger() *slog.Logger

NewLogger builds the app logger from the environment.

func Now

func Now(ctx context.Context) time.Time

Now returns the current time from the clock in ctx (the services' Clock, or the real one). Handlers use it instead of time.Now so a test can freeze or advance time.

func Optional

func Optional[T any](ctx context.Context) (T, bool)

Optional returns the T provided at start and whether there is one: for code that adapts to which packs are enabled (the admin pages).

func Provide

func Provide[T any](s *Services, v T)

Provide registers v under its static type T. Providing the same type twice replaces the first value.

func Reconfigure

func Reconfigure(ctx context.Context, s *Services) error

Reconfigure asks every service that can to read its configuration again. Every error is returned, joined.

func Run

func Run(app App)

Run serves the app until SIGINT or SIGTERM and exits the process with a non-zero status on error. Configuration comes from the environment:

LIDZA_ADDR          listen address, default 127.0.0.1:3000
LIDZA_MODE          "dev" to proxy the frontend instead of serving Dist
LIDZA_FRONTEND_URL  the frontend dev server (dev mode; set by `lidza dev`)
LIDZA_TRUSTED_PROXIES  proxies whose X-Forwarded-For counts (IPs,
                    CIDRs, loopback, private); ClientIP resolves
                    through them
LIDZA_TLS_DOMAINS   serve HTTPS on :443 for these domains with Let's
                    Encrypt certificates (stored in Postgres through the
                    db pack), redirect :80; APP_URL and AUTH_COOKIE_SECURE
                    follow unless set (see tls.go)

func Serve

func Serve(ctx context.Context, app App) error

Serve is Run without the process exit: it blocks until ctx is cancelled or a termination signal arrives, then shuts the server down.

func Service

func Service[T any](ctx context.Context) T

Service returns the T provided at start. A missing service is a wiring mistake, not a runtime condition, so it panics with the type name.

func Sub

func Sub(fsys fs.FS, dir string) fs.FS

Sub returns the subdirectory dir of fsys, for `//go:embed all:dist` followed by lidza.Sub(dist, "dist"). It panics if dir does not exist, which for an embedded FS is a build mistake, not a runtime condition.

func WithServices

func WithServices(ctx context.Context, s *Services) context.Context

WithServices attaches s to ctx; the app handler does this for every request, tests do it by hand.

Types

type App

type App struct {
	// Name is shown in logs.
	Name string
	// Dist is the built frontend, served in production. Nil for templates
	// without a static build.
	Dist fs.FS
	// Frontend serves every non-API path when there is no Dist (the htmx
	// template renders pages in Go). Ignored while the dev proxy is active.
	Frontend http.Handler
	// Routes registers the app's API handlers. May be nil.
	Routes func(r *router.Router)
	// Middleware wraps the whole app, API and frontend alike, outermost
	// first. The API router already runs request ids, logging, panic
	// recovery and the timeout; add CORS or auth here or with router.Use.
	Middleware []middleware.Middleware
	// Timeout is the deadline every API request's context gets; default
	// DefaultTimeout.
	Timeout time.Duration
	// StreamTimeout is the deadline of a streamed operation or WebSocket
	// (router.Stream, asked for with Accept: text/event-stream, as the
	// generated clients do); default DefaultStreamTimeout. A model's
	// answer streams for longer than a JSON reply takes.
	StreamTimeout time.Duration
	// CSP is the Content-Security-Policy sent with every response. Empty
	// sends middleware.DefaultCSP, except in dev mode (LIDZA_MODE=dev),
	// where Vite's dev server needs inline scripts and none is sent;
	// middleware.AddCSP extends it for another origin (a script CDN, an
	// image host). middleware.NoCSP sends none anywhere. A value set here
	// is sent in dev mode too.
	CSP string
	// PermissionsPolicy is the Permissions-Policy sent with every
	// response. Empty sends middleware.DefaultPermissionsPolicy (camera,
	// microphone and location off); an app that asks for the visitor's
	// location sets middleware.AllowGeolocation.
	PermissionsPolicy string
	// HSTS is the Strict-Transport-Security value. Empty sends
	// middleware.DefaultHSTS outside dev mode when APP_URL is https://
	// (as LIDZA_TLS_DOMAINS sets it), and none otherwise;
	// middleware.HSTSSubdomains covers the subdomains too, and
	// middleware.NoHSTS sends none.
	HSTS string
	// Head sets the <head> of each page served from Dist (the shell and
	// the prerendered pages, the SSR sidecar's and, under lidza dev, the
	// dev server's): title, description, canonical address, social tags
	// and JSON-LD, per request. A route with a parameter is one shell for
	// every address until Head names it. Return false to leave a page as
	// built. See Head.
	Head func(r *http.Request) (Head, bool)
	// Logger receives request and error logs. Default: NewLogger from
	// LIDZA_LOG and LIDZA_LOG_LEVEL, also installed as slog's default so
	// packs log the same way. Handlers use lidza.Log(ctx).
	Logger *slog.Logger
	// Packs are started in order before OnStart and stopped in reverse
	// after OnShutdown. packs.go, generated from lidza.json, lists them.
	Packs []Pack
	// Tools are the app's MCP tools (see Tool); tools.go lists them.
	Tools []Tool

	// OnStart runs after the packs and before the listener opens: connect
	// what the packs do not, warm caches, Provide services. An error
	// aborts the start.
	OnStart func(ctx context.Context, s *Services) error
	// OnReady runs once the app is listening.
	OnReady func()
	// OnShutdown runs after in-flight requests finished, before exit:
	// close pools, flush queues.
	OnShutdown func(ctx context.Context) error

	// TLSHosts approves a hostname beyond LIDZA_TLS_DOMAINS for a
	// certificate (a customer's own domain the app serves): nil approves
	// it, an error refuses it; a nil TLSHosts approves none. It is asked
	// during TLS handshakes, ACME challenges and before every certificate
	// order, renewals included, with the services in ctx (db.From works);
	// the verdict is cached per node, an approval 5 minutes and a refusal
	// 1 minute, so a host the app stops approving is refused within 5
	// minutes and never renewed. Certificates live in the same shared
	// cache as the listed domains'. Requests on an approved host reach the
	// whole app, as on a listed domain: a path outside /api is served
	// with r.Mount, and a middleware that checks r.Host keeps the rest
	// (the frontend, /api) to the app's own domains. Behind a terminator
	// that issues certificates itself, TLSAllowPath asks it the same way.
	TLSHosts func(ctx context.Context, host string) error

	// PrivateTLS serves the normal LIDZA_ADDR listener using explicit TLS1.3
	// and required verified client certificates (for a trusted gateway). Build
	// it with gateway.ServerTLS. It is mutually exclusive with ACME TLS and
	// opens no plaintext fallback. Gateway evidence still needs route middleware;
	// a backend TLS handshake alone does not prove original-client transport.
	PrivateTLS *tls.Config
	// PrivateTLSAddr optionally opens PrivateTLS on a second listener instead of
	// LIDZA_ADDR, retaining the ordinary listener for internal HTTP services.
	// Sensitive routes must enforce gateway.Verify on both listeners; the
	// ordinary listener never acquires verified gateway evidence implicitly.
	PrivateTLSAddr string

	// ReadyTimeout bounds the checks behind /readyz; default 3s.
	ReadyTimeout time.Duration
}

App describes one application.

type Booted

type Booted struct {
	Handler  http.Handler
	Services *Services
	// contains filtered or unexported fields
}

Booted is an app with its packs started and its handler built, not yet listening: what Serve runs and what tests drive through lidzatest.

func Boot

func Boot(ctx context.Context, app App) (*Booted, error)

Boot starts the packs in order, runs OnStart and builds the handler. Close stops everything in reverse.

func (*Booted) Close

func (b *Booted) Close(ctx context.Context) error

Close runs OnShutdown, then stops the packs in reverse order. Every error is logged; the first is returned.

type Clock

type Clock interface {
	Now() time.Time
}

Clock is where the app reads the time, so tests can set it. The real clock is the default; lidzatest provides a controllable one.

type Head

type Head = devserver.Head

Head is a page's head as the App.Head hook sets it: Title, Description, Canonical, Image, Type, SiteName, NoIndex, Meta, JSONLD and Status (devserver.Head documents each).

Head: func(r *http.Request) (lidza.Head, bool) {
	id, ok := strings.CutPrefix(r.URL.Path, "/products/")
	if !ok {
		return lidza.Head{}, false
	}
	p, err := queries.New(db.From(r.Context())).GetProduct(r.Context(), id)
	if err != nil {
		return lidza.Head{Title: "Not found", NoIndex: true, Status: http.StatusNotFound}, true
	}
	return lidza.Head{Title: p.Name, Description: p.Summary, Canonical: "https://example.com/products/" + id}, true
},

type HeadMeta

type HeadMeta = devserver.Meta

HeadMeta is one further <meta> tag of a Head.

type LocaleNegotiator

type LocaleNegotiator interface {
	NegotiateLocale(r *http.Request) string
}

LocaleNegotiator is implemented by packs that pick a request's locale, such as i18n: the embedded build serves the page prerendered in that locale (dist/.locales). It returns "" before the pack has started.

type Middlewarer

type Middlewarer interface {
	Middleware() middleware.Middleware
}

Middlewarer is implemented by packs that wrap every API request, such as i18n's locale negotiation. The middleware resolves the running pack from the request context, so it may be built before Start.

type Pack

type Pack interface {
	Name() string
	Start(ctx context.Context, s *Services) error
	Stop(ctx context.Context) error
}

Pack is a unit the app starts and stops: an official or local pack. Start registers whatever it offers (a pool, a client) with Provide.

type RealClock

type RealClock struct{}

RealClock is time.Now.

func (RealClock) Now

func (RealClock) Now() time.Time

Now implements Clock.

type Reconfigurable

type Reconfigurable interface {
	Reconfigure(ctx context.Context) error
}

Reconfigurable is a pack that can read its configuration again while the app runs: after a credential is saved from the admin pages, the mail, llm and storage packs pick up the new provider or key without a restart.

type Services

type Services struct {
	// contains filtered or unexported fields
}

Services holds what packs and OnStart provide, keyed by static type, and hands it to handlers through the request context. It is filled at start and read-only afterwards.

func NewServices

func NewServices() *Services

NewServices returns an empty registry.

func ServicesFrom

func ServicesFrom(ctx context.Context) *Services

ServicesFrom returns the services in ctx, nil outside the app.

func (*Services) Each

func (s *Services) Each(f func(any))

Each calls f with every provided value, in no particular order.

func (*Services) Lookup

func (s *Services) Lookup(t reflect.Type) (any, bool)

Lookup returns the value registered for t.

type TLSHost

type TLSHost struct {
	Host     string
	Approved time.Time
	Expires  time.Time
}

TLSHost is a hostname with the certificate expiry last seen (zero before the first handshake) and, for a host the hook approved, when.

type TLSRefusal

type TLSRefusal struct {
	Host, Reason string
	At           time.Time
}

TLSRefusal is a hostname refused a certificate, and why.

type TLSReporter

type TLSReporter interface {
	Snapshot() TLSSnapshot
}

TLSReporter is what this node's TLS server knows about its hostnames, for the admin pages: the listed domains, the hosts App.TLSHosts approved, each with the expiry of the certificate last served, and the latest refusals. It is provided as a service while the binary serves TLS itself.

type TLSSnapshot

type TLSSnapshot struct {
	Domains  []TLSHost
	Approved []TLSHost
	Refused  []TLSRefusal
}

TLSSnapshot is a copy of the status.

type Tool

type Tool struct {
	Name        string
	Description string
	// Input is a value of the input type; its JSON Schema is derived from
	// the Go type. nil means no input.
	Input any
	// Handler receives the raw JSON input and returns a JSON-encodable
	// result or an error the caller sees.
	Handler func(ctx context.Context, input json.RawMessage) (any, error)
	// ReadOnly says the tool changes nothing (a lookup, a report): an
	// agent's client may run it without asking.
	ReadOnly bool
	// Destructive says the tool can lose data (a delete, an overwrite).
	// A tool marked neither counts as one that may.
	Destructive bool
}

Tool is an MCP tool the app defines: a name, a description, a JSON input and a handler that runs with the app's services (packs, clock, logger) in its context. `lidza mcp` exposes app tools next to the framework's; with LIDZA_MCP_TOKEN set, the running binary serves them at /mcp (Streamable HTTP) to agents that present the token.

func ToolFunc

func ToolFunc[In, Out any](name, description string, fn func(ctx context.Context, in In) (Out, error)) Tool

ToolFunc builds a Tool from a typed function. In is decoded from the input and validated when it implements validate.Validator.