@cotal-ai/core 0.171.1 → 0.171.3
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/advisory-lock.d.ts +2 -0
- package/dist/advisory-lock.d.ts.map +1 -1
- package/dist/advisory-lock.js +10 -0
- package/dist/advisory-lock.js.map +1 -1
- package/dist/agent-file.d.ts +3 -2
- package/dist/agent-file.d.ts.map +1 -1
- package/dist/agent-file.js +11 -2
- package/dist/agent-file.js.map +1 -1
- package/dist/connector.d.ts +5 -0
- package/dist/connector.d.ts.map +1 -1
- package/dist/connector.js.map +1 -1
- package/dist/endpoint-credentials.d.ts +306 -0
- package/dist/endpoint-credentials.d.ts.map +1 -0
- package/dist/endpoint-credentials.js +585 -0
- package/dist/endpoint-credentials.js.map +1 -0
- package/dist/endpoint-dial.d.ts +171 -0
- package/dist/endpoint-dial.d.ts.map +1 -0
- package/dist/endpoint-dial.js +479 -0
- package/dist/endpoint-dial.js.map +1 -0
- package/dist/endpoint-messages.d.ts +44 -0
- package/dist/endpoint-messages.d.ts.map +1 -0
- package/dist/endpoint-messages.js +153 -0
- package/dist/endpoint-messages.js.map +1 -0
- package/dist/endpoint-options.d.ts +295 -0
- package/dist/endpoint-options.d.ts.map +1 -0
- package/dist/endpoint-options.js +75 -0
- package/dist/endpoint-options.js.map +1 -0
- package/dist/endpoint-subscriptions.d.ts +2 -2
- package/dist/endpoint-subscriptions.d.ts.map +1 -1
- package/dist/endpoint-subscriptions.js +4 -6
- package/dist/endpoint-subscriptions.js.map +1 -1
- package/dist/endpoint.d.ts +26 -536
- package/dist/endpoint.d.ts.map +1 -1
- package/dist/endpoint.js +102 -1184
- package/dist/endpoint.js.map +1 -1
- package/package.json +1 -1
package/dist/endpoint.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
export { MULTI_FILTER_BATCH, MULTI_FILTER_READ_CONCURRENCY } from "./endpoint-history.js";
|
|
2
2
|
import { type NativeConnectionBinding } from "./native-connection.js";
|
|
3
3
|
import { EventEmitter } from "node:events";
|
|
4
|
-
import {
|
|
4
|
+
import { type NatsConnection } from "@nats-io/transport-node";
|
|
5
5
|
import { type LivenessAnswer, type LivenessPlane, type ResponderState } from "./liveness.js";
|
|
6
6
|
import { type PresenceView } from "./endpoint-presence.js";
|
|
7
7
|
export { PresenceWriteStuckError, type PresenceView } from "./endpoint-presence.js";
|
|
@@ -13,267 +13,16 @@ import type { EndpointReply } from "./endpoint-envelope.js";
|
|
|
13
13
|
import type { CompiledContract } from "./schema-profile.js";
|
|
14
14
|
import type { RegistryEndpointsInput, RegistryEndpointsOutput } from "./registry-contract.js";
|
|
15
15
|
import type { EpVerbTarget, EpAttributedReply } from "./endpoint-verbs.js";
|
|
16
|
-
import type { AgentCard, ChannelConfig, ControlReply, ControlRequest, ControlRequestInit,
|
|
16
|
+
import type { AgentCard, ChannelConfig, ControlReply, ControlRequest, ControlRequestInit, EndpointRef, Part, Presence, PresencePrompts, PresenceStatus, PresenceCondition, AttentionMode, ChannelMode, CotalMessage, DmHistoryRead, HistoryMessage, DeliveryClass, MembershipChange, MembershipSnapshot } from "./types.js";
|
|
17
17
|
import type { DeliveryLeaseInfo, ManagerLeaseInfo } from "./lease.js";
|
|
18
18
|
import { type MaybePromise } from "./endpoint-delivery-plane.js";
|
|
19
19
|
import { type AnycastStatus } from "./anycast-requests.js";
|
|
20
|
-
import { type ParsedSubject } from "./subjects.js";
|
|
21
20
|
import { isPermissionDenied } from "./permission-denied.js";
|
|
22
21
|
export { isPermissionDenied };
|
|
23
|
-
export
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
* Throws on any other value. */
|
|
28
|
-
export declare function deliveryLimitOf(value: string | undefined): number | null;
|
|
29
|
-
/** Space joined when none is given on the CLI (the `cotal-<space>` cmux tab, etc.). */
|
|
30
|
-
export declare const DEFAULT_SPACE = "main";
|
|
31
|
-
export interface EndpointOptions {
|
|
32
|
-
/** Trusted composition custody of each opened transport, including replacement epochs.
|
|
33
|
-
* Called before binding so the owner can await its terminal closed signal on bind failure. */
|
|
34
|
-
onConnection?: (nc: NatsConnection) => void;
|
|
35
|
-
/** A planned credential swap dials a second connection, calls {@link onConnection}, and flushes
|
|
36
|
-
* before it reconnects the resident connection. The second connection closes after that
|
|
37
|
-
* reconnect. `onConnection` must accept a connection that exists only for the swap. Serve
|
|
38
|
-
* subscriptions that share an incarnation queue keep dispatch while the resident connection
|
|
39
|
-
* is down. Without this option the resident connection reconnects in place. */
|
|
40
|
-
overlapOnConnectionRenewal?: boolean;
|
|
41
|
-
/** Await local admission checks before presence, consumers and the ready event on each bind. */
|
|
42
|
-
beforeBind?: () => Promise<void>;
|
|
43
|
-
/** The collaboration to join. */
|
|
44
|
-
space: string;
|
|
45
|
-
/** Identity. `id` is generated if omitted. */
|
|
46
|
-
card: Omit<AgentCard, "id"> & {
|
|
47
|
-
id?: string;
|
|
48
|
-
};
|
|
49
|
-
/** Opaque presence label. Omitted reads COTAL_ENVIRONMENT; null omits the label without reading it. */
|
|
50
|
-
environment?: string | null;
|
|
51
|
-
/** This incarnation's lifecycle UID (SPEC §13.1), minted ONCE per lifecycle by the provisioning
|
|
52
|
-
* authority (manager/CLI: `mintLifecycleUid()`) and PERSISTED with the agent — never re-minted per
|
|
53
|
-
* process, or a supervised restart would abandon the durable inbox. REQUIRED to bind/create the
|
|
54
|
-
* lifecycle-keyed messaging durables (`dm_…-<uid>`, `dlv_…-<uid>`, `chathist_…-<uid>`) — an
|
|
55
|
-
* endpoint without one (a pure operator/daemon connection) can not consume DM/chat history. */
|
|
56
|
-
lifecycleUid?: string;
|
|
57
|
-
/** The CHAT stream sequence this incarnation had reached before its preservation cut (a supervised
|
|
58
|
-
* preserve/resume, never a fresh join). The boot backfill reads only what came after it instead of
|
|
59
|
-
* the whole retained window. Core reads no environment variable for this — the caller (a launcher)
|
|
60
|
-
* resolves it and passes it explicitly. */
|
|
61
|
-
backfillFloor?: number;
|
|
62
|
-
/** The accepted-row token of this credential's issuance (SPEC 13.15). Set when the launcher
|
|
63
|
-
* minted the credential as an issuance: after connecting, the endpoint reads the generation the
|
|
64
|
-
* ISSUER bound under this token (a broker-enforced per-key read) and pins it into every caller
|
|
65
|
-
* rail it forms. A token that resolves to no row, or to another incarnation's reference, fails
|
|
66
|
-
* the connect: the rails would be refused at the broker anyway, and a silent legacy fallback is
|
|
67
|
-
* exactly what the versioned rail exists to rule out. */
|
|
68
|
-
acceptedToken?: string;
|
|
69
|
-
servers?: string;
|
|
70
|
-
/** Connection token (soft-shared auth). Mutually exclusive with user/pass. */
|
|
71
|
-
token?: string;
|
|
72
|
-
/** Username/password auth (both required together). */
|
|
73
|
-
user?: string;
|
|
74
|
-
pass?: string;
|
|
75
|
-
/** NATS user creds file *content* (JWT + nkey seed), or a SOURCE that mints/reads a fresh copy.
|
|
76
|
-
* When set, the endpoint authenticates as that user and adopts the creds' identity as its card.id.
|
|
77
|
-
*
|
|
78
|
-
* A STRING is the ordinary static cred. A FUNCTION is the STANDING-RENEWAL seam for
|
|
79
|
-
* bounded-lifetime standing creds: the endpoint fetches before the first connect, re-fetches at
|
|
80
|
-
* 75% of each JWT's lifetime (then swaps the connection onto the fresh cred with a controlled
|
|
81
|
-
* reconnect) and on rebuilds, and every (re)connect attempt presents the freshest copy — the
|
|
82
|
-
* broker's expiry-close is only the backstop for a missed swap.
|
|
83
|
-
* The two source shapes are the renewal classes: a seed-holder self-remints (the manager's
|
|
84
|
-
* supervisor), a seed-less daemon re-reads its manager-reminted creds file (delivery). A source
|
|
85
|
-
* requires explicit `card.id` (the pinned identity); every fetched cred MUST carry that same nkey
|
|
86
|
-
* or the endpoint fails loud — renewal may never silently swap identity. A fetch failure is
|
|
87
|
-
* emitted as a "warning" event and retried; the connection stays up until its current JWT expires,
|
|
88
|
-
* so a dead reminter is loud without instantly dropping the mesh. Node rethrows unhandled "error"
|
|
89
|
-
* events, so a retry notice must not use that channel (#891). Once the cached cred expires,
|
|
90
|
-
* the endpoint refuses to present it to the broker and keeps retrying the source with backoff. */
|
|
91
|
-
creds?: string | (() => Promise<string>);
|
|
92
|
-
/** USER-MODE auth: a validated Cotal user bearer (the JWT from `cotal login` → the IdP bridge), or a
|
|
93
|
-
* SOURCE that mints a fresh one. When set, the endpoint connects through the auth callout — presenting
|
|
94
|
-
* {@link sentinelCreds} + the bearer, the broker mints its scoped data-account JWT.
|
|
95
|
-
*
|
|
96
|
-
* A STRING is a one-shot bearer for connection-lifetime ≤ bearer-lifetime callers (the CLI): the
|
|
97
|
-
* owner+actor PRINCIPAL is derived from it (`sub`, `act.actor`), and the connection dies at the
|
|
98
|
-
* bearer-bound JWT expiry. A FUNCTION is a bearer source for long-lived endpoints (spawned agents):
|
|
99
|
-
* the endpoint fetches before the first connect, renews at a random point between 50% and 80% of
|
|
100
|
-
* each token's lifetime (then swaps the connection onto it with a controlled reconnect) and on
|
|
101
|
-
* rebuilds, and every (re)connect attempt presents the freshest unexpired token — so reconnects
|
|
102
|
-
* outlive any single bearer, and none presents an expired one.
|
|
103
|
-
* A source requires explicit `card.owner` + `card.actor` (there is no bearer to derive them from at
|
|
104
|
-
* construction); every fetched bearer MUST carry that same principal or the endpoint fails loud.
|
|
105
|
-
* A fetch failure is emitted as one "warning" event per run of failures and retried on a jittered,
|
|
106
|
-
* capped backoff — the connection stays up until its current JWT expires, so a dead auth service
|
|
107
|
-
* surfaces loudly without instantly dropping the mesh. A failure that carries a numeric
|
|
108
|
-
* `retryAfterSeconds` is retried when those seconds have passed instead, not before.
|
|
109
|
-
* Node rethrows unhandled "error" events, so a retry notice must not use that channel (#891).
|
|
110
|
-
* Mutually exclusive with `creds`/`token`/`user`/`pass`; requires `sentinelCreds`. */
|
|
111
|
-
bearer?: string | (() => Promise<string>);
|
|
112
|
-
/** The shared, deny-all auth-account sentinel creds presented alongside {@link bearer} so the connect
|
|
113
|
-
* lands in the callout account (`createCalloutAuth().sentinelCreds`). Powerless on its own. */
|
|
114
|
-
sentinelCreds?: string;
|
|
115
|
-
/** Require a TLS connection to the server. */
|
|
116
|
-
tls?: boolean;
|
|
117
|
-
/** Native NATS PING interval for this endpoint's resident connection, in milliseconds.
|
|
118
|
-
* Defaults to 10 seconds. Pair with transportMaxPingOut. No probe connection. */
|
|
119
|
-
transportPingIntervalMs?: number;
|
|
120
|
-
/** Unanswered native PING count before the resident transport becomes stale. Defaults to 2.
|
|
121
|
-
* Pair with transportPingIntervalMs for bounded silent loss. */
|
|
122
|
-
transportMaxPingOut?: number;
|
|
123
|
-
/** How long the first connect may take before it fails with the transport's TimeoutError, in
|
|
124
|
-
* milliseconds. Omitted uses the transport's default. */
|
|
125
|
-
transportConnectTimeoutMs?: number;
|
|
126
|
-
/** Channels to subscribe to; the first concrete one is the default broadcast target. Omitted or
|
|
127
|
-
* empty ⇒ NO channels: the endpoint joins nothing, and {@link CotalEndpoint.multicast} refuses
|
|
128
|
-
* a call with no explicit channel rather than picking one. */
|
|
129
|
-
channels?: string[];
|
|
130
|
-
/** The credential's complete channel read ACL when the composition has it. An explicit empty list
|
|
131
|
-
* means provisioning omitted the DLV durable. When omitted, static credentials select the optional
|
|
132
|
-
* bind from their presented publish permissions; bearer callers need the resolved ACL. A denied
|
|
133
|
-
* bind still refuses startup. */
|
|
134
|
-
allowSubscribe?: string[];
|
|
135
|
-
/** Presence heartbeat interval (ms). */
|
|
136
|
-
heartbeatMs?: number;
|
|
137
|
-
/** Presence liveness window (ms); a peer is considered gone after this. */
|
|
138
|
-
ttlMs?: number;
|
|
139
|
-
/** Publish our own presence (default true). */
|
|
140
|
-
registerPresence?: boolean;
|
|
141
|
-
/** Track the roster of peers with a live watch (default true). Every watcher receives every
|
|
142
|
-
* member's heartbeat, so a space of K watching members moves K² deliveries per heartbeat. An
|
|
143
|
-
* endpoint that only needs the roster when it acts sets this false and calls
|
|
144
|
-
* {@link CotalEndpoint.readPresence} instead (SPEC §6). */
|
|
145
|
-
watchPresence?: boolean;
|
|
146
|
-
/** Keep the channel registry cache (default true). An endpoint that watches presence watches the
|
|
147
|
-
* registry; a consumer that reads presence on demand reads the registry on demand too
|
|
148
|
-
* ({@link CotalEndpoint.readChannels}), and any other endpoint keeps no cache. A presence-only
|
|
149
|
-
* supervisor sets this false to track the roster WITHOUT opening the channel-registry cache — so
|
|
150
|
-
* its cred needs no channel-registry read grant (residual 2). A consumer always opens the
|
|
151
|
-
* registry, because the join-time replay decision reads it. */
|
|
152
|
-
watchChannels?: boolean;
|
|
153
|
-
/** Read presence and the channel registry ONCE at start instead of watching them (default false),
|
|
154
|
-
* for an endpoint that does one thing and stops (`cotal send`, a roster probe). Each read is a
|
|
155
|
-
* batched Direct Get of every key's last record, so it binds no consumer. A watch's ordered consumer
|
|
156
|
-
* outlives {@link CotalEndpoint.stop} by the broker's five-minute inactive threshold, because the
|
|
157
|
-
* operator and agent profiles hold no CONSUMER.DELETE on these buckets (#691), and one per
|
|
158
|
-
* short-lived process piles up until the broker refuses new consumers there (#4091). The roster
|
|
159
|
-
* and the channel cache hold the state at start and never update, and no sweep runs. Requires
|
|
160
|
-
* `consume` and `registerPresence` false. */
|
|
161
|
-
readOnce?: boolean;
|
|
162
|
-
/** Consume ONLY this endpoint's own existing DM durable, for a credential that can read nothing
|
|
163
|
-
* else. The endpoint binds `dm_<owner>-<actor>-<uid>` and opens no channel registry, presence,
|
|
164
|
-
* KV, channel subscription, `dlv_` durable, history reader or JetStream manager. It never creates
|
|
165
|
-
* the durable: a missing one fails start with {@link DmDurableMissingError}, a refused bind with
|
|
166
|
-
* {@link DmBindRefusedError}. Each authenticated DM goes to `handler`, one at a time; the next is
|
|
167
|
-
* not read until the previous handler settles. The `message` event does not fire in this mode.
|
|
168
|
-
* {@link CotalEndpoint.stop} resolves only after the connection is closed and the running handler
|
|
169
|
-
* has settled; a rejecting handler still lets the connection close, and stop throws, keeping
|
|
170
|
-
* custody, when closure or settlement within `settleTimeoutMs` (default 30000) is unproved.
|
|
171
|
-
* A copy received after stop begins or after a reconnect replaces the connection is never
|
|
172
|
-
* handed to the handler and stays unacked for broker redelivery; an ack, nak or in-progress
|
|
173
|
-
* signal on a closed connection throws.
|
|
174
|
-
* Requires static or sourced creds or a bearer, `consume` true, `registerPresence`,
|
|
175
|
-
* `watchPresence` and `watchChannels` false, and no channels, role, `readOnce` or `acceptedToken`. */
|
|
176
|
-
dmOnly?: DmOnlyOptions;
|
|
177
|
-
/** Create inbound stream consumers (DM / chat / anycast). Default true; a pure observer sets false. */
|
|
178
|
-
consume?: boolean;
|
|
179
|
-
/** Initial per-channel attention overrides to publish in presence from the first heartbeat (the
|
|
180
|
-
* connector's file-default seed). Mirror only — never read back into delivery. */
|
|
181
|
-
channelModes?: Record<string, ChannelMode>;
|
|
182
|
-
/** How long an unacked (un-surfaced) message waits before redelivery (ms). */
|
|
183
|
-
ackWaitMs?: number;
|
|
184
|
-
/** Retire this instance's durable consumers after it's been gone this long (ms). */
|
|
185
|
-
inactiveThresholdMs?: number;
|
|
186
|
-
}
|
|
187
|
-
/** A peer subscribed to a channel — broker truth (a chat-stream consumer) joined with
|
|
188
|
-
* presence for liveness. `live: false` is a stale ghost: the durable lingers (reconnect
|
|
189
|
-
* grace) but presence says the peer is gone/offline. */
|
|
190
|
-
export interface ChannelMember {
|
|
191
|
-
id: string;
|
|
192
|
-
name: string;
|
|
193
|
-
role?: string;
|
|
194
|
-
live: boolean;
|
|
195
|
-
}
|
|
196
|
-
/** See {@link EndpointOptions.dmOnly}. */
|
|
197
|
-
export interface DmOnlyOptions {
|
|
198
|
-
/** Receives each authenticated DM. A resolved promise does not ack: call `delivery.ack()`. A
|
|
199
|
-
* rejection is emitted as `error` and leaves the copy unacked, so the broker redelivers it. */
|
|
200
|
-
handler: (msg: CotalMessage, delivery: Delivery, meta: MessageMeta) => void | Promise<void>;
|
|
201
|
-
/** How long {@link CotalEndpoint.stop} waits for a running handler, in milliseconds. */
|
|
202
|
-
settleTimeoutMs?: number;
|
|
203
|
-
}
|
|
204
|
-
/** This endpoint's own `dm_` durable does not exist. A DM-only endpoint, and any endpoint on an
|
|
205
|
-
* authenticated mesh, binds the durable its provisioner created and never creates one. */
|
|
206
|
-
export declare class DmDurableMissingError extends Error {
|
|
207
|
-
readonly stream: string;
|
|
208
|
-
readonly durable: string;
|
|
209
|
-
readonly code: "dm-durable-missing";
|
|
210
|
-
constructor(stream: string, durable: string);
|
|
211
|
-
}
|
|
212
|
-
/** The broker refused a DM-only endpoint's bind of its own `dm_` durable. No other credential or
|
|
213
|
-
* read path is tried. */
|
|
214
|
-
export declare class DmBindRefusedError extends Error {
|
|
215
|
-
readonly stream: string;
|
|
216
|
-
readonly durable: string;
|
|
217
|
-
readonly code: "dm-bind-refused";
|
|
218
|
-
constructor(stream: string, durable: string, cause: unknown);
|
|
219
|
-
}
|
|
220
|
-
/** Raw NATS transport liveness for the endpoint's CURRENT connection epoch. This is deliberately
|
|
221
|
-
* separate from the `connection` event, which means the full Cotal bind is ready. */
|
|
222
|
-
export interface TransportState {
|
|
223
|
-
connected: boolean;
|
|
224
|
-
/** The server nats.js named for this edge. Omitted when the runtime supplied none. */
|
|
225
|
-
server?: string;
|
|
226
|
-
}
|
|
227
|
-
/**
|
|
228
|
-
* Events: "message" (CotalMessage), "presence" (PresenceEvent), "roster" (Presence[]), "error" (Error),
|
|
229
|
-
* "connection" ({ connected: boolean }) — true on every successful (re)bind (initial start, manual
|
|
230
|
-
* reconnect, AND background self-heal), false the moment the connection drops (rebuild null window /
|
|
231
|
-
* terminal close). Lets an in-process agent track connectedness off the endpoint's own (re)binds
|
|
232
|
-
* instead of an imperative flag the self-heal path can't reach; "transport" ({ connected, server? })
|
|
233
|
-
* is the lower-level NATS socket edge, true before the full bind finishes and false during an internal
|
|
234
|
-
* nats.js reconnect without changing `connection` readiness. "stored-copies-full" ({ limit: number }): a
|
|
235
|
-
* stored copy arrived with the store at the count the copy was written under ({@link deliveryLimitOf}),
|
|
236
|
-
* so the store may have discarded older copies before this session read them; emitted for each such
|
|
237
|
-
* copy. A lowering of the count or an age set on the store removes copies without this event.
|
|
238
|
-
*
|
|
239
|
-
* Callers MUST attach an "error" listener before `start()`: async faults (incl. NATS
|
|
240
|
-
* permission denials, surfaced via `watchStatus`) are emitted as "error", and Node throws
|
|
241
|
-
* synchronously on an unhandled "error" — a missing listener turns any such fault into a
|
|
242
|
-
* process crash instead of a logged denial.
|
|
243
|
-
*/
|
|
244
|
-
/** One page of a mediated history read: the newest `limit` messages, oldest-first WITHIN the page.
|
|
245
|
-
*
|
|
246
|
-
* `complete` is the honest-truncation signal and the reason this is not just `CotalMessage[]`:
|
|
247
|
-
* `true` means the page reaches the start of the channel's RETAINED history (nothing older is on
|
|
248
|
-
* the stream to read), `false` means older messages exist behind it. A caller that cannot tell
|
|
249
|
-
* those apart renders "there is more" as "this is the beginning of the conversation". It says
|
|
250
|
-
* nothing about messages already aged out by retention — no reader can see those. */
|
|
251
|
-
export type HistoryPage = {
|
|
252
|
-
items: CotalMessage[];
|
|
253
|
-
complete: boolean;
|
|
254
|
-
};
|
|
255
|
-
/** The NEWEST prefix-from-the-end of `items` whose serialized `readHistory` reply fits `budget`
|
|
256
|
-
* bytes, order preserved. Returns `[]` when not even the newest single message fits — the caller
|
|
257
|
-
* must refuse loudly there rather than serve an empty page, which would read as "no history".
|
|
258
|
-
*
|
|
259
|
-
* The `ControlReply` around the items rides the same NATS message, so it is charged too: items
|
|
260
|
-
* that fit on their own can still make a reply the broker refuses.
|
|
261
|
-
*
|
|
262
|
-
* Measured in ENCODED bytes, not `string.length`: a page of multi-byte text would otherwise be
|
|
263
|
-
* undercounted and still overflow the broker. Same discipline as `assertFactFits`. */
|
|
264
|
-
export declare function fitHistoryPage(items: CotalMessage[], budget: number): CotalMessage[];
|
|
265
|
-
/** A served principal endpoint (SPEC 13.21). */
|
|
266
|
-
export interface PrincipalServe {
|
|
267
|
-
/** Resolves once the broker accepted this process's subscription; rejects with its refusal. */
|
|
268
|
-
readonly ready: Promise<void>;
|
|
269
|
-
/** Resolves with the refusal that ended the serve, including one that arrives on a replaced
|
|
270
|
-
* connection after `ready` resolved. Never rejects, and never resolves after `stop`. */
|
|
271
|
-
readonly failed: Promise<Error>;
|
|
272
|
-
/** Unsubscribe, abort every handler's `signal`, and wait for each handler in flight until its
|
|
273
|
-
* request's deadline at most, which the route caps at 30 s. A reply that comes after that is
|
|
274
|
-
* dropped. */
|
|
275
|
-
stop(): Promise<void>;
|
|
276
|
-
}
|
|
22
|
+
export { DEFAULT_SERVER, isPublishPermissionDenied, wsServers, defaultProbeTimeoutMs, dialerFor, isAuthRejection, isReachable, type ProbeResult, probeConnect, } from "./endpoint-dial.js";
|
|
23
|
+
import { type EndpointOptions, type ChannelMember, type HistoryPage, type PrincipalServe } from "./endpoint-options.js";
|
|
24
|
+
export { deliveryLimitOf, DEFAULT_SPACE, type EndpointOptions, type ChannelMember, type DmOnlyOptions, DmDurableMissingError, DmBindRefusedError, type TransportState, type HistoryPage, fitHistoryPage, type PrincipalServe, } from "./endpoint-options.js";
|
|
25
|
+
export { isFromSubjectSender, } from "./endpoint-messages.js";
|
|
277
26
|
export declare class CotalEndpoint extends EventEmitter {
|
|
278
27
|
readonly card: AgentCard;
|
|
279
28
|
readonly space: string;
|
|
@@ -550,172 +299,43 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
550
299
|
private get authed();
|
|
551
300
|
start(): Promise<void>;
|
|
552
301
|
private startOnce;
|
|
553
|
-
/** The floor on a bearer renewal's delay. A token whose whole lifetime sits under it is renewed at
|
|
554
|
-
* this cadence (`expiry-renewal` mints 5s bearers). */
|
|
555
|
-
private static readonly BEARER_MIN_RENEWAL_MS;
|
|
556
|
-
/** A failed bearer renewal retries after about this long, doubling per failure up to the cap. */
|
|
557
|
-
private static readonly BEARER_RETRY_MS;
|
|
558
|
-
private static readonly BEARER_RETRY_CAP_MS;
|
|
559
302
|
/**
|
|
560
303
|
* A condition the endpoint is already surviving. Node rethrows `error` when no listener is
|
|
561
304
|
* attached, so emitting retry notices on `error` killed hosts that the endpoint intended to
|
|
562
305
|
* keep running (#891). `warning` is observable and never fatal without a listener.
|
|
563
306
|
*/
|
|
564
307
|
private emitRecoverable;
|
|
565
|
-
/**
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
*
|
|
569
|
-
*
|
|
308
|
+
/** The resident swap a reload scheduled, until its connection is back or the gate's bound ends. */
|
|
309
|
+
private residentSwap?;
|
|
310
|
+
/** Serializes every prove-then-adopt transaction (the 75% timer and the explicit reload) so a timer
|
|
311
|
+
* tick and an explicit reload can never interleave their fetch/preflight/commit — the design's
|
|
312
|
+
* single-flight requirement. Runs `fn` after any in-flight transaction settles, whatever its
|
|
313
|
+
* outcome; the internal chain never rejects. */
|
|
314
|
+
private credsTxn;
|
|
315
|
+
/** The bearer and credential renewal of this endpoint. Every dependency is read when it is used, so
|
|
316
|
+
* a field assigned after construction is seen. */
|
|
317
|
+
private readonly credentials;
|
|
318
|
+
/** Forwards to the credentials component's {@link EndpointCredentials.refreshBearer}. */
|
|
570
319
|
private refreshBearer;
|
|
571
|
-
|
|
572
|
-
/** The timed renewal. A new token moves the live connection onto itself at once, through the
|
|
573
|
-
* same controlled reconnect the creds path uses, so the broker never has to expire a connection
|
|
574
|
-
* this endpoint could renew. With no live connection, it ends the rebuild loop's wait instead:
|
|
575
|
-
* that loop refuses to dial an expired token and leaves the retries to this timer. */
|
|
576
|
-
private renewBearerOnTimer;
|
|
577
|
-
/** The cached bearer, checked: every (re)connect attempt reads it, the reconnects nats.js runs
|
|
578
|
-
* on its own included, so none presents an expired token, which the callout could only deny
|
|
579
|
-
* after a full round trip. The bearer counterpart of {@link credsForWire}. */
|
|
320
|
+
/** Forwards to the credentials component's {@link EndpointCredentials.bearerForWire}. */
|
|
580
321
|
private bearerForWire;
|
|
581
|
-
/**
|
|
582
|
-
* (75% of iat→exp), not a fixed margin — standing creds span hours to days, bearers minutes. */
|
|
583
|
-
private static readonly CREDS_RETRY_MS;
|
|
584
|
-
/** THE ONE PLACE a credential is cleared for presentation to a broker.
|
|
585
|
-
*
|
|
586
|
-
* The property is unconditional — this endpoint never presents a credential it has already
|
|
587
|
-
* decoded as expired — so it is a property of the SUPPLY, not of any one dial site. It used to
|
|
588
|
-
* live inside {@link bindConnection}, which only `start()` and `doRebuild` reach; the
|
|
589
|
-
* authenticator nats.js re-evaluates on ITS OWN reconnects read the cache directly and so
|
|
590
|
-
* presented whatever was last fetched, expired included. Two such reconnects exist and neither
|
|
591
|
-
* passes through bindConnection: the one the broker forces at JWT `exp`, and an ALREADY RUNNING
|
|
592
|
-
* dial loop from an earlier drop that crosses `exp` while it retries (the pre-expiry
|
|
593
|
-
* reconnect fence flips a policy flag nats-core only reads when it observes a NEW drop, so it
|
|
594
|
-
* cannot stop a loop already in flight).
|
|
595
|
-
*
|
|
596
|
-
* Putting the refusal here instead means a future caller cannot miss it: the only way to reach a
|
|
597
|
-
* dial is through {@link credsForWire}, and the one presentation that does not read the cache
|
|
598
|
-
* (the adoption preflight, which presents a fresh CANDIDATE) calls this same function on it.
|
|
599
|
-
*
|
|
600
|
-
* An unbounded credential (no numeric `exp`) is presentable: bounded lifetimes are the renewal
|
|
601
|
-
* seam's concern, and a cred with no expiry has none to be past. */
|
|
602
|
-
private static presentableCreds;
|
|
603
|
-
/** The connect attempt's credential getters: what {@link credsForWire} and {@link bearerForWire}
|
|
604
|
-
* return, with its expiry recorded as {@link presentedExp}. */
|
|
322
|
+
/** Forwards to the credentials component's {@link EndpointCredentials.presentCreds}. */
|
|
605
323
|
private presentCreds;
|
|
324
|
+
/** Forwards to the credentials component's {@link EndpointCredentials.presentBearer}. */
|
|
606
325
|
private presentBearer;
|
|
607
|
-
/** The cached credential, checked. Handed to nats.js as the authenticator's source on EVERY auth
|
|
608
|
-
* mode (renewed or static), so each (re)connect attempt — ours or the library's — re-reads a
|
|
609
|
-
* CHECKED value. A refusal throws out of the authenticator, which nats-core turns into a closed
|
|
610
|
-
* connection rather than a CONNECT carrying dead material; the endpoint's own supervisor then
|
|
611
|
-
* rebuilds on capped backoff, and {@link bindConnection} re-fetches from the source on each of
|
|
612
|
-
* those attempts, so a renewal that starts working recovers the endpoint without presenting
|
|
613
|
-
* anything expired in the meantime. Deliberately side-effect free: kicking the renewal timer
|
|
614
|
-
* from here would retry the source once per dial attempt, which is the flat load on a dead
|
|
615
|
-
* broker that {@link RETRY_BACKOFF_CAP_MS} exists to prevent. */
|
|
616
|
-
private credsForWire;
|
|
617
326
|
/** The credential this endpoint presents on its next connect, checked as {@link credsForWire}
|
|
618
327
|
* checks it. A second connection under the same identity reads it on every attempt, so it
|
|
619
328
|
* presents each credential this endpoint adopts and never an expired one. */
|
|
620
329
|
wireCreds(): string;
|
|
621
|
-
/**
|
|
622
|
-
* ({@link CREDS_RETRY_MS}) applies instead of the renewal schedule (issue #1523).
|
|
623
|
-
*
|
|
624
|
-
* A source that hands back the SAME generation past its own renewal point has not re-signed yet:
|
|
625
|
-
* that is a missed remint, not a candidate. Adopting it re-arms from a non-positive delay, which
|
|
626
|
-
* {@link armCredsRefresh} floors to 1s, which fetches again, which is the same generation — a 1s
|
|
627
|
-
* read loop against a store that is already having a bad day, for the JWT's remaining 25% of life,
|
|
628
|
-
* with the 60s backoff that exists for exactly this bypassed because the fetch did not FAIL.
|
|
629
|
-
*
|
|
630
|
-
* The membership feed's rw-cred renewal already refuses it this way (`membership-feed.ts`,
|
|
631
|
-
* `adoptRwCreds`: "the rw source still holds the previous generation past its renewal point");
|
|
632
|
-
* this is the same rule on the endpoint's `delivery.creds` seam, so the two renewal paths answer
|
|
633
|
-
* a dead source identically.
|
|
634
|
-
*
|
|
635
|
-
* An ALREADY-EXPIRED generation is refused whatever it is: the delay is non-positive for it too,
|
|
636
|
-
* but it is dead rather than merely due, so it is named separately and refused even when the
|
|
637
|
-
* source keeps returning a different one. */
|
|
638
|
-
private static assertRenewableGeneration;
|
|
639
|
-
/** The disposable-preflight connect bound for the EXPLICIT reload proof (D5 class-2 adoption). A
|
|
640
|
-
* rogue or unreachable candidate must resolve well UNDER the manager's delivery-admin request
|
|
641
|
-
* bound, so this stays a few seconds and never blocks the responder. */
|
|
642
|
-
private static readonly PREFLIGHT_MS;
|
|
643
|
-
/** How long the resident wire swap is deferred past the reply on the EXPLICIT reload path. The
|
|
644
|
-
* delivery-admin responder rides THIS connection, so `nc.reconnect()` must not run until the
|
|
645
|
-
* reply has flushed on the still-live old cred; the old cred stays valid until its exp, so a short
|
|
646
|
-
* deferral is safe. */
|
|
647
|
-
private static readonly RESIDENT_SWAP_DEFER_MS;
|
|
648
|
-
/** How long a delivery-admin request read after a reload waits for the resident swap's reconnect.
|
|
649
|
-
* nats.js drops a publish made while the connection is down when it redials, so a reply sent
|
|
650
|
-
* during the swap is lost and its caller waits out its whole request timeout. Past this bound the
|
|
651
|
-
* request is answered anyway, as it was before the gate. */
|
|
652
|
-
private static readonly RESIDENT_SWAP_GATE_MS;
|
|
653
|
-
/** The resident swap a reload scheduled, until its connection is back or the gate's bound ends. */
|
|
654
|
-
private residentSwap?;
|
|
655
|
-
/** The daemon-side deadline for the WHOLE prove-then-adopt transaction (source fetch + preflight +
|
|
656
|
-
* commit), kept strictly BELOW the manager's delivery-admin request bound so a slow or hung hosted
|
|
657
|
-
* store returns a structured component failure rather than an ambiguous client timeout, and a late
|
|
658
|
-
* fetch can never commit after the caller gave up. */
|
|
659
|
-
private static readonly RELOAD_DEADLINE_MS;
|
|
660
|
-
/** Fetch fresh creds from the source, pin their identity to ours, cache them, and arm the next
|
|
661
|
-
* refresh at 75% of the new JWT's lifetime. THROWS on fetch/pin failure — the callers decide the
|
|
662
|
-
* failure posture (loud-and-retry for the timer, a structured error reply for an explicit
|
|
663
|
-
* {@link reloadCreds}). This is the PASSIVE-BACKSTOP fetch; the explicit auditable path
|
|
664
|
-
* ({@link reloadCreds}) does its own fetch so it can preflight the candidate on a disposable
|
|
665
|
-
* connection BEFORE mutating this live cache. */
|
|
666
|
-
private fetchFreshCreds;
|
|
667
|
-
/** Swap the live connection onto the freshest cached cred or bearer with a controlled
|
|
668
|
-
* `nc.reconnect()` (nats.js re-evaluates the authenticator per attempt). Swapping now, instead of
|
|
669
|
-
* waiting for the broker to close the connection at `exp`, means the wire never carries a
|
|
670
|
-
* near-dead JWT and the operator never sees a spurious "authentication expired". After the
|
|
671
|
-
* reconnect succeeds, re-arm the expiry fence for the credential now authenticated on the wire. */
|
|
672
|
-
private swapConnectionOntoFreshCreds;
|
|
673
|
-
/** A second connection whose `onConnection` subscriptions are flushed before the resident
|
|
674
|
-
* reconnect. Its inbox is not the resident connection's inbox. A flush that does not finish
|
|
675
|
-
* closes it and leaves the caller to reconnect in place. */
|
|
676
|
-
private openRenewalOverlap;
|
|
677
|
-
/** nats-core keeps its reconnect switch on the protocol handler. This pinned internal shape is the
|
|
678
|
-
* same last-resort surface used by {@link closeFailedBind}; there is no public API for changing the
|
|
679
|
-
* reconnect policy of an existing connection. Disabling it does not disable Cotal self-heal: the
|
|
680
|
-
* `nc.closed()` supervisor below rebuilds the endpoint with freshly checked auth material. */
|
|
330
|
+
/** Forwards to the credentials component's {@link EndpointCredentials.disableLibraryReconnect}. */
|
|
681
331
|
private disableLibraryReconnect;
|
|
682
|
-
/**
|
|
683
|
-
* PING and waits for the matching PONG; nats-core only rejects that waiter inside reconnect
|
|
684
|
-
* `prepare()`, so a half-open socket with reconnect=false leaves drain pending until the 2-minute
|
|
685
|
-
* ping interval times out. `close()` tears the transport down without that round-trip, which is
|
|
686
|
-
* the same public path {@link closeFailedBind} already uses when there is no graceful delivery
|
|
687
|
-
* contract left. */
|
|
332
|
+
/** Forwards to the credentials component's {@link EndpointCredentials.closeWithoutLibraryReconnect}. */
|
|
688
333
|
private closeWithoutLibraryReconnect;
|
|
689
|
-
/**
|
|
690
|
-
* lead makes the policy change precede the broker's expiry close even when both timers wake in the
|
|
691
|
-
* same event-loop turn. A credential adoption does not move this fence until the resident reconnect
|
|
692
|
-
* is requested, so the old wire remains protected during the prove-then-adopt window. */
|
|
334
|
+
/** Forwards to the credentials component's {@link EndpointCredentials.armAuthExpiryReconnectFence}. */
|
|
693
335
|
private armAuthExpiryReconnectFence;
|
|
694
|
-
/**
|
|
695
|
-
* {@link currentCreds} so the connect() that immediately follows presents it — that connect IS the
|
|
696
|
-
* proof, so NO preflight and NO live swap here. THROWS when `initial` (no cred to start from), else
|
|
697
|
-
* emits and retries. The LIVE-SWAP paths — the 75% timer {@link renewCredsOnTimer} and the explicit
|
|
698
|
-
* {@link reloadCreds} — preflight the candidate on a disposable connection instead, so they never
|
|
699
|
-
* reconnect the live connection onto an unproven cred. */
|
|
336
|
+
/** Forwards to the credentials component's {@link EndpointCredentials.refreshCreds}. */
|
|
700
337
|
private refreshCreds;
|
|
701
|
-
/**
|
|
702
|
-
* tick and an explicit reload can never interleave their fetch/preflight/commit — the design's
|
|
703
|
-
* single-flight requirement. Runs `fn` after any in-flight transaction settles, whatever its
|
|
704
|
-
* outcome; the internal chain never rejects. */
|
|
705
|
-
private credsTxn;
|
|
706
|
-
private runCredsTxn;
|
|
707
|
-
/** The one PROVE-then-adopt transaction shared by the 75% timer and the explicit reload (run under
|
|
708
|
-
* {@link runCredsTxn}). Fetch (deadline-bounded) → identity-pin → optional `expected` fingerprint →
|
|
709
|
-
* PREFLIGHT the candidate on a disposable connection → fence a late commit against the deadline →
|
|
710
|
-
* commit {@link currentCreds} → arm the next 75% timer. Because currentCreds is written ONLY after
|
|
711
|
-
* the preflight proves broker acceptance, the resident authenticator getter can never present an
|
|
712
|
-
* unproven cred (not even on an incidental reconnect), and a rejected candidate leaves the resident
|
|
713
|
-
* connection untouched on BOTH the timer and explicit paths. THROWS (structured) on any failure. */
|
|
714
|
-
private adoptFreshCreds;
|
|
715
|
-
/** The 75%-of-lifetime renewal timer tick: prove + adopt + swap the LIVE connection. Preflights (it
|
|
716
|
-
* reconnects a live connection, so the candidate must be broker-proven first) and is serialized
|
|
717
|
-
* with the explicit reload. Never throws — a failed renewal logs and retries while the old cred
|
|
718
|
-
* stays live until its expiry. */
|
|
338
|
+
/** Forwards to the credentials component's {@link EndpointCredentials.renewCredsOnTimer}. */
|
|
719
339
|
private renewCredsOnTimer;
|
|
720
340
|
/** Fetch, broker-prove and adopt the source credential, then refresh the same connection
|
|
721
341
|
* once outgoing mux and named-reply requests are quiet. A busy timeout retains the connection
|
|
@@ -743,18 +363,8 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
743
363
|
iat?: number;
|
|
744
364
|
exp?: number;
|
|
745
365
|
}>;
|
|
746
|
-
/**
|
|
747
|
-
* {@link handleDeliveryAdmin} ONLY after BOTH component proofs have settled and immediately before
|
|
748
|
-
* the reply is returned+responded — never from inside {@link reloadCreds} while the aggregate is
|
|
749
|
-
* still open, or a slow co-component proof would let `nc.reconnect()` reconnect the admin rail
|
|
750
|
-
* before the reply flushes and silently strand it. The short deferral lets the reply flush on the
|
|
751
|
-
* still-live old cred first. Best-effort — the proof was the preflight; a transient swap failure is
|
|
752
|
-
* retried by the 75% timer and the broker's own expiry-close, both presenting the adopted candidate.
|
|
753
|
-
* Until the swapped connection is back, {@link residentSwap} holds the delivery-admin requests that
|
|
754
|
-
* arrive after this reply. */
|
|
366
|
+
/** Forwards to the credentials component's {@link EndpointCredentials.scheduleResidentSwap}. */
|
|
755
367
|
private scheduleResidentSwap;
|
|
756
|
-
/** Resolve when this endpoint reports its transport connected again, or after `ms`. */
|
|
757
|
-
private transportBack;
|
|
758
368
|
private armCredsRefresh;
|
|
759
369
|
/** Open the connection and bind everything that hangs off it: status watch, presence
|
|
760
370
|
* watch + heartbeat, channel registry, and the durable consumers. Re-runnable — a
|
|
@@ -2412,124 +2022,4 @@ export declare class CotalEndpoint extends EventEmitter {
|
|
|
2412
2022
|
private readChannelsOnce;
|
|
2413
2023
|
private sweep;
|
|
2414
2024
|
}
|
|
2415
|
-
/** SPEC §5 on receive: a delivery comes from the principal its subject names. The payload is an
|
|
2416
|
-
* object whose `from.id` is the subject's sender, and the subject's owner is a real principal, not
|
|
2417
|
-
* an old-shape alias. Every receive path asks this one predicate. What a path does with a refusal
|
|
2418
|
-
* (drop, skip, ack, term or reject) and its own extra checks (a usable id, its own echo) stay with
|
|
2419
|
-
* the path. */
|
|
2420
|
-
export declare function isFromSubjectSender(msg: unknown, parsed: ParsedSubject): boolean;
|
|
2421
|
-
/** Auth subset of connect() options, shared by the endpoint and isReachable. `bearer` may be a
|
|
2422
|
-
* sync GETTER — nats.js re-evaluates token authenticators per (re)connect attempt, which is how a
|
|
2423
|
-
* refreshing endpoint presents its freshest bearer without rebuilding the connection options. */
|
|
2424
|
-
interface AuthOpts {
|
|
2425
|
-
token?: string;
|
|
2426
|
-
user?: string;
|
|
2427
|
-
pass?: string;
|
|
2428
|
-
/** May be a sync GETTER (like `bearer`) — the authenticator then re-reads it per (re)connect
|
|
2429
|
-
* attempt, which is how a standing-renewal endpoint presents its freshest cred. */
|
|
2430
|
-
creds?: string | (() => string);
|
|
2431
|
-
/** Observe only the credential actually presented, including native reconnect authentication. */
|
|
2432
|
-
onCreds?: (creds: string) => void;
|
|
2433
|
-
bearer?: string | (() => string);
|
|
2434
|
-
sentinelCreds?: string;
|
|
2435
|
-
tls?: boolean;
|
|
2436
|
-
}
|
|
2437
|
-
/** True ONLY for a denial on a **publish** — the single case that proves the message was never
|
|
2438
|
-
* ACCEPTED or stored. (Not "never reached the server": the server necessarily received enough of
|
|
2439
|
-
* it to reject it. The distinction matters precisely here, because this helper exists to separate
|
|
2440
|
-
* provably-not-stored from possibly-stored, and the looser phrasing overstates the very thing
|
|
2441
|
-
* being measured.) {@link isPermissionDenied} deliberately does not look at the operation: it exists to
|
|
2442
|
-
* separate "denied" from "service down", and that answer is the same either way. The operation
|
|
2443
|
-
* matters enormously to a caller that reports *delivery*, because a JetStream publish is
|
|
2444
|
-
* request/PubAck and the subscription half is the reply inbox — a denial THERE rejects
|
|
2445
|
-
* `js.publish()` while the stream may already hold the message. Verified against a live broker: a
|
|
2446
|
-
* user allowed to publish but denied its `_INBOX` subscription got
|
|
2447
|
-
* `Permissions Violation for Subscription to "_INBOX.….*"` back from `js.publish()`, and an
|
|
2448
|
-
* unrestricted observer then read `messages: 1` off the stream.
|
|
2449
|
-
*
|
|
2450
|
-
* Note what is deliberately NOT accepted: the untyped text fallback above. A permission-shaped
|
|
2451
|
-
* message string carries no operation, so it cannot prove non-delivery, and guessing "publish"
|
|
2452
|
-
* from wording would reintroduce exactly the false certainty this exists to prevent. Anything not
|
|
2453
|
-
* provably a publish denial is unknown, and a caller reporting delivery must fail toward
|
|
2454
|
-
* "I could not confirm" rather than toward "it did not happen" — the costly mistake is telling
|
|
2455
|
-
* someone to re-send a message that was in fact stored. */
|
|
2456
|
-
export declare function isPublishPermissionDenied(e: unknown): boolean;
|
|
2457
|
-
/** Whether a server list dials over websocket: the FIRST entry's scheme decides (one list, one
|
|
2458
|
-
* transport — a mixed tcp+ws list would race two transports over one identity). */
|
|
2459
|
-
export declare function wsServers(servers: string): boolean;
|
|
2460
|
-
/** Default probe budget by TRANSPORT. 1s was tuned for the loopback/LAN TCP brokers every local
|
|
2461
|
-
* probe dials; a ws(s) broker is by definition published through an HTTPS edge (CDN tunnel,
|
|
2462
|
-
* reverse proxy), where TLS + upgrade + INFO + the auth round-trip routinely exceeds 1s cold —
|
|
2463
|
-
* measured ~60% spurious "not reachable" against a Cloudflare-fronted broker. Callers passing an
|
|
2464
|
-
* explicit `timeoutMs` are untouched.
|
|
2465
|
-
*
|
|
2466
|
-
* EXPORTED because a caller that judges a probe by WHEN it answered has to compare against the
|
|
2467
|
-
* deadline this function actually handed the probe. The delivery watchdog does exactly that, and
|
|
2468
|
-
* hardcoding 1000 there silently misread every ws broker: honest refusals arrive at 2-5s, past a
|
|
2469
|
-
* budget that was never theirs, and would be classified as this process's starvation rather than
|
|
2470
|
-
* the server's refusal. The budget and the judgment must come from one place. */
|
|
2471
|
-
export declare function defaultProbeTimeoutMs(servers: string): number;
|
|
2472
|
-
/** Pick the dial function by SCHEME: `ws://`/`wss://` servers go through nats-core's
|
|
2473
|
-
* `wsconnect` (the websocket transport - e.g. a broker published through an HTTPS edge at
|
|
2474
|
-
* `wss://host/path`), everything else through the TCP transport. The websocket dial OWNS its
|
|
2475
|
-
* transport options: a required TLS connection refuses any `ws://` target before dialing.
|
|
2476
|
-
* `wss://` performs TLS itself, and the w3c transport refuses a `tls` block outright
|
|
2477
|
-
* ("'tls' is not configurable"), so the block is removed after that check.
|
|
2478
|
-
* A TCP dial that requires TLS to one IP address names that address as the host its certificate
|
|
2479
|
-
* must cover (see {@link withDialedTlsHost}). */
|
|
2480
|
-
export declare function dialerFor(servers: string): typeof connect;
|
|
2481
|
-
/** Whether a failed connect was the server refusing these credentials: a server answered, so it is
|
|
2482
|
-
* up. The same errors {@link isReachable} reads as up after its own authenticated connect. */
|
|
2483
|
-
export declare function isAuthRejection(e: unknown): boolean;
|
|
2484
|
-
/** Whether a NATS server is *running* at `servers`. With NO creds this is a SILENT plaintext
|
|
2485
|
-
* liveness check ({@link tcpInfoProbe}): it reads the server's pre-auth `INFO` greeting and closes
|
|
2486
|
-
* WITHOUT authenticating, so a live broker (open OR auth — INFO precedes auth) returns true while
|
|
2487
|
-
* emitting no broker auth-error log. It may return false for a TLS-first listener — the credless
|
|
2488
|
-
* probe is plaintext-only. With creds/token/tls supplied it is instead the AUTHORITATIVE identity
|
|
2489
|
-
* check: a real authenticated connect, true on success AND on an auth rejection (a server that
|
|
2490
|
-
* refuses these creds is still up — so the caller surfaces the real auth failure, and `up` won't
|
|
2491
|
-
* start a duplicate on the bound port). Only a genuine connection failure (refused/timeout) is false. */
|
|
2492
|
-
export declare function isReachable(servers?: string, opts?: AuthOpts & {
|
|
2493
|
-
timeoutMs?: number;
|
|
2494
|
-
}): Promise<boolean>;
|
|
2495
|
-
/** What a connect attempt told us about the server — the distinction {@link isReachable} flattens.
|
|
2496
|
-
* `auth-required` means a server answered but rejected these creds (so it IS up); `stale-auth`
|
|
2497
|
-
* means the PRESENTED CREDENTIAL ITSELF is dead — expired by its bounded lifetime, either because
|
|
2498
|
-
* the broker said "authentication expired" or because the cred is LOCALLY PROVABLY expired (its own
|
|
2499
|
-
* JWT `exp` is past). The local check is decided without a round-trip, so a slow or failed connect
|
|
2500
|
-
* never downgrades a dead cred to `unreachable`; the repair is `doctor auth` either way, never a
|
|
2501
|
-
* registry prune (the D5 credential-death event). `unreachable` means nothing usable answered and
|
|
2502
|
-
* the cred is not provably dead (refused / timeout / a stale registry entry). `timeout` means the
|
|
2503
|
-
* dial ran out of its own budget before anything conclusive came back — never a trust or credential
|
|
2504
|
-
* verdict, just "try again with more time" (#851). `inferred` marks an `auth-required` read from
|
|
2505
|
-
* the broker's greeting rather than from a rejection: the greeting asked for auth and the handshake
|
|
2506
|
-
* was then reset. The greeting is unauthenticated, so that verdict may name a failure but must never
|
|
2507
|
-
* be grounds for deleting state. */
|
|
2508
|
-
export type ProbeResult = {
|
|
2509
|
-
ok: true;
|
|
2510
|
-
} | {
|
|
2511
|
-
ok: false;
|
|
2512
|
-
reason: "auth-required";
|
|
2513
|
-
inferred?: true;
|
|
2514
|
-
} | {
|
|
2515
|
-
ok: false;
|
|
2516
|
-
reason: "stale-auth";
|
|
2517
|
-
} | {
|
|
2518
|
-
ok: false;
|
|
2519
|
-
reason: "unreachable";
|
|
2520
|
-
} | {
|
|
2521
|
-
ok: false;
|
|
2522
|
-
reason: "tls-unsupported";
|
|
2523
|
-
} | {
|
|
2524
|
-
ok: false;
|
|
2525
|
-
reason: "timeout";
|
|
2526
|
-
};
|
|
2527
|
-
/** Like {@link isReachable}, but distinguishes "up but won't take these creds" from "nothing there".
|
|
2528
|
-
* `spawn` needs the difference: auth-required → name the trust dir + next step; unreachable → the
|
|
2529
|
-
* mesh is down (prune the stale entry, tell the user to `cotal up`). Pass `creds` to confirm a
|
|
2530
|
-
* specific identity is accepted (`ok`); omit them to probe mere liveness (an auth broker answers
|
|
2531
|
-
* `auth-required`, which still proves it's up). */
|
|
2532
|
-
export declare function probeConnect(server?: string, opts?: AuthOpts & {
|
|
2533
|
-
timeoutMs?: number;
|
|
2534
|
-
}): Promise<ProbeResult>;
|
|
2535
2025
|
//# sourceMappingURL=endpoint.d.ts.map
|