Expand description
§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.
use cortexkit_bus_client::{BusClient, BusClientOptions};
let bus = BusClient::connect(subc, BusClientOptions::new("my_module")?).await?;
let connection = bus.connection();
let mut changes = bus.connection_changes();
bus.publish_event("fact.created", 1, None, "fact-42", "public fact").await?;§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 prefix and lets cortexkit-bus-nats set it before connecting.
The prefix is either _INBOX.{credential_public} or, for a module that reads
hub records, ckdel.{box}.{module}. The bus module must not serve the new prefix
until readers run bus-client 0.1.7 or later with bus-nats 0.5.4 or later.
Nonces are signed through ckbus.nonce_sign; the module never receives a seed.
inbox_prefix() returns an owned copy of the current connection’s prefix. It
changes after credential re-issue for the per-credential form and stays stable
for the ckdel form. box_id() returns the computer’s box id from the
credential’s box_{machine_id} account, or None for another account form. Use
the id supplied by the bus module in that account; a module must never derive it
itself.
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 JWT for that connection’s credential public key on each
reconnect. Renewal must keep the same inbox prefix; older replies that omit the
prefix leave it unchanged. 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 credential’s inbox prefix.
connection() returns a cloned snapshot, not a permanently updating handle.
Watch connection_changes() and reopen raw subscriptions and durable pulls on
the new snapshot whenever it changes. EventReader and BucketWatch handle this
rebinding for you. 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.
A dropped connection reconnects on its own for about 36 seconds (20 attempts),
so a bus restart of about 30 seconds keeps the same connection and emits no
change. After that the connection ends for good and the client replaces it the
same way as a re-issue, retrying with backoff from 250 ms to 30 seconds while the
bus is still down. EventReader and BucketWatch wait for the replacement
instead of returning errors from the ended connection. A replaced connection
also stops reconnecting within that bound, so it never keeps retrying with a
revoked key.
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. Event bodies carry ids, counters and enums and are
limited to 4 KiB; retrieve large content through its owner’s own call.
Inline bodies reach every reader whose durable matches the subject, with no
per-reader visibility check; reserve them for pointers and facts every declared
reader may see. Flow triggers must use
BusClient::publish_claim_check, thecortexkit_bus_trait::Stream::publishclaim-check path (empty payload plus content digest), with the publisher serving the body under the reading flow’s own scope to check which agent may see it. The flow engine refuses inline trigger bodies. 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 naming dependency and itsevent_subject_with_readerconstructor.publish_claim_check(event, version, qualifier, msg_id, digest, headers)uses the same subject naming and the bus-nats codec, sending an empty payload withNats-Msg-IdandCk-Content-Digest. Store the body before publishing and serve it through the publisher’s ownevents_getquery under the reading flow’s scope. Caller headers may not override either reserved codec header.live_hint(kind, version, body)is a plain-NATS, versioned publish onck.{acct}.live.{module}.{kind}.v{version}; it is not a stored fact.
§Reading event bodies
bus.event_reader(durable).await? attaches to the module’s existing EVENT
durable; ck-bus provisions it, and the client never creates or changes one.
Names must follow bus-naming’s owner rule: m_{module} or
m_{module}_{suffix}, with a nonempty lowercase-letter, digit or underscore
suffix. Ownership does not grant new permissions: the module must already be
an authorized event reader.
reader.next().await? waits for one record and returns EventItem::Delivery
or EventItem::Malformed. A valid delivery has a naming-parsed subject
(module is the publisher, plus event, version, optional reader),
msg_id, body: Bytes, stream_sequence and delivered_count. Its
headers() accessor returns a read-only cortexkit_bus_trait::Headers map;
header(name) looks up a stored header name. Repeated headers retain their
first value, including Nats-Msg-Id.
Call delivery.ack().await? only after your own transaction commits.
nak(delay).await? requests redelivery, and term().await? stops redelivery.
No read, drop or reconnect acknowledges anything automatically. After a
credential re-issue, the reader rebinds to the same durable on the new connection;
the server keeps its cursor and unacknowledged records may redeliver. Keep the
BusClient alive for credential maintenance.
Malformed records (for example, a missing Nats-Msg-Id or an invalid EVENT
subject) carry a raw subject, a reason, and a stream sequence (absent only for
invalid JetStream metadata). They expose only term(): log the reason and
terminate the record rather than retrying it. They are not terminated
automatically. next() returns Err for transport or bind failures, including
the credential-maintenance change stream closing.
§Module KV buckets
bus.bucket(owner_module, bucket)? resolves a declaration in bus-naming’s
MODULE_BUCKETS, refusing undeclared buckets and modules that are neither the
owner nor a declared reader before making any NATS request. The bus service must
already have provisioned the bucket and grants; this client never provisions it.
bucket.get(key).await?returnsOption<BucketEntry>withvalue: Bytesandrevision: u64. Deleted and absent keys returnNone.bucket.put(key, value).await?andbucket.delete(key).await?return their revisions. Only the owner may write, and put checks the declared value cap before sending. Delete writes a retained tombstone; it does not purge history.bucket.watch().await?returns aBucketWatch. Itsnext().await?yieldsBucketItem::Put { key, revision, value },Delete { key, revision }, orCaughtUp. Current entries come first, followed by exactly oneCaughtUp(also for an empty bucket), then live changes. No durable name is accepted.
After reconnecting, the watch resumes after its last delivered revision and
never repeats a delivered revision. With history 1, overwritten intermediate
values cannot be recovered; every key’s latest retained value or delete is
delivered instead. Use an event stream if every intermediate change matters.
Owners must use delete, not purge: a removed tombstone cannot inform readers of
a deletion. Keep the BusClient alive; terminal credential maintenance failure
returns the same Error::Transport as the event reader.
Error::WatchCapacity means the bucket’s shared consumer slots are full. On
NATS 2.15.0 this maps code 400, JetStream error 10026, maximum consumers limit reached. Watches are unnamed ephemeral ordered consumers. Their grants cannot
delete consumers; after a watch drops, its slot is reclaimed by the server’s
30-second inactivity threshold, so rapid reopen attempts can temporarily fill
the bucket even with fewer live readers.
New watches fail immediately when capacity is exhausted. An already-open watch
rebinding after credential reissue logs once and retries with backoff from 1 to
5 seconds, allowing its old consumer to be reaped; after 60 seconds it returns
WatchCapacity if no slot is available. Terminal credential maintenance failure
interrupts the wait with Error::Transport.
§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.
The bucket_live tests reuse the testkit’s isolated server with restricted
owner/reader JWTs matching the bus service’s KV grants. Run them against the
checksummed NATS 2.15.0 binary with CK_NATS_SERVER_BIN and
CK_REQUIRE_NATS_SERVER=1; without a binary they report a skip.
Structs§
- Bucket
- A declared module bucket. Keep its BusClient alive for credential upkeep.
- Bucket
Entry - A current value and its bucket-wide JetStream revision.
- Bucket
Watch - A revision-resuming snapshot and live watch. Cancellation of next() is safe.
- BusClient
- A module’s current connection and the task that maintains its credentials.
- BusClient
Options - Options for one module’s bus connection.
- Event
Delivery - A stored event. Commit your own transaction before calling
Self::ack. Dropping a delivery does not acknowledge it; the server may redeliver it. - Event
Reader - A one-at-a-time reader of an existing module-owned EVENT durable.
The server owns its cursor. Re-issue rebinds the reader to the same durable;
unacknowledged messages may redeliver. Keep the
BusClientalive so its credential maintenance continues to run. - Malformed
Delivery - A malformed record. Log the reason and call
Self::termto prevent retries. Nothing, including malformed records, is acknowledged automatically.
Enums§
- Bucket
Item - A snapshot/live change, or the boundary after the initial snapshot.
- Error
- Errors contain refusal codes, not credential JWTs or nonce signatures.
- Event
Item - One EVENT pull result. Malformed records can only be terminated, not acked.
- Malformed
Reason - Why a stored record cannot be exposed as a valid event.