httpapi

Documentation

Overview

Package httpapi is the transport-neutral HTTP surface for quicSQL. Phase 1 serves the thin native-JSON endpoint (POST /<db>/query) over an ordinary http.Handler, so it runs identically on every transport a later phase adds (HTTP/1.1, h2/h2c, HTTP/3, WebSocket, UDS). Routing resolves the target database from the URL path (default) or the Host subdomain, with server-scoped reserved paths (`/_health`, and `/_*` reserved) resolved first.

Index

• type Handler
  • func New(reg *registry.Registry, eng *engine.Engine, route config.Routing, ...) *Handler
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Option
  • func WithAdmin(a http.Handler) Option
  • func WithLimiter(l *limits.Limiter) Option
  • func WithLogger(l *slog.Logger) Option
  • func WithMaxBlob(n int64) Option
  • func WithMaxBody(n int64) Option
  • func WithMaxExport(n int64) Option
  • func WithMetrics(m obs.Metrics) Option
  • func WithPolicy(p *authz.Policy) Option
  • func WithSessions(s *session.Store) Option
  • func WithStatementTimeout(d time.Duration) Option

Types

type Handler

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

Handler is the quicSQL HTTP handler. The auth middleware (package auth) has already attached the request's principal to the context by the time a request reaches here; the handler enforces the per-database capability via policy.

func New

func New(reg *registry.Registry, eng *engine.Engine, route config.Routing, opts ...Option) *Handler

New builds the handler. When neither path nor host routing is configured, path routing is enabled by default.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Option

type Option func(*Handler)

Option customizes a Handler.

func WithAdmin

func WithAdmin(a http.Handler) Option

WithAdmin mounts the control-plane handler at /_admin. Nil (the default) leaves the control plane disabled — /_admin then 404s like any reserved path.

func WithLimiter

func WithLimiter(l *limits.Limiter) Option

WithLimiter sets the admission-control limiter (per-principal rate + per-db concurrency). Nil admits every request.

func WithLogger

func WithLogger(l *slog.Logger) Option

WithLogger sets the handler's logger (server-side error logging).

func WithMaxBlob

func WithMaxBlob(n int64) Option

WithMaxBlob caps a single streamed large object (blob write). Non-positive keeps the default. Unlike WithMaxBody this bounds a streamed body, not a buffered one, so it can be large without a matching memory cost.

func WithMaxBody

func WithMaxBody(n int64) Option

WithMaxBody caps the request body size (bytes). Non-positive keeps the default.

func WithMaxExport

func WithMaxExport(n int64) Option

WithMaxExport caps a full-database /export image (bytes), which is materialized whole in RAM. Non-positive disables the cap (unbounded).

func WithMetrics

func WithMetrics(m obs.Metrics) Option

WithMetrics sets the metrics sink; when it also implements obs.Exposer, the /_metrics endpoint renders it.

func WithPolicy

func WithPolicy(p *authz.Policy) Option

WithPolicy sets the authorization policy. Without it the handler defaults to open mode (every principal is read-write on every database), preserving the pre-auth behavior for tests and no-auth deployments.

func WithSessions

func WithSessions(s *session.Store) Option

WithSessions enables the Hrana pipeline endpoints, backed by the given store.

func WithStatementTimeout

func WithStatementTimeout(d time.Duration) Option

WithStatementTimeout bounds each request's execution via the request context.