Help us shape the future of Go! Take the 2026 Go Developer Survey

client

package
v0.2.49 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 20, 2026 License: MPL-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package client is the small HTTP client the txco CLI uses to talk to a running chassis admin server.

Index

Constants

View Source 
const MaxMissingBlobsBatch = 1000

MaxMissingBlobsBatch is the most hashes one POST /blobs/missing carries.

Variables

View Source 
var ErrCommandUnsupported = errors.New("command not supported by this server")

ErrCommandUnsupported is returned by RunCommand when the server does not implement the forwarded command (HTTP 404) — either it registers no commands (open core) or no handler matches args[0]. The CLI treats this as "fall back to the unknown-subcommand error" rather than surfacing it.

View Source 
var ErrNoMissingBlobs = errors.New("chassis has no batch blob probe")

ErrNoMissingBlobs reports a chassis that predates POST /blobs/missing (the batch probe). The same release taught it COMPUTES/ rows, so callers also read it as "this chassis doesn't keep compute source".

Functions

func IsRetryable added in v0.2.16 

func IsRetryable(err error) bool

IsRetryable reports whether err is a transient failure worth retrying with backoff: a 5xx or 429 response (gateway timeouts, `database is locked`, overload), or a transport-layer network error (dial refused, TLS, timeout). Fatal 4xx (validation, auth, not-found) and a caller-canceled context are NOT retryable.

Types

type AbortResult added in v0.2.38 

type AbortResult struct {
	Aborted int    `json:"aborted"`
	RID     string `json:"rid,omitempty"`
	Stack   string `json:"stack,omitempty"`
	// Published: on a fleet, the abort was also sent to every node as a
	// control event; Aborted counts the admin plane's own process only.
	Published bool `json:"published,omitempty"`
}

AbortResult is what an abort answers: how many runs it ended.

type ActivateOpts added in v0.2.24 

type ActivateOpts struct {
	ExpectedActive *int64
	ForceData      bool
}

ActivateOpts refines an activation. ExpectedActive is the version this client believes is active (0 = none): the chassis refuses with 409 `stack_moved` if the ref moved since — git's non-fast-forward rule; nil skips the check (`--force`). ForceData is `txco data apply --force`: the tree wins over runtime drift (every store-seed pack reconciled, seeded blobs re-asserted/dropped even where a runtime edit would otherwise stand).

type ActivateResponse 

type ActivateResponse struct {
	PriorVersionNumber *int64 `json:"prior_version_number,omitempty"`
	VersionNumber      int64  `json:"version_number"`
	StructuredURL      string `json:"structured_url,omitempty"`
}

type AddHostnameRequest 

type AddHostnameRequest struct {
	Hostname string `json:"hostname"`
	Stack    string `json:"stack"`
}

AddHostnameRequest is the wire body POST /v1/tenants/{t}/hostnames expects. Hostname is canonicalized server-side; the response shows the canonical form back.

type Allowance added in v0.2.45 

type Allowance struct {
	Name      string `json:"name"`
	Defined   bool   `json:"defined"`
	Fuel      int64  `json:"fuel,omitempty"`
	Per       string `json:"per"`
	Used      int64  `json:"used"`
	Remaining *int64 `json:"remaining,omitempty"`
	ResetsAt  string `json:"resets_at,omitempty"`
}

Allowance is one tenant-defined fuel budget and its current window (GET/PUT /v1/tenants/{t}/allowances/{name}). Remaining is nil for an allowance that was entered but never defined: metered, not limited.

type AllowanceList added in v0.2.45 

type AllowanceList struct {
	Allowances []Allowance `json:"allowances"`
	Next       string      `json:"next,omitempty"`
	Count      int         `json:"count"`
}

AllowanceList is one page of GET /v1/tenants/{t}/allowances.

type BatchStackSettingsResponse added in v0.2.17 

type BatchStackSettingsResponse struct {
	Matched      int      `json:"matched"`       // number of stacks whose gate was set
	MintHostname bool     `json:"mint_hostname"` // the value applied
	RevokedHosts []string `json:"revoked_hosts,omitempty"`
}

BatchStackSettingsResponse is the result of a bulk mint-gate flip.

type BootstrapBrowserResponse 

type BootstrapBrowserResponse struct {
	Token            string `json:"token"`
	ExpiresInSeconds int    `json:"expires_in_seconds"`
	URL              string `json:"url"`
}

BootstrapBrowserAuth mints a single-use exchange token. The returned URL is what the user opens to complete login in their browser; the token is embedded in the URL's hash fragment.

type Call added in v0.2.48 

type Call struct {
	Stack       string              `json:"stack"`
	Name        string              `json:"name"`
	Entry       int                 `json:"entry"`
	Stage       string              `json:"stage"`
	Description string              `json:"description,omitempty"`
	Input       map[string]CapInput `json:"input,omitempty"`
	Output      map[string]CapInput `json:"output,omitempty"`
	Timeout     int                 `json:"timeout,omitempty"`
	Err         string              `json:"err,omitempty"`
}

Call is one declared entry of a tenant's stacks: what an active stack declares under CALLS/ (chassis/calldecl). Err is set, and the declaration's fields are empty, when the active row does not parse.

type Cap added in v0.2.33 

type Cap struct {
	Name        string              `json:"name"`
	Stack       string              `json:"stack"`
	Entry       int                 `json:"entry"`
	Stage       string              `json:"stage"`
	Description string              `json:"description,omitempty"`
	Input       map[string]CapInput `json:"input,omitempty"`
	Output      map[string]CapInput `json:"output,omitempty"`
	Timeout     int                 `json:"timeout,omitempty"`
	Err         string              `json:"err,omitempty"`
}

Cap is one capability of the tenant's catalogue: what an active stack declares under CAPS/ (chassis/capdecl). Err is set, and the declaration's fields are empty, when the active row does not parse.

type CapInput added in v0.2.33 

type CapInput struct {
	Description string `json:"description,omitempty"`
	Required    bool   `json:"required,omitempty"`
}

CapInput is one input a capability takes.

type Client 

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

Client wraps an *http.Client and a Target.

func New 

func New(t Target) *Client

func NewWithTimeout added in v0.2.12 

func NewWithTimeout(t Target, timeout time.Duration) *Client

NewWithTimeout is New with a custom overall per-request timeout. Use a generous value for commands that push a lot of data (e.g. `apply` uploading many FILES); the 30s default is too short for large bundles. A non-positive timeout falls back to the default.

func (*Client) AbortRun added in v0.2.38 

func (c *Client) AbortRun(ctx context.Context, rid, reason string) (AbortResult, error)

AbortRun ends one run by rid. A run that is not in flight on the chassis answers a 404 HTTPError.

func (*Client) AbortStack added in v0.2.38 

func (c *Client) AbortStack(ctx context.Context, stack, reason string) (AbortResult, error)

AbortStack ends every run of the stack in flight on the chassis.

func (*Client) Activate 

func (c *Client) Activate(ctx context.Context, name string, versionNumber int64) (*ActivateResponse, error)

Activate: POST /stacks/{name}/activate

func (*Client) ActivateWith added in v0.2.24 

func (c *Client) ActivateWith(ctx context.Context, name string, versionNumber int64, opts ActivateOpts) (*ActivateResponse, error)

ActivateWith is Activate with ActivateOpts (ref compare-and-swap, data force).

func (*Client) AddHostname 

func (c *Client) AddHostname(ctx context.Context, req AddHostnameRequest) (*Hostname, error)

AddHostname claims a hostname for the target tenant against a specific stack. Server canonicalizes the hostname (lowercase, port- stripped, trailing-dot-stripped) so the returned row may differ from the request literal.

func (*Client) Addr 

func (c *Client) Addr() string

Addr returns the configured chassis URL. Useful for auth commands that want to echo the URL they're talking to without re-resolving.

func (*Client) AttachHostname 

func (c *Client) AttachHostname(ctx context.Context, hostname, stack string) (*Hostname, error)

AttachHostname binds an existing hostname (claimed earlier via AddHostname without --stack, or being re-pointed at a different stack) to the given stack within the active tenant.

func (*Client) BatchSetStackHostMint added in v0.2.17 

func (c *Client) BatchSetStackHostMint(ctx context.Context, match string, mint, force bool) (*BatchStackSettingsResponse, error)

BatchSetStackHostMint flips the auto-URL gate on EVERY stack whose name contains `match`, via POST /stacks/settings — the bulk sibling of SetStackHostMint, done in one server tx + one reload. Like the per-stack call, mint=false on stacks that already have live URLs requires force=true (the server returns 409 "live_url_exists" — with a `count` + sample `stacks` — otherwise) and revokes those hosts.

func (*Client) BootstrapBrowserAuth 

func (c *Client) BootstrapBrowserAuth(ctx context.Context, label string) (*BootstrapBrowserResponse, error)

BootstrapBrowserAuth signs a POST to /auth/browser/bootstrap and returns the mint response. The CLI then `open`s the URL (or prints it for the user to paste into a browser).

func (*Client) CatFile added in v0.2.13 

func (c *Client) CatFile(ctx context.Context, name, filePath string) (*FileContent, error)

