@pod-network/trade-sdk 0.4.0 → 0.4.1

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/src/datafeed.ts CHANGED
@@ -5,6 +5,7 @@
5
5
  import type { PodTradeClient } from "./client.js";
6
6
  import type { Bar, MarketId, Resolution } from "./types/public.js";
7
7
  import { toNumber } from "./codec/units.js";
8
+ import { RESOLUTION_SECONDS } from "./codec/resolution.js";
8
9
 
9
10
  const TV_TO_RESOLUTION: Record<string, Resolution> = {
10
11
  "1": "1m", "5": "5m", "15": "15m", "30": "30m",
@@ -56,15 +57,20 @@ export function createPodDatafeed(client: PodTradeClient): unknown {
56
57
  try {
57
58
  const id = (symbolInfo.ticker ?? symbolInfo.name) as MarketId;
58
59
  const res = TV_TO_RESOLUTION[resolution] ?? "1h";
59
- const series = client.candles(id, res, {
60
- from: periodParams.from * 1000,
61
- to: periodParams.to * 1000,
62
- });
63
- const bars = await series.ready();
64
- const inRange = bars
65
- .filter((b) => b.time >= periodParams.from * 1000 && b.time < periodParams.to * 1000)
66
- .map((b) => toTvBar(b));
67
- onResult(inRange, { noData: inRange.length === 0 });
60
+ // One-shot read, never the memoised series — see client.candleHistory.
61
+ const range = { from: periodParams.from * 1000, to: periodParams.to * 1000 };
62
+ let bars = await client.candleHistory(id, res, range);
63
+ // Nothing closed in a window that reaches into the forming bucket: that
64
+ // bucket is all this market has, and `noData` would make TV stop asking
65
+ // for it. Tested against the bucket, not `Date.now()`: TV rounds `to` to
66
+ // whole seconds, so a window covering the open bucket can still end a
67
+ // few hundred ms in the past.
68
+ const bucketMs = RESOLUTION_SECONDS[res] * 1000;
69
+ if (!bars.length && range.to > Math.floor(Date.now() / bucketMs) * bucketMs) {
70
+ bars = await client.candleTail(id, res, range);
71
+ }
72
+ const tv = bars.map((b) => toTvBar(b));
73
+ onResult(tv, { noData: tv.length === 0 });
68
74
  } catch (e) {
69
75
  onError(String(e));
70
76
  }
@@ -5,6 +5,13 @@
5
5
  export interface Resource<T> {
6
6
  get(): T | undefined;
7
7
  subscribe(listener: () => void): () => void;
8
+ /**
9
+ * Resolves on the FIRST value the source commits — which for a resource that
10
+ * seeds progressively is the initial, possibly empty, seed and not "fully
11
+ * loaded". Do not use it to decide that a window has finished loading (that
12
+ * mistake drew empty charts); for a bounded read that must be complete, use a
13
+ * one-shot call such as `client.candleHistory`.
14
+ */
8
15
  ready(): Promise<T>;
9
16
  /** Restart the source for a fresh seed (optional — see BaseResource). */
10
17
  refresh?(): void;
@@ -62,7 +69,13 @@ export class BaseResource<T> implements Resource<T> {
62
69
  return this.readyPromise;
63
70
  }
64
71
 
65
- /** Force teardown (used by the client on close). */
72
+ /**
73
+ * Force teardown, ignoring the subscriber count — for `client.close()`, not
74
+ * for one consumer that is done with a shared resource. Resources are
75
+ * memoised per key, so destroying one another consumer still holds stops its
76
+ * source underneath it; releasing your `subscribe()` teardown is enough,
77
+ * since the last one out stops the source anyway.
78
+ */
66
79
  destroy(): void {
67
80
  this.stop();
68
81
  }
@@ -17,11 +17,13 @@ import { dec, usToMs, WAD } from "../codec/units.js";
17
17
  import { RESOLUTION_PAGE_BUCKETS, RESOLUTION_SECONDS } from "../codec/resolution.js";
18
18
  import { BaseResource, type ResourceHandle } from "../stores/resource.js";
19
19
  import type { Subscription } from "../transport/ws.js";
20
+ import { PodHttpError, type PodRestClient } from "../transport/rest.js";
20
21
  import type { SyncContext } from "./sources.js";
21
22
 
22
23
  export interface SeriesResource<Item> {
23
24
  get(): Item[] | undefined;
24
25
  subscribe(listener: () => void): () => void;
26
+ /** First committed value, not "window loaded" — see `Resource.ready`. */
25
27
  ready(): Promise<Item[]>;
26
28
  readonly error?: Error;
27
29
  setWindow(range: TimeRange): void;
@@ -40,6 +42,271 @@ const bmin = (a: bigint, b: bigint) => (a < b ? a : b);
40
42
  const REPLAY_SAFE_SECS = 3_600;
41
43
  const SEED_RESOLUTION: Resolution = "1h";
42
44
 
45
+ /** One canonical page window: an epoch-anchored span of `RESOLUTION_PAGE_BUCKETS`
46
+ * buckets, identified by its page index. */
47
+ export interface CandlePageWindow { page: number; fromMs: number; toMs: number }
48
+
49
+ /**
50
+ * One page's bars, plus how far the indexer had actually got. `watermarkMs` is
51
+ * `MAX_SAFE_INTEGER` when the page is known complete (a settled cache hit), so
52
+ * it never bounds a read it has nothing to say about.
53
+ */
54
+ interface CandlePage { bars: Bar[]; watermarkMs: number }
55
+
56
+ const pageSpanMs = (resolution: Resolution) =>
57
+ RESOLUTION_PAGE_BUCKETS[resolution] * RESOLUTION_SECONDS[resolution] * 1000;
58
+
59
+ /**
60
+ * Page index of `ms` on a resolution's epoch-anchored grid — the single
61
+ * definition of that grid. Every candle read goes through it on purpose: the
62
+ * server's `immutable` responses and the REST client's URL-keyed in-flight
63
+ * dedupe both only pay off while every request lands on the same boundaries, so
64
+ * a second implementation of this arithmetic would silently turn cache hits
65
+ * into node traffic.
66
+ */
67
+ export function candlePageAt(resolution: Resolution, ms: number): number {
68
+ return Math.floor(Math.max(0, ms) / pageSpanMs(resolution));
69
+ }
70
+
71
+ /**
72
+ * One page's canonical window — `undefined` when the page holds nothing but the
73
+ * forming bucket, because there is nothing closed to fetch. The window is
74
+ * clamped to the last closed bucket so it stays fully elapsed: those are the
75
+ * responses the server marks `immutable`, while a `to` in the future is
76
+ * `no-store` on every open.
77
+ */
78
+ export function candlePageWindow(
79
+ resolution: Resolution,
80
+ page: number,
81
+ nowMs = Date.now(),
82
+ ): CandlePageWindow | undefined {
83
+ const stepMs = RESOLUTION_SECONDS[resolution] * 1000;
84
+ const fromMs = page * pageSpanMs(resolution);
85
+ const toMs = Math.min(fromMs + pageSpanMs(resolution), Math.floor(nowMs / stepMs) * stepMs);
86
+ return toMs > fromMs ? { page, fromMs, toMs } : undefined;
87
+ }
88
+
89
+ /** The canonical windows covering `[fromMs, toMs)`, oldest first. */
90
+ export function candlePageWindows(
91
+ resolution: Resolution,
92
+ fromMs: number,
93
+ toMs: number,
94
+ nowMs = Date.now(),
95
+ ): CandlePageWindow[] {
96
+ const windows: CandlePageWindow[] = [];
97
+ const last = candlePageAt(resolution, toMs - 1);
98
+ for (let page = candlePageAt(resolution, fromMs); page <= last; page++) {
99
+ const window = candlePageWindow(resolution, page, nowMs);
100
+ if (window) windows.push(window);
101
+ }
102
+ return windows;
103
+ }
104
+
105
+ /**
106
+ * The live series' bars inside `range`, waiting up to `timeoutMs` for one to
107
+ * turn up. The series folds the tick stream, so this is where the forming
108
+ * bucket comes from — REST withholds it.
109
+ *
110
+ * Deliberately not `ready()`: that resolves on the series' FIRST commit, and a
111
+ * fresh series commits an empty seed while its load is still in flight (see
112
+ * `fetchPages`, which surfaces loading state before any page lands). Awaiting
113
+ * it hands back `[]` and gives up before the bucket it was called for arrives.
114
+ */
115
+ export function candleTailFrom(
116
+ series: SeriesResource<Bar>,
117
+ range: TimeRange,
118
+ timeoutMs: number,
119
+ ): Promise<Bar[]> {
120
+ const toMs = range.to ?? Number.MAX_SAFE_INTEGER;
121
+ const inWindow = () => (series.get() ?? []).filter((b) => b.time >= range.from && b.time < toMs);
122
+ const found = inWindow();
123
+ if (found.length) return Promise.resolve(found);
124
+ return new Promise((resolve) => {
125
+ let release: (() => void) | undefined;
126
+ let timer: ReturnType<typeof setTimeout> | undefined;
127
+ let settled = false;
128
+ const settle = (bars: Bar[]) => {
129
+ if (settled) return;
130
+ settled = true;
131
+ clearTimeout(timer);
132
+ release?.();
133
+ resolve(bars);
134
+ };
135
+ timer = setTimeout(() => settle(inWindow()), timeoutMs);
136
+ release = series.subscribe(() => {
137
+ const bars = inWindow();
138
+ if (bars.length) settle(bars);
139
+ });
140
+ // `subscribe` starts the source, which can emit synchronously inside the
141
+ // call above — before `release` was assigned. Release here or the listener
142
+ // (and with it the series' tick fold) is never let go.
143
+ if (settled) release();
144
+ });
145
+ }
146
+
147
+ /**
148
+ * Decoded pages, per REST client — so per host, never shared between clients
149
+ * pointed at different environments. A page is only stored once it can never
150
+ * change again, which takes BOTH of: a full span (not the trailing page, which
151
+ * still grows as buckets close) and an indexer watermark past the window's end.
152
+ * Wall clock is not enough — the server gates its own `immutable` header on
153
+ * solution time, and a window that has elapsed by the clock while the indexer
154
+ * lags comes back SHORT of its newest buckets. Caching that would pin a hole
155
+ * for the process's lifetime, which is the failure this whole read exists to
156
+ * avoid.
157
+ *
158
+ * Without this, overlapping requests re-decode the same bars, and overlap is
159
+ * the norm: a chart's opening window reaches further back than it has been
160
+ * served, and every pan-left ends mid-page. Decoding costs six `BigInt` parses
161
+ * per bar (see `decodeCandle`) on the thread that draws the chart.
162
+ */
163
+ const pageCaches = new WeakMap<PodRestClient, Map<string, Bar[]>>();
164
+ const PAGE_CACHE_MAX = 256;
165
+
166
+ /** One canonical page, served from this client's page cache when it is final. */
167
+ async function fetchCandlePage(
168
+ rest: PodRestClient,
169
+ id: MarketId,
170
+ resolution: Resolution,
171
+ window: CandlePageWindow,
172
+ ): Promise<CandlePage> {
173
+ const wholePage = window.toMs - window.fromMs === pageSpanMs(resolution);
174
+ const key = `${id}:${resolution}:${window.page}`;
175
+ let cache = pageCaches.get(rest);
176
+ if (!cache) pageCaches.set(rest, (cache = new Map()));
177
+ // Cached entries were verified final when stored, so a hit needs no re-check.
178
+ const hit = wholePage ? cache.get(key) : undefined;
179
+ if (hit) return { bars: hit, watermarkMs: Number.MAX_SAFE_INTEGER };
180
+ for (let attempt = 1; ; attempt++) {
181
+ try {
182
+ const page = await rest.candles(id, {
183
+ resolution,
184
+ from: window.fromMs,
185
+ to: window.toMs,
186
+ limit: RESOLUTION_PAGE_BUCKETS[resolution],
187
+ });
188
+ // Two different questions, so two predicates. Cacheable? Only a whole
189
+ // page the indexer has passed can never change again.
190
+ const covered = page.solutionNow >= window.toMs;
191
+ if (covered && wholePage) {
192
+ // Oldest insertion out first; the bound is on memory, not a policy.
193
+ if (cache.size >= PAGE_CACHE_MAX) cache.delete(cache.keys().next().value!);
194
+ cache.set(key, page.bars);
195
+ }
196
+ // Worth retrying? Only a WHOLE page that came back short — the indexer is
197
+ // behind by more than a page and a moment will fix it. The trailing page
198
+ // is clamped by OUR clock, so its shortfall is the normal state of
199
+ // affairs, and retrying it spins three requests and seconds of backoff
200
+ // against a healthy node on nothing worse than clock skew.
201
+ if (covered || !wholePage || attempt >= PAGE_ATTEMPTS) {
202
+ return { bars: page.bars, watermarkMs: page.solutionNow };
203
+ }
204
+ } catch (err) {
205
+ if (attempt >= PAGE_ATTEMPTS || !worthRetrying(err)) throw err;
206
+ }
207
+ // Exponential with jitter: the node sheds load in bursts, and a read that
208
+ // retries on a fixed short delay just lands inside the same burst.
209
+ const backoff = PAGE_RETRY_MS * 2 ** (attempt - 1) * (1 + Math.random());
210
+ await new Promise((resolve) => setTimeout(resolve, backoff));
211
+ }
212
+ }
213
+
214
+ /** How many pages a history read has in flight at once. */
215
+ const HISTORY_CONCURRENCY = 8;
216
+
217
+ /**
218
+ * Attempts per page, and the backoff between them. One failure must not decide
219
+ * a whole read: `fetchCandleHistory` rejects the window on a failed page, and a
220
+ * chart shows that as a hard error it will not retry on its own. Cold windows
221
+ * on a busy node do fail once and then answer in half a second, which is
222
+ * exactly what a retry is for. A 4xx (other than 429) is the server saying the
223
+ * request itself is wrong — asking again cannot help.
224
+ */
225
+ const PAGE_ATTEMPTS = 3;
226
+ const PAGE_RETRY_MS = 400;
227
+
228
+ const worthRetrying = (err: unknown) =>
229
+ !(err instanceof PodHttpError) || err.status === 429 || err.status >= 500;
230
+
231
+ /**
232
+ * Closed bars covering `[range.from, range.to)` — the one-shot read behind a
233
+ * chart's history request, with no resource, no subscription and no shared
234
+ * mutable state.
235
+ *
236
+ * A page that fails after its retries decides how much of the window is
237
+ * deliverable, and WHERE it failed is what matters:
238
+ *
239
+ * - at the old end, the answer is simply shorter — history stops at the gap,
240
+ * and the caller asks again for the older range when it needs it (a chart
241
+ * does exactly that on the next pan). Nothing is misrepresented, with one
242
+ * exception that must not slip through: if nothing at all survives, an empty
243
+ * answer would assert the window is empty, so that case rejects too.
244
+ * - anywhere inside, the read REJECTS. A chart treats the answer as the truth
245
+ * for the range it asked about and does not re-ask, so bars either side of a
246
+ * swallowed gap would draw a hole nobody can detect — the failure this whole
247
+ * read exists to prevent. Callers get an error they can retry.
248
+ *
249
+ * (The live series takes the opposite side of that trade — see `fetchPages`.)
250
+ */
251
+ export async function fetchCandleHistory(
252
+ rest: PodRestClient,
253
+ id: MarketId,
254
+ resolution: Resolution,
255
+ range: TimeRange,
256
+ nowMs = Date.now(),
257
+ ): Promise<Bar[]> {
258
+ const toMs = range.to ?? nowMs;
259
+ const windows = candlePageWindows(resolution, range.from, toMs, nowMs);
260
+ const pages: CandlePage[] = new Array(windows.length);
261
+ const failures: unknown[] = new Array(windows.length);
262
+ // Newest page first, `HISTORY_CONCURRENCY` at a time: a wide window is tens
263
+ // of pages (56 for a fortnight of 1m bars, thousands for a year), and firing
264
+ // them all at once queues the visible edge behind the oldest history on
265
+ // HTTP/1.1 and lands the whole fan-out on the node at once on HTTP/2.
266
+ let next = windows.length - 1;
267
+ const worker = async () => {
268
+ while (next >= 0) {
269
+ const i = next--;
270
+ try {
271
+ pages[i] = await fetchCandlePage(rest, id, resolution, windows[i]!);
272
+ } catch (err) {
273
+ failures[i] = err;
274
+ }
275
+ }
276
+ };
277
+ await Promise.all(Array.from({ length: Math.min(HISTORY_CONCURRENCY, windows.length) }, worker));
278
+
279
+ // An unfetched page reads as `undefined`; an empty page is an empty array, so
280
+ // "no bars here" and "never arrived" stay distinguishable.
281
+ const oldestOk = pages.findIndex((page) => page !== undefined);
282
+ if (windows.length && oldestOk === -1) throw failures.find((err) => err !== undefined);
283
+ for (let i = oldestOk; i < pages.length; i++) {
284
+ if (pages[i] === undefined) throw failures[i]; // a gap with bars on both sides
285
+ }
286
+ const kept = pages.slice(Math.max(0, oldestOk));
287
+ // The indexer's watermark bounds what any of these answers could cover:
288
+ // buckets past it are not history yet, they are simply unwritten. Claiming
289
+ // only up to there keeps a lagging indexer from looking like a complete
290
+ // window that happens to stop early.
291
+ const coveredToMs = kept.reduce((limit, page) => Math.min(limit, page.watermarkMs), toMs);
292
+ // Pages tile the window in ascending order and never overlap, so this is
293
+ // already sorted; the filter drops the partial buckets at either edge.
294
+ const bars = kept.flatMap((page) => page.bars).filter((b) => b.time >= range.from && b.time < coveredToMs);
295
+
296
+ // An EMPTY answer is not a small answer: it asserts "there are no bars in this
297
+ // window", and a chart takes that as settled and stops asking. Only the part
298
+ // of the window that was actually read can say that. So when nothing came
299
+ // back and the window was not covered — a failed page dropped off the old
300
+ // end, or the watermark short of the new end — surface the failure instead,
301
+ // which the caller retries. Otherwise a quiet stretch next to a shed page
302
+ // would hide that page's bars for as long as the chart lives.
303
+ if (!bars.length && (oldestOk > 0 || coveredToMs < toMs)) {
304
+ throw failures[oldestOk - 1]
305
+ ?? new Error(`candle history for ${id} is not indexed past ${coveredToMs}`);
306
+ }
307
+ return bars;
308
+ }
309
+
43
310
  export class CandleSeries implements SeriesResource<Bar> {
44
311
  private readonly base: BaseResource<Bar[]>;
45
312
  private handle: ResourceHandle<Bar[]> | undefined;
@@ -47,12 +314,9 @@ export class CandleSeries implements SeriesResource<Bar> {
47
314
  private readonly pages = new Map<number, Bar[]>(); // pageIndex -> closed bars
48
315
  private readonly live = new Map<number, Bar>(); // bucketStartMs -> forming bar
49
316
  private readonly resSecs: number;
50
- private readonly pageBuckets: number;
51
- private readonly pageSpanSecs: number;
52
317
 
53
318
  private window: TimeRange;
54
319
  private minPage: number | undefined;
55
- private maxPage: number | undefined;
56
320
  private _loading = false;
57
321
  private _hasMore = true;
58
322
  private lastTickUs = 0;
@@ -68,10 +332,7 @@ export class CandleSeries implements SeriesResource<Bar> {
68
332
  range?: TimeRange,
69
333
  ) {
70
334
  this.resSecs = RESOLUTION_SECONDS[resolution];
71
- this.pageBuckets = RESOLUTION_PAGE_BUCKETS[resolution];
72
- this.pageSpanSecs = this.resSecs * this.pageBuckets;
73
- const span = this.pageSpanSecs * 1000;
74
- this.window = range ?? { from: Date.now() - span };
335
+ this.window = range ?? { from: Date.now() - pageSpanMs(resolution) };
75
336
 
76
337
  this.base = new BaseResource<Bar[]>((h) => {
77
338
  this.handle = h;
@@ -105,6 +366,12 @@ export class CandleSeries implements SeriesResource<Bar> {
105
366
  this.tickSub?.unsubscribe();
106
367
  this.tickSub = undefined;
107
368
  this.handle = undefined;
369
+ // Folded buckets do not survive the fold being stopped: on re-subscribe
370
+ // the first `rebuild()` would re-emit a partially-folded bucket from
371
+ // whenever the series last ran, and a reader asking for the forming
372
+ // edge would take it as the answer. Closed pages are immutable, so they
373
+ // stay — dropping them would only refetch what is already correct.
374
+ this.live.clear();
108
375
  };
109
376
  });
110
377
  }
@@ -131,17 +398,12 @@ export class CandleSeries implements SeriesResource<Bar> {
131
398
 
132
399
  // --- internals ---
133
400
 
134
- private pageOf(secs: number): number {
135
- return Math.floor(secs / this.pageSpanSecs);
136
- }
137
-
138
401
  private async loadWindow(range: TimeRange): Promise<void> {
139
- const fromSecs = Math.floor(range.from / 1000);
140
- const toSecs = Math.floor((range.to ?? Date.now()) / 1000);
141
- const startPage = this.pageOf(fromSecs);
142
- const endPage = this.pageOf(Math.max(fromSecs, toSecs - 1));
143
- const nowSecs = Math.floor(Date.now() / 1000);
144
- const trailingPage = this.pageOf(nowSecs);
402
+ const nowMs = Date.now();
403
+ const toMs = range.to ?? nowMs;
404
+ const startPage = candlePageAt(this.resolution, range.from);
405
+ const endPage = candlePageAt(this.resolution, Math.max(range.from, toMs - 1));
406
+ const trailingPage = candlePageAt(this.resolution, nowMs);
145
407
 
146
408
  const wanted: number[] = [];
147
409
  for (let p = startPage; p <= endPage; p++) {
@@ -150,42 +412,32 @@ export class CandleSeries implements SeriesResource<Bar> {
150
412
  await this.fetchPages(wanted);
151
413
  }
152
414
 
415
+ /** The oldest page loaded — `loadOlder` walks down from it. */
416
+ private notePage(page: number): void {
417
+ this.minPage = Math.min(this.minPage ?? page, page);
418
+ }
419
+
153
420
  private async fetchPages(pageIndices: number[]): Promise<void> {
154
421
  if (!pageIndices.length) { this.rebuild(); return; }
155
422
  this._loading = true;
156
423
  this.rebuild(); // surface loading state
157
424
  try {
158
- // The trailing page's window is clamped to the last closed bucket: the
159
- // server returns only closed bars either way, so the content is
160
- // identical — but a fully-elapsed window is served `immutable`
161
- // (browser/CDN-cacheable; its URL rotates once per bucket close), while
162
- // a `to` in the future would be `no-store` on every open. The forming
163
- // bucket comes from the tick subscription (see prepareLiveEdge).
164
- const lastClosedMs = Math.floor(Date.now() / 1000 / this.resSecs) * this.resSecs * 1000;
425
+ const nowMs = Date.now(); // one clock read, so every page agrees on it
165
426
  await Promise.all(pageIndices.map(async (p) => {
166
- const fromMs = p * this.pageSpanSecs * 1000;
167
- const toMs = Math.min((p + 1) * this.pageSpanSecs * 1000, lastClosedMs);
168
- if (toMs <= fromMs) {
169
- // Page holds nothing but the forming bucket (it just started) —
170
- // nothing closed to fetch yet; keep bookkeeping consistent.
171
- this.pages.set(p, this.pages.get(p) ?? []);
172
- this.minPage = this.minPage === undefined ? p : Math.min(this.minPage, p);
173
- this.maxPage = this.maxPage === undefined ? p : Math.max(this.maxPage, p);
174
- return;
175
- }
427
+ const window = candlePageWindow(this.resolution, p, nowMs);
428
+ if (!window) { this.notePage(p); return; }
176
429
  try {
177
- const page = await this.ctx.rest.candles(this.id, {
178
- resolution: this.resolution,
179
- from: fromMs,
180
- to: toMs,
181
- limit: this.pageBuckets,
182
- });
183
- this.pages.set(p, page.bars);
184
- this.minPage = this.minPage === undefined ? p : Math.min(this.minPage, p);
185
- this.maxPage = this.maxPage === undefined ? p : Math.max(this.maxPage, p);
186
- if (page.bars.length === 0 && this.minPage === p) this._hasMore = false;
430
+ const { bars } = await fetchCandlePage(this.ctx.rest, this.id, this.resolution, window);
431
+ this.pages.set(p, bars);
432
+ this.notePage(p);
433
+ if (bars.length === 0 && this.minPage === p) this._hasMore = false;
187
434
  } catch {
188
- this.pages.set(p, this.pages.get(p) ?? []);
435
+ // A live series tolerates a missing page where `fetchCandleHistory`
436
+ // rejects: it will ask again. But leave the page MISSING rather than
437
+ // storing it empty — a stored empty page is indistinguishable from
438
+ // "no bars in this span", so a transient failure would become a
439
+ // permanent hole, since `loadWindow` only fetches pages it does not
440
+ // already have.
189
441
  }
190
442
  }));
191
443
  } finally {
@@ -70,16 +70,25 @@ type FetchFn = typeof fetch;
70
70
  export interface RestClientOptions {
71
71
  restUrl: string;
72
72
  fetch?: FetchFn;
73
+ /**
74
+ * Per-request timeout (ms, default 15s). A request that never settles is
75
+ * worse than one that fails: it holds its slot in `inflight`, so retries of
76
+ * the same URL join the hang instead of trying again. Cold candle windows on
77
+ * a busy node have taken tens of seconds and then answered in half a second.
78
+ */
79
+ timeoutMs?: number;
73
80
  }
74
81
 
75
82
  export class PodRestClient {
76
83
  private readonly base: string;
77
84
  private readonly fetchFn: FetchFn;
85
+ private readonly timeoutMs: number;
78
86
  private readonly inflight = new Map<string, Promise<unknown>>();
79
87
 
80
88
  constructor(opts: RestClientOptions) {
81
89
  this.base = opts.restUrl.replace(/\/$/, "");
82
90
  this.fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
91
+ this.timeoutMs = opts.timeoutMs ?? 15_000;
83
92
  }
84
93
 
85
94
  private async get<T>(path: string, query?: Record<string, string | number | undefined>): Promise<T> {
@@ -105,7 +114,12 @@ export class PodRestClient {
105
114
  }
106
115
 
107
116
  private async doGet<T>(url: string): Promise<T> {
108
- const res = await this.fetchFn(url, { headers: { accept: "application/json" } });
117
+ const res = await this.fetchFn(url, {
118
+ headers: { accept: "application/json" },
119
+ // `AbortSignal.timeout` everywhere current; omitted rather than polyfilled
120
+ // where it is missing, which only loses the timeout.
121
+ signal: AbortSignal.timeout?.(this.timeoutMs),
122
+ });
109
123
  if (!res.ok) {
110
124
  let body = "";
111
125
  try { body = await res.text(); } catch { /* ignore */ }