cortexkit-bus-client
The shared Rust connection to the local ck-bus service. The module passes its
existing Arc<subc_client_rs::SubcConsumer>. Call
subc_client_rs::launch_nonce() before the module spawns children, as in any
supervised subc module.
# async
Credential lifecycle
The client calls ckbus.credential over a subc route whose caller identity the
daemon authenticates using the module's launch nonce, and connects to the
returned plaintext nats://127.0.0.1:<port> endpoint. It checks
the returned _INBOX.{credential_public} prefix and lets cortexkit-bus-nats
set it before connecting. Nonces are signed through ckbus.nonce_sign; the
module never receives a seed.
JWTs last fifteen minutes. A background task renews roughly five minutes before
exp, with zero to six seconds of process jitter. The dynamic NATS auth callback
reads the latest same-key JWT on each reconnect. Renewal does not replace the
connection or emit a change notification.
ckbus_credential_superseded and ckbus_credential_revoked from signing or
renewal cause one single-flight re-issue for the observed key. Managers are
shared by module id within the process, so concurrent refusals cannot repeatedly
revoke each other's replacements. ckbus_generation_not_live never re-issues.
Transient issuance refusals (ckbus_census_unavailable, ckbus_not_ready,
ckbus_spawn_snapshot_unavailable, ckbus_signing_failed) retain the current
credential and retry with exponential backoff from 250 ms to 30 seconds. The
ck-bus contract
specifies backoff but no numeric schedule. Initial connect waits
through those refusals too; cancel its future to stop waiting.
Re-issue creates a new connection with the new key's inbox prefix.
connection() returns a cloned snapshot, not a permanently updating handle.
Watch connection_changes() and reopen subscriptions and durable pulls on the
new snapshot whenever it changes. A durable resumes at its server-side cursor.
The watch value advances once the replacement is ready; a closed watch means
the maintenance task stopped (including on a terminal renewal refusal). Dropping
the client stops its maintenance task. Already held snapshots should not be used
after re-issue.
After any unseen change is consumed, changed() returns Err when the
maintenance task ends and drops its sender. A terminal renewal refusal also
logs one warning containing only its refusal code, not the credential. Reconnect
with BusClient::connect or report the module as degraded when this happens.
Publishing and reading rules
- Acknowledge a delivery after your own transaction commits, not before.
msg_idis the fact's own stable id, not a delivery attempt id. Distinct facts need distinct ids, including across subjects in the same stream. Inspect the returned receipt'sduplicate()flag.- Bodies carry no secrets and no tool output. Publish a safe fact or pointer, not raw execution output.
publish_event(event, version, qualifier, msg_id, body)uses naming constructors forck.{acct}.event.{module}.{event}.v{version}[.{reader}]. The optional reader qualifier is a validated module token. This crate relies on commons' naming 0.4.0 path dependency and itsevent_subject_with_readerconstructor.live_hint(kind, version, body)is a plain-NATS, versioned publish onck.{acct}.live.{module}.{kind}.v{version}; it is not a stored fact.
TLS and platforms
The local endpoint uses no TLS. However, async-nats 0.50 has unconditional
rustls dependencies, and the shared NATS backend selects its ring provider.
This crate uses the same explicit features with default features disabled; it
does not claim to remove ring. Native Windows builds can supply that provider
as existing Rust modules do.
Tests
Unit tests use a fake subc transport and a loopback NATS protocol server for issuance, nonce signing, renewal, refusal handling, backoff, single-flight, fresh inboxes and publish helpers. The opt-in real-rig test uses the published testkit; see its source for explicit binary paths and the rerun command.