Documentation
¶
Overview ¶
Package admin runs the second HTTP server fronting the rule-mutation API. It's a sibling to the user-facing web/tcp/cron personalities: separate port, separate auth, but shares the same processor + db.
Wire from chassis/server/server.go when "admin" is in --personalities.
Index ¶
- Variables
- type Controller
- func (c *Controller) ApplyStackVersion(ctx context.Context, tx *sql.Tx, tenantID, stack string, version int64, ...) error
- func (c *Controller) BackfillStructuredHostDKIM(ctx context.Context) (int, error)
- func (c *Controller) EnableRoomRelay(name string) error
- func (c *Controller) EnsureStructuredSuffixZone(ctx context.Context) error
- func (c *Controller) PublishSecretRevoke(ctx context.Context, tenantID string, parentRow map[string]any) (func(*sql.Tx) error, error)
- func (c *Controller) PublishSecretUpsert(ctx context.Context, tenantID string, versionRow, parentRow map[string]any) (func(*sql.Tx) error, error)
- func (c *Controller) ReconcileStorePacks(ctx context.Context, tenantID, stack string, version, priorVersion int64, ...)
- func (c *Controller) SetArtifactStore(s artifact.Store)
- func (c *Controller) SetBlobIndex(ix blob.Index)
- func (c *Controller) SetDatasetCache(dc *dataset.Cache)
- func (c *Controller) SetFileCAS(s filecas.Store)
- func (c *Controller) SetGate(ctx context.Context, slug string, suspended bool, denyStatus int, ...) error
- func (c *Controller) SetNotebookStore(st *chnotebook.Store)
- func (c *Controller) SetSourceStore(s *chsource.Store)
- func (c *Controller) SetStoreReconciler(r *storeseed.Reconciler)
- func (c *Controller) SetVectorStore(v vector.Store)
- func (c *Controller) Start()
- func (c *Controller) Stop()
- func (c *Controller) WarmDatasets(ctx context.Context, tenantID, stackName string, versionNumber int64)
- type OpRecord
Constants ¶
This section is empty.
Variables ¶
var Features = []string{"web-abi-markers"}
Features names what this chassis can do that an older one can't, for a client to check before relying on it. The JSON /healthz lists them.
web-abi-markers the static index reads FILES/_txco/ markers (public "_"
roots, immutable prefixes). `txco apply` refuses to send
a Web ABI build to a chassis without it: an older one
would store the markers as private files, and every "_"
asset would 404.
Functions ¶
This section is empty.
Types ¶
type Controller ¶
type Controller struct {
// contains filtered or unexported fields
}
func NewController ¶
func NewController(ctx context.Context, pu *processor.Unit) *Controller
func (*Controller) ApplyStackVersion ¶
func (c *Controller) ApplyStackVersion(ctx context.Context, tx *sql.Tx, tenantID, stack string, version int64, now string) error
ApplyStackVersion is the non-HTTP entry point to the activation core, used by the control-event applier (chassis/controlapply) to materialise a stack.activated event. It runs the same transactional logic the admin handler uses; the caller owns tx begin/commit and any dbcache reload. The HTTP-only status/code/detail is collapsed to a plain error.
func (*Controller) BackfillStructuredHostDKIM ¶ added in v0.2.6
func (c *Controller) BackfillStructuredHostDKIM(ctx context.Context) (int, error)
BackfillStructuredHostDKIM mints a per-host DKIM keypair for every active chassis-minted structured host that predates the per-host key columns (0017) — created_by = structured-host with an empty key. Idempotent: hosts that already have a key are skipped, so re-running (e.g. every boot) is a cheap no-op once the fleet is keyed. Each updated row is fleet-published so data- plane nodes sign with it and the dns head publishes its per-host records. Control-plane only. Returns the number of hosts newly keyed.
func (*Controller) EnableRoomRelay ¶ added in v0.2.10
func (c *Controller) EnableRoomRelay(name string) error
EnableRoomRelay opens the named cross-node room relay and attaches it to the hub so room messages fan out across fleet nodes (the relay's inbound feed is wired to hub.Deliver). Empty name is a no-op (rooms stay in-process). Called from boot when --room-relay is set; the relay is closed in Stop.
func (*Controller) EnsureStructuredSuffixZone ¶ added in v0.2.6
func (c *Controller) EnsureStructuredSuffixZone(ctx context.Context) error
EnsureStructuredSuffixZone idempotently creates the system-owned zone for the configured structured-host suffix (e.g. stacks.thanks.computer), making the chassis authoritative for it: synth emits a WILDCARD A/MX/SPF when a zone's origin == the suffix, and per-host DKIM/DMARC come from the structured-host rows. Reuses the zone create + fleet-publish + dbcache-reload path. Control-plane only (the caller gates on the 'admin' personality + --structured-dns-self). No-op when the zone already exists.
func (*Controller) PublishSecretRevoke ¶ added in v0.2.16
func (c *Controller) PublishSecretRevoke( ctx context.Context, tenantID string, parentRow map[string]any, ) (func(*sql.Tx) error, error)
PublishSecretRevoke implements secrets.Syncer for a revoke: one tenant_secrets upsert carrying revoked_at (the consumer's INSERT OR REPLACE flips it inactive), as a TypeSecretRevoked event.
func (*Controller) PublishSecretUpsert ¶ added in v0.2.16
func (c *Controller) PublishSecretUpsert( ctx context.Context, tenantID string, versionRow, parentRow map[string]any, ) (func(*sql.Tx) error, error)
PublishSecretUpsert implements secrets.Syncer for create / rotate / description changes. versionRow is nil for a parent-only change. The version event is queued BEFORE the parent so a consumer never briefly sees a tenant_secrets row pointing at an absent version.
func (*Controller) ReconcileStorePacks ¶ added in v0.2.16
func (c *Controller) ReconcileStorePacks(ctx context.Context, tenantID, stack string, version, priorVersion int64, origin, force bool)
ReconcileStorePacks loads the version's CHANGED VECTORS/ + KV/ + BLOBS/ packs and reconciles them into the runtime stores (force: every pack, and the tree wins over runtime drift — see storeseed.Scope.Force). It is invoked AFTER the activation tx commits, from both the control-plane admin handler (origin=true) and the data-plane applier (origin=false, in package controlapply — hence exported).
Store key = the tenant SLUG. The runtime keys every store by the slug (processor.TenantScope), but the control plane only has the tenant_id in hand; keying the reconcile by the id would seed under a different identifier than the runtime reads (collection-not-found at search time). storeTenantKey resolves it. stack_files queries below stay on tenant_id — that's the durable DB FK.
Change-driven, self-healing: a pack is reconciled when its content-hash differs from the prior active version (priorVersion) OR when its target is absent from the store. A code-only deploy (`txco apply`) carries packs forward unchanged and the targets already exist → empty set → no item reconcile (just a cheap presence probe per vector pack). priorVersion <= 0, or any diff failure, reconciles every pack (correct for a first activation / a fresh or wiped node).
Best-effort by contract: it logs and swallows every error so a slow or failing store never stalls or rolls back a deploy — the pack bytes are durable in the CAS, so a missed reconcile is retried on the next apply/reload.
func (*Controller) SetArtifactStore ¶
func (c *Controller) SetArtifactStore(s artifact.Store)
SetArtifactStore wires the artifact store the admin handlers use to publish event payloads when fleet-sync producer is enabled. The chassis boot calls this after opening the artifact store; handlers guard internally on FeedSink != nop before touching it.
This is also where the Controller registers itself as the secret store's fleet Syncer (so create/rotate/revoke fan out): it's the "this node is a producer" hook. The PublishSecret* methods self-gate on fleetEnabled(), so registering here is safe even on a single-node chassis (they no-op). nil Secrets (feature off) ⇒ nothing to wire.
func (*Controller) SetBlobIndex ¶ added in v0.2.24
func (c *Controller) SetBlobIndex(ix blob.Index)
SetBlobIndex wires the blob name index the stack-blobs endpoint reads. Nil-safe: unset ⇒ the endpoint answers 503.
func (*Controller) SetDatasetCache ¶ added in v0.2.19
func (c *Controller) SetDatasetCache(dc *dataset.Cache)
SetDatasetCache wires the node's dataset artifact cache (chassis/dataset). Set by chassis/server/server.go at boot. Nil-safe: when unset, activating a dataset-bearing version fails loudly rather than shipping queries that can never run.
func (*Controller) SetFileCAS ¶ added in v0.2.6
func (c *Controller) SetFileCAS(s filecas.Store)
SetFileCAS wires the content-addressed store activation uses to persist tenant FILES/ asset bytes. Nil-safe.
func (*Controller) SetGate ¶ added in v0.2.6
func (c *Controller) SetGate(ctx context.Context, slug string, suspended bool, denyStatus int, denyReason string) error
SetGate engages or releases the programmatic admission gate for a tenant, identified by slug — the identity background services see in usage data (the envelope `_txc.tenant`). It owns the `suspended` column exclusively (operator disable owns `enabled`) and routes through applyRuntimeRow so the full-row write + fleet emit + dbcache reload is reused, never a partial row. Unknown or revoked slugs are a no-op (the caller logs). This makes *Controller satisfy bgservice.Gate, which is injected into background services at boot.
func (*Controller) SetNotebookStore ¶ added in v0.2.28
func (c *Controller) SetNotebookStore(st *chnotebook.Store)
SetNotebookStore wires the notebook store the read-only endpoints use. Nil-safe: unset ⇒ the endpoints answer 503.
func (*Controller) SetSourceStore ¶ added in v0.2.28
func (c *Controller) SetSourceStore(s *chsource.Store)
SetSourceStore wires the read-only source-watcher status endpoint.
func (*Controller) SetStoreReconciler ¶ added in v0.2.16
func (c *Controller) SetStoreReconciler(r *storeseed.Reconciler)
SetStoreReconciler wires the declarative store-seed reconciler the activation path runs (post-commit, best-effort) to materialise VECTORS/ + KV/ packs into the runtime stores. Nil-safe: unset ⇒ packs are inert.
func (*Controller) SetVectorStore ¶ added in v0.2.16
func (c *Controller) SetVectorStore(v vector.Store)
SetVectorStore wires the vector store the inspect/teardown admin endpoints read (`txco vector ls/show/diff/rm`). Nil-safe.
func (*Controller) Start ¶
func (c *Controller) Start()
func (*Controller) Stop ¶
func (c *Controller) Stop()
func (*Controller) WarmDatasets ¶ added in v0.2.19
func (c *Controller) WarmDatasets(ctx context.Context, tenantID, stackName string, versionNumber int64)
WarmDatasets prefetches + opens every dataset artifact the given stack version references, so a data-plane node's first query doesn't eat a multi-GB CAS fetch inside a request. Post-commit, best-effort: failures log and the lazy path remains (the op materialises on demand).
type OpRecord ¶
type OpRecord struct {
Stack string `json:"stack"`
Scope int `json:"scope"`
Name string `json:"name"`
Txcl string `json:"txcl"`
MockReq string `json:"mock_req,omitempty"`
MockRes string `json:"mock_res,omitempty"`
}
OpRecord is the wire shape for a single rule in the admin API. It maps 1:1 to a row in the `ops` table.
Identity is `(stack, scope, name)` — the name comes from the rule's filename minus the `.txcl` extension on the developer's disk. Multiple rules per (stack, scope) are first-class: each name is one row, and each runs in parallel at that stage.
Source Files
¶
- allowance_endpoints.go
- auth_endpoints.go
- blob_endpoints.go
- blobs.go
- browserauth.go
- calls.go
- caps.go
- cli_exec.go
- compute_source.go
- computes.go
- control_publish.go
- cron_config_endpoints.go
- datasets.go
- demo.go
- dns_config_endpoints.go
- dns_crud_endpoints.go
- dns_fleet.go
- dns_render.go
- error_logging.go
- fleet_resync.go
- gate.go
- inspect_endpoints.go
- invite_endpoints.go
- kv_endpoints.go
- legacy_routes.go
- notebook_endpoints.go
- oauth_endpoints.go
- oauth_reauth.go
- oauth_verify.go
- ops.go
- outlets.go
- registry_token.go
- room_endpoints.go
- runs.go
- sandboxes.go
- secret_endpoints.go
- secret_fleet.go
- server.go
- source_endpoints.go
- stacks.go
- storeseed.go
- tenant_endpoints.go
- tenant_hostname_endpoints.go
- tenant_middleware.go
- tenant_runtime_endpoints.go
- throttle.go
- tls_ask.go
- trace_request.go
- trace_stream.go
- traces.go
- vector_inspect.go
Directories