@cotal-ai/core 0.168.0 → 0.169.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/dist/agent-file.d.ts.map +1 -1
  2. package/dist/agent-file.js +12 -9
  3. package/dist/agent-file.js.map +1 -1
  4. package/dist/connector-setup.d.ts +2 -0
  5. package/dist/connector-setup.d.ts.map +1 -1
  6. package/dist/connector.d.ts +8 -11
  7. package/dist/connector.d.ts.map +1 -1
  8. package/dist/control-exchange.d.ts +114 -0
  9. package/dist/control-exchange.d.ts.map +1 -0
  10. package/dist/control-exchange.js +416 -0
  11. package/dist/control-exchange.js.map +1 -0
  12. package/dist/endpoint-call.d.ts +2 -1
  13. package/dist/endpoint-call.d.ts.map +1 -1
  14. package/dist/endpoint-call.js +14 -7
  15. package/dist/endpoint-call.js.map +1 -1
  16. package/dist/endpoint-delivery-plane.d.ts +337 -0
  17. package/dist/endpoint-delivery-plane.d.ts.map +1 -0
  18. package/dist/endpoint-delivery-plane.js +1291 -0
  19. package/dist/endpoint-delivery-plane.js.map +1 -0
  20. package/dist/endpoint-envelope.d.ts +2 -1
  21. package/dist/endpoint-envelope.d.ts.map +1 -1
  22. package/dist/endpoint-envelope.js +9 -3
  23. package/dist/endpoint-envelope.js.map +1 -1
  24. package/dist/endpoint-history.d.ts +370 -0
  25. package/dist/endpoint-history.d.ts.map +1 -0
  26. package/dist/endpoint-history.js +969 -0
  27. package/dist/endpoint-history.js.map +1 -0
  28. package/dist/endpoint-inbound.d.ts +10 -0
  29. package/dist/endpoint-inbound.d.ts.map +1 -0
  30. package/dist/endpoint-inbound.js +28 -0
  31. package/dist/endpoint-inbound.js.map +1 -0
  32. package/dist/endpoint-serve.d.ts +11 -1
  33. package/dist/endpoint-serve.d.ts.map +1 -1
  34. package/dist/endpoint-serve.js +42 -5
  35. package/dist/endpoint-serve.js.map +1 -1
  36. package/dist/endpoint-subjects.d.ts +3 -0
  37. package/dist/endpoint-subjects.d.ts.map +1 -1
  38. package/dist/endpoint-subjects.js +3 -0
  39. package/dist/endpoint-subjects.js.map +1 -1
  40. package/dist/endpoint.d.ts +64 -253
  41. package/dist/endpoint.d.ts.map +1 -1
  42. package/dist/endpoint.js +177 -2015
  43. package/dist/endpoint.js.map +1 -1
  44. package/dist/index.d.ts +2 -1
  45. package/dist/index.d.ts.map +1 -1
  46. package/dist/index.js +4 -1
  47. package/dist/index.js.map +1 -1
  48. package/dist/launch-material.d.ts +9 -3
  49. package/dist/launch-material.d.ts.map +1 -1
  50. package/dist/launch-material.js +22 -2
  51. package/dist/launch-material.js.map +1 -1
  52. package/dist/provision-permissions.d.ts.map +1 -1
  53. package/dist/provision-permissions.js +7 -1
  54. package/dist/provision-permissions.js.map +1 -1
  55. package/dist/remote-manager-authority.d.ts +1 -1
  56. package/dist/run-journal.d.ts +2 -0
  57. package/dist/run-journal.d.ts.map +1 -1
  58. package/dist/run-journal.js +1 -1
  59. package/dist/run-journal.js.map +1 -1
  60. package/package.json +5 -1
