@cotal-ai/core 0.171.2 → 0.171.4

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/endpoint.js CHANGED
@@ -1,17 +1,13 @@
1
1
  import { EndpointHistory } from "./endpoint-history.js";
2
2
  export { MULTI_FILTER_BATCH, MULTI_FILTER_READ_CONCURRENCY } from "./endpoint-history.js";
3
- import { requestSafeReconnect } from "./request-safe-reconnect.js";
4
- import { nativeBindingAfter, nativeConnectionBinding } from "./native-connection.js";
3
+ import { nativeBindingAfter } from "./native-connection.js";
5
4
  import { EventEmitter } from "node:events";
6
- import { drainAndClose } from "./connection-cleanup.js";
7
5
  import { randomUUID } from "node:crypto";
8
6
  import { nanos, PermissionViolationError, NoRespondersError, RequestError, TimeoutError, } from "@nats-io/transport-node";
9
7
  import { responderFromLease, responderFromProbe, } from "./liveness.js";
10
8
  import { EndpointPresence } from "./endpoint-presence.js";
11
9
  export { PresenceWriteStuckError } from "./endpoint-presence.js";
12
- import { credsClaims, credsFingerprint, credsRenewalDelayMs, idFromCreds } from "./identity.js";
13
- import { armRenewal, jitteredBackoffMs } from "./renewal.js";
14
- import { requireBrokerFloor } from "./broker-floor.js";
10
+ import { idFromCreds } from "./identity.js";
15
11
  import { withDeadline } from "./deadline.js";
16
12
  import {} from "./secret-store.js";
17
13
  import { BIND_SPLIT_REISSUES, resolveService } from "./endpoint-invoke.js";
@@ -22,14 +18,13 @@ import { servePrincipalRoute, describeContracts } from "./endpoint-serve.js";
22
18
  import { epPrincipalCall } from "./endpoint-call.js";
23
19
  import { AGENT_CLUSTER, AGENT_CONTRACTS, AGENT_ENDPOINT } from "./agent-endpoint.js";
24
20
  import { processRuntime } from "./process-runtime.js";
25
- import { importNativeSubjectPermissions, issuedPermitsSubject, readAcceptedRow } from "./issued-authority.js";
21
+ import { issuedPermitsSubject } from "./issued-authority.js";
26
22
  import { listRegistryEndpoints } from "./registry-client.js";
27
23
  import { isConsumerNotFound, isJetStreamMissing, isStreamNotFound } from "./jetstream-missing.js";
28
24
  import { assertValidKind } from "./agent-file.js";
29
25
  import { assertValidName } from "./resolve.js";
30
- import { nextHeartbeat } from "./presence-heartbeat.js";
31
- import { anycastStoreDefinition, taskDurableConfig, PRESENCE_STORAGE } from "./streams.js";
32
- import { jetstream, jetstreamManager, AckPolicy, DeliverPolicy, JetStreamApiCodes, } from "@nats-io/jetstream";
26
+ import { anycastStoreDefinition, taskDurableConfig } from "./streams.js";
27
+ import { jetstreamManager, AckPolicy, DeliverPolicy, JetStreamApiCodes, } from "@nats-io/jetstream";
33
28
  import {} from "@nats-io/jetstream";
34
29
  import { Kvm } from "@nats-io/kv";
35
30
  import { listMembers } from "./members.js";
@@ -42,16 +37,19 @@ import { EndpointDurableBackstop } from "./endpoint-durable-backstop.js";
42
37
  import { EndpointSubscriptions, membershipConsumerReleased } from "./endpoint-subscriptions.js";
43
38
  import { EndpointChannelDiscovery } from "./endpoint-channel-discovery.js";
44
39
  import { EndpointLiveness } from "./endpoint-liveness.js";
40
+ import { EndpointCredentials } from "./endpoint-credentials.js";
41
+ import { EndpointReconnect } from "./endpoint-reconnect.js";
42
+ import { EndpointConnection } from "./endpoint-connection.js";
45
43
  import { EndpointProvisioning } from "./endpoint-provisioning.js";
46
44
  import { EndpointBootMemberships } from "./endpoint-boot-memberships.js";
47
45
  import { ackWaitOf, durableDelivery, isRecord } from "./endpoint-inbound.js";
48
- import { openChannelRegistry, effectiveReplay, effectiveReplayWindowMs, readChannelConfig, readChannelDefaults, } from "./channels.js";
46
+ import { effectiveReplay, effectiveReplayWindowMs, readChannelConfig, readChannelDefaults, } from "./channels.js";
49
47
  import { isCasLoss } from "./endpoint-records.js";
50
48
  import { ANYCAST_CANCEL_OP, ANYCAST_NOTICE_KEY, ANYCAST_RECORDS_CREDENTIAL_OUTDATED, ANYCAST_STATUS_OP, ANYCAST_TAKES_OP, AnycastRequestAuthority, isAnycastSeq, } from "./anycast-requests.js";
51
- import { assertValidRole, chatStream, chatSubject, controlServiceSubject, CONTROL_DELIVERY, CONTROL_DELIVERY_ADMIN, dmStream, dmDurable, membershipInAllow, isConcreteChannel, isChannelFamily, MENTION_NOTICE_KEY, parseSubject, isPrincipalOwnerToken, assertInboxConnId, presenceBucket, MEMBERSHIP_FEED_KEY, principalKey, parsePrincipalKey, assertLifecycleToken, mintLifecycleUid, lifecycleNameKey, DEV_OWNER, spacePrefix, spaceWildcard, subjectMatches, taskStream, taskDurable, takeServeFilter, takeSubject, parseTakeSubject, TAKE_ROUTE, token, unicastSubject, unicastRecvFilter, } from "./subjects.js";
49
+ import { assertValidRole, chatStream, chatSubject, controlServiceSubject, CONTROL_DELIVERY, CONTROL_DELIVERY_ADMIN, dmStream, dmDurable, membershipInAllow, isConcreteChannel, isChannelFamily, MENTION_NOTICE_KEY, parseSubject, isPrincipalOwnerToken, assertInboxConnId, MEMBERSHIP_FEED_KEY, principalKey, parsePrincipalKey, assertLifecycleToken, mintLifecycleUid, lifecycleNameKey, DEV_OWNER, spacePrefix, spaceWildcard, subjectMatches, taskStream, taskDurable, takeServeFilter, takeSubject, parseTakeSubject, TAKE_ROUTE, token, unicastSubject, unicastRecvFilter, } from "./subjects.js";
52
50
  import { isPermissionDenied } from "./permission-denied.js";
53
51
  export { isPermissionDenied };
54
- import { DEFAULT_SERVER, isPublishPermissionDenied, dialerFor, probeConnect, isAuthRejection, kvWatchConsumer, decodeBearerPrincipal, bearerExpiryMs, bearerRenewalDeadlineMs, bearerLifetimeMs, retryAfterMs, authOpts, RepeatedRefusal, describeStatusError, } from "./endpoint-dial.js";
52
+ import { DEFAULT_SERVER, isPublishPermissionDenied, isAuthRejection, kvWatchConsumer, decodeBearerPrincipal, RepeatedRefusal, describeStatusError, } from "./endpoint-dial.js";
55
53
  export { DEFAULT_SERVER, isPublishPermissionDenied, wsServers, defaultProbeTimeoutMs, dialerFor, isAuthRejection, isReachable, probeConnect, } from "./endpoint-dial.js";
56
54
  import { MAX_TIMER_MS, ANYCAST_SWEEP_MS, MAX_TAKES_IN_FLIGHT, ANYCAST_TAKE_TIMEOUT_MS, DmDurableMissingError, DmBindRefusedError, } from "./endpoint-options.js";
57
55
  export { deliveryLimitOf, DEFAULT_SPACE, DmDurableMissingError, DmBindRefusedError, fitHistoryPage, } from "./endpoint-options.js";
@@ -637,12 +635,6 @@ export class CotalEndpoint extends EventEmitter {
637
635
  return;
638
636
  this.superviseConnection();
639
637
  }