CatFile: GET /stacks/{name}/cat?path=... — resolve a FILES/ asset of the stack's active version the way read-file does (manifest → CAS), for debugging.

func (*Client) ConsumeInvitation 

func (c *Client) ConsumeInvitation(ctx context.Context, req ConsumeInvitationRequest) (*DevEnrollResponse, error)

ConsumeInvitation redeems a token in exchange for a fresh actor + key. Unsigned endpoint; the token is the credential.

func (*Client) CreateDraft 

func (c *Client) CreateDraft(ctx context.Context, name, from string) (int64, error)

CreateDraft: POST /stacks/{name}/draft from: "active" to clone the currently-active version, "<N>" to clone a specific version_number, or "" for an empty draft.

func (*Client) CreateHostnameChallenge 

func (c *Client) CreateHostnameChallenge(ctx context.Context, hostname, method string, force bool) (*HostnameChallenge, error)

CreateHostnameChallenge issues a fresh DNS-TXT or HTTP-01 challenge for the named hostname. Server returns the token + human-readable setup instructions the CLI prints verbatim.

func (*Client) CreateInvitation 

func (c *Client) CreateInvitation(ctx context.Context, req CreateInvitationRequest) (*CreateInvitationResponse, error)

CreateInvitation mints a new invitation. Signed.

func (*Client) CreateRecord added in v0.2.4 

func (c *Client) CreateRecord(ctx context.Context, origin, name, rtype string, ttl int64, rdata string) error

CreateRecord adds an override/extra record under a zone. ttl<0 means "inherit the zone default".

func (*Client) CreateSecret 

func (c *Client) CreateSecret(ctx context.Context, req CreateSecretRequest) (*Secret, error)

CreateSecret stores an operator-supplied value. Server returns metadata only — the operator already has the cleartext.

func (*Client) CreateTenant 

func (c *Client) CreateTenant(ctx context.Context, req CreateTenantRequest) (*Tenant, error)

CreateTenant mints a new tenant. Server-side gated by super_admin (or basic-auth / open operator). Returns the new row including the generated tenant_id. Signed.

func (*Client) CreateZone added in v0.2.4 

func (c *Client) CreateZone(ctx context.Context, origin, mode, answerMode, fallback string) (*CreateZoneResult, error)

CreateZone registers a delegated zone. mode is "" (pattern) or "manual"; answerMode is "" (snapshot) or "stack"; fallback is "" (proposal) or "servfail".

func (*Client) DeactivateStack added in v0.2.12 

func (c *Client) DeactivateStack(ctx context.Context, name string) (*ActivateResponse, error)

DeactivateStack retires a stack by activating an EMPTY version: it creates an empty draft (no ops/files) and activates it, so the stack stops serving (HTTP 404 / mail 550 / no matching ops) while its version history stays intact and re-deployable.

This is the fleet-safe "stop serving": it rides the normal stack activation path, so every node converges the same way `apply` does — no bespoke control event that an older node couldn't apply.

Use it when you've removed a stack from your local OPS/ tree: `apply` only re-versions the stacks it still finds, so a deleted stack keeps serving its last active version until it's deactivated here.

func (*Client) DeleteAllowance added in v0.2.45 

func (c *Client) DeleteAllowance(ctx context.Context, name string) error

DeleteAllowance removes an allowance's definition.

func (*Client) DeleteDraftFile 

func (c *Client) DeleteDraftFile(ctx context.Context, name string, versionNumber int64, path, baseHash string) (*DeleteFileResponse, error)

DeleteDraftFile: DELETE /stacks/{name}/versions/{n}/files

baseHash is required (server returns 400 for blind deletes).

func (*Client) DevEnroll 

func (c *Client) DevEnroll(ctx context.Context, secret string, body DevEnrollRequest) (*DevEnrollResponse, error)

DevEnroll exchanges a shared secret for an actor + key in one shot. Unsigned (the endpoint is unprotected); we send X-Txco-Enroll-Secret as the bootstrap credential.

func (*Client) DiffVersions 

func (c *Client) DiffVersions(ctx context.Context, name string, v1, v2 int64) (*DiffResponse, error)

DiffVersions: GET /stacks/{name}/diff?v1=&v2=

func (*Client) DoScoped added in v0.2.7 

func (c *Client) DoScoped(ctx context.Context, method, suffix string, body, out any) error

DoScoped issues a signed request to a tenant-scoped endpoint living under /v1/tenants/{tenant}<suffix> (suffix is slash-prefixed, e.g. "/credit/balance"). body is JSON-encoded when non-nil; the 2xx response is decoded into out when non-nil. A non-2xx status is returned as a decoded server error.

It's the generic primitive overlay-registered CLI verbs reuse so they never reimplement signing or tenant-scoping — the same applyAuth/scopedURL/do path the built-in client methods use.

func (*Client) ExportNotebook added in v0.2.28 

func (c *Client) ExportNotebook(ctx context.Context, namespace, name string, opt NotebookReadOptions, w io.Writer) (int64, error)

ExportNotebook streams the selection as NDJSON into w and returns the byte count.

func (*Client) FleetResync added in v0.2.4 

func (c *Client) FleetResync(ctx context.Context, req FleetResyncRequest) (*FleetResyncResponse, error)

FleetResync re-emits a tenant's current control-plane state (its row + hostnames + active stack versions) as fresh fleet-sync events so lagging replicas converge. Non-destructive (upserts only). Server-side gated by super_admin. Signed.

func (*Client) GenerateSecret 

func (c *Client) GenerateSecret(ctx context.Context, req GenerateSecretRequest) (*SecretWithValue, error)

GenerateSecret mints a fresh random value server-side and returns it once. The caller is responsible for surfacing the value to the operator (e.g. printing to terminal) — no other endpoint can retrieve it later.

func (*Client) GetAllowance added in v0.2.45 

func (c *Client) GetAllowance(ctx context.Context, name string) (*Allowance, error)

GetAllowance reads one allowance's current window.

func (*Client) GetBlob added in v0.2.19 

func (c *Client) GetBlob(ctx context.Context, hash string) (io.ReadCloser, int64, error)

GetBlob streams a blob out of the chassis CAS. The caller owns closing the reader — and, because the transport is a plain body stream, SHOULD verify the received bytes hash to `hash` before trusting them (the pull path does).

func (*Client) GetDNSConfig added in v0.2.4 

func (c *Client) GetDNSConfig(ctx context.Context) (*DNSConfig, error)

GetDNSConfig returns the chassis's effective synthesis config.

func (*Client) GetDNSRender added in v0.2.4 

func (c *Client) GetDNSRender(ctx context.Context, zone string) (string, error)

GetDNSRender fetches the rendered authoritative zone-file for the target tenant from GET /v1/tenants/{tenant}/dns/render. The response is text/plain (a zone-file), not JSON. `zone` optionally limits the output to a single origin; empty renders all the tenant's zones.

func (*Client) GetSecret 

func (c *Client) GetSecret(ctx context.Context, name, stack string) (*Secret, error)

GetSecret returns metadata for one secret. `stack` selects the stack-scoped row; empty string selects the tenant-wide row.

func (*Client) GetStack 

func (c *Client) GetStack(ctx context.Context, name string) (*StackRecord, error)

GetStack: GET /stacks/{name}

func (*Client) GetTenantRuntimeState added in v0.2.11 

func (c *Client) GetTenantRuntimeState(ctx context.Context, slug string) (*TenantRuntimeState, error)

GetTenantRuntimeState reads a tenant's current admission state (read-only) — enabled/suspended, the deny status+reason a denied request gets, and the rate/concurrency limits. super_admin. Signed.

func (*Client) GetTrace 

func (c *Client) GetTrace(ctx context.Context, rid string, full bool) (*TraceResponse, []byte, error)

GetTrace fetches the aggregate trace document for rid. When full is true the response also embeds in/out payloads (only present when the chassis is running with --trace-mode=full).

Returns *TraceNotFoundError if the server returns 404 — handlers can type-assert to print a friendlier error.

Also returns the raw response bytes so callers that want to emit the untouched JSON (e.g. `txco trace --json`) don't have to re-encode.

func (*Client) GetVersion 

func (c *Client) GetVersion(ctx context.Context, name string, versionNumber int64, includeContent bool) (*VersionDetail, error)

GetVersion: GET /stacks/{name}/versions/{n}?include=content

func (*Client) GrantMember 

func (c *Client) GrantMember(ctx context.Context, req GrantMemberRequest) (*TenantMember, error)

GrantMember upserts a membership in the caller's target tenant. Server gates on actor:*:invite in the tenant. Returns the freshly- written row so callers can echo "granted actor_X: opstack:*:read" without a follow-up read.

func (*Client) HasBlob added in v0.2.19 

func (c *Client) HasBlob(ctx context.Context, hash string) (bool, error)

HasBlob reports whether the chassis CAS already holds hash, so apply can skip re-streaming an unchanged dataset artifact (the "have" probe).

func (*Client) HeadCompute 

func (c *Client) HeadCompute(ctx context.Context, alg, digest string) (bool, error)

HeadCompute reports whether a compute artifact is already present, so apply can skip re-uploading unchanged modules.

func (*Client) HostnameStatusOf 