@@ -0,0 +1,969 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import { setTimeout as delay } from "node:timers/promises";
3
+ import { nanos } from "@nats-io/transport-node";
4
+ import { jetstream, jetstreamManager, AckPolicy, DeliverPolicy, JetStreamApiError } from "@nats-io/jetstream";
5
+ import { chatStream, dmStream, chatSubject, chatHistDurable, spacePrefix, parseSubject, subjectMatches, assertValidChannel, assertValidOwnerToken, isConcreteChannel, isChannelFamily, historyReaderConsumer, HISTORY_READERS, calloutReaderId } from "./subjects.js";
6
+ import { isConsumerAlreadyExists, isConsumerNotFound } from "./jetstream-missing.js";
7
+ import { isPermissionDenied } from "./permission-denied.js";
8
+ /** A history reader's inactive threshold. It bounds only a reader whose delete never ran (its link
9
+ * dropped, or its process stopped), because every read deletes its readers when it ends. Five
10
+ * minutes is what the nats.js ordered consumers it replaces carried, and it keeps a reader alive
11
+ * across the gap between pulls on a slow link. */
12
+ const HISTORY_READER_INACTIVE_MS = 5 * 60_000;
13
+ /** How many channel filters one multi-filter consumer create may carry.
14
+ *
15
+ * A create names every requested channel in one request, so the request grows with the channel
16
+ * count and the CLIENT's request timeout is what gives way, not the broker: the create is never
17
+ * refused, it just does not answer. Measured on an isolated broker, one message per channel,
18
+ * `limit=5`: 70 filters answer in 43ms, 1,000 in 246ms, 5,000 in 5,345ms, and 10,000 does not
19
+ * answer at all, failing `timeout` after 5,023ms. Note 5,000 SUCCEEDED while taking longer than
20
+ * 10,000 took to fail, which is what says the ceiling is on the create request rather than on the
21
+ * read: past roughly 5s the create itself is what times out.
22
+ *
23
+ * 1,000 is chosen from that sweep rather than from the failure point: it is a fifth of the largest
24
+ * count that still answered, and it answers in a quarter second, so a batch stays far away from
25
+ * both the timeout and the response-deadline budget the dashboard has to share with its DM read.
26
+ * A space with the 69 chat channels this was built for is still ONE read, so the round-trip claim
27
+ * in #1210 is unchanged at that size. */
28
+ export const MULTI_FILTER_BATCH = 1_000;
29
+ /** How many filter batches may be in flight at once. Bounded because the point of #1210 was to stop
30
+ * issuing one read per channel: a space large enough to need batches must not get the fan-out back
31
+ * under another name. */
32
+ export const MULTI_FILTER_READ_CONCURRENCY = 4;
33
+ /** What a history read failure NAMES when it could not finish. One filter subject is the useful
34
+ * thing to print; a set of sixty-nine of them is a wall of text in a message a human has to read,
35
+ * so a set says its size and the stream it was read from instead. */
36
+ function subjectLabel(subjects) {
37
+ return subjects.length === 1 ? subjects[0] : `${subjects.length} filtered subjects`;
38
+ }
39
+ /** The signal's exact abort reason, or the platform-standard AbortError when none was supplied. */
40
+ function abortReason(signal) {
41
+ return signal?.reason instanceof Error
42
+ ? signal.reason
43
+ : new DOMException("This operation was aborted", "AbortError");
44
+ }
45
+ /** Retained-history reads and private reader allocation for one endpoint. */
46
+ export class EndpointHistory {
47
+ deps;
48
+ /** Serializes history reads ({@link collectHistory}): they share the fixed per-instance
49
+ * `chathist_<id>` consumer, so overlapping reads would delete/recreate it under one another. */
50
+ histLock = Promise.resolve();
51
+ /** Per stream, the history-reader names of this connection's current reader id and the reads
52
+ * waiting for one (see {@link acquireHistoryReader}). */
53
+ historyReaderSlots = new Map();
54
+ constructor(deps) {
55
+ this.deps = deps;
56
+ }
57
+ get nc() { return this.deps.connection(); }
58
+ get js() { return this.deps.jetstream(); }
59
+ get jsm() { return this.deps.manager(); }
60
+ set jsm(manager) {
61
+ this.deps.setManager(manager);
62
+ }
63
+ get space() { return this.deps.space(); }
64
+ get owner() { return this.deps.owner(); }
65
+ get actor() { return this.deps.actor(); }
66
+ get userMode() { return this.deps.userMode(); }
67
+ get connId() { return this.deps.connectionId(); }
68
+ get card() { return this.deps.card(); }
69
+ /** Fetch recent messages from a channel's JetStream backlog. `signal` cancels the active pull and
70
+ * reclaims its ephemeral consumer before the promise rejects. Returns `HistoryMessage[]`
71
+ * (#1413): every field present on a row was checked by the drain before the row was
72
+ * returned — a stored row missing `ts` / `space` / `parts` / `from.name` is dropped, never
73
+ * returned with that member silently `undefined`.
74
+ *
75
+ * `publisher` reads only what that one principal published on the channel, by filtering on its
76
+ * own subject (`chat.<owner>.<actor>.<channel>`). The subject's sender slots are what the
77
+ * broker's publish permissions police, so on a mesh with permissions every row of such a read was
78
+ * published by that principal: the same guarantee a live subscription to that subject gives.
79
+ * Without it the read is the channel from any sender. */
80
+ async channelHistory(channel, opts) {
81
+ const from = opts?.publisher;
82
+ // A publisher is one principal. A `*` in either slot would widen the read back to any sender
83
+ // while the caller believes it narrowed it, so both slots are checked as concrete tokens.
84
+ const subject = from === undefined
85
+ ? chatSubject(this.space, "*", "*", channel)
86
+ : chatSubject(this.space, assertValidOwnerToken(from.owner), assertValidOwnerToken(from.actor), channel);
87
+ return (await this.streamHistory(chatStream(this.space), [subject], opts?.limit ?? 100, undefined, opts?.signal)).map((r) => r.msg);
88
+ }
89
+ /** Read one concrete channel using this lifecycle's single-filter CHAT grant (SPEC §8/§9).
90
+ * No observer authority, presence or delivery ACL mirror is required. Returns the newest page,
91
+ * oldest-first, including this caller's own sends. `complete` says no older valid row remains.
92
+ * Reads have a ten-second budget, shortened by `signal`. Concurrent connections sharing this
93
+ * lifecycle wait for native consumer inactivity cleanup; they never delete another reader. */
94
+ async channelHistoryPage(channel, opts) {
95
+ assertValidChannel(channel);
96
+ if (!isConcreteChannel(channel))
97
+ throw new Error("channelHistoryPage requires one concrete channel");
98
+ const limit = opts?.limit ?? 50;
99
+ if (!Number.isSafeInteger(limit) || limit < 1)
100
+ throw new Error("channelHistoryPage limit must be a positive safe integer");
101
+ if (!this.nc || !this.js)
102
+ throw new Error(this.deps.notLiveMsg());
103
+ const jsm = this.jsm ??= await jetstreamManager(this.nc);
104
+ const signal = AbortSignal.any([AbortSignal.timeout(10_000), ...(opts?.signal ? [opts.signal] : [])]);
105
+ signal.throwIfAborted();
106
+ const stream = chatStream(this.space);
107
+ const name = chatHistDurable(this.owner, this.actor, this.deps.requireLifecycleUid("channelHistoryPage"));
108
+ const subject = chatSubject(this.space, "*", "*", channel);
109
+ const marker = randomUUID();
110
+ let created;
111
+ for (;;) {
112
+ signal.throwIfAborted();
113
+ try {
114
+ // The pinned client's add is CREATE-only. A unique description makes even an otherwise
115
+ // identical occupied config conflict. Never bind/update it or pre-delete by shared name.
116
+ created = await jsm.consumers.add(stream, {
117
+ name, description: marker, filter_subject: subject,
118
+ ack_policy: AckPolicy.None, deliver_policy: DeliverPolicy.All,
119
+ mem_storage: true, inactive_threshold: nanos(250),
120
+ });
121
+ break;
122
+ }
123
+ catch (e) {
124
+ if (!(e instanceof JetStreamApiError) || e.code !== 10148)
125
+ throw e; // consumer already exists
126
+ await delay(50, undefined, { signal });
127
+ }
128
+ }
129
+ signal.throwIfAborted();
130
+ const owns = (info) => info.created === created.created &&
131
+ info.config.description === marker && info.config.filter_subject === subject;
132
+ if (!owns(created))
133
+ throw new Error("channelHistoryPage: consumer ownership was not established");
134
+ const consumer = await this.js.consumers.get(stream, name);
135
+ const pending = created.num_pending;
136
+ const out = [];
137
+ let delivered = 0;
138
+ if (pending > 0) {
139
+ const iter = await consumer.consume({ max_messages: Math.min(pending, 32) });
140
+ const stop = () => iter.stop(abortReason(signal));
141
+ signal.addEventListener("abort", stop, { once: true });
142
+ try {
143
+ signal.throwIfAborted();
144
+ for await (const m of iter) {
145
+ signal.throwIfAborted();
146
+ if (!subjectMatches(subject, m.subject))
147
+ throw new Error("channelHistoryPage: consumer delivered another channel; ownership was lost");
148
+ delivered++;
149
+ const msg = this.deps.decodeHistory(m);
150
+ if (msg) {
151
+ out.push(msg);
152
+ if (out.length > limit + 1)
153
+ out.shift();
154
+ }
155
+ if (delivered >= pending)
156
+ break;
157
+ }
158
+ }
159
+ finally {
160
+ signal.removeEventListener("abort", stop);
161
+ iter.stop();
162
+ }
163
+ signal.throwIfAborted();
164
+ if (delivered !== pending)
165
+ throw new Error(`channelHistoryPage: read ${delivered} of ${pending} messages before the window was cut short`);
166
+ }
167
+ signal.throwIfAborted();
168
+ // A legacy join/recall reader can delete/recreate this fixed name. A final ownership check
169
+ // makes that interference loud. It is detection, not a fence against those legacy readers.
170
+ if (!owns(await consumer.info()))
171
+ throw new Error("channelHistoryPage: consumer ownership was lost");
172
+ signal.throwIfAborted();
173
+ // No DELETE, even after abort: a delayed owner could otherwise delete its successor between
174
+ // INFO and DELETE. Native inactivity reaps this transient reader without that TOCTOU race.
175
+ return { items: out.slice(-limit), complete: out.length <= limit };
176
+ }
177
+ /**
178
+ * The newest `limit` chat messages across concrete channels or one channel family, oldest-first within the page,
179
+ * each tagged with the channel the BROKER delivered it on.
180
+ *
181
+ * The CHAT stream interleaves every channel into one sequence space. Consumers take sets of
182
+ * filter subjects for the requested channels. Large filter sets are read in batches, and the
183
+ * pages are merged by stream sequence to select the newest `limit` messages overall.
184
+ *
185
+ * **The broker does the filtering, so the wire carries only what is asked for.** A channel left
186
+ * out of `channels` costs nothing: its messages are never delivered, so a space whose volume is
187
+ * dominated by channels the caller does not want stays cheap.
188
+ *
189
+ * **The channel comes from the SUBJECT, never from the payload.** A message claims a `channel`
190
+ * field, and this method ignores it: the tag is derived from the subject the broker routed the
191
+ * message on, the same derivation {@link listChannels} uses to name a channel in the first place.
192
+ *
193
+ * A single channel family such as `events.>` uses one broker filter without enumerating its
194
+ * concrete channels. Otherwise every channel must be concrete: mixing a family with other
195
+ * filters, or using other wildcard patterns, is refused rather than risking overlapping filters.
196
+ *
197
+ * **The broker enforces read authority.** A multi-filter create
198
+ * cannot encode its filter in the API subject, so it rides the bare
199
+ * `$JS.API.CONSUMER.CREATE.<CHAT>` row that only the read-only dashboard profiles hold. An agent
200
+ * credential pins the filter into the subject per channel and is denied here by the broker, which
201
+ * is the correct answer: this method reads across channels, and an agent's read ACL is per
202
+ * channel. A single filter uses the filter-bearing create subject, including a channel family,
203
+ * so the broker checks the credential's grant for that filter. No additional authority is minted.
204
+ */
205
+ async multiChannelHistory(channels, opts) {
206
+ const subjects = [...new Set(channels.map((channel) => {
207
+ if (!isConcreteChannel(channel) && !(channels.length === 1 && isChannelFamily(channel)))
208
+ throw new Error(`multiChannelHistory: "${channel}" is a wildcard channel - name one channel family alone or concrete channels without wildcards`);
209
+ // `chatSubject` builds the filter through `token()`, which REWRITES rather than refuses: it
210
+ // maps a character a subject may not carry to `_`, trims each segment, and drops empty ones.
211
+ // So "foo/bar" would filter on `foo_bar`, ".lead" on `lead`, and "team..b" on `team.b` - the
212
+ // caller names one channel and the broker returns another, which is the exact promise this
213
+ // method makes ("a channel left out of the list never crosses the link") inverted. This is the
214
+ // same aliasing `assertValidChannel` was written for on the policy path; the read path needs
215
+ // it too, and it fails loud rather than serving a channel nobody asked for.
216
+ assertValidChannel(channel);
217
+ return chatSubject(this.space, "*", "*", channel);
218
+ }))];
219
+ // No channels is not an empty stream, but it IS an empty answer, and asking the broker for a
220
+ // consumer with no filter would read the WHOLE stream instead of none of it.
221
+ if (subjects.length === 0)
222
+ return [];
223
+ const limit = opts?.limit ?? 100;
224
+ // ONE CREATE CANNOT CARRY AN UNBOUNDED FILTER LIST. The create names every subject in one
225
+ // request and the client's request timeout is what gives way, so past roughly 5,000 filters the
226
+ // read does not answer at all and the route loses the whole chat source: measured on an
227
+ // isolated broker, 10,000 channels failed `timeout` after 5,023ms while the fan-out this
228
+ // replaced still returned 2,739 messages on the same corpus. Reading in batches keeps the
229
+ // single-read cost at the sizes this was built for (69 channels is one batch, so #1210's
230
+ // round-trip numbers are unchanged) and degrades to a few reads instead of none above that.
231
+ // `batch` is a knob rather than a constant so the batched path can be compared against the
232
+ // single-create path on ONE corpus: forcing a small batch makes a space that would otherwise be
233
+ // one read take many, which is the only way to assert the two select the same messages.
234
+ const size = Math.max(1, Math.trunc(opts?.batch ?? MULTI_FILTER_BATCH));
235
+ const batches = [];
236
+ for (let i = 0; i < subjects.length; i += size)
237
+ batches.push(subjects.slice(i, i + size));
238
+ const pages = new Array(batches.length);
239
+ let next = 0;
240
+ const readBatch = async () => {
241
+ for (;;) {
242
+ const i = next++;
243
+ if (i >= batches.length)
244
+ return;
245
+ pages[i] = await this.streamHistory(chatStream(this.space), batches[i], limit, undefined, opts?.signal);
246
+ }
247
+ };
248
+ // A BATCH THAT FAILS FAILS THE READ. Returning the batches that answered would be the newest
249
+ // `limit` across SOME of the channels asked for while looking like the newest across all of
250
+ // them, which is a wrong page presented as a right one. Throwing keeps the caller's existing
251
+ // envelope: the dashboard marks `chat` missing and says the page is partial, which is what it
252
+ // already did when this method was one read.
253
+ await Promise.all(Array.from({ length: Math.min(MULTI_FILTER_READ_CONCURRENCY, batches.length) }, readBatch));
254
+ // MERGE ON ARRIVAL, NOT ON `ts`. Each batch returns the newest `limit` within its own subjects,
255
+ // and the newest `limit` overall is a subset of their union, so re-selecting by stream sequence
256
+ // reproduces exactly what one create over the whole list would have selected. Sorting by the
257
+ // payload's `ts` here instead would change which messages the page holds, which is the
258
+ // selection question this pull request already had to answer once.
259
+ const rows = pages.flat().sort((a, b) => a.seq - b.seq).slice(-limit);
260
+ return rows.map(({ seq, subject, msg }) => {
261
+ const p = parseSubject(subject);
262
+ // The filter set is built from chat subjects, so this cannot fire against a healthy broker.
263
+ // It is here because the alternative to raising is tagging a message with a guess.
264
+ if (p?.kind !== "chat")
265
+ throw new Error(`multiChannelHistory: the broker delivered ${subject}, which is not a chat subject on this space`);
266
+ return { channel: p.rest, seq, msg };
267
+ });
268
+ }
269
+ /** Read a channel's recent history through the delivery daemon, using a provisioned ACL mirror.
270
+ * SPEC's ban on raw control-surface stream reads does not remove the single-channel CHAT grant.
271
+ * Human callers without an ACL mirror use {@link channelHistoryPage}; this method adds fresh
272
+ * mirror checks for provisioned readers. `items` is shape-identical to what {@link channelHistory}
273
+ * returns — the same `CotalMessage[]`, the same newest-N selection, the same oldest-first order
274
+ * within the page — so a caller migrates by reading `.items` and nothing else changes. The return
275
+ * is WRAPPED rather than bare precisely because of `complete`: a bare array cannot say whether
276
+ * older history remains behind it.
277
+ *
278
+ * **Why this exists when `channelHistory` already works:** authorization. A consumer pins its
279
+ * authorization at CREATE time, so a caller whose read ACL is revoked mid-scroll keeps being served
280
+ * by the consumer it already holds. The mediator re-reads authorization on EVERY call (live
281
+ * registry row ∩ mint-time ceiling — SPEC §9.6), so a revocation stops the very next read and a
282
+ * registry-only widen cannot exceed the effective credential. That is the whole point of the verb;
283
+ * a mediator that cached the ACL would be a rename of the path it replaces.
284
+ *
285
+ * **The caller never names itself.** The daemon takes the principal from the broker-authenticated
286
+ * request subject ({@link serveControl} fail-closes when the payload `from` disagrees), so there is
287
+ * no caller-supplied identity to forge.
288
+ *
289
+ * A channel outside the caller's read ACL THROWS. It must never come back as an empty page: "you
290
+ * may not read this" and "there is nothing here" are different answers and only one is safe to
291
+ * render as an empty conversation.
292
+ *
293
+ * Chat channels only — DM history is deliberately not served here (it is god-view-only today, a
294
+ * different authorization model, and one handler with two authz paths is the wrong shape on the
295
+ * surface where a mistake exposes messages). */
296
+ async readHistory(channel, opts) {
297
+ const reply = await this.deps.requestDelivery("readHistory", { channel, limit: opts?.limit });
298
+ if (!reply.ok)
299
+ throw new Error(reply.error ?? "readHistory failed");
300
+ const data = reply.data;
301
+ // Validate rather than coerce. A malformed reply must not be massaged into a plausible page:
302
+ // defaulting `complete` would invent the very signal a caller uses to decide whether it is
303
+ // looking at the start of a conversation.
304
+ if (!Array.isArray(data?.items) || typeof data?.complete !== "boolean")
305
+ throw new Error("readHistory: the delivery daemon returned a malformed page (expected { items, complete })");
306
+ return { items: data.items, complete: data.complete };
307
+ }
308
+ /** Fetch recent DMs (any sender→any recipient) from the space's DM backlog. `signal` cancels the
309
+ * active pull and reclaims its ephemeral consumer. God-view only:
310
+ * a normal agent/observer's ACL denies CONSUMER.CREATE on DM_<space>, so this throws-and-
311
+ * skips for them — only an `admin`-profile cred can read it. Returns `HistoryMessage[]`
312
+ * (#1413): every field present on a row was checked by the drain before the row was
313
+ * returned — a stored row missing `ts` / `space` / `parts` / `from.name` is dropped, never
314
+ * returned with that member silently `undefined`. */
315
+ async dmHistory(opts) {
316
+ try {
317
+ // every inst.<recipOwner>.<recipActor>.<sndOwner>.<sndActor> DM — the whole DM subtree (god-view)
318
+ return (await this.streamHistory(dmStream(this.space), [`${spacePrefix(this.space)}.inst.>`], opts?.limit ?? 100, undefined, opts?.signal)).map((r) => r.msg);
319
+ }
320
+ catch (e) {
321
+ if (isPermissionDenied(e))
322
+ return [];
323
+ throw e;
324
+ }
325
+ }
326
+ /**
327
+ * The `limit` MOST RECENT messages matching `subject`, oldest-first within the page.
328
+ *
329
+ * **This used to return the OLDEST N.** `js.consumers.get(stream, {...})` builds an ORDERED
330
+ * consumer, which defaults to `DeliverPolicy.StartSequence` with `opt_start_seq: 1` — the very
331
+ * beginning of the stream. Capping the fetch at `limit` therefore took the first N messages ever
332
+ * sent, while this method is documented as "recent" and every caller (the dashboard feed, the
333
+ * agent-facing history tools) presents the result as the latest. Confirmed live against a
334
+ * 123-message channel: `limit=10` returned the ten oldest, not the ten newest.
335
+ *
336
+ * Fixing it by draining from the start and keeping the tail would be correct and ruinous: it
337
+ * transfers the entire backlog to show one screen. Instead, find the newest matching sequence and
338
+ * consume a WINDOW ending there, widening geometrically until the window holds `limit` matches.
339
+ * A filtered subject's sequences are non-contiguous (other channels interleave in the same
340
+ * stream), so the window cannot be computed arithmetically. A FAILED attempt holds fewer than a
341
+ * page by definition, so wasted transfer stays page-sized and geometric growth keeps the number of
342
+ * attempts logarithmic. A channel with fewer than `limit` matches used to keep widening until
343
+ * sequence 1 and drain the stream's whole retained set (#840). The walk now stops at the
344
+ * subject's FIRST matching sequence (the mirror of the last-matching ceiling), probed on the
345
+ * same CREATE surface, and only after a short drain so a dense page never pays for the floor.
346
+ *
347
+ * `before` pages toward the past: pass the `seq` of the oldest message you already have.
348
+ */
349
+ async streamHistory(stream, subjects, limit, before, signal) {
350
+ if (!this.nc)
351
+ throw new Error(this.deps.notLiveMsg());
352
+ signal?.throwIfAborted();
353
+ // A LIMIT THAT IS NOT A FINITE NUMBER HAS NO ANSWER, AND THE SEARCH BELOW CANNOT REFUSE IT.
354
+ // Every comparison against NaN is false, so `limit <= 0` does not fire for one, and neither of
355
+ // the widening loop's exits can ever be true either: `page.length >= NaN` is false forever and
356
+ // `start === 1` compares against a `start` that is itself NaN. The loop does not return
357
+ // everything, it never returns. Measured through the dashboard on a real broker: no answer
358
+ // after 30s, and the abandoned read still consuming half a core fifteen seconds after its
359
+ // caller had gone, while the process kept serving every other route so nothing announced it.
360
+ // `Infinity` reaches the other end of the same hole: it passes the guard, `start` collapses to
361
+ // 1, and `slice(-Infinity)` is the subject's whole retained set.
362
+ // A caller that computed a limit it cannot state is told so, rather than handed a process that
363
+ // quietly spins. `0` and negatives keep their existing meaning, an empty page.
364
+ // A COUNT OF MESSAGES IS A WHOLE NUMBER THIS SERVER CAN COUNT EXACTLY, and the check sits ABOVE
365
+ // the zero check on purpose: `-Infinity <= 0` is true, so a guard placed below it would fold a
366
+ // limit nobody can answer into a silent empty page. `NaN` never returns (both widening exits
367
+ // compare against it and are false forever). `Infinity` and any magnitude past the safe range
368
+ // collapse `start` to 1. A fraction is the quietest of the set: the page is taken with
369
+ // `slice(-limit)` and slice truncates toward zero, so any limit in (0,1) becomes `slice(0)` and
370
+ // hands back the ENTIRE retained history. Measured on 30 retained: 0.5 and 0.9 both returned all
371
+ // 30, and 2.5 returned 2, a page nobody asked for.
372
+ if (!Number.isSafeInteger(limit))
373
+ throw new Error(`history limit must be a whole number of messages this server can count exactly, received ${limit}`);
374
+ if (limit <= 0)
375
+ return [];
376
+ const nc = this.nc;
377
+ let reader;
378
+ try {
379
+ reader = await this.acquireHistoryReader(nc, this.jsm ?? (this.jsm = await jetstreamManager(nc)), stream, signal);
380
+ // THE EXACT CEILING, on the already-granted surface. A one-shot consumer with
381
+ // `DeliverPolicy.Last` plus this subject's filter reports the newest MATCHING sequence, and its
382
+ // `num_pending` of zero means the channel is genuinely empty. Using the STREAM's last sequence
383
+ // instead (which is all `STREAM.INFO` offers) was a loose upper bound, and on a quiet channel
384
+ // in a busy stream the gap between the two is the whole problem: every window near the stream
385
+ // head is empty, so the search widened over and over before finding anything.
386
+ //
387
+ // Deliberately NOT `getMessage({ last_by_subj })`, which would be the obvious way to ask: it
388
+ // needs `$JS.API.STREAM.MSG.GET`, which read credentials do not hold. That grant hole already
389
+ // shipped once from this function and turned every non-admin history read into an empty list.
390
+ const ceiling = before !== undefined ? before - 1 : await this.lastMatchingSeq(reader, subjects, signal);
391
+ if (ceiling < 1)
392
+ return [];
393
+ // Widen from the exact ceiling until a window holds a full page, or until the window IS the
394
+ // whole subject. Draining each attempt is bounded, and that is the point: a window only fails
395
+ // when it holds FEWER than `limit` matches, so every wasted drain moves less than one page.
396
+ // Geometric growth keeps the number of attempts logarithmic, so total wasted transfer is a
397
+ // small multiple of a page.
398
+ //
399
+ // THE FIRST WINDOW IS ONE PAGE WIDE, NOT FOUR. It used to open at `limit * 4` on the reasoning
400
+ // that a filtered subject is sparse inside its stream and a wider first look would land the
401
+ // page in one drain. That is true for one channel of a busy stream and false for a subject
402
+ // that IS most of its stream, and the second case is the one a whole-backlog read takes: the
403
+ // window succeeds on the first attempt and drains four pages to keep one, because
404
+ // `drainWindow` delivers everything in the window and keeps the tail. Measured on `/api/dms`
405
+ // at limit 500 against a 2500-message backlog: 1,995,854 to 1,995,859 bytes moved across
406
+ // four runs to return a 346,001-byte page, and 8161ms to 8753ms on that link, so all four
407
+ // missed the dashboard's 8000ms deadline with nothing else on the connection (Cotal #1210).
408
+ // That cost does not keep growing with the backlog, and saying it did was wrong: the old first
409
+ // span was `max(limit * 4, 64)`, so at limit 500 it is 2000 messages, and ANY backlog of 2000
410
+ // or more drains the same 2000-message window. The point is that the window, not the backlog,
411
+ // sets the cost, and four pages to return one is already past the deadline on this link for
412
+ // every such deployment. One page wide makes the
413
+ // SUCCESSFUL drain
414
+ // obey the same bound the failed ones already promised: it moves at most one page. A sparse
415
+ // subject pays one more widening step for that, which is four round trips against a transfer
416
+ // several times the size of the answer.
417
+ //
418
+ // A SHORT PAGE is either "the channel is exhausted" or "the window is still above the
419
+ // first match". Sequence 1 is the wrong floor for the first of those: three matches at
420
+ // the high end of a busy stream are exhausted as soon as the window's lower edge passes
421
+ // the subject's first matching sequence, and walking on to 1 re-reads everyone else's
422
+ // retained set (#840). Probe that floor only after a short drain so a dense page (one
423
+ // drain, full) never pays for it. The remaining unbounded-looking case is a subject
424
+ // whose FIRST match really is near sequence 1; that span is the channel's own, not the
425
+ // stream's.
426
+ let span = Math.max(limit, 64);
427
+ let floor = 1;
428
+ let floorKnown = false;
429
+ for (;;) {
430
+ signal?.throwIfAborted();
431
+ const start = Math.max(floor, ceiling - span + 1);
432
+ const page = await this.drainWindow(reader, subjects, start, ceiling, limit, signal);
433
+ if (page.length >= limit)
434
+ return page.slice(-limit);
435
+ if (!floorKnown) {
436
+ floor = Math.max(1, await this.firstMatchingSeq(reader, subjects, signal));
437
+ floorKnown = true;
438
+ }
439
+ if (start <= floor)
440
+ return page.slice(-limit);
441
+ span *= 4;
442
+ }
443
+ }
444
+ catch (e) {
445
+ // NARROW. This catch is how the MSG.GET grant bug shipped: it turned a Permissions Violation
446
+ // into an empty history, so every non-admin read looked exactly like a quiet channel, and the
447
+ // smokes stayed green because they run as admin against a local broker. Emitting on the error
448
+ // event is not enough either — callers consume the RETURN VALUE, and the dashboard renders
449
+ // empty regardless of what an operator log says.
450
+ //
451
+ // So only one thing may still produce an empty result here: the stream does not exist (a space
452
+ // with no history yet). Anything else — a denial, a timeout, a 503, a protocol or
453
+ // consumer-create failure — is raised, because "no history" and "I could not read the history"
454
+ // are different answers and only one of them is safe to render as an empty conversation.
455
+ // `dmHistory` alone turns a denial into its documented empty god-view result.
456
+ const msg = String(e?.message ?? "");
457
+ if (/stream not found/i.test(msg) || e?.code === 404)
458
+ return [];
459
+ throw e;
460
+ }
461
+ finally {
462
+ if (reader)
463
+ this.releaseHistoryReader(reader);
464
+ }
465
+ }
466
+ /** This connection's history-reader id, the key of its credential's reader deletes
467
+ * ({@link historyReaderConsumer}). A static credential's is its connId, the nkey it signs with.
468
+ * Under the auth callout the connId is the inbox nonce this client chose, so the callout keys the
469
+ * deletes on {@link calloutReaderId} instead: the server's id and the client id it assigned this
470
+ * connection, which the client reads from the server's INFO and does not choose. */
471
+ historyReaderId(nc) {
472
+ if (!this.userMode)
473
+ return this.connId;
474
+ const info = nc.info;
475
+ if (!info)
476
+ throw new Error("history: the server has not sent its INFO, so this connection has no history reader id yet");
477
+ return calloutReaderId(info.server_id, info.client_id);
478
+ }
479
+ /** Take one of this connection's history-reader names on `stream` ({@link historyReaderConsumer})
480
+ * for one read. The read holds the name for its whole walk and creates and deletes a consumer
481
+ * under it at each step, so this connection keeps at most {@link HISTORY_READERS} reader consumers
482
+ * on a stream (#4123). A read past that many waits for a name, and `signal` ends the wait. A
483
+ * reconnect under the auth callout changes the reader id, and reads from then on take the new
484
+ * id's names. */
485
+ async acquireHistoryReader(nc, jsm, stream, signal) {
486
+ for (;;) {
487
+ signal?.throwIfAborted();
488
+ const readerId = this.historyReaderId(nc);
489
+ let pool = this.historyReaderSlots.get(stream);
490
+ if (pool?.readerId !== readerId) {
491
+ pool = { readerId, free: Array.from({ length: HISTORY_READERS }, (_, i) => HISTORY_READERS - 1 - i), held: 0, waiting: [], refusedUntil: 0 };
492
+ this.historyReaderSlots.set(stream, pool);
493
+ }
494
+ // A read here would leave one more reader it may not delete, so it fails before creating one.
495
+ if (pool.refusedUntil > Date.now())
496
+ throw this.readerDeleteRefused(stream);
497
+ const slot = pool.free.pop();
498
+ if (slot !== undefined) {
499
+ pool.held++;
500
+ return { nc, js: jetstream(nc), jsm, stream, pool, slot, name: historyReaderConsumer(readerId, slot), held: true, left: false };
501
+ }
502
+ // No read here holds a name, so none will come back from one: every name is set aside (see
503
+ // openHistoryReader and closeHistoryReader). Waiting would hang until those expire.
504
+ if (pool.held === 0)
505
+ throw new Error(`history: every history reader name this connection has on ${stream} is set aside, held by a consumer it did not create (another process using the same credential, or one that stopped mid-read) or by a reader it could not confirm deleted; they expire ${HISTORY_READER_INACTIVE_MS / 60_000} minutes after their last use`);
506
+ const waitOn = pool;
507
+ await new Promise((resolve, reject) => {
508
+ const wake = () => { signal?.removeEventListener("abort", stop); resolve(); };
509
+ const stop = () => { waitOn.waiting.splice(waitOn.waiting.indexOf(wake), 1); reject(abortReason(signal)); };
510
+ waitOn.waiting.push(wake);
511
+ signal?.addEventListener("abort", stop, { once: true });
512
+ });
513
+ }
514
+ }
515
+ /** Give a read's history-reader name back and wake one read waiting for a name. A name whose
516
+ * delete failed is set aside instead. */
517
+ releaseHistoryReader(reader) {
518
+ if (!reader.held)
519
+ return;
520
+ reader.held = false;
521
+ const pool = reader.pool;
522
+ pool.held--;
523
+ if (!reader.left) {
524
+ pool.free.push(reader.slot);
525
+ pool.waiting.shift()?.();
526
+ return;
527
+ }
528
+ this.setAsideHistoryReader(pool, reader.slot);
529
+ // Every waiter checks again, so one that no running read can now serve fails instead of hanging.
530
+ if (pool.held === 0)
531
+ for (const wake of pool.waiting.splice(0))
532
+ wake();
533
+ }
534
+ /** Keep `slot` out of use until a consumer under it would have expired, then free it. */
535
+ setAsideHistoryReader(pool, slot) {
536
+ setTimeout(() => { pool.free.push(slot); pool.waiting.shift()?.(); }, HISTORY_READER_INACTIVE_MS).unref();
537
+ }
538
+ /** Create the reader consumer for one step of a read, under the read's name. It is a plain pull
539
+ * consumer: an nats.js ordered consumer renames itself on every rebuild, and the observer and admin
540
+ * credentials may delete only these exact names.
541
+ *
542
+ * Every create carries a fresh description. NATS answers a create whose config equals the existing
543
+ * consumer's with that consumer, delivery state and all (measured on nats-server 2.15), and a read
544
+ * repeats the same config on the same name. Without the description a reader left under the name
545
+ * would come back as if new: a `DeliverPolicy.Last` reader that already delivered its message
546
+ * reports nothing pending, which reads as an empty channel. With it, a create on a name in use is
547
+ * refused, and a consumer that does not carry this step's description is never used.
548
+ *
549
+ * A consumer already under the name is never deleted, whoever left it: another holder of this
550
+ * credential, a process that stopped mid-read, or this endpoint when a delete's answer was lost and
551
+ * the name was taken again since. The read moves to a free name, and the taken one stays out of use
552
+ * until such a consumer would have expired. */
553
+ async openHistoryReader(reader, config) {
554
+ // A single filter must ride the filter-bearing API subject so scoped read grants apply.
555
+ if (config.filter_subjects?.length === 1) {
556
+ const { filter_subjects, ...rest } = config;
557
+ config = { ...rest, filter_subject: filter_subjects[0] };
558
+ }
559
+ const pool = reader.pool;
560
+ for (;;) {
561
+ // A reconnect under the auth callout moved this connection to new reader names, and its
562
+ // credential may no longer delete this one. Creating under it would leave the reader behind.
563
+ if (this.historyReaderId(reader.nc) !== pool.readerId)
564
+ throw new Error(`history: the connection was re-established during the read on ${reader.stream}, so its history reader names changed; the read is not served`);
565
+ const description = `cotal history read ${randomUUID()}`;
566
+ let info;
567
+ try {
568
+ info = await reader.jsm.consumers.add(reader.stream, {
569
+ ...config,
570
+ name: reader.name,
571
+ description,
572
+ ack_policy: AckPolicy.None,
573
+ max_deliver: 1,
574
+ mem_storage: true,
575
+ num_replicas: 1,
576
+ inactive_threshold: nanos(HISTORY_READER_INACTIVE_MS),
577
+ });
578
+ }
579
+ catch (e) {
580
+ if (!isConsumerAlreadyExists(e))
581
+ throw e;
582
+ }
583
+ if (info?.config.description === description)
584
+ return reader.js.consumers.getConsumerFromInfo(info);
585
+ this.setAsideHistoryReader(pool, reader.slot);
586
+ const next = pool.free.pop();
587
+ if (next === undefined) {
588
+ // The read ends holding no name. Every waiter checks again, so one that no running read can
589
+ // now serve fails instead of hanging.
590
+ reader.held = false;
591
+ pool.held--;
592
+ for (const wake of pool.waiting.splice(0))
593
+ wake();
594
+ throw new Error(`history: reader ${reader.name} on ${reader.stream} is held by a consumer this read did not create, and no other reader name is free`);
595
+ }
596
+ reader.slot = next;
597
+ reader.name = historyReaderConsumer(pool.readerId, next);
598
+ }
599
+ }
600
+ /** Delete the read's reader consumer; already gone is the same outcome. A failed delete may still
601
+ * have run with its answer lost, and the name may be taken again before this endpoint could tell,
602
+ * so the name is set aside when the read gives it back rather than deleted again later. A refused
603
+ * delete means the credential was minted before the observer and admin profiles held their reader
604
+ * deletes. Each read would then leave a reader for the inactive threshold, which is how a polling
605
+ * dashboard filled the stream's consumer limit (#4123), so the read fails and says to remint
606
+ * rather than leak quietly, and reads on the stream fail at once until that reader expires. */
607
+ async closeHistoryReader(reader) {
608
+ try {
609
+ await reader.jsm.consumers.delete(reader.stream, reader.name);
610
+ }
611
+ catch (e) {
612
+ if (isConsumerNotFound(e))
613
+ return;
614
+ reader.left = true;
615
+ // No `cause`: a permission-shaped cause would let streamHistory read this as the admin-only
616
+ // DM denial and return an empty page.
617
+ if (this.deps.isPublishPermissionDenied(e)) {
618
+ if (this.historyReaderId(reader.nc) !== reader.pool.readerId)
619
+ throw new Error(`history: the connection was re-established during the read on ${reader.stream}, so it may no longer delete its reader ${reader.name}, which expires on its own; the read is not served`);
620
+ reader.pool.refusedUntil = Date.now() + HISTORY_READER_INACTIVE_MS;
621
+ throw this.readerDeleteRefused(reader.stream);
622
+ }
623
+ throw e;
624
+ }
625
+ }
626
+ readerDeleteRefused(stream) {
627
+ return new Error(`history: this credential may not delete its own history readers on ${stream}; it predates the observer and admin reader-delete grant, so remint it`);
628
+ }
629
+ /** The newest stream sequence matching `subject`, or 0 when the subject has no messages.
630
+ *
631
+ * One reader consumer at `DeliverPolicy.Last` with this subject's filter: its `num_pending`
632
+ * (available from the create, before anything is delivered) is 0 for an empty subject, and
633
+ * otherwise one message carries the sequence. Same CREATE/INFO/NEXT/DELETE surface `drainWindow`
634
+ * already uses, so no broker authority is added. */
635
+ async lastMatchingSeq(reader, subjects, signal) {
636
+ signal?.throwIfAborted();
637
+ const consumer = await this.openHistoryReader(reader, {
638
+ filter_subjects: subjects,
639
+ deliver_policy: DeliverPolicy.Last,
640
+ });
641
+ try {
642
+ // Bind-time zero is the ONLY thing that means "this subject has no messages".
643
+ if ((await consumer.info(true)).num_pending === 0)
644
+ return 0;
645
+ signal?.throwIfAborted();
646
+ const iter = await consumer.fetch({ max_messages: 1 });
647
+ const stop = () => iter.stop(abortReason(signal));
648
+ signal?.addEventListener("abort", stop, { once: true });
649
+ try {
650
+ signal?.throwIfAborted();
651
+ for await (const m of iter)
652
+ return m.seq;
653
+ }
654
+ finally {
655
+ signal?.removeEventListener("abort", stop);
656
+ iter.stop();
657
+ }
658
+ // Bind said a message was pending and none arrived. The pinned client's pull iterator ends
659
+ // CLEANLY when the connection closes ("we don't propagate the error here"), so this is what a
660
+ // dropped link looks like from here. Returning 0 would make the caller report an empty
661
+ // channel, which is the same "could not read means no history" lie the narrowed catch above
662
+ // exists to stop.
663
+ throw new Error(`history: the broker reported messages on ${subjectLabel(subjects)} but delivered none - the read was cut short, not empty`);
664
+ }
665
+ finally {
666
+ await this.closeHistoryReader(reader);
667
+ }
668
+ }
669
+ /** The oldest stream sequence matching `subject`, or 0 when the subject has no messages.
670
+ * Mirror of {@link lastMatchingSeq}: same CREATE/INFO/NEXT/DELETE surface, `DeliverPolicy.All`
671
+ * instead of `Last`, first delivered seq instead of last. Read credentials already hold this. */
672
+ async firstMatchingSeq(reader, subjects, signal) {
673
+ signal?.throwIfAborted();
674
+ const consumer = await this.openHistoryReader(reader, {
675
+ filter_subjects: subjects,
676
+ deliver_policy: DeliverPolicy.All,
677
+ });
678
+ try {
679
+ if ((await consumer.info(true)).num_pending === 0)
680
+ return 0;
681
+ signal?.throwIfAborted();
682
+ const iter = await consumer.fetch({ max_messages: 1 });
683
+ const stop = () => iter.stop(abortReason(signal));
684
+ signal?.addEventListener("abort", stop, { once: true });
685
+ try {
686
+ signal?.throwIfAborted();
687
+ for await (const m of iter)
688
+ return m.seq;
689
+ }
690
+ finally {
691
+ signal?.removeEventListener("abort", stop);
692
+ iter.stop();
693
+ }
694
+ throw new Error(`history: the broker reported messages on ${subjectLabel(subjects)} but delivered none - the read was cut short, not empty`);
695
+ }
696
+ finally {
697
+ await this.closeHistoryReader(reader);
698
+ }
699
+ }
700
+ /** Drain every message matching `subject` with sequence in `[start, ceiling]`, oldest-first.
701
+ * One reader consumer, one batched pull — `AckPolicy.None`, so no per-message ack
702
+ * round trip. Fetches exactly the pending count so it returns as soon as the window is
703
+ * delivered rather than blocking for the pull's full expiry. */
704
+ async drainWindow(reader, subjects, start, ceiling, limit, signal) {
705
+ signal?.throwIfAborted();
706
+ const out = [];
707
+ const consumer = await this.openHistoryReader(reader, {
708
+ filter_subjects: subjects,
709
+ deliver_policy: DeliverPolicy.StartSequence,
710
+ opt_start_seq: start,
711
+ });
712
+ try {
713
+ // A freshly created consumer already carries its ConsumerInfo, so read the CACHED copy: the
714
+ // explicit uncached `info()` this used to call was a round trip for data we already had.
715
+ const pending = (await consumer.info(true)).num_pending;
716
+ if (pending === 0)
717
+ return out;
718
+ signal?.throwIfAborted();
719
+ // Keep only a small rolling buffer in flight. Stopping a client iterator cannot unsend bytes the
720
+ // broker already committed to that pull request, so fetching the whole page let an aborted history
721
+ // read keep filling a constrained shared connection and starve the next dashboard poll. `consume`
722
+ // replenishes this bounded buffer as it is read, so large pages still complete without committing
723
+ // all of their bytes to the connection up front.
724
+ const iter = await consumer.consume({ max_messages: Math.min(pending, 32) });
725
+ const stop = () => iter.stop(abortReason(signal));
726
+ signal?.addEventListener("abort", stop, { once: true });
727
+ // PROVE THE WINDOW COMPLETED. The pull iterator ends cleanly on a dropped connection, so a
728
+ // close after three of ten deliveries would otherwise return a convincing three-message page.
729
+ // The window is done when we have reached its upper bound or consumed everything bind said
730
+ // was pending; anything else is a cut-short read and must say so.
731
+ let delivered = 0;
732
+ let complete = false;
733
+ try {
734
+ signal?.throwIfAborted();
735
+ for await (const m of iter) {
736
+ delivered++;
737
+ // A plain consumer does not rebuild itself the way an ordered one did, so a gap in its
738
+ // delivery sequence is a message this page would silently lack.
739
+ if (m.info.deliverySequence !== delivered)
740
+ throw new Error(`history: delivery ${m.info.deliverySequence} arrived where ${delivered} was due on ${subjectLabel(subjects)} - the window has a gap, so the page is not served`);
741
+ if (m.seq >= ceiling) { // reached the page's upper bound
742
+ if (m.seq === ceiling) {
743
+ const msg = this.deps.decodeHistory(m);
744
+ if (msg)
745
+ out.push({ seq: m.seq, subject: m.subject, msg });
746
+ }
747
+ complete = true;
748
+ break;
749
+ }
750
+ const msg = this.deps.decodeHistory(m);
751
+ if (msg) {
752
+ out.push({ seq: m.seq, subject: m.subject, msg });
753
+ if (out.length > limit)
754
+ out.shift();
755
+ }
756
+ if (delivered >= pending) {
757
+ complete = true;
758
+ break;
759
+ }
760
+ }
761
+ }
762
+ finally {
763
+ signal?.removeEventListener("abort", stop);
764
+ iter.stop();
765
+ }
766
+ if (!complete)
767
+ throw new Error(`history: read ${delivered} of ${pending} messages on ${subjectLabel(subjects)} before the stream ended early - the window was cut short, not empty`);
768
+ return out;
769
+ }
770
+ finally {
771
+ // DELETE THE READER. Left alone it would stay for its inactive threshold, and the widening
772
+ // search can run several steps per call while a polling dashboard repeats every call on each
773
+ // poll. The observer and admin profiles used to hold no delete at all (#691), so a dashboard
774
+ // polling every ten seconds filled the stream's consumer limit and every later read failed
775
+ // (#4123). Each reader now goes when its step ends.
776
+ await this.closeHistoryReader(reader);
777
+ }
778
+ }
779
+ /**
780
+ * Read retained chat history on ONE channel subject through a name-scoped, single-filter
781
+ * EPHEMERAL pull consumer — the broker-contained replacement for the removed Direct Get. The
782
+ * create rides `$JS.API.CONSUMER.CREATE.<CHAT>.<chathist_id>.<subject>`, whose trailing filter
783
+ * token nats-server pins to the request body (JSConsumerCreateFilterSubjectMismatchErr, code
784
+ * 10131) — so an agent can only ever replay a channel its `allowSubscribe` grants. Single filter
785
+ * only (plural isn't ACL-constrainable); `AckPolicy.None` + `mem_storage` so it leaves no durable
786
+ * state, and it is deleted right after. Returns raw messages in stream order from `start`,
787
+ * stopping once past `untilSeq` (exclusive of it) or after `limit`. The per-instance name means
788
+ * calls must be serial — every reader here awaits to completion, so they are.
789
+ */
790
+ async collectHistory(subject, start, opts = {}) {
791
+ // Serialize on the per-instance lock: the fixed `chathist_<id>` name means two concurrent reads
792
+ // (recall + join-backfill + drop-marker can race in-process) would delete/recreate the consumer
793
+ // under each other and cross-feed results. The chain makes the "serial callers" assumption true.
794
+ const run = this.histLock.then(() => this.collectHistoryInner(subject, start, opts));
795
+ this.histLock = run.catch(() => { }); // keep the chain alive on error
796
+ return run;
797
+ }
798
+ async collectHistoryInner(subject, start, opts = {}) {
799
+ if (!this.jsm || !this.js)
800
+ throw new Error(this.deps.notLiveMsg());
801
+ const stream = chatStream(this.space);
802
+ const name = chatHistDurable(this.owner, this.actor, this.deps.requireLifecycleUid("chat history reads"));
803
+ const out = [];
804
+ // Clear any consumer leaked by a crashed prior read before re-creating it with THIS read's
805
+ // single filter (the read ACL is enforced at create — see the doc above).
806
+ await this.deps.deleteConsumerIfPresent(stream, name);
807
+ await this.jsm.consumers.add(stream, {
808
+ name,
809
+ filter_subject: subject,
810
+ ack_policy: AckPolicy.None,
811
+ mem_storage: true,
812
+ inactive_threshold: nanos(30_000),
813
+ ...("time" in start
814
+ ? { deliver_policy: DeliverPolicy.StartTime, opt_start_time: start.time.toISOString() }
815
+ : { deliver_policy: DeliverPolicy.StartSequence, opt_start_seq: start.seq }),
816
+ });
817
+ try {
818
+ const consumer = await this.js.consumers.get(stream, name);
819
+ let pending = (await consumer.info()).num_pending;
820
+ while (pending > 0) {
821
+ const want = Math.min(pending, 256);
822
+ const iter = await consumer.fetch({ max_messages: want, expires: 5_000 });
823
+ let got = 0;
824
+ for await (const m of iter) {
825
+ got++;
826
+ if (opts.untilSeq !== undefined && m.seq > opts.untilSeq)
827
+ return out; // crossed the frontier
828
+ // Belt-and-suspenders over the lock: only keep messages on the requested channel subject
829
+ // (the consumer's filter already bounds this; guards against any stale-consumer edge).
830
+ if (!subjectMatches(subject, m.subject))
831
+ continue;
832
+ out.push(m);
833
+ if (opts.limit !== undefined && out.length >= opts.limit)
834
+ return out;
835
+ }
836
+ if (got < want)
837
+ break; // drained early
838
+ pending -= got;
839
+ }
840
+ }
841
+ finally {
842
+ await this.deps.deleteConsumerIfPresent(stream, name);
843
+ }
844
+ return out;
845
+ }
846
+ /** Read a channel's retained history up to `upToSeq` (the join frontier) and emit each message
847
+ * as a `historical` "message" event. `sinceMs` bounds how far back via a native consumer
848
+ * `start_time` (now − window); unset ⇒ the full retained window. `floorSeq`, when set, is a
849
+ * tighter lower bound than the window: this incarnation had already consumed everything up to
850
+ * and including it before a preservation cut, so the read starts at `floorSeq + 1` and the
851
+ * `sinceMs` window is not consulted (the floor is the tighter bound by construction — the seat
852
+ * was live for the window's tail). `floorSeq >= upToSeq` means there is nothing new to read at
853
+ * all; return 0 without creating a consumer. A floor below the stream's oldest retained sequence
854
+ * is fine: JetStream's `DeliverPolicy.StartSequence` begins at the first retained message at or
855
+ * after it, which is exactly the catch-up. New messages (`seq > upToSeq`) are skipped — the live
856
+ * tail owns them. Reads through the contained {@link collectHistory}. */
857
+ async backfillChannel(channel, upToSeq, sinceMs, floorSeq) {
858
+ if (floorSeq !== undefined && floorSeq >= upToSeq)
859
+ return 0;
860
+ const subject = chatSubject(this.space, "*", "*", channel);
861
+ // A window that reaches back before 1970 covers the whole retained window (#7323). Its start time
862
+ // would be a date JetStream does not read, or not a valid date at all, and the read replayed nothing.
863
+ const since = sinceMs === undefined ? undefined : Date.now() - sinceMs;
864
+ const start = floorSeq !== undefined ? { seq: floorSeq + 1 } : since === undefined || !(since > 0) ? { seq: 1 } : { time: new Date(since) };
865
+ let msgs;
866
+ try {
867
+ msgs = await this.collectHistory(subject, start, { untilSeq: upToSeq });
868
+ }
869
+ catch (e) {
870
+ this.deps.emit("error", e);
871
+ if (isPermissionDenied(e))
872
+ throw e;
873
+ return 0;
874
+ }
875
+ const noop = { ack: () => { }, nak: () => { }, durable: false };
876
+ let n = 0;
877
+ for (const sm of msgs) {
878
+ let msg;
879
+ try {
880
+ msg = sm.json();
881
+ }
882
+ catch {
883
+ continue; // skip undecodable
884
+ }
885
+ // Same authenticity guard as the tail; skip our own echoes in history.
886
+ if (!this.deps.isRecord(msg) || !this.deps.isUsableMessageId(msg.id))
887
+ continue; // malformed envelope (SPEC sec 5) — history skips
888
+ const parsed = parseSubject(sm.subject);
889
+ if (!parsed || !this.deps.isFromSubjectSender(msg, parsed) || msg.from.id === this.card.id)
890
+ continue;
891
+ // Backfill only ever reads the chat stream, so the authenticated class is always "channel".
892
+ this.deps.emit("message", this.deps.authenticatedMessage(msg, parsed), noop, { historical: true, kind: "channel" });
893
+ n++;
894
+ }
895
+ return n;
896
+ }
897
+ /**
898
+ * Replay-gated pull of a channel's retained ambient from `sinceSeq` (exclusive) forward — the
899
+ * focus-recall read behind `cotal_inbox`. Returns the messages (NOT emitted — this is a pull,
900
+ * not a push into context) plus `dropped: true` when the window may not be complete: the stream's
901
+ * limits may have removed posts after the watermark ({@link chatMayHaveLost}: a sender at the
902
+ * per-sender limit, or the stream's oldest post already past the watermark), or replay is off
903
+ * for the channel below. Either way the caller must say so rather than silently reporting an
904
+ * empty, complete window. `seqs[i]` is the chat
905
+ * stream sequence of `messages[i]`, the one identity two identical messages do not share.
906
+ * `unanswered` is true when no history read answered (replay is off, or the read failed), so
907
+ * `messages` says nothing about what the channel retains.
908
+ *
909
+ * Honors the **same** per-channel replay gate as join-backfill ({@link joinPolicyFresh}): a
910
+ * `replay=off` channel returns no messages, so `focus` can't become a history bypass for a
911
+ * channel that denies replay to everyone else (the read ACL bounds *which* channels recall can
912
+ * touch; this app gate bounds *whether* a permitted channel replays). Ingest still ack-drops
913
+ * focus-mode ambient/mentions on this channel on the promise that they stay recallable (#977) —
914
+ * the gate means that promise cannot be kept, so it reports `dropped: true` rather than pretend
915
+ * the window was empty and complete.
916
+ */
917
+ async recallChannel(channel, sinceSeq) {
918
+ if (!this.jsm)
919
+ throw new Error(this.deps.notLiveMsg());
920
+ if (!isConcreteChannel(channel))
921
+ return { messages: [], seqs: [], dropped: false, unanswered: true };
922
+ const policy = await this.deps.joinPolicyFresh(channel);
923
+ if (!policy.replay)
924
+ return { messages: [], seqs: [], dropped: true, unanswered: true };
925
+ const subject = chatSubject(this.space, "*", "*", channel);
926
+ let raw;
927
+ try {
928
+ raw = await this.collectHistory(subject, { seq: sinceSeq + 1 });
929
+ }
930
+ catch (e) {
931
+ this.deps.emit("error", e);
932
+ if (isPermissionDenied(e))
933
+ throw e;
934
+ return { messages: [], seqs: [], dropped: true, unanswered: true };
935
+ }
936
+ const collected = [];
937
+ const seqs = [];
938
+ for (const sm of raw) {
939
+ let msg;
940
+ try {
941
+ msg = sm.json();
942
+ }
943
+ catch {
944
+ continue; // skip undecodable
945
+ }
946
+ // Same authenticity guard as the tail/backfill; skip our own echoes.
947
+ if (!this.deps.isRecord(msg) || !this.deps.isUsableMessageId(msg.id))
948
+ continue; // malformed envelope (SPEC sec 5) — recall skips
949
+ const parsed = parseSubject(sm.subject);
950
+ if (!parsed || !this.deps.isFromSubjectSender(msg, parsed) || msg.from.id === this.card.id)
951
+ continue;
952
+ collected.push(this.deps.authenticatedMessage(msg, parsed));
953
+ seqs.push(sm.seq);
954
+ }
955
+ let dropped;
956
+ try {
957
+ dropped = await this.deps.chatMayHaveLost(subject, sinceSeq);
958
+ }
959
+ catch (e) {
960
+ // Completeness could not be read, so the read is reported as unanswered: nothing settles on it.
961
+ this.deps.emit("error", e);
962
+ if (isPermissionDenied(e))
963
+ throw e;
964
+ return { messages: [], seqs: [], dropped: true, unanswered: true };
965
+ }
966
+ return { messages: collected, seqs, dropped, unanswered: false };
967
+ }
968
+ }
969
+ //# sourceMappingURL=endpoint-history.js.map