@cotal-ai/core 0.171.3 → 0.171.5

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.
Files changed (43) hide show
  1. package/dist/control-exchange.d.ts.map +1 -1
  2. package/dist/control-exchange.js +3 -4
  3. package/dist/control-exchange.js.map +1 -1
  4. package/dist/endpoint-anycast.d.ts +110 -0
  5. package/dist/endpoint-anycast.d.ts.map +1 -0
  6. package/dist/endpoint-anycast.js +316 -0
  7. package/dist/endpoint-anycast.js.map +1 -0
  8. package/dist/endpoint-connection.d.ts +363 -0
  9. package/dist/endpoint-connection.d.ts.map +1 -0
  10. package/dist/endpoint-connection.js +741 -0
  11. package/dist/endpoint-connection.js.map +1 -0
  12. package/dist/endpoint-consumers.d.ts +147 -0
  13. package/dist/endpoint-consumers.d.ts.map +1 -0
  14. package/dist/endpoint-consumers.js +459 -0
  15. package/dist/endpoint-consumers.js.map +1 -0
  16. package/dist/endpoint-dial.d.ts +3 -1
  17. package/dist/endpoint-dial.d.ts.map +1 -1
  18. package/dist/endpoint-dial.js +5 -2
  19. package/dist/endpoint-dial.js.map +1 -1
  20. package/dist/endpoint-durable.d.ts +82 -0
  21. package/dist/endpoint-durable.d.ts.map +1 -0
  22. package/dist/endpoint-durable.js +164 -0
  23. package/dist/endpoint-durable.js.map +1 -0
  24. package/dist/endpoint-principal-serve.d.ts +110 -0
  25. package/dist/endpoint-principal-serve.d.ts.map +1 -0
  26. package/dist/endpoint-principal-serve.js +233 -0
  27. package/dist/endpoint-principal-serve.js.map +1 -0
  28. package/dist/endpoint-reconnect.d.ts +129 -0
  29. package/dist/endpoint-reconnect.d.ts.map +1 -0
  30. package/dist/endpoint-reconnect.js +166 -0
  31. package/dist/endpoint-reconnect.js.map +1 -0
  32. package/dist/endpoint.d.ts +44 -241
  33. package/dist/endpoint.d.ts.map +1 -1
  34. package/dist/endpoint.js +403 -1740
  35. package/dist/endpoint.js.map +1 -1
  36. package/dist/launch-artifacts.d.ts.map +1 -1
  37. package/dist/launch-artifacts.js +17 -9
  38. package/dist/launch-artifacts.js.map +1 -1
  39. package/dist/websocket-dial.d.ts +9 -0
  40. package/dist/websocket-dial.d.ts.map +1 -0
  41. package/dist/websocket-dial.js +121 -0
  42. package/dist/websocket-dial.js.map +1 -0
  43. package/package.json +1 -1