func (c *Client) HostnameStatusOf(ctx context.Context, hostname string) (*HostnameStatus, error)

HostnameStatusOf reads the read-only state of a hostname (binding + current active/expired challenges) without rotating anything. Counterpart to CreateHostnameChallenge for "I just want to see what token is in DNS today." See internal docs/todo-custom-domains.md §6a.

func (*Client) ListAllowances added in v0.2.45 

func (c *Client) ListAllowances(ctx context.Context, after string, limit int) (*AllowanceList, error)

ListAllowances returns a page of the tenant's allowances after the cursor.

func (*Client) ListBrowserSessions 

func (c *Client) ListBrowserSessions(ctx context.Context) ([]SessionRecord, error)

ListBrowserSessions returns every session for the target tenant, newest first.

func (*Client) ListCalls added in v0.2.48 

func (c *Client) ListCalls(ctx context.Context) ([]Call, error)

ListCalls returns the entries the target tenant's active stacks declare.

func (*Client) ListCaps added in v0.2.33 

func (c *Client) ListCaps(ctx context.Context) ([]Cap, error)

ListCaps returns the target tenant's capability catalogue, by name.

func (*Client) ListHostnames 

func (c *Client) ListHostnames(ctx context.Context, history bool) ([]Hostname, error)

ListHostnames returns the active hostnames bound to the target tenant. `history=true` flips to all-rows mode (including revoked ones) for debugging "who used to own this?".

func (*Client) ListInvitations 

func (c *Client) ListInvitations(ctx context.Context) ([]Invitation, error)

ListInvitations returns all invitations (newest first). Signed.

func (*Client) ListKV added in v0.2.19 

func (c *Client) ListKV(ctx context.Context, namespace, after string, limit int) (*KVListResponse, error)

ListKV returns a windowed page of user keys under (tenant, namespace) in the op-writable KV store. `after` is the resume cursor (empty = first page); `limit` caps the page (0 = server default). The response's Next is the cursor for the following page ("" when the namespace is exhausted).

func (*Client) ListNotebooks added in v0.2.28 

func (c *Client) ListNotebooks(ctx context.Context, namespace, prefix, after string, limit int) (*NotebookListResponse, error)

ListNotebooks returns a windowed page of the notebooks under (tenant, namespace) whose names start with prefix. `after` is the last name of the previous page ("" = first page).

func (*Client) ListOps 

func (c *Client) ListOps(ctx context.Context, prefix string) ([]Op, error)

ListOps returns rules at-or-under the given stack prefix. Empty prefix returns all rules.

func (*Client) ListRecords added in v0.2.4 

func (c *Client) ListRecords(ctx context.Context, origin string) ([]DNSRecordInfo, error)

ListRecords returns the active override records under a zone.

func (*Client) ListRuns added in v0.2.38 

func (c *Client) ListRuns(ctx context.Context) ([]LiveRun, error)

ListRuns returns the target tenant's runs in flight on the chassis.

func (*Client) ListSecrets 

func (c *Client) ListSecrets(ctx context.Context) ([]Secret, error)

ListSecrets returns active secrets in the active tenant (both tenant-wide and stack-scoped). Metadata only — the wire never carries a value field on this path.

func (*Client) ListSources added in v0.2.28 

func (c *Client) ListSources(ctx context.Context) ([]SourceStatus, error)

ListSources returns the URL tenant's declared source watchers with runtime state (read-only). Backs `txco source status`.

func (*Client) ListStackBlobs added in v0.2.24 

func (c *Client) ListStackBlobs(ctx context.Context, stack string) ([]StackBlob, error)

ListStackBlobs: GET /stacks/{name}/blobs — the names the stack's BLOBS/ tree seeded, with drift. `txco data apply` refuses to push over drift unless forced; `txco data pull` materialises it into the tree.

func (*Client) ListStacks 

func (c *Client) ListStacks(ctx context.Context) ([]StackRecord, error)

ListStacks: GET /stacks

func (*Client) ListTenantMembers 

func (c *Client) ListTenantMembers(ctx context.Context) ([]TenantMember, error)

ListTenantMembers returns the active membership rows for the caller's target tenant (set via Target.Tenant). Server enforces actor:read in this tenant. Signed.

func (*Client) ListTenants 

func (c *Client) ListTenants(ctx context.Context) ([]Tenant, error)

ListTenants returns the tenants the caller can see. The chassis filters by membership (or returns all for super_admin); the client just renders. Signed.

func (*Client) ListTraces 

func (c *Client) ListTraces(ctx context.Context, limit int, grep string) (*TraceListResponse, error)

ListTraces fetches recent traces. See ListTracesETag for the ETag-aware variant; this thin wrapper is kept for callers that don't care about caching.

func (*Client) ListTracesETag 

func (c *Client) ListTracesETag(ctx context.Context, limit int, grep, ifNoneMatch string) (*TraceListResponse, string, bool, error)

ListTracesETag fetches recent traces, sending If-None-Match when ifNoneMatch is non-empty. Returns (resp, etag, notModified, err):

  • notModified=true means the server returned 304 and resp is nil; the caller should keep using its cached copy.
  • on a fresh 200 response, etag is the server's new ETag — pass it on the next call to short-circuit if nothing changed.

limit<=0 means the server default (50; server caps at 500). When grep is non-empty the server filters to traces whose files contain the substring (case-insensitive).

func (*Client) ListVersions 

func (c *Client) ListVersions(ctx context.Context, name string) ([]VersionRecord, error)

ListVersions: GET /stacks/{name}/versions

func (*Client) ListZones added in v0.2.4 

func (c *Client) ListZones(ctx context.Context) ([]DNSZoneInfo, error)

ListZones returns the tenant's active zones.

func (*Client) MintHostname added in v0.2.9 

func (c *Client) MintHostname(ctx context.Context, stack string) (*MintHostnameResult, error)

MintHostname mints a structured (auto-generated) hostname bound to a stack — verified + DKIM at mint, routable fleet-wide. Use it to give a non-web stack (e.g. a mail-only `_mail` channel) a reachable host with no DNS setup.

func (*Client) MissingBlobs added in v0.2.36 

func (c *Client) MissingBlobs(ctx context.Context, hashes []string) ([]string, error)

MissingBlobs returns which of hashes the chassis CAS does not hold — one request per MaxMissingBlobsBatch hashes instead of a HEAD each. It returns ErrNoMissingBlobs from an older chassis (404), so the caller can fall back to HasBlob. An empty list is a valid probe of the endpoint itself.

func (*Client) OAuthEnroll added in v0.2.4 

func (c *Client) OAuthEnroll(ctx context.Context, endpointURL string, req OAuthEnrollRequest) (*OAuthEnrollResponse, error)

OAuthEnroll POSTs to the full enroll endpoint URL (resolved by the caller from cloud discovery / flags — the CLI never guesses the path), exchanging a verified id_token + ed25519 public key for a tenant + actor/key. Unsigned; the id_token is the credential. On a non-200 it returns *HTTPError so callers can branch on StatusCode/Code — e.g. a 409 `tenant_slug_required` carrying Detail["suggested_tenant_slug"].

func (*Client) OAuthReauth added in v0.2.31 

func (c *Client) OAuthReauth(ctx context.Context, endpointURL string, req OAuthReauthRequest) (*OAuthReauthResponse, error)

OAuthReauth POSTs to the full reauth endpoint URL: an already-enrolled key signing back in after an admin-UI sign-out. It clears the actor's re-auth marker and creates nothing. Unsigned; the id_token is the credential. A non-200 is an *HTTPError: 403 `identity_not_enrolled` / `identity_mismatch` carry Detail["signed_in_as"]; a 404 with no code is a chassis that predates the endpoint.

func (*Client) OpenStream added in v0.2.9 

func (c *Client) OpenStream(ctx context.Context, suffix string) (io.ReadCloser, error)

OpenStream issues a signed GET to a tenant-scoped endpoint and returns the raw response body for streaming (e.g. an SSE feed). The caller MUST Close the returned body.

Unlike DoScoped it imposes NO client-level timeout — the stream is long-lived and cancelled via ctx, not a deadline. A non-2xx status is returned as a decoded server error.

func (*Client) PatchDraftFile 

func (c *Client) PatchDraftFile(ctx context.Context, name string, versionNumber int64, path, content, baseHash string) (*PatchFileResponse, error)

PatchDraftFile: PATCH /stacks/{name}/versions/{n}/files

Single-file upsert with optimistic concurrency. baseHash is the content_hash the caller previously observed; pass "" to create a new file. The server returns 404 if you pass a non-empty baseHash for a path that doesn't exist, and 409 for hash mismatch or create-collision. decodeError surfaces those with their `current_hash` so the caller can present a useful conflict UI.

func (*Client) PutBlob added in v0.2.19 

func (c *Client) PutBlob(ctx context.Context, hash string, r io.Reader, size int64) error

PutBlob streams size bytes from r into the chassis CAS under hash (lowercase sha256 hex of the bytes, which the caller has already computed by streaming the file — see hashFileStreaming). The body is never held in memory; Content-Digest is pre-set from the known hash so the request signature covers it without the signer needing the bytes. The server re-hashes the stream and refuses a mismatch, so a corrupt read or truncated transfer cannot poison the CAS. Idempotent.

