@yorun-ai/vrpc 0.9.0 → 0.9.2
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 +103 -3
- package/README.zh-CN.md +103 -3
- package/dist/client.cjs +45 -24
- package/dist/client.d.cts +47 -11
- package/dist/client.d.ts +47 -11
- package/dist/client.es.js +41 -25
- package/dist/http.cjs +7 -3
- package/dist/http.d.cts +35 -9
- package/dist/http.d.ts +35 -9
- package/dist/http.es.js +4 -4
- package/dist/{request-options-disym648.js → request-options-Bjy2LvRE.js} +175 -47
- package/dist/{request-options-2HZzkj4w.cjs → request-options-m8_63jpk.cjs} +210 -46
- package/docs/guides/axios.md +43 -21
- package/docs/guides/usage.md +167 -7
- package/docs/maintainers/architecture.md +26 -4
- package/docs/maintainers/protocol.md +16 -1
- package/package.json +1 -1
|
@@ -1,15 +1,68 @@
|
|
|
1
1
|
//#region src/contracts/errors.ts
|
|
2
2
|
var HTTP_TIMEOUT_ERROR_CODE = "HTTP_TIMEOUT";
|
|
3
|
-
var
|
|
3
|
+
var HTTP_ABORT_ERROR_CODE = "HTTP_ABORTED";
|
|
4
|
+
var HTTP_TRANSPORT_ERROR_CODE = "HTTP_TRANSPORT_ERROR";
|
|
5
|
+
var VRPC_PROTOCOL_ERROR_CODE = "VRPC_PROTOCOL_ERROR";
|
|
6
|
+
var HttpClientError = class extends Error {
|
|
7
|
+
isHttpClientError = true;
|
|
8
|
+
kind;
|
|
9
|
+
url;
|
|
10
|
+
method;
|
|
11
|
+
constructor(message, kind, requestMeta = {}, options = {}) {
|
|
12
|
+
super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
|
|
13
|
+
this.name = "HttpClientError";
|
|
14
|
+
this.kind = kind;
|
|
15
|
+
this.url = requestMeta.url || "";
|
|
16
|
+
this.method = requestMeta.method || "GET";
|
|
17
|
+
}
|
|
18
|
+
};
|
|
19
|
+
var HttpTimeoutError = class extends HttpClientError {
|
|
4
20
|
code;
|
|
5
21
|
timeoutMs;
|
|
6
|
-
constructor(timeoutMs) {
|
|
7
|
-
super(`request timeout after ${timeoutMs}ms
|
|
22
|
+
constructor(timeoutMs, requestMeta = {}, options = {}) {
|
|
23
|
+
super(`request timeout after ${timeoutMs}ms`, "timeout", requestMeta, options);
|
|
8
24
|
this.name = "HttpTimeoutError";
|
|
9
25
|
this.code = HTTP_TIMEOUT_ERROR_CODE;
|
|
10
26
|
this.timeoutMs = timeoutMs;
|
|
11
27
|
}
|
|
12
28
|
};
|
|
29
|
+
var HttpAbortError = class extends HttpClientError {
|
|
30
|
+
code;
|
|
31
|
+
reason;
|
|
32
|
+
constructor(requestMeta = {}, options = {}) {
|
|
33
|
+
super("request aborted", "abort", requestMeta, options);
|
|
34
|
+
this.name = "HttpAbortError";
|
|
35
|
+
this.code = HTTP_ABORT_ERROR_CODE;
|
|
36
|
+
this.reason = options.reason;
|
|
37
|
+
}
|
|
38
|
+
};
|
|
39
|
+
var HttpTransportError = class extends HttpClientError {
|
|
40
|
+
code;
|
|
41
|
+
constructor(requestMeta = {}, options = {}) {
|
|
42
|
+
super("network request failed", "transport", requestMeta, options);
|
|
43
|
+
this.name = "HttpTransportError";
|
|
44
|
+
this.code = HTTP_TRANSPORT_ERROR_CODE;
|
|
45
|
+
}
|
|
46
|
+
};
|
|
47
|
+
var VrpcProtocolError = class extends HttpClientError {
|
|
48
|
+
code;
|
|
49
|
+
status;
|
|
50
|
+
statusText;
|
|
51
|
+
responseHeaders;
|
|
52
|
+
vrpcStatus;
|
|
53
|
+
constructor(response, message, requestMeta = {}, options = {}) {
|
|
54
|
+
super(message, "protocol", {
|
|
55
|
+
url: requestMeta.url || response.url || "",
|
|
56
|
+
method: requestMeta.method || "POST"
|
|
57
|
+
}, options);
|
|
58
|
+
this.name = "VrpcProtocolError";
|
|
59
|
+
this.code = VRPC_PROTOCOL_ERROR_CODE;
|
|
60
|
+
this.status = response.status;
|
|
61
|
+
this.statusText = response.statusText;
|
|
62
|
+
this.responseHeaders = response.headers;
|
|
63
|
+
this.vrpcStatus = response.headers.get("vrpc-status");
|
|
64
|
+
}
|
|
65
|
+
};
|
|
13
66
|
function readServerErrorMessage(payload) {
|
|
14
67
|
if (!payload || typeof payload !== "object") return;
|
|
15
68
|
const body = payload;
|
|
@@ -22,7 +75,7 @@ function readServerErrorStringField(payload, field) {
|
|
|
22
75
|
const value = payload[field];
|
|
23
76
|
return typeof value === "string" ? value : void 0;
|
|
24
77
|
}
|
|
25
|
-
var HttpInvokeError = class extends
|
|
78
|
+
var HttpInvokeError = class extends HttpClientError {
|
|
26
79
|
type;
|
|
27
80
|
code;
|
|
28
81
|
reason;
|
|
@@ -31,11 +84,12 @@ var HttpInvokeError = class extends Error {
|
|
|
31
84
|
statusText;
|
|
32
85
|
responseHeaders;
|
|
33
86
|
payload;
|
|
34
|
-
|
|
35
|
-
method;
|
|
36
|
-
constructor(response, payload, requestMeta = {}) {
|
|
87
|
+
constructor(response, payload, requestMeta = {}, options = {}) {
|
|
37
88
|
const message = readServerErrorMessage(payload) || `request failed (status=${response.status})`;
|
|
38
|
-
super(message
|
|
89
|
+
super(message, "invoke", {
|
|
90
|
+
url: requestMeta.url || response.url || "",
|
|
91
|
+
method: requestMeta.method || "GET"
|
|
92
|
+
}, options);
|
|
39
93
|
this.name = "HttpInvokeError";
|
|
40
94
|
this.status = response.status;
|
|
41
95
|
this.statusText = response.statusText;
|
|
@@ -45,19 +99,47 @@ var HttpInvokeError = class extends Error {
|
|
|
45
99
|
this.code = readServerErrorStringField(payload, "code");
|
|
46
100
|
this.reason = readServerErrorStringField(payload, "reason");
|
|
47
101
|
this.detail = readServerErrorStringField(payload, "detail");
|
|
48
|
-
this.url = requestMeta.url || response.url || "";
|
|
49
|
-
this.method = requestMeta.method || "GET";
|
|
50
102
|
}
|
|
51
103
|
};
|
|
52
104
|
var VrpcInvokeError = class extends HttpInvokeError {
|
|
53
105
|
vrpcStatus;
|
|
54
|
-
constructor(response, payload, requestMeta = {}) {
|
|
55
|
-
super(response, payload, requestMeta);
|
|
106
|
+
constructor(response, payload, requestMeta = {}, options = {}) {
|
|
107
|
+
super(response, payload, requestMeta, options);
|
|
56
108
|
this.name = "VrpcInvokeError";
|
|
57
|
-
|
|
58
|
-
this.vrpcStatus = vrpcStatus;
|
|
109
|
+
this.vrpcStatus = response.headers.get("vrpc-status");
|
|
59
110
|
}
|
|
60
111
|
};
|
|
112
|
+
function hasHttpClientErrorBrand(error) {
|
|
113
|
+
return Boolean(error && typeof error === "object" && error.isHttpClientError === true);
|
|
114
|
+
}
|
|
115
|
+
function isHttpError(error) {
|
|
116
|
+
if (!hasHttpClientErrorBrand(error)) return false;
|
|
117
|
+
const candidate = error;
|
|
118
|
+
switch (candidate.kind) {
|
|
119
|
+
case "abort": return candidate.code === HTTP_ABORT_ERROR_CODE;
|
|
120
|
+
case "timeout": return candidate.code === "HTTP_TIMEOUT" && typeof candidate.timeoutMs === "number";
|
|
121
|
+
case "transport": return candidate.code === HTTP_TRANSPORT_ERROR_CODE;
|
|
122
|
+
case "invoke": return typeof candidate.status === "number" && "payload" in candidate;
|
|
123
|
+
default: return false;
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
function isVrpcError(error) {
|
|
127
|
+
if (!hasHttpClientErrorBrand(error)) return false;
|
|
128
|
+
const candidate = error;
|
|
129
|
+
switch (candidate.kind) {
|
|
130
|
+
case "abort": return candidate.code === HTTP_ABORT_ERROR_CODE;
|
|
131
|
+
case "timeout": return candidate.code === "HTTP_TIMEOUT" && typeof candidate.timeoutMs === "number";
|
|
132
|
+
case "transport": return candidate.code === HTTP_TRANSPORT_ERROR_CODE;
|
|
133
|
+
case "protocol": return candidate.code === "VRPC_PROTOCOL_ERROR" && typeof candidate.status === "number";
|
|
134
|
+
case "invoke": return typeof candidate.status === "number" && "vrpcStatus" in candidate;
|
|
135
|
+
default: return false;
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
function isAbortErrorLike(error) {
|
|
139
|
+
if (!error || typeof error !== "object" || error instanceof HttpTimeoutError) return false;
|
|
140
|
+
const candidate = error;
|
|
141
|
+
return candidate.kind === "abort" || candidate.name === "HttpAbortError" || candidate.name === "AbortError" || candidate.code === "HTTP_ABORTED" || candidate.code === "ABORT_ERR" || candidate.code === "ERR_CANCELED" || candidate.__CANCEL__ === true;
|
|
142
|
+
}
|
|
61
143
|
//#endregion
|
|
62
144
|
//#region src/core/http-utils.ts
|
|
63
145
|
var NULL_BODY_STATUS_CODES = /* @__PURE__ */ new Set([
|
|
@@ -73,10 +155,18 @@ function isNullBodyStatus(status) {
|
|
|
73
155
|
function shouldTreatResponseAsBodyless(method, status) {
|
|
74
156
|
return method.toUpperCase() === "HEAD" || isNullBodyStatus(status);
|
|
75
157
|
}
|
|
76
|
-
|
|
158
|
+
var ALLOWED_ABSOLUTE_URL_PROTOCOLS = /* @__PURE__ */ new Set(["http:", "https:"]);
|
|
159
|
+
function buildRequestUrl(prefixUrl, path, { allowAbsoluteUrls = false } = {}) {
|
|
160
|
+
if (/^\s*\/\//.test(path)) throw new Error("Protocol-relative request URLs are not supported.");
|
|
161
|
+
let absoluteUrl;
|
|
77
162
|
try {
|
|
78
|
-
|
|
163
|
+
absoluteUrl = new URL(path);
|
|
79
164
|
} catch {}
|
|
165
|
+
if (absoluteUrl) {
|
|
166
|
+
if (!ALLOWED_ABSOLUTE_URL_PROTOCOLS.has(absoluteUrl.protocol)) throw new Error(`Unsupported absolute request URL protocol: ${absoluteUrl.protocol || "unknown"}`);
|
|
167
|
+
if (!allowAbsoluteUrls) throw new Error("Absolute request URLs are disabled. Set allowAbsoluteUrls: true on createHttpClient() to enable them.");
|
|
168
|
+
return absoluteUrl.toString();
|
|
169
|
+
}
|
|
80
170
|
const base = String(prefixUrl).replace(/\/+$/, "");
|
|
81
171
|
const relativePath = path.replace(/^\/+/, "");
|
|
82
172
|
return relativePath ? `${base}/${relativePath}` : `${base}/`;
|
|
@@ -124,43 +214,56 @@ async function parseResponsePayload(response) {
|
|
|
124
214
|
}
|
|
125
215
|
//#endregion
|
|
126
216
|
//#region src/transports/fetch-transport.ts
|
|
127
|
-
function
|
|
128
|
-
return new HttpTimeoutError(timeoutMs);
|
|
129
|
-
}
|
|
130
|
-
function withTimeoutSignal(timeoutMs, signal) {
|
|
217
|
+
function withTimeoutSignal(timeoutMs, callerSignal, requestMeta) {
|
|
131
218
|
if (!timeoutMs || timeoutMs <= 0) return {
|
|
132
|
-
signal:
|
|
133
|
-
cleanup: () => {}
|
|
219
|
+
signal: callerSignal || void 0,
|
|
220
|
+
cleanup: () => {},
|
|
221
|
+
getAbortSource: () => callerSignal?.aborted ? "caller" : void 0,
|
|
222
|
+
getTimeoutError: () => void 0
|
|
134
223
|
};
|
|
135
224
|
const controller = new AbortController();
|
|
136
|
-
|
|
225
|
+
let abortSource;
|
|
226
|
+
let timeoutError;
|
|
227
|
+
const timer = setTimeout(() => {
|
|
228
|
+
if (controller.signal.aborted) return;
|
|
229
|
+
abortSource = "timeout";
|
|
230
|
+
timeoutError = new HttpTimeoutError(timeoutMs, requestMeta);
|
|
231
|
+
controller.abort(timeoutError);
|
|
232
|
+
}, timeoutMs);
|
|
137
233
|
const clear = () => clearTimeout(timer);
|
|
138
|
-
if (!
|
|
234
|
+
if (!callerSignal) return {
|
|
139
235
|
signal: controller.signal,
|
|
140
|
-
cleanup: clear
|
|
236
|
+
cleanup: clear,
|
|
237
|
+
getAbortSource: () => abortSource,
|
|
238
|
+
getTimeoutError: () => timeoutError
|
|
141
239
|
};
|
|
142
|
-
|
|
143
|
-
controller.
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
}
|
|
149
|
-
const relayAbort = () => controller.abort(signal.reason);
|
|
150
|
-
signal.addEventListener("abort", relayAbort, { once: true });
|
|
240
|
+
const relayAbort = () => {
|
|
241
|
+
if (controller.signal.aborted) return;
|
|
242
|
+
abortSource = "caller";
|
|
243
|
+
controller.abort(callerSignal.reason);
|
|
244
|
+
};
|
|
245
|
+
if (callerSignal.aborted) relayAbort();
|
|
246
|
+
else callerSignal.addEventListener("abort", relayAbort, { once: true });
|
|
151
247
|
return {
|
|
152
248
|
signal: controller.signal,
|
|
153
249
|
cleanup: () => {
|
|
154
250
|
clear();
|
|
155
|
-
|
|
156
|
-
}
|
|
251
|
+
callerSignal.removeEventListener("abort", relayAbort);
|
|
252
|
+
},
|
|
253
|
+
getAbortSource: () => abortSource,
|
|
254
|
+
getTimeoutError: () => timeoutError
|
|
157
255
|
};
|
|
158
256
|
}
|
|
159
257
|
function createFetchTransport(fetchImpl) {
|
|
160
258
|
const request = fetchImpl || globalThis.fetch;
|
|
161
259
|
if (!request) throw new Error("fetch is not available in current runtime.");
|
|
162
260
|
return { request: async (input) => {
|
|
163
|
-
const
|
|
261
|
+
const requestMeta = {
|
|
262
|
+
url: input.url,
|
|
263
|
+
method: input.method
|
|
264
|
+
};
|
|
265
|
+
const callerSignal = input.init.signal || input.signal;
|
|
266
|
+
const { signal, cleanup, getAbortSource, getTimeoutError } = withTimeoutSignal(input.timeoutMs, callerSignal, requestMeta);
|
|
164
267
|
try {
|
|
165
268
|
const response = await request(input.url, {
|
|
166
269
|
...input.init,
|
|
@@ -178,6 +281,20 @@ function createFetchTransport(fetchImpl) {
|
|
|
178
281
|
body,
|
|
179
282
|
url: response.url || input.url
|
|
180
283
|
};
|
|
284
|
+
} catch (cause) {
|
|
285
|
+
const abortSource = getAbortSource();
|
|
286
|
+
if (abortSource === "timeout") {
|
|
287
|
+
const timeoutError = getTimeoutError();
|
|
288
|
+
if (cause === timeoutError && timeoutError) throw timeoutError;
|
|
289
|
+
throw new HttpTimeoutError(input.timeoutMs, requestMeta, { cause });
|
|
290
|
+
}
|
|
291
|
+
if (abortSource === "caller") throw new HttpAbortError(requestMeta, {
|
|
292
|
+
cause,
|
|
293
|
+
reason: callerSignal?.reason
|
|
294
|
+
});
|
|
295
|
+
if (isHttpError(cause)) throw cause;
|
|
296
|
+
if (isAbortErrorLike(cause)) throw new HttpAbortError(requestMeta, { cause });
|
|
297
|
+
throw new HttpTransportError(requestMeta, { cause });
|
|
181
298
|
} finally {
|
|
182
299
|
cleanup();
|
|
183
300
|
}
|
|
@@ -238,15 +355,26 @@ function createClientCore(options) {
|
|
|
238
355
|
url: context.url
|
|
239
356
|
};
|
|
240
357
|
await validateRequest?.(context, requestMeta);
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
358
|
+
let result;
|
|
359
|
+
try {
|
|
360
|
+
result = await httpTransport.request({
|
|
361
|
+
url: context.url,
|
|
362
|
+
init: context.init,
|
|
363
|
+
method,
|
|
364
|
+
headers,
|
|
365
|
+
body: resolveTransportBody(context.init, prepared.fallbackBody),
|
|
366
|
+
timeoutMs: prepared.timeoutMs,
|
|
367
|
+
signal: context.init.signal
|
|
368
|
+
});
|
|
369
|
+
} catch (cause) {
|
|
370
|
+
if (isHttpError(cause) || isVrpcError(cause)) throw cause;
|
|
371
|
+
if (context.init.signal?.aborted || isAbortErrorLike(cause)) throw new HttpAbortError(requestMeta, {
|
|
372
|
+
cause,
|
|
373
|
+
reason: context.init.signal?.reason
|
|
374
|
+
});
|
|
375
|
+
throw new HttpTransportError(requestMeta, { cause });
|
|
376
|
+
}
|
|
377
|
+
const response = buildResponseFromTransportResult(result);
|
|
250
378
|
const payload = await parseResponse(response, context);
|
|
251
379
|
await runAfterResponseInterceptors(interceptors, response, context);
|
|
252
380
|
await assertResponse(response, payload, context, requestMeta);
|
|
@@ -291,6 +419,18 @@ Object.defineProperty(exports, "HTTP_TIMEOUT_ERROR_CODE", {
|
|
|
291
419
|
return HTTP_TIMEOUT_ERROR_CODE;
|
|
292
420
|
}
|
|
293
421
|
});
|
|
422
|
+
Object.defineProperty(exports, "HttpAbortError", {
|
|
423
|
+
enumerable: true,
|
|
424
|
+
get: function() {
|
|
425
|
+
return HttpAbortError;
|
|
426
|
+
}
|
|
427
|
+
});
|
|
428
|
+
Object.defineProperty(exports, "HttpClientError", {
|
|
429
|
+
enumerable: true,
|
|
430
|
+
get: function() {
|
|
431
|
+
return HttpClientError;
|
|
432
|
+
}
|
|
433
|
+
});
|
|
294
434
|
Object.defineProperty(exports, "HttpInvokeError", {
|
|
295
435
|
enumerable: true,
|
|
296
436
|
get: function() {
|
|
@@ -303,12 +443,24 @@ Object.defineProperty(exports, "HttpTimeoutError", {
|
|
|
303
443
|
return HttpTimeoutError;
|
|
304
444
|
}
|
|
305
445
|
});
|
|
446
|
+
Object.defineProperty(exports, "HttpTransportError", {
|
|
447
|
+
enumerable: true,
|
|
448
|
+
get: function() {
|
|
449
|
+
return HttpTransportError;
|
|
450
|
+
}
|
|
451
|
+
});
|
|
306
452
|
Object.defineProperty(exports, "VrpcInvokeError", {
|
|
307
453
|
enumerable: true,
|
|
308
454
|
get: function() {
|
|
309
455
|
return VrpcInvokeError;
|
|
310
456
|
}
|
|
311
457
|
});
|
|
458
|
+
Object.defineProperty(exports, "VrpcProtocolError", {
|
|
459
|
+
enumerable: true,
|
|
460
|
+
get: function() {
|
|
461
|
+
return VrpcProtocolError;
|
|
462
|
+
}
|
|
463
|
+
});
|
|
312
464
|
Object.defineProperty(exports, "appendQueryToUrl", {
|
|
313
465
|
enumerable: true,
|
|
314
466
|
get: function() {
|
|
@@ -333,6 +485,18 @@ Object.defineProperty(exports, "createFetchTransport", {
|
|
|
333
485
|
return createFetchTransport;
|
|
334
486
|
}
|
|
335
487
|
});
|
|
488
|
+
Object.defineProperty(exports, "isHttpError", {
|
|
489
|
+
enumerable: true,
|
|
490
|
+
get: function() {
|
|
491
|
+
return isHttpError;
|
|
492
|
+
}
|
|
493
|
+
});
|
|
494
|
+
Object.defineProperty(exports, "isVrpcError", {
|
|
495
|
+
enumerable: true,
|
|
496
|
+
get: function() {
|
|
497
|
+
return isVrpcError;
|
|
498
|
+
}
|
|
499
|
+
});
|
|
336
500
|
Object.defineProperty(exports, "mergeHeaders", {
|
|
337
501
|
enumerable: true,
|
|
338
502
|
get: function() {
|
package/docs/guides/axios.md
CHANGED
|
@@ -59,31 +59,52 @@ A runtime transport returns the response body as raw bytes:
|
|
|
59
59
|
|
|
60
60
|
```ts
|
|
61
61
|
import axios from "axios";
|
|
62
|
+
import { HttpAbortError, HttpTimeoutError, HttpTransportError } from "@yorun-ai/vrpc";
|
|
62
63
|
import type { VrpcTransport } from "@yorun-ai/vrpc";
|
|
63
64
|
|
|
64
65
|
export const axiosTransport: VrpcTransport = {
|
|
65
66
|
async request(request) {
|
|
66
|
-
const
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
67
|
+
const requestMeta = { url: request.url, method: request.method };
|
|
68
|
+
try {
|
|
69
|
+
const response = await axios.request<ArrayBuffer>({
|
|
70
|
+
url: request.url,
|
|
71
|
+
method: request.method,
|
|
72
|
+
headers: Object.fromEntries(new Headers(request.headers).entries()),
|
|
73
|
+
data: request.body,
|
|
74
|
+
signal: request.signal ?? undefined,
|
|
75
|
+
timeout: request.timeoutMs,
|
|
76
|
+
withCredentials: request.init.credentials === "include",
|
|
77
|
+
responseType: "arraybuffer",
|
|
78
|
+
validateStatus: () => true,
|
|
79
|
+
});
|
|
80
|
+
|
|
81
|
+
const body = response.data.byteLength ? new Uint8Array(response.data) : null;
|
|
82
|
+
|
|
83
|
+
return {
|
|
84
|
+
status: response.status,
|
|
85
|
+
statusText: response.statusText,
|
|
86
|
+
headers: new Headers(response.headers as Record<string, string>),
|
|
87
|
+
body,
|
|
88
|
+
url: request.url,
|
|
89
|
+
};
|
|
90
|
+
} catch (cause) {
|
|
91
|
+
if (axios.isCancel(cause)) {
|
|
92
|
+
throw new HttpAbortError(requestMeta, {
|
|
93
|
+
cause,
|
|
94
|
+
reason: request.signal?.reason,
|
|
95
|
+
});
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
if (
|
|
99
|
+
request.timeoutMs !== undefined &&
|
|
100
|
+
axios.isAxiosError(cause) &&
|
|
101
|
+
(cause.code === "ECONNABORTED" || cause.code === "ETIMEDOUT")
|
|
102
|
+
) {
|
|
103
|
+
throw new HttpTimeoutError(request.timeoutMs, requestMeta, { cause });
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
throw new HttpTransportError(requestMeta, { cause });
|
|
107
|
+
}
|
|
87
108
|
},
|
|
88
109
|
};
|
|
89
110
|
```
|
|
@@ -107,6 +128,7 @@ Constraints:
|
|
|
107
128
|
|
|
108
129
|
- Use the complete `request.url` already calculated by the core.
|
|
109
130
|
- A custom transport applies optional `request.timeoutMs` to local I/O; when omitted it is `undefined` and the runtime enables no timeout.
|
|
131
|
+
- Convert adapter cancellation, timeout, and transport failures to the package error classes as shown above. The core wraps any remaining unknown transport failure as `HttpTransportError`, but only the adapter can reliably identify its own timeout codes.
|
|
110
132
|
- Do not regenerate the path, headers, or envelope.
|
|
111
133
|
- Do not parse JSON/CBOR or call `parseVrpcResponse`.
|
|
112
134
|
- Do not read `wire` or `suppressGlobalToast`; these fields never enter the transport request.
|
package/docs/guides/usage.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
## 1. Generic HTTP client
|
|
4
4
|
|
|
5
5
|
```ts
|
|
6
|
-
import {
|
|
6
|
+
import { createHttpClient, isHttpError } from "@yorun-ai/vrpc/http";
|
|
7
7
|
|
|
8
8
|
const client = createHttpClient({
|
|
9
9
|
prefixUrl: "https://api.example.com",
|
|
@@ -19,6 +19,9 @@ client.use({
|
|
|
19
19
|
console.log(context.url, context.init.method);
|
|
20
20
|
},
|
|
21
21
|
onError(error, context) {
|
|
22
|
+
if (isHttpError(error) && error.kind === "abort") {
|
|
23
|
+
return;
|
|
24
|
+
}
|
|
22
25
|
if (context.options.suppressGlobalToast) {
|
|
23
26
|
return;
|
|
24
27
|
}
|
|
@@ -66,17 +69,20 @@ client.request({
|
|
|
66
69
|
- `json` and `body` are mutually exclusive.
|
|
67
70
|
- `json` is serialized automatically and adds `content-type: application/json`.
|
|
68
71
|
- Pass `FormData` through `body`; do not set its content-type boundary manually.
|
|
72
|
+
- `path` is relative to `prefixUrl` by default. Absolute request URLs are rejected before transport.
|
|
73
|
+
- Set create-time `allowAbsoluteUrls: true` only for trusted complete URLs. The opt-in accepts `http:` and `https:`, forwards configured headers to the selected URL, and still rejects protocol-relative URLs such as `//example.com/path`.
|
|
69
74
|
- Create-time defaults are merged with per-request options; per-request scalar and requestInit fields take precedence.
|
|
70
75
|
- An interceptor receives merged configuration in `context.options` and the original call shape in `context.request`.
|
|
71
76
|
- Options do not leak into the transport request.
|
|
72
77
|
- `timeoutMs` is disabled by default. Set an application default at creation and override it per request when needed.
|
|
73
78
|
- The default is `credentials: "omit"`; use `requestInit.credentials: "include"` for cookies.
|
|
74
|
-
-
|
|
79
|
+
- Response parsing is intentionally lenient and independent of `content-type`: an empty body returns `null`, valid JSON is decoded, and any other body is returned as text.
|
|
80
|
+
- A timeout throws `HttpTimeoutError`; a non-2xx response throws `HttpInvokeError`.
|
|
75
81
|
|
|
76
82
|
## 2. vRPC client
|
|
77
83
|
|
|
78
84
|
```ts
|
|
79
|
-
import {
|
|
85
|
+
import { createVrpcClient, getClientInstanceId, isVrpcError } from "@yorun-ai/vrpc/client";
|
|
80
86
|
|
|
81
87
|
const client = createVrpcClient({
|
|
82
88
|
prefixUrl: "https://api.example.com/invoke",
|
|
@@ -91,13 +97,19 @@ const client = createVrpcClient({
|
|
|
91
97
|
|
|
92
98
|
client.use({
|
|
93
99
|
onError(error, context) {
|
|
100
|
+
if (isVrpcError(error) && error.kind === "abort") {
|
|
101
|
+
return;
|
|
102
|
+
}
|
|
94
103
|
if (context.options.suppressGlobalToast) {
|
|
95
104
|
return;
|
|
96
105
|
}
|
|
97
106
|
|
|
98
|
-
if (error
|
|
107
|
+
if (isVrpcError(error) && error.kind === "invoke") {
|
|
99
108
|
console.error(error.status, error.vrpcStatus, error.code, error.reason);
|
|
109
|
+
return;
|
|
100
110
|
}
|
|
111
|
+
|
|
112
|
+
console.error(error);
|
|
101
113
|
},
|
|
102
114
|
});
|
|
103
115
|
|
|
@@ -158,7 +170,155 @@ options: {
|
|
|
158
170
|
|
|
159
171
|
`timeoutMs` is disabled by default. Setting `timeoutMs: 2500` creates both a local timeout and `vrpc-options: timeout=2500ms`. The create-time value is the client default and may be overridden per call; a vRPC timeout must be a positive safe integer.
|
|
160
172
|
|
|
161
|
-
## 3.
|
|
173
|
+
## 3. Error handling
|
|
174
|
+
|
|
175
|
+
The vRPC entry point exposes one client-level guard, `isVrpcError`. After it succeeds, use only the discriminating `kind` field for error policy and server business fields:
|
|
176
|
+
|
|
177
|
+
```ts
|
|
178
|
+
import { isVrpcError } from "@yorun-ai/vrpc";
|
|
179
|
+
|
|
180
|
+
function handleVrpcError(error: unknown) {
|
|
181
|
+
if (!isVrpcError(error)) {
|
|
182
|
+
console.error("Unexpected error", error);
|
|
183
|
+
return;
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
switch (error.kind) {
|
|
187
|
+
case "abort":
|
|
188
|
+
return;
|
|
189
|
+
case "timeout":
|
|
190
|
+
console.error(`Request timed out after ${error.timeoutMs}ms`);
|
|
191
|
+
return;
|
|
192
|
+
case "transport":
|
|
193
|
+
console.error("Network request failed", error.cause);
|
|
194
|
+
return;
|
|
195
|
+
case "invoke":
|
|
196
|
+
console.error(error.status, error.vrpcStatus, error.code, error.reason, error.message);
|
|
197
|
+
return;
|
|
198
|
+
case "protocol":
|
|
199
|
+
console.error("Invalid vRPC response", error.cause);
|
|
200
|
+
return;
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
The generic HTTP entry point exposes the equivalent `isHttpError` guard. Both guards recognize only normalized errors produced by this package; compatibility handling for native Fetch and custom adapter errors stays inside the transport boundary. Error classes remain available for compatibility and specialized tests, but ordinary application code does not need a second `instanceof` check after the guard.
|
|
206
|
+
|
|
207
|
+
| `kind` | Client | Meaning |
|
|
208
|
+
| ----------- | ------------- | ------------------------------------------------------------------------------------------ |
|
|
209
|
+
| `abort` | HTTP and vRPC | The caller canceled through an `AbortSignal`. Usually silent in the UI. |
|
|
210
|
+
| `timeout` | HTTP and vRPC | The configured client timeout expired. |
|
|
211
|
+
| `transport` | HTTP and vRPC | No usable HTTP response was received. The original adapter error is available as `cause`. |
|
|
212
|
+
| `invoke` | HTTP and vRPC | The server rejected the invocation. vRPC errors expose `vrpcStatus`, `code`, and `reason`. |
|
|
213
|
+
| `protocol` | vRPC only | Required vRPC metadata is missing, or a successful response cannot be decoded. |
|
|
214
|
+
|
|
215
|
+
`VrpcInvokeError` uses `vrpc-status` as the authoritative vRPC outcome. The body error is auxiliary: `code` identifies the business category, `reason` identifies a more specific case, and a non-empty `detail` remains appended to `message`. If a failed vRPC response has an undecodable body, the client still throws `VrpcInvokeError` and records the decoding failure in `cause`.
|
|
216
|
+
|
|
217
|
+
An interceptor `onError` observes the error but does not consume it; the request promise still rejects. Put the `abort` check before logging or global toast logic when caller cancellation should be quiet.
|
|
218
|
+
|
|
219
|
+
Recommended application policy:
|
|
220
|
+
|
|
221
|
+
- Handle `abort` once in the global `onError` interceptor and show no error UI.
|
|
222
|
+
- Handle `timeout`, `transport`, and `protocol` globally with a stable user-facing message; retain `cause` for logging or reporting rather than displaying it directly.
|
|
223
|
+
- Branch on expected `invoke` values such as `code` and `reason` near the feature that understands them. Use `suppressGlobalToast` when that feature owns the UI, preventing duplicate messages.
|
|
224
|
+
- Treat values that fail `isVrpcError` as configuration, interceptor, or other unexpected application errors; do not silently classify them as network failures.
|
|
225
|
+
|
|
226
|
+
### Global `onError` and local `try/catch`
|
|
227
|
+
|
|
228
|
+
Global and local handlers have different responsibilities. A global `onError` interceptor is suitable for shared logging, reporting, and fallback UI. A local `try/catch` is suitable for an expected business outcome that the current feature can explain or recover from.
|
|
229
|
+
|
|
230
|
+
```ts
|
|
231
|
+
client.use({
|
|
232
|
+
onError(error, context) {
|
|
233
|
+
if (isVrpcError(error) && error.kind === "abort") {
|
|
234
|
+
return;
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
reportError(error);
|
|
238
|
+
|
|
239
|
+
if (!context.options.suppressGlobalToast) {
|
|
240
|
+
showToast("Request failed. Please try again.");
|
|
241
|
+
}
|
|
242
|
+
},
|
|
243
|
+
});
|
|
244
|
+
|
|
245
|
+
async function loadProfile() {
|
|
246
|
+
try {
|
|
247
|
+
return await client.invoke({
|
|
248
|
+
serviceName: "user.UserService",
|
|
249
|
+
methodName: "getProfile",
|
|
250
|
+
params: { userId: 1 },
|
|
251
|
+
options: {
|
|
252
|
+
// This feature owns the error UI shown in the catch block below.
|
|
253
|
+
suppressGlobalToast: true,
|
|
254
|
+
},
|
|
255
|
+
});
|
|
256
|
+
} catch (error) {
|
|
257
|
+
if (!isVrpcError(error)) {
|
|
258
|
+
throw error;
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
if (error.kind === "abort") {
|
|
262
|
+
return;
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
if (error.kind === "invoke" && error.code === "USER" && error.reason === "NOT_FOUND") {
|
|
266
|
+
showToast(error.message);
|
|
267
|
+
return;
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
// suppressGlobalToast also suppressed the global fallback, so keep a local fallback.
|
|
271
|
+
showToast("Unable to load the profile. Please try again.");
|
|
272
|
+
}
|
|
273
|
+
}
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
For transport and response failures, the lifecycle is:
|
|
277
|
+
|
|
278
|
+
```text
|
|
279
|
+
request fails -> onError runs -> the Promise rejects -> local catch runs
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
`onError` should perform side effects and complete normally. It does not turn a failed request into a successful result; after the interceptors complete, the request Promise still rejects.
|
|
283
|
+
|
|
284
|
+
`suppressGlobalToast` is policy metadata for application interceptors. The package does not display or suppress UI by itself. Setting it to `true` does not skip `onError`, logging, or Promise rejection; it only has an effect when an interceptor reads `context.options.suppressGlobalToast`. A per-request `true` or `false` overrides the client-level default. Set it to `true` only when the local caller owns a complete error experience, including a fallback for errors it does not specifically recognize.
|
|
285
|
+
|
|
286
|
+
Request-construction errors that occur before an interceptor context exists, such as invalid configuration, reject directly and may only reach the local `catch`. The same global/local pattern applies to the generic HTTP client with `isHttpError`.
|
|
287
|
+
|
|
288
|
+
## 4. Cancel requests
|
|
289
|
+
|
|
290
|
+
Both clients accept an `AbortSignal` through `requestInit.signal`:
|
|
291
|
+
|
|
292
|
+
```ts
|
|
293
|
+
import { isVrpcError } from "@yorun-ai/vrpc";
|
|
294
|
+
|
|
295
|
+
const controller = new AbortController();
|
|
296
|
+
const request = client.invoke({
|
|
297
|
+
serviceName: "user.UserService",
|
|
298
|
+
methodName: "getUser",
|
|
299
|
+
params: { userId: 1 },
|
|
300
|
+
options: {
|
|
301
|
+
requestInit: { signal: controller.signal },
|
|
302
|
+
},
|
|
303
|
+
});
|
|
304
|
+
|
|
305
|
+
// For example: the user closes a dialog or navigates away.
|
|
306
|
+
controller.abort();
|
|
307
|
+
|
|
308
|
+
try {
|
|
309
|
+
await request;
|
|
310
|
+
} catch (error) {
|
|
311
|
+
if (!(isVrpcError(error) && error.kind === "abort")) {
|
|
312
|
+
throw error;
|
|
313
|
+
}
|
|
314
|
+
}
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
Cancellation remains a rejected promise so frameworks and callers can finish loading-state cleanup. The normalized error preserves a custom `controller.abort(reason)` value as `reason` and the underlying runtime error as `cause`. A single controller may cancel multiple requests that share its signal. Aborting after a request has settled has no effect.
|
|
318
|
+
|
|
319
|
+
Timeouts may also use `AbortController` internally, but they remain `kind: "timeout"`; applications should not silently treat them as caller cancellation.
|
|
320
|
+
|
|
321
|
+
## 5. Automatic CBOR
|
|
162
322
|
|
|
163
323
|
A generated method without Binary has no wire and uses JSON. A method whose arguments or result contain Binary includes the corresponding schema:
|
|
164
324
|
|
|
@@ -214,7 +374,7 @@ Selection depends entirely on wire-property presence:
|
|
|
214
374
|
|
|
215
375
|
Wire never appears in the HTTP body, custom headers, or transport request.
|
|
216
376
|
|
|
217
|
-
##
|
|
377
|
+
## 6. Protocol helpers
|
|
218
378
|
|
|
219
379
|
```ts
|
|
220
380
|
import {
|
|
@@ -237,7 +397,7 @@ const body = buildVrpcRequestBody({ userId: 1 });
|
|
|
237
397
|
|
|
238
398
|
`parseVrpcResponse` returns a normalized result without throwing; `unwrapVrpcResponse` throws `VrpcInvokeError` on failure. A fully custom HTTP client is responsible for JSON/CBOR decoding of the response body; `createVrpcClient` handles it when using a runtime transport.
|
|
239
399
|
|
|
240
|
-
##
|
|
400
|
+
## 7. Custom transport
|
|
241
401
|
|
|
242
402
|
A transport performs I/O only, and the response body must remain raw bytes:
|
|
243
403
|
|