@gusnips/sdkgen 0.2.1 → 0.2.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 +6 -1
- package/dist/transport.d.ts +12 -5
- package/dist/transport.d.ts.map +1 -1
- package/dist/transport.js +23 -4
- package/dist/transport.js.map +1 -1
- package/package.json +1 -1
- package/src/transport.test.ts +55 -0
- package/src/transport.ts +40 -11
package/README.md
CHANGED
|
@@ -192,7 +192,7 @@ export class Example extends GeneratedOperations {
|
|
|
192
192
|
| `baseUrl` | required | Where the API lives, with its base path. |
|
|
193
193
|
| `error(failure)` | required | Builds your SDK's error. The transport throws what it returns. |
|
|
194
194
|
| `headers` | none | Sent on every call. |
|
|
195
|
-
| `fetch` | global |
|
|
195
|
+
| `fetch` | global | `(url, init) => Promise<Response>`, such as a fake one in tests. |
|
|
196
196
|
| `timeoutMs(spec, params)` | 30,000 ms | How long one try waits for an answer. A call's `opts.timeoutMs` wins. |
|
|
197
197
|
| `maxRetries` | 2 | Extra tries after a failure worth repeating. |
|
|
198
198
|
| `durableCodes` | none | Error codes that waiting does not fix, such as a spent monthly quota. |
|
|
@@ -215,6 +215,11 @@ A failed call is tried again:
|
|
|
215
215
|
It waits what the `Retry-After` header says, in seconds or as a date, then what
|
|
216
216
|
`details.retryAfterSecs` says. With neither, it waits about 1 second, then 2.
|
|
217
217
|
|
|
218
|
+
Every method's last argument takes `timeoutMs` for that one call, and `signal` to stop it. A call
|
|
219
|
+
that reads an `Idempotency-Key` also takes `idempotencyKey`. A call stopped by its `signal` throws
|
|
220
|
+
the signal's reason rather than your SDK's error, because nothing failed, and it is not tried
|
|
221
|
+
again, even partway through a wait. `signal` needs `AbortSignal.any`, which Node has from 18.17 and 20.3.
|
|
222
|
+
|
|
218
223
|
## Keep the SDK current
|
|
219
224
|
|
|
220
225
|
```ts
|
package/dist/transport.d.ts
CHANGED
|
@@ -1,7 +1,6 @@
|
|
|
1
|
-
export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
|
|
2
1
|
/** What a generated method tells the transport about its operation. */
|
|
3
2
|
export interface RequestSpec {
|
|
4
|
-
method:
|
|
3
|
+
method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
|
|
5
4
|
/** `/numbers/:numberId/pair`. Each `:name` is filled from the params field of that name. */
|
|
6
5
|
path: string;
|
|
7
6
|
/** The operation reads an `Idempotency-Key`, so the server answers a repeat from the first run. */
|
|
@@ -18,6 +17,11 @@ export interface RequestOptions {
|
|
|
18
17
|
idempotencyKey?: string;
|
|
19
18
|
/** How long one attempt waits for an answer, in milliseconds. Overrides the SDK's. */
|
|
20
19
|
timeoutMs?: number;
|
|
20
|
+
/**
|
|
21
|
+
* Stops the call, and any retry of it, when it aborts. The call then throws the signal's reason
|
|
22
|
+
* rather than the SDK's error, because nothing failed: you asked it to stop.
|
|
23
|
+
*/
|
|
24
|
+
signal?: AbortSignal;
|
|
21
25
|
}
|
|
22
26
|
/** The `error` of the envelope, as the answer carried it. */
|
|
23
27
|
export interface EnvelopeError {
|
|
@@ -31,7 +35,7 @@ export interface EnvelopeError {
|
|
|
31
35
|
}
|
|
32
36
|
/** A call that did not work, as `error` gets it to build the SDK's own error. */
|
|
33
37
|
export interface Failure {
|
|
34
|
-
method:
|
|
38
|
+
method: RequestSpec["method"];
|
|
35
39
|
/** The path with its values filled in: `/numbers/n_1/pair`. */
|
|
36
40
|
path: string;
|
|
37
41
|
/** The HTTP status, or 0 when no answer came back: offline, a dropped connection, a timeout. */
|
|
@@ -58,8 +62,11 @@ export interface Transport {
|
|
|
58
62
|
baseUrl: string;
|
|
59
63
|
/** Sent on every call, such as the credential and the SDK's version. */
|
|
60
64
|
headers?: Readonly<Record<string, string>>;
|
|
61
|
-
/**
|
|
62
|
-
|
|
65
|
+
/**
|
|
66
|
+
* Default: the global `fetch`. Typed as the one way the transport calls it, so a test's fake
|
|
67
|
+
* needs no cast.
|
|
68
|
+
*/
|
|
69
|
+
fetch?: (url: string, init: RequestInit) => Promise<Response>;
|
|
63
70
|
/** How long one attempt of this call waits for an answer, in milliseconds. Default 30,000. */
|
|
64
71
|
timeoutMs?: (spec: RequestSpec, params: object) => number;
|
|
65
72
|
/** Extra attempts after a failure the retry rule says is worth repeating. Default 2. */
|
package/dist/transport.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAsBA,MAAM,MAAM,
|
|
1
|
+
{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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"}
|
package/dist/transport.js
CHANGED
|
@@ -43,10 +43,14 @@ export async function send(transport, spec, params = {}, opts = {}) {
|
|
|
43
43
|
// A local, never `transport.fetch(...)`: called as a method, a browser's fetch gets the
|
|
44
44
|
// settings object as `this` and throws "Illegal invocation".
|
|
45
45
|
const fetchImpl = transport.fetch ?? globalThis.fetch;
|
|
46
|
+
const { signal } = opts;
|
|
47
|
+
signal?.throwIfAborted();
|
|
46
48
|
for (let attempt = 0;; attempt++) {
|
|
47
|
-
const outcome = await once(fetchImpl, request, timeoutMs);
|
|
49
|
+
const outcome = await once(fetchImpl, request, timeoutMs, signal);
|
|
48
50
|
if (outcome.ok)
|
|
49
51
|
return outcome.answer;
|
|
52
|
+
// The caller stopped it, so there is nothing to report and nothing to retry.
|
|
53
|
+
signal?.throwIfAborted();
|
|
50
54
|
const failure = { ...outcome.failure, idempotencyKey: key };
|
|
51
55
|
// The rule reads these fields as the answer sent them: the header's wait apart from the
|
|
52
56
|
// body's, and `details` untouched, so an explicit `retryAfterSecs: null` still says never.
|
|
@@ -60,9 +64,23 @@ export async function send(transport, spec, params = {}, opts = {}) {
|
|
|
60
64
|
shouldRetry(answer, { repeatable, durableCodes: transport.durableCodes });
|
|
61
65
|
if (!again)
|
|
62
66
|
throw transport.error(failure);
|
|
63
|
-
await
|
|
67
|
+
await sleep(retryDelayMs(attempt, answer), signal);
|
|
64
68
|
}
|
|
65
69
|
}
|
|
70
|
+
/** Waits `ms`, or rejects with the signal's reason the moment it aborts. */
|
|
71
|
+
function sleep(ms, signal) {
|
|
72
|
+
return new Promise((resolve, reject) => {
|
|
73
|
+
const timer = setTimeout(() => {
|
|
74
|
+
signal?.removeEventListener("abort", stop);
|
|
75
|
+
resolve();
|
|
76
|
+
}, ms);
|
|
77
|
+
function stop() {
|
|
78
|
+
clearTimeout(timer);
|
|
79
|
+
reject(signal?.reason);
|
|
80
|
+
}
|
|
81
|
+
signal?.addEventListener("abort", stop, { once: true });
|
|
82
|
+
});
|
|
83
|
+
}
|
|
66
84
|
/** The request every attempt sends: the path filled in, the rest in the query or the body. */
|
|
67
85
|
function prepare(transport, spec, params, key) {
|
|
68
86
|
const values = new Map(Object.entries(params));
|
|
@@ -108,7 +126,8 @@ function prepare(transport, spec, params, key) {
|
|
|
108
126
|
};
|
|
109
127
|
}
|
|
110
128
|
/** One attempt. Never throws: a failure is a value, so the loop can ask the rule about it. */
|
|
111
|
-
async function once(fetchImpl, request, timeoutMs) {
|
|
129
|
+
async function once(fetchImpl, request, timeoutMs, signal) {
|
|
130
|
+
const timeout = AbortSignal.timeout(timeoutMs);
|
|
112
131
|
const base = { method: request.method, path: request.path, timeoutMs };
|
|
113
132
|
let response;
|
|
114
133
|
let text;
|
|
@@ -117,7 +136,7 @@ async function once(fetchImpl, request, timeoutMs) {
|
|
|
117
136
|
method: request.method,
|
|
118
137
|
headers: request.headers,
|
|
119
138
|
body: request.body,
|
|
120
|
-
signal: AbortSignal.timeout
|
|
139
|
+
signal: signal === undefined ? timeout : AbortSignal.any([signal, timeout]),
|
|
121
140
|
});
|
|
122
141
|
// Inside the try: a connection that drops halfway through the body is no answer either.
|
|
123
142
|
text = await response.text();
|
package/dist/transport.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;
|
|
1
|
+
{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gusnips/sdkgen",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.3",
|
|
4
4
|
"description": "The pieces of an SDK generator: copy your API's types with their comments, write a schema as a TypeScript type, and keep the output current.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
package/src/transport.test.ts
CHANGED
|
@@ -424,3 +424,58 @@ describe("send: the answer", () => {
|
|
|
424
424
|
});
|
|
425
425
|
});
|
|
426
426
|
});
|
|
427
|
+
|
|
428
|
+
describe("send: the caller's signal", () => {
|
|
429
|
+
const reason = new Error("The reader closed the page.");
|
|
430
|
+
|
|
431
|
+
it("sends nothing when the signal has already aborted, and throws its reason", async () => {
|
|
432
|
+
const controller = new AbortController();
|
|
433
|
+
controller.abort(reason);
|
|
434
|
+
const { calls, outcome } = await call(GET, [ok({})], { opts: { signal: controller.signal } });
|
|
435
|
+
expect(calls).toHaveLength(0);
|
|
436
|
+
expect(outcome).toEqual({ ok: false, error: reason });
|
|
437
|
+
});
|
|
438
|
+
|
|
439
|
+
it("stops a call that is out, throws the reason rather than the SDK's error, and never retries", async () => {
|
|
440
|
+
const controller = new AbortController();
|
|
441
|
+
let sent = 0;
|
|
442
|
+
// A fetch as the transport calls it: two arguments, no cast.
|
|
443
|
+
const fetch = (_url: string, init: RequestInit) => {
|
|
444
|
+
sent++;
|
|
445
|
+
return new Promise<Response>((_resolve, reject) => {
|
|
446
|
+
init.signal?.addEventListener("abort", () => reject(init.signal?.reason));
|
|
447
|
+
controller.abort(reason);
|
|
448
|
+
});
|
|
449
|
+
};
|
|
450
|
+
const { outcome } = await call(GET, [ok({})], {
|
|
451
|
+
opts: { signal: controller.signal },
|
|
452
|
+
transport: { fetch },
|
|
453
|
+
});
|
|
454
|
+
expect(outcome).toEqual({ ok: false, error: reason });
|
|
455
|
+
expect(sent).toBe(1);
|
|
456
|
+
});
|
|
457
|
+
|
|
458
|
+
it("stops during the wait before a retry, without waiting it out", async () => {
|
|
459
|
+
const controller = new AbortController();
|
|
460
|
+
const start = Date.now();
|
|
461
|
+
const unavailable: Reply = () => {
|
|
462
|
+
setTimeout(() => controller.abort(reason), 100);
|
|
463
|
+
return refuse(503)();
|
|
464
|
+
};
|
|
465
|
+
const { calls, outcome } = await call(GET, [unavailable, ok({})], {
|
|
466
|
+
opts: { signal: controller.signal },
|
|
467
|
+
});
|
|
468
|
+
expect(outcome).toEqual({ ok: false, error: reason });
|
|
469
|
+
expect(calls).toHaveLength(1);
|
|
470
|
+
expect(Date.now() - start).toBe(100);
|
|
471
|
+
});
|
|
472
|
+
|
|
473
|
+
it("still times an attempt out, and reports it as the SDK's error", async () => {
|
|
474
|
+
const controller = new AbortController();
|
|
475
|
+
const timeout: Reply = () => {
|
|
476
|
+
throw new DOMException("The operation timed out.", "TimeoutError");
|
|
477
|
+
};
|
|
478
|
+
const { outcome } = await call(WRITE, [timeout], { opts: { signal: controller.signal } });
|
|
479
|
+
expect(failureOf(outcome)).toMatchObject({ status: 0, timedOut: true });
|
|
480
|
+
});
|
|
481
|
+
});
|
package/src/transport.ts
CHANGED
|
@@ -20,11 +20,11 @@
|
|
|
20
20
|
*/
|
|
21
21
|
import { parseRetryAfter, retryDelayMs, shouldRetry } from "@gusnips/http/retry";
|
|
22
22
|
|
|
23
|
-
export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
|
|
24
|
-
|
|
25
23
|
/** What a generated method tells the transport about its operation. */
|
|
26
24
|
export interface RequestSpec {
|
|
27
|
-
|
|
25
|
+
// Spelled out rather than named: an SDK re-exports these types, not the transport, so a named
|
|
26
|
+
// alias would leave its public types naming something nobody can import.
|
|
27
|
+
method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
|
|
28
28
|
/** `/numbers/:numberId/pair`. Each `:name` is filled from the params field of that name. */
|
|
29
29
|
path: string;
|
|
30
30
|
/** The operation reads an `Idempotency-Key`, so the server answers a repeat from the first run. */
|
|
@@ -42,6 +42,11 @@ export interface RequestOptions {
|
|
|
42
42
|
idempotencyKey?: string;
|
|
43
43
|
/** How long one attempt waits for an answer, in milliseconds. Overrides the SDK's. */
|
|
44
44
|
timeoutMs?: number;
|
|
45
|
+
/**
|
|
46
|
+
* Stops the call, and any retry of it, when it aborts. The call then throws the signal's reason
|
|
47
|
+
* rather than the SDK's error, because nothing failed: you asked it to stop.
|
|
48
|
+
*/
|
|
49
|
+
signal?: AbortSignal;
|
|
45
50
|
}
|
|
46
51
|
|
|
47
52
|
/** The `error` of the envelope, as the answer carried it. */
|
|
@@ -57,7 +62,7 @@ export interface EnvelopeError {
|
|
|
57
62
|
|
|
58
63
|
/** A call that did not work, as `error` gets it to build the SDK's own error. */
|
|
59
64
|
export interface Failure {
|
|
60
|
-
method:
|
|
65
|
+
method: RequestSpec["method"];
|
|
61
66
|
/** The path with its values filled in: `/numbers/n_1/pair`. */
|
|
62
67
|
path: string;
|
|
63
68
|
/** The HTTP status, or 0 when no answer came back: offline, a dropped connection, a timeout. */
|
|
@@ -85,8 +90,11 @@ export interface Transport {
|
|
|
85
90
|
baseUrl: string;
|
|
86
91
|
/** Sent on every call, such as the credential and the SDK's version. */
|
|
87
92
|
headers?: Readonly<Record<string, string>>;
|
|
88
|
-
/**
|
|
89
|
-
|
|
93
|
+
/**
|
|
94
|
+
* Default: the global `fetch`. Typed as the one way the transport calls it, so a test's fake
|
|
95
|
+
* needs no cast.
|
|
96
|
+
*/
|
|
97
|
+
fetch?: (url: string, init: RequestInit) => Promise<Response>;
|
|
90
98
|
/** How long one attempt of this call waits for an answer, in milliseconds. Default 30,000. */
|
|
91
99
|
timeoutMs?: (spec: RequestSpec, params: object) => number;
|
|
92
100
|
/** Extra attempts after a failure the retry rule says is worth repeating. Default 2. */
|
|
@@ -140,10 +148,14 @@ export async function send<T = unknown, M = unknown>(
|
|
|
140
148
|
// A local, never `transport.fetch(...)`: called as a method, a browser's fetch gets the
|
|
141
149
|
// settings object as `this` and throws "Illegal invocation".
|
|
142
150
|
const fetchImpl = transport.fetch ?? globalThis.fetch;
|
|
151
|
+
const { signal } = opts;
|
|
152
|
+
signal?.throwIfAborted();
|
|
143
153
|
|
|
144
154
|
for (let attempt = 0; ; attempt++) {
|
|
145
|
-
const outcome = await once<T, M>(fetchImpl, request, timeoutMs);
|
|
155
|
+
const outcome = await once<T, M>(fetchImpl, request, timeoutMs, signal);
|
|
146
156
|
if (outcome.ok) return outcome.answer;
|
|
157
|
+
// The caller stopped it, so there is nothing to report and nothing to retry.
|
|
158
|
+
signal?.throwIfAborted();
|
|
147
159
|
const failure: Failure = { ...outcome.failure, idempotencyKey: key };
|
|
148
160
|
// The rule reads these fields as the answer sent them: the header's wait apart from the
|
|
149
161
|
// body's, and `details` untouched, so an explicit `retryAfterSecs: null` still says never.
|
|
@@ -157,12 +169,27 @@ export async function send<T = unknown, M = unknown>(
|
|
|
157
169
|
attempt < maxRetries &&
|
|
158
170
|
shouldRetry(answer, { repeatable, durableCodes: transport.durableCodes });
|
|
159
171
|
if (!again) throw transport.error(failure);
|
|
160
|
-
await
|
|
172
|
+
await sleep(retryDelayMs(attempt, answer), signal);
|
|
161
173
|
}
|
|
162
174
|
}
|
|
163
175
|
|
|
176
|
+
/** Waits `ms`, or rejects with the signal's reason the moment it aborts. */
|
|
177
|
+
function sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {
|
|
178
|
+
return new Promise((resolve, reject) => {
|
|
179
|
+
const timer = setTimeout(() => {
|
|
180
|
+
signal?.removeEventListener("abort", stop);
|
|
181
|
+
resolve();
|
|
182
|
+
}, ms);
|
|
183
|
+
function stop() {
|
|
184
|
+
clearTimeout(timer);
|
|
185
|
+
reject(signal?.reason);
|
|
186
|
+
}
|
|
187
|
+
signal?.addEventListener("abort", stop, { once: true });
|
|
188
|
+
});
|
|
189
|
+
}
|
|
190
|
+
|
|
164
191
|
interface Prepared {
|
|
165
|
-
method:
|
|
192
|
+
method: RequestSpec["method"];
|
|
166
193
|
path: string;
|
|
167
194
|
url: string;
|
|
168
195
|
headers: Headers;
|
|
@@ -223,10 +250,12 @@ function prepare(
|
|
|
223
250
|
|
|
224
251
|
/** One attempt. Never throws: a failure is a value, so the loop can ask the rule about it. */
|
|
225
252
|
async function once<T, M>(
|
|
226
|
-
fetchImpl:
|
|
253
|
+
fetchImpl: NonNullable<Transport["fetch"]>,
|
|
227
254
|
request: Prepared,
|
|
228
255
|
timeoutMs: number,
|
|
256
|
+
signal: AbortSignal | undefined,
|
|
229
257
|
): Promise<Outcome<T, M>> {
|
|
258
|
+
const timeout = AbortSignal.timeout(timeoutMs);
|
|
230
259
|
const base = { method: request.method, path: request.path, timeoutMs };
|
|
231
260
|
let response: Response;
|
|
232
261
|
let text: string;
|
|
@@ -235,7 +264,7 @@ async function once<T, M>(
|
|
|
235
264
|
method: request.method,
|
|
236
265
|
headers: request.headers,
|
|
237
266
|
body: request.body,
|
|
238
|
-
signal: AbortSignal.timeout
|
|
267
|
+
signal: signal === undefined ? timeout : AbortSignal.any([signal, timeout]),
|
|
239
268
|
});
|
|
240
269
|
// Inside the try: a connection that drops halfway through the body is no answer either.
|
|
241
270
|
text = await response.text();
|