func (*Client) PutCompute 

func (c *Client) PutCompute(ctx context.Context, alg, digest, engine string, wasm []byte) error

PutCompute uploads a content-addressed compute module. The server verifies sha256(body)==digest; the upload is idempotent. engine (e.g. "wazero") is recorded in the artifact manifest.

func (*Client) PutDNSConfig added in v0.2.4 

func (c *Client) PutDNSConfig(ctx context.Context, patch DNSConfigPatch) (*DNSConfig, error)

PutDNSConfig applies a partial update and returns the new effective config.

func (*Client) PutDraftFiles 

func (c *Client) PutDraftFiles(ctx context.Context, name string, versionNumber int64, files []StackFile) (*PutFilesResponse, error)

PutDraftFiles: PUT /stacks/{name}/versions/{n}/files — replaces the whole file set (manage="all"). Used by `txco dev` (full local mirror).

func (*Client) PutDraftFilesScoped added in v0.2.16 

func (c *Client) PutDraftFilesScoped(ctx context.Context, name string, versionNumber int64, files []StackFile, manage string) (*PutFilesResponse, error)

PutDraftFilesScoped is PutDraftFiles with an explicit manage scope: "code" replaces rules + FILES and carries the store-seed packs forward; "data" replaces VECTORS/+KV/ packs and carries the code forward; "" / "all" replaces everything. This is how data stays opt-in — `txco apply` uses "code".

func (*Client) ReadNotebook added in v0.2.28 

func (c *Client) ReadNotebook(ctx context.Context, namespace, name string, opt NotebookReadOptions) (*NotebookReadResponse, error)

ReadNotebook returns one page of entries, always oldest first. Next is the cursor for the following page ("" when the selection is exhausted).

func (*Client) RemoveHostname 

func (c *Client) RemoveHostname(ctx context.Context, hostname string) error

RemoveHostname soft-deletes a hostname binding. Idempotent — the server returns 200 with revoked=true whether or not the row was present.

func (*Client) ResumeTenant added in v0.2.4 

func (c *Client) ResumeTenant(ctx context.Context, slug string) (*TenantRuntimeState, error)

ResumeTenant clears a tenant's suspension (back to admit). super_admin. Signed.

func (*Client) RevokeActor added in v0.2.4 

func (c *Client) RevokeActor(ctx context.Context, actorID string) (*RevokeResponse, error)

RevokeActor signs a POST /v1/tenants/{tenant}/auth/actors/{id}/revoke. Soft-revokes the actor (stamps actors.revoked_at) and cascades to all its keys. Capability gate: actor:*:revoke (super_admin). Server refuses self-revoke with 409.

func (*Client) RevokeBrowserSession 

func (c *Client) RevokeBrowserSession(ctx context.Context, sessionID string) error

RevokeBrowserSession revokes one session by id. Idempotent at the server.

func (*Client) RevokeInvitation 

func (c *Client) RevokeInvitation(ctx context.Context, invitationID string) (*RevokeInvitationResponse, error)

RevokeInvitation marks an invitation revoked by id. Signed.

func (*Client) RevokeKey 

func (c *Client) RevokeKey(ctx context.Context, keyID string) (*RevokeResponse, error)

RevokeKey signs a POST /auth/keys/<id>/revoke.

func (*Client) RevokeMember 

func (c *Client) RevokeMember(ctx context.Context, actorID string) error

RevokeMember soft-deletes a membership for the given actor in the caller's target tenant. Server gates on actor:*:invite. Idempotent — revoking an absent/already-revoked membership returns ok.

func (*Client) RevokeRecord added in v0.2.4 

func (c *Client) RevokeRecord(ctx context.Context, origin, name, rtype string) error

RevokeRecord soft-revokes records matching (name, type) under a zone.

func (*Client) RevokeSecret 

func (c *Client) RevokeSecret(ctx context.Context, name, stack string) error

RevokeSecret soft-deletes the active row. Returns nil on 204.

func (*Client) RevokeZone added in v0.2.4 

func (c *Client) RevokeZone(ctx context.Context, origin string) error

RevokeZone soft-revokes a delegated zone by origin.

func (*Client) RotateSecret 

func (c *Client) RotateSecret(ctx context.Context, name, stack, newValue string) (*Secret, error)

RotateSecret writes a new version under the same name with an operator-supplied value.

func (*Client) RotateSecretGenerated 

func (c *Client) RotateSecretGenerated(ctx context.Context, name, stack string, byteLen int) (*SecretWithValue, error)

RotateSecretGenerated mints a fresh random value, writes a new version under the same name, and returns the value once.

func (*Client) RunCommand added in v0.2.6 

func (c *Client) RunCommand(ctx context.Context, args []string) (*CommandResult, error)

RunCommand forwards a CLI argv (e.g. ["credit","grant","add","acme","500"]) to the server's /v1/cli dispatcher as a signed request, and returns the command's rendered output + exit code. A 404 maps to ErrCommandUnsupported so the caller can fall through gracefully; other non-200s return the decoded server error.

func (*Client) RunCommandCursor added in v0.2.10 

func (c *Client) RunCommandCursor(ctx context.Context, args []string, cursor string) (*CommandResult, error)

RunCommandCursor is RunCommand carrying a poll cursor for a pollable command. The cursor is sent ONLY when non-empty, so a first poll / non-pollable command produces the exact legacy request shape (older servers that DisallowUnknownFields never see an unexpected field).

func (*Client) RunTenantCommand added in v0.2.21 

func (c *Client) RunTenantCommand(ctx context.Context, tenant string, args []string) (*CommandResult, error)

RunTenantCommand forwards a CLI argv to the TENANT-scoped exec endpoint (/v1/tenants/{tenant}/cli) as a signed request — the door for self-serve overlay verbs (`credits`/`billing`) that must run as the tenant, not super-admin. Same 404→ErrCommandUnsupported contract as RunCommand.

func (*Client) RunTenantCommandCursor added in v0.2.21 

func (c *Client) RunTenantCommandCursor(ctx context.Context, tenant string, args []string, cursor string) (*CommandResult, error)

RunTenantCommandCursor is RunTenantCommand carrying a poll cursor.

func (*Client) SetAllowance added in v0.2.45 

func (c *Client) SetAllowance(ctx context.Context, name string, fuel int64, per string) (*Allowance, error)

