Skip to main content

Crate subc_control

Crate subc_control 

Source
Expand description

Client-facing subc channel-0 control wire shapes.

This crate is the client ↔ subc control-plane boundary. It depends only on [subc-protocol] for shared primitives such as RouteTarget and BindIdentity; clients can use it without depending on the daemon implementation.

Modules§

config
Reserved dotted operation prefixes for the v0.4 control vocabulary.
ops

Structs§

ActivityActor
Verified identity stamped by the daemon, not supplied by a recording module.
ActivityCursor
A live-feed position. Query continuation positions are sequence numbers only.
ActivityEntry
One durably appended event. prev is reserved for a future hash chain and is deliberately absent from this format. Identity is (daemon_incarnation, seq), and entries are ordered by seq rather than by their wall-clock timestamps.
ActivityQueryRequest
Filter a newest-first scan. cursor is exclusive: only lower seqs follow it.
ActivityQueryResponse
A page plus the current incarnation’s head at scan capture, even on an empty page. Subscribe from head to move from the scan to live entries without a gap.
ActivityRecordRequest
Report an event. Shape checking lives here; kind, size, ownership and rate validation remain the daemon’s responsibility. There is no actor field.
ActivityRecordResponse
Sent only after the assigned sequence has been durably appended.
ActivityRoute
A route binding owned by the recording module, checked at this epoch.
ActivityScope
A live scope owned by the recording module, checked at this epoch.
ActivitySubject
A short typed pointer, never a secret value.
ActivitySubscribeRequest
Replay after since and remain open for live entries. A refused or lagged feed ends with an Error frame carrying one of the activity refusal-code constants.
ActivitySubscribeResponse
One successful append delivered on the subscription’s correlation id. There is no separate acknowledgement; each response is one streamed entry.
AgentCommandResources
Commands attributed to agents rather than to the module that launches them. Construct with AgentCommandResources::new and its builders, not a struct literal.
AppOpenReply
A successful app.open reply.
AppOpenRequest
Ask the daemon to start the operator app named app.
BusyGaugeReading
A declared busy gauge’s last reading from the daemon’s health cache.
CapabilityRequirementStatus
CatalogEntry
A registered module’s catalog projection.
CatalogWatchRequest
Channel-0 subscription request, framed like activity.subscribe. It stays outside the exhaustive control enums; defining it does not advertise the op.
CatalogWatchResponse
One channel-0 subscription response on the request’s correlation id, with RESPONSE and MORE set, like activity.subscribe. There is no separate ACK: the first push carries the current generation, then advances may coalesce.
ChildResourceReading
One reading of a module process’s memory and CPU time. Use ChildResourceReading::new and its builders so future fields stay additive.
Claim
An opaque bearer claim. Debug output is always redacted, including when a containing request or reply is formatted. Never log the serialized body or exposed value, or put the claim in argv or an environment variable.
ClaimMintReply
One single-use 128-bit base64url claim, redeemable for 30 seconds on the daemon’s monotonic clock. The wall-clock expiry is informational only; readers must not use it to decide that a claim is still valid.
ClaimMintRequest
Mint only over the spawn’s live primary registration channel. Claim-bound connections cannot mint. Refusals never permit falling back to direct.
ClaimPresentReply
Acceptance of a single-use claim. Refusals use an ERROR frame, never this ACK.
ClaimPresentRequest
The first frame after a new connection’s handshake. Acceptance consumes the claim and binds the connection atomically while rechecking the live spawn. Any refused presentation closes the connection, including a retryable refusal; it never continues as direct.
ClaimRateLimitedDetail
Backoff carried in crate::ErrorBody::detail for claim_rate_limited.
ConnectionDescribeReply
The daemon’s current view of the caller’s connection.
ConnectionDescribeRequest
Ask the daemon what it knows about this connection.
ConsumerIdentity
Daemon-spawned consumer identity presented on route.open.
CpuLastHour
CPU used between the retained wall-clock samples, not a percentage. Construct with CpuLastHour::new and its builders, not a struct literal.
DaemonBuildProvenance
Build metadata embedded in the daemon binary.
DaemonObservedProcess
Runtime process facts observed for the daemon itself.
DaemonResources
The daemon’s own process, excluding CPU of its reaped module children. Construct with DaemonResources::new and its builders, not a struct literal.
LiveSpawn
One process present in an atomic supervisor spawn snapshot.
NotReadyReason
Why a registered module is not accepting new route binds.
OrderedJsonObject
Ordered JSON members retained for an unknown tagged value.
PendingReloadVerdict
Independent comparisons of configured path, launch spec and running image at list time. An absent verdict means the daemon predates this field, not agreement.
ProcessGroup
A live program group, ordered by descending memory in a tree reading. CPU is funded attributed credit of its currently live identities; the row additionally retains retired work. Groups never exceed their row’s CPU. Construct with ProcessGroup::new and its builders, not a struct literal.
RescanExpect
What must still match for the daemon to accept an apply of this preview, so the apply does what the preview described.
RescanModuleAction
One module’s entry in a candidate preview.
RouteOpenReplyExt
Optional reply keys kept beside, rather than inside, the exhaustive RouteOpen variant so existing emitters and readers need no source changes.
RouteOpenRequestExt
Optional request keys kept outside the exhaustive RouteOpen variant so existing construction sites and destructures remain source-compatible. SDKs send these keys only after observing ROUTE_CLOSE_REASONS_CAPABILITY.
RouteOpenTarget
Daemon-attested target facts. Spawn-only keys are ignored for all other kinds, which are always unmarked. Incomplete targets decode as absent in the reply.
ScopeServedByReply
Volatile bind history in one daemon incarnation; unknown never means served.
ScopeServedByRequest
Ask about an epoch owned by the registered module sending the request.
SpawnCursor
A daemon-incarnation-scoped position in the supervised spawn event stream.
SpawnEvent
One retained or live spawn event.
SpawnSnapshot
Atomic live-process census and the cursor at which it was observed.
StagedGeneration
Names one state of the daemon’s staged configuration. The counter alone is not enough: it starts again at zero when the daemon restarts, and a restarted daemon may hold different staged specs under the same number.
StderrTail
A module’s retained stderr, oldest entry first.
SubtreeReading
A report-only memory reading of a module’s process container.
SupervisorDaemonProvenance
Daemon provenance paired with its runtime process observation.
SupervisorEntry
A supervised module’s current state and process observations.
SupervisorHealthEntry
SupervisorModuleProvenance
Source-tagged provenance for one supervised module.
SupervisorModuleProvenanceExt
Optional entry keys kept outside the exhaustive provenance struct so older construction sites and destructures remain source-compatible.
SupervisorObservedProcess
Process facts observed by the daemon for a supervised module.
SupervisorRescanResult
SupervisorRoute
One live consumer route in a SupervisorRouteModule.
SupervisorRouteModule
Live routes served by one module.
TerminalEntry
One terminal child exit and the supervisor action it selected.
TerminalHistory
Bounded terminal history for one module, oldest retained record first.
TreeOwn
The module root’s attributed share, funded from the module row like groups. Root plus emitted child-group CPU and memory shares never exceed their respective module-row totals.
TreeReading
Cumulative CPU and current memory of a module and its descendants. Construct with TreeReading::new and its builders, not a struct literal.

