sysops

Documentation

Overview

Package sysops loads trusted, chassis-local opstacks into the in-memory ops snapshot at startup.

"System" opstacks live under `_`-prefixed tenant slugs (`_sys`, `_playground`, …). They are NOT authored through the admin API — they ship embedded in the binary (the open-core default) and may be overridden/extended from a local directory the operator controls. Filesystem control == operator trust, so these bypass the tenant-level admin auth path entirely; they are the *second* writer of the `ops` table (admin activation is the first), scoped to their own `_`-prefixed tenants which the admin API can never create (tenants.ReservedSlug).

`_sys` owns the ingress-fallback `boot` stack. Shape mirrors continuation.Open: Load() resolves+validates, Apply(db) overlays. Apply is idempotent and re-run after every dbcache reload (the snapshot is rebuilt from runtime.db and would otherwise drop the overlay).

Index

• func Scaffold(destRoot string, force bool) (wrote bool, err error)
• func Watch(ctx context.Context, cfg Config, logger *zap.Logger, ...)
• type Config
• type Loader
  • func Load(cfg Config) (*Loader, error)
  • func (l *Loader) Apply(db *sql.DB) error
  • func (l *Loader) BootOpCount() int

Functions

func Scaffold

func Scaffold(destRoot string, force bool) (wrote bool, err error)

Scaffold materializes the embedded system bundle into a workspace so the `_sys/boot` router is visible and editable instead of an invisible binary default. destRoot is the workspace root; files land alongside application stacks in the same tree:

<destRoot>/OPS/_sys/boot/0/detect.txcl
<destRoot>/OPS/_sys/boot/20/route.txcl

Because Load merges the on-disk bundle per (stack, scope, name) onto the embed, an unedited scaffold is behaviour-neutral; the operator can then edit boot/0, add a boot/10, etc.

No-clobber is per file: an existing file is never overwritten unless force is set, so operator edits survive and only genuinely-new embedded files appear. The embed root is `opstacks/`; that prefix is stripped so the embedded `opstacks/OPS/...` lands at `<destRoot>/OPS/...`. Returns whether anything was written.

Only `txco dev` calls this — `txco serve` stays static and uses the embed (or an explicitly configured --system-opstacks-dir) directly.

func Watch

func Watch(ctx context.Context, cfg Config, logger *zap.Logger, reapply func(*Loader) error)

Watch hot-recompiles the system bundle when files under cfg.Dir change. It is wired ONLY on the `txco dev` path (gated by --system-opstacks-watch); `txco serve` compiles once at startup and stays static. On each debounced change it re-Loads (re-validating txcl) and, on success, hands the fresh *Loader to reapply — which the caller overlays onto the live snapshot. A failed Load (bad edit) is logged and the previous bundle stays live, mirroring the non-fatal dbcache OnReload contract.

Same watcher/debounce stack the dbcache uses, for consistency.

Types

type Config

type Config struct {
	Dir string
}

Config selects the optional on-disk source. Dir is a workspace root that contains an `OPS/` tree; the loader reads only its `_`-prefixed system stacks (OPS/_sys/...). Dir == "" means embedded-only (the open-core default — `txco serve` in production). Mirrors continuation.StoreConfig in spirit.

type Loader

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

Loader is a resolved, validated system bundle ready to overlay onto an ops snapshot. ops carry the full "_slug/stack" name (e.g. "_sys/boot"); Apply splits that into (tenant, stack). Construct via Load; apply via Apply.

func Load

func Load(cfg Config) (*Loader, error)

Load resolves the embedded default, overlays the optional on-disk bundle (merged per stack/scope/name — extend or override individual rules), validates every rule's txcl, and returns a Loader. A parse error anywhere is fatal — a broken system bundle must fail the chassis at startup, not silently misroute.

func (*Loader) Apply

func (l *Loader) Apply(db *sql.DB) error

Apply overlays the system bundle onto db (the in-memory ops snapshot). Idempotent: for each system tenant it upserts the tenants row, deletes all of that tenant's ops, then re-inserts. Safe to call after every dbcache reload.

func (*Loader) BootOpCount

func (l *Loader) BootOpCount() int

BootOpCount reports how many `_sys` `boot` ops resolved. Zero means the ingress-fallback pipeline is missing — the caller logs loudly and the chassis falls back to the synthetic 404 safety net.