SetAllowance creates or replaces an allowance: fuel per hour, day or month (per "" = the server's default, day).

func (*Client) SetCallback added in v0.2.21 

func (c *Client) SetCallback(url, state string)

SetCallback attaches a loopback callback URL + state nonce to subsequent RunCommand calls, sent as request headers the server reads via clicmd.Callback.

func (*Client) SetSecretPolicy added in v0.2.31 

func (c *Client) SetSecretPolicy(ctx context.Context, name, stack, pull string) (*Secret, error)

SetSecretPolicy sets a secret's pull policy ("none", "reviewed" or "any") and nothing else: whether work dispatched somewhere else may be handed the secret itself.

func (*Client) SetStackHostMint added in v0.2.14 

func (c *Client) SetStackHostMint(ctx context.Context, name string, mint, force bool) (*StackSettingsResponse, error)

SetStackHostMint flips the per-stack auto-URL gate (stacks.mint_hostname) via PATCH /stacks/{name}/settings. mint=false makes activate skip the auto-minted routing hostname (`txco stack set --no-host`); mint=true re-enables it. The stack row is vivified server-side if it doesn't exist yet, so this can be set before the stack's first apply.

If the stack already has a live chassis-minted URL, mint=false requires force=true (the server returns 409 "live_url_exists" otherwise) and revokes that host; the revoked hostnames come back in RevokedHosts.

func (*Client) SetTenantLimits added in v0.2.4 

func (c *Client) SetTenantLimits(ctx context.Context, slug string, req SetTenantLimitsRequest) (*TenantRuntimeState, error)

SetTenantLimits sets a tenant's node-local rate-limit / concurrency caps. super_admin. Signed.

func (*Client) SetTraceAllTenants added in v0.2.6 

func (c *Client) SetTraceAllTenants(on bool)

SetTraceAllTenants switches trace reads to the chassis-wide (all-tenant) endpoints. Default (false) is tenant-scoped; the trace command turns this on when whoami reports the caller is a super-admin.

func (*Client) SetZone added in v0.2.24 

func (c *Client) SetZone(ctx context.Context, origin, answerMode, fallback string) (*DNSZoneInfo, error)

SetZone changes a zone's answer mode and/or stack fallback in place (PATCH /dns/zones/{origin}); "" leaves a field unchanged.

func (*Client) SuspendTenant added in v0.2.4 

func (c *Client) SuspendTenant(ctx context.Context, slug string, req SuspendTenantRequest) (*TenantRuntimeState, error)

SuspendTenant marks a tenant suspended so its requests are denied (deny_status, default 402) before its stack runs. super_admin. Signed.

func (*Client) TenantSlug added in v0.2.24 

func (c *Client) TenantSlug() string

TenantSlug returns the tenant this client issues tenant-scoped requests under ("" = legacy flat routes). Paired with Addr it identifies the target for per-target workspace state (state.Key).

func (*Client) UpdateSecretDescription 

func (c *Client) UpdateSecretDescription(ctx context.Context, name, stack, newDescription string) (*Secret, error)

UpdateSecretDescription PATCHes the description only. The server rejects any body that includes a `name` field (immutable per design §1.7).

func (*Client) ValidateVersion 

func (c *Client) ValidateVersion(ctx context.Context, name string, versionNumber int64) (*ValidateResponse, error)

ValidateVersion: POST /stacks/{name}/versions/{n}/validate

Server returns 200 with `{"ok": true|false, "errors": [...]}` so a failed parse is not an HTTP error — the caller decides whether `!ok` should block a downstream activate.

func (*Client) VectorDropCollection added in v0.2.16 

func (c *Client) VectorDropCollection(ctx context.Context, name string) (int, error)

VectorDropCollection: DELETE /vectors/{name}. Returns the number of items removed.

func (*Client) VectorGetCollection added in v0.2.16 

func (c *Client) VectorGetCollection(ctx context.Context, name string) (*VectorCollectionDetail, error)

VectorGetCollection: GET /vectors/{name}

func (*Client) VectorListCollections added in v0.2.16 

func (c *Client) VectorListCollections(ctx context.Context) ([]VectorCollection, error)

VectorListCollections: GET /vectors

func (*Client) VerifyHostname 

func (c *Client) VerifyHostname(ctx context.Context, hostname string) (*HostnameVerifyResponse, error)

VerifyHostname runs the active challenge for the named hostname (either DNS or HTTP method, whichever was issued). On success returns the verified_at timestamp; on failure decodes the server's "verification_failed" body so the CLI can show last_error.

func (*Client) VerifyZone added in v0.2.10 

func (c *Client) VerifyZone(ctx context.Context, origin string) (*VerifyZoneResult, error)

VerifyZone confirms a zone's NS delegate to the chassis (POST /dns/zones/{origin}/verify), flipping a pending zone live.

func (*Client) Whoami 

func (c *Client) Whoami(ctx context.Context) (*WhoamiResponse, error)

Whoami calls GET /auth/whoami with whatever credentials the target has configured. Useful to confirm signed-auth wiring.

type CommandResult added in v0.2.6 

type CommandResult struct {
	Stdout string `json:"stdout"`
	Stderr string `json:"stderr"`
	Exit   int    `json:"exit"`
	// Cursor + PollAfterMs drive the forwarder's poll loop: when PollAfterMs > 0
	// the CLI re-runs the command after that delay, passing Cursor back.
	Cursor      string `json:"cursor,omitempty"`
	PollAfterMs int    `json:"poll_after_ms,omitempty"`
	// OpenURL asks the forwarder to open this URL in the browser (best-effort,
	// interactive terminals only) after printing Stdout.
	OpenURL string `json:"open_url,omitempty"`
	// AwaitCallback asks the forwarder to block on its loopback server after
	// opening OpenURL, until the hosted page redirects back or times out.
	AwaitCallback bool `json:"await_callback,omitempty"`
}

CommandResult mirrors the server's /v1/cli response: rendered output + a process-style exit code, plus the optional poll directive (see clicmd.Result).

type ConsumeInvitationRequest 

type ConsumeInvitationRequest struct {
	Token        string `json:"token"`
	PublicKeyB64 string `json:"public_key_b64"`
	Algorithm    string `json:"algorithm"`
	Label        string `json:"label,omitempty"`
	Kind         string `json:"kind,omitempty"`
}

ConsumeInvitationRequest is the wire body POST /auth/invitations/consume expects. Unsigned endpoint — the token IS the authentication.

type CreateInvitationRequest 

type CreateInvitationRequest struct {
	Label        string   `json:"label,omitempty"`
	Kind         string   `json:"kind,omitempty"`
	TTLSeconds   int      `json:"ttl_seconds,omitempty"`
	Capabilities []string `json:"capabilities,omitempty"`
}

CreateInvitationRequest is the wire body POST /auth/invitations expects.

Capabilities is the list of 3-segment capability strings the resulting member receives. Empty defaults to admin:all on the server (back-compat with pre-phase-6 CLIs).

type CreateInvitationResponse 

type CreateInvitationResponse struct {
	InvitationID string `json:"invitation_id"`
	Token        string `json:"token"`
	ExpiresAt    string `json:"expires_at"`
}

CreateInvitationResponse is what the server returns once the token is minted. Token is the one-shot raw secret — it never appears in the DB or in any subsequent response.

type CreateSecretRequest 

type CreateSecretRequest struct {
	Name        string `json:"name"`
	Value       string `json:"value"`
	Description string `json:"description,omitempty"`
	Stack       string `json:"stack,omitempty"`
}

CreateSecretRequest mirrors the JSON shape POST /secrets accepts. Value is the operator-supplied cleartext; the server NEVER returns it back in any response.

type CreateTenantRequest 

type CreateTenantRequest struct {
	Slug string `json:"slug"`
	Name string `json:"name,omitempty"`
}

CreateTenantRequest is the wire body POST /v1/tenants expects. Slug is the durable handle and is required; Name is optional display text.

type CreateZoneResult added in v0.2.4 

type CreateZoneResult struct {
	Zone        DNSZoneInfo `json:"zone"`
	Nameservers []string    `json:"nameservers"`
	Delegation  string      `json:"delegation"`
	Warning     string      `json:"warning,omitempty"` // blast-radius note on a high fan-out reconcile
}

CreateZoneResult is the create-zone response (zone + delegation hint).

type DNSConfig added in v0.2.4 

type DNSConfig struct {
	Nameservers []string `json:"nameservers"`
	EdgeIPs     []string `json:"edge_ips"`
	MXHost      string   `json:"mx_host"`
	MXPriority  int      `json:"mx_priority"`
	TTL         int      `json:"ttl"`
	Configured  bool     `json:"configured"`
}

DNSConfig mirrors the admin effective-config DTO.

type DNSConfigPatch added in v0.2.4 

type DNSConfigPatch struct {
	Nameservers *[]string `json:"nameservers,omitempty"`
	EdgeIPs     *[]string `json:"edge_ips,omitempty"`
	MXHost      *string   `json:"mx_host,omitempty"`
	MXPriority  *int      `json:"mx_priority,omitempty"`
	TTL         *int      `json:"ttl,omitempty"`
}

DNSConfigPatch is the partial-update body; only non-nil fields change.

type DNSRecordInfo added in v0.2.4 

type DNSRecordInfo struct {
	Name  string `json:"name"`
	Type  string `json:"type"`
	TTL   *int64 `json:"ttl,omitempty"`
	Rdata string `json:"rdata"`
}

DNSRecordInfo mirrors the admin record DTO.

type DNSZoneInfo added in v0.2.4 

type DNSZoneInfo struct {
	Origin        string `json:"origin"`
	Mode          string `json:"mode"`
	AnswerMode    string `json:"answer_mode"`    // "snapshot" | "stack"
	StackFallback string `json:"stack_fallback"` // "proposal" | "servfail"
	MName         string `json:"mname"`
	RName         string `json:"rname"`
	DefaultTTL    int    `json:"default_ttl"`
	CreatedAt     string `json:"created_at,omitempty"`
	RevokedAt     string `json:"revoked_at,omitempty"`
	VerifiedAt    string `json:"verified_at,omitempty"`
}

DNSZoneInfo mirrors the admin zone DTO.

type DeleteFileResponse 

type DeleteFileResponse struct {
	Path         string `json:"path"`
	Deleted      bool   `json:"deleted"`
	ManifestHash string `json:"manifest_hash"`
}

type DevEnrollRequest 

type DevEnrollRequest struct {
	PublicKeyB64 string `json:"public_key_b64"`
	Algorithm    string `json:"algorithm"`
	Label        string `json:"label,omitempty"`
	Kind         string `json:"kind,omitempty"`
}

DevEnrollRequest is the wire body /auth/dev/enroll expects.

type DevEnrollResponse 

type DevEnrollResponse struct {
	ActorID      string   `json:"actor_id"`
	KeyID        string   `json:"key_id"`
	Capabilities []string `json:"capabilities"`
	// TenantSlug is the tenant the new actor was placed in. Always
	// "default" for bootstrap-local; the invitation's tenant for
	// accept. Empty if the server is older than phase 5; the CLI
	// falls back to "default" in that case.
	TenantSlug string `json:"tenant_slug,omitempty"`
	// SuperAdmin reports whether this enrolment yielded chassis-wide
	// super-admin (first-boot bootstrap only).
	SuperAdmin bool `json:"super_admin,omitempty"`
}

DevEnrollResponse is the wire response /auth/dev/enroll returns.

type DiffEntry 

type DiffEntry struct {
	Path     string `json:"path"`
	Change   string `json:"change"`
	FromHash string `json:"from_hash,omitempty"`
	ToHash   string `json:"to_hash,omitempty"`
}

type DiffResponse 

type DiffResponse struct {
	V1      int64       `json:"v1"`
	V2      int64       `json:"v2"`
	Equal   bool        `json:"equal"`
	Entries []DiffEntry `json:"entries,omitempty"`
}

type ErrorResponse 

type ErrorResponse struct {
	Error   string         `json:"error"`
	Message string         `json:"message,omitempty"`
	Detail  map[string]any `json:"detail,omitempty"`
}

type FileContent added in v0.2.13 

type FileContent struct {
	Stack           string `json:"stack"`
	Path            string `json:"path"`
	ActiveVersionID int64  `json:"active_version_id"`
	Found           bool   `json:"found"`
	Source          string `json:"source"`
	Reason          string `json:"reason"`
	ContentHash     string `json:"content_hash"`
	InlineLen       int    `json:"inline_len"`
	Size            int    `json:"size"`
	ContentB64      string `json:"content_b64"`
}

FileContent is the diagnostic + resolved bytes from GET /stacks/{name}/cat.

type FleetResyncCounts added in v0.2.4 

type FleetResyncCounts struct {
	TenantCreated        int `json:"tenant_created"`
	HostnameBound        int `json:"hostname_bound"`
	StackActivated       int `json:"stack_activated"`
	DNSZoneUpserted      int `json:"dns_zone_upserted"`
	DNSRecordUpserted    int `json:"dns_record_upserted"`
	DNSSettingsUpserted  int `json:"dns_settings_upserted"`
	CronSettingsUpserted int `json:"cron_settings_upserted"`
	SecretChanged        int `json:"secret_changed"`
}

FleetResyncCounts reports how many of each event type were queued.

type FleetResyncRequest added in v0.2.4 

type FleetResyncRequest struct {
	TenantSlug string `json:"tenant_slug"`
}

FleetResyncRequest targets one tenant by slug for a control-plane re-emit.

type FleetResyncResponse added in v0.2.4 

type FleetResyncResponse struct {
	FleetEnabled bool              `json:"fleet_enabled"`
	TenantSlug   string            `json:"tenant_slug,omitempty"`
	Events       FleetResyncCounts `json:"events"`
}

FleetResyncResponse is the summary POST /v1/fleet/resync returns.

type GenerateSecretRequest 

type GenerateSecretRequest struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Stack       string `json:"stack,omitempty"`
	ByteLen     int    `json:"byte_len,omitempty"`
}

