Documentation
¶
Overview ¶
Package api is the machine-tier REST API: a stable seam between the core library and its consumers. It is mounted by `gofast-cli serve` via NewRouter, and can be mounted by a downstream product via RegisterMachineRoutes onto its own gin engine.
Index ¶
Constants ¶
const ContractVersion = "1.0.0"
ContractVersion is the machine-API REST contract version: what /health and the served OpenAPI advertise. NOT the software release (that is the git tag). Held constant so contract goldens stay stable.
Variables ¶
ErrStoreUnavailable is returned by a StoreProvider when no store is open (e.g. the DB is being rebuilt by a parse). Handlers map it to 503 db_unavailable.
Functions ¶
func NewRouter ¶
func NewRouter(provider StoreProvider, opts Options) *gin.Engine
NewRouter is the standalone entry point: a fresh *gin.Engine with Recovery() plus RegisterMachineRoutes. Used by `gofast-cli serve`. No dashboard routes.
func RegisterMachineRoutes ¶
func RegisterMachineRoutes(r gin.IRouter, provider StoreProvider, opts Options)
RegisterMachineRoutes mounts the machine tier onto any gin router (a full engine or a group): /health, /api/v1/health, /api/v1/openapi.json, /api/v1/sql/{queries,databases,execute}. It attaches the machine middleware (request-id, gzip, CORS) to its own route groups so the same behavior holds wherever it is mounted. Bearer auth on /sql/* unless opts.DisableAuth; /sql/execute registered unless opts.DisableSQLExecute. /api/v1/openapi.json is always unauthenticated, alongside /health.
Exported so downstream consumers can mount the machine tier onto their own engine.
Types ¶
type Options ¶
type Options struct {
Token string // bearer token; required unless DisableAuth
DisableAuth bool // DEV ONLY: mount /sql/* with no bearer middleware
DisableSQLExecute bool // zero-value false => /sql/execute ENABLED (default)
}
Options configures the machine-tier router.
type StoreProvider ¶
type StoreProvider interface {
// WithStore runs fn while holding the read lease. fn MUST NOT retain the
// *storage.Storage past its return. Returns ErrStoreUnavailable if no store
// is open.
WithStore(fn func(*storage.Storage) error) error
}
StoreProvider yields the current read-only store under a read LEASE held for the whole callback, so a concurrent parse (which closes/swaps the store) can't invalidate the handle mid-query. The machine `serve` path wraps a fixed RO store; a downstream RW-swapping store implements the lease over its swap mutex.
Source Files