@yorun-ai/vrpc 0.9.1 → 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.
@@ -1,15 +1,68 @@
1
1
  //#region src/contracts/errors.ts
2
2
  var HTTP_TIMEOUT_ERROR_CODE = "HTTP_TIMEOUT";
3
- var HttpTimeoutError = class extends Error {
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 Error {
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
- url;
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
- const vrpcStatus = response.headers.get("vrpc-status");
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
- function buildRequestUrl(prefixUrl, path) {
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
- return new URL(path).toString();
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 createTimeoutError(timeoutMs) {
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: signal || void 0,
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
- const timer = setTimeout(() => controller.abort(createTimeoutError(timeoutMs)), timeoutMs);
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 (!signal) return {
234
+ if (!callerSignal) return {
139
235
  signal: controller.signal,
140
- cleanup: clear
236
+ cleanup: clear,
237
+ getAbortSource: () => abortSource,
238
+ getTimeoutError: () => timeoutError
141
239
  };
142
- if (signal.aborted) {
143
- controller.abort(signal.reason);
144
- return {
145
- signal: controller.signal,
146
- cleanup: clear
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
- signal.removeEventListener("abort", relayAbort);
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 { signal, cleanup } = withTimeoutSignal(input.timeoutMs, input.init.signal || input.signal);
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
- const response = buildResponseFromTransportResult(await httpTransport.request({
242
- url: context.url,
243
- init: context.init,
244
- method,
245
- headers,
246
- body: resolveTransportBody(context.init, prepared.fallbackBody),
247
- timeoutMs: prepared.timeoutMs,
248
- signal: context.init.signal
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() {
@@ -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 response = await axios.request<ArrayBuffer>({
67
- url: request.url,
68
- method: request.method,
69
- headers: Object.fromEntries(new Headers(request.headers).entries()),
70
- data: request.body,
71
- signal: request.signal ?? undefined,
72
- timeout: request.timeoutMs,
73
- withCredentials: request.init.credentials === "include",
74
- responseType: "arraybuffer",
75
- validateStatus: () => true,
76
- });
77
-
78
- const body = response.data.byteLength ? new Uint8Array(response.data) : null;
79
-
80
- return {
81
- status: response.status,
82
- statusText: response.statusText,
83
- headers: new Headers(response.headers as Record<string, string>),
84
- body,
85
- url: request.url,
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.
@@ -3,7 +3,7 @@
3
3
  ## 1. Generic HTTP client
4
4
 
5
5
  ```ts
6
- import { HttpInvokeError, HttpTimeoutError, createHttpClient } from "@yorun-ai/vrpc/http";
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
- - An empty body returns `null`; a timeout throws `HttpTimeoutError`; a non-2xx response throws `HttpInvokeError`.
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 { VrpcInvokeError, createVrpcClient, getClientInstanceId } from "@yorun-ai/vrpc/client";
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 instanceof VrpcInvokeError) {
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. Automatic CBOR
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
- ## 4. Protocol helpers
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
- ## 5. Custom transport
400
+ ## 7. Custom transport
241
401
 
242
402
  A transport performs I/O only, and the response body must remain raw bytes:
243
403