GenerateSecretRequest is the body for POST /secrets/generate. The server mints ByteLen random bytes (default 32) and returns the base64-url encoded value exactly once.

type GrantMemberRequest 

type GrantMemberRequest struct {
	ActorID      string   `json:"actor_id"`
	Capabilities []string `json:"capabilities"`
}

GrantMemberRequest is the wire body for POST .../auth/members. The server treats this as an upsert: re-granting an existing member replaces the capability set (and clears revoked_at).

type HTTPError 

type HTTPError struct {
	StatusCode int
	Status     string
	Code       string
	Message    string
	Detail     map[string]any
	Raw        string
	// Server and CFRay are captured from the response headers so a 5xx can be
	// attributed to the layer that produced it: a Cloudflare edge 502/504 (the
	// worker may still be running, just slow — the apply usually lands anyway)
	// vs a real worker 5xx like `database is locked`. Error() surfaces them on
	// every 5xx so the failure line is self-describing without TXCO_VERBOSE.
	Server string
	CFRay  string
}

HTTPError captures a server-side JSON error response in a typed form so callers can branch on status (`errors.As`) without parsing the rendered string. The `Code` field is the `error` value the chassis writes (e.g. `base_hash_mismatch`, `file_not_found`); the `Detail` map carries actionable context (current_hash, path, etc.).

func (*HTTPError) Error 

func (e *HTTPError) Error() string

type Hostname 

type Hostname struct {
	ID         string `json:"id"`
	Hostname   string `json:"hostname"`
	TenantID   string `json:"tenant_id"`
	Stack      string `json:"stack"`
	CreatedAt  string `json:"created_at"`
	CreatedBy  string `json:"created_by,omitempty"`
	RevokedAt  string `json:"revoked_at,omitempty"`
	VerifiedAt string `json:"verified_at,omitempty"`
}

Hostname mirrors a tenant_hostnames row returned by the admin API.

type HostnameChallenge 

type HostnameChallenge struct {
	ID           string `json:"id"`
	Method       string `json:"method"`
	Token        string `json:"token"`
	ExpiresAt    string `json:"expires_at"`
	Instructions string `json:"instructions"`
	// Reused is true when the server returned a pre-existing active
	// challenge (idempotent path, status 200) instead of minting a new
	// one. The CLI prints a "reusing active challenge" note in that
	// case instead of implying rotation.
	Reused bool `json:"reused,omitempty"`
	// Rotated is true when the server revoked a prior active token to
	// mint this one (only when the request set force=true, status 201).
	// The CLI prints a loud "previous token revoked — update your DNS"
	// warning so the operator notices their existing TXT is now stale.
	Rotated bool `json:"rotated,omitempty"`
}

HostnameChallenge mirrors a fresh challenge row + its operator- facing instructions string.

type HostnameStatus 

type HostnameStatus struct {
	Hostname
	ActiveChallenges []HostnameStatusChallenge `json:"active_challenges,omitempty"`
}

HostnameStatus is the read-only state-of-the-hostname view returned by GET /hostnames/{hostname}/status. Lets the CLI show the current verify token (and verified state) WITHOUT mutating anything — pre-status, the only way to "see" the token was to call challenge, which rotated it (internal docs/todo-custom-domains.md §6a).

type HostnameStatusChallenge 

type HostnameStatusChallenge struct {
	ID           string `json:"id"`
	Method       string `json:"method"`
	Token        string `json:"token"`
	ExpiresAt    string `json:"expires_at"`
	Expired      bool   `json:"expired,omitempty"`
	AttemptedAt  string `json:"attempted_at,omitempty"`
	LastError    string `json:"last_error,omitempty"`
	Instructions string `json:"instructions,omitempty"`
}

HostnameStatusChallenge is one entry of HostnameStatus.ActiveChallenges — same shape as HostnameChallenge minus the issuance-only Reused / Rotated flags, plus diagnostic fields (expired, last error from the previous verify attempt).

type HostnameVerifyResponse 

type HostnameVerifyResponse struct {
	VerifiedAt string `json:"verified_at"`
	Method     string `json:"method"`
}

HostnameVerifyResponse mirrors the /verify endpoint's success body.

type Invitation 

type Invitation struct {
	InvitationID string   `json:"invitation_id"`
	Label        string   `json:"label,omitempty"`
	Kind         string   `json:"kind,omitempty"`
	Capabilities []string `json:"capabilities"`
	CreatedBy    string   `json:"created_by"`
	CreatedAt    string   `json:"created_at"`
	ExpiresAt    string   `json:"expires_at"`
	ConsumedAt   *string  `json:"consumed_at,omitempty"`
	ConsumedBy   string   `json:"consumed_by,omitempty"`
	RevokedAt    *string  `json:"revoked_at,omitempty"`
	Status       string   `json:"status"`
}

Invitation mirrors the server's invitation row for listing.

type KVListResponse added in v0.2.19 

type KVListResponse struct {
	Namespace string   `json:"namespace"`
	Keys      []string `json:"keys"`
	Next      string   `json:"next,omitempty"`
	Count     int      `json:"count"`
}

KVListResponse mirrors admin.kvListResponse (GET /kv/{namespace}).

type ListResponse 

type ListResponse struct {
	Ops []Op `json:"ops"`
}

type LiveRun added in v0.2.38 

type LiveRun struct {
	RID       string `json:"rid"`
	Tenant    string `json:"tenant"`
	Src       string `json:"src"`
	Entry     string `json:"entry,omitempty"`
	Stack     string `json:"stack,omitempty"`
	Stage     string `json:"stage,omitempty"`
	Started   string `json:"started"`
	AgeMs     int64  `json:"age_ms"`
	AbortedBy string `json:"aborted_by,omitempty"`
}

LiveRun is one run in flight, as the chassis lists it.

type MintHostnameResult added in v0.2.9 

type MintHostnameResult struct {
	Hostname string `json:"hostname"`
	Stack    string `json:"stack"`
	URL      string `json:"url"`
}

MintHostnameResult is the response from POST /hostnames/mint.

type NetworkError 

type NetworkError struct {
	Msg   string
	Cause error
}

NetworkError is the user-facing wrapping prettifyNetworkError uses when it recognises a transport-layer failure. Error() returns just the friendly sentence — the raw `Post "http://…": dial tcp …` text is hidden from `%v` output but still reachable via errors.Unwrap (and therefore errors.Is on syscall.ECONNREFUSED, net.DNSError, etc.). Debuggers grep the wrap chain; operators read the message.

func (*NetworkError) Error 

func (e *NetworkError) Error() string

func (*NetworkError) Unwrap 

func (e *NetworkError) Unwrap() error

type NotebookHead added in v0.2.28 

type NotebookHead struct {
	Name      string `json:"name"`
	HighSeq   int64  `json:"high_seq"`
	TTLSecs   int64  `json:"ttl_secs"`
	CreatedAt string `json:"created_at"`
	UpdatedAt string `json:"updated_at"`
}

NotebookHead mirrors admin.notebookHeadRow (one notebook in a namespace).

type NotebookListResponse added in v0.2.28 

type NotebookListResponse struct {
	Namespace string         `json:"namespace"`
	Notebooks []NotebookHead `json:"notebooks"`
	Next      string         `json:"next,omitempty"`
	Count     int            `json:"count"`
}

