engine

Documentation

Overview

Package engine: snapshot/restore of simulator state (collections, kv, blobs).

A snapshot is a gzip-compressed tar of a LOGICAL dump produced through the engine's existing accessor API (StateStores) — not a copy of the on-disk SQLite/blob files. The request log is observational and is NOT snapshotted.

Archive layout (Plan 3b):

snapshot.json                 # {version, created_at, manifest, services}
<service>/collections.json    # { "<collection>": [ {doc}, ... ] }
<service>/kv.json             # { "<namespace>": [ ["k","v"], ... ] }
<service>/blobs/<ns>/<id>.blob   # raw content
<service>/blobs/<ns>/<id>.meta   # {name,size,content_type,modified}

Index

• func Restore(e *Engine, r io.Reader) (*snapshotHeader, error)
• func Snapshot(e *Engine, manifestPath string, w io.Writer) error
• type Engine
  • func New(m *manifest.Manifest, opts ...Option) (*Engine, error)
  • func (e *Engine) AdapterFor(name string) *adapter.Adapter
  • func (e *Engine) Close() error
  • func (e *Engine) GrpcTarget(name string) string
  • func (e *Engine) HTTPServerForTest() *http.Server
  • func (e *Engine) HandlerForTest() http.Handler
  • func (e *Engine) HandlerForTestByName(name string) http.Handler
  • func (e *Engine) HasLoadError() bool
  • func (e *Engine) RequestLog() *requestlog.Store
  • func (e *Engine) ResetAll() error
  • func (e *Engine) ResetService(name string) error
  • func (e *Engine) Seq() *atomic.Int64
  • func (e *Engine) Serve(ctx context.Context) error
  • func (e *Engine) ServeForTest(ctx context.Context) (map[string]string, func(), error)
  • func (e *Engine) ServeSingle(ctx context.Context, listenAddr, tld string) (string, func(), error)
  • func (e *Engine) ServiceLoadError(name string) string
  • func (e *Engine) ServiceNames() []string
  • func (e *Engine) Start(ctx context.Context) (map[string]string, func(), error)
  • func (e *Engine) StateStores(name string) (col *primitives.Store, k *kv.KV, b *blob.Store, ok bool)
• type Option
  • func WithClock(c *clock.Clock) Option

Functions

func Restore

func Restore(e *Engine, r io.Reader) (*snapshotHeader, error)

Restore reads a gzip-tar snapshot from r, wipes the engine's current state (ResetAll), then re-populates collections, kv, and blobs from the archive. The request log is cleared by ResetAll and not restored.

func Snapshot

func Snapshot(e *Engine, manifestPath string, w io.Writer) error

Snapshot writes a gzip-tar snapshot of every service's simulator state (collections, kv, blobs) to w. It does NOT capture the request log. The engine's stores are read in place; nothing is mutated.

Types

type Engine

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

Engine turns a manifest into runnable HTTP servers, one per service. Services backed by an adapter are loaded eagerly: the adapter directory is parsed, per-service state stores (SQLite) are opened, and Starlark VMs are cached for handler dispatch.

func New

func New(m *manifest.Manifest, opts ...Option) (*Engine, error)

func (*Engine) AdapterFor

func (e *Engine) AdapterFor(name string) *adapter.Adapter

AdapterFor returns the loaded adapter for the named service, or nil if the service has no adapter (rules-only) or is not loaded. Useful for introspection (e.g. printing gRPC method counts in `stunt up`).

func (*Engine) Close

func (e *Engine) Close() error

Close stops any gRPC servers started by serve(), then releases all per-service stores and emitters. gRPC servers are stopped FIRST so that in-flight RPCs finish against still-open stores rather than hitting a closed SQLite handle. Safe to call on a rules-only engine.

func (*Engine) GrpcTarget

func (e *Engine) GrpcTarget(name string) string

GrpcTarget returns the gRPC dial target ("host:port") for the named service, or "" if the service has no gRPC server. Must be called after ServeForTest (or Serve) has started servers.

func (*Engine) HTTPServerForTest

func (e *Engine) HTTPServerForTest() *http.Server