Enums§

ActivityOn
Exactly one citation from which the daemon resolves the actor.
AppOpenStatus
What an app.open call did.
CatalogOrigin
Evidence-backed program origin. Unknown strings establish no recognized origin.
ChildMemoryKind
What ChildResourceReading::memory_bytes measures.
ChildResourceUnavailableReason
Why a module process’s resources could not be read.
ChildResourceUsage
A module process’s memory and CPU time as read at list time, or why none could be read.
ClaimPurpose
The authority requested for one additional connection. Only a prefix claim carries a module id. The daemon checks its grammar and that the minting module owns the longest matching reserved prefix, excluding exact reserved or gated ids and prefixes without an owner.
ClientControlPush
Daemon-originated channel-0 control push body.
ClientControlRequest
Client-originated channel-0 control RPC body.
ClientControlResponse
subc’s channel-0 response body for client control RPCs.
LaunchSpecAgreement
Comparison of the configured launch inputs with the inputs recorded at spawn. No digest or configured env values are sent to clients.
LaunchSpecUnavailableReason
ModuleDeclaredProvenance
A module’s declared build metadata, if its HELLO manifest carried it.
ModuleProtocol
Which wire protocol a supervised module speaks to subc, as DECLARED in daemon config. Never inferred from observed behaviour.
OrderedJsonValue
JSON values whose object members retain wire order at every depth.
PollKind
RegistrationMethod
How a running supervised spawn registered. Unknown future methods confer neither channel registration nor nonce registration.
ReloadPathAgreement
Whether the running process was spawned from the currently configured program.
ReloadPathUnavailableReason
Why configured and spawned paths cannot be compared.
RescanModuleActionKind
What applying a candidate would do to one module.
ResourceBound
Exact counters omit this member; uncontained or ambiguous CPU is a floor.
RouteCloseReason
Why subc is closing a module’s client routes.
RouteOpenTargetKind
A target kind unknown to this reader never establishes a supervised spawn.
RunningImageAgreement
Whether the executable currently running agrees with the spawned image.
RunningImageEvidence
Platform-specific evidence used to compare a running image with its spawn path.
RunningImageUnavailableReason
Reasons why an executable identity could not be observed.
ScopeServedByAnswer
Only Served establishes that the target acknowledged a scoped bind.
SpawnEventKind
Fact observed by the supervisor when a child process starts or exits.
StderrCaptureState
Whether stderr is being captured for a module, and if not, why not.
StderrTailEntry
SubtreeSource
The measurement behind a module’s memory including child processes.
SupervisorHealthStatus
SupervisorRouteConsumer
The identity tier the daemon can honestly report for a route consumer.
TerminalDisposition
The supervisor disposition selected after observing a terminal exit.
TerminalExitKind
Exit classification carried by supervisor history and census records.
TreeSource
The measurement behind cumulative tree resources.

