@wats/graph 0.3.29 → 0.3.30
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/rateLimiter.d.ts +22 -0
- package/dist/rateLimiter.js +75 -0
- package/dist/reliableTransport.d.ts +20 -0
- package/dist/reliableTransport.js +52 -11
- package/package.json +2 -2
package/dist/index.d.ts
CHANGED
|
@@ -17,6 +17,7 @@ export { WABAClient, validateWABAClientConfig } from "./subclients/wabaClient.js
|
|
|
17
17
|
export type { WABAClientConfig } from "./subclients/wabaClient.js";
|
|
18
18
|
export * from "./transport.js";
|
|
19
19
|
export * from "./reliableTransport.js";
|
|
20
|
+
export * from "./rateLimiter.js";
|
|
20
21
|
export { createFetchTransport } from "./createFetchTransport.js";
|
|
21
22
|
export type { CreateFetchTransportOptions } from "./createFetchTransport.js";
|
|
22
23
|
export { paginate, paginateAll, PaginationError } from "./pagination.js";
|
package/dist/index.js
CHANGED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
export interface RateLimiter {
|
|
2
|
+
/**
|
|
3
|
+
* Wait until `cost` tokens are available, then deduct them. Resolves once
|
|
4
|
+
* the request is admitted; never rejects unless the injected sleep does.
|
|
5
|
+
*/
|
|
6
|
+
acquire(cost?: number): Promise<void>;
|
|
7
|
+
/**
|
|
8
|
+
* Non-blocking admission check. Refills the bucket to the current virtual
|
|
9
|
+
* time, then if `cost` tokens are available deducts them and returns true;
|
|
10
|
+
* otherwise returns false without deducting.
|
|
11
|
+
*/
|
|
12
|
+
tryAcquire(cost?: number): boolean;
|
|
13
|
+
}
|
|
14
|
+
export interface CreateTokenBucketRateLimiterOptions {
|
|
15
|
+
readonly capacity: number;
|
|
16
|
+
readonly refillPerSecond: number;
|
|
17
|
+
/** Injectable clock returning epoch milliseconds. Defaults to Date.now. */
|
|
18
|
+
readonly now?: () => number;
|
|
19
|
+
/** Injectable sleep for the wait path. Defaults to setTimeout-based sleep. */
|
|
20
|
+
readonly sleep?: (delayMs: number) => Promise<void>;
|
|
21
|
+
}
|
|
22
|
+
export declare function createTokenBucketRateLimiter(options: CreateTokenBucketRateLimiterOptions): RateLimiter;
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
const MAX_CAPACITY = 1e4;
|
|
2
|
+
function defaultSleep(delayMs) {
|
|
3
|
+
return new Promise((resolve) => setTimeout(resolve, delayMs));
|
|
4
|
+
}
|
|
5
|
+
function assertCapacity(value) {
|
|
6
|
+
if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > 1e4) {
|
|
7
|
+
throw new Error("CreateTokenBucketRateLimiterOptions: capacity must be an integer in [1, 10000].");
|
|
8
|
+
}
|
|
9
|
+
return value;
|
|
10
|
+
}
|
|
11
|
+
function assertRefillPerSecond(value) {
|
|
12
|
+
if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
|
|
13
|
+
throw new Error("CreateTokenBucketRateLimiterOptions: refillPerSecond must be a finite number > 0.");
|
|
14
|
+
}
|
|
15
|
+
return value;
|
|
16
|
+
}
|
|
17
|
+
export function createTokenBucketRateLimiter(options) {
|
|
18
|
+
if (options === null || typeof options !== "object") {
|
|
19
|
+
throw new Error("CreateTokenBucketRateLimiterOptions: options must be an object.");
|
|
20
|
+
}
|
|
21
|
+
const capacity = assertCapacity(options.capacity);
|
|
22
|
+
const refillPerSecond = assertRefillPerSecond(options.refillPerSecond);
|
|
23
|
+
if (options.now !== undefined && typeof options.now !== "function") {
|
|
24
|
+
throw new Error("CreateTokenBucketRateLimiterOptions: now must be a function.");
|
|
25
|
+
}
|
|
26
|
+
if (options.sleep !== undefined && typeof options.sleep !== "function") {
|
|
27
|
+
throw new Error("CreateTokenBucketRateLimiterOptions: sleep must be a function.");
|
|
28
|
+
}
|
|
29
|
+
const now = options.now ?? (() => Date.now());
|
|
30
|
+
const sleep = options.sleep ?? defaultSleep;
|
|
31
|
+
let tokens = capacity;
|
|
32
|
+
let lastRefillMs = now();
|
|
33
|
+
function assertCost(cost) {
|
|
34
|
+
const c = cost ?? 1;
|
|
35
|
+
if (typeof c !== "number" || !Number.isInteger(c) || c < 1 || c > capacity) {
|
|
36
|
+
throw new Error(`RateLimiter: cost must be an integer in [1, ${capacity}] (the bucket capacity).`);
|
|
37
|
+
}
|
|
38
|
+
return c;
|
|
39
|
+
}
|
|
40
|
+
function refill() {
|
|
41
|
+
const currentMs = now();
|
|
42
|
+
const elapsedMs = currentMs - lastRefillMs;
|
|
43
|
+
if (elapsedMs > 0) {
|
|
44
|
+
const added = elapsedMs / 1000 * refillPerSecond;
|
|
45
|
+
tokens = Math.min(capacity, tokens + added);
|
|
46
|
+
lastRefillMs = currentMs;
|
|
47
|
+
} else if (elapsedMs < 0) {
|
|
48
|
+
lastRefillMs = currentMs;
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
return {
|
|
52
|
+
async acquire(cost) {
|
|
53
|
+
const c = assertCost(cost);
|
|
54
|
+
for (;; ) {
|
|
55
|
+
refill();
|
|
56
|
+
if (tokens >= c) {
|
|
57
|
+
tokens -= c;
|
|
58
|
+
return;
|
|
59
|
+
}
|
|
60
|
+
const deficit = c - tokens;
|
|
61
|
+
const waitMs = deficit / refillPerSecond * 1000;
|
|
62
|
+
await sleep(Math.max(0, waitMs));
|
|
63
|
+
}
|
|
64
|
+
},
|
|
65
|
+
tryAcquire(cost) {
|
|
66
|
+
const c = assertCost(cost);
|
|
67
|
+
refill();
|
|
68
|
+
if (tokens >= c) {
|
|
69
|
+
tokens -= c;
|
|
70
|
+
return true;
|
|
71
|
+
}
|
|
72
|
+
return false;
|
|
73
|
+
}
|
|
74
|
+
};
|
|
75
|
+
}
|
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
import type { Transport, TransportRequest, TransportResponse, TransportRetryPolicy } from "./transport.js";
|
|
2
|
+
import type { RateLimiter } from "./rateLimiter.js";
|
|
2
3
|
export interface ReliableTransportRetryContext {
|
|
3
4
|
readonly attempt: number;
|
|
4
5
|
readonly request: TransportRequest;
|
|
5
6
|
readonly response?: TransportResponse;
|
|
6
7
|
readonly error?: unknown;
|
|
7
8
|
}
|
|
9
|
+
export type RetryPostMode = "never" | "network-only" | "always";
|
|
8
10
|
export interface ReliableTransportOptions extends Partial<TransportRetryPolicy> {
|
|
9
11
|
readonly timeoutMs?: number;
|
|
10
12
|
readonly retryOn?: (ctx: ReliableTransportRetryContext) => boolean;
|
|
@@ -13,5 +15,23 @@ export interface ReliableTransportOptions extends Partial<TransportRetryPolicy>
|
|
|
13
15
|
}) => void | Promise<void>;
|
|
14
16
|
readonly sleep?: (delayMs: number) => Promise<void>;
|
|
15
17
|
readonly random?: () => number;
|
|
18
|
+
/**
|
|
19
|
+
* Controls retry of non-idempotent POST requests. Default "never" preserves
|
|
20
|
+
* the historical behavior: POST is retried only on 429 (the rate-limit
|
|
21
|
+
* exception), never on 5xx or network errors.
|
|
22
|
+
*
|
|
23
|
+
* - "network-only": additionally retry a POST whose request threw a
|
|
24
|
+
* GraphNetworkError BEFORE any response arrived, but only when the request
|
|
25
|
+
* carries an Idempotency-Key header (case-insensitive). A pre-response
|
|
26
|
+
* network failure is the one POST failure shape that cannot have been
|
|
27
|
+
* processed by the server, so an idempotency key makes the retry safe.
|
|
28
|
+
* POST 5xx is still not retried — the server may have side-effected.
|
|
29
|
+
* - "always": additionally retry POST on 5xx. Requires server-side
|
|
30
|
+
* idempotency for the endpoint; a 5xx after the server began processing
|
|
31
|
+
* can otherwise duplicate a send. Use only for endpoints you have
|
|
32
|
+
* verified are idempotent or dedupe by Idempotency-Key.
|
|
33
|
+
*/
|
|
34
|
+
readonly retryPosts?: RetryPostMode;
|
|
35
|
+
readonly rateLimiter?: RateLimiter;
|
|
16
36
|
}
|
|
17
37
|
export declare function createReliableTransport(inner: Transport, options?: ReliableTransportOptions): Transport;
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { GraphNetworkError } from "./errors.js";
|
|
2
2
|
import { DEFAULT_TRANSPORT_RETRY_POLICY } from "./transport.js";
|
|
3
|
+
const VALID_RETRY_POST_MODES = ["never", "network-only", "always"];
|
|
3
4
|
function assertFiniteNumber(value, name, min) {
|
|
4
5
|
if (typeof value !== "number" || !Number.isFinite(value) || value < min) {
|
|
5
6
|
throw new Error(`ReliableTransportOptions: ${name} must be a finite number >= ${min}.`);
|
|
@@ -33,6 +34,16 @@ function resolvePolicy(options) {
|
|
|
33
34
|
throw new Error("ReliableTransportOptions: sleep must be a function.");
|
|
34
35
|
if (options?.random !== undefined && typeof options.random !== "function")
|
|
35
36
|
throw new Error("ReliableTransportOptions: random must be a function.");
|
|
37
|
+
const retryPosts = resolveRetryPostMode(options?.retryPosts);
|
|
38
|
+
if (options?.rateLimiter !== undefined) {
|
|
39
|
+
const rl = options.rateLimiter;
|
|
40
|
+
if (rl === null || typeof rl !== "object" || typeof rl.acquire !== "function") {
|
|
41
|
+
throw new Error("ReliableTransportOptions: rateLimiter must be an object with an acquire(cost?) => Promise<void> method.");
|
|
42
|
+
}
|
|
43
|
+
if (typeof rl.tryAcquire !== "function") {
|
|
44
|
+
throw new Error("ReliableTransportOptions: rateLimiter must also implement tryAcquire(cost?) => boolean.");
|
|
45
|
+
}
|
|
46
|
+
}
|
|
36
47
|
return {
|
|
37
48
|
retries,
|
|
38
49
|
baseDelayMs,
|
|
@@ -42,21 +53,47 @@ function resolvePolicy(options) {
|
|
|
42
53
|
...options?.retryOn !== undefined ? { retryOn: options.retryOn } : {},
|
|
43
54
|
...options?.onRetry !== undefined ? { onRetry: options.onRetry } : {},
|
|
44
55
|
sleep: options?.sleep ?? defaultSleep,
|
|
45
|
-
random: options?.random ?? Math.random
|
|
56
|
+
random: options?.random ?? Math.random,
|
|
57
|
+
retryPosts,
|
|
58
|
+
...options?.rateLimiter !== undefined ? { rateLimiter: options.rateLimiter } : {}
|
|
46
59
|
};
|
|
47
60
|
}
|
|
61
|
+
function resolveRetryPostMode(value) {
|
|
62
|
+
if (value === undefined)
|
|
63
|
+
return "never";
|
|
64
|
+
if (typeof value !== "string" || !VALID_RETRY_POST_MODES.includes(value)) {
|
|
65
|
+
throw new Error(`ReliableTransportOptions: retryPosts must be one of ${VALID_RETRY_POST_MODES.map((m) => `"${m}"`).join(", ")} (got ${value === undefined ? "undefined" : JSON.stringify(value)}).`);
|
|
66
|
+
}
|
|
67
|
+
return value;
|
|
68
|
+
}
|
|
48
69
|
function isRetryableMethod(method) {
|
|
49
70
|
return method === "GET" || method === "DELETE";
|
|
50
71
|
}
|
|
51
|
-
function
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
72
|
+
function hasIdempotencyKey(req) {
|
|
73
|
+
return req.headers.has("idempotency-key");
|
|
74
|
+
}
|
|
75
|
+
function makeDefaultRetryOn(retryPosts) {
|
|
76
|
+
return (ctx) => {
|
|
77
|
+
const status = ctx.response?.status;
|
|
78
|
+
if (status === 429)
|
|
79
|
+
return true;
|
|
80
|
+
const method = ctx.request.method;
|
|
81
|
+
const retryableMethod = isRetryableMethod(method);
|
|
82
|
+
const is5xx = typeof status === "number" && status >= 500 && status < 600;
|
|
83
|
+
if (ctx.error instanceof GraphNetworkError) {
|
|
84
|
+
if (retryableMethod)
|
|
85
|
+
return true;
|
|
86
|
+
if (method === "POST" && retryPosts !== "never") {
|
|
87
|
+
return hasIdempotencyKey(ctx.request);
|
|
88
|
+
}
|
|
89
|
+
return false;
|
|
90
|
+
}
|
|
91
|
+
if (retryableMethod)
|
|
92
|
+
return is5xx;
|
|
93
|
+
if (method === "POST" && retryPosts === "always")
|
|
94
|
+
return is5xx;
|
|
56
95
|
return false;
|
|
57
|
-
|
|
58
|
-
return true;
|
|
59
|
-
return typeof status === "number" && status >= 500 && status < 600;
|
|
96
|
+
};
|
|
60
97
|
}
|
|
61
98
|
function parseRetryAfterMs(header, nowMs) {
|
|
62
99
|
if (header === null)
|
|
@@ -140,16 +177,20 @@ export function createReliableTransport(inner, options) {
|
|
|
140
177
|
return {
|
|
141
178
|
async request(req, opts) {
|
|
142
179
|
const policy = resolvePolicy(options);
|
|
180
|
+
const retryOn = policy.retryOn ?? makeDefaultRetryOn(policy.retryPosts);
|
|
143
181
|
let attempt = 0;
|
|
144
182
|
for (;; ) {
|
|
145
183
|
throwIfAborted(opts?.signal);
|
|
184
|
+
if (policy.rateLimiter !== undefined) {
|
|
185
|
+
await policy.rateLimiter.acquire();
|
|
186
|
+
}
|
|
146
187
|
attempt += 1;
|
|
147
188
|
const composedSignal = composeSignal(opts?.signal, policy.timeoutMs);
|
|
148
189
|
const attemptOpts = composedSignal !== undefined ? { signal: composedSignal } : undefined;
|
|
149
190
|
try {
|
|
150
191
|
const response = await inner.request(req, attemptOpts);
|
|
151
192
|
const ctx = { attempt, request: req, response };
|
|
152
|
-
const shouldRetry =
|
|
193
|
+
const shouldRetry = retryOn(ctx);
|
|
153
194
|
if (!shouldRetry || attempt > policy.retries)
|
|
154
195
|
return response;
|
|
155
196
|
await cancelRetryResponseBody(response);
|
|
@@ -161,7 +202,7 @@ export function createReliableTransport(inner, options) {
|
|
|
161
202
|
if (opts?.signal?.aborted)
|
|
162
203
|
throw error;
|
|
163
204
|
const ctx = { attempt, request: req, error };
|
|
164
|
-
const shouldRetry =
|
|
205
|
+
const shouldRetry = retryOn(ctx);
|
|
165
206
|
if (!shouldRetry || attempt > policy.retries)
|
|
166
207
|
throw error;
|
|
167
208
|
throwIfAborted(opts?.signal);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wats/graph",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.30",
|
|
4
4
|
"private": false,
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -85,6 +85,6 @@
|
|
|
85
85
|
"wats"
|
|
86
86
|
],
|
|
87
87
|
"dependencies": {
|
|
88
|
-
"@wats/crypto": "^0.3.
|
|
88
|
+
"@wats/crypto": "^0.3.30"
|
|
89
89
|
}
|
|
90
90
|
}
|