Skip to main content

Crate cortexkit_bus_client

Crate cortexkit_bus_client 

Source
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.{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 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.

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_id is 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’s duplicate() 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, the cortexkit_bus_trait::Stream::publish claim-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 for ck.{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 its event_subject_with_reader constructor.
  • publish_claim_check(event, version, qualifier, msg_id, digest, headers) uses the same subject naming and the bus-nats codec, sending an empty payload with Nats-Msg-Id and Ck-Content-Digest. Store the body before publishing and serve it through the publisher’s own events_get query 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 on ck.{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? returns Option<BucketEntry> with value: Bytes and revision: u64. Deleted and absent keys return None.
  • bucket.put(key, value).await? and bucket.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 a BucketWatch. Its next().await? yields BucketItem::Put { key, revision, value }, Delete { key, revision }, or CaughtUp. Current entries come first, followed by exactly one CaughtUp (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.
BucketEntry
A current value and its bucket-wide JetStream revision.
BucketWatch
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.
BusClientOptions
Options for one module’s bus connection.
EventDelivery
A stored event. Commit your own transaction before calling Self::ack. Dropping a delivery does not acknowledge it; the server may redeliver it.
EventReader
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 BusClient alive so its credential maintenance continues to run.
MalformedDelivery
A malformed record. Log the reason and call Self::term to prevent retries. Nothing, including malformed records, is acknowledged automatically.

Enums§

BucketItem
A snapshot/live change, or the boundary after the initial snapshot.
Error
Errors contain refusal codes, not credential JWTs or nonce signatures.
EventItem
One EVENT pull result. Malformed records can only be terminated, not acked.
MalformedReason
Why a stored record cannot be exposed as a valid event.

Type Aliases§

Result