@bedrock-rbx/ocale 0.3.1 → 0.3.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/README.md +23 -11
- package/dist/badges.d.mts +1 -1
- package/dist/badges.mjs +3 -3
- package/dist/{polling-0t1wQyVY.d.mts → capacity-admission-BvnJjY0S.d.mts} +35 -3
- package/dist/capacity-admission-BvnJjY0S.d.mts.map +1 -0
- package/dist/developer-products.d.mts +1 -1
- package/dist/developer-products.mjs +4 -4
- package/dist/game-passes.d.mts +1 -1
- package/dist/game-passes.mjs +4 -4
- package/dist/index.d.mts +113 -4
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +5 -5
- package/dist/luau-execution.d.mts +39 -5
- package/dist/luau-execution.d.mts.map +1 -1
- package/dist/luau-execution.mjs +8 -13
- package/dist/luau-execution.mjs.map +1 -1
- package/dist/{network-error-DmNy_j-u.mjs → network-error-DR9FX5hb.mjs} +32 -7
- package/dist/network-error-DR9FX5hb.mjs.map +1 -0
- package/dist/places.d.mts +4 -4
- package/dist/places.d.mts.map +1 -1
- package/dist/places.mjs +8 -13
- package/dist/places.mjs.map +1 -1
- package/dist/{poll-timeout-wrPTnGl_.mjs → poll-timeout-3PXLsabj.mjs} +2 -2
- package/dist/{poll-timeout-wrPTnGl_.mjs.map → poll-timeout-3PXLsabj.mjs.map} +1 -1
- package/dist/{polling-helpers-CzdT2FS5.mjs → polling-helpers-sKTsqEc1.mjs} +323 -21
- package/dist/polling-helpers-sKTsqEc1.mjs.map +1 -0
- package/dist/{price-information-Czs5cWR1.mjs → price-information-hWXV6DAI.mjs} +2 -2
- package/dist/{price-information-Czs5cWR1.mjs.map → price-information-hWXV6DAI.mjs.map} +1 -1
- package/dist/{resource-client-aqk_V4TD.mjs → resource-client-3cOhqZpX.mjs} +254 -72
- package/dist/resource-client-3cOhqZpX.mjs.map +1 -0
- package/dist/resource-client-BivRq3JZ.d.mts +164 -0
- package/dist/resource-client-BivRq3JZ.d.mts.map +1 -0
- package/dist/{retry-Cj5OXCdL.d.mts → retry-DXEklFrt.d.mts} +51 -16
- package/dist/{retry-Cj5OXCdL.d.mts.map → retry-DXEklFrt.d.mts.map} +1 -1
- package/dist/{retry-DIK_T_oF.mjs → retry-vpHMIwaU.mjs} +359 -192
- package/dist/retry-vpHMIwaU.mjs.map +1 -0
- package/dist/storage.d.mts +2 -158
- package/dist/storage.d.mts.map +1 -1
- package/dist/storage.mjs +3 -3
- package/dist/testing.d.mts +1 -1
- package/dist/testing.mjs +1 -1
- package/dist/{types-D_njb3qW.d.mts → types-C3Egi37J.d.mts} +14 -8
- package/dist/types-C3Egi37J.d.mts.map +1 -0
- package/dist/universes.d.mts +308 -2
- package/dist/universes.d.mts.map +1 -1
- package/dist/universes.mjs +509 -34
- package/dist/universes.mjs.map +1 -1
- package/dist/{validation-BwjwOJPD.mjs → validation-B_Zs1So2.mjs} +2 -2
- package/dist/validation-B_Zs1So2.mjs.map +1 -0
- package/package.json +3 -3
- package/dist/network-error-DmNy_j-u.mjs.map +0 -1
- package/dist/polling-0t1wQyVY.d.mts.map +0 -1
- package/dist/polling-helpers-CzdT2FS5.mjs.map +0 -1
- package/dist/resource-client-aqk_V4TD.mjs.map +0 -1
- package/dist/retry-DIK_T_oF.mjs.map +0 -1
- package/dist/types-D_njb3qW.d.mts.map +0 -1
- package/dist/validation-BwjwOJPD.mjs.map +0 -1
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { a as ApiError, i as markServerRetryGuidance, n as RateLimitError, r as hasServerRetryGuidance, s as OpenCloudError, t as NetworkError } from "./network-error-
|
|
1
|
+
import { a as ApiError, i as markServerRetryGuidance, n as RateLimitError, r as hasServerRetryGuidance, s as OpenCloudError, t as NetworkError } from "./network-error-DR9FX5hb.mjs";
|
|
2
2
|
//#region src/internal/utils/try-catch.ts
|
|
3
3
|
/**
|
|
4
4
|
* Wraps a promise into a {@link Result}, catching rejections.
|
|
@@ -31,6 +31,15 @@ const DIAGNOSTIC_HEADER_ALLOWLIST = new Set([
|
|
|
31
31
|
"x-request-id"
|
|
32
32
|
]);
|
|
33
33
|
const DIAGNOSTIC_HEADER_PREFIX = "x-roblox-";
|
|
34
|
+
const RATE_LIMIT_HEADER_ALLOWLIST = new Set([
|
|
35
|
+
"date",
|
|
36
|
+
"retry-after",
|
|
37
|
+
"x-envoy-ratelimited",
|
|
38
|
+
"x-ratelimit-limit",
|
|
39
|
+
"x-ratelimit-remaining",
|
|
40
|
+
"x-ratelimit-reset",
|
|
41
|
+
"x-retry-after-coverage"
|
|
42
|
+
]);
|
|
34
43
|
const TITLE_OPEN_PATTERN = /<title[^>]*>/i;
|
|
35
44
|
const H1_OPEN_PATTERN = /<h1[^>]*>/i;
|
|
36
45
|
const TAG_PATTERN = /<[^<>]*>/g;
|
|
@@ -69,9 +78,18 @@ function extractGatewaySummary(contentType, rawText) {
|
|
|
69
78
|
* @returns A record containing only the allowlisted headers that were present.
|
|
70
79
|
*/
|
|
71
80
|
function pickDiagnosticHeaders(headers) {
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
81
|
+
return pickHeaders(headers);
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Filters a lowercased header record to the raw evidence useful for diagnosing
|
|
85
|
+
* a 429: the general diagnostic headers plus rate-limit guidance and counters.
|
|
86
|
+
* Values are copied without parsing so comma-joined windows remain available.
|
|
87
|
+
*
|
|
88
|
+
* @param headers - The full header record (lowercased keys).
|
|
89
|
+
* @returns Only allowlisted diagnostic and rate-limit headers.
|
|
90
|
+
*/
|
|
91
|
+
function pickRateLimitHeaders(headers) {
|
|
92
|
+
return pickHeaders(headers, RATE_LIMIT_HEADER_ALLOWLIST);
|
|
75
93
|
}
|
|
76
94
|
/**
|
|
77
95
|
* Converts a `Headers` object to a plain record with lowercased keys.
|
|
@@ -135,6 +153,104 @@ function isHtmlBody(contentType, rawText) {
|
|
|
135
153
|
const head = rawText.trimStart().toLowerCase();
|
|
136
154
|
return head.startsWith("<html") || head.startsWith("<!doctype html");
|
|
137
155
|
}
|
|
156
|
+
function pickHeaders(headers, additionalAllowlist) {
|
|
157
|
+
const picked = {};
|
|
158
|
+
for (const [name, value] of Object.entries(headers)) if (DIAGNOSTIC_HEADER_ALLOWLIST.has(name) || name.startsWith(DIAGNOSTIC_HEADER_PREFIX) || additionalAllowlist?.has(name) === true) picked[name] = value;
|
|
159
|
+
return picked;
|
|
160
|
+
}
|
|
161
|
+
//#endregion
|
|
162
|
+
//#region src/internal/http/error-body.ts
|
|
163
|
+
const CANONICAL_STATUS = /^[A-Z][A-Z0-9_]*$/;
|
|
164
|
+
/**
|
|
165
|
+
* Permissively extracts a machine-readable error code from a response body.
|
|
166
|
+
*
|
|
167
|
+
* Four shapes are checked, in precedence order. Modern Open Cloud responses
|
|
168
|
+
* use `{ errorCode: string, message: string }`; Cloud v2 resource endpoints
|
|
169
|
+
* carry the canonical status in `code` (`{ code: "INVALID_ARGUMENT", message:
|
|
170
|
+
* string }`); other v2 endpoints, such as memory-store queues, carry it in
|
|
171
|
+
* `error` (`{ error: "NOT_FOUND", message: string }`); the legacy
|
|
172
|
+
* game-internationalization endpoints use
|
|
173
|
+
* `{ errors: [{ code: number, message: string }, ...] }`. Numeric legacy codes
|
|
174
|
+
* are returned as strings so callers see one consistent type.
|
|
175
|
+
*
|
|
176
|
+
* `error` is read only when it holds an upper-snake-case token. A Google-style
|
|
177
|
+
* nested envelope (`{ error: { code, message, status } }`) puts an object
|
|
178
|
+
* there, and coercing that to a string would hand callers `"[object Object]"`
|
|
179
|
+
* as a status. The server-management API puts a sentence there (`{ error:
|
|
180
|
+
* "Place 1 does not belong to universe 2" }`), which
|
|
181
|
+
* {@link extractErrorMessage} reads instead.
|
|
182
|
+
*
|
|
183
|
+
* @param body - The parsed response body (unknown shape).
|
|
184
|
+
* @returns The error code if present, otherwise `undefined`.
|
|
185
|
+
*/
|
|
186
|
+
function extractErrorCode(body) {
|
|
187
|
+
if (body === null || typeof body !== "object") return;
|
|
188
|
+
const errorCode = Reflect.get(body, "errorCode");
|
|
189
|
+
if (typeof errorCode === "string") return errorCode;
|
|
190
|
+
const v2Code = Reflect.get(body, "code");
|
|
191
|
+
if (typeof v2Code === "string") return v2Code;
|
|
192
|
+
const v2Error = readErrorField(body);
|
|
193
|
+
if (v2Error !== void 0 && CANONICAL_STATUS.test(v2Error)) return v2Error;
|
|
194
|
+
return extractLegacyCode(body);
|
|
195
|
+
}
|
|
196
|
+
/**
|
|
197
|
+
* Permissively extracts a human-readable error message from a response body.
|
|
198
|
+
*
|
|
199
|
+
* Modern Open Cloud responses expose `message` at the top level;
|
|
200
|
+
* server-management business-rule errors put a sentence in `error`, and its
|
|
201
|
+
* validation errors are ASP.NET ProblemDetails, read as the `title` followed
|
|
202
|
+
* by the first field error in `errors`; the legacy game-internationalization
|
|
203
|
+
* endpoints nest it under `errors[0].message`.
|
|
204
|
+
*
|
|
205
|
+
* @param body - The parsed response body (unknown shape).
|
|
206
|
+
* @returns The message if present, otherwise `undefined`.
|
|
207
|
+
*/
|
|
208
|
+
function extractErrorMessage(body) {
|
|
209
|
+
if (body === null || typeof body !== "object") return;
|
|
210
|
+
const message = Reflect.get(body, "message");
|
|
211
|
+
if (typeof message === "string") return message;
|
|
212
|
+
const errorSentence = readErrorField(body);
|
|
213
|
+
if (errorSentence !== void 0 && !CANONICAL_STATUS.test(errorSentence)) return errorSentence;
|
|
214
|
+
return extractProblemDetailsMessage(body) ?? extractLegacyMessage(body);
|
|
215
|
+
}
|
|
216
|
+
function readErrorField(body) {
|
|
217
|
+
const error = Reflect.get(body, "error");
|
|
218
|
+
return typeof error === "string" ? error : void 0;
|
|
219
|
+
}
|
|
220
|
+
function readLegacyErrorEntry(body) {
|
|
221
|
+
const errors = Reflect.get(body, "errors");
|
|
222
|
+
if (!Array.isArray(errors)) return;
|
|
223
|
+
const [first] = errors;
|
|
224
|
+
if (typeof first !== "object" || first === null) return;
|
|
225
|
+
return first;
|
|
226
|
+
}
|
|
227
|
+
function extractLegacyCode(body) {
|
|
228
|
+
const first = readLegacyErrorEntry(body);
|
|
229
|
+
if (first === void 0) return;
|
|
230
|
+
const code = Reflect.get(first, "code");
|
|
231
|
+
if (typeof code === "string") return code;
|
|
232
|
+
return typeof code === "number" ? String(code) : void 0;
|
|
233
|
+
}
|
|
234
|
+
function readFirstFieldError(body) {
|
|
235
|
+
const errors = Reflect.get(body, "errors");
|
|
236
|
+
if (typeof errors !== "object" || errors === null) return;
|
|
237
|
+
const [fieldErrors] = Object.values(errors);
|
|
238
|
+
if (!Array.isArray(fieldErrors)) return;
|
|
239
|
+
const [first] = fieldErrors;
|
|
240
|
+
return typeof first === "string" ? first : void 0;
|
|
241
|
+
}
|
|
242
|
+
function extractProblemDetailsMessage(body) {
|
|
243
|
+
const title = Reflect.get(body, "title");
|
|
244
|
+
const fieldError = readFirstFieldError(body);
|
|
245
|
+
if (typeof title !== "string") return fieldError;
|
|
246
|
+
return fieldError === void 0 ? title : `${title} ${fieldError}`;
|
|
247
|
+
}
|
|
248
|
+
function extractLegacyMessage(body) {
|
|
249
|
+
const first = readLegacyErrorEntry(body);
|
|
250
|
+
if (first === void 0) return;
|
|
251
|
+
const message = Reflect.get(first, "message");
|
|
252
|
+
return typeof message === "string" ? message : void 0;
|
|
253
|
+
}
|
|
138
254
|
//#endregion
|
|
139
255
|
//#region src/internal/http/http1-dispatcher.ts
|
|
140
256
|
/**
|
|
@@ -258,112 +374,6 @@ function parseRateLimitHeaders(headers) {
|
|
|
258
374
|
};
|
|
259
375
|
}
|
|
260
376
|
//#endregion
|
|
261
|
-
//#region src/errors/request-aborted.ts
|
|
262
|
-
/**
|
|
263
|
-
* Returned when a caller's `AbortSignal` cancels an Open Cloud request.
|
|
264
|
-
* The reason is preserved so intentional cancellation can be distinguished
|
|
265
|
-
* from transport failures and SDK-owned request timeouts.
|
|
266
|
-
*
|
|
267
|
-
* @since 0.3.1
|
|
268
|
-
*
|
|
269
|
-
* @example
|
|
270
|
-
*
|
|
271
|
-
* ```ts
|
|
272
|
-
* import { RequestAbortedError } from "@bedrock-rbx/ocale";
|
|
273
|
-
*
|
|
274
|
-
* const error = new RequestAbortedError("Request was aborted", {
|
|
275
|
-
* reason: "superseded",
|
|
276
|
-
* });
|
|
277
|
-
*
|
|
278
|
-
* expect(error).toBeInstanceOf(RequestAbortedError);
|
|
279
|
-
* expect(error.reason).toBe("superseded");
|
|
280
|
-
* ```
|
|
281
|
-
*/
|
|
282
|
-
var RequestAbortedError = class extends OpenCloudError {
|
|
283
|
-
name = "RequestAbortedError";
|
|
284
|
-
reason;
|
|
285
|
-
/**
|
|
286
|
-
* Creates a new RequestAbortedError.
|
|
287
|
-
*
|
|
288
|
-
* @param message - Human-readable description of the cancellation.
|
|
289
|
-
* @param options - Error options including the caller's abort reason.
|
|
290
|
-
*/
|
|
291
|
-
constructor(message, options = {}) {
|
|
292
|
-
super(message, options);
|
|
293
|
-
this.reason = options.reason;
|
|
294
|
-
}
|
|
295
|
-
};
|
|
296
|
-
//#endregion
|
|
297
|
-
//#region src/internal/utils/abort.ts
|
|
298
|
-
/**
|
|
299
|
-
* Sentinel returned when an asynchronous operation loses a race with a signal.
|
|
300
|
-
*/
|
|
301
|
-
const ABORTED = Symbol("aborted");
|
|
302
|
-
/**
|
|
303
|
-
* Runs an asynchronous operation and resolves with {@link ABORTED} when the
|
|
304
|
-
* supplied signal fires first. The underlying operation still receives the
|
|
305
|
-
* signal separately so cancellable implementations can release their work.
|
|
306
|
-
*
|
|
307
|
-
* @template T - Value produced by the operation.
|
|
308
|
-
* @param operation - Operation to start after the abort observer is installed.
|
|
309
|
-
* @param signal - Optional caller cancellation signal.
|
|
310
|
-
* @returns The operation's value, or {@link ABORTED} when cancellation wins.
|
|
311
|
-
* @rejects The operation's error when it fails before cancellation.
|
|
312
|
-
*/
|
|
313
|
-
async function raceWithAbortAsync(operation, signal) {
|
|
314
|
-
if (signal === void 0) return operation();
|
|
315
|
-
if (signal.aborted) return ABORTED;
|
|
316
|
-
const { promise, resolve } = Promise.withResolvers();
|
|
317
|
-
function onAbort() {
|
|
318
|
-
resolve(ABORTED);
|
|
319
|
-
}
|
|
320
|
-
signal.addEventListener("abort", onAbort);
|
|
321
|
-
try {
|
|
322
|
-
return await Promise.race([operation(), promise]);
|
|
323
|
-
} finally {
|
|
324
|
-
signal.removeEventListener("abort", onAbort);
|
|
325
|
-
}
|
|
326
|
-
}
|
|
327
|
-
/**
|
|
328
|
-
* Creates the canonical typed failure for caller-request cancellation.
|
|
329
|
-
*
|
|
330
|
-
* @param signal - The caller signal whose reason should be preserved.
|
|
331
|
-
* @returns A cancellation error carrying the signal's reason.
|
|
332
|
-
*/
|
|
333
|
-
function requestAbortedError(signal) {
|
|
334
|
-
return new RequestAbortedError("Request was aborted", { reason: signal?.reason });
|
|
335
|
-
}
|
|
336
|
-
//#endregion
|
|
337
|
-
//#region src/internal/http/request-signal.ts
|
|
338
|
-
/**
|
|
339
|
-
* Composes caller cancellation with Ocale's request deadline. The winning
|
|
340
|
-
* signal's reason is retained by `AbortSignal.any`, allowing failure
|
|
341
|
-
* classification to distinguish cancellation from timeout.
|
|
342
|
-
*
|
|
343
|
-
* @param config - Transport configuration for one request.
|
|
344
|
-
* @returns A caller signal, timeout signal, their composition, or `undefined`.
|
|
345
|
-
*/
|
|
346
|
-
function requestSignal(config) {
|
|
347
|
-
if (config.timeout === void 0) return config.signal;
|
|
348
|
-
const timeout = AbortSignal.timeout(config.timeout);
|
|
349
|
-
return config.signal === void 0 ? timeout : AbortSignal.any([config.signal, timeout]);
|
|
350
|
-
}
|
|
351
|
-
/**
|
|
352
|
-
* Classifies a fetch rejection without confusing a caller abort with the
|
|
353
|
-
* transport's own timeout.
|
|
354
|
-
*
|
|
355
|
-
* @param args - Failure, target, request config, and effective fetch signal.
|
|
356
|
-
* @returns A typed caller cancellation or network failure.
|
|
357
|
-
*/
|
|
358
|
-
function requestFailure({ cause, config, effectiveSignal, target }) {
|
|
359
|
-
if (config.signal?.aborted === true && effectiveSignal?.aborted === true && Object.is(effectiveSignal.reason, config.signal.reason)) return requestAbortedError(config.signal);
|
|
360
|
-
return new NetworkError("Network request failed", {
|
|
361
|
-
cause,
|
|
362
|
-
method: target.method,
|
|
363
|
-
url: target.url
|
|
364
|
-
});
|
|
365
|
-
}
|
|
366
|
-
//#endregion
|
|
367
377
|
//#region src/internal/http/retry-guidance.ts
|
|
368
378
|
const ABBREVIATED_WEEKDAYS = [
|
|
369
379
|
"Sun",
|
|
@@ -494,6 +504,146 @@ function parseHttpDate(value, nowMs) {
|
|
|
494
504
|
return parseFixedDate(value) ?? parseObsoleteDate(value, nowMs) ?? parseAnsiDate(value);
|
|
495
505
|
}
|
|
496
506
|
//#endregion
|
|
507
|
+
//#region src/internal/http/rate-limit-response.ts
|
|
508
|
+
/**
|
|
509
|
+
* Builds a public rate-limit error from a 429 response and its already-read
|
|
510
|
+
* body, retaining safe raw evidence alongside the existing parsed guidance.
|
|
511
|
+
*
|
|
512
|
+
* @param response - The 429 response to classify.
|
|
513
|
+
* @param details - The parsed or safely truncated response body.
|
|
514
|
+
* @returns A rate-limit error carrying the response evidence.
|
|
515
|
+
*/
|
|
516
|
+
function createRateLimitError(response, details) {
|
|
517
|
+
const headers = headersToRecord(response.headers);
|
|
518
|
+
const remaining = reduceRateLimitTokens(headers["x-ratelimit-remaining"], (a, b) => {
|
|
519
|
+
return Math.min(a, b);
|
|
520
|
+
});
|
|
521
|
+
const guidedRetrySeconds = resolveRetryGuidance({
|
|
522
|
+
headers,
|
|
523
|
+
remaining
|
|
524
|
+
});
|
|
525
|
+
const error = new RateLimitError("Rate limited", {
|
|
526
|
+
code: extractRateLimitErrorCode(details),
|
|
527
|
+
details,
|
|
528
|
+
remaining,
|
|
529
|
+
responseHeaders: pickRateLimitHeaders(headers),
|
|
530
|
+
retryAfterSeconds: guidedRetrySeconds ?? 0,
|
|
531
|
+
statusCode: response.status
|
|
532
|
+
});
|
|
533
|
+
return guidedRetrySeconds === void 0 ? error : markServerRetryGuidance(error);
|
|
534
|
+
}
|
|
535
|
+
function extractRateLimitErrorCode(body) {
|
|
536
|
+
if (body === null || typeof body !== "object") return;
|
|
537
|
+
const code = Reflect.get(body, "code");
|
|
538
|
+
return typeof code === "string" && code.trim() ? code : void 0;
|
|
539
|
+
}
|
|
540
|
+
//#endregion
|
|
541
|
+
//#region src/errors/request-aborted.ts
|
|
542
|
+
/**
|
|
543
|
+
* Returned when a caller's `AbortSignal` cancels an Open Cloud request.
|
|
544
|
+
* The reason is preserved so intentional cancellation can be distinguished
|
|
545
|
+
* from transport failures and SDK-owned request timeouts.
|
|
546
|
+
*
|
|
547
|
+
* @since 0.3.1
|
|
548
|
+
*
|
|
549
|
+
* @example
|
|
550
|
+
*
|
|
551
|
+
* ```ts
|
|
552
|
+
* import { RequestAbortedError } from "@bedrock-rbx/ocale";
|
|
553
|
+
*
|
|
554
|
+
* const error = new RequestAbortedError("Request was aborted", {
|
|
555
|
+
* reason: "superseded",
|
|
556
|
+
* });
|
|
557
|
+
*
|
|
558
|
+
* expect(error).toBeInstanceOf(RequestAbortedError);
|
|
559
|
+
* expect(error.reason).toBe("superseded");
|
|
560
|
+
* ```
|
|
561
|
+
*/
|
|
562
|
+
var RequestAbortedError = class extends OpenCloudError {
|
|
563
|
+
name = "RequestAbortedError";
|
|
564
|
+
reason;
|
|
565
|
+
/**
|
|
566
|
+
* Creates a new RequestAbortedError.
|
|
567
|
+
*
|
|
568
|
+
* @param message - Human-readable description of the cancellation.
|
|
569
|
+
* @param options - Error options including the caller's abort reason.
|
|
570
|
+
*/
|
|
571
|
+
constructor(message, options = {}) {
|
|
572
|
+
super(message, options);
|
|
573
|
+
this.reason = options.reason;
|
|
574
|
+
}
|
|
575
|
+
};
|
|
576
|
+
//#endregion
|
|
577
|
+
//#region src/internal/utils/abort.ts
|
|
578
|
+
/**
|
|
579
|
+
* Sentinel returned when an asynchronous operation loses a race with a signal.
|
|
580
|
+
*/
|
|
581
|
+
const ABORTED = Symbol("aborted");
|
|
582
|
+
/**
|
|
583
|
+
* Runs an asynchronous operation and resolves with {@link ABORTED} when the
|
|
584
|
+
* supplied signal fires first. The underlying operation still receives the
|
|
585
|
+
* signal separately so cancellable implementations can release their work.
|
|
586
|
+
*
|
|
587
|
+
* @template T - Value produced by the operation.
|
|
588
|
+
* @param operation - Operation to start after the abort observer is installed.
|
|
589
|
+
* @param signal - Optional caller cancellation signal.
|
|
590
|
+
* @returns The operation's value, or {@link ABORTED} when cancellation wins.
|
|
591
|
+
* @rejects The operation's error when it fails before cancellation.
|
|
592
|
+
*/
|
|
593
|
+
async function raceWithAbortAsync(operation, signal) {
|
|
594
|
+
if (signal === void 0) return operation();
|
|
595
|
+
if (signal.aborted) return ABORTED;
|
|
596
|
+
const { promise, resolve } = Promise.withResolvers();
|
|
597
|
+
function onAbort() {
|
|
598
|
+
resolve(ABORTED);
|
|
599
|
+
}
|
|
600
|
+
signal.addEventListener("abort", onAbort);
|
|
601
|
+
try {
|
|
602
|
+
return await Promise.race([operation(), promise]);
|
|
603
|
+
} finally {
|
|
604
|
+
signal.removeEventListener("abort", onAbort);
|
|
605
|
+
}
|
|
606
|
+
}
|
|
607
|
+
/**
|
|
608
|
+
* Creates the canonical typed failure for caller-request cancellation.
|
|
609
|
+
*
|
|
610
|
+
* @param signal - The caller signal whose reason should be preserved.
|
|
611
|
+
* @returns A cancellation error carrying the signal's reason.
|
|
612
|
+
*/
|
|
613
|
+
function requestAbortedError(signal) {
|
|
614
|
+
return new RequestAbortedError("Request was aborted", { reason: signal?.reason });
|
|
615
|
+
}
|
|
616
|
+
//#endregion
|
|
617
|
+
//#region src/internal/http/request-signal.ts
|
|
618
|
+
/**
|
|
619
|
+
* Composes caller cancellation with Ocale's transport-attempt timeout. The
|
|
620
|
+
* winning signal's reason is retained by `AbortSignal.any`, allowing failure
|
|
621
|
+
* classification to distinguish cancellation from timeout.
|
|
622
|
+
*
|
|
623
|
+
* @param config - Transport configuration for one request.
|
|
624
|
+
* @returns A caller signal, timeout signal, their composition, or `undefined`.
|
|
625
|
+
*/
|
|
626
|
+
function requestSignal(config) {
|
|
627
|
+
if (config.timeout === void 0) return config.signal;
|
|
628
|
+
const timeout = AbortSignal.timeout(config.timeout);
|
|
629
|
+
return config.signal === void 0 ? timeout : AbortSignal.any([config.signal, timeout]);
|
|
630
|
+
}
|
|
631
|
+
/**
|
|
632
|
+
* Classifies a fetch rejection without confusing a caller abort with the
|
|
633
|
+
* transport's own timeout.
|
|
634
|
+
*
|
|
635
|
+
* @param args - Failure, target, request config, and effective fetch signal.
|
|
636
|
+
* @returns A typed caller cancellation or network failure.
|
|
637
|
+
*/
|
|
638
|
+
function requestFailure({ cause, config, effectiveSignal, target }) {
|
|
639
|
+
if (config.signal?.aborted === true && effectiveSignal?.aborted === true && Object.is(effectiveSignal.reason, config.signal.reason)) return requestAbortedError(config.signal);
|
|
640
|
+
return new NetworkError("Network request failed", {
|
|
641
|
+
cause,
|
|
642
|
+
method: target.method,
|
|
643
|
+
url: target.url
|
|
644
|
+
});
|
|
645
|
+
}
|
|
646
|
+
//#endregion
|
|
497
647
|
//#region src/internal/http/upload-request.ts
|
|
498
648
|
/**
|
|
499
649
|
* Reports whether a request is an upload: its body is `FormData`
|
|
@@ -513,46 +663,6 @@ function isUploadRequest(request) {
|
|
|
513
663
|
const CONTENT_TYPE_HEADER = "content-type";
|
|
514
664
|
const CONNECTION_HEADER = "connection";
|
|
515
665
|
/**
|
|
516
|
-
* Permissively extracts a machine-readable error code from a response body.
|
|
517
|
-
*
|
|
518
|
-
* Three shapes are checked, in precedence order. Modern Open Cloud responses
|
|
519
|
-
* use `{ errorCode: string, message: string }`; Open Cloud v2 endpoints carry
|
|
520
|
-
* the canonical status in `error` (`{ error: "NOT_FOUND", message: string }`);
|
|
521
|
-
* the legacy game-internationalization endpoints use
|
|
522
|
-
* `{ errors: [{ code: number, message: string }, ...] }`. Numeric legacy codes
|
|
523
|
-
* are returned as strings so callers see one consistent type.
|
|
524
|
-
*
|
|
525
|
-
* `error` is read only when it holds a string. A Google-style nested envelope
|
|
526
|
-
* (`{ error: { code, message, status } }`) puts an object there, and coercing
|
|
527
|
-
* that to a string would hand callers `"[object Object]"` as a status.
|
|
528
|
-
*
|
|
529
|
-
* @param body - The parsed response body (unknown shape).
|
|
530
|
-
* @returns The error code if present, otherwise `undefined`.
|
|
531
|
-
*/
|
|
532
|
-
function extractErrorCode(body) {
|
|
533
|
-
if (body === null || typeof body !== "object") return;
|
|
534
|
-
const errorCode = Reflect.get(body, "errorCode");
|
|
535
|
-
if (typeof errorCode === "string") return errorCode;
|
|
536
|
-
const v2Error = Reflect.get(body, "error");
|
|
537
|
-
if (typeof v2Error === "string") return v2Error;
|
|
538
|
-
return extractLegacyCode(body);
|
|
539
|
-
}
|
|
540
|
-
/**
|
|
541
|
-
* Permissively extracts a human-readable error message from a response body.
|
|
542
|
-
*
|
|
543
|
-
* Modern Open Cloud responses expose `message` at the top level; the legacy
|
|
544
|
-
* game-internationalization endpoints nest it under `errors[0].message`.
|
|
545
|
-
*
|
|
546
|
-
* @param body - The parsed response body (unknown shape).
|
|
547
|
-
* @returns The message if present, otherwise `undefined`.
|
|
548
|
-
*/
|
|
549
|
-
function extractErrorMessage(body) {
|
|
550
|
-
if (body === null || typeof body !== "object") return;
|
|
551
|
-
const message = Reflect.get(body, "message");
|
|
552
|
-
if (typeof message === "string") return message;
|
|
553
|
-
return extractLegacyMessage(body);
|
|
554
|
-
}
|
|
555
|
-
/**
|
|
556
666
|
* Joins the base URL from config with the relative path from the request.
|
|
557
667
|
*
|
|
558
668
|
* @param request - The HTTP request containing the relative URL.
|
|
@@ -608,26 +718,6 @@ function createFetchHttpClient(fetchFunc = fetch, { createDispatcher = createHtt
|
|
|
608
718
|
});
|
|
609
719
|
} };
|
|
610
720
|
}
|
|
611
|
-
function readLegacyErrorEntry(body) {
|
|
612
|
-
const errors = Reflect.get(body, "errors");
|
|
613
|
-
if (!Array.isArray(errors)) return;
|
|
614
|
-
const [first] = errors;
|
|
615
|
-
if (typeof first !== "object" || first === null) return;
|
|
616
|
-
return first;
|
|
617
|
-
}
|
|
618
|
-
function extractLegacyCode(body) {
|
|
619
|
-
const first = readLegacyErrorEntry(body);
|
|
620
|
-
if (first === void 0) return;
|
|
621
|
-
const code = Reflect.get(first, "code");
|
|
622
|
-
if (typeof code === "string") return code;
|
|
623
|
-
return typeof code === "number" ? String(code) : void 0;
|
|
624
|
-
}
|
|
625
|
-
function extractLegacyMessage(body) {
|
|
626
|
-
const first = readLegacyErrorEntry(body);
|
|
627
|
-
if (first === void 0) return;
|
|
628
|
-
const message = Reflect.get(first, "message");
|
|
629
|
-
return typeof message === "string" ? message : void 0;
|
|
630
|
-
}
|
|
631
721
|
/**
|
|
632
722
|
* Merges the request's own headers onto the transport's, then applies the
|
|
633
723
|
* transport-owned connection directive. `x-api-key` is skipped so a request
|
|
@@ -744,24 +834,6 @@ async function readResponseBodyAsync(response) {
|
|
|
744
834
|
text
|
|
745
835
|
};
|
|
746
836
|
}
|
|
747
|
-
async function createRateLimitErrorAsync(response) {
|
|
748
|
-
const headers = headersToRecord(response.headers);
|
|
749
|
-
const { parsed, text } = await readResponseBodyAsync(response);
|
|
750
|
-
const remaining = reduceRateLimitTokens(headers["x-ratelimit-remaining"], (a, b) => {
|
|
751
|
-
return Math.min(a, b);
|
|
752
|
-
});
|
|
753
|
-
const guidedRetrySeconds = resolveRetryGuidance({
|
|
754
|
-
headers,
|
|
755
|
-
remaining
|
|
756
|
-
});
|
|
757
|
-
const error = new RateLimitError("Rate limited", {
|
|
758
|
-
details: bodyDetail(text, parsed),
|
|
759
|
-
remaining,
|
|
760
|
-
retryAfterSeconds: guidedRetrySeconds ?? 0,
|
|
761
|
-
statusCode: response.status
|
|
762
|
-
});
|
|
763
|
-
return guidedRetrySeconds === void 0 ? error : markServerRetryGuidance(error);
|
|
764
|
-
}
|
|
765
837
|
/**
|
|
766
838
|
* Classifies a fetch `Response` into a typed `Result`.
|
|
767
839
|
*
|
|
@@ -778,11 +850,11 @@ async function createRateLimitErrorAsync(response) {
|
|
|
778
850
|
* @returns A Result containing an HttpResponse on success or an OpenCloudError on failure.
|
|
779
851
|
*/
|
|
780
852
|
async function classifyResponseAsync(response, context) {
|
|
853
|
+
const { parsed, text } = await readResponseBodyAsync(response);
|
|
781
854
|
if (response.status === 429) return {
|
|
782
|
-
err:
|
|
855
|
+
err: createRateLimitError(response, bodyDetail(text, parsed)),
|
|
783
856
|
success: false
|
|
784
857
|
};
|
|
785
|
-
const { parsed, text } = await readResponseBodyAsync(response);
|
|
786
858
|
if (response.status >= 300) return {
|
|
787
859
|
err: createApiError({
|
|
788
860
|
context,
|
|
@@ -911,6 +983,101 @@ var PermissionError = class extends ApiError {
|
|
|
911
983
|
}
|
|
912
984
|
};
|
|
913
985
|
//#endregion
|
|
986
|
+
//#region src/errors/request-deadline-exceeded.ts
|
|
987
|
+
/**
|
|
988
|
+
* Returned when a logical request cannot complete by its absolute deadline.
|
|
989
|
+
* Optional wait details identify an SDK-managed admission wait that was
|
|
990
|
+
* refused. This is distinct from caller cancellation so consumers can report
|
|
991
|
+
* exhausted wall-clock budget accurately.
|
|
992
|
+
*
|
|
993
|
+
* @since 0.3.2
|
|
994
|
+
*
|
|
995
|
+
* @example
|
|
996
|
+
*
|
|
997
|
+
* ```ts
|
|
998
|
+
* import { RequestDeadlineExceededError } from "@bedrock-rbx/ocale";
|
|
999
|
+
*
|
|
1000
|
+
* const error = new RequestDeadlineExceededError("Request deadline elapsed", {
|
|
1001
|
+
* deadlineMs: 1_000_000,
|
|
1002
|
+
* remainingMs: 0,
|
|
1003
|
+
* waitReason: "operation-queue",
|
|
1004
|
+
* });
|
|
1005
|
+
*
|
|
1006
|
+
* expect(error.remainingMs).toBe(0);
|
|
1007
|
+
* expect(error.waitReason).toBe("operation-queue");
|
|
1008
|
+
* ```
|
|
1009
|
+
*/
|
|
1010
|
+
var RequestDeadlineExceededError = class extends OpenCloudError {
|
|
1011
|
+
/** Absolute caller-supplied deadline, as Unix epoch milliseconds. */
|
|
1012
|
+
deadlineMs;
|
|
1013
|
+
name = "RequestDeadlineExceededError";
|
|
1014
|
+
/** Time left when the SDK refused or ended the wait. */
|
|
1015
|
+
remainingMs;
|
|
1016
|
+
/** Intended wait duration, when known. */
|
|
1017
|
+
waitMs;
|
|
1018
|
+
/** SDK admission mechanism whose wait could not meet the deadline. */
|
|
1019
|
+
waitReason;
|
|
1020
|
+
/**
|
|
1021
|
+
* Creates a new RequestDeadlineExceededError.
|
|
1022
|
+
*
|
|
1023
|
+
* @param message - Human-readable description of the exhausted deadline.
|
|
1024
|
+
* @param options - Deadline, remaining budget, and optional wait details.
|
|
1025
|
+
*/
|
|
1026
|
+
constructor(message, options) {
|
|
1027
|
+
super(message, options);
|
|
1028
|
+
this.deadlineMs = options.deadlineMs;
|
|
1029
|
+
this.remainingMs = options.remainingMs;
|
|
1030
|
+
this.waitMs = options.waitMs;
|
|
1031
|
+
this.waitReason = options.waitReason;
|
|
1032
|
+
}
|
|
1033
|
+
};
|
|
1034
|
+
//#endregion
|
|
1035
|
+
//#region src/errors/retry-delay-exceeded.ts
|
|
1036
|
+
/**
|
|
1037
|
+
* Returned when the SDK refuses a retry delay that cannot complete before the
|
|
1038
|
+
* request deadline. This is distinct from cancellation so consumers can
|
|
1039
|
+
* report the server's stated retry time without waiting for it.
|
|
1040
|
+
*
|
|
1041
|
+
* @since 0.3.2
|
|
1042
|
+
*
|
|
1043
|
+
* @example
|
|
1044
|
+
*
|
|
1045
|
+
* ```ts
|
|
1046
|
+
* import { RetryDelayExceededError } from "@bedrock-rbx/ocale";
|
|
1047
|
+
*
|
|
1048
|
+
* const error = new RetryDelayExceededError("Retry delay exceeds the request deadline", {
|
|
1049
|
+
* deadlineMs: 1_000_000,
|
|
1050
|
+
* remainingMs: 495_000,
|
|
1051
|
+
* retryAfterMs: 1_856_000,
|
|
1052
|
+
* });
|
|
1053
|
+
*
|
|
1054
|
+
* expect(error.retryAfterMs).toBe(1_856_000);
|
|
1055
|
+
* expect(error.remainingMs).toBe(495_000);
|
|
1056
|
+
* ```
|
|
1057
|
+
*/
|
|
1058
|
+
var RetryDelayExceededError = class extends RequestDeadlineExceededError {
|
|
1059
|
+
name = "RetryDelayExceededError";
|
|
1060
|
+
/** Computed retry delay refused by the SDK, in milliseconds. */
|
|
1061
|
+
retryAfterMs;
|
|
1062
|
+
/** Computed retry delay refused by the SDK, in seconds. */
|
|
1063
|
+
retryAfterSeconds;
|
|
1064
|
+
/**
|
|
1065
|
+
* Creates a new RetryDelayExceededError.
|
|
1066
|
+
*
|
|
1067
|
+
* @param message - Human-readable description of the refused retry delay.
|
|
1068
|
+
* @param options - Refused delay, deadline budget, and original failure.
|
|
1069
|
+
*/
|
|
1070
|
+
constructor(message, options) {
|
|
1071
|
+
super(message, {
|
|
1072
|
+
...options,
|
|
1073
|
+
waitMs: options.retryAfterMs,
|
|
1074
|
+
waitReason: "retry-delay"
|
|
1075
|
+
});
|
|
1076
|
+
this.retryAfterMs = options.retryAfterMs;
|
|
1077
|
+
this.retryAfterSeconds = options.retryAfterMs / 1e3;
|
|
1078
|
+
}
|
|
1079
|
+
};
|
|
1080
|
+
//#endregion
|
|
914
1081
|
//#region src/internal/utils/find-error-code.ts
|
|
915
1082
|
/**
|
|
916
1083
|
* Maximum cause-chain depth walked by {@link findErrorCode}. Caps pathological
|
|
@@ -1317,6 +1484,6 @@ function mergeConfig(clientConfig, { methodDefaults, methodKind, requestOptions
|
|
|
1317
1484
|
}
|
|
1318
1485
|
}
|
|
1319
1486
|
//#endregion
|
|
1320
|
-
export {
|
|
1487
|
+
export { ABORTED as _, TRANSIENT_TRANSPORT_CODES as a, RequestAbortedError as b, defaultRetryDelay as c, findErrorCode as d, RetryDelayExceededError as f, isUploadRequest as g, createFetchHttpClient as h, RESPONSE_UNPARSEABLE as i, mergeConfig as l, PermissionError as m, GATEWAY_REJECTED as n, UPLOAD_METHOD_DEFAULTS as o, RequestDeadlineExceededError as p, IDEMPOTENT_METHOD_DEFAULTS as r, computeRetryWaitMs as s, CREATE_METHOD_DEFAULTS as t, shouldRetry as u, raceWithAbortAsync as v, parseRateLimitHeaders as x, requestAbortedError as y };
|
|
1321
1488
|
|
|
1322
|
-
//# sourceMappingURL=retry-
|
|
1489
|
+
//# sourceMappingURL=retry-vpHMIwaU.mjs.map
|