Constants§

ACTIVITY_ACTOR_UNKNOWN
ACTIVITY_CURSOR_INCARNATION_MISMATCH
ACTIVITY_CURSOR_TOO_OLD
ACTIVITY_KIND_FORBIDDEN
ACTIVITY_LEDGER_CAPABILITY
Advertised in HELLO_ACK and server.describe before activity operations are used.
ACTIVITY_MALFORMED
ACTIVITY_RATE_LIMITED
ACTIVITY_READ_FORBIDDEN
ACTIVITY_SUBSCRIBER_LAGGED
ACTIVITY_TOO_LARGE
ACTIVITY_UNAVAILABLE
APP_NOT_INSTALLED
Refusal code for a known app that is not installed where the daemon looks.
APP_OPEN_DISABLED
Refusal code when the platform supports app.open but this daemon build has it switched off.
APP_OPEN_ERROR_CODES
Every app.open refusal code, in the order the daemon checks them.
APP_OPEN_NOT_USED
Refusal code on a platform that never launches apps through the daemon.
APP_UNKNOWN
Refusal code for an app id the daemon does not know.
APP_VERIFICATION_FAILED
Refusal code for an installed binary that failed the daemon’s checks. No process was started.
CONFIG_CHANGED_SINCE_PREVIEW
Refusal code for an apply whose expect no longer matches the daemon: the file it reads hashes differently, or the staged generation has moved since the preview (another rescan with module changes ran, even one that failed partway, or the daemon restarted). Nothing was applied.
REGISTRATION_CHANNEL_UNSUPPORTED
Admission refused because a gated module lacks channel support. This reason spends no restart budget; restarting cannot repair a missing declaration.
RESCAN_CANDIDATE_MAX_BYTES
The largest candidate text, in bytes, a preview accepts. A daemon config file is a few kilobytes; the cap bounds what one request can make the daemon parse.
RESCAN_CANDIDATE_PREVIEW_CAPABILITY
Advertised in server.describe by a daemon that serves supervisor.rescan_checked. A client sends that op only when this is listed: an older daemon refuses the unknown op, so a client that skipped the check would fail closed rather than preview the file on disk.
RESCAN_CANDIDATE_TOO_LARGE
Refusal code for a preview whose candidate is longer than RESCAN_CANDIDATE_MAX_BYTES.
ROUTE_CLOSE_REASONS_CAPABILITY
Capability required before sending accepts_close_reasons on route.open.
SCOPE_SERVED_BY_OP