NotebookListResponse mirrors admin.notebookListResponse (GET /notebooks/{namespace}).

type NotebookReadOptions added in v0.2.28 

type NotebookReadOptions struct {
	After string
	Since string
	Until string
	Type  string
	Tail  int
	Limit int
}

NotebookReadOptions is the read selection: After is an opaque cursor from a previous response (never a sequence number); Since/Until are RFC 3339; Tail selects the newest N (returned oldest first).

type NotebookReadResponse added in v0.2.28 

type NotebookReadResponse struct {
	Namespace string            `json:"namespace"`
	Name      string            `json:"name"`
	Entries   []json.RawMessage `json:"entries"`
	Next      string            `json:"next,omitempty"`
	Cursor    string            `json:"cursor,omitempty"`
	Count     int               `json:"count"`
	Truncated bool              `json:"truncated"`
}

NotebookReadResponse mirrors admin.notebookReadResponse (GET /notebooks/{namespace}/{name}). Entries are kept raw: each is one JSON object {seq, at, type, data, object_key?} — the same line an NDJSON export writes — so the CLI prints them verbatim.

type OAuthEnrollRequest added in v0.2.4 

type OAuthEnrollRequest struct {
	IDToken    string `json:"id_token"`
	PublicKey  string `json:"public_key"`
	Label      string `json:"label,omitempty"`
	Profile    string `json:"profile,omitempty"`
	TenantSlug string `json:"tenant_slug,omitempty"`
}

OAuthEnrollRequest is the body for POST /auth/oauth/enroll. IDToken is a bearer secret — do not log this struct.

type OAuthEnrollResponse added in v0.2.4 

type OAuthEnrollResponse struct {
	ChassisURL   string   `json:"chassis_url"`
	TenantSlug   string   `json:"tenant_slug"`
	ActorID      string   `json:"actor_id"`
	KeyID        string   `json:"key_id"`
	Capabilities []string `json:"capabilities"`
}

OAuthEnrollResponse mirrors the enroll endpoint's success body. ChassisURL is the BASE admin URL to write into the CLI profile.

type OAuthReauthRequest added in v0.2.31 

type OAuthReauthRequest struct {
	IDToken   string `json:"id_token"`
	PublicKey string `json:"public_key"`
}

OAuthReauthRequest is the body for POST /auth/oauth/reauth. IDToken is a bearer secret — do not log this struct.

type OAuthReauthResponse added in v0.2.31 

type OAuthReauthResponse struct {
	ActorID    string `json:"actor_id"`
	TenantSlug string `json:"tenant_slug"`
	SignedInAs string `json:"signed_in_as"`
}

OAuthReauthResponse mirrors the reauth endpoint's success body.

type Op 

type Op 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"`
}

Op mirrors the wire shape used by chassis/server/admin.OpRecord. Kept duplicated rather than imported so the CLI doesn't pull in the server package transitively.

type PatchFileResponse 

type PatchFileResponse struct {
	Path         string `json:"path"`
	ContentHash  string `json:"content_hash"`
	ManifestHash string `json:"manifest_hash"`
}

type PutFilesResponse 

type PutFilesResponse struct {
	ManifestHash string `json:"manifest_hash"`
}

type RevokeInvitationResponse 

type RevokeInvitationResponse struct {
	Revoked      bool   `json:"revoked"`
	InvitationID string `json:"invitation_id"`
}

RevokeInvitationResponse mirrors the server's revoke response shape.

type RevokeResponse 

type RevokeResponse struct {
	Revoked bool   `json:"revoked"`
	ActorID string `json:"actor_id,omitempty"`
	KeyID   string `json:"key_id,omitempty"`
}

RevokeResponse mirrors chassis/server/admin.revokeResponse.

type Secret 

type Secret struct {
	SecretID      string `json:"secret_id"`
	TenantID      string `json:"tenant_id"`
	Stack         string `json:"stack,omitempty"`
	Name          string `json:"name"`
	Description   string `json:"description,omitempty"`
	CreatedAt     string `json:"created_at"`
	CreatedBy     string `json:"created_by,omitempty"`
	LastRotatedAt string `json:"last_rotated_at,omitempty"`
	KeyVersion    int    `json:"key_version"`
	VersionNo     int    `json:"version_no"`
	// Pull is the pull policy: "none", "reviewed" or "any". Empty from a
	// chassis that predates it, which is "none".
	Pull string `json:"pull,omitempty"`
}

Secret is the metadata view of a tenant_secrets row. NEVER contains a value field — the only paths that return cleartext are GenerateSecret and RotateSecretGenerated, both via SecretWithValue.

type SecretWithValue 

type SecretWithValue struct {
	Secret Secret `json:"secret"`
	Value  string `json:"value"`
}

SecretWithValue is the response shape from GenerateSecret and RotateSecretGenerated — the only two paths that return cleartext. `Value` is base64-url no-padding encoded random bytes.

type SessionRecord 

type SessionRecord struct {
	SessionID  string  `json:"session_id"`
	ActorID    string  `json:"actor_id"`
	TenantID   string  `json:"tenant_id"`
	UA         string  `json:"ua,omitempty"`
	IP         string  `json:"ip,omitempty"`
	CreatedAt  string  `json:"created_at"`
	ExpiresAt  string  `json:"expires_at"`
	LastSeenAt string  `json:"last_seen_at"`
	RevokedAt  *string `json:"revoked_at,omitempty"`
	RevokedBy  string  `json:"revoked_by,omitempty"`
}

SessionRecord mirrors the chassis's sessionRecord; one entry in the list-sessions response or the read side of a future "manage sessions" view.

type SetTenantLimitsRequest added in v0.2.4 

type SetTenantLimitsRequest struct {
	RPS         *float64 `json:"rps,omitempty"`
	Burst       *int     `json:"burst,omitempty"`
	Concurrency *int     `json:"concurrency,omitempty"`
}

SetTenantLimitsRequest patches a tenant's node-local rate/concurrency caps; nil fields are left unchanged server-side.

type SourceStatus added in v0.2.28 

type SourceStatus struct {
	SourceID   string `json:"source_id"`
	Stack      string `json:"stack"`
	Pack       string `json:"pack"`
	DeclaredID string `json:"declared_id"`
	Kind       string `json:"kind"`
	Enabled    bool   `json:"enabled"`
	Retired    bool   `json:"retired"`
	Status     string `json:"status"`
	ClaimedBy  string `json:"claimed_by,omitempty"`
	Cursor     string `json:"cursor,omitempty"`
	NextPollAt string `json:"next_poll_at,omitempty"`
	LastPollAt string `json:"last_poll_at,omitempty"`
	LastError  string `json:"last_error,omitempty"`
	Attempts   int    `json:"attempts"`
}

SourceStatus is one row of GET /v1/tenants/{tenant}/sources — a declared source watcher and its runtime poll state. No secret is ever included.

type StackBlob added in v0.2.24 

type StackBlob struct {
	Name        string `json:"name"`
	SHA256      string `json:"sha256"`
	Size        int64  `json:"size"`
	ContentType string `json:"content_type,omitempty"`
	Filename    string `json:"filename,omitempty"`
	SeededSHA   string `json:"seeded_sha"`
	Drifted     bool   `json:"drifted"`
	UpdatedAt   string `json:"updated_at"`
}

StackBlob is one name a stack's BLOBS/ tree seeded, as reported by GET /stacks/{name}/blobs: the live sha, the sha the tree last shipped, and whether a runtime put moved it since (drift).

type StackFile 

type StackFile struct {
	Path        string `json:"path"`
	Content     string `json:"content,omitempty"`
	ContentHash string `json:"content_hash"`
	// Encoding is "base64" when Content is base64-encoded — used for non-UTF-8
	// binary assets (images, fonts) that JSON would otherwise mangle. Empty =
	// raw UTF-8 text. The server decodes base64 before hashing/storing.
	//
	// Encoding "cas" marks a fingerprint-only row: Content is omitted and the
	// bytes MUST already be in the chassis content-addressed store under
	// ContentHash (streamed there via PutBlob). Used for DATASETS/ artifacts,
	// which can run to gigabytes and never ride the JSON body. The server
	// verifies presence and refuses the row when the hash is absent.
	Encoding string `json:"encoding,omitempty"`
}

type StackRecord 

type StackRecord struct {
	Name          string `json:"name"`
	ActiveVersion *int64 `json:"active_version,omitempty"`
	ManifestHash  string `json:"manifest_hash,omitempty"`
	// CodeManifestHash is the active version's manifest over CODE files only
	// (rules + FILES, no VECTORS/+KV/ packs). `txco apply` is code-only, so its
	// no-op short-circuit compares the local code manifest to THIS. Empty from an
	// older server → the client falls back to a normal deploy. See handleGetStack.
	CodeManifestHash string `json:"code_manifest_hash,omitempty"`
	CreatedAt        string `json:"created_at"`
	// MintHostname: false = headless (activate mints no auto routing URL),
	// true = mints one. Pointer so an OLDER server that doesn't send the
	// field decodes to nil ("unknown") rather than a misleading false — a
	// plain bool would label every stack headless against such a server.
	MintHostname *bool `json:"mint_hostname,omitempty"`
}