@@ -0,0 +1,741 @@
1
+ // The connection bind and teardown of CotalEndpoint, as an internal component: open a connection and bind
2
+ // everything that hangs off it, clear the connection-scoped state, close a failed bind, tear down a bind
3
+ // that lost a race with stop, stop the endpoint, and report its native connections. Moved verbatim from
4
+ // endpoint.ts; the endpoint keeps connectAndBind, the supervisor and the retry loop and forwards to these.
5
+ // Not re-exported by the index.
6
+ import { requireBrokerFloor } from "./broker-floor.js";
7
+ import { openChannelRegistry } from "./channels.js";
8
+ import { drainAndClose } from "./connection-cleanup.js";
9
+ import { withDeadline } from "./deadline.js";
10
+ import { bearerRenewalDeadlineMs, RepeatedRefusal, dialerFor, authOpts } from "./endpoint-dial.js";
11
+ import { credsRenewalDelayMs, credsClaims } from "./identity.js";
12
+ import { importNativeSubjectPermissions, readAcceptedRow } from "./issued-authority.js";
13
+ import { nativeConnectionBinding } from "./native-connection.js";
14
+ import { nextHeartbeat } from "./presence-heartbeat.js";
15
+ import { PRESENCE_STORAGE } from "./streams.js";
16
+ import { presenceBucket, dmStream, dmDurable } from "./subjects.js";
17
+ import { jetstream, jetstreamManager } from "@nats-io/jetstream";
18
+ import { Kvm } from "@nats-io/kv";
19
+ /** One endpoint's connection bind and teardown. Internal: `CotalEndpoint` keeps the fields, connectAndBind,
20
+ * the supervisor and the retry loop, and forwards to it. */
21
+ export class EndpointConnection {
22
+ deps;
23
+ constructor(deps) {
24
+ this.deps = deps;
25
+ }
26
+ get bearerSource() { return this.deps.bearerSource(); }
27
+ get currentBearer() { return this.deps.currentBearer(); }
28
+ get bearerRenewalFailures() { return this.deps.bearerRenewalFailures(); }
29
+ get bearerAdoptedAtMs() { return this.deps.bearerAdoptedAtMs(); }
30
+ get credsSource() { return this.deps.credsSource(); }
31
+ get currentCreds() { return this.deps.currentCreds(); }
32
+ get userMode() { return this.deps.userMode(); }
33
+ get bearerRefusalSurfaced() { return this.deps.bearerRefusalSurfaced(); }
34
+ set bearerRefusalSurfaced(value) { this.deps.setBearerRefusalSurfaced(value); }
35
+ get nc() { return this.deps.nc(); }
36
+ set nc(value) { this.deps.setNc(value); }
37
+ get servers() { return this.deps.servers(); }
38
+ get connId() { return this.deps.connId(); }
39
+ get card() { return this.deps.card(); }
40
+ get transportPingIntervalMs() { return this.deps.transportPingIntervalMs(); }
41
+ get transportMaxPingOut() { return this.deps.transportMaxPingOut(); }
42
+ get transportConnectTimeoutMs() { return this.deps.transportConnectTimeoutMs(); }
43
+ get token() { return this.deps.token(); }
44
+ get user() { return this.deps.user(); }
45
+ get pass() { return this.deps.pass(); }
46
+ get sentinelCreds() { return this.deps.sentinelCreds(); }
47
+ get tls() { return this.deps.tls(); }
48
+ get watchDeletePermissions() { return this.deps.watchDeletePermissions(); }
49
+ get ownedConnections() { return this.deps.ownedConnections(); }
50
+ get onConnection() { return this.deps.onConnection(); }
51
+ get js() { return this.deps.js(); }
52
+ set js(value) { this.deps.setJs(value); }
53
+ get dmOnly() { return this.deps.dmOnly(); }
54
+ get beforeBind() { return this.deps.beforeBind(); }
55
+ get stopped() { return this.deps.stopped(); }
56
+ set stopped(value) { this.deps.setStopped(value); }
57
+ get acceptedToken() { return this.deps.acceptedToken(); }
58
+ get space() { return this.deps.space(); }
59
+ get owner() { return this.deps.owner(); }
60
+ get actor() { return this.deps.actor(); }
61
+ get issuedGeneration() { return this.deps.issuedGeneration(); }
62
+ set issuedGeneration(value) { this.deps.setIssuedGeneration(value); }
63
+ get doWatch() { return this.deps.doWatch(); }
64
+ get doRegister() { return this.deps.doRegister(); }
65
+ get kv() { return this.deps.kv(); }
66
+ set kv(value) { this.deps.setKv(value); }
67
+ get authed() { return this.deps.authed(); }
68
+ get ttlMs() { return this.deps.ttlMs(); }
69
+ get readOnce() { return this.deps.readOnce(); }
70
+ get sweepTimer() { return this.deps.sweepTimer(); }
71
+ set sweepTimer(value) { this.deps.setSweepTimer(value); }
72
+ get doWatchChannels() { return this.deps.doWatchChannels(); }
73
+ get doConsume() { return this.deps.doConsume(); }
74
+ get channelKv() { return this.deps.channelKv(); }
75
+ set channelKv(value) { this.deps.setChannelKv(value); }
76
+ get readsChannelsOnDemand() { return this.deps.readsChannelsOnDemand(); }
77
+ get deliveryLease() { return this.deps.deliveryLease(); }
78
+ get jsm() { return this.deps.jsm(); }
79
+ set jsm(value) { this.deps.setJsm(value); }
80
+ get heartbeatMs() { return this.deps.heartbeatMs(); }
81
+ get heartbeatTimer() { return this.deps.heartbeatTimer(); }
82
+ set heartbeatTimer(value) { this.deps.setHeartbeatTimer(value); }
83
+ get livenessResponders() { return this.deps.livenessResponders(); }
84
+ get taps() { return this.deps.taps(); }
85
+ get activeGoalFollowers() { return this.deps.activeGoalFollowers(); }
86
+ get authExpiryReconnectTimer() { return this.deps.authExpiryReconnectTimer(); }
87
+ set authExpiryReconnectTimer(value) { this.deps.setAuthExpiryReconnectTimer(value); }
88
+ get streamMsgs() { return this.deps.streamMsgs(); }
89
+ get presenceEpoch() { return this.deps.presenceEpoch(); }
90
+ set presenceEpoch(value) { this.deps.setPresenceEpoch(value); }
91
+ get presence() { return this.deps.presence(); }
92
+ get channelWatchIter() { return this.deps.channelWatchIter(); }
93
+ set channelWatchIter(value) { this.deps.setChannelWatchIter(value); }
94
+ get chatSubs() { return this.deps.chatSubs(); }
95
+ get chatSubDenied() { return this.deps.chatSubDenied(); }
96
+ get ownWatchDeletePrefixes() { return this.deps.ownWatchDeletePrefixes(); }
97
+ get channelConfigs() { return this.deps.channelConfigs(); }
98
+ get channelDefaults() { return this.deps.channelDefaults(); }
99
+ set channelDefaults(value) { this.deps.setChannelDefaults(value); }
100
+ get channelRead() { return this.deps.channelRead(); }
101
+ set channelRead(value) { this.deps.setChannelRead(value); }
102
+ get channelReadGeneration() { return this.deps.channelReadGeneration(); }
103
+ set channelReadGeneration(value) { this.deps.setChannelReadGeneration(value); }
104
+ get channelReadApplied() { return this.deps.channelReadApplied(); }
105
+ set channelReadApplied(value) { this.deps.setChannelReadApplied(value); }
106
+ get membershipFeedWatches() { return this.deps.membershipFeedWatches(); }
107
+ get membersKv() { return this.deps.membersKv(); }
108
+ set membersKv(value) { this.deps.setMembersKv(value); }
109
+ get aclKv() { return this.deps.aclKv(); }
110
+ set aclKv(value) { this.deps.setAclKv(value); }
111
+ get membershipFeedKv() { return this.deps.membershipFeedKv(); }
112
+ set membershipFeedKv(value) { this.deps.setMembershipFeedKv(value); }
113
+ get managerLeaseKv() { return this.deps.managerLeaseKv(); }
114
+ set managerLeaseKv(value) { this.deps.setManagerLeaseKv(value); }
115
+ get daemonRenewalLeaseRevision() { return this.deps.daemonRenewalLeaseRevision(); }
116
+ set daemonRenewalLeaseRevision(value) { this.deps.setDaemonRenewalLeaseRevision(value); }
117
+ get deliveryPlane() { return this.deps.deliveryPlane(); }
118
+ get subs() { return this.deps.subs(); }
119
+ get principalServes() { return this.deps.principalServes(); }
120
+ get membershipPauses() { return this.deps.membershipPauses(); }
121
+ get cancelBearerRenewal() { return this.deps.cancelBearerRenewal(); }
122
+ get credsTimer() { return this.deps.credsTimer(); }
123
+ get dmOnlyInFlight() { return this.deps.dmOnlyInFlight(); }
124
+ get rebuildPromise() { return this.deps.rebuildPromise(); }
125
+ get startPromise() { return this.deps.startPromise(); }
126
+ get reconnecting() { return this.deps.reconnecting(); }
127
+ get credsTxnsRunning() { return this.deps.credsTxnsRunning(); }
128
+ get residentSwap() { return this.deps.residentSwap(); }
129
+ get nativeBound() { return this.deps.nativeBound(); }
130
+ refreshBearer(initial) { return this.deps.refreshBearer(initial); }
131
+ refreshCreds(initial) { return this.deps.refreshCreds(initial); }
132
+ bearerForWire() { return this.deps.bearerForWire(); }
133
+ presentCreds() { return this.deps.presentCreds(); }
134
+ presentBearer() { return this.deps.presentBearer(); }
135
+ armAuthExpiryReconnectFence(nc) { return this.deps.armAuthExpiryReconnectFence(nc); }
136
+ watchStatus() { return this.deps.watchStatus(); }
137
+ bindDmOnly(mode) { return this.deps.bindDmOnly(mode); }
138
+ requireLifecycleUid(what) { return this.deps.requireLifecycleUid(what); }
139
+ readPresenceOnce() { return this.deps.readPresenceOnce(); }
140
+ startPresenceWatch() { return this.deps.startPresenceWatch(); }
141
+ sweep() { return this.deps.sweep(); }
142
+ readChannelsOnce() { return this.deps.readChannelsOnce(); }
143
+ startChannelWatch() { return this.deps.startChannelWatch(); }
144
+ readChannels() { return this.deps.readChannels(); }
145
+ bindDeliveryLeaseWatch() { return this.deps.bindDeliveryLeaseWatch(); }
146
+ ensureStreams() { return this.deps.ensureStreams(); }
147
+ startConsumers() { return this.deps.startConsumers(); }
148
+ publishPresence() { return this.deps.publishPresence(); }
149
+ emitRecoverable(err) { return this.deps.emitRecoverable(err); }
150
+ rearmMembershipWatches() { return this.deps.rearmMembershipWatches(); }
151
+ armPlane3() { return this.deps.armPlane3(); }
152
+ bindLiveness(plane) { return this.deps.bindLiveness(plane); }
153
+ rebindPrincipalServes(reconnected) { return this.deps.rebindPrincipalServes(reconnected); }
154
+ bindTap(tap) { return this.deps.bindTap(tap); }
155
+ retireKvWatch(iter) { return this.deps.retireKvWatch(iter); }
156
+ stopDeliveryLeaseWatch() { return this.deps.stopDeliveryLeaseWatch(); }
157
+ disarmMembershipWatch(watch) { return this.deps.disarmMembershipWatch(watch); }
158
+ disableLibraryReconnect(nc) { return this.deps.disableLibraryReconnect(nc); }
159
+ dropAnycastRequests() { return this.deps.dropAnycastRequests(); }
160
+ closeWithoutLibraryReconnect(nc) { return this.deps.closeWithoutLibraryReconnect(nc); }
161
+ stopPrincipalServe(intent, republish) { return this.deps.stopPrincipalServe(intent, republish); }
162
+ kickBackoff() { return this.deps.kickBackoff(); }
163
+ deleteRetainedMembershipConsumer(watch) { return this.deps.deleteRetainedMembershipConsumer(watch); }
164
+ settleDeliveryLeaseWatches() { return this.deps.settleDeliveryLeaseWatches(); }
165
+ settleKvWatches() { return this.deps.settleKvWatches(); }
166
+ clearPresenceWriteFailure() { return this.deps.clearPresenceWriteFailure(); }
167
+ emit(event, ...args) { return this.deps.emit(event, ...args); }
168
+ async bindConnection() {
169
+ this.clearConnectionScoped();
170
+ // Bearer-source endpoints fetch before the FIRST connect, and renew first on a rebuild whose
171
+ // cached token is past its renewal window (a rebuild after a long outage would otherwise
172
+ // present a dead bearer). While renewals are failing, their retry timer owns the source: a
173
+ // fetch here too would add one call to the exchange per rebuild attempt.
174
+ if (this.bearerSource) {
175
+ if (!this.currentBearer)
176
+ await this.refreshBearer(true);
177
+ else if (this.bearerRenewalFailures === 0 && Date.now() >= bearerRenewalDeadlineMs(this.currentBearer, this.bearerAdoptedAtMs))
178
+ await this.refreshBearer();
179
+ }
180
+ // Creds-source endpoints likewise fetch before the FIRST connect, and re-fetch on a rebuild
181
+ // whose cached cred is expired or inside its renewal window.
182
+ if (this.credsSource) {
183
+ const stale = !this.currentCreds || credsRenewalDelayMs(this.currentCreds) <= 0;
184
+ if (stale)
185
+ await this.refreshCreds(!this.currentCreds);
186
+ }
187
+ // Never dial with material we can already prove is dead. The refresh above is best-effort (a
188
+ // failed renewal emits and retries rather than throwing, so a dead auth service does not
189
+ // instantly drop a still-live mesh), which used to leave the connect below presenting an
190
+ // EXPIRED bearer: a guaranteed denial that still costs a full auth-callout round trip, repeated
191
+ // by the reestablish loop at a flat rate for as long as the process lives. Refuse here instead.
192
+ // The loop's capped backoff paces the retries and re-enters this method, and a renewal that
193
+ // starts working ends its wait; an endpoint with no bearer source cannot renew at all, and says
194
+ // so. The refusal is surfaced once per outage: the loop retries a repeat without a notice.
195
+ if (this.userMode) {
196
+ try {
197
+ this.bearerForWire();
198
+ this.bearerRefusalSurfaced = false;
199
+ }
200
+ catch (e) {
201
+ if (!this.bearerRefusalSurfaced) {
202
+ this.bearerRefusalSurfaced = true;
203
+ throw e;
204
+ }
205
+ throw new RepeatedRefusal(e.message);
206
+ }
207
+ }
208
+ // The CREDS refusal is NOT repeated here. It lives on the supply itself ({@link credsForWire}),
209
+ // which the authenticator below re-reads per attempt, so it covers this dial AND the reconnects
210
+ // nats.js runs on its own. Raising it early here too would only duplicate it on the one path
211
+ // that was already covered, and a fourth dial site added later would silently miss the copy.
212
+ // The refusal still surfaces on this path: the authenticator throws during the CONNECT, the
213
+ // library closes that attempt, and the reestablish loop's capped backoff re-enters here — where
214
+ // the source re-fetch above is what recovers a renewable endpoint.
215
+ let watchDeletePermission;
216
+ this.nc = await dialerFor(this.servers)({
217
+ servers: this.servers,
218
+ // Keep native failures without eagerly capturing a request-origin stack on every operation.
219
+ noAsyncTraces: true,
220
+ // In USER MODE the connection `name` carries the client-chosen inbox nonce (= connId) the callout
221
+ // scopes `_INBOX_<connId>.>` on (see EndpointOptions.bearer); otherwise it's the display handle.
222
+ name: this.userMode ? this.connId : `cotal:${this.card.name}`,
223
+ // Per-CONNECTION inbox namespace (the "Private Inbox" pattern), keyed on the connection nkey
224
+ // (NOT the owner+actor principal): the reply inbox is per-connection plumbing, and under the auth
225
+ // callout the principal is unknown to the client pre-connect (owner is derived server-side) while
226
+ // the connection id always is. nats.js routes ALL generated inboxes — request replies, JetStream
227
+ // pull delivery, kv.watch ordered-consumer delivery — through this prefix. Paired with
228
+ // sub.allow=[_INBOX_<connId>.>] it stops a peer from subscribing the wildcard inbox to sniff
229
+ // others' DM deliveries. Set unconditionally so the prefix can never drift from the ACL.
230
+ inboxPrefix: `_INBOX_${this.connId}`,
231
+ ...(this.transportPingIntervalMs === undefined ? {} : { pingInterval: this.transportPingIntervalMs }),
232
+ ...(this.transportMaxPingOut === undefined ? {} : { maxPingOut: this.transportMaxPingOut }),
233
+ ...(this.transportConnectTimeoutMs === undefined ? {} : { timeout: this.transportConnectTimeoutMs }),
234
+ // The bearer rides the CHECKED getter: nats.js re-evaluates the token authenticator per
235
+ // (re)connect attempt, so internal reconnects present whatever refreshBearer last fetched,
236
+ // and refuse a token that has expired since, as the creds getter does.
237
+ // Creds ALWAYS ride the CHECKED getter, renewed or static, so every attempt — including the
238
+ // reconnects nats.js performs on its own (the one the broker forces at JWT `exp`, and a dial
239
+ // loop from an earlier drop that crosses `exp` mid-retry) — re-reads a credential that has
240
+ // just been proven unexpired rather than whatever the cache happens to hold.
241
+ // The gate is `!== undefined`, NOT truthiness. An EMPTY creds string is a caller that meant to
242
+ // authenticate and supplied nothing; on a truthiness gate it fell through to `creds: undefined`
243
+ // and dialed ANONYMOUSLY, so the broker answered `Authorization Violation` and the real fault
244
+ // (an empty credential) was never named. Routing it into the checked getter fails it loud
245
+ // instead. Anonymous access stays reachable the only way it should be: by passing no creds.
246
+ ...authOpts({ token: this.token, user: this.user, pass: this.pass, creds: this.currentCreds !== undefined || this.credsSource ? () => this.presentCreds() : undefined, bearer: this.userMode ? () => this.presentBearer() : undefined, sentinelCreds: this.sentinelCreds, tls: this.tls,
247
+ onCreds: (creds) => {
248
+ watchDeletePermission = undefined;
249
+ try {
250
+ const nats = credsClaims(creds).nats;
251
+ if (nats?.pub !== undefined)
252
+ watchDeletePermission = importNativeSubjectPermissions({ pub: nats.pub }).publish;
253
+ }
254
+ catch {
255
+ // Unknown/malformed claims cannot prove a denial. Keep the existing broker check.
256
+ }
257
+ },
258
+ }),
259
+ });
260
+ // SPEC §13.12: the control surface requires nats-server >= 2.12; this runs on every
261
+ // fresh connection, including the reconnects the library performs on its own here.
262
+ this.watchDeletePermissions.set(this.nc, () => watchDeletePermission);
263
+ this.ownedConnections.add(this.nc);
264
+ const owned = this.nc;
265
+ void owned.closed().then(() => this.ownedConnections.delete(owned));
266
+ this.onConnection?.(this.nc);
267
+ requireBrokerFloor(this.nc);
268
+ this.armAuthExpiryReconnectFence(this.nc);
269
+ this.watchStatus();
270
+ this.js = jetstream(this.nc);
271
+ // DM-only (EndpointOptions.dmOnly): the own DM durable is the whole binding. Nothing below runs:
272
+ // no accepted-row read, presence, channel registry, JetStream manager, lease, membership,
273
+ // Plane-3 or liveness responder, so the credential needs no row for any of them.
274
+ if (this.dmOnly) {
275
+ await this.beforeBind?.();
276
+ if (this.stopped)
277
+ return;
278
+ await this.bindDmOnly(this.dmOnly);
279
+ if (this.stopped)
280
+ return;
281
+ this.emit("connection", { connected: true });
282
+ return;
283
+ }
284
+ // Discovery of the issued generation (SPEC 13.15): the ISSUER wrote the accepted reference
285
+ // under the token this launch was handed; the broker admits the read only under this
286
+ // connection's own per-key grant. What comes back must name this incarnation, and a fresh
287
+ // connection re-reads it: the generation is bound to the credential the transport presented,
288
+ // never to a file that may have been replaced under it.
289
+ if (this.acceptedToken !== undefined) {
290
+ const ref = await readAcceptedRow(this.nc, this.space, this.acceptedToken);
291
+ const uid = this.requireLifecycleUid("an issued endpoint");
292
+ if (ref.owner !== this.owner || ref.actor !== this.actor || ref.uid !== uid)
293
+ throw new Error(`the accepted row names ${ref.owner}.${ref.actor} (uid ${ref.uid}), not this endpoint ${this.owner}.${this.actor} (uid ${uid}); refusing to ride a foreign issuance (SPEC 13.15)`);
294
+ this.issuedGeneration = ref.generation;
295
+ }
296
+ await this.beforeBind?.();
297
+ if (this.stopped)
298
+ return;
299
+ if (this.doWatch || this.doRegister) {
300
+ const kvm = new Kvm(this.nc);
301
+ // The presence bucket is a JetStream stream. Open mode lazily creates it; auth mode
302
+ // OPENs it (it's pre-created at `cotal up`; KV stream-create is denied to agents).
303
+ this.kv = this.authed
304
+ ? await kvm.open(presenceBucket(this.space))
305
+ : await kvm.create(presenceBucket(this.space), { ttl: this.ttlMs, storage: PRESENCE_STORAGE });
306
+ }
307
+ if (this.doWatch && this.readOnce)
308
+ await this.readPresenceOnce();
309
+ else if (this.doWatch) {
310
+ await this.startPresenceWatch();
311
+ this.sweepTimer = setInterval(() => this.sweep(), Math.max(500, Math.floor(this.ttlMs / 3)));
312
+ }
313
+ // Open the channel registry bucket when we either watch it (live cache for the connector's
314
+ // pull/display) or consume (the join-time replay decision reads it fresh). A presence-only
315
+ // supervisor (watchChannels:false, consume:false) skips it entirely — it needs no channel cache,
316
+ // so its scoped cred holds no channel-registry read (residual 2). Auth mode OPENs the bucket
317
+ // pre-created at `cotal up`; open mode lazily creates it.
318
+ const watchChannels = this.doWatch && this.doWatchChannels;
319
+ if (watchChannels || this.doConsume) {
320
+ this.channelKv = await openChannelRegistry(this.nc, this.space, { create: !this.authed });
321
+ if (watchChannels)
322
+ await (this.readOnce ? this.readChannelsOnce() : this.startChannelWatch());
323
+ // A seat reads the registry on demand, as it reads the roster; this first read fills the cache
324
+ // its boot briefing renders from.
325
+ else if (this.readsChannelsOnDemand)
326
+ await this.readChannels();
327
+ }
328
+ // Rebind the daemon's lease-loss watch onto the fresh connection (#1596). The intent survived
329
+ // clearConnectionScoped; a bind that completes after a stop or another rebuild finds the epoch
330
+ // moved and retires itself. The replay re-delivers the row's current state, so a change that
331
+ // landed in the null window still reaches the trigger.
332
+ if (this.deliveryLease.hasWatchIntent)
333
+ await this.bindDeliveryLeaseWatch();
334
+ // FAIL BEFORE PRESENCE (SPEC 13.1): an AUTHED endpoint that will register on the roster or
335
+ // bind lifecycle-keyed consumers must hold its launcher-supplied lifecycle uid BEFORE anything
336
+ // makes it visible - a missing uid must never leave a roster ghost that could not bind (false
337
+ // readiness). Non-registering, non-consuming infra endpoints (a provisioner window, the
338
+ // delivery daemon, one-shot CLI probes) bind no lifecycle-keyed names and stay outside the
339
+ // rule; open/token mode self-minted at construction, so this only ever throws for a
340
+ // mis-launched AUTH endpoint.
341
+ if (this.authed && (this.doConsume || this.doRegister))
342
+ this.requireLifecycleUid(this.doConsume ? "an authed consuming endpoint" : "an authed presence-registering endpoint");
343
+ // Consumers bind BEFORE presence publishes: the durable bind is the broker's proof that this
344
+ // incarnation's lifecycle-keyed names match its minted grants, so a wrong-uid launch dies
345
+ // with NO presence ghost instead of advertising an agent that can never receive.
346
+ if (this.doConsume) {
347
+ this.jsm = await jetstreamManager(this.nc);
348
+ // Open mode: lazily create the streams on the first endpoint. Auth mode: they are
349
+ // pre-created at `cotal up` and STREAM.CREATE is denied to agents, so skip.
350
+ if (!this.authed)
351
+ await this.ensureStreams();
352
+ await this.startConsumers();
353
+ }
354
+ // The register-only broker proof: a consuming agent proved its lifecycle by binding a
355
+ // durable above, but an authed AGENT that only REGISTERS presence (consume:false) has bound
356
+ // nothing yet, so a wrong-but-valid uid would grammar-pass requireLifecycleUid and then
357
+ // advertise a ghost that can receive nothing. Prove the incarnation at the broker FIRST — an
358
+ // exact info on this agent's own pre-provisioned dm_<owner>-<actor>-<uid> durable (the
359
+ // manager/self-provision minted it under the SAME uid). A wrong uid names a durable that
360
+ // does not exist, so the info throws and presence never publishes. Only for `kind: "agent"`
361
+ // (a peer on the roster); pure `kind: "endpoint"` infra (manager, delivery, feedback intake)
362
+ // holds no dm_ durable and stays exempt.
363
+ if (this.doRegister && !this.doConsume && this.authed && this.card.kind === "agent") {
364
+ const jsm = this.jsm ?? (this.jsm = await jetstreamManager(this.nc));
365
+ const uid = this.requireLifecycleUid("an authed presence-registering agent");
366
+ try {
367
+ await jsm.consumers.info(dmStream(this.space), dmDurable(this.owner, this.actor, uid));
368
+ }
369
+ catch (e) {
370
+ throw new Error(`lifecycle proof failed for ${this.card.id} (uid ${uid}): its dm_ durable is not present at the broker, so this incarnation's uid does not match its provisioned resources - refusing to publish presence (SPEC 13.1 fail-before-presence): ${e?.message ?? String(e)}`);
371
+ }
372
+ }
373
+ if (this.doRegister) {
374
+ // #1356: this await is bounded already — a refused presence write returns no response at all,
375
+ // so it surfaces as the JetStream request TIMEOUT (~5s), once, with no retry here. What it did
376
+ // NOT do was say what failed: the bare `timeout` names no bucket, no space and no subsystem,
377
+ // and a launcher that catches it has nothing to act on. The lifecycle-proof failure a few lines
378
+ // above throws a fully explanatory message; this one is held to the same standard. Still fails
379
+ // rather than degrading — SPEC 13.1 fail-before-presence means a registering agent that cannot
380
+ // publish presence must not come up as though it had.
381
+ try {
382
+ await this.publishPresence();
383
+ }
384
+ catch (e) {
385
+ const detail = e?.message ?? String(e);
386
+ throw new Error(`presence registration failed for ${this.card.id}: the space's presence KV bucket "${presenceBucket(this.space)}" did not accept this endpoint's first write (${detail}). The bucket can be OPENED and WATCHED while refusing every write, so a healthy-looking connection does not rule this out; a broker whose store has latched refuses until it is restarted, and no client can clear it (#1356).`);
387
+ }
388
+ // Beat at this endpoint's own phase. A repeating timer re-arms from the instant its callback
389
+ // ran, and every timer run in one timers pass re-arms to the same instant, so the heartbeats of
390
+ // many endpoints in one process that once coincided stay coincident and the loop takes the whole
391
+ // batch in one tick (5088 endpoints in one process: 1 to 2 s stalls, with the put deadlines
392
+ // expiring inside them). Re-arming from the scheduled beat keeps each endpoint's phase.
393
+ const phase = Date.now();
394
+ let beat = 0;
395
+ const arm = () => {
396
+ const next = nextHeartbeat(phase, this.heartbeatMs, beat, Date.now());
397
+ beat = next.beat;
398
+ const handle = setTimeout(() => {
399
+ this.publishPresence().catch((e) => this.emitRecoverable(e));
400
+ if (this.heartbeatTimer === handle)
401
+ arm();
402
+ }, next.delayMs);
403
+ this.heartbeatTimer = handle;
404
+ };
405
+ arm();
406
+ }
407
+ // Caller-owned membership watches are INTENT rather than one-connection iterators. Re-open them
408
+ // before reporting the endpoint connected, so a successful reconnect does not leave the graph stale.
409
+ await this.rearmMembershipWatches();
410
+ // Re-arm Plane-3 (delivery-daemon-hosted fan-out + trusted reader + ctl.delivery) on every (re)connect — no-op unless this
411
+ // endpoint hosts it. The first arm comes from startPlane3 (after start()); this re-binds the loops
412
+ // a reconnect's clearConnectionScoped() tore down, so a broker blip doesn't silently kill the backstop.
413
+ await this.armPlane3();
414
+ // Re-bind the liveness responders on this connection, for armPlane3's reason: the rebuild closed
415
+ // the old connection and the responders with it.
416
+ for (const plane of this.livenessResponders.keys())
417
+ this.bindLiveness(plane);
418
+ // The principal serves subscribe again on the new connection and run their check again.
419
+ this.rebindPrincipalServes(false);
420
+ for (const tap of this.taps)
421
+ this.bindTap(tap);
422
+ // Bound and live — covers initial start, manual reconnect, AND background self-heal (every
423
+ // path lands here). The single signal an in-process agent's connected flag tracks.
424
+ //
425
+ // The stopped guard: stop() can land in any await above. Both callers tear the fresh
426
+ // connection back down (tearDownIfStopped), but an event has no undo, so a late
427
+ // `connection: true` would be the last edge a listener ever sees on a stopped endpoint and
428
+ // nothing follows it to correct the record. It belongs here rather than in a consumer because
429
+ // every listener reads the same edge; MeshAgent carries its own `stopping` guard and so was
430
+ // never the one exposed, which is the point.
431
+ //
432
+ // Measured for the start() caller by the broker suite's mid-bind cell. doRebuild is
433
+ // also measured, by a separate cell that holds the rebuild's connectAndBind at
434
+ // armPlane3 after a successful first bind and lands stop() in that window (#1028).
435
+ // Shared-line reasoning is no longer the rebuild proof.
436
+ if (this.stopped)
437
+ return;
438
+ this.emit("connection", { connected: true });
439
+ if (this.nc) {
440
+ for (const follower of this.activeGoalFollowers) {
441
+ follower.reconnected(this.nc);
442
+ }
443
+ }
444
+ }
445
+ /** Tear down everything {@link connectAndBind} (re)creates, so a rebind can't leak a
446
+ * second heartbeat, double-pump a consumer, or keep stale roster ghosts. Caller-owned
447
+ * subs (tap/serve) are left alone — they aren't rebuilt here. */
448
+ clearConnectionScoped() {
449
+ if (this.authExpiryReconnectTimer) {
450
+ clearTimeout(this.authExpiryReconnectTimer);
451
+ this.authExpiryReconnectTimer = undefined;
452
+ }
453
+ if (this.heartbeatTimer) {
454
+ clearInterval(this.heartbeatTimer);
455
+ this.heartbeatTimer = undefined;
456
+ }
457
+ if (this.sweepTimer) {
458
+ clearInterval(this.sweepTimer);
459
+ this.sweepTimer = undefined;
460
+ }
461
+ for (const msgs of this.streamMsgs) {
462
+ try {
463
+ msgs.stop();
464
+ }
465
+ catch {
466
+ /* already closed with the connection */
467
+ }
468
+ }
469
+ this.streamMsgs.length = 0;
470
+ this.presenceEpoch++;
471
+ this.presence.cancelRebind();
472
+ this.presence.retireWatch();
473
+ if (this.channelWatchIter)
474
+ this.retireKvWatch(this.channelWatchIter);
475
+ this.channelWatchIter = undefined;
476
+ this.stopDeliveryLeaseWatch();
477
+ for (const sub of this.chatSubs.values()) {
478
+ try {
479
+ sub.unsubscribe();
480
+ }
481
+ catch {
482
+ /* already closed with the connection */
483
+ }
484
+ }
485
+ this.chatSubs.clear();
486
+ this.chatSubDenied.clear();
487
+ this.ownWatchDeletePrefixes.clear();
488
+ this.presence.resetConnection();
489
+ this.channelConfigs.clear();
490
+ this.channelDefaults = {};
491
+ // A read in flight on the old connection must not land in the new connection's cache.
492
+ this.channelRead = undefined;
493
+ this.channelReadGeneration++;
494
+ this.channelReadApplied = this.channelReadGeneration;
495
+ for (const watch of this.membershipFeedWatches)
496
+ watch.arm = watch.arm.catch(() => { }).then(() => this.disarmMembershipWatch(watch)).catch((err) => { this.emit("error", err); });
497
+ }
498
+ /** A transport can connect before a later JetStream/KV/subscription bind fails. The caller will
499
+ * retry the whole start, so release that partial epoch first instead of overwriting `nc` and
500
+ * leaving one established socket behind per retry. `close()` is deliberate: a failed bind has no
501
+ * graceful delivery contract to drain, and cleanup itself must not extend the retry failure.
502
+ *
503
+ * A throwing `close()` is not hypothetical: nats.js `NatsConnectionImpl.close()` awaits the
504
+ * protocol close, which itself flushes outbound + tears down subscription state; any of those
505
+ * that reject leaves the underlying TCP transport ESTABLISHED even though every client handle
506
+ * on this endpoint has been cleared. The next `start()` on the same object then dials a fresh
507
+ * connection while the old socket stays live on the broker (`/varz.connections` climbs once per
508
+ * failed attempt). The recovery path is layered, from most graceful to most surgical, matching
509
+ * nats-core's public surface (nats.d.ts: `close`, `drain`, `isClosed`; protocol.d.ts owns the
510
+ * `transport` handle whose `close(err?)` is the socket teardown; transport.d.ts exposes a
511
+ * synchronous `disconnect()` for the case where even close rejects). We only touch a private
512
+ * (`nc.protocol.transport`) when the public API has already refused, and the ORIGINAL bind
513
+ * error is re-raised at every layer. The close error is diagnostic noise. The bind error is
514
+ * what the caller must see.
515
+ *
516
+ * The delivery-serve subs and `this.subs` array are handles created by a successful
517
+ * `armDeliveryControl` on a PREVIOUS epoch; a bind failure on the retry never rewrites them
518
+ * because arming is a late step. Left in place they point at a dead protocol and survive into
519
+ * the next retry. The reviewer flagged this as an untested handle class. Zero them here so a
520
+ * retry starts with the same empty state as a first attempt. */
521
+ async closeFailedBind() {
522
+ const failedNc = this.nc;
523
+ if (failedNc)
524
+ this.disableLibraryReconnect(failedNc);
525
+ this.clearConnectionScoped();
526
+ this.nc = undefined;
527
+ this.js = undefined;
528
+ this.jsm = undefined;
529
+ this.kv = undefined;
530
+ this.channelKv = undefined;
531
+ this.membersKv = undefined;
532
+ this.aclKv = undefined;
533
+ this.membershipFeedKv = undefined;
534
+ this.deliveryLease.resetConnection();
535
+ this.managerLeaseKv = undefined;
536
+ this.daemonRenewalLeaseRevision = undefined;
537
+ // Handles that armDeliveryControl created on a previous connection: null them so a rebind
538
+ // does not carry a dead protocol's subs forward. Best-effort unsubscribe first (the sub is
539
+ // dead with its connection either way; unsubscribing an already-dead sub is a noop).
540
+ if (this.deliveryPlane.deliveryServeSub) {
541
+ try {
542
+ this.deliveryPlane.deliveryServeSub.unsubscribe();
543
+ }
544
+ catch { /* dead with the old connection */ }
545
+ this.deliveryPlane.deliveryServeSub = undefined;
546
+ }
547
+ if (this.deliveryPlane.deliveryAdminServeSub) {
548
+ try {
549
+ this.deliveryPlane.deliveryAdminServeSub.unsubscribe();
550
+ }
551
+ catch { /* dead with the old connection */ }
552
+ this.deliveryPlane.deliveryAdminServeSub = undefined;
553
+ }
554
+ this.dropAnycastRequests();
555
+ for (const sub of this.subs) {
556
+ try {
557
+ sub.unsubscribe();
558
+ }
559
+ catch { /* dead with the old connection */ }
560
+ }
561
+ this.subs.length = 0;
562
+ if (!failedNc)
563
+ return;
564
+ // The old status iterator is stale after nc is cleared, so its close cannot report this edge.
565
+ // As in doRebuild, teardown itself must announce the no-nc window before closing the socket.
566
+ this.emit("transport", { connected: false });
567
+ this.emit("connection", { connected: false });
568
+ // Layered teardown, comments kept OUT of the code span below on purpose: the mutation fixture
569
+ // bin/smoke/mutations/failed-bind-cleanup.json anchors on that span verbatim and the fixture
570
+ // census (bin/smoke/mutation-fixtures.smoke.ts) reddens an anchor that crosses a comment line.
571
+ // Fast path: the public close resolved, the broker drops the connection on its own.
572
+ // Layer 1: nats.js exposes drain() as the sanctioned "close on error" path. It flushes
573
+ // outbound then closes, and unlike close() has its own idempotent guard against a half-closed
574
+ // protocol. If drain resolves the socket is gone.
575
+ // Layer 2: last resort. nats.js `NatsConnectionImpl.protocol.transport` (see
576
+ // node_modules/@nats-io/nats-core/lib/{nats,protocol,transport}.d.ts) is the TCP socket the
577
+ // dialer produced. Its `close(err?)` returns a Promise once the socket is torn down; its
578
+ // synchronous `disconnect()` forces the FIN without waiting. Reached only after the public
579
+ // API has already refused, guarded only against the shape not being what the pinned version
580
+ // documents.
581
+ try {
582
+ await failedNc.close();
583
+ return;
584
+ }
585
+ catch { /* fall through to the layered fallback */ }
586
+ if (!failedNc.isClosed?.()) {
587
+ try {
588
+ await drainAndClose(failedNc);
589
+ return;
590
+ }
591
+ catch { /* both graceful paths refused, drop to the transport */ }
592
+ }
593
+ const proto = failedNc.protocol;
594
+ const transport = proto?.transport;
595
+ if (transport && !transport.isClosed) {
596
+ try {
597
+ await transport.close?.();
598
+ }
599
+ catch { /* transport close itself threw, force it down synchronously below */ }
600
+ if (!transport.isClosed) {
601
+ try {
602
+ transport.disconnect?.();
603
+ }
604
+ catch { /* nothing left to try */ }
605
+ }
606
+ }
607
+ }
608
+ /** If stop() ran during a rebuild's `await connectAndBind`, the just-bound connection +
609
+ * heartbeat + supervisor would be left live on a stopped endpoint. Tear that fresh
610
+ * connection back down and report it. Reads `this.nc` in its own scope (a bare `this.nc`
611
+ * in doRebuild narrows to `never` via TS inlining connectAndBind's assignment). Returns
612
+ * true iff it tore something down (caller bails out of the rebuild). */
613
+ async tearDownIfStopped() {
614
+ if (!this.stopped)
615
+ return false;
616
+ const nc = this.nc;
617
+ if (nc)
618
+ this.disableLibraryReconnect(nc);
619
+ this.clearConnectionScoped();
620
+ await this.closeWithoutLibraryReconnect(nc);
621
+ this.nc = undefined;
622
+ return true;
623
+ }
624
+ async stopOnce() {
625
+ if (this.nc)
626
+ this.disableLibraryReconnect(this.nc);
627
+ this.stopped = true;
628
+ for (const follower of this.activeGoalFollowers) {
629
+ follower.cancel();
630
+ }
631
+ this.activeGoalFollowers.clear();
632
+ this.presenceEpoch++;
633
+ // Every principal serve ends now, so a `ready` still waiting for the broker rejects and no new
634
+ // request is taken. Its handlers in flight finish below, before the connection they reply on
635
+ // closes, or their requests' deadlines pass.
636
+ const principalStops = [...this.principalServes.values()].map((intent) => this.stopPrincipalServe(intent, false));
637
+ this.presence.cancelRebind();
638
+ // Wake a reestablishLoop sitting in backoff so it sees `stopped` and exits instead of
639
+ // sleeping out retryMs; also clears the timer so it can't fire later.
640
+ this.kickBackoff();
641
+ for (const wake of [...this.membershipPauses])
642
+ wake();
643
+ if (this.heartbeatTimer)
644
+ clearInterval(this.heartbeatTimer);
645
+ if (this.sweepTimer)
646
+ clearInterval(this.sweepTimer);
647
+ this.cancelBearerRenewal?.();
648
+ if (this.credsTimer)
649
+ clearTimeout(this.credsTimer);
650
+ if (this.authExpiryReconnectTimer)
651
+ clearTimeout(this.authExpiryReconnectTimer);
652
+ for (const watch of this.membershipFeedWatches) {
653
+ watch.stopped = true;
654
+ watch.arm = watch.arm.catch(() => { }).then(async () => {
655
+ await this.disarmMembershipWatch(watch);
656
+ await this.deleteRetainedMembershipConsumer(watch);
657
+ });
658
+ }
659
+ // Permanent endpoint shutdown has no future epoch. Try strict cleanup on the current live epoch;
660
+ // if the broker is already gone, terminate local ownership rather than hanging shutdown forever.
661
+ await Promise.all([...this.membershipFeedWatches].map((watch) => watch.arm.catch((err) => {
662
+ if (this.nc && !this.nc.isClosed())
663
+ throw err;
664
+ })));
665
+ for (const watch of this.membershipFeedWatches) {
666
+ watch.resolveStop?.();
667
+ watch.resolveStop = undefined;
668
+ watch.rejectStop = undefined;
669
+ }
670
+ this.membershipFeedWatches.clear();
671
+ for (const msgs of this.streamMsgs) {
672
+ try {
673
+ msgs.stop();
674
+ }
675
+ catch {
676
+ /* already closed */
677
+ }
678
+ }
679
+ this.presence.retireWatch();
680
+ if (this.channelWatchIter)
681
+ this.retireKvWatch(this.channelWatchIter);
682
+ this.channelWatchIter = undefined;
683
+ this.stopDeliveryLeaseWatch();
684
+ await Promise.all(principalStops);
685
+ try {
686
+ if (this.doRegister) {
687
+ await this.presence.publishOffline();
688
+ }
689
+ }
690
+ catch {
691
+ /* best-effort graceful leave */
692
+ }
693
+ await Promise.all([this.settleDeliveryLeaseWatches(), this.settleKvWatches()]);
694
+ // DM-only: the pull above is stopped, so no new copy reaches the handler. Let a running handler
695
+ // settle while the connection is still open, so its ack can reach the broker; close either way.
696
+ let dmOnlyUnsettled = false;
697
+ if (this.dmOnly && this.dmOnlyInFlight) {
698
+ const settleMs = this.dmOnly.settleTimeoutMs ?? 30_000;
699
+ dmOnlyUnsettled = await withDeadline(this.dmOnlyInFlight.then(() => false), settleMs, () => new Error("unsettled"))
700
+ .catch(() => true);
701
+ }
702
+ await this.closeWithoutLibraryReconnect(this.nc);
703
+ // #1356: stop() does its own teardown and never runs clearConnectionScoped, so clear here too —
704
+ // AFTER the best-effort offline publish above, which would otherwise re-record a refusal on its
705
+ // way out. A stopped endpoint has no live basis for "this bucket is refusing writes", and the
706
+ // duration is computed from `Date.now()`, so a retained record does not merely go stale: it keeps
707
+ // COUNTING UP for as long as the dead object is held.
708
+ this.clearPresenceWriteFailure();
709
+ // Custody callers must not observe stop completion while a concurrent rebind can still
710
+ // publish a late consuming connection. doRebuild closes its stopped epoch before resolving.
711
+ await this.rebuildPromise;
712
+ await this.startPromise;
713
+ if ([...this.ownedConnections].some((nc) => !nc.isClosed()))
714
+ throw new Error("endpoint stop could not prove its connection closed; local consumer custody must be retained");
715
+ if (dmOnlyUnsettled)
716
+ throw new Error(`endpoint stop closed the connection but the DM-only handler did not settle within ${this.dmOnly?.settleTimeoutMs ?? 30_000}ms; its copy stays unacked and handler custody must be retained`);
717
+ }
718
+ /** The native binding of every connection this endpoint holds. A host compares the list with a
719
+ * complete native census of the account to show that no other connection uses it. The list
720
+ * proves neither liveness nor the absence of other connections. A stopped endpoint whose
721
+ * connections all closed reports none. It throws while there is no settled answer: before
722
+ * start, during a start, rebuild or stop, while a credential transaction or its connection swap
723
+ * is pending, and while the connection is down or redialing. */
724
+ nativeConnections() {
725
+ const unsettled = (why) => new Error(`endpoint connection inventory is unsettled: ${why}`);
726
+ if (this.startPromise !== undefined || this.rebuildPromise !== undefined || this.reconnecting)
727
+ throw unsettled("a start or rebuild is in flight");
728
+ const open = [...this.ownedConnections].filter((nc) => !nc.isClosed());
729
+ if (this.stopped) {
730
+ if (open.length > 0)
731
+ throw unsettled("the endpoint stopped but a connection has not closed");
732
+ return [];
733
+ }
734
+ if (this.credsTxnsRunning > 0 || this.residentSwap !== undefined)
735
+ throw unsettled("a credential adoption is in flight");
736
+ if (!this.nc || !this.nativeBound)
737
+ throw unsettled("the connection is down or redialing");
738
+ return open.map((nc) => nativeConnectionBinding(nc, "endpoint connection"));
739
+ }
740
+ }
741
+ //# sourceMappingURL=endpoint-connection.js.map