@cotal-ai/core 0.168.0 → 0.170.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agent-file.d.ts +9 -5
- package/dist/agent-file.d.ts.map +1 -1
- package/dist/agent-file.js +30 -17
- package/dist/agent-file.js.map +1 -1
- package/dist/anycast-requests.d.ts +8 -1
- package/dist/anycast-requests.d.ts.map +1 -1
- package/dist/anycast-requests.js +47 -0
- package/dist/anycast-requests.js.map +1 -1
- package/dist/backup-config.d.ts +5 -2
- package/dist/backup-config.d.ts.map +1 -1
- package/dist/backup-config.js +7 -2
- package/dist/backup-config.js.map +1 -1
- package/dist/backup.d.ts +6 -0
- package/dist/backup.d.ts.map +1 -1
- package/dist/backup.js +11 -4
- package/dist/backup.js.map +1 -1
- package/dist/connector-setup.d.ts +2 -0
- package/dist/connector-setup.d.ts.map +1 -1
- package/dist/connector.d.ts +8 -11
- package/dist/connector.d.ts.map +1 -1
- package/dist/control-exchange.d.ts +114 -0
- package/dist/control-exchange.d.ts.map +1 -0
- package/dist/control-exchange.js +416 -0
- package/dist/control-exchange.js.map +1 -0
- package/dist/endpoint-binding.d.ts.map +1 -1
- package/dist/endpoint-binding.js +2 -0
- package/dist/endpoint-binding.js.map +1 -1
- package/dist/endpoint-call.d.ts +2 -1
- package/dist/endpoint-call.d.ts.map +1 -1
- package/dist/endpoint-call.js +14 -7
- package/dist/endpoint-call.js.map +1 -1
- package/dist/endpoint-channel-discovery.d.ts +102 -0
- package/dist/endpoint-channel-discovery.d.ts.map +1 -0
- package/dist/endpoint-channel-discovery.js +170 -0
- package/dist/endpoint-channel-discovery.js.map +1 -0
- package/dist/endpoint-control-plane.d.ts +204 -0
- package/dist/endpoint-control-plane.d.ts.map +1 -0
- package/dist/endpoint-control-plane.js +627 -0
- package/dist/endpoint-control-plane.js.map +1 -0
- package/dist/endpoint-delivery-plane.d.ts +337 -0
- package/dist/endpoint-delivery-plane.d.ts.map +1 -0
- package/dist/endpoint-delivery-plane.js +1291 -0
- package/dist/endpoint-delivery-plane.js.map +1 -0
- package/dist/endpoint-durable-backstop.d.ts +249 -0
- package/dist/endpoint-durable-backstop.d.ts.map +1 -0
- package/dist/endpoint-durable-backstop.js +485 -0
- package/dist/endpoint-durable-backstop.js.map +1 -0
- package/dist/endpoint-envelope.d.ts +2 -1
- package/dist/endpoint-envelope.d.ts.map +1 -1
- package/dist/endpoint-envelope.js +9 -3
- package/dist/endpoint-envelope.js.map +1 -1
- package/dist/endpoint-history.d.ts +370 -0
- package/dist/endpoint-history.d.ts.map +1 -0
- package/dist/endpoint-history.js +969 -0
- package/dist/endpoint-history.js.map +1 -0
- package/dist/endpoint-inbound.d.ts +10 -0
- package/dist/endpoint-inbound.d.ts.map +1 -0
- package/dist/endpoint-inbound.js +28 -0
- package/dist/endpoint-inbound.js.map +1 -0
- package/dist/endpoint-liveness.d.ts +105 -0
- package/dist/endpoint-liveness.d.ts.map +1 -0
- package/dist/endpoint-liveness.js +223 -0
- package/dist/endpoint-liveness.js.map +1 -0
- package/dist/endpoint-messaging.d.ts +229 -0
- package/dist/endpoint-messaging.d.ts.map +1 -0
- package/dist/endpoint-messaging.js +420 -0
- package/dist/endpoint-messaging.js.map +1 -0
- package/dist/endpoint-presence.d.ts +15 -0
- package/dist/endpoint-presence.d.ts.map +1 -1
- package/dist/endpoint-presence.js +35 -0
- package/dist/endpoint-presence.js.map +1 -1
- package/dist/endpoint-serve.d.ts +11 -1
- package/dist/endpoint-serve.d.ts.map +1 -1
- package/dist/endpoint-serve.js +42 -5
- package/dist/endpoint-serve.js.map +1 -1
- package/dist/endpoint-subjects.d.ts +3 -0
- package/dist/endpoint-subjects.d.ts.map +1 -1
- package/dist/endpoint-subjects.js +3 -0
- package/dist/endpoint-subjects.js.map +1 -1
- package/dist/endpoint-subscriptions.d.ts +199 -0
- package/dist/endpoint-subscriptions.d.ts.map +1 -0
- package/dist/endpoint-subscriptions.js +543 -0
- package/dist/endpoint-subscriptions.js.map +1 -0
- package/dist/endpoint.d.ts +96 -344
- package/dist/endpoint.d.ts.map +1 -1
- package/dist/endpoint.js +518 -3854
- package/dist/endpoint.js.map +1 -1
- package/dist/index.d.ts +3 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +5 -1
- package/dist/index.js.map +1 -1
- package/dist/launch-material.d.ts +9 -3
- package/dist/launch-material.d.ts.map +1 -1
- package/dist/launch-material.js +22 -2
- package/dist/launch-material.js.map +1 -1
- package/dist/provision-jwt.d.ts.map +1 -1
- package/dist/provision-jwt.js +1 -0
- package/dist/provision-jwt.js.map +1 -1
- package/dist/provision-permissions.d.ts +1 -1
- package/dist/provision-permissions.d.ts.map +1 -1
- package/dist/provision-permissions.js +10 -1
- package/dist/provision-permissions.js.map +1 -1
- package/dist/remote-manager-authority.d.ts +1 -1
- package/dist/run-host.d.ts +4 -1
- package/dist/run-host.d.ts.map +1 -1
- package/dist/run-journal.d.ts +2 -0
- package/dist/run-journal.d.ts.map +1 -1
- package/dist/run-journal.js +1 -1
- package/dist/run-journal.js.map +1 -1
- package/dist/run-record.d.ts +4 -0
- package/dist/run-record.d.ts.map +1 -1
- package/dist/run-record.js +36 -0
- package/dist/run-record.js.map +1 -1
- package/dist/space-quiescence-resources.d.ts +30 -0
- package/dist/space-quiescence-resources.d.ts.map +1 -0
- package/dist/space-quiescence-resources.js +45 -0
- package/dist/space-quiescence-resources.js.map +1 -0
- package/package.json +5 -1
package/dist/endpoint.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
export { MULTI_FILTER_BATCH, MULTI_FILTER_READ_CONCURRENCY } from "./endpoint-history.js";
|
|
1
2
|
import { type NativeConnectionBinding } from "./native-connection.js";
|
|
2
3
|
import { EventEmitter } from "node:events";
|
|
3
4
|
import { connect, type NatsConnection } from "@nats-io/transport-node";
|
|
@@ -8,13 +9,13 @@ import { type SecretStoreIdentity } from "./secret-store.js";
|
|
|
8
9
|
import { type ResolvedService, type SubmitAndFollowGoalOptions } from "./endpoint-invoke.js";
|
|
9
10
|
import type { EpCaller, EpPrincipal, IssuedCaller, PrincipalAuthority } from "./endpoint-subjects.js";
|
|
10
11
|
import { type EpPrincipalCommandDef } from "./endpoint-serve.js";
|
|
11
|
-
import type { ClusterDocument } from "./endpoint-cluster.js";
|
|
12
12
|
import type { EndpointReply } from "./endpoint-envelope.js";
|
|
13
13
|
import type { CompiledContract } from "./schema-profile.js";
|
|
14
|
-
import {
|
|
14
|
+
import type { RegistryEndpointsInput, RegistryEndpointsOutput } from "./registry-contract.js";
|
|
15
15
|
import type { EpVerbTarget, EpAttributedReply } from "./endpoint-verbs.js";
|
|
16
16
|
import type { AgentCard, ChannelConfig, ControlReply, ControlRequest, ControlRequestInit, Delivery, EndpointRef, MessageMeta, Part, Presence, PresencePrompts, PresenceStatus, PresenceCondition, AttentionMode, ChannelMode, CotalMessage, DmHistoryRead, HistoryMessage, DeliveryClass, MembershipChange, MembershipSnapshot } from "./types.js";
|
|
17
17
|
import type { DeliveryLeaseInfo, ManagerLeaseInfo } from "./lease.js";
|
|
18
|
+
import { type MaybePromise } from "./endpoint-delivery-plane.js";
|
|
18
19
|
import { type AnycastStatus } from "./anycast-requests.js";
|
|
19
20
|
import { type ParsedSubject } from "./subjects.js";
|
|
20
21
|
import { isPermissionDenied } from "./permission-denied.js";
|
|
@@ -27,26 +28,6 @@ export declare const DEFAULT_SERVER = "nats://127.0.0.1:4222";
|
|
|
27
28
|
export declare function deliveryLimitOf(value: string | undefined): number | null;
|
|
28
29
|
/** Space joined when none is given on the CLI (the `cotal-<space>` cmux tab, etc.). */
|
|
29
30
|
export declare const DEFAULT_SPACE = "main";
|
|
30
|
-
/** How many channel filters one multi-filter consumer create may carry.
|
|
31
|
-
*
|
|
32
|
-
* A create names every requested channel in one request, so the request grows with the channel
|
|
33
|
-
* count and the CLIENT's request timeout is what gives way, not the broker: the create is never
|
|
34
|
-
* refused, it just does not answer. Measured on an isolated broker, one message per channel,
|
|
35
|
-
* `limit=5`: 70 filters answer in 43ms, 1,000 in 246ms, 5,000 in 5,345ms, and 10,000 does not
|
|
36
|
-
* answer at all, failing `timeout` after 5,023ms. Note 5,000 SUCCEEDED while taking longer than
|
|
37
|
-
* 10,000 took to fail, which is what says the ceiling is on the create request rather than on the
|
|
38
|
-
* read: past roughly 5s the create itself is what times out.
|
|
39
|
-
*
|
|
40
|
-
* 1,000 is chosen from that sweep rather than from the failure point: it is a fifth of the largest
|
|
41
|
-
* count that still answered, and it answers in a quarter second, so a batch stays far away from
|
|
42
|
-
* both the timeout and the response-deadline budget the dashboard has to share with its DM read.
|
|
43
|
-
* A space with the 69 chat channels this was built for is still ONE read, so the round-trip claim
|
|
44
|
-
* in #1210 is unchanged at that size. */
|
|
45
|
-
export declare const MULTI_FILTER_BATCH = 1000;
|
|
46
|
-
/** How many filter batches may be in flight at once. Bounded because the point of #1210 was to stop
|
|
47
|
-
* issuing one read per channel: a space large enough to need batches must not get the fan-out back
|
|
48
|
-
* under another name. */
|
|
49
|
-
export declare const MULTI_FILTER_READ_CONCURRENCY = 4;
|
|
50
31
|
export interface EndpointOptions {
|
|
51
32
|
/** Trusted composition custody of each opened transport, including replacement epochs.
|
|
52
33
|
* Called before binding so the owner can await its terminal closed signal on bind failure. */
|
|
@@ -243,9 +224,23 @@ export interface TransportState {
|
|
|
243
224
|
/** The server nats.js named for this edge. Omitted when the runtime supplied none. */
|
|
244
225
|
server?: string;
|
|
245
226
|
}
|
|
246
|
-
/**
|
|
247
|
-
*
|
|
248
|
-
|
|
227
|
+
/**
|
|
228
|
+
* Events: "message" (CotalMessage), "presence" (PresenceEvent), "roster" (Presence[]), "error" (Error),
|
|
229
|
+
* "connection" ({ connected: boolean }) — true on every successful (re)bind (initial start, manual
|
|
230
|
+
* reconnect, AND background self-heal), false the moment the connection drops (rebuild null window /
|
|
231
|
+
* terminal close). Lets an in-process agent track connectedness off the endpoint's own (re)binds
|
|
232
|
+
* instead of an imperative flag the self-heal path can't reach; "transport" ({ connected, server? })
|
|
233
|
+
* is the lower-level NATS socket edge, true before the full bind finishes and false during an internal
|
|
234
|
+
* nats.js reconnect without changing `connection` readiness. "stored-copies-full" ({ limit: number }): a
|
|
235
|
+
* stored copy arrived with the store at the count the copy was written under ({@link deliveryLimitOf}),
|
|
236
|
+
* so the store may have discarded older copies before this session read them; emitted for each such
|
|
237
|
+
* copy. A lowering of the count or an age set on the store removes copies without this event.
|
|
238
|
+
*
|
|
239
|
+
* Callers MUST attach an "error" listener before `start()`: async faults (incl. NATS
|
|
240
|
+
* permission denials, surfaced via `watchStatus`) are emitted as "error", and Node throws
|
|
241
|
+
* synchronously on an unhandled "error" — a missing listener turns any such fault into a
|
|
242
|
+
* process crash instead of a logged denial.
|
|
243
|
+
*/
|
|
249
244
|
/** One page of a mediated history read: the newest `limit` messages, oldest-first WITHIN the page.
|
|
250
245
|
*
|
|
251
246
|
* `complete` is the honest-truncation signal and the reason this is not just `CotalMessage[]`:
|
|
@@ -274,7 +269,9 @@ export interface PrincipalServe {
|
|
|
274
269
|
/** Resolves with the refusal that ended the serve, including one that arrives on a replaced
|
|
275
270
|
* connection after `ready` resolved. Never rejects, and never resolves after `stop`. */
|
|
276
271
|
readonly failed: Promise<Error>;
|
|
277
|
-
/** Unsubscribe and wait for
|
|
272
|
+
/** Unsubscribe, abort every handler's `signal`, and wait for each handler in flight until its
|
|
273
|
+
* request's deadline at most, which the route caps at 30 s. A reply that comes after that is
|
|
274
|
+
* dropped. */
|
|
278
275
|
stop(): Promise<void>;
|
|
279
276
|
}
|
|
280
277
|
export declare class CotalEndpoint extends EventEmitter {
|
|
@@ -369,10 +366,9 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
369
366
|
/** Caller-owned membership watches survive a connection rebuild as INTENT. Their iterators are
|
|
370
367
|
* connection-scoped and are stopped/re-created around the epoch swap. */
|
|
371
368
|
private readonly membershipFeedWatches;
|
|
372
|
-
/** The
|
|
373
|
-
*
|
|
374
|
-
private
|
|
375
|
-
private deliveryAdminServeSub?;
|
|
369
|
+
/** The plane-3 delivery daemon side of this endpoint (fan-out writer, trusted reader, control
|
|
370
|
+
* responders) and the agent's DELIVER pump. Every dependency is read when it is used. */
|
|
371
|
+
private readonly deliveryPlane;
|
|
376
372
|
/** The anycast take responder, the request records it writes, and their maintenance timer
|
|
377
373
|
* (delivery daemon, SPEC §8.1). Bound with the other Plane-3 responders and dropped with them. */
|
|
378
374
|
private takeServeSub?;
|
|
@@ -384,24 +380,6 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
384
380
|
private anycastUnavailable?;
|
|
385
381
|
private anycastSweep?;
|
|
386
382
|
private takesInFlight;
|
|
387
|
-
/** The lifecycles whose membership inventory this daemon has been asked for, as principal to uids
|
|
388
|
-
* (#4965). A durable join or leave bound to one of them is refused, so no row of a retiring lifecycle
|
|
389
|
-
* is written after its inventory read starts. An entry goes when a later inventory for the same
|
|
390
|
-
* principal finds its ACL row retired; an alias that never retires again keeps its one entry until
|
|
391
|
-
* the daemon restarts. This is the second layer of the fence: it covers a manager that does not
|
|
392
|
-
* narrow the ACL row before the inventory, on this daemon process only. The first is the ACL row
|
|
393
|
-
* each join re-reads around its write (`durableJoinFor`'s `aclFence`), which holds across daemons. */
|
|
394
|
-
private readonly retiringLifecycles;
|
|
395
|
-
/** The durable joins and leaves running now, by `<principal>/<lifecycleUid>`: the writes an
|
|
396
|
-
* inventory of that lifecycle waits for before it reads. */
|
|
397
|
-
private readonly membershipWrites;
|
|
398
|
-
/** True once {@link quiescePlane3} has stopped serving this shard pending an ownership answer.
|
|
399
|
-
* Guards {@link armPlane3} so a RECONNECT cannot silently resume serving mid-question. */
|
|
400
|
-
private plane3Quiesced;
|
|
401
|
-
/** When set, this endpoint hosts the Plane-3 fan-out writer + trusted reader (the server-side delivery
|
|
402
|
-
* daemon). `aclFor` maps an owner id to its current read ACL (`allowSubscribe`) for the reader's
|
|
403
|
-
* re-authorization — read FRESH per entry from the durable ACL registry KV, hence async. */
|
|
404
|
-
private plane3?;
|
|
405
383
|
/** Local cache of the channel registry (key = channel token), kept by a KV watch or, on an
|
|
406
384
|
* endpoint that reads it on demand, by {@link readChannels}. */
|
|
407
385
|
private readonly channelConfigs;
|
|
@@ -411,9 +389,7 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
411
389
|
/** Orders {@link readChannels} results: a read that settles after a newer one was applied is dropped. */
|
|
412
390
|
private channelReadGeneration;
|
|
413
391
|
private channelReadApplied;
|
|
414
|
-
|
|
415
|
-
* `chathist_<id>` consumer, so overlapping reads would delete/recreate it under one another. */
|
|
416
|
-
private histLock;
|
|
392
|
+
private readonly history;
|
|
417
393
|
private readonly subs;
|
|
418
394
|
/** The observer feeds {@link tap} was asked for. This is INTENT, re-subscribed by {@link bindTap}
|
|
419
395
|
* on every (re)connect: a rebuild after an outage the library could not ride out closes the old
|
|
@@ -468,9 +444,6 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
468
444
|
/** `$JS.API.CONSUMER.DELETE.<stream>.<prefix>_` for each of this connection's own KV watches and
|
|
469
445
|
* running membership scans (see {@link recordOwnWatchConsumer}). */
|
|
470
446
|
private readonly ownWatchDeletePrefixes;
|
|
471
|
-
/** Per stream, the history-reader names of this connection's current reader id and the reads
|
|
472
|
-
* waiting for one (see {@link acquireHistoryReader}). */
|
|
473
|
-
private readonly historyReaderSlots;
|
|
474
447
|
/** True until the first successful connect completes its boot backfill — distinguishes first-connect
|
|
475
448
|
* (backfill the boot channels' history) from a reconnect (reopen the core-subs, no re-backfill).
|
|
476
449
|
* Persists across reconnect (NOT connection-scoped). Replaces the legacy chat-durable consumed-cursor
|
|
@@ -875,7 +848,14 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
875
848
|
* running in the background so the endpoint never stays dead, and rethrows so the caller
|
|
876
849
|
* can report it. */
|
|
877
850
|
reconnect(): Promise<void>;
|
|
878
|
-
/**
|
|
851
|
+
/** Stop the endpoint and close its connection.
|
|
852
|
+
*
|
|
853
|
+
* Every principal serve ends first: its handlers' `signal` aborts, and stop waits for each
|
|
854
|
+
* handler in flight until its request's deadline at most, so a handler that never settles does
|
|
855
|
+
* not hold stop open longer than 30 s, the route's cap on a deadline. A reply that comes after
|
|
856
|
+
* that is dropped.
|
|
857
|
+
*
|
|
858
|
+
* The presence epoch moves first: a bind still awaiting the broker must find it moved
|
|
879
859
|
* before any await below gives it a window to install a watch on a stopped endpoint
|
|
880
860
|
* (see {@link startPresenceWatch}). */
|
|
881
861
|
stop(): Promise<void>;
|
|
@@ -887,6 +867,9 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
887
867
|
* start, during a start, rebuild or stop, while a credential transaction or its connection swap
|
|
888
868
|
* is pending, and while the connection is down or redialing. */
|
|
889
869
|
nativeConnections(): NativeConnectionBinding[];
|
|
870
|
+
/** The messaging verbs of this endpoint: multicast, unicast, anycast and the event-payload
|
|
871
|
+
* channel. Every dependency is read when it is used, so a field assigned after construction is seen. */
|
|
872
|
+
private readonly messaging;
|
|
890
873
|
/** Multicast: broadcast to everyone on a channel. */
|
|
891
874
|
multicast(text: string, opts?: {
|
|
892
875
|
channel?: string;
|
|
@@ -931,11 +914,6 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
931
914
|
* one replica. Never degrades to a warning: the failure it prevents is silent.
|
|
932
915
|
*/
|
|
933
916
|
assertExpectationSemantics(): Promise<void>;
|
|
934
|
-
/** The envelope {@link multicastExpecting} publishes, built in ONE place so that a frame and any
|
|
935
|
-
* measurement of that frame cannot describe different messages. The fields this adds — `ts`,
|
|
936
|
-
* `space`, `from`, `channel` and the normalized `mentions` — are exactly the ones a caller
|
|
937
|
-
* holding only its parts cannot account for. */
|
|
938
|
-
private casEnvelope;
|
|
939
917
|
/**
|
|
940
918
|
* The bytes this frame will ACTUALLY put on the wire, to compare against {@link maxPayload}.
|
|
941
919
|
*
|
|
@@ -951,6 +929,7 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
951
929
|
*
|
|
952
930
|
* `expectedLastSubjectSeq` is a parameter because it is a header VALUE: sizing at 0 and publishing
|
|
953
931
|
* at 123456 differ by five bytes.
|
|
932
|
+
* `expectedLastMsgId` is measured when given, so a caller that may send it can size for it.
|
|
954
933
|
*
|
|
955
934
|
* Residual: `ts` is re-stamped at publish, so the two differ in value — not in length until
|
|
956
935
|
* epoch-millis needs a 14th digit.
|
|
@@ -960,6 +939,7 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
960
939
|
parts: Part[];
|
|
961
940
|
id: string;
|
|
962
941
|
expectedLastSubjectSeq: number;
|
|
942
|
+
expectedLastMsgId?: string;
|
|
963
943
|
mentions?: string[];
|
|
964
944
|
replyTo?: string;
|
|
965
945
|
contextId?: string;
|
|
@@ -982,6 +962,10 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
982
962
|
* means "the subject must be empty". A mismatch throws, and the throw stays classifiable by the
|
|
983
963
|
* already-public {@link isCasLoss} — the error is deliberately **not wrapped**, since wrapping
|
|
984
964
|
* would hide the `err_code` that classification reads.
|
|
965
|
+
* - `expectedLastMsgId`, when given, becomes `Nats-Expected-Last-Msg-Id`. The broker checks it after
|
|
966
|
+
* its dedup cache, so a fresh value nobody has published turns a publish into a probe: an id the
|
|
967
|
+
* cache holds answers `duplicate: true` with the stored sequence, and any other id is refused
|
|
968
|
+
* with error 10070 before anything is stored.
|
|
985
969
|
*
|
|
986
970
|
* @throws if the endpoint is not live, the channel is not concrete, `id` is malformed, `parts` is
|
|
987
971
|
* empty, or `expectedLastSubjectSeq` is not a non-negative safe integer.
|
|
@@ -991,6 +975,7 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
991
975
|
parts: Part[];
|
|
992
976
|
id: string;
|
|
993
977
|
expectedLastSubjectSeq: number;
|
|
978
|
+
expectedLastMsgId?: string;
|
|
994
979
|
mentions?: string[];
|
|
995
980
|
replyTo?: string;
|
|
996
981
|
contextId?: string;
|
|
@@ -1076,6 +1061,9 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
1076
1061
|
}): void;
|
|
1077
1062
|
/** Subscribe one {@link tap} on the current connection; with none, the next bind subscribes it. */
|
|
1078
1063
|
private bindTap;
|
|
1064
|
+
/** The control plane and the service-invocation client of this endpoint. Every dependency is
|
|
1065
|
+
* read when it is used, so a field assigned after construction is seen. */
|
|
1066
|
+
private readonly controlPlane;
|
|
1079
1067
|
/** Serve control requests for a service. Returns the subscription so a caller that re-registers on
|
|
1080
1068
|
* reconnect (the delivery daemon) can drop the stale one. `boundReply` is REQUIRED for any service
|
|
1081
1069
|
* whose responder holds a wildcard publish grant over the service subtree (the delivery daemon's
|
|
@@ -1093,11 +1081,7 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
1093
1081
|
boundReply?: boolean;
|
|
1094
1082
|
concurrent?: (req: ControlRequest) => boolean;
|
|
1095
1083
|
}): import("@nats-io/transport-node").Subscription;
|
|
1096
|
-
/**
|
|
1097
|
-
private answerControl;
|
|
1098
|
-
/** Keep native named-reply and NoResponders handling, but settle when its connection closes:
|
|
1099
|
-
* nats.js can close a no-mux subscription without settling its request. One close observer per
|
|
1100
|
-
* connection avoids retaining a closed-promise callback for every completed request. */
|
|
1084
|
+
/** Forwards to the control plane's {@link EndpointControlPlane.requestBoundReply}. */
|
|
1101
1085
|
private requestBoundReply;
|
|
1102
1086
|
/** Send a control request to a service and await its reply (client side). Like {@link requestDelivery},
|
|
1103
1087
|
* the reply rides a BOUNDED subject UNDER the request subject (`ctl.<service>.<id>.reply.<uuid>`), not
|
|
@@ -1110,23 +1094,11 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
1110
1094
|
* caller with its discovered generation (SPEC 13.15). It names the reply rail this connection's
|
|
1111
1095
|
* credential reads, which is where a manager's turn notice for it lands (SPEC 14.3). */
|
|
1112
1096
|
serviceRailCaller(): EpCaller;
|
|
1113
|
-
/** This endpoint's v0.4 caller triple (§13.2) — the identity its minted ep-rail rows pin. The
|
|
1114
|
-
* owner/actor principal is mode-correct by construction (static: DEV_OWNER + the connection
|
|
1115
|
-
* identity; user mode: the bearer's callout-derived pair), and the lifecycle UID is the
|
|
1116
|
-
* launcher-supplied incarnation the rows are keyed on (ledger-consistent: the §13.1 presence
|
|
1117
|
-
* lifecycle-proof refuses a divergent uid before any publish). */
|
|
1118
|
-
private serviceCaller;
|
|
1119
1097
|
/** Follow this caller's goal on its standing connection, subscribing before submission.
|
|
1120
1098
|
* A submitter may use a separate short-lived control credential for the same caller triple;
|
|
1121
1099
|
* the accepted action's readiness budget can outlive that credential. This endpoint retains
|
|
1122
1100
|
* its existing credential renewal and caller-scoped progress grants. */
|
|
1123
1101
|
followServiceGoal(endpoint: string, submit: (signal?: AbortSignal) => Promise<EpAttributedReply>, deadlineMs?: number, opts?: Pick<SubmitAndFollowGoalOptions, "reconcile" | "signal" | "prepare">): Promise<EpAttributedReply>;
|
|
1124
|
-
/** Drop every cached handle for one endpoint after refresh or a currency split. */
|
|
1125
|
-
private clearResolvedService;
|
|
1126
|
-
/** Hold connection recovery through the whole pre-acceptance phase, including the progress
|
|
1127
|
-
* subscription flush. Release on setup failure or the command's answer, never on goal terminal. */
|
|
1128
|
-
private beginServiceInvocation;
|
|
1129
|
-
private waitServiceRecovery;
|
|
1130
1102
|
/** The resolved, digest-verified command surface of `endpoint` as this connection's caller sees
|
|
1131
1103
|
* it. Unpinned calls cache the complete discovery surface, and `refresh` drops both the full
|
|
1132
1104
|
* handle and any command-specific invocation handles. `instanceId` selects one instance without
|
|
@@ -1205,7 +1177,6 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
1205
1177
|
instanceId?: string;
|
|
1206
1178
|
classInstanceId?: string;
|
|
1207
1179
|
}): Promise<EpAttributedReply>;
|
|
1208
|
-
private invokeServiceOnce;
|
|
1209
1180
|
/** Send a durable-membership request to the SERVER-SIDE delivery daemon (`ctl.delivery`) and await its
|
|
1210
1181
|
* reply. The reply rides a subject UNDER `ctl.delivery.<id>.>` (not the per-id `_INBOX`), so the
|
|
1211
1182
|
* scoped delivery cred can answer without broad inbox-publish — see
|
|
@@ -1274,8 +1245,10 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
1274
1245
|
* or end in whitespace, so it is never trimmed or normalized. An empty string names no directory
|
|
1275
1246
|
* and leaves the card unchanged. */
|
|
1276
1247
|
setCardCwd(cwd: string): Promise<void>;
|
|
1277
|
-
/**
|
|
1278
|
-
*
|
|
1248
|
+
/** The channel registry cache, its policy lookups and the registry watch that fills it, of this
|
|
1249
|
+
* endpoint. Every dependency is read when it is used, so a field assigned after construction is seen. */
|
|
1250
|
+
private readonly channelDiscovery;
|
|
1251
|
+
/** Forwards to the channel discovery component's {@link EndpointChannelDiscovery.readsChannelsOnDemand}. */
|
|
1279
1252
|
private get readsChannelsOnDemand();
|
|
1280
1253
|
/**
|
|
1281
1254
|
* Read the channel registry from the broker now, for a consumer that reads presence on demand. One
|
|
@@ -1308,6 +1281,9 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
1308
1281
|
* from the live watch cache — drives the non-gating delivery-health surface (only durable-class
|
|
1309
1282
|
* channels have a Plane-3 backstop to report on). */
|
|
1310
1283
|
channelDeliveryClass(channel: string): DeliveryClass;
|
|
1284
|
+
/** Join, leave and channel listing, and the membership feed watches, of this endpoint. Every
|
|
1285
|
+
* dependency is read when it is used, so a field assigned after construction is seen. */
|
|
1286
|
+
private readonly subscriptions;
|
|
1311
1287
|
/** The channels this endpoint is currently subscribed to (live — reflects join/leave). */
|
|
1312
1288
|
joinedChannels(): string[];
|
|
1313
1289
|
/**
|
|
@@ -1382,11 +1358,6 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
1382
1358
|
*/
|
|
1383
1359
|
channelMembers(channel: string): Promise<ChannelMember[]>;
|
|
1384
1360
|
channelMembers(): Promise<Map<string, ChannelMember[]>>;
|
|
1385
|
-
/** Lazily open the DERIVED membership FEED KV (`cotal_membership_<space>`; admin/observer read, the
|
|
1386
|
-
* delivery daemon writes it) — the display-only who-is-subscribed view. Distinct from the authoritative
|
|
1387
|
-
* {@link membersRegistry} (`cotal_members_<space>`, the Plane-3 durable-membership source of truth): the
|
|
1388
|
-
* two names look alike, so this one is explicitly "feed". Read-only here; agents hold no grant. */
|
|
1389
|
-
private membershipFeedRegistry;
|
|
1390
1361
|
/**
|
|
1391
1362
|
* Snapshot the broker-sourced channel-membership feed (admin/observer read): every agent's
|
|
1392
1363
|
* `{live, durable}` record plus `asOf` — the feed's freshness heartbeat (epoch ms of the daemon's last
|
|
@@ -1405,12 +1376,8 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
1405
1376
|
watchMembership(onChange: (change: MembershipChange) => void, onClosed?: (err: Error) => void): Promise<{
|
|
1406
1377
|
stop(): Promise<void>;
|
|
1407
1378
|
}>;
|
|
1408
|
-
/**
|
|
1409
|
-
* per intent, so a public watch call cannot race a reconnect rearm into two consumers. */
|
|
1410
|
-
private armMembershipWatch;
|
|
1411
|
-
/** Delete identity retained across a failed/closed-epoch consumer object using the CURRENT connection. */
|
|
1379
|
+
/** Forwards to the subscriptions component's {@link EndpointSubscriptions.deleteRetainedMembershipConsumer}. */
|
|
1412
1380
|
private deleteRetainedMembershipConsumer;
|
|
1413
|
-
private finishMembershipWatchStop;
|
|
1414
1381
|
/** Record the consumer behind one of this connection's own KV watches or membership scans, and
|
|
1415
1382
|
* return the delete-subject prefix it recorded. nats.js names it `<prefix>_<serial>` and,
|
|
1416
1383
|
* rebuilding it after a stall or a sequence gap, deletes the predecessor itself with no hook before
|
|
@@ -1433,10 +1400,9 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
1433
1400
|
private deleteOwnConsumer;
|
|
1434
1401
|
/** Delete one membership-watch consumer, swallowing ONLY already-gone and a refused delete. */
|
|
1435
1402
|
private deleteMembershipConsumer;
|
|
1436
|
-
/**
|
|
1437
|
-
* cleanup custody without a request; the broker reclaims the consumer at its inactive threshold. */
|
|
1403
|
+
/** Forwards to the subscriptions component's {@link EndpointSubscriptions.disarmMembershipWatch}. */
|
|
1438
1404
|
private disarmMembershipWatch;
|
|
1439
|
-
/**
|
|
1405
|
+
/** Forwards to the subscriptions component's {@link EndpointSubscriptions.rearmMembershipWatches}. */
|
|
1440
1406
|
private rearmMembershipWatches;
|
|
1441
1407
|
/** Fetch recent messages from a channel's JetStream backlog. `signal` cancels the active pull and
|
|
1442
1408
|
* reclaims its ephemeral consumer before the promise rejects. Returns `HistoryMessage[]`
|
|
@@ -1577,65 +1543,6 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
1577
1543
|
* `before` pages toward the past: pass the `seq` of the oldest message you already have.
|
|
1578
1544
|
*/
|
|
1579
1545
|
private streamHistory;
|
|
1580
|
-
/** This connection's history-reader id, the key of its credential's reader deletes
|
|
1581
|
-
* ({@link historyReaderConsumer}). A static credential's is its connId, the nkey it signs with.
|
|
1582
|
-
* Under the auth callout the connId is the inbox nonce this client chose, so the callout keys the
|
|
1583
|
-
* deletes on {@link calloutReaderId} instead: the server's id and the client id it assigned this
|
|
1584
|
-
* connection, which the client reads from the server's INFO and does not choose. */
|
|
1585
|
-
private historyReaderId;
|
|
1586
|
-
/** Take one of this connection's history-reader names on `stream` ({@link historyReaderConsumer})
|
|
1587
|
-
* for one read. The read holds the name for its whole walk and creates and deletes a consumer
|
|
1588
|
-
* under it at each step, so this connection keeps at most {@link HISTORY_READERS} reader consumers
|
|
1589
|
-
* on a stream (#4123). A read past that many waits for a name, and `signal` ends the wait. A
|
|
1590
|
-
* reconnect under the auth callout changes the reader id, and reads from then on take the new
|
|
1591
|
-
* id's names. */
|
|
1592
|
-
private acquireHistoryReader;
|
|
1593
|
-
/** Give a read's history-reader name back and wake one read waiting for a name. A name whose
|
|
1594
|
-
* delete failed is set aside instead. */
|
|
1595
|
-
private releaseHistoryReader;
|
|
1596
|
-
/** Keep `slot` out of use until a consumer under it would have expired, then free it. */
|
|
1597
|
-
private setAsideHistoryReader;
|
|
1598
|
-
/** Create the reader consumer for one step of a read, under the read's name. It is a plain pull
|
|
1599
|
-
* consumer: an nats.js ordered consumer renames itself on every rebuild, and the observer and admin
|
|
1600
|
-
* credentials may delete only these exact names.
|
|
1601
|
-
*
|
|
1602
|
-
* Every create carries a fresh description. NATS answers a create whose config equals the existing
|
|
1603
|
-
* consumer's with that consumer, delivery state and all (measured on nats-server 2.15), and a read
|
|
1604
|
-
* repeats the same config on the same name. Without the description a reader left under the name
|
|
1605
|
-
* would come back as if new: a `DeliverPolicy.Last` reader that already delivered its message
|
|
1606
|
-
* reports nothing pending, which reads as an empty channel. With it, a create on a name in use is
|
|
1607
|
-
* refused, and a consumer that does not carry this step's description is never used.
|
|
1608
|
-
*
|
|
1609
|
-
* A consumer already under the name is never deleted, whoever left it: another holder of this
|
|
1610
|
-
* credential, a process that stopped mid-read, or this endpoint when a delete's answer was lost and
|
|
1611
|
-
* the name was taken again since. The read moves to a free name, and the taken one stays out of use
|
|
1612
|
-
* until such a consumer would have expired. */
|
|
1613
|
-
private openHistoryReader;
|
|
1614
|
-
/** Delete the read's reader consumer; already gone is the same outcome. A failed delete may still
|
|
1615
|
-
* have run with its answer lost, and the name may be taken again before this endpoint could tell,
|
|
1616
|
-
* so the name is set aside when the read gives it back rather than deleted again later. A refused
|
|
1617
|
-
* delete means the credential was minted before the observer and admin profiles held their reader
|
|
1618
|
-
* deletes. Each read would then leave a reader for the inactive threshold, which is how a polling
|
|
1619
|
-
* dashboard filled the stream's consumer limit (#4123), so the read fails and says to remint
|
|
1620
|
-
* rather than leak quietly, and reads on the stream fail at once until that reader expires. */
|
|
1621
|
-
private closeHistoryReader;
|
|
1622
|
-
private readerDeleteRefused;
|
|
1623
|
-
/** The oldest stream sequence matching `subject`, or 0 when the subject has no messages.
|
|
1624
|
-
* Mirror of {@link lastMatchingSeq}: same CREATE/INFO/NEXT/DELETE surface, `DeliverPolicy.All`
|
|
1625
|
-
* instead of `Last`, first delivered seq instead of last. Read credentials already hold this. */
|
|
1626
|
-
private firstMatchingSeq;
|
|
1627
|
-
/** The newest stream sequence matching `subject`, or 0 when the subject has no messages.
|
|
1628
|
-
*
|
|
1629
|
-
* One reader consumer at `DeliverPolicy.Last` with this subject's filter: its `num_pending`
|
|
1630
|
-
* (available from the create, before anything is delivered) is 0 for an empty subject, and
|
|
1631
|
-
* otherwise one message carries the sequence. Same CREATE/INFO/NEXT/DELETE surface `drainWindow`
|
|
1632
|
-
* already uses, so no broker authority is added. */
|
|
1633
|
-
private lastMatchingSeq;
|
|
1634
|
-
/** Drain every message matching `subject` with sequence in `[start, ceiling]`, oldest-first.
|
|
1635
|
-
* One reader consumer, one batched pull — `AckPolicy.None`, so no per-message ack
|
|
1636
|
-
* round trip. Fetches exactly the pending count so it returns as soon as the window is
|
|
1637
|
-
* delivered rather than blocking for the pull's full expiry. */
|
|
1638
|
-
private drainWindow;
|
|
1639
1546
|
/**
|
|
1640
1547
|
* Surface the connection's async status errors on our `error` event. NATS reports
|
|
1641
1548
|
* publish permission violations *only* here (subscription ones too), never on the
|
|
@@ -1725,10 +1632,12 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
1725
1632
|
* Idempotent per role. The caller must be permissive on TASK_<space>.
|
|
1726
1633
|
*/
|
|
1727
1634
|
provisionTaskQueue(role: string): Promise<void>;
|
|
1728
|
-
/**
|
|
1635
|
+
/** The Plane-3 registries, manager and daemon-renewal leases, and durable membership writes of this
|
|
1636
|
+
* endpoint. Every dependency is read when it is used, so a field assigned after construction is seen. */
|
|
1637
|
+
private readonly durableBackstop;
|
|
1638
|
+
/** Forwards to the durable backstop's {@link EndpointDurableBackstop.membersRegistry}. */
|
|
1729
1639
|
private membersRegistry;
|
|
1730
|
-
/**
|
|
1731
|
-
* ACL at mint); the delivery daemon reads it fresh per durable entry to re-authorize. */
|
|
1640
|
+
/** Forwards to the durable backstop's {@link EndpointDurableBackstop.aclRegistry}. */
|
|
1732
1641
|
private aclRegistry;
|
|
1733
1642
|
/** Privileged ({@link DurableProvisioner}): record an agent's read ACL in the durable registry at
|
|
1734
1643
|
* provision/mint time — the same act as baking it into the JWT, persisted so the server-side
|
|
@@ -1893,16 +1802,6 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
1893
1802
|
info: DeliveryLeaseInfo;
|
|
1894
1803
|
revision: number;
|
|
1895
1804
|
} | undefined>;
|
|
1896
|
-
/** Ensure + bind the manager singleton-lease bucket. Mirrors the presence-bucket pattern (connectAndBind):
|
|
1897
|
-
* AUTH mode OPENs the bucket pre-created at `cotal up` (the scoped `supervisor` cred holds no
|
|
1898
|
-
* STREAM.CREATE — and `open` binds direct=false, so the CAS-conflict `kv.get` inside `acquire` rides
|
|
1899
|
-
* STREAM.MSG.GET, the verb the supervisor grants, never DIRECT.GET). OPEN mode (no creds) create-firsts:
|
|
1900
|
-
* `Kvm.open` binds LAZILY — it does NOT verify the stream exists or throw when it's missing (a fresh
|
|
1901
|
-
* bucket then fails 'stream not found' on the first write), so `create` is the ensure-exists call (it
|
|
1902
|
-
* makes the bucket or, when another endpoint already did, throws and we bind the existing one). Either
|
|
1903
|
-
* way the per-KEY CAS create stays the only single-flight gate, so a lost bucket-create race never reads
|
|
1904
|
-
* as "lease held". */
|
|
1905
|
-
private managerLeaseRegistry;
|
|
1906
1805
|
/** Take or keep the per-SPACE daemon-credential renewal lease (#1634), returning whether THIS
|
|
1907
1806
|
* instance now holds it. One atomic CAS `create` per pass: it succeeds for whoever arrives first
|
|
1908
1807
|
* and throws for everyone else, so exactly one manager remints even when several share the
|
|
@@ -1914,7 +1813,6 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
1914
1813
|
/** Release the renewal lease on a clean stop so a peer takes over at once rather than at the TTL.
|
|
1915
1814
|
* CAS-guarded, so a lease we already lost is never deleted out from under its new holder. */
|
|
1916
1815
|
releaseDaemonRenewalLease(): Promise<void>;
|
|
1917
|
-
private encodeDaemonRenewalLease;
|
|
1918
1816
|
/** Read the per-space daemon-credential renewal-lease row (the one {@link holdDaemonRenewalLease}
|
|
1919
1817
|
* CAS-writes), or `undefined` when nothing holds it. A `doctor auth --fix` that lost `hold` calls
|
|
1920
1818
|
* this through the SAME bucket the hold attempt opened, to name the live holder in its refusal —
|
|
@@ -1923,7 +1821,6 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
1923
1821
|
instanceId: string;
|
|
1924
1822
|
since: number;
|
|
1925
1823
|
} | undefined>;
|
|
1926
|
-
private encodeManagerLease;
|
|
1927
1824
|
/** Acquire THIS logical instance's liveness lease via ATOMIC CAS create on its own per-instance key
|
|
1928
1825
|
* ({@link managerLeaseKey}). THROWS only if that SAME instance id already holds a live key (a same-root
|
|
1929
1826
|
* concurrent double-start, or a restart racing the crashed predecessor's not-yet-expired key) — a loud
|
|
@@ -1984,27 +1881,12 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
1984
1881
|
* `live`→`durable` flip is seen by fan-out without a cache-propagation gap (red-team MED-3), and a
|
|
1985
1882
|
* reader just started need not wait for the cache to fill. */
|
|
1986
1883
|
deliveryClassFresh(channel: string): Promise<DeliveryClass>;
|
|
1987
|
-
/**
|
|
1988
|
-
* peer wins; 0 or >1 matches drop (never fan a directed durable copy to an unrelated same-named
|
|
1989
|
-
* bystander — red-team LOW; SPEC §4 unique instance id). */
|
|
1884
|
+
/** Forwards to the durable backstop's {@link EndpointDurableBackstop.resolveOwnerByName}. */
|
|
1990
1885
|
private resolveOwnerByName;
|
|
1991
|
-
/**
|
|
1992
|
-
* lifecycle (`keySuffix`). One message reaches one lifecycle once, whichever membership row and
|
|
1993
|
-
* whichever writer (fan-out or any row's catch-up) produced the copy (#5404), within the stream's
|
|
1994
|
-
* duplicate window. An empty `msg.id` contributes NO msgID (#673, SPEC §4: two `id: ""` posts MUST
|
|
1995
|
-
* NOT collapse to one delivery) — a plain publish, never an empty or salted one — so an id-less
|
|
1996
|
-
* message is at-least-once on the durable plane (a redelivery may reach the member twice; the
|
|
1997
|
-
* receiver already treats each as its own delivery). */
|
|
1886
|
+
/** Forwards to the durable backstop's {@link EndpointDurableBackstop.plane3MsgId}. */
|
|
1998
1887
|
private plane3MsgId;
|
|
1999
|
-
/**
|
|
2000
|
-
* §13.1: fan-out addresses the member row's RECORDED lifecycle, never the alias's current
|
|
2001
|
-
* occupant), idempotent via `Nats-Msg-Id` (`<msgId>:<principal>:<lifecycleUid>`) so a catch-up copy
|
|
2002
|
-
* and a racing fan-out copy collapse, from the same row or from two rows that both cover the post.
|
|
2003
|
-
* The `principal` is the member's owner+actor dot-form. */
|
|
1888
|
+
/** Forwards to the durable backstop's {@link EndpointDurableBackstop.publishDinbox}. */
|
|
2004
1889
|
private publishDinbox;
|
|
2005
|
-
/** The fan-out consumer's delivered stream-seq — the activation-fence upper bound (red-team
|
|
2006
|
-
* BLOCKER-1: the shared fan-out cursor advances independently of the stream frontier). */
|
|
2007
|
-
private fanoutDeliveredSeq;
|
|
2008
1890
|
/**
|
|
2009
1891
|
* Privileged durable-JOIN write (v3: the delivery daemon calls this from its `ctl.delivery` handler
|
|
2010
1892
|
* after validating channel ⊆ the caller's read ACL): capture `joinCursor`, commit a `durable-active`
|
|
@@ -2037,13 +1919,6 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
2037
1919
|
* inside one entry, {@link membershipInAllow}). A leader-served read: the handle is opened without
|
|
2038
1920
|
* direct reads, so a row narrowed before this read began is the row it returns. */
|
|
2039
1921
|
private aclAllows;
|
|
2040
|
-
/** The post-write half of {@link durableJoinFor}'s `aclFence`: keep the row just written (at
|
|
2041
|
-
* `revision`) only on proof that the lifecycle's ACL row still allows the channel, and refuse the
|
|
2042
|
-
* join otherwise. When the ACL row proves the channel is no longer allowed, no row of the lifecycle
|
|
2043
|
-
* on that channel is wanted, so the row goes by its exact key whoever wrote its latest revision.
|
|
2044
|
-
* When the read itself fails, nothing is proven either way, so only this write is taken back: a
|
|
2045
|
-
* later revision belongs to another join of the same lifecycle, which may have been authorized. */
|
|
2046
|
-
private keepRowIfAclAllows;
|
|
2047
1922
|
/** Privileged durable-LEAVE write: tombstone the membership at `leaveCursor = frontier` so the
|
|
2048
1923
|
* backstop denies `seq > leaveCursor` while a pre-leave entry stays deliverable (SPEC §7 interval). */
|
|
2049
1924
|
durableLeaveFor(owner: string, channel: string, lifecycleUid: string, expectedGeneration?: number): Promise<void>;
|
|
@@ -2075,71 +1950,6 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
2075
1950
|
onDeliveryCredsAdopted?: () => void;
|
|
2076
1951
|
startupComplete?: () => boolean;
|
|
2077
1952
|
}): Promise<void>;
|
|
2078
|
-
/** Whether an ALREADY-DISPATCHED unit of Plane-3 work may still take effect.
|
|
2079
|
-
*
|
|
2080
|
-
* Unsubscribing stops NEW work; it cannot recall work already in flight. A handler that entered
|
|
2081
|
-
* before {@link quiescePlane3} and awaited broker I/O inside it resumes AFTER the freeze, and a
|
|
2082
|
-
* reviewer traced the ordering that makes that a split rather than a latency blip: the loser
|
|
2083
|
-
* accepts a unit and awaits, the loser is descheduled, the successor acquires the shard and flips
|
|
2084
|
-
* its lease READY, then the loser resumes and answers or acks for a shard it no longer holds.
|
|
2085
|
-
* Subscription counts and parked-pull readings cannot see it, because the effect is the reply and
|
|
2086
|
-
* the ack rather than the binding.
|
|
2087
|
-
*
|
|
2088
|
-
* So each work path re-asks HERE, at the point of effect, after its awaits and before it acts.
|
|
2089
|
-
* The lease keeps one ROW, not one SERVER; this is the half that keeps one server. An unacked
|
|
2090
|
-
* message is not lost by refusing: a stopped consumer redelivers it to whoever holds the shard
|
|
2091
|
-
* next, which is the same property quiescing already relies on. */
|
|
2092
|
-
private plane3MayAct;
|
|
2093
|
-
/** Serve one runtime durable-membership control request (the server-side delivery daemon). The caller
|
|
2094
|
-
* id is the authenticated subject sender ({@link serveControl} fail-closes on a mismatch). Validation
|
|
2095
|
-
* is against the durable ACL registry — the SAME KV the reader re-auths against (single source of
|
|
2096
|
-
* truth, no in-memory ledger to drift). */
|
|
2097
|
-
private handleDeliveryControl;
|
|
2098
|
-
/** Validate the channel ARG shape only: non-blank, valid, concrete (NO ACL check, that is op-specific).
|
|
2099
|
-
* `family` also admits a channel family such as `review.>` (a membership join or leave, #5404).
|
|
2100
|
-
* Returns the channel on success or a ControlReply error to short-circuit. */
|
|
2101
|
-
private checkDurableChannelArg;
|
|
2102
|
-
/** JOIN requires the channel be within the caller's CURRENT read ACL (you can't durable-subscribe a
|
|
2103
|
-
* channel you may not read). A family must lie inside one ACL entry, so every channel under it is
|
|
2104
|
-
* readable. */
|
|
2105
|
-
private deliveryJoin;
|
|
2106
|
-
/** Whether `lifecycleUid`'s exact ACL row still allows reads, so an inventory of it came from a
|
|
2107
|
-
* caller that did not fence. A row narrowed to no reads, or retired or absent, is fenced. A read
|
|
2108
|
-
* that fails answers true: the caller keeps its in-memory mark, which only ever refuses. */
|
|
2109
|
-
private lifecycleAclUnfenced;
|
|
2110
|
-
/** Run one durable join or leave that writes `principal`'s rows of `lifecycleUid`, refused once that
|
|
2111
|
-
* lifecycle's inventory has been asked for ({@link retiringLifecycles}). The check and the
|
|
2112
|
-
* registration have no await between them, so an inventory either finds this write running and
|
|
2113
|
-
* waits for it, or this write finds the inventory's mark and is refused. */
|
|
2114
|
-
private membershipWrite;
|
|
2115
|
-
/** LEAVE must NOT require current-ACL coverage. Leave fires precisely when the ACL was narrowed/revoked
|
|
2116
|
-
* (a refused live sub → {@link closeRefusedMembership}); gating the tombstone on the current ACL would
|
|
2117
|
-
* loop forever and leave the SPEC §7 boundary open (the membership could resume if the ACL is later
|
|
2118
|
-
* restored). The guards are: authenticated caller (serveControl), concrete channel, a finite generation
|
|
2119
|
-
* (the join epoch — without it a stale/replayed leave could tombstone a newer rejoin), and an EXISTING
|
|
2120
|
-
* own membership; `durableLeaveFor` → `tombstoneMember` then enforces the generation match. */
|
|
2121
|
-
private deliveryLeave;
|
|
2122
|
-
/** Serve one MEDIATED HISTORY READ (`readHistory`, the client side is {@link readHistory}). The daemon
|
|
2123
|
-
* holds the consumer so the caller does not have to: this is a privilege reduction, not a new
|
|
2124
|
-
* capability, and it is the shape SPEC's "Mediated reads (normative)" rule asks for.
|
|
2125
|
-
*
|
|
2126
|
-
* THE ONE INVARIANT THIS METHOD EXISTS FOR: authorization is read FRESH on every call and never
|
|
2127
|
-
* cached across calls. A consumer pins its authorization when it is created, so a revoked caller
|
|
2128
|
-
* keeps being served by a consumer it already holds; re-reading here is what makes a revocation
|
|
2129
|
-
* stop the very NEXT read. Cache this and the verb loses its only advantage over the raw consumer
|
|
2130
|
-
* path.
|
|
2131
|
-
*
|
|
2132
|
-
* AUTHORITY (SPEC §9.6): "current read ACL" is the effective broker-accepted credential. The
|
|
2133
|
-
* durable registry is a live mirror of that credential, not a second grant source. History
|
|
2134
|
-
* authorizes against `allowSubscribe ∩ issuedAllowSubscribe` — the live row (so revocation via
|
|
2135
|
-
* plain commitAcl still stops the next read) intersected with the mint-time ceiling (so a
|
|
2136
|
-
* registry widen without a remint cannot grant what the JWT does not). Raising the ceiling is
|
|
2137
|
-
* {@link reissueAcl}, which is what provision does when it bakes the list into the JWT.
|
|
2138
|
-
*
|
|
2139
|
-
* The caller arrives as an alias (the control subject carries owner+actor, never a uid) and is the
|
|
2140
|
-
* AUTHENTICATED subject sender — `serveControl` has already fail-closed on any payload that names a
|
|
2141
|
-
* different principal, so `caller` cannot be self-asserted. */
|
|
2142
|
-
private deliveryReadHistory;
|
|
2143
1953
|
/** Stop serving Plane-3 WITHOUT tearing down the connection, so a daemon that has just learned its
|
|
2144
1954
|
* lease may no longer be its own can stop acting on the shard while it finds out for certain.
|
|
2145
1955
|
*
|
|
@@ -2175,19 +1985,12 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
2175
1985
|
* That is a readiness lie surviving a transient broker error, the daemon claims a responder it does
|
|
2176
1986
|
* not have, which is the #1318 outage wearing the readiness flag instead of the exit path. */
|
|
2177
1987
|
rearmPlane3(): Promise<void>;
|
|
2178
|
-
/**
|
|
2179
|
-
|
|
2180
|
-
|
|
2181
|
-
* the loops while `durableJoinFor` kept reporting `durable:true` (the impl-review's BLOCKER-1). No-op
|
|
2182
|
-
* unless this endpoint hosts Plane-3 (`this.plane3` set). */
|
|
1988
|
+
/** Forwards to the delivery plane's {@link EndpointDeliveryPlane.plane3MayAct}. */
|
|
1989
|
+
private plane3MayAct;
|
|
1990
|
+
/** Forwards to the delivery plane's {@link EndpointDeliveryPlane.armPlane3}. */
|
|
2183
1991
|
private armPlane3;
|
|
2184
|
-
/**
|
|
2185
|
-
|
|
2186
|
-
* this MUST run on every arm — otherwise durable join/leave/list silently lose their responder after a
|
|
2187
|
-
* broker blip. The stale sub is dropped (unsubscribed + removed from `this.subs`) before re-creating.
|
|
2188
|
-
* `boundReply` is essential here: the daemon holds a wildcard reply-publish grant, so the serve path
|
|
2189
|
-
* must reject any reply target outside the authenticated sender's own subtree (confused-deputy fix). */
|
|
2190
|
-
private armDeliveryControl;
|
|
1992
|
+
/** Forwards to the delivery plane's {@link EndpointDeliveryPlane.pumpDlv}. */
|
|
1993
|
+
private pumpDlv;
|
|
2191
1994
|
/** (Re)bind the anycast take responder and the request records maintenance on the current
|
|
2192
1995
|
* connection (SPEC §8.1). The records bucket is created here as well as at space setup, so a mesh
|
|
2193
1996
|
* that predates it gets one when its daemon restarts at this version. */
|
|
@@ -2212,6 +2015,9 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
2212
2015
|
/** Answer a sender's status or cancel for one of its own requests. The caller is the
|
|
2213
2016
|
* authenticated subject sender, checked against the request's stored subject. */
|
|
2214
2017
|
private deliveryAnycast;
|
|
2018
|
+
/** The peer-readable liveness responders and the probe, of this endpoint. Every dependency is read
|
|
2019
|
+
* when it is used, so a field assigned after construction is seen. */
|
|
2020
|
+
private readonly liveness;
|
|
2215
2021
|
/** Bind this endpoint as the liveness RESPONDER for one plane, answering presence and nothing
|
|
2216
2022
|
* else to any credentialed peer that asks (`live.<plane>.<owner>.<actor>`).
|
|
2217
2023
|
*
|
|
@@ -2254,8 +2060,7 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
2254
2060
|
* the plane answered by the broker's no-responders status while this endpoint is serving. A second
|
|
2255
2061
|
* call for the same plane replaces the first. */
|
|
2256
2062
|
serveLiveness(plane: LivenessPlane, readState: () => Promise<ResponderState> | ResponderState): void;
|
|
2257
|
-
/**
|
|
2258
|
-
* as {@link armDeliveryControl} does. */
|
|
2063
|
+
/** Forwards to the liveness component's {@link EndpointLiveness.bindLiveness}. */
|
|
2259
2064
|
private bindLiveness;
|
|
2260
2065
|
/** Bind the liveness responder for the DELIVERY plane, grading itself from its own shard-0 lease
|
|
2261
2066
|
* through the shared classifier. The daemon is the one process that can answer this honestly: it
|
|
@@ -2283,37 +2088,33 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
2283
2088
|
* The reply rides `<request>.reply.<uuid>`, the sender's own subtree, so the responder's bound
|
|
2284
2089
|
* reply guard accepts it and the responder needs no broad inbox-publish grant to answer. */
|
|
2285
2090
|
probeLiveness(plane: string, timeoutMs?: number): Promise<LivenessAnswer>;
|
|
2286
|
-
/** Grade a failed probe that was NOT a no-responders answer. Both arms return an outcome that
|
|
2287
|
-
* maps to `unknown`; they are told apart so the distinction stays legible at the call site and so
|
|
2288
|
-
* a future caller can render the two differently (a refusal is about YOUR credential, a timeout
|
|
2289
|
-
* is about something being wedged). Neither may ever mean health. */
|
|
2290
|
-
private probeFailureOutcome;
|
|
2291
2091
|
/**
|
|
2292
|
-
* Serve this process's
|
|
2293
|
-
* set about this principal, addressed by its own principal, lifecycle UID
|
|
2294
|
-
*
|
|
2092
|
+
* Serve this process's `agent` endpoint on the principal route (SPEC 13.21, 13.22): the
|
|
2093
|
+
* `AGENT_CLUSTER` command set about this principal, addressed by its own principal, lifecycle UID
|
|
2094
|
+
* and runtime id, with no registration. `handlers` serves the cluster's commands with
|
|
2095
|
+
* `AGENT_CONTRACTS`; `describe` is built in.
|
|
2295
2096
|
*
|
|
2296
2097
|
* Throws on an open mesh and on a static credential, where no row names who may call, without a
|
|
2297
|
-
* lifecycle UID, before the endpoint has started,
|
|
2298
|
-
* cluster
|
|
2299
|
-
* subscribes this process's own subject
|
|
2098
|
+
* lifecycle UID, before the endpoint has started, while it already serves `agent`, for an
|
|
2099
|
+
* `endpoint` or `cluster` field, which this entry point does not take, and for a set of handlers
|
|
2100
|
+
* that is not the cluster's commands with its contracts. It subscribes this process's own subject
|
|
2101
|
+
* with no queue group.
|
|
2300
2102
|
*
|
|
2301
2103
|
* `ready` is a positive check: it resolves only after the broker accepted the subscription
|
|
2302
2104
|
* (subscribe, flush, and no permission violation for that subject), and rejects with the
|
|
2303
2105
|
* refusal, which a credential minted before the rows existed gets. The serve is INTENT: every
|
|
2304
2106
|
* replaced connection subscribes again and runs the check again, and a refusal there ends the
|
|
2305
|
-
* serve, resolves `failed` and clears the presence field. `stop` unsubscribes
|
|
2306
|
-
* handlers in flight.
|
|
2107
|
+
* serve, resolves `failed` and clears the presence field. `stop` unsubscribes, aborts the
|
|
2108
|
+
* handlers' `signal`, and waits for each handler in flight until its request's deadline at most.
|
|
2307
2109
|
*/
|
|
2308
|
-
servePrincipal(
|
|
2309
|
-
endpoint: string;
|
|
2310
|
-
cluster: ClusterDocument;
|
|
2110
|
+
servePrincipal(spec: {
|
|
2311
2111
|
handlers: EpPrincipalCommandDef[];
|
|
2312
2112
|
}): PrincipalServe;
|
|
2313
2113
|
/** Subscribe `intent` on `nc`. */
|
|
2314
2114
|
private bindPrincipalHandle;
|
|
2315
|
-
/** A
|
|
2316
|
-
|
|
2115
|
+
/** A principal-route refusal a call or a serve reports itself: a request publish, a serve
|
|
2116
|
+
* subscription or a reply read. Only a reply publish is left, which no call or serve awaits. */
|
|
2117
|
+
private ownedPrincipalRouteRefusal;
|
|
2317
2118
|
/** Track one binding: a refusal ends the serve, and an accepted subscription on the current
|
|
2318
2119
|
* connection shows the presence field. */
|
|
2319
2120
|
private armPrincipalServe;
|
|
@@ -2327,7 +2128,8 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
2327
2128
|
private endPrincipalServe;
|
|
2328
2129
|
/** Mark `intent` ended and release what it holds in this endpoint and in this process. */
|
|
2329
2130
|
private forgetPrincipalServe;
|
|
2330
|
-
/** Stop serving `intent` and wait for its handlers in flight
|
|
2131
|
+
/** Stop serving `intent` and wait for its handlers in flight, each until its request's deadline
|
|
2132
|
+
* at most. The ending is synchronous, so a
|
|
2331
2133
|
* `ready` still waiting for the broker rejects before the caller's next step. `republish` writes
|
|
2332
2134
|
* presence without the `prompts` field; the endpoint's own stop writes it offline instead. */
|
|
2333
2135
|
private stopPrincipalServe;
|
|
@@ -2336,8 +2138,8 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
2336
2138
|
* prompts it holds `open` or `sent`, and a counter that goes up by one each time a prompt opens or
|
|
2337
2139
|
* changes state. The field shows only while the `agent` endpoint is served and the broker accepted
|
|
2338
2140
|
* its subscription on the current connection. Until this is called it shows `open: 0` with the
|
|
2339
|
-
*
|
|
2340
|
-
* not served, and a RangeError for a `seq` below one this runtime already used.
|
|
2141
|
+
* fresh `seq` the serve took from {@link nextPromptsSeq} when it started. Throws when the `agent`
|
|
2142
|
+
* endpoint is not served, and a RangeError for a `seq` below one this runtime already used.
|
|
2341
2143
|
*/
|
|
2342
2144
|
setPromptsPresence(prompts: PresencePrompts): Promise<void>;
|
|
2343
2145
|
/**
|
|
@@ -2374,52 +2176,6 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
2374
2176
|
};
|
|
2375
2177
|
signal?: AbortSignal;
|
|
2376
2178
|
}): Promise<EndpointReply>;
|
|
2377
|
-
/** Serve one PRIVILEGED delivery-admin request (the D5 rail-split). The cred layer is the caller
|
|
2378
|
-
* boundary — only the supervisor profile can publish here — and `serveControl`'s sender check +
|
|
2379
|
-
* bounded reply still apply on top. `reloadCreds` is the class-2 renewal ADOPTION step: re-read
|
|
2380
|
-
* the renewal-owner-re-signed creds file, pin, swap the live connection, reconnect the membership
|
|
2381
|
-
* feed's rw connection, and reply with proof (identities + the adopted JWT windows) — or a
|
|
2382
|
-
* structured failure (e.g. the file was never re-signed), never a silent partial. */
|
|
2383
|
-
private handleDeliveryAdmin;
|
|
2384
|
-
/** Create one of the daemon's Plane-3 durables. A named create is idempotent for the same config,
|
|
2385
|
-
* and a denial is never taken for existence. The one conflict accepted is this durable as a full
|
|
2386
|
-
* restore recreated it, starting after its recorded ACK floor ({@link isRestoredConsumer}); every
|
|
2387
|
-
* other failure propagates. */
|
|
2388
|
-
private addPlane3Durable;
|
|
2389
|
-
/** Fan-out loop: bind the privileged `fanout` durable on CHAT and route each message (routing only —
|
|
2390
|
-
* the trusted reader is the auth gate). */
|
|
2391
|
-
private runFanout;
|
|
2392
|
-
/** Route ONE chat message to eligible owners' mixed inboxes. `durable` channel → its `durable-active`
|
|
2393
|
-
* members within interval; `live` channel → `@mention` targets authorized to read it (ACL only).
|
|
2394
|
-
* On either class, a mention of an agent whose read ACL excludes the channel is reported to the
|
|
2395
|
-
* sender with a mention notice. Members KV is scanned FRESH per message (no cache — red-team
|
|
2396
|
-
* BLOCKER-1 catch-up correctness). */
|
|
2397
|
-
private fanOutMessage;
|
|
2398
|
-
private deliveryLimitRead?;
|
|
2399
|
-
/** The DLV count the trusted writer stamps on a copy (SPEC §8): the stream's `max_msgs_per_subject`,
|
|
2400
|
-
* read at most {@link DELIVERY_LIMIT_READ_MS} before the write, as a whole number or `none`. */
|
|
2401
|
-
private deliveryLimitStamp;
|
|
2402
|
-
/** Trusted-reader loop: bind the single privileged `reader` durable over `dinbox.>` and re-authorize
|
|
2403
|
-
* + transfer each entry. */
|
|
2404
|
-
private runReader;
|
|
2405
|
-
/** Whether one of the lifecycle's rows covering concrete `channel`, the channel's own or a family
|
|
2406
|
-
* above it, is eligible for the post at `seq`. One exact read per row, the channel's own first. */
|
|
2407
|
-
private lifecycleCoversPost;
|
|
2408
|
-
/** Remove a retired lifecycle's member row for `channel`, when one exists. Best effort: the row
|
|
2409
|
-
* authorizes nothing (its ACL row is retired), and the next entry fan-out writes against it
|
|
2410
|
-
* brings the reader back here. */
|
|
2411
|
-
private removeRetiredMemberRow;
|
|
2412
|
-
/** Re-authorize ONE mixed-inbox entry and transfer it to the owner's DELIVER store. Deny (drop) on a
|
|
2413
|
-
* revoked/narrowed ACL or out-of-interval seq; on transfer success, ack the mixed entry (durability
|
|
2414
|
-
* has moved to DLV — an §8 equivalent per-member at-least-once mechanism). The agent acks DLV. */
|
|
2415
|
-
private readerHandle;
|
|
2416
|
-
/** Agent-side: bind + pump our pre-created Plane-3 DELIVER durable (`dlv_<id>`). Every message here is
|
|
2417
|
-
* delivery-daemon-written (DLV is delivery-write-only, broker-enforced) and is a CHANNEL message by contract
|
|
2418
|
-
* (the backstop never carries DMs), so `kind=channel` is path-derived (SPEC §4) and the body is
|
|
2419
|
-
* trusted (no spoof-guard). `durable:true` — real JetStream ack, coalesced with the core-sub live
|
|
2420
|
-
* copy by `MeshAgent.ingest`. No-op when the durable isn't present (open mode / not provisioned). A read
|
|
2421
|
-
* list declared on a credential that cannot fetch the durable refuses. */
|
|
2422
|
-
private pumpDlv;
|
|
2423
2179
|
/** Agent-side: request a Plane-3 durable backstop for a channel via the server-side delivery daemon (ctl.delivery). Throws
|
|
2424
2180
|
* when no privileged writer is present (open / no delivery daemon). 30s timeout — activation catch-up may
|
|
2425
2181
|
* run before the reply (the window is small, but a busy channel can take more than the 5s default). */
|
|
@@ -2586,7 +2342,6 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
2586
2342
|
* calls must be serial — every reader here awaits to completion, so they are.
|
|
2587
2343
|
*/
|
|
2588
2344
|
private collectHistory;
|
|
2589
|
-
private collectHistoryInner;
|
|
2590
2345
|
/** Read a channel's retained history up to `upToSeq` (the join frontier) and emit each message
|
|
2591
2346
|
* as a `historical` "message" event. `sinceMs` bounds how far back via a native consumer
|
|
2592
2347
|
* `start_time` (now − window); unset ⇒ the full retained window. `floorSeq`, when set, is a
|
|
@@ -2674,13 +2429,10 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
2674
2429
|
/** {@link EndpointOptions.readOnce}: fill the roster from one read of the presence bucket. Stale
|
|
2675
2430
|
* and offline records resolve as they do in a watch's initial replay. */
|
|
2676
2431
|
private readPresenceOnce;
|
|
2677
|
-
/**
|
|
2678
|
-
* cache. A failed bind throws out of connect; an entry that does not decode or validate is
|
|
2679
|
-
* reported as a `warning` and dropped, so its channel resolves to the default policy. */
|
|
2432
|
+
/** Forwards to the channel discovery component's {@link EndpointChannelDiscovery.startChannelWatch}. */
|
|
2680
2433
|
private startChannelWatch;
|
|
2681
|
-
/**
|
|
2434
|
+
/** Forwards to the channel discovery component's {@link EndpointChannelDiscovery.readChannelsOnce}. */
|
|
2682
2435
|
private readChannelsOnce;
|
|
2683
|
-
private handleChannelEntry;
|
|
2684
2436
|
private sweep;
|
|
2685
2437
|
}
|
|
2686
2438
|
/** SPEC §5 on receive: a delivery comes from the principal its subject names. The payload is an
|