type StackSettingsResponse added in v0.2.14 

type StackSettingsResponse struct {
	MintHostname bool     `json:"mint_hostname"`
	RevokedHosts []string `json:"revoked_hosts,omitempty"`
}

type SuspendTenantRequest added in v0.2.4 

type SuspendTenantRequest struct {
	DenyStatus int    `json:"deny_status,omitempty"`
	DenyReason string `json:"deny_reason,omitempty"`
}

SuspendTenantRequest optionally overrides the status/reason a suspended tenant's requests return. Empty fields default to 402 / "payment_required".

type Target 

type Target struct {
	Addr   string
	User   string
	Pass   string
	Tenant string
	Auth   signer.Signer
}

Target is the destination chassis — URL plus optional basic auth. When Auth is non-nil, signed requests take precedence over basic.

Auth holds a signer.Signer (interface), not a concrete struct, so the chosen backend (file key, ssh-agent, future hardware) plugs in at this seam without the client knowing which it talks to.

Tenant is the slug under which tenant-scoped requests are issued. Empty means "talk to the legacy flat routes" — useful for chassis-wide endpoints (whoami, key revoke) where there's no tenant context, and for callers that haven't migrated yet. Phase 2 keeps both URL shapes wired on the server.

type Tenant 

type Tenant struct {
	TenantID  string `json:"tenant_id"`
	Slug      string `json:"slug"`
	Name      string `json:"name,omitempty"`
	CreatedAt string `json:"created_at"`
}

Tenant mirrors the server's tenant row for listing.

type TenantMember 

type TenantMember struct {
	ActorID      string   `json:"actor_id"`
	Label        string   `json:"label,omitempty"`
	Capabilities []string `json:"capabilities"`
	CreatedAt    string   `json:"created_at"`
}

TenantMember is one row of GET /v1/tenants/{t}/auth/members.

type TenantRuntimeState added in v0.2.4 

type TenantRuntimeState struct {
	TenantID         string  `json:"tenant_id"`
	Slug             string  `json:"slug"`
	Enabled          bool    `json:"enabled"`
	Suspended        bool    `json:"suspended"`
	DenyStatus       int     `json:"deny_status"`
	DenyReason       string  `json:"deny_reason,omitempty"`
	RateLimitRPS     float64 `json:"rate_limit_rps"`
	RateBurst        int     `json:"rate_burst"`
	ConcurrencyLimit int     `json:"concurrency_limit"`
}

TenantRuntimeState is the operator-visible admission state returned by suspend/resume.

type TraceListResponse 

type TraceListResponse struct {
	Traces []TraceSummary `json:"traces"`
	Total  int            `json:"total"`
}

TraceListResponse mirrors chassis/server/admin.traceListResponse — a paginated list of recent traces returned by GET /traces/requests.json.

type TraceNotFoundError 

type TraceNotFoundError struct{ RID string }

TraceNotFoundError marks a 404 from the trace endpoint so the caller can produce a friendly "no trace for rid …" message instead of the raw HTTP error.

func (*TraceNotFoundError) Error 

func (e *TraceNotFoundError) Error() string

type TraceResponse 

type TraceResponse struct {
	RID    string `json:"rid"`
	Src    string `json:"src,omitempty"`
	Tenant string `json:"tenant,omitempty"`
	// Stack is the boot trampoline; Route is the first stage.jump's
	// destination. See TraceSummary for the rationale.
	Stack      string `json:"stack,omitempty"`
	Route      string `json:"route,omitempty"`
	StartedAt  string `json:"started_at,omitempty"`
	FinishedAt string `json:"finished_at,omitempty"`
	DurationMs *int64 `json:"duration_ms,omitempty"`
	Status     string `json:"status"`
	// Error is the request-level reason a non-ok Status occurred (the
	// pipeline error). Empty on success. Companion to Status.
	Error            string `json:"error,omitempty"`
	PayloadBytes     int64  `json:"payload_bytes,omitempty"`
	PayloadTruncated bool   `json:"payload_truncated,omitempty"`
	// Fuel is the per-request fuel consumed; BytesIn/BytesOut are the
	// request/response sizes. Promoted from the request.usage event (mirror
	// of server traceRequestResponse). Zero when absent (older/resume traces).
	Fuel      int64          `json:"fuel,omitempty"`
	BytesIn   int64          `json:"bytes_in,omitempty"`
	BytesOut  int64          `json:"bytes_out,omitempty"`
	TraceMode string         `json:"trace_mode,omitempty"`
	Steps     []TraceStep    `json:"steps"`
	In        map[string]any `json:"in,omitempty"`
	Out       any            `json:"out,omitempty"`
}

TraceResponse mirrors chassis/server/admin.traceRequestResponse — the aggregated view of one request returned by GET /traces/requests/{rid}.json.

type TraceStep 

type TraceStep struct {
	Name            string `json:"name"`
	Operation       string `json:"operation,omitempty"`
	Transport       string `json:"transport,omitempty"`
	Stack           string `json:"stack,omitempty"`
	Scope           int    `json:"scope"`
	StartedAt       string `json:"started_at,omitempty"`
	FinishedAt      string `json:"finished_at,omitempty"`
	DurationMs      int64  `json:"duration_ms"`
	Status          string `json:"status"`
	InputBytes      int64  `json:"input_bytes"`
	OutputBytes     int64  `json:"output_bytes"`
	InputTruncated  bool   `json:"input_truncated,omitempty"`
	OutputTruncated bool   `json:"output_truncated,omitempty"`
	Error           string `json:"error,omitempty"`
	In              any    `json:"in,omitempty"`
	Out             any    `json:"out,omitempty"`
	Passes          int    `json:"passes,omitempty"`
	StopReason      string `json:"stop_reason,omitempty"`
}

type TraceSummary 

type TraceSummary struct {
	RID    string `json:"rid"`
	Src    string `json:"src,omitempty"`
	Tenant string `json:"tenant,omitempty"`
	// Stack is the chassis trampoline stack the request enters at
	// (typically "boot/%/0"). Route is the destination of the first
	// stage.jump, if any — much more useful than Stack since every
	// request enters at the same trampoline.
	Stack      string `json:"stack,omitempty"`
	Route      string `json:"route,omitempty"`
	StartedAt  string `json:"started_at,omitempty"`
	FinishedAt string `json:"finished_at,omitempty"`
	DurationMs *int64 `json:"duration_ms,omitempty"`
	Status     string `json:"status"`
}

TraceSummary is the per-trace summary used in the list view.

type ValidateError 

type ValidateError struct {
	Path string `json:"path"`
	Err  string `json:"err"`
}

type ValidateResponse 

type ValidateResponse struct {
	OK      bool            `json:"ok"`
	Errors  []ValidateError `json:"errors,omitempty"`
	Checked int             `json:"checked"`
}

type VectorCollection added in v0.2.16 

type VectorCollection struct {
	Name           string `json:"name"`
	EmbeddingModel string `json:"embedding_model,omitempty"`
	Dimensions     int    `json:"dimensions"`
	Metric         string `json:"metric"`
	Count          int    `json:"count"`
}

VectorCollection is one collection's pin + item count (`txco vector ls`).

type VectorCollectionDetail added in v0.2.16 

type VectorCollectionDetail struct {
	VectorCollection
	IDs []string `json:"ids"`
}

VectorCollectionDetail adds the item IDs (`txco vector show`/`diff`).

type VerifyZoneResult added in v0.2.10 

type VerifyZoneResult struct {
	Origin     string `json:"origin"`
	VerifiedAt string `json:"verified_at"`
	Warning    string `json:"warning,omitempty"` // blast-radius note on a high fan-out reconcile
}

VerifyZoneResult is the verify-zone response.

type VersionDetail 

type VersionDetail struct {
	VersionRecord
	Files []StackFile `json:"files"`
}

type VersionRecord 

type VersionRecord struct {
	VersionNumber int64   `json:"version_number"`
	Status        string  `json:"status"`
	ParentVersion *int64  `json:"parent_version_number,omitempty"`
	CreatedBy     string  `json:"created_by"`
	CreatedAt     string  `json:"created_at"`
	ActivatedAt   *string `json:"activated_at,omitempty"`
	ManifestHash  string  `json:"manifest_hash"`
	IsActive      bool    `json:"is_active"`
}

type WhoamiMembership 

type WhoamiMembership struct {
	TenantID     string   `json:"tenant_id"`
	TenantSlug   string   `json:"tenant_slug"`
	Capabilities []string `json:"capabilities"`
}

WhoamiMembership is one row of the per-tenant grants for the caller, returned alongside identity.

type WhoamiResponse 

type WhoamiResponse struct {
	Source       string             `json:"source"`
	ActorID      string             `json:"actor_id,omitempty"`
	KeyID        string             `json:"key_id,omitempty"`
	Label        string             `json:"label,omitempty"`
	SuperAdmin   bool               `json:"super_admin,omitempty"`
	Capabilities []string           `json:"capabilities"`
	Memberships  []WhoamiMembership `json:"memberships,omitempty"`
}

WhoamiResponse mirrors chassis/server/admin.whoamiResponse.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.