HTTPServerForTest returns an http.Server whose handler is the first service, with no listener attached (tests bind their own listener and call Serve).

func (*Engine) HandlerForTest

func (e *Engine) HandlerForTest() http.Handler

HandlerForTest builds the serving handler for the first service. Tests bind it to a listener of their choosing.

func (*Engine) HandlerForTestByName

func (e *Engine) HandlerForTestByName(name string) http.Handler

HandlerForTestByName builds the serving handler for a named service (or the first service if name is empty). Tests bind it to a listener of their choice.

func (*Engine) HasLoadError

func (e *Engine) HasLoadError() bool

HasLoadError returns true if any service had a load error during engine construction.

func (*Engine) RequestLog

func (e *Engine) RequestLog() *requestlog.Store

RequestLog returns the shared request/response capture store, or nil if the engine was not able to open one (e.g. construction failed). Callers query it via requestlog.Query / (*Store).List.

func (*Engine) ResetAll

func (e *Engine) ResetAll() error

ResetAll wipes every service's state plus the shared request log. Used by the dashboard/CLI reset for a clean slate.

func (*Engine) ResetService

func (e *Engine) ResetService(name string) error

ResetService wipes one service's state (collections + kv + blobs) in place. Used by the dashboard/CLI reset for deterministic runs.

func (*Engine) Seq

func (e *Engine) Seq() *atomic.Int64

Seq returns the engine-wide monotonic sequence counter shared by all request recorders. Exposed so the dashboard can pull the next seq for replay entries (which bypass the recorder). See (*Dashboard).SetSeq.

func (*Engine) Serve

func (e *Engine) Serve(ctx context.Context) error

Serve starts one server per service at sequential ports from base_port, blocking until ctx is canceled.

func (*Engine) ServeForTest

func (e *Engine) ServeForTest(ctx context.Context) (map[string]string, func(), error)

ServeForTest starts one server per service on free ports (ignores base_port) and returns a map of service name -> http://host:port.

func (*Engine) ServeSingle

func (e *Engine) ServeSingle(ctx context.Context, listenAddr, tld string) (string, func(), error)

ServeSingle starts a single HTTP server (one listener) that dispatches all services by Host header, returning the bound address. Used in subdomain mode where the TLS proxy fronts the engine. listenAddr may be "127.0.0.1:0" for an OS-assigned port.

func (*Engine) ServiceLoadError

func (e *Engine) ServiceLoadError(name string) string

ServiceLoadError returns a non-empty error message if the named service's adapter failed to load (partial startup). Returns "" if the service loaded successfully or is rules-only.

func (*Engine) ServiceNames

func (e *Engine) ServiceNames() []string

ServiceNames returns the manifest's service names, sorted (for the dashboard's data-browser service picker).

func (*Engine) Start

func (e *Engine) Start(ctx context.Context) (map[string]string, func(), error)

Start launches one HTTP server per service at sequential ports from base_port (and one gRPC server per gRPC-backed adapter on free ports), returning immediately with a map of service name -> http://host:port and a shutdown function. The caller must call the shutdown function (or cancel ctx) to stop the servers. Use Start (non-blocking) when you need the actual addresses before serving completes (e.g. printing a banner in `stunt up`); use Serve (blocking) when you just want to serve until ctx is canceled.

func (*Engine) StateStores

func (e *Engine) StateStores(name string) (col *primitives.Store, k *kv.KV, b *blob.Store, ok bool)

StateStores returns the per-service storage handles (document collections, kv, blobs) for a service, or ok=false if the service has no adapter/state. Used by the dashboard's read-only data browser.

type Option

type Option func(*Engine)

New creates an Engine from a manifest. Git adapter sources are resolved (cloned/fetched if missing) against the adapter cache directory. The cache root defaults to ~/.stunt/adapters and can be overridden with the STUNT_ADAPTER_CACHE environment variable. Option configures an Engine at construction.

func WithClock

func WithClock(c *clock.Clock) Option

WithClock overrides the engine's clock (default real-time). Used by tests to drive time-based adapter behavior deterministically.