640
- /** The floor on a bearer renewal's delay. A token whose whole lifetime sits under it is renewed at
641
- * this cadence (`expiry-renewal` mints 5s bearers). */
642
- static BEARER_MIN_RENEWAL_MS = 5_000;
643
- /** A failed bearer renewal retries after about this long, doubling per failure up to the cap. */
644
- static BEARER_RETRY_MS = 5_000;
645
- static BEARER_RETRY_CAP_MS = 60_000;
646
638
  /**
647
639
  * A condition the endpoint is already surviving. Node rethrows `error` when no listener is
648
640
  * attached, so emitting retry notices on `error` killed hosts that the endpoint intended to
@@ -651,461 +643,115 @@ export class CotalEndpoint extends EventEmitter {
651
643
  emitRecoverable(err) {
652
644
  this.emit("warning", err);
653
645
  }
654
- /** Fetch a fresh bearer from the source, pin its principal to ours, arm the next renewal. On a
655
- * fetch/principal failure: THROWS when `initial` (start() must fail loud before first connect);
656
- * otherwise retries on a jittered, capped backoff, and warns once for the whole run of failures —
657
- * the live connection keeps working until its current JWT expiry, so a dead auth service is
658
- * loud without instantly dropping the mesh, and without a line per attempt. */
659
- async refreshBearer(initial = false) {
660
- try {
661
- const bearer = await this.bearerSource();
662
- const claims = decodeBearerPrincipal(bearer);
663
- if (claims.owner !== this.owner || claims.actor !== this.actor)
664
- throw new Error(`bearer source returned principal ${claims.owner}.${claims.actor}, expected ${this.owner}.${this.actor}`);
665
- // Two refusals, answering different questions, and both of them are about protecting what is
666
- // ALREADY held. So both are scoped to there BEING something held, which is the same set as
667
- // `!initial` but names the thing the rules actually depend on: on the first fetch there is no
668
- // cache to lose, `start()` has to come up on whatever the source has, and the pre-dial guard
669
- // in {@link bindConnection} is what speaks for a dead first token.
670
- const expiryMs = bearerExpiryMs(bearer);
671
- const held = this.currentBearer;
672
- if (held !== undefined) {
673
- // ALREADY DEAD, whatever else is true of it. Advancement is deliberately not part of this
674
- // test: a candidate expiring at now-5s does advance a held one that died at now-60s, so an
675
- // advance-only rule adopts it - overwriting the cache with material nothing can dial,
676
- // skipping the recoverable warning because the fetch did not throw, and arming the next
677
- // read off a non-positive delay. The creds path draws its line on expiry alone too, in
678
- // {@link presentableCreds} (#1572).
679
- if (expiryMs <= Date.now())
680
- throw new Error("the bearer source returned a token that has already expired - nothing adopted");
681
- // THE SAME BYTES BACK AGAIN from a source whose token is already past its renewal window:
682
- // the renewal it arms is floored to 5s, and the next read returns that same token - a 5s
683
- // loop against the auth service for the rest of its life, with the retry backoff bypassed
684
- // because the fetch did not FAIL. It succeeded and returned nothing new (#1561).
685
- //
686
- // The test is byte identity, not expiry, and not advancement. `exp` carries one second of
687
- // resolution, so a key rotation re-signing the same claims under a new key - and a healthy
688
- // short-TTL source read twice inside one wall-clock second - both hand back a token whose
689
- // `exp` has not moved. That is genuinely re-issued material, which an advancement test
690
- // refuses and this one adopts. It is the question the creds path asks with
691
- // `credsFingerprint`: did the source re-issue ANYTHING (#1572).
692
- if (bearer === held && Date.now() >= bearerRenewalDeadlineMs(held, this.bearerAdoptedAtMs))
693
- throw new Error("the bearer source re-served the token already held and it cannot carry another cycle (the auth service has not issued a fresh one) - nothing adopted");
694
- }
695
- if (bearer !== held)
696
- this.bearerAdoptedAtMs = Date.now();
697
- this.currentBearer = bearer;
698
- this.bearerRenewalFailures = 0;
699
- // The renewal point is drawn from the middle of the token's lifetime, spaced from this
700
- // process's other renewals in the space: a fixed margin before `exp` kept every endpoint
701
- // issued in one second renewing, and rebinding through the callout, in one second for life.
702
- const { issuedAtMs, expiresAtMs } = bearerLifetimeMs(bearer, this.bearerAdoptedAtMs);
703
- this.armBearerTimer(armRenewal(this.space, issuedAtMs, expiresAtMs, () => void this.renewBearerOnTimer(), CotalEndpoint.BEARER_MIN_RENEWAL_MS));
704
- }
705
- catch (e) {
706
- if (initial)
707
- throw e;
708
- if (this.bearerRenewalFailures === 0)
709
- this.emitRecoverable(new Error(`bearer refresh failed (${e instanceof Error ? e.message : String(e)}) - retrying with backoff; this connection dies at its current token's expiry if the auth service stays down`));
710
- // A wait the source named is kept as named: never retried inside it, nor stretched by the backoff.
711
- const named = retryAfterMs(e);
712
- const delay = named > 0 ? named : jitteredBackoffMs(this.bearerRenewalFailures, CotalEndpoint.BEARER_RETRY_MS, CotalEndpoint.BEARER_RETRY_CAP_MS);
713
- this.bearerRenewalFailures++;
714
- const timer = setTimeout(() => void this.renewBearerOnTimer(), delay);
715
- timer.unref?.();
716
- this.armBearerTimer(() => clearTimeout(timer));
717
- }
718
- }
719
- armBearerTimer(cancel) {
720
- this.cancelBearerRenewal?.();
721
- this.cancelBearerRenewal = cancel;
722
- if (this.stopped)
723
- cancel();
724
- }
725
- /** The timed renewal. A new token moves the live connection onto itself at once, through the
726
- * same controlled reconnect the creds path uses, so the broker never has to expire a connection
727
- * this endpoint could renew. With no live connection, it ends the rebuild loop's wait instead:
728
- * that loop refuses to dial an expired token and leaves the retries to this timer. */
729
- async renewBearerOnTimer() {
730
- const held = this.currentBearer;
731
- await this.refreshBearer();
732
- if (this.stopped || this.currentBearer === held)
733
- return;
734
- if (this.nc && !this.nc.isClosed())
735
- await this.swapConnectionOntoFreshCreds();
736
- else
737
- this.kickBackoff();
646
+ /** The resident swap a reload scheduled, until its connection is back or the gate's bound ends. */
647
+ residentSwap;
648
+ /** Serializes every prove-then-adopt transaction (the 75% timer and the explicit reload) so a timer
649
+ * tick and an explicit reload can never interleave their fetch/preflight/commit — the design's
650
+ * single-flight requirement. Runs `fn` after any in-flight transaction settles, whatever its
651
+ * outcome; the internal chain never rejects. */
652
+ credsTxn = Promise.resolve();
653
+ /** The bearer and credential renewal of this endpoint. Every dependency is read when it is used, so
654
+ * a field assigned after construction is seen. */
655
+ credentials = new EndpointCredentials({
656
+ nc: () => this.nc,
657
+ bearerSource: () => this.bearerSource,
658
+ owner: () => this.owner,
659
+ actor: () => this.actor,
660
+ space: () => this.space,
661
+ currentBearer: () => this.currentBearer,
662
+ setCurrentBearer: (value) => { this.currentBearer = value; },
663
+ bearerAdoptedAtMs: () => this.bearerAdoptedAtMs,
664
+ setBearerAdoptedAtMs: (value) => { this.bearerAdoptedAtMs = value; },
665
+ bearerRenewalFailures: () => this.bearerRenewalFailures,
666
+ setBearerRenewalFailures: (value) => { this.bearerRenewalFailures = value; },
667
+ cancelBearerRenewal: () => this.cancelBearerRenewal,
668
+ setCancelBearerRenewal: (value) => { this.cancelBearerRenewal = value; },
669
+ stopped: () => this.stopped,
670
+ presentedExp: () => this.presentedExp,
671
+ setPresentedExp: (value) => { this.presentedExp = value; },
672
+ currentCreds: () => this.currentCreds,
673
+ setCurrentCreds: (value) => { this.currentCreds = value; },
674
+ credsSource: () => this.credsSource,
675
+ connId: () => this.connId,
676
+ overlapOnConnectionRenewal: () => this.overlapOnConnectionRenewal,
677
+ onConnection: () => this.onConnection,
678
+ servers: () => this.servers,
679
+ card: () => this.card,
680
+ token: () => this.token,
681
+ user: () => this.user,
682
+ pass: () => this.pass,
683
+ userMode: () => this.userMode,
684
+ sentinelCreds: () => this.sentinelCreds,
685
+ tls: () => this.tls,
686
+ ownedConnections: () => this.ownedConnections,
687
+ authExpiryReconnectTimer: () => this.authExpiryReconnectTimer,
688
+ setAuthExpiryReconnectTimer: (value) => { this.authExpiryReconnectTimer = value; },
689
+ credsTxnsRunning: () => this.credsTxnsRunning,
690
+ setCredsTxnsRunning: (value) => { this.credsTxnsRunning = value; },
691
+ credsTxn: () => this.credsTxn,
692
+ setCredsTxn: (value) => { this.credsTxn = value; },
693
+ reconnecting: () => this.reconnecting,
694
+ reestablishing: () => this.reestablishing,
695
+ requestsAwaitingReply: () => this.requestsAwaitingReply,
696
+ residentSwap: () => this.residentSwap,
697
+ setResidentSwap: (value) => { this.residentSwap = value; },
698
+ emitRecoverable: (err) => this.emitRecoverable(err),
699
+ kickBackoff: () => this.kickBackoff(),
700
+ armCredsRefresh: (delayMs) => this.armCredsRefresh(delayMs),
701
+ reconnect: () => this.reconnect(),
702
+ emit: (event, ...args) => this.emit(event, ...args),
703
+ on: (event, listener) => { this.on(event, listener); },
704
+ off: (event, listener) => { this.off(event, listener); },
705
+ });
706
+ /** Forwards to the credentials component's {@link EndpointCredentials.refreshBearer}. */
707
+ refreshBearer(initial = false) {
708
+ return this.credentials.refreshBearer(initial);
738
709
  }
739
- /** The cached bearer, checked: every (re)connect attempt reads it, the reconnects nats.js runs
740
- * on its own included, so none presents an expired token, which the callout could only deny
741
- * after a full round trip. The bearer counterpart of {@link credsForWire}. */
710
+ /** Forwards to the credentials component's {@link EndpointCredentials.bearerForWire}. */
742
711
  bearerForWire() {
743
- const bearer = this.currentBearer;
744
- if (bearer !== undefined && bearerExpiryMs(bearer) > Date.now())
745
- return bearer;
746
- throw new Error(this.bearerSource
747
- ? "this endpoint's user bearer has expired and renewal through the auth exchange is failing - not presenting the expired token to the broker; retrying with backoff"
748
- : "this endpoint's user bearer has expired and it holds no bearer source to renew it - re-authenticate and rebuild the endpoint (construct it with a bearer FUNCTION for standing renewal)");
749
- }
750
- /** How soon a FAILED creds refresh retries. Successful refreshes schedule by lifetime fraction
751
- * (75% of iat→exp), not a fixed margin — standing creds span hours to days, bearers minutes. */
752
- static CREDS_RETRY_MS = 60_000;
753
- /** THE ONE PLACE a credential is cleared for presentation to a broker.
754
- *
755
- * The property is unconditional — this endpoint never presents a credential it has already
756
- * decoded as expired — so it is a property of the SUPPLY, not of any one dial site. It used to
757
- * live inside {@link bindConnection}, which only `start()` and `doRebuild` reach; the
758
- * authenticator nats.js re-evaluates on ITS OWN reconnects read the cache directly and so
759
- * presented whatever was last fetched, expired included. Two such reconnects exist and neither
760
- * passes through bindConnection: the one the broker forces at JWT `exp`, and an ALREADY RUNNING
761
- * dial loop from an earlier drop that crosses `exp` while it retries (the pre-expiry
762
- * reconnect fence flips a policy flag nats-core only reads when it observes a NEW drop, so it
763
- * cannot stop a loop already in flight).
764
- *
765
- * Putting the refusal here instead means a future caller cannot miss it: the only way to reach a
766
- * dial is through {@link credsForWire}, and the one presentation that does not read the cache
767
- * (the adoption preflight, which presents a fresh CANDIDATE) calls this same function on it.
768
- *
769
- * An unbounded credential (no numeric `exp`) is presentable: bounded lifetimes are the renewal
770
- * seam's concern, and a cred with no expiry has none to be past. */
771
- static presentableCreds(creds, opts) {
772
- const { exp } = credsClaims(creds); // throws on a structurally-unusable file (fail-loud)
773
- if (typeof exp === "number" && exp * 1000 <= Date.now())
774
- throw new Error(opts.renewable
775
- ? "this endpoint's creds have expired and renewal is failing - not presenting the expired credential to the broker; retrying with backoff"
776
- : "this endpoint's creds have expired and it holds no creds source to renew them - replace the credential and rebuild the endpoint (pass a creds FUNCTION for standing renewal)");
777
- return creds;
778
- }
779
- /** The connect attempt's credential getters: what {@link credsForWire} and {@link bearerForWire}
780
- * return, with its expiry recorded as {@link presentedExp}. */
712
+ return this.credentials.bearerForWire();
713
+ }
714
+ /** Forwards to the credentials component's {@link EndpointCredentials.presentCreds}. */
781
715
  presentCreds() {
782
- const creds = this.credsForWire();
783
- this.presentedExp = credsClaims(creds).exp;
784
- return creds;
716
+ return this.credentials.presentCreds();
785
717
  }
718
+ /** Forwards to the credentials component's {@link EndpointCredentials.presentBearer}. */
786
719
  presentBearer() {
787
- const bearer = this.bearerForWire();
788
- this.presentedExp = bearerExpiryMs(bearer) / 1000;
789
- return bearer;
790
- }
791
- /** The cached credential, checked. Handed to nats.js as the authenticator's source on EVERY auth
792
- * mode (renewed or static), so each (re)connect attempt — ours or the library's — re-reads a
793
- * CHECKED value. A refusal throws out of the authenticator, which nats-core turns into a closed
794
- * connection rather than a CONNECT carrying dead material; the endpoint's own supervisor then
795
- * rebuilds on capped backoff, and {@link bindConnection} re-fetches from the source on each of
796
- * those attempts, so a renewal that starts working recovers the endpoint without presenting
797
- * anything expired in the meantime. Deliberately side-effect free: kicking the renewal timer
798
- * from here would retry the source once per dial attempt, which is the flat load on a dead
799
- * broker that {@link RETRY_BACKOFF_CAP_MS} exists to prevent. */
800
- credsForWire() {
801
- if (!this.currentCreds)
802
- throw new Error(this.credsSource
803
- ? "this endpoint has no credential to present yet (the creds source has not returned one) - not dialing without auth material"
804
- : "this endpoint was constructed with an empty creds string - not dialing without auth material (an empty credential is not anonymous access)");
805
- return CotalEndpoint.presentableCreds(this.currentCreds, { renewable: Boolean(this.credsSource) });
720
+ return this.credentials.presentBearer();
806
721
  }
807
722
  /** The credential this endpoint presents on its next connect, checked as {@link credsForWire}
808
723
  * checks it. A second connection under the same identity reads it on every attempt, so it
809
724
  * presents each credential this endpoint adopts and never an expired one. */
810
725
  wireCreds() {
811
- return this.credsForWire();
726
+ return this.credentials.wireCreds();
812
727
  }
813
- /** Refuses a fetched generation there is nothing to renew FROM, so the caller's failure posture
814
- * ({@link CREDS_RETRY_MS}) applies instead of the renewal schedule (issue #1523).
815
- *
816
- * A source that hands back the SAME generation past its own renewal point has not re-signed yet:
817
- * that is a missed remint, not a candidate. Adopting it re-arms from a non-positive delay, which
818
- * {@link armCredsRefresh} floors to 1s, which fetches again, which is the same generation — a 1s
819
- * read loop against a store that is already having a bad day, for the JWT's remaining 25% of life,
820
- * with the 60s backoff that exists for exactly this bypassed because the fetch did not FAIL.
821
- *
822
- * The membership feed's rw-cred renewal already refuses it this way (`membership-feed.ts`,
823
- * `adoptRwCreds`: "the rw source still holds the previous generation past its renewal point");
824
- * this is the same rule on the endpoint's `delivery.creds` seam, so the two renewal paths answer
825
- * a dead source identically.
826
- *
827
- * An ALREADY-EXPIRED generation is refused whatever it is: the delay is non-positive for it too,
828
- * but it is dead rather than merely due, so it is named separately and refused even when the
829
- * source keeps returning a different one. */
830
- static assertRenewableGeneration(candidate, current, delayMs) {
831
- const { exp } = credsClaims(candidate);
832
- if (typeof exp === "number" && exp * 1000 <= Date.now())
833
- throw new Error("the creds source returned an already-expired credential (its `exp` is in the past) - nothing adopted; the renewal owner has not re-signed it, or the store is serving a stale generation");
834
- // Compared by GENERATION, not by envelope. `EndpointOptions.creds` takes opaque file content and
835
- // promises no canonical whitespace: `jwtFromCreds` pads with `\s*` and trims, so a store, editor or
836
- // filesystem round trip that adds a newline re-serves the SAME credential in bytes `===` calls
837
- // different - and the refusal would be skipped for the one case it exists to catch. The envelope
838
- // also carries the nkey seed, which is why `credsFingerprint` hashes the JWT instead.
839
- if (current !== undefined && credsFingerprint(candidate) === credsFingerprint(current) && delayMs <= 0)
840
- throw new Error("the creds source still holds the previous generation past its renewal point (the renewal owner has not re-signed it) - nothing adopted");
841
- }
842
- /** The disposable-preflight connect bound for the EXPLICIT reload proof (D5 class-2 adoption). A
843
- * rogue or unreachable candidate must resolve well UNDER the manager's delivery-admin request
844
- * bound, so this stays a few seconds and never blocks the responder. */
845
- static PREFLIGHT_MS = 4_000;
846
- /** How long the resident wire swap is deferred past the reply on the EXPLICIT reload path. The
847
- * delivery-admin responder rides THIS connection, so `nc.reconnect()` must not run until the
848
- * reply has flushed on the still-live old cred; the old cred stays valid until its exp, so a short
849
- * deferral is safe. */
850
- static RESIDENT_SWAP_DEFER_MS = 250;
851
- /** How long a delivery-admin request read after a reload waits for the resident swap's reconnect.
852
- * nats.js drops a publish made while the connection is down when it redials, so a reply sent
853
- * during the swap is lost and its caller waits out its whole request timeout. Past this bound the
854
- * request is answered anyway, as it was before the gate. */
855
- static RESIDENT_SWAP_GATE_MS = 5_000;
856
- /** The resident swap a reload scheduled, until its connection is back or the gate's bound ends. */
857
- residentSwap;
858
- /** The daemon-side deadline for the WHOLE prove-then-adopt transaction (source fetch + preflight +
859
- * commit), kept strictly BELOW the manager's delivery-admin request bound so a slow or hung hosted
860
- * store returns a structured component failure rather than an ambiguous client timeout, and a late
861
- * fetch can never commit after the caller gave up. */
862
- static RELOAD_DEADLINE_MS = 12_000;
863
- /** Fetch fresh creds from the source, pin their identity to ours, cache them, and arm the next
864
- * refresh at 75% of the new JWT's lifetime. THROWS on fetch/pin failure — the callers decide the
865
- * failure posture (loud-and-retry for the timer, a structured error reply for an explicit
866
- * {@link reloadCreds}). This is the PASSIVE-BACKSTOP fetch; the explicit auditable path
867
- * ({@link reloadCreds}) does its own fetch so it can preflight the candidate on a disposable
868
- * connection BEFORE mutating this live cache. */
869
- async fetchFreshCreds() {
870
- const creds = await this.credsSource();
871
- const id = idFromCreds(creds);
872
- if (id !== this.connId)
873
- throw new Error(`creds source returned identity ${id}, expected ${this.connId} - renewal may not swap the connection's nkey`);
874
- // Before the commit, so a refusal leaves the cache holding the last generation that was renewable
875
- // from (and, on the initial fetch, fails loud rather than dialling with dead material).
876
- const delay = credsRenewalDelayMs(creds);
877
- CotalEndpoint.assertRenewableGeneration(creds, this.currentCreds, delay);
878
- this.currentCreds = creds;
879
- this.armCredsRefresh(delay);
880
- const { iat, exp } = credsClaims(creds);
881
- return { iat, exp };
882
- }
883
- /** Swap the live connection onto the freshest cached cred or bearer with a controlled
884
- * `nc.reconnect()` (nats.js re-evaluates the authenticator per attempt). Swapping now, instead of
885
- * waiting for the broker to close the connection at `exp`, means the wire never carries a
886
- * near-dead JWT and the operator never sees a spurious "authentication expired". After the
887
- * reconnect succeeds, re-arm the expiry fence for the credential now authenticated on the wire. */
888
- async swapConnectionOntoFreshCreds() {
889
- const nc = this.nc;
890
- if (!(nc && !this.stopped))
891
- return;
892
- const overlap = this.overlapOnConnectionRenewal && this.onConnection
893
- ? await this.openRenewalOverlap().catch(() => undefined)
894
- : undefined;
895
- try {
896
- // reconnect() resolves when the disconnect is requested, before subscriptions return.
897
- // A flush started now is sent after those subscriptions, so it resolves only once they
898
- // are on the broker. The overlap stays up until then.
899
- await nc.reconnect().catch(() => { });
900
- if (overlap && !nc.isClosed())
901
- await withDeadline(nc.flush(), 10_000, () => new Error("resident renewal flush did not finish")).catch(() => { });
902
- if (this.nc === nc && !this.stopped)
903
- this.armAuthExpiryReconnectFence(nc);
904
- }
905
- finally {
906
- if (overlap && !overlap.isClosed())
907
- await this.closeWithoutLibraryReconnect(overlap).catch(() => { });
908
- }
728
+ /** Forwards to the credentials component's {@link EndpointCredentials.disableLibraryReconnect}. */
729
+ disableLibraryReconnect(nc) {
730
+ return this.credentials.disableLibraryReconnect(nc);
909
731
  }
910
- /** A second connection whose `onConnection` subscriptions are flushed before the resident
911
- * reconnect. Its inbox is not the resident connection's inbox. A flush that does not finish
912
- * closes it and leaves the caller to reconnect in place. */
913
- async openRenewalOverlap() {
914
- const overlap = await dialerFor(this.servers)({
915
- servers: this.servers,
916
- noAsyncTraces: true,
917
- name: `cotal:${this.card.name}:renewal`,
918
- inboxPrefix: `_INBOX_renew_${randomUUID()}`,
919
- maxReconnectAttempts: 0,
920
- ...authOpts({
921
- token: this.token, user: this.user, pass: this.pass,
922
- creds: this.currentCreds !== undefined || this.credsSource ? () => this.presentCreds() : undefined,
923
- bearer: this.userMode ? () => this.presentBearer() : undefined,
924
- sentinelCreds: this.sentinelCreds, tls: this.tls,
925
- }),
926
- });
927
- this.ownedConnections.add(overlap);
928
- try {
929
- this.onConnection?.(overlap);
930
- await withDeadline(overlap.flush(), 5_000, () => new Error("renewal overlap flush did not finish"));
931
- return overlap;
932
- }
933
- catch (error) {
934
- await this.closeWithoutLibraryReconnect(overlap).catch(() => { });
935
- throw error;
936
- }
732
+ /** Forwards to the credentials component's {@link EndpointCredentials.closeWithoutLibraryReconnect}. */
733
+ closeWithoutLibraryReconnect(nc) {
734
+ return this.credentials.closeWithoutLibraryReconnect(nc);
937
735
  }
938
- /** nats-core keeps its reconnect switch on the protocol handler. This pinned internal shape is the
939
- * same last-resort surface used by {@link closeFailedBind}; there is no public API for changing the
940
- * reconnect policy of an existing connection. Disabling it does not disable Cotal self-heal: the
941
- * `nc.closed()` supervisor below rebuilds the endpoint with freshly checked auth material. */
942
- disableLibraryReconnect(nc) {
943
- const protocol = nc.protocol;
944
- if (protocol?.options)
945
- protocol.options.reconnect = false;
946
- }
947
- /** Close a connection whose library reconnect has already been disabled. `drain()` flushes with a
948
- * PING and waits for the matching PONG; nats-core only rejects that waiter inside reconnect
949
- * `prepare()`, so a half-open socket with reconnect=false leaves drain pending until the 2-minute
950
- * ping interval times out. `close()` tears the transport down without that round-trip, which is
951
- * the same public path {@link closeFailedBind} already uses when there is no graceful delivery
952
- * contract left. */
953
- async closeWithoutLibraryReconnect(nc) {
954
- if (!nc)
955
- return;
956
- this.disableLibraryReconnect(nc);
957
- await nc.close();
958
- if (!nc.isClosed())
959
- throw new Error("endpoint connection closure is unproved; consumer custody must be retained");
960
- this.ownedConnections.delete(nc);
961
- }
962
- /** Disable nats-core reconnect shortly before the JWT authenticated on this wire expires. The small
963
- * lead makes the policy change precede the broker's expiry close even when both timers wake in the
964
- * same event-loop turn. A credential adoption does not move this fence until the resident reconnect
965
- * is requested, so the old wire remains protected during the prove-then-adopt window. */
736
+ /** Forwards to the credentials component's {@link EndpointCredentials.armAuthExpiryReconnectFence}. */
966
737
  armAuthExpiryReconnectFence(nc) {
967
- clearTimeout(this.authExpiryReconnectTimer);
968
- this.authExpiryReconnectTimer = undefined;
969
- const credsExp = this.currentCreds && credsClaims(this.currentCreds).exp;
970
- const expiryMs = this.userMode && this.currentBearer
971
- ? bearerExpiryMs(this.currentBearer)
972
- : typeof credsExp === "number"
973
- ? credsExp * 1000
974
- : undefined;
975
- if (expiryMs === undefined || this.stopped)
976
- return;
977
- // Node fires a delay above 2^31-1 ms (about 24.8 days) after 1 ms, which would disable reconnect
978
- // at once. A later expiry waits in steps of that bound, and the fence is armed again from there.
979
- const delay = Math.max(0, expiryMs - Date.now() - 500);
980
- this.authExpiryReconnectTimer = delay > MAX_TIMER_MS
981
- ? setTimeout(() => { if (this.nc === nc)
982
- this.armAuthExpiryReconnectFence(nc); }, MAX_TIMER_MS)
983
- : setTimeout(() => { if (this.nc === nc)
984
- this.disableLibraryReconnect(nc); }, delay);
985
- this.authExpiryReconnectTimer.unref?.();
986
- }
987
- /** The connectAndBind PRE-CONNECT fetch: pull the freshest source cred and pin it into
988
- * {@link currentCreds} so the connect() that immediately follows presents it — that connect IS the
989
- * proof, so NO preflight and NO live swap here. THROWS when `initial` (no cred to start from), else
990
- * emits and retries. The LIVE-SWAP paths — the 75% timer {@link renewCredsOnTimer} and the explicit
991
- * {@link reloadCreds} — preflight the candidate on a disposable connection instead, so they never
992
- * reconnect the live connection onto an unproven cred. */
993
- async refreshCreds(initial = false) {
994
- try {
995
- await this.fetchFreshCreds();
996
- }
997
- catch (e) {
998
- if (initial)
999
- throw e;
1000
- this.emitRecoverable(new Error(`creds refresh failed (${e instanceof Error ? e.message : String(e)}) - retrying; this connection dies at its current JWT's expiry if renewal keeps failing`));
1001
- this.armCredsRefresh(CotalEndpoint.CREDS_RETRY_MS);
1002
- }
738
+ return this.credentials.armAuthExpiryReconnectFence(nc);
1003
739
  }
1004
- /** Serializes every prove-then-adopt transaction (the 75% timer and the explicit reload) so a timer
1005
- * tick and an explicit reload can never interleave their fetch/preflight/commit — the design's
1006
- * single-flight requirement. Runs `fn` after any in-flight transaction settles, whatever its
1007
- * outcome; the internal chain never rejects. */
1008
- credsTxn = Promise.resolve();
1009
- runCredsTxn(fn) {
1010
- const counted = async () => {
1011
- this.credsTxnsRunning++;
1012
- try {
1013
- return await fn();
1014
- }
1015
- finally {
1016
- this.credsTxnsRunning--;
1017
- }
1018
- };
1019
- const next = this.credsTxn.then(counted, counted);
1020
- this.credsTxn = next.then(() => undefined, () => undefined);
1021
- return next;
740
+ /** Forwards to the credentials component's {@link EndpointCredentials.refreshCreds}. */
741
+ refreshCreds(initial = false) {
742
+ return this.credentials.refreshCreds(initial);
1022
743
  }
1023
- /** The one PROVE-then-adopt transaction shared by the 75% timer and the explicit reload (run under
1024
- * {@link runCredsTxn}). Fetch (deadline-bounded) → identity-pin → optional `expected` fingerprint →
1025
- * PREFLIGHT the candidate on a disposable connection → fence a late commit against the deadline →
1026
- * commit {@link currentCreds} → arm the next 75% timer. Because currentCreds is written ONLY after
1027
- * the preflight proves broker acceptance, the resident authenticator getter can never present an
1028
- * unproven cred (not even on an incidental reconnect), and a rejected candidate leaves the resident
1029
- * connection untouched on BOTH the timer and explicit paths. THROWS (structured) on any failure. */
1030
- async adoptFreshCreds(opts = {}) {
1031
- // ABSOLUTE deadline, captured at the CALLER's entry (reloadCreds / renewCredsOnTimer) BEFORE the
1032
- // single-flight enqueue, so the queue wait behind an in-flight transaction counts against it. A
1033
- // reload queued behind a hung-store timer tick can never receive a FRESH budget and commit after
1034
- // the renewal owner's request bound already elapsed.
1035
- const deadline = opts.deadline ?? Date.now() + CotalEndpoint.RELOAD_DEADLINE_MS;
1036
- // Fence BEFORE any source I/O: if the queue wait already burned the budget, fail structured now and
1037
- // never touch the store, the preflight, or currentCreds.
1038
- if (Date.now() > deadline)
1039
- throw new Error("reloadCreds: the request deadline elapsed while queued behind another credential transaction; nothing adopted");
1040
- const candidate = await withDeadline(this.credsSource(), deadline - Date.now(), () => new Error("reloadCreds: the creds source did not return before the daemon deadline; nothing adopted"));
1041
- const id = idFromCreds(candidate);
1042
- if (id !== this.connId)
1043
- throw new Error(`creds source returned identity ${id}, expected ${this.connId} - renewal may not swap the connection's nkey`);
1044
- // Non-material message ON PURPOSE: this text flows to the manager's persisted
1045
- // `RenewalRecord.adoption.error`, so neither the observed nor the expected digest may appear.
1046
- if (opts.expected !== undefined && credsFingerprint(candidate) !== opts.expected)
1047
- throw new Error("reloadCreds: re-read credential generation did not match the expected re-signed generation (a different store, or a torn/stale read); nothing adopted");
1048
- // PREFLIGHT = the proof. A disposable connection presenting exactly the candidate BEFORE the live
1049
- // cache is touched; a refused cred throws here, leaving the resident connection untouched.
1050
- // The candidate goes through the SAME checkpoint the resident getter uses: this is the one
1051
- // presentation that does not read the cache, so routing it here is what makes the refusal a
1052
- // property of every path rather than of the cached one. An already-dead re-signed generation is
1053
- // refused locally instead of spending a round trip to be told so, and — because this throws
1054
- // BEFORE the commit below — it can never become the resident connection's next-presented cred.
1055
- const proven = CotalEndpoint.presentableCreds(candidate, { renewable: true });
1056
- const probe = await probeConnect(this.servers, { creds: proven, tls: this.tls, timeoutMs: Math.max(500, Math.min(CotalEndpoint.PREFLIGHT_MS, deadline - Date.now())) });
1057
- if (!probe.ok)
1058
- throw new Error(`reloadCreds: the broker did not accept the re-signed credential (${probe.reason}); nothing adopted`);
1059
- if (Date.now() > deadline)
1060
- throw new Error("reloadCreds: the proof exceeded the daemon deadline; nothing adopted"); // fence a late commit
1061
- // Validate the bounded-window renewal delay BEFORE the commit: credsRenewalDelayMs throws on a cred
1062
- // lacking a numeric `exp`, and that throw must not leave currentCreds flipped to a candidate the
1063
- // authenticator would present on the next reconnect (a post-preflight validation failure is a no-op).
1064
- const delay = credsRenewalDelayMs(candidate);
1065
- CotalEndpoint.assertRenewableGeneration(candidate, this.currentCreds, delay);
1066
- this.currentCreds = candidate;
1067
- this.armCredsRefresh(delay);
1068
- this.emit("creds-adopted", credsClaims(candidate));
1069
- return credsClaims(candidate);
1070
- }
1071
- /** The 75%-of-lifetime renewal timer tick: prove + adopt + swap the LIVE connection. Preflights (it
1072
- * reconnects a live connection, so the candidate must be broker-proven first) and is serialized
1073
- * with the explicit reload. Never throws — a failed renewal logs and retries while the old cred
1074
- * stays live until its expiry. */
1075
- async renewCredsOnTimer() {
1076
- // Deadline captured HERE, before the enqueue, for the same reason as the explicit reload.
1077
- const deadline = Date.now() + CotalEndpoint.RELOAD_DEADLINE_MS;
1078
- try {
1079
- await this.runCredsTxn(() => this.adoptFreshCreds({ deadline }));
1080
- await this.swapConnectionOntoFreshCreds();
1081
- }
1082
- catch (e) {
1083
- this.emitRecoverable(new Error(`creds refresh failed (${e instanceof Error ? e.message : String(e)}) - retrying; this connection dies at its current JWT's expiry if renewal keeps failing`));
1084
- this.armCredsRefresh(CotalEndpoint.CREDS_RETRY_MS);
1085
- }
744
+ /** Forwards to the credentials component's {@link EndpointCredentials.renewCredsOnTimer}. */
745
+ renewCredsOnTimer() {
746
+ return this.credentials.renewCredsOnTimer();
1086
747
  }
1087
748
  /** Fetch, broker-prove and adopt the source credential, then refresh the same connection
1088
749
  * once outgoing mux and named-reply requests are quiet. A busy timeout retains the connection
1089
750
  * and adopted credential. Call again to retry. This does not tear down endpoint bindings.
1090
751
  * A dropped connection that is being re-established carries no request, so it redials now
1091
752
  * instead of after its backoff; the rebuild re-fetches a stale credential from the source. */
1092
- async refreshCredsRequestSafe() {
1093
- if (!this.credsSource)
1094
- throw new Error("credential refresh requires a creds source");
1095
- const nc = this.nc;
1096
- if (!nc && !this.stopped && (this.reconnecting || this.reestablishing))
1097
- return await this.reconnect();
1098
- if (!nc || this.stopped)
1099
- throw new Error("credential refresh requires a running endpoint");
1100
- const deadline = Date.now() + CotalEndpoint.RELOAD_DEADLINE_MS;
1101
- await this.runCredsTxn(async () => {
1102
- await this.adoptFreshCreds({ deadline });
1103
- if (this.nc !== nc || this.stopped)
1104
- throw new Error("endpoint connection changed during credential refresh");
1105
- await requestSafeReconnect(nc, () => this.requestsAwaitingReply.get(nc)?.size ?? 0);
1106
- if (this.nc === nc && !this.stopped)
1107
- this.armAuthExpiryReconnectFence(nc);
1108
- });
753
+ refreshCredsRequestSafe() {
754
+ return this.credentials.refreshCredsRequestSafe();
1109
755
  }
1110
756
  /** EXPLICIT credential reload — the auditable adoption step of D5 class-2 standing renewal (served
1111
757
  * to the renewal owner via the delivery-admin rail). The PROOF-OF-RECORD is a DISPOSABLE PREFLIGHT
@@ -1122,51 +768,12 @@ export class CotalEndpoint extends EventEmitter {
1122
768
  * the resident wire swap is best-effort and self-healing (the 75% timer + the broker's expiry-close),
1123
769
  * NOT witnessed, so the caller must claim broker acceptance, not verified resident reauth. NEVER a
1124
770
  * fingerprint. */
1125
- async reloadCreds(expected) {
1126
- if (!this.credsSource)
1127
- throw new Error("reloadCreds: this endpoint has no creds source (a static cred cannot be renewed in place)");
1128
- // Capture the ABSOLUTE deadline at ENTRY, before enqueue, so a reload queued behind a hung-store
1129
- // 75% timer tick is bounded by the SAME window (queue wait included) and cannot commit/swap after
1130
- // the renewal owner's request bound has already elapsed and it recorded "no responder".
1131
- const deadline = Date.now() + CotalEndpoint.RELOAD_DEADLINE_MS;
1132
- // The prove-then-adopt transaction (fetch + preflight + commit) runs under the single-flight so it
1133
- // cannot interleave with the 75% timer; the wire swap is scheduled by {@link handleDeliveryAdmin}
1134
- // after the aggregate reply (the responder rides this connection).
1135
- const { iat, exp } = await this.runCredsTxn(() => this.adoptFreshCreds({ expected, deadline }));
1136
- return { identity: this.connId, iat, exp };
1137
- }
1138
- /** Arm the resident wire swap for the delivery-admin `reloadCreds` path. Called by
1139
- * {@link handleDeliveryAdmin} ONLY after BOTH component proofs have settled and immediately before
1140
- * the reply is returned+responded — never from inside {@link reloadCreds} while the aggregate is
1141
- * still open, or a slow co-component proof would let `nc.reconnect()` reconnect the admin rail
1142
- * before the reply flushes and silently strand it. The short deferral lets the reply flush on the
1143
- * still-live old cred first. Best-effort — the proof was the preflight; a transient swap failure is
1144
- * retried by the 75% timer and the broker's own expiry-close, both presenting the adopted candidate.
1145
- * Until the swapped connection is back, {@link residentSwap} holds the delivery-admin requests that
1146
- * arrive after this reply. */
771
+ reloadCreds(expected) {
772
+ return this.credentials.reloadCreds(expected);
773
+ }
774
+ /** Forwards to the credentials component's {@link EndpointCredentials.scheduleResidentSwap}. */
1147
775
  scheduleResidentSwap() {
1148
- if (this.stopped)
1149
- return;
1150
- const swap = new Promise((resolve) => { setTimeout(resolve, CotalEndpoint.RESIDENT_SWAP_DEFER_MS).unref?.(); })
1151
- .then(async () => {
1152
- const back = this.transportBack(CotalEndpoint.RESIDENT_SWAP_GATE_MS);
1153
- await this.swapConnectionOntoFreshCreds();
1154
- await back;
1155
- })
1156
- .finally(() => { if (this.residentSwap === swap)
1157
- this.residentSwap = undefined; });
1158
- this.residentSwap = swap;
1159
- }
1160
- /** Resolve when this endpoint reports its transport connected again, or after `ms`. */
1161
- transportBack(ms) {
1162
- return new Promise((resolve) => {
1163
- const done = () => { clearTimeout(timer); this.off("transport", seen); resolve(); };
1164
- const seen = (state) => { if (state.connected)
1165
- done(); };
1166
- const timer = setTimeout(done, ms);
1167
- timer.unref?.();
1168
- this.on("transport", seen);
1169
- });
776
+ return this.credentials.scheduleResidentSwap();
1170
777
  }
1171
778
  armCredsRefresh(delayMs) {
1172
779
  if (this.stopped)
@@ -1194,461 +801,167 @@ export class CotalEndpoint extends EventEmitter {
1194
801
  throw error;
1195
802
  }
1196
803
  }
1197
- async bindConnection() {
1198
- this.clearConnectionScoped();
1199
- // Bearer-source endpoints fetch before the FIRST connect, and renew first on a rebuild whose
1200
- // cached token is past its renewal window (a rebuild after a long outage would otherwise
1201
- // present a dead bearer). While renewals are failing, their retry timer owns the source: a
1202
- // fetch here too would add one call to the exchange per rebuild attempt.
1203
- if (this.bearerSource) {
1204
- if (!this.currentBearer)
1205
- await this.refreshBearer(true);
1206
- else if (this.bearerRenewalFailures === 0 && Date.now() >= bearerRenewalDeadlineMs(this.currentBearer, this.bearerAdoptedAtMs))
1207
- await this.refreshBearer();
1208
- }
1209
- // Creds-source endpoints likewise fetch before the FIRST connect, and re-fetch on a rebuild
1210
- // whose cached cred is expired or inside its renewal window.
1211
- if (this.credsSource) {
1212
- const stale = !this.currentCreds || credsRenewalDelayMs(this.currentCreds) <= 0;
1213
- if (stale)
1214
- await this.refreshCreds(!this.currentCreds);
1215
- }
1216
- // Never dial with material we can already prove is dead. The refresh above is best-effort (a
1217
- // failed renewal emits and retries rather than throwing, so a dead auth service does not
1218
- // instantly drop a still-live mesh), which used to leave the connect below presenting an
1219
- // EXPIRED bearer: a guaranteed denial that still costs a full auth-callout round trip, repeated
1220
- // by the reestablish loop at a flat rate for as long as the process lives. Refuse here instead.
1221
- // The loop's capped backoff paces the retries and re-enters this method, and a renewal that
1222
- // starts working ends its wait; an endpoint with no bearer source cannot renew at all, and says
1223
- // so. The refusal is surfaced once per outage: the loop retries a repeat without a notice.
1224
- if (this.userMode) {
1225
- try {
1226
- this.bearerForWire();
1227
- this.bearerRefusalSurfaced = false;
1228
- }
1229
- catch (e) {
1230
- if (!this.bearerRefusalSurfaced) {
1231
- this.bearerRefusalSurfaced = true;
1232
- throw e;
1233
- }
1234
- throw new RepeatedRefusal(e.message);
1235
- }
1236
- }
1237
- // The CREDS refusal is NOT repeated here. It lives on the supply itself ({@link credsForWire}),
1238
- // which the authenticator below re-reads per attempt, so it covers this dial AND the reconnects
1239
- // nats.js runs on its own. Raising it early here too would only duplicate it on the one path
1240
- // that was already covered, and a fourth dial site added later would silently miss the copy.
1241
- // The refusal still surfaces on this path: the authenticator throws during the CONNECT, the
1242
- // library closes that attempt, and the reestablish loop's capped backoff re-enters here — where
1243
- // the source re-fetch above is what recovers a renewable endpoint.
1244
- let watchDeletePermission;
1245
- this.nc = await dialerFor(this.servers)({
1246
- servers: this.servers,
1247
- // Keep native failures without eagerly capturing a request-origin stack on every operation.
1248
- noAsyncTraces: true,
1249
- // In USER MODE the connection `name` carries the client-chosen inbox nonce (= connId) the callout
1250
- // scopes `_INBOX_<connId>.>` on (see EndpointOptions.bearer); otherwise it's the display handle.
1251
- name: this.userMode ? this.connId : `cotal:${this.card.name}`,
1252
- // Per-CONNECTION inbox namespace (the "Private Inbox" pattern), keyed on the connection nkey
1253
- // (NOT the owner+actor principal): the reply inbox is per-connection plumbing, and under the auth
1254
- // callout the principal is unknown to the client pre-connect (owner is derived server-side) while
1255
- // the connection id always is. nats.js routes ALL generated inboxes — request replies, JetStream
1256
- // pull delivery, kv.watch ordered-consumer delivery — through this prefix. Paired with
1257
- // sub.allow=[_INBOX_<connId>.>] it stops a peer from subscribing the wildcard inbox to sniff
1258
- // others' DM deliveries. Set unconditionally so the prefix can never drift from the ACL.
1259
- inboxPrefix: `_INBOX_${this.connId}`,
1260
- ...(this.transportPingIntervalMs === undefined ? {} : { pingInterval: this.transportPingIntervalMs }),
1261
- ...(this.transportMaxPingOut === undefined ? {} : { maxPingOut: this.transportMaxPingOut }),
1262
- ...(this.transportConnectTimeoutMs === undefined ? {} : { timeout: this.transportConnectTimeoutMs }),
1263
- // The bearer rides the CHECKED getter: nats.js re-evaluates the token authenticator per
1264
- // (re)connect attempt, so internal reconnects present whatever refreshBearer last fetched,
1265
- // and refuse a token that has expired since, as the creds getter does.
1266
- // Creds ALWAYS ride the CHECKED getter, renewed or static, so every attempt — including the
1267
- // reconnects nats.js performs on its own (the one the broker forces at JWT `exp`, and a dial
1268
- // loop from an earlier drop that crosses `exp` mid-retry) — re-reads a credential that has
1269
- // just been proven unexpired rather than whatever the cache happens to hold.
1270
- // The gate is `!== undefined`, NOT truthiness. An EMPTY creds string is a caller that meant to
1271
- // authenticate and supplied nothing; on a truthiness gate it fell through to `creds: undefined`
1272
- // and dialed ANONYMOUSLY, so the broker answered `Authorization Violation` and the real fault
1273
- // (an empty credential) was never named. Routing it into the checked getter fails it loud
1274
- // instead. Anonymous access stays reachable the only way it should be: by passing no creds.
1275
- ...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,
1276
- onCreds: (creds) => {
1277
- watchDeletePermission = undefined;
1278
- try {
1279
- const nats = credsClaims(creds).nats;
1280
- if (nats?.pub !== undefined)
1281
- watchDeletePermission = importNativeSubjectPermissions({ pub: nats.pub }).publish;
1282
- }
1283
- catch {
1284
- // Unknown/malformed claims cannot prove a denial. Keep the existing broker check.
1285
- }
1286
- },
1287
- }),
1288
- });
1289
- // SPEC §13.12: the control surface requires nats-server >= 2.12; this runs on every
1290
- // fresh connection, including the reconnects the library performs on its own here.
1291
- this.watchDeletePermissions.set(this.nc, () => watchDeletePermission);
1292
- this.ownedConnections.add(this.nc);
1293
- const owned = this.nc;
1294
- void owned.closed().then(() => this.ownedConnections.delete(owned));
1295
- this.onConnection?.(this.nc);
1296
- requireBrokerFloor(this.nc);
1297
- this.armAuthExpiryReconnectFence(this.nc);
1298
- this.watchStatus();
1299
- this.js = jetstream(this.nc);
1300
- // DM-only (EndpointOptions.dmOnly): the own DM durable is the whole binding. Nothing below runs:
1301
- // no accepted-row read, presence, channel registry, JetStream manager, lease, membership,
1302
- // Plane-3 or liveness responder, so the credential needs no row for any of them.
1303
- if (this.dmOnly) {
1304
- await this.beforeBind?.();
1305
- if (this.stopped)
1306
- return;
1307
- await this.bindDmOnly(this.dmOnly);
1308
- if (this.stopped)
1309
- return;
1310
- this.emit("connection", { connected: true });
1311
- return;
1312
- }
1313
- // Discovery of the issued generation (SPEC 13.15): the ISSUER wrote the accepted reference
1314
- // under the token this launch was handed; the broker admits the read only under this
1315
- // connection's own per-key grant. What comes back must name this incarnation, and a fresh
1316
- // connection re-reads it: the generation is bound to the credential the transport presented,
1317
- // never to a file that may have been replaced under it.
1318
- if (this.acceptedToken !== undefined) {
1319
- const ref = await readAcceptedRow(this.nc, this.space, this.acceptedToken);
1320
- const uid = this.requireLifecycleUid("an issued endpoint");
1321
- if (ref.owner !== this.owner || ref.actor !== this.actor || ref.uid !== uid)
1322
- 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)`);
1323
- this.issuedGeneration = ref.generation;
1324
- }
1325
- await this.beforeBind?.();
1326
- if (this.stopped)
1327
- return;
1328
- if (this.doWatch || this.doRegister) {
1329
- const kvm = new Kvm(this.nc);
1330
- // The presence bucket is a JetStream stream. Open mode lazily creates it; auth mode
1331
- // OPENs it (it's pre-created at `cotal up`; KV stream-create is denied to agents).
1332
- this.kv = this.authed
1333
- ? await kvm.open(presenceBucket(this.space))
1334
- : await kvm.create(presenceBucket(this.space), { ttl: this.ttlMs, storage: PRESENCE_STORAGE });
1335
- }
1336
- if (this.doWatch && this.readOnce)
1337
- await this.readPresenceOnce();
1338
- else if (this.doWatch) {
1339
- await this.startPresenceWatch();
1340
- this.sweepTimer = setInterval(() => this.sweep(), Math.max(500, Math.floor(this.ttlMs / 3)));
1341
- }
1342
- // Open the channel registry bucket when we either watch it (live cache for the connector's
1343
- // pull/display) or consume (the join-time replay decision reads it fresh). A presence-only
1344
- // supervisor (watchChannels:false, consume:false) skips it entirely — it needs no channel cache,
1345
- // so its scoped cred holds no channel-registry read (residual 2). Auth mode OPENs the bucket
1346
- // pre-created at `cotal up`; open mode lazily creates it.
1347
- const watchChannels = this.doWatch && this.doWatchChannels;
1348
- if (watchChannels || this.doConsume) {
1349
- this.channelKv = await openChannelRegistry(this.nc, this.space, { create: !this.authed });
1350
- if (watchChannels)
1351
- await (this.readOnce ? this.readChannelsOnce() : this.startChannelWatch());
1352
- // A seat reads the registry on demand, as it reads the roster; this first read fills the cache
1353
- // its boot briefing renders from.
1354
- else if (this.readsChannelsOnDemand)
1355
- await this.readChannels();
1356
- }
1357
- // Rebind the daemon's lease-loss watch onto the fresh connection (#1596). The intent survived
1358
- // clearConnectionScoped; a bind that completes after a stop or another rebuild finds the epoch
1359
- // moved and retires itself. The replay re-delivers the row's current state, so a change that
1360
- // landed in the null window still reaches the trigger.
1361
- if (this.deliveryLease.hasWatchIntent)
1362
- await this.bindDeliveryLeaseWatch();
1363
- // FAIL BEFORE PRESENCE (SPEC 13.1): an AUTHED endpoint that will register on the roster or
1364
- // bind lifecycle-keyed consumers must hold its launcher-supplied lifecycle uid BEFORE anything
1365
- // makes it visible - a missing uid must never leave a roster ghost that could not bind (false
1366
- // readiness). Non-registering, non-consuming infra endpoints (a provisioner window, the
1367
- // delivery daemon, one-shot CLI probes) bind no lifecycle-keyed names and stay outside the
1368
- // rule; open/token mode self-minted at construction, so this only ever throws for a
1369
- // mis-launched AUTH endpoint.
1370
- if (this.authed && (this.doConsume || this.doRegister))
1371
- this.requireLifecycleUid(this.doConsume ? "an authed consuming endpoint" : "an authed presence-registering endpoint");
1372
- // Consumers bind BEFORE presence publishes: the durable bind is the broker's proof that this
1373
- // incarnation's lifecycle-keyed names match its minted grants, so a wrong-uid launch dies
1374
- // with NO presence ghost instead of advertising an agent that can never receive.
1375
- if (this.doConsume) {
1376
- this.jsm = await jetstreamManager(this.nc);
1377
- // Open mode: lazily create the streams on the first endpoint. Auth mode: they are
1378
- // pre-created at `cotal up` and STREAM.CREATE is denied to agents, so skip.
1379
- if (!this.authed)
1380
- await this.ensureStreams();
1381
- await this.startConsumers();
1382
- }
1383
- // The register-only broker proof: a consuming agent proved its lifecycle by binding a
1384
- // durable above, but an authed AGENT that only REGISTERS presence (consume:false) has bound
1385
- // nothing yet, so a wrong-but-valid uid would grammar-pass requireLifecycleUid and then
1386
- // advertise a ghost that can receive nothing. Prove the incarnation at the broker FIRST — an
1387
- // exact info on this agent's own pre-provisioned dm_<owner>-<actor>-<uid> durable (the
1388
- // manager/self-provision minted it under the SAME uid). A wrong uid names a durable that
1389
- // does not exist, so the info throws and presence never publishes. Only for `kind: "agent"`
1390
- // (a peer on the roster); pure `kind: "endpoint"` infra (manager, delivery, feedback intake)
1391
- // holds no dm_ durable and stays exempt.
1392
- if (this.doRegister && !this.doConsume && this.authed && this.card.kind === "agent") {
1393
- const jsm = this.jsm ?? (this.jsm = await jetstreamManager(this.nc));
1394
- const uid = this.requireLifecycleUid("an authed presence-registering agent");
1395
- try {
1396
- await jsm.consumers.info(dmStream(this.space), dmDurable(this.owner, this.actor, uid));
1397
- }
1398
- catch (e) {
1399
- 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)}`);
1400
- }
1401
- }
1402
- if (this.doRegister) {
1403
- // #1356: this await is bounded already — a refused presence write returns no response at all,
1404
- // so it surfaces as the JetStream request TIMEOUT (~5s), once, with no retry here. What it did
1405
- // NOT do was say what failed: the bare `timeout` names no bucket, no space and no subsystem,
1406
- // and a launcher that catches it has nothing to act on. The lifecycle-proof failure a few lines
1407
- // above throws a fully explanatory message; this one is held to the same standard. Still fails
1408
- // rather than degrading — SPEC 13.1 fail-before-presence means a registering agent that cannot
1409
- // publish presence must not come up as though it had.
1410
- try {
1411
- await this.publishPresence();
1412
- }
1413
- catch (e) {
1414
- const detail = e?.message ?? String(e);
1415
- 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).`);
1416
- }
1417
- // Beat at this endpoint's own phase. A repeating timer re-arms from the instant its callback
1418
- // ran, and every timer run in one timers pass re-arms to the same instant, so the heartbeats of
1419
- // many endpoints in one process that once coincided stay coincident and the loop takes the whole
1420
- // batch in one tick (5088 endpoints in one process: 1 to 2 s stalls, with the put deadlines
1421
- // expiring inside them). Re-arming from the scheduled beat keeps each endpoint's phase.
1422
- const phase = Date.now();
1423
- let beat = 0;
1424
- const arm = () => {
1425
- const next = nextHeartbeat(phase, this.heartbeatMs, beat, Date.now());
1426
- beat = next.beat;
1427
- const handle = setTimeout(() => {
1428
- this.publishPresence().catch((e) => this.emitRecoverable(e));
1429
- if (this.heartbeatTimer === handle)
1430
- arm();
1431
- }, next.delayMs);
1432
- this.heartbeatTimer = handle;
1433
- };
1434
- arm();
1435
- }
1436
- // Caller-owned membership watches are INTENT rather than one-connection iterators. Re-open them
1437
- // before reporting the endpoint connected, so a successful reconnect does not leave the graph stale.
1438
- await this.rearmMembershipWatches();
1439
- // Re-arm Plane-3 (delivery-daemon-hosted fan-out + trusted reader + ctl.delivery) on every (re)connect — no-op unless this
1440
- // endpoint hosts it. The first arm comes from startPlane3 (after start()); this re-binds the loops
1441
- // a reconnect's clearConnectionScoped() tore down, so a broker blip doesn't silently kill the backstop.
1442
- await this.armPlane3();
1443
- // Re-bind the liveness responders on this connection, for armPlane3's reason: the rebuild closed
1444
- // the old connection and the responders with it.
1445
- for (const plane of this.livenessResponders.keys())
1446
- this.bindLiveness(plane);
1447
- // The principal serves subscribe again on the new connection and run their check again.
1448
- this.rebindPrincipalServes(false);
1449
- for (const tap of this.taps)
1450
- this.bindTap(tap);
1451
- // Bound and live — covers initial start, manual reconnect, AND background self-heal (every
1452
- // path lands here). The single signal an in-process agent's connected flag tracks.
1453
- //
1454
- // The stopped guard: stop() can land in any await above. Both callers tear the fresh
1455
- // connection back down (tearDownIfStopped), but an event has no undo, so a late
1456
- // `connection: true` would be the last edge a listener ever sees on a stopped endpoint and
1457
- // nothing follows it to correct the record. It belongs here rather than in a consumer because
1458
- // every listener reads the same edge; MeshAgent carries its own `stopping` guard and so was
1459
- // never the one exposed, which is the point.
1460
- //
1461
- // Measured for the start() caller by the broker suite's mid-bind cell. doRebuild is
1462
- // also measured, by a separate cell that holds the rebuild's connectAndBind at
1463
- // armPlane3 after a successful first bind and lands stop() in that window (#1028).
1464
- // Shared-line reasoning is no longer the rebuild proof.
1465
- if (this.stopped)
1466
- return;
1467
- this.emit("connection", { connected: true });
1468
- if (this.nc) {
1469
- for (const follower of this.activeGoalFollowers) {
1470
- follower.reconnected(this.nc);
1471
- }
1472
- }
804
+ /** The connection bind and teardown of this endpoint. Every dependency is read when it is used, so a
805
+ * field assigned after construction is seen. */
806
+ connection = new EndpointConnection({
807
+ bearerSource: () => this.bearerSource,
808
+ currentBearer: () => this.currentBearer,
809
+ bearerRenewalFailures: () => this.bearerRenewalFailures,
810
+ bearerAdoptedAtMs: () => this.bearerAdoptedAtMs,
811
+ credsSource: () => this.credsSource,
812
+ currentCreds: () => this.currentCreds,
813
+ userMode: () => this.userMode,
814
+ bearerRefusalSurfaced: () => this.bearerRefusalSurfaced,
815
+ setBearerRefusalSurfaced: (value) => { this.bearerRefusalSurfaced = value; },
816
+ nc: () => this.nc,
817
+ setNc: (value) => { this.nc = value; },
818
+ servers: () => this.servers,
819
+ connId: () => this.connId,
820
+ card: () => this.card,
821
+ transportPingIntervalMs: () => this.transportPingIntervalMs,
822
+ transportMaxPingOut: () => this.transportMaxPingOut,
823
+ transportConnectTimeoutMs: () => this.transportConnectTimeoutMs,
824
+ token: () => this.token,
825
+ user: () => this.user,
826
+ pass: () => this.pass,
827
+ sentinelCreds: () => this.sentinelCreds,
828
+ tls: () => this.tls,
829
+ watchDeletePermissions: () => this.watchDeletePermissions,
830
+ ownedConnections: () => this.ownedConnections,
831
+ onConnection: () => this.onConnection,
832
+ js: () => this.js,
833
+ setJs: (value) => { this.js = value; },
834
+ dmOnly: () => this.dmOnly,
835
+ beforeBind: () => this.beforeBind,
836
+ stopped: () => this.stopped,
837
+ setStopped: (value) => { this.stopped = value; },
838
+ acceptedToken: () => this.acceptedToken,
839
+ space: () => this.space,
840
+ owner: () => this.owner,
841
+ actor: () => this.actor,
842
+ issuedGeneration: () => this.issuedGeneration,
843
+ setIssuedGeneration: (value) => { this.issuedGeneration = value; },
844
+ doWatch: () => this.doWatch,
845
+ doRegister: () => this.doRegister,
846
+ kv: () => this.kv,
847
+ setKv: (value) => { this.kv = value; },
848
+ authed: () => this.authed,
849
+ ttlMs: () => this.ttlMs,
850
+ readOnce: () => this.readOnce,
851
+ sweepTimer: () => this.sweepTimer,
852
+ setSweepTimer: (value) => { this.sweepTimer = value; },
853
+ doWatchChannels: () => this.doWatchChannels,
854
+ doConsume: () => this.doConsume,
855
+ channelKv: () => this.channelKv,
856
+ setChannelKv: (value) => { this.channelKv = value; },
857
+ readsChannelsOnDemand: () => this.readsChannelsOnDemand,
858
+ deliveryLease: () => this.deliveryLease,
859
+ jsm: () => this.jsm,
860
+ setJsm: (value) => { this.jsm = value; },
861
+ heartbeatMs: () => this.heartbeatMs,
862
+ heartbeatTimer: () => this.heartbeatTimer,
863
+ setHeartbeatTimer: (value) => { this.heartbeatTimer = value; },
864
+ livenessResponders: () => this.livenessResponders,
865
+ taps: () => this.taps,
866
+ activeGoalFollowers: () => this.activeGoalFollowers,
867
+ authExpiryReconnectTimer: () => this.authExpiryReconnectTimer,
868
+ setAuthExpiryReconnectTimer: (value) => { this.authExpiryReconnectTimer = value; },
869
+ streamMsgs: () => this.streamMsgs,
870
+ presenceEpoch: () => this.presenceEpoch,
871
+ setPresenceEpoch: (value) => { this.presenceEpoch = value; },
872
+ presence: () => this.presence,
873
+ channelWatchIter: () => this.channelWatchIter,
874
+ setChannelWatchIter: (value) => { this.channelWatchIter = value; },
875
+ chatSubs: () => this.chatSubs,
876
+ chatSubDenied: () => this.chatSubDenied,
877
+ ownWatchDeletePrefixes: () => this.ownWatchDeletePrefixes,
878
+ channelConfigs: () => this.channelConfigs,
879
+ channelDefaults: () => this.channelDefaults,
880
+ setChannelDefaults: (value) => { this.channelDefaults = value; },
881
+ channelRead: () => this.channelRead,
882
+ setChannelRead: (value) => { this.channelRead = value; },
883
+ channelReadGeneration: () => this.channelReadGeneration,
884
+ setChannelReadGeneration: (value) => { this.channelReadGeneration = value; },
885
+ channelReadApplied: () => this.channelReadApplied,
886
+ setChannelReadApplied: (value) => { this.channelReadApplied = value; },
887
+ membershipFeedWatches: () => this.membershipFeedWatches,
888
+ membersKv: () => this.membersKv,
889
+ setMembersKv: (value) => { this.membersKv = value; },
890
+ aclKv: () => this.aclKv,
891
+ setAclKv: (value) => { this.aclKv = value; },
892
+ membershipFeedKv: () => this.membershipFeedKv,
893
+ setMembershipFeedKv: (value) => { this.membershipFeedKv = value; },
894
+ managerLeaseKv: () => this.managerLeaseKv,
895
+ setManagerLeaseKv: (value) => { this.managerLeaseKv = value; },
896
+ daemonRenewalLeaseRevision: () => this.daemonRenewalLeaseRevision,
897
+ setDaemonRenewalLeaseRevision: (value) => { this.daemonRenewalLeaseRevision = value; },
898
+ deliveryPlane: () => this.deliveryPlane,
899
+ subs: () => this.subs,
900
+ principalServes: () => this.principalServes,
901
+ membershipPauses: () => this.membershipPauses,
902
+ cancelBearerRenewal: () => this.cancelBearerRenewal,
903
+ credsTimer: () => this.credsTimer,
904
+ dmOnlyInFlight: () => this.dmOnlyInFlight,
905
+ rebuildPromise: () => this.rebuildPromise,
906
+ startPromise: () => this.startPromise,
907
+ reconnecting: () => this.reconnecting,
908
+ credsTxnsRunning: () => this.credsTxnsRunning,
909
+ residentSwap: () => this.residentSwap,
910
+ nativeBound: () => this.nativeBound,
911
+ refreshBearer: (initial) => this.refreshBearer(initial),
912
+ refreshCreds: (initial) => this.refreshCreds(initial),
913
+ bearerForWire: () => this.bearerForWire(),
914
+ presentCreds: () => this.presentCreds(),
915
+ presentBearer: () => this.presentBearer(),
916
+ armAuthExpiryReconnectFence: (nc) => this.armAuthExpiryReconnectFence(nc),
917
+ watchStatus: () => this.watchStatus(),
918
+ bindDmOnly: (mode) => this.bindDmOnly(mode),
919
+ requireLifecycleUid: (what) => this.requireLifecycleUid(what),
920
+ readPresenceOnce: () => this.readPresenceOnce(),
921
+ startPresenceWatch: () => this.startPresenceWatch(),
922
+ sweep: () => this.sweep(),
923
+ readChannelsOnce: () => this.readChannelsOnce(),
924
+ startChannelWatch: () => this.startChannelWatch(),
925
+ readChannels: () => this.readChannels(),
926
+ bindDeliveryLeaseWatch: () => this.bindDeliveryLeaseWatch(),
927
+ ensureStreams: () => this.ensureStreams(),
928
+ startConsumers: () => this.startConsumers(),
929
+ publishPresence: () => this.publishPresence(),
930
+ emitRecoverable: (err) => this.emitRecoverable(err),
931
+ rearmMembershipWatches: () => this.rearmMembershipWatches(),
932
+ armPlane3: () => this.armPlane3(),
933
+ bindLiveness: (plane) => this.bindLiveness(plane),
934
+ rebindPrincipalServes: (reconnected) => this.rebindPrincipalServes(reconnected),
935
+ bindTap: (tap) => this.bindTap(tap),
936
+ retireKvWatch: (iter) => this.retireKvWatch(iter),
937
+ stopDeliveryLeaseWatch: () => this.stopDeliveryLeaseWatch(),
938
+ disarmMembershipWatch: (watch) => this.disarmMembershipWatch(watch),
939
+ disableLibraryReconnect: (nc) => this.disableLibraryReconnect(nc),
940
+ dropAnycastRequests: () => this.dropAnycastRequests(),
941
+ closeWithoutLibraryReconnect: (nc) => this.closeWithoutLibraryReconnect(nc),
942
+ stopPrincipalServe: (intent, republish) => this.stopPrincipalServe(intent, republish),
943
+ kickBackoff: () => this.kickBackoff(),
944
+ deleteRetainedMembershipConsumer: (watch) => this.deleteRetainedMembershipConsumer(watch),
945
+ settleDeliveryLeaseWatches: () => this.settleDeliveryLeaseWatches(),
946
+ settleKvWatches: () => this.settleKvWatches(),
947
+ clearPresenceWriteFailure: () => this.clearPresenceWriteFailure(),
948
+ emit: (event, ...args) => this.emit(event, ...args),
949
+ });
950
+ /** Forwards to the connection component's {@link EndpointConnection.bindConnection}. */
951
+ bindConnection() {
952
+ return this.connection.bindConnection();
1473
953
  }
1474
- /** Tear down everything {@link connectAndBind} (re)creates, so a rebind can't leak a
1475
- * second heartbeat, double-pump a consumer, or keep stale roster ghosts. Caller-owned
1476
- * subs (tap/serve) are left alone — they aren't rebuilt here. */
954
+ /** Forwards to the connection component's {@link EndpointConnection.clearConnectionScoped}. */
1477
955
  clearConnectionScoped() {
1478
- if (this.authExpiryReconnectTimer) {
1479
- clearTimeout(this.authExpiryReconnectTimer);
1480
- this.authExpiryReconnectTimer = undefined;
1481
- }
1482
- if (this.heartbeatTimer) {
1483
- clearInterval(this.heartbeatTimer);
1484
- this.heartbeatTimer = undefined;
1485
- }
1486
- if (this.sweepTimer) {
1487
- clearInterval(this.sweepTimer);
1488
- this.sweepTimer = undefined;
1489
- }
1490
- for (const msgs of this.streamMsgs) {
1491
- try {
1492
- msgs.stop();
1493
- }
1494
- catch {
1495
- /* already closed with the connection */
1496
- }
1497
- }
1498
- this.streamMsgs.length = 0;
1499
- this.presenceEpoch++;
1500
- this.presence.cancelRebind();
1501
- this.presence.retireWatch();
1502
- if (this.channelWatchIter)
1503
- this.retireKvWatch(this.channelWatchIter);
1504
- this.channelWatchIter = undefined;
1505
- this.stopDeliveryLeaseWatch();
1506
- for (const sub of this.chatSubs.values()) {
1507
- try {
1508
- sub.unsubscribe();
1509
- }
1510
- catch {
1511
- /* already closed with the connection */
1512
- }
1513
- }
1514
- this.chatSubs.clear();
1515
- this.chatSubDenied.clear();
1516
- this.ownWatchDeletePrefixes.clear();
1517
- this.presence.resetConnection();
1518
- this.channelConfigs.clear();
1519
- this.channelDefaults = {};
1520
- // A read in flight on the old connection must not land in the new connection's cache.
1521
- this.channelRead = undefined;
1522
- this.channelReadGeneration++;
1523
- this.channelReadApplied = this.channelReadGeneration;
1524
- for (const watch of this.membershipFeedWatches)
1525
- watch.arm = watch.arm.catch(() => { }).then(() => this.disarmMembershipWatch(watch)).catch((err) => { this.emit("error", err); });
1526
- }
1527
- /** A transport can connect before a later JetStream/KV/subscription bind fails. The caller will
1528
- * retry the whole start, so release that partial epoch first instead of overwriting `nc` and
1529
- * leaving one established socket behind per retry. `close()` is deliberate: a failed bind has no
1530
- * graceful delivery contract to drain, and cleanup itself must not extend the retry failure.
1531
- *
1532
- * A throwing `close()` is not hypothetical: nats.js `NatsConnectionImpl.close()` awaits the
1533
- * protocol close, which itself flushes outbound + tears down subscription state; any of those
1534
- * that reject leaves the underlying TCP transport ESTABLISHED even though every client handle
1535
- * on this endpoint has been cleared. The next `start()` on the same object then dials a fresh
1536
- * connection while the old socket stays live on the broker (`/varz.connections` climbs once per
1537
- * failed attempt). The recovery path is layered, from most graceful to most surgical, matching
1538
- * nats-core's public surface (nats.d.ts: `close`, `drain`, `isClosed`; protocol.d.ts owns the
1539
- * `transport` handle whose `close(err?)` is the socket teardown; transport.d.ts exposes a
1540
- * synchronous `disconnect()` for the case where even close rejects). We only touch a private
1541
- * (`nc.protocol.transport`) when the public API has already refused, and the ORIGINAL bind
1542
- * error is re-raised at every layer. The close error is diagnostic noise. The bind error is
1543
- * what the caller must see.
1544
- *
1545
- * The delivery-serve subs and `this.subs` array are handles created by a successful
1546
- * `armDeliveryControl` on a PREVIOUS epoch; a bind failure on the retry never rewrites them
1547
- * because arming is a late step. Left in place they point at a dead protocol and survive into
1548
- * the next retry. The reviewer flagged this as an untested handle class. Zero them here so a
1549
- * retry starts with the same empty state as a first attempt. */
1550
- async closeFailedBind() {
1551
- const failedNc = this.nc;
1552
- if (failedNc)
1553
- this.disableLibraryReconnect(failedNc);
1554
- this.clearConnectionScoped();
1555
- this.nc = undefined;
1556
- this.js = undefined;
1557
- this.jsm = undefined;
1558
- this.kv = undefined;
1559
- this.channelKv = undefined;
1560
- this.membersKv = undefined;
1561
- this.aclKv = undefined;
1562
- this.membershipFeedKv = undefined;
1563
- this.deliveryLease.resetConnection();
1564
- this.managerLeaseKv = undefined;
1565
- this.daemonRenewalLeaseRevision = undefined;
1566
- // Handles that armDeliveryControl created on a previous connection: null them so a rebind
1567
- // does not carry a dead protocol's subs forward. Best-effort unsubscribe first (the sub is
1568
- // dead with its connection either way; unsubscribing an already-dead sub is a noop).
1569
- if (this.deliveryPlane.deliveryServeSub) {
1570
- try {
1571
- this.deliveryPlane.deliveryServeSub.unsubscribe();
1572
- }
1573
- catch { /* dead with the old connection */ }
1574
- this.deliveryPlane.deliveryServeSub = undefined;
1575
- }
1576
- if (this.deliveryPlane.deliveryAdminServeSub) {
1577
- try {
1578
- this.deliveryPlane.deliveryAdminServeSub.unsubscribe();
1579
- }
1580
- catch { /* dead with the old connection */ }
1581
- this.deliveryPlane.deliveryAdminServeSub = undefined;
1582
- }
1583
- this.dropAnycastRequests();
1584
- for (const sub of this.subs) {
1585
- try {
1586
- sub.unsubscribe();
1587
- }
1588
- catch { /* dead with the old connection */ }
1589
- }
1590
- this.subs.length = 0;
1591
- if (!failedNc)
1592
- return;
1593
- // The old status iterator is stale after nc is cleared, so its close cannot report this edge.
1594
- // As in doRebuild, teardown itself must announce the no-nc window before closing the socket.
1595
- this.emit("transport", { connected: false });
1596
- this.emit("connection", { connected: false });
1597
- // Layered teardown, comments kept OUT of the code span below on purpose: the mutation fixture
1598
- // bin/smoke/mutations/failed-bind-cleanup.json anchors on that span verbatim and the fixture
1599
- // census (bin/smoke/mutation-fixtures.smoke.ts) reddens an anchor that crosses a comment line.
1600
- // Fast path: the public close resolved, the broker drops the connection on its own.
1601
- // Layer 1: nats.js exposes drain() as the sanctioned "close on error" path. It flushes
1602
- // outbound then closes, and unlike close() has its own idempotent guard against a half-closed
1603
- // protocol. If drain resolves the socket is gone.
1604
- // Layer 2: last resort. nats.js `NatsConnectionImpl.protocol.transport` (see
1605
- // node_modules/@nats-io/nats-core/lib/{nats,protocol,transport}.d.ts) is the TCP socket the
1606
- // dialer produced. Its `close(err?)` returns a Promise once the socket is torn down; its
1607
- // synchronous `disconnect()` forces the FIN without waiting. Reached only after the public
1608
- // API has already refused, guarded only against the shape not being what the pinned version
1609
- // documents.
1610
- try {
1611
- await failedNc.close();
1612
- return;
1613
- }
1614
- catch { /* fall through to the layered fallback */ }
1615
- if (!failedNc.isClosed?.()) {
1616
- try {
1617
- await drainAndClose(failedNc);
1618
- return;
1619
- }
1620
- catch { /* both graceful paths refused, drop to the transport */ }
1621
- }
1622
- const proto = failedNc.protocol;
1623
- const transport = proto?.transport;
1624
- if (transport && !transport.isClosed) {
1625
- try {
1626
- await transport.close?.();
1627
- }
1628
- catch { /* transport close itself threw, force it down synchronously below */ }
1629
- if (!transport.isClosed) {
1630
- try {
1631
- transport.disconnect?.();
1632
- }
1633
- catch { /* nothing left to try */ }
1634
- }
1635
- }
956
+ return this.connection.clearConnectionScoped();
1636
957
  }
1637
- /** If stop() ran during a rebuild's `await connectAndBind`, the just-bound connection +
1638
- * heartbeat + supervisor would be left live on a stopped endpoint. Tear that fresh
1639
- * connection back down and report it. Reads `this.nc` in its own scope (a bare `this.nc`
1640
- * in doRebuild narrows to `never` via TS inlining connectAndBind's assignment). Returns
1641
- * true iff it tore something down (caller bails out of the rebuild). */
1642
- async tearDownIfStopped() {
1643
- if (!this.stopped)
1644
- return false;
1645
- const nc = this.nc;
1646
- if (nc)
1647
- this.disableLibraryReconnect(nc);
1648
- this.clearConnectionScoped();
1649
- await this.closeWithoutLibraryReconnect(nc);
1650
- this.nc = undefined;
1651
- return true;
958
+ /** Forwards to the connection component's {@link EndpointConnection.closeFailedBind}. */
959
+ closeFailedBind() {
960
+ return this.connection.closeFailedBind();
961
+ }
962
+ /** Forwards to the connection component's {@link EndpointConnection.tearDownIfStopped}. */
963
+ tearDownIfStopped() {
964
+ return this.connection.tearDownIfStopped();
1652
965
  }
1653
966
  /** Watch for a terminal close (nats.js has exhausted its own reconnect) and rebuild.
1654
967
  * Our own stop()/drain also resolves closed(), so the `stopped` guard keeps a clean
@@ -1673,95 +986,68 @@ export class CotalEndpoint extends EventEmitter {
1673
986
  void this.reestablishLoop();
1674
987
  });
1675
988
  }
1676
- /** Single serialized rebuild: drain the old connection and rebind via {@link connectAndBind},
1677
- * guarded so concurrent triggers (manual {@link reconnect}, the supervisor's closed(), the
1678
- * retry loop) coalesce onto ONE in-flight rebuild instead of racing two connectAndBinds and
1679
- * leaking a connection. Returns the shared promise; a second caller gets the in-flight one. */
989
+ /** The rebuild and retry pacing of this endpoint. Every dependency is read when it is used, so a field
990
+ * assigned after construction is seen. */
991
+ reconnection = new EndpointReconnect({
992
+ rebuildPromise: () => this.rebuildPromise,
993
+ setRebuildPromise: (value) => { this.rebuildPromise = value; },
994
+ nc: () => this.nc,
995
+ setNc: (value) => { this.nc = value; },
996
+ reconnecting: () => this.reconnecting,
997
+ setReconnecting: (value) => { this.reconnecting = value; },
998
+ membershipFeedWatches: () => this.membershipFeedWatches,
999
+ js: () => this.js,
1000
+ setJs: (value) => { this.js = value; },
1001
+ jsm: () => this.jsm,
1002
+ setJsm: (value) => { this.jsm = value; },
1003
+ kv: () => this.kv,
1004
+ setKv: (value) => { this.kv = value; },
1005
+ channelKv: () => this.channelKv,
1006
+ setChannelKv: (value) => { this.channelKv = value; },
1007
+ membersKv: () => this.membersKv,
1008
+ setMembersKv: (value) => { this.membersKv = value; },
1009
+ aclKv: () => this.aclKv,
1010
+ setAclKv: (value) => { this.aclKv = value; },
1011
+ membershipFeedKv: () => this.membershipFeedKv,
1012
+ setMembershipFeedKv: (value) => { this.membershipFeedKv = value; },
1013
+ deliveryLease: () => this.deliveryLease,
1014
+ managerLeaseKv: () => this.managerLeaseKv,
1015
+ setManagerLeaseKv: (value) => { this.managerLeaseKv = value; },
1016
+ daemonRenewalLeaseRevision: () => this.daemonRenewalLeaseRevision,
1017
+ setDaemonRenewalLeaseRevision: (value) => { this.daemonRenewalLeaseRevision = value; },
1018
+ stopped: () => this.stopped,
1019
+ retryMs: () => this.retryMs,
1020
+ retryAttempt: () => this.retryAttempt,
1021
+ setRetryAttempt: (value) => { this.retryAttempt = value; },
1022
+ backoffResolve: () => this.backoffResolve,
1023
+ backoffTimer: () => this.backoffTimer,
1024
+ setBackoffTimer: (value) => { this.backoffTimer = value; },
1025
+ membershipPauses: () => this.membershipPauses,
1026
+ disableLibraryReconnect: (nc) => this.disableLibraryReconnect(nc),
1027
+ clearConnectionScoped: () => this.clearConnectionScoped(),
1028
+ settleDeliveryLeaseWatches: () => this.settleDeliveryLeaseWatches(),
1029
+ settleKvWatches: () => this.settleKvWatches(),
1030
+ closeWithoutLibraryReconnect: (nc) => this.closeWithoutLibraryReconnect(nc),
1031
+ connectAndBind: () => this.connectAndBind(),
1032
+ tearDownIfStopped: () => this.tearDownIfStopped(),
1033
+ superviseConnection: () => this.superviseConnection(),
1034
+ emit: (event, ...args) => this.emit(event, ...args),
1035
+ });
1036
+ /** Forwards to the reconnect component's {@link EndpointReconnect.rebuild}. */
1680
1037
  rebuild() {
1681
- if (this.rebuildPromise)
1682
- return this.rebuildPromise;
1683
- const p = this.doRebuild().finally(() => {
1684
- if (this.rebuildPromise === p)
1685
- this.rebuildPromise = undefined;
1686
- });
1687
- this.rebuildPromise = p;
1688
- return p;
1689
- }
1690
- /** The transition: stop the connection-scoped timers FIRST (so nothing live touches
1691
- * this.nc during the null window), drop the connection refs, close the old nc, then
1692
- * rebind + re-arm the supervisor on the fresh connection. clearConnectionScoped is
1693
- * idempotent, so connectAndBind's own call here is a noop. */
1694
- async doRebuild() {
1695
- const oldNc = this.nc;
1696
- if (oldNc)
1697
- this.disableLibraryReconnect(oldNc);
1698
- this.reconnecting = true;
1699
- try {
1700
- this.clearConnectionScoped();
1701
- // Manual reconnect still has a live old epoch: complete broker-consumer cleanup before close.
1702
- // Terminal self-heal has an already-closed epoch: disarm retains stream/name for fresh cleanup,
1703
- // and the KV watch consumers that closed with it are left to the broker's inactive threshold.
1704
- if (oldNc && !oldNc.isClosed())
1705
- await Promise.all([...[...this.membershipFeedWatches].map((watch) => watch.arm), this.settleDeliveryLeaseWatches(), this.settleKvWatches()]);
1706
- this.nc = undefined;
1707
- this.js = undefined;
1708
- this.jsm = undefined;
1709
- this.kv = undefined;
1710
- this.channelKv = undefined;
1711
- // Plane-3 KV handles are bound to the old connection too — drop them so the daemon re-opens them on
1712
- // the fresh nc (else durableJoin/leave/list, the reader's ACL re-auth, and lease renew use a dead
1713
- // handle after a reconnect).
1714
- this.membersKv = undefined;
1715
- this.aclKv = undefined;
1716
- this.membershipFeedKv = undefined;
1717
- this.deliveryLease.resetConnection();
1718
- // The manager's liveness-lease handle too: left bound to the old connection, every renew and
1719
- // re-read after a reconnect times out, and the manager reports its lease unknown for good.
1720
- this.managerLeaseKv = undefined;
1721
- this.daemonRenewalLeaseRevision = undefined;
1722
- // This is an application-requested epoch teardown, not a transient nats.js blip. The old
1723
- // status iterator is now stale by construction and its close is epoch-dropped, so this line is
1724
- // the authoritative raw-liveness edge for the no-nc window until the new watcher seeds true.
1725
- this.emit("transport", { connected: false });
1726
- this.emit("connection", { connected: false });
1727
- await this.closeWithoutLibraryReconnect(oldNc);
1728
- // stop() can arrive while the old epoch closes. Do not start another authentication
1729
- // handshake after it: a terminal credential may already have expired in that window.
1730
- // Keep old-epoch and late-epoch close failures outside this dial-only catch.
1731
- if (this.stopped)
1732
- return;
1733
- try {
1734
- await this.connectAndBind();
1735
- }
1736
- catch (error) {
1737
- if (!this.stopped)
1738
- throw error;
1739
- }
1740
- // stop() may have run during the await — don't leave a live connection + heartbeat +
1741
- // supervisor on a stopped endpoint. (Reads this.nc in its own scope — a bare `this.nc`
1742
- // here in doRebuild narrows to `never` via TS inlining connectAndBind's assignment.)
1743
- // Re-arm on the fresh nc only after this stopped fence accepts it.
1744
- if (await this.tearDownIfStopped())
1745
- return;
1746
- this.superviseConnection();
1747
- }
1748
- finally {
1749
- this.reconnecting = false;
1750
- }
1038
+ return this.reconnection.rebuild();
1751
1039
  }
1752
- /** The ceiling {@link nextRetryDelayMs} grows to. A failure that outlives a couple of retries is
1753
- * a standing one (a down broker, a credential nothing can renew), and retrying it every few
1754
- * seconds forever is what turns one stuck client into a permanent flat load on the broker and its
1755
- * auth callout. */
1756
- static RETRY_BACKOFF_CAP_MS = 60_000;
1757
- /** The wait before the next rebuild attempt: {@link retryMs}, doubling per consecutive failure up
1758
- * to {@link RETRY_BACKOFF_CAP_MS}, then a random half of it taken off. A transient drop still
1759
- * recovers within retryMs, and endpoints refused together, as a broker restart or an auth limit
1760
- * refuses a host's agents, spread their retries instead of arriving at the callout at once. */
1040
+ /** Forwards to the reconnect component's {@link EndpointReconnect.nextRetryDelayMs}. */
1761
1041
  nextRetryDelayMs() {
1762
- const delay = Math.min(this.retryMs * 2 ** this.retryAttempt, CotalEndpoint.RETRY_BACKOFF_CAP_MS);
1763
- this.retryAttempt++;
1764
- return Math.round(delay / 2 + Math.random() * (delay / 2));
1042
+ return this.reconnection.nextRetryDelayMs();
1043
+ }
1044
+ /** Forwards to the reconnect component's {@link EndpointReconnect.kickBackoff}. */
1045
+ kickBackoff() {
1046
+ return this.reconnection.kickBackoff();
1047
+ }
1048
+ /** Forwards to the reconnect component's {@link EndpointReconnect.membershipPause}. */
1049
+ membershipPause(attempt) {
1050
+ return this.reconnection.membershipPause(attempt);
1765
1051
  }
1766
1052
  /** Rebuild with backoff until it sticks or we're stopped. Interruptible: a manual
1767
1053
  * {@link reconnect} kicks the backoff so the next attempt runs immediately instead of
@@ -1811,30 +1097,6 @@ export class CotalEndpoint extends EventEmitter {
1811
1097
  if (!this.stopped && this.reestablishing && !this.rebuildPromise)
1812
1098
  this.kickBackoff();
1813
1099
  }
1814
- /** Cut an in-flight reestablish backoff short so the next attempt runs immediately, and
1815
- * clear its timer so it can't fire later on a stopped/restarted loop. */
1816
- kickBackoff() {
1817
- this.backoffResolve?.();
1818
- if (this.backoffTimer) {
1819
- clearTimeout(this.backoffTimer);
1820
- this.backoffTimer = undefined;
1821
- }
1822
- }
1823
- /** Capped exponential pause between membership retries. stop() ends it early, so a loop waiting
1824
- * on an absent delivery daemon never holds a stopped endpoint's process open for the delay. */
1825
- membershipPause(attempt) {
1826
- if (this.stopped)
1827
- return Promise.resolve();
1828
- return new Promise((resolve) => {
1829
- const wake = () => {
1830
- clearTimeout(timer);
1831
- this.membershipPauses.delete(wake);
1832
- resolve();
1833
- };
1834
- const timer = setTimeout(wake, Math.min(30_000, 1000 * 2 ** attempt));
1835
- this.membershipPauses.add(wake);
1836
- });
1837
- }
1838
1100
  /** Manual reconnect: tear down the current connection and rebuild, WITHOUT the permanent
1839
1101
  * stop (stopped/stopping stay false). Serialized with the self-heal supervisor via
1840
1102
  * {@link rebuild}, and interruptible — if a backoff is in flight, kick it so the attempt
@@ -1866,99 +1128,9 @@ export class CotalEndpoint extends EventEmitter {
1866
1128
  stop() {
1867
1129
  return this.stopPromise ??= this.stopOnce();
1868
1130
  }
1869
- async stopOnce() {
1870
- if (this.nc)
1871
- this.disableLibraryReconnect(this.nc);
1872
- this.stopped = true;
1873
- for (const follower of this.activeGoalFollowers) {
1874
- follower.cancel();
1875
- }
1876
- this.activeGoalFollowers.clear();
1877
- this.presenceEpoch++;
1878
- // Every principal serve ends now, so a `ready` still waiting for the broker rejects and no new
1879
- // request is taken. Its handlers in flight finish below, before the connection they reply on
1880
- // closes, or their requests' deadlines pass.
1881
- const principalStops = [...this.principalServes.values()].map((intent) => this.stopPrincipalServe(intent, false));
1882
- this.presence.cancelRebind();
1883
- // Wake a reestablishLoop sitting in backoff so it sees `stopped` and exits instead of
1884
- // sleeping out retryMs; also clears the timer so it can't fire later.
1885
- this.kickBackoff();
1886
- for (const wake of [...this.membershipPauses])
1887
- wake();
1888
- if (this.heartbeatTimer)
1889
- clearInterval(this.heartbeatTimer);
1890
- if (this.sweepTimer)
1891
- clearInterval(this.sweepTimer);
1892
- this.cancelBearerRenewal?.();
1893
- if (this.credsTimer)
1894
- clearTimeout(this.credsTimer);
1895
- if (this.authExpiryReconnectTimer)
1896
- clearTimeout(this.authExpiryReconnectTimer);
1897
- for (const watch of this.membershipFeedWatches) {
1898
- watch.stopped = true;
1899
- watch.arm = watch.arm.catch(() => { }).then(async () => {
1900
- await this.disarmMembershipWatch(watch);
1901
- await this.deleteRetainedMembershipConsumer(watch);
1902
- });
1903
- }
1904
- // Permanent endpoint shutdown has no future epoch. Try strict cleanup on the current live epoch;
1905
- // if the broker is already gone, terminate local ownership rather than hanging shutdown forever.
1906
- await Promise.all([...this.membershipFeedWatches].map((watch) => watch.arm.catch((err) => {
1907
- if (this.nc && !this.nc.isClosed())
1908
- throw err;
1909
- })));
1910
- for (const watch of this.membershipFeedWatches) {
1911
- watch.resolveStop?.();
1912
- watch.resolveStop = undefined;
1913
- watch.rejectStop = undefined;
1914
- }
1915
- this.membershipFeedWatches.clear();
1916
- for (const msgs of this.streamMsgs) {
1917
- try {
1918
- msgs.stop();
1919
- }
1920
- catch {
1921
- /* already closed */
1922
- }
1923
- }
1924
- this.presence.retireWatch();
1925
- if (this.channelWatchIter)
1926
- this.retireKvWatch(this.channelWatchIter);
1927
- this.channelWatchIter = undefined;
1928
- this.stopDeliveryLeaseWatch();
1929
- await Promise.all(principalStops);
1930
- try {
1931
- if (this.doRegister) {
1932
- await this.presence.publishOffline();
1933
- }
1934
- }
1935
- catch {
1936
- /* best-effort graceful leave */
1937
- }
1938
- await Promise.all([this.settleDeliveryLeaseWatches(), this.settleKvWatches()]);
1939
- // DM-only: the pull above is stopped, so no new copy reaches the handler. Let a running handler
1940
- // settle while the connection is still open, so its ack can reach the broker; close either way.
1941
- let dmOnlyUnsettled = false;
1942
- if (this.dmOnly && this.dmOnlyInFlight) {
1943
- const settleMs = this.dmOnly.settleTimeoutMs ?? 30_000;
1944
- dmOnlyUnsettled = await withDeadline(this.dmOnlyInFlight.then(() => false), settleMs, () => new Error("unsettled"))
1945
- .catch(() => true);
1946
- }
1947
- await this.closeWithoutLibraryReconnect(this.nc);
1948
- // #1356: stop() does its own teardown and never runs clearConnectionScoped, so clear here too —
1949
- // AFTER the best-effort offline publish above, which would otherwise re-record a refusal on its
1950
- // way out. A stopped endpoint has no live basis for "this bucket is refusing writes", and the
1951
- // duration is computed from `Date.now()`, so a retained record does not merely go stale: it keeps
1952
- // COUNTING UP for as long as the dead object is held.
1953
- this.clearPresenceWriteFailure();
1954
- // Custody callers must not observe stop completion while a concurrent rebind can still
1955
- // publish a late consuming connection. doRebuild closes its stopped epoch before resolving.
1956
- await this.rebuildPromise;
1957
- await this.startPromise;
1958
- if ([...this.ownedConnections].some((nc) => !nc.isClosed()))
1959
- throw new Error("endpoint stop could not prove its connection closed; local consumer custody must be retained");
1960
- if (dmOnlyUnsettled)
1961
- 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`);
1131
+ /** Forwards to the connection component's {@link EndpointConnection.stopOnce}. */
1132
+ stopOnce() {
1133
+ return this.connection.stopOnce();
1962
1134
  }
1963
1135
  /** The native binding of every connection this endpoint holds. A host compares the list with a
1964
1136
  * complete native census of the account to show that no other connection uses it. The list
@@ -1967,20 +1139,7 @@ export class CotalEndpoint extends EventEmitter {
1967
1139
  * start, during a start, rebuild or stop, while a credential transaction or its connection swap
1968
1140
  * is pending, and while the connection is down or redialing. */
1969
1141
  nativeConnections() {
1970
- const unsettled = (why) => new Error(`endpoint connection inventory is unsettled: ${why}`);
1971
- if (this.startPromise !== undefined || this.rebuildPromise !== undefined || this.reconnecting)
1972
- throw unsettled("a start or rebuild is in flight");
1973
- const open = [...this.ownedConnections].filter((nc) => !nc.isClosed());
1974
- if (this.stopped) {
1975
- if (open.length > 0)
1976
- throw unsettled("the endpoint stopped but a connection has not closed");
1977
- return [];
1978
- }
1979
- if (this.credsTxnsRunning > 0 || this.residentSwap !== undefined)
1980
- throw unsettled("a credential adoption is in flight");
1981
- if (!this.nc || !this.nativeBound)
1982
- throw unsettled("the connection is down or redialing");
1983
- return open.map((nc) => nativeConnectionBinding(nc, "endpoint connection"));
1142
+ return this.connection.nativeConnections();
1984
1143
  }
1985
1144
  // ---- messaging -----------------------------------------------------------
1986
1145
  /** The messaging verbs of this endpoint: multicast, unicast, anycast and the event-payload