@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.
package/README.md CHANGED
@@ -1,5 +1,9 @@
1
1
  # @yorun-ai/vrpc
2
2
 
3
+ [![license](https://img.shields.io/github/license/yorun-ai/vrpc-ts)](https://github.com/yorun-ai/vrpc-ts/blob/main/LICENSE)
4
+ [![version](https://img.shields.io/npm/v/%40yorun-ai%2Fvrpc?label=version&logo=npm)](https://www.npmjs.com/package/@yorun-ai/vrpc)
5
+ [![CI](https://github.com/yorun-ai/vrpc-ts/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/yorun-ai/vrpc-ts/actions/workflows/ci.yml)
6
+
3
7
  **English** | [简体中文](README.zh-CN.md)
4
8
 
5
9
  Client runtime for Vine vRPC and generic HTTP requests.
@@ -24,7 +28,7 @@ pnpm add @yorun-ai/vrpc
24
28
  ## vRPC quick start
25
29
 
26
30
  ```ts
27
- import { VrpcInvokeError, createVrpcClient, getClientInstanceId } from "@yorun-ai/vrpc";
31
+ import { createVrpcClient, getClientInstanceId, isVrpcError } from "@yorun-ai/vrpc";
28
32
 
29
33
  const client = createVrpcClient({
30
34
  prefixUrl: "https://api.example.com/invoke",
@@ -39,6 +43,9 @@ const client = createVrpcClient({
39
43
 
40
44
  client.use({
41
45
  onError(error, context) {
46
+ if (isVrpcError(error) && error.kind === "abort") {
47
+ return;
48
+ }
42
49
  if (context.options.suppressGlobalToast) {
43
50
  return;
44
51
  }
@@ -70,7 +77,7 @@ try {
70
77
  params: {},
71
78
  });
72
79
  } catch (error) {
73
- if (error instanceof VrpcInvokeError) {
80
+ if (isVrpcError(error) && error.kind === "invoke") {
74
81
  console.error(error.status, error.vrpcStatus, error.code, error.reason);
75
82
  }
76
83
  }
@@ -185,7 +192,100 @@ await http.request({
185
192
  });
186
193
  ```
187
194
 
188
- HTTP interceptors read merged request configuration from `context.options`. `json` and `body` are mutually exclusive, and an empty response returns `null`.
195
+ HTTP interceptors read merged request configuration from `context.options`. `json` and `body` are mutually exclusive. Generic HTTP 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.
196
+
197
+ Request paths are relative to `prefixUrl` by default. Absolute request URLs are rejected before transport so an untrusted `path` cannot redirect client-level headers to another origin. For a trusted use case that requires complete URLs, set `allowAbsoluteUrls: true` when creating the HTTP client. This opt-in accepts only `http:` and `https:` URLs, continues to send the configured headers to the selected URL, and does not permit protocol-relative URLs such as `//example.com/path`.
198
+
199
+ ## Error handling
200
+
201
+ Use the single `isVrpcError` guard, then classify a normalized vRPC client error by `kind`:
202
+
203
+ ```ts
204
+ import { isVrpcError } from "@yorun-ai/vrpc";
205
+
206
+ function handleError(error: unknown) {
207
+ if (!isVrpcError(error)) {
208
+ console.error(error);
209
+ return;
210
+ }
211
+
212
+ if (error.kind === "abort") {
213
+ return;
214
+ }
215
+
216
+ if (error.kind === "invoke") {
217
+ console.error(error.vrpcStatus, error.code, error.reason, error.message);
218
+ return;
219
+ }
220
+
221
+ console.error(error.kind, error.message, error.cause);
222
+ }
223
+ ```
224
+
225
+ The vRPC error kinds are `abort`, `timeout`, `transport`, `invoke`, and `protocol`. The generic HTTP entry point provides the equivalent `isHttpError` guard with `abort`, `timeout`, `transport`, and `invoke`. Original adapter or vRPC decoding errors are preserved in `cause`. For vRPC invoke errors, `code` and `reason` remain server-defined business fields, and `message` continues to include a non-empty `detail`.
226
+
227
+ Error classes remain exported for compatibility and specialized tests, but application policy normally needs only the guard and `kind`.
228
+
229
+ ### Local `try/catch` and `suppressGlobalToast`
230
+
231
+ Use a local `try/catch` when a feature owns the error UI. Set `suppressGlobalToast: true` on that request so the global interceptor can skip its fallback toast:
232
+
233
+ ```ts
234
+ async function loadProfile() {
235
+ try {
236
+ return await client.invoke({
237
+ serviceName: "user.UserService",
238
+ methodName: "getProfile",
239
+ params: { userId: 1 },
240
+ options: { suppressGlobalToast: true },
241
+ });
242
+ } catch (error) {
243
+ if (!isVrpcError(error)) {
244
+ throw error;
245
+ }
246
+ if (error.kind === "abort") {
247
+ return;
248
+ }
249
+ if (error.kind === "invoke" && error.code === "USER" && error.reason === "NOT_FOUND") {
250
+ showToast(error.message);
251
+ return;
252
+ }
253
+ showToast("Unable to load the profile. Please try again.");
254
+ }
255
+ }
256
+ ```
257
+
258
+ `suppressGlobalToast` is only metadata for application interceptors; the package does not operate UI itself. It does not skip `onError` or consume the error. The lifecycle remains `onError` first, followed by Promise rejection and the local `catch`. A per-request value overrides the client-level default.
259
+
260
+ ## Cancel requests
261
+
262
+ Pass an `AbortSignal` through `requestInit.signal`. Cancellation rejects with an error whose `kind` is `"abort"`; it is not converted into a successful `undefined` result.
263
+
264
+ ```ts
265
+ import { isVrpcError } from "@yorun-ai/vrpc";
266
+
267
+ const controller = new AbortController();
268
+ const request = client.invoke({
269
+ serviceName: "user.UserService",
270
+ methodName: "getProfile",
271
+ params: { userId: 1 },
272
+ options: {
273
+ requestInit: { signal: controller.signal },
274
+ },
275
+ });
276
+
277
+ controller.abort();
278
+
279
+ try {
280
+ await request;
281
+ } catch (error) {
282
+ if (!(isVrpcError(error) && error.kind === "abort")) {
283
+ throw error;
284
+ }
285
+ }
286
+ ```
287
+
288
+ Handle `abort` once in a global `onError` interceptor when cancellation should be silent in the UI. Timeouts remain `kind: "timeout"` and are not treated as caller cancellation.
189
289
 
190
290
  ## Protocol helpers
191
291
 
package/README.zh-CN.md CHANGED
@@ -1,5 +1,9 @@
1
1
  # @yorun-ai/vrpc
2
2
 
3
+ [![license](https://img.shields.io/github/license/yorun-ai/vrpc-ts)](https://github.com/yorun-ai/vrpc-ts/blob/main/LICENSE)
4
+ [![version](https://img.shields.io/npm/v/%40yorun-ai%2Fvrpc?label=version&logo=npm)](https://www.npmjs.com/package/@yorun-ai/vrpc)
5
+ [![CI](https://github.com/yorun-ai/vrpc-ts/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/yorun-ai/vrpc-ts/actions/workflows/ci.yml)
6
+
3
7
  [English](README.md) | **简体中文**
4
8
 
5
9
  用于 Vine vRPC 与通用 HTTP 请求的客户端运行时。
@@ -24,7 +28,7 @@ pnpm add @yorun-ai/vrpc
24
28
  ## vRPC 快速开始
25
29
 
26
30
  ```ts
27
- import { VrpcInvokeError, createVrpcClient, getClientInstanceId } from "@yorun-ai/vrpc";
31
+ import { createVrpcClient, getClientInstanceId, isVrpcError } from "@yorun-ai/vrpc";
28
32
 
29
33
  const client = createVrpcClient({
30
34
  prefixUrl: "https://api.example.com/invoke",
@@ -39,6 +43,9 @@ const client = createVrpcClient({
39
43
 
40
44
  client.use({
41
45
  onError(error, context) {
46
+ if (isVrpcError(error) && error.kind === "abort") {
47
+ return;
48
+ }
42
49
  if (context.options.suppressGlobalToast) {
43
50
  return;
44
51
  }
@@ -70,7 +77,7 @@ try {
70
77
  params: {},
71
78
  });
72
79
  } catch (error) {
73
- if (error instanceof VrpcInvokeError) {
80
+ if (isVrpcError(error) && error.kind === "invoke") {
74
81
  console.error(error.status, error.vrpcStatus, error.code, error.reason);
75
82
  }
76
83
  }
@@ -185,7 +192,100 @@ await http.request({
185
192
  });
186
193
  ```
187
194
 
188
- HTTP interceptor 通过 `context.options` 读取合并后的请求配置。`json` 和 `body` 互斥,空响应返回 `null`。
195
+ HTTP interceptor 通过 `context.options` 读取合并后的请求配置。`json` 和 `body` 互斥。通用 HTTP 响应采用与 `content-type` 无关的宽松解析策略:空 body 返回 `null`,合法 JSON 返回解码结果,其他 body 返回文本。
196
+
197
+ 请求 `path` 默认只能相对于 `prefixUrl`。绝对请求 URL 会在进入 transport 前被拒绝,避免不可信的 `path` 把 client 级 Header 转发到其他 origin。确实需要完整 URL 且输入可信时,可以在创建 HTTP client 时设置 `allowAbsoluteUrls: true`。该显式选项只接受 `http:` 和 `https:` URL,并会继续向目标 URL 发送已配置的 Header;`//example.com/path` 形式的协议相对 URL 始终不允许。
198
+
199
+ ## 错误处理
200
+
201
+ 业务只需要使用 `isVrpcError` 判断是否为 vRPC client 规范化错误,然后通过 `kind` 分类:
202
+
203
+ ```ts
204
+ import { isVrpcError } from "@yorun-ai/vrpc";
205
+
206
+ function handleError(error: unknown) {
207
+ if (!isVrpcError(error)) {
208
+ console.error(error);
209
+ return;
210
+ }
211
+
212
+ if (error.kind === "abort") {
213
+ return;
214
+ }
215
+
216
+ if (error.kind === "invoke") {
217
+ console.error(error.vrpcStatus, error.code, error.reason, error.message);
218
+ return;
219
+ }
220
+
221
+ console.error(error.kind, error.message, error.cause);
222
+ }
223
+ ```
224
+
225
+ vRPC 的错误 kind 包括 `abort`、`timeout`、`transport`、`invoke` 和 `protocol`。通用 HTTP 入口提供等价的 `isHttpError`,其错误 kind 包括 `abort`、`timeout`、`transport` 和 `invoke`。adapter 或 vRPC 解码产生的原始异常会保留在 `cause` 中。对于 vRPC invoke 错误,`code` 和 `reason` 仍然是服务端业务字段,非空 `detail` 仍会拼接到 `message`。
226
+
227
+ 错误 class 会继续导出,供兼容代码和特定测试使用;业务错误策略通常只需要 guard 和 `kind`,无需再使用 `instanceof` 二次分类。
228
+
229
+ ### 局部 `try/catch` 与 `suppressGlobalToast`
230
+
231
+ 当功能模块自行负责错误 UI 时,使用局部 `try/catch`,并为该请求设置 `suppressGlobalToast: true`,让全局 interceptor 跳过兜底 toast:
232
+
233
+ ```ts
234
+ async function loadProfile() {
235
+ try {
236
+ return await client.invoke({
237
+ serviceName: "user.UserService",
238
+ methodName: "getProfile",
239
+ params: { userId: 1 },
240
+ options: { suppressGlobalToast: true },
241
+ });
242
+ } catch (error) {
243
+ if (!isVrpcError(error)) {
244
+ throw error;
245
+ }
246
+ if (error.kind === "abort") {
247
+ return;
248
+ }
249
+ if (error.kind === "invoke" && error.code === "USER" && error.reason === "NOT_FOUND") {
250
+ showToast(error.message);
251
+ return;
252
+ }
253
+ showToast("加载用户资料失败,请稍后重试");
254
+ }
255
+ }
256
+ ```
257
+
258
+ `suppressGlobalToast` 只是提供给应用 interceptor 的策略元数据,包本身不会操作 UI。它不会跳过 `onError`,也不会吞掉错误;执行顺序仍然是先运行 `onError`,随后 Promise reject 并进入局部 `catch`。单次请求的值会覆盖 client 级默认值。
259
+
260
+ ## 取消请求
261
+
262
+ 通过 `requestInit.signal` 传入 `AbortSignal`。取消请求会 reject 一个 `kind` 为 `"abort"` 的错误,不会被转换成成功的 `undefined` 结果。
263
+
264
+ ```ts
265
+ import { isVrpcError } from "@yorun-ai/vrpc";
266
+
267
+ const controller = new AbortController();
268
+ const request = client.invoke({
269
+ serviceName: "user.UserService",
270
+ methodName: "getProfile",
271
+ params: { userId: 1 },
272
+ options: {
273
+ requestInit: { signal: controller.signal },
274
+ },
275
+ });
276
+
277
+ controller.abort();
278
+
279
+ try {
280
+ await request;
281
+ } catch (error) {
282
+ if (!(isVrpcError(error) && error.kind === "abort")) {
283
+ throw error;
284
+ }
285
+ }
286
+ ```
287
+
288
+ 如果取消请求不需要展示 UI 错误,只需在全局 `onError` interceptor 中统一忽略 `abort`。超时保持为 `kind: "timeout"`,不会被误判为用户主动取消。
189
289
 
190
290
  ## 协议 helper
191
291
 
package/dist/client.cjs CHANGED
@@ -1,5 +1,5 @@
1
1
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
- const require_request_options = require("./request-options-2HZzkj4w.cjs");
2
+ const require_request_options = require("./request-options-m8_63jpk.cjs");
3
3
  //#region src/protocol/id.ts
4
4
  var DEFAULT_CLIENT_INSTANCE_ID_STORAGE_KEY = "vrpc-client-instance-id";
5
5
  function getRandomByteArray(length) {
@@ -224,8 +224,8 @@ function readEnvelopeResult(payload) {
224
224
  if (!payload || typeof payload !== "object") return;
225
225
  return payload.result;
226
226
  }
227
- function requireResponseHeader(headers, name) {
228
- const value = headers.get(name);
227
+ function requireResponseHeader(response, name) {
228
+ const value = response.headers.get(name);
229
229
  if (!value) throw new Error(`Invalid vRPC response: missing ${name} header.`);
230
230
  return value;
231
231
  }
@@ -234,28 +234,33 @@ function readDecodedEnvelopeField(payload, field) {
234
234
  if (payload && typeof payload === "object") return payload[field];
235
235
  }
236
236
  async function decodeVrpcResponsePayload(response, cborCodec, resultSchema) {
237
- requireResponseHeader(response.headers, "vrpc-status");
238
- assertValidVrpcServerHeader(response.headers.get("vrpc-server"));
239
- const contentType = mediaTypeOf(requireResponseHeader(response.headers, "content-type"));
240
- if (contentType === "application/vrpc+json") {
241
- const text = await response.text();
242
- if (!text) throw new Error("Invalid vRPC response: empty response body.");
243
- try {
244
- return JSON.parse(text);
245
- } catch {
246
- throw new Error("Invalid vRPC response: JSON body cannot be parsed.");
237
+ try {
238
+ requireResponseHeader(response, "vrpc-status");
239
+ assertValidVrpcServerHeader(response.headers.get("vrpc-server"));
240
+ const contentType = mediaTypeOf(requireResponseHeader(response, "content-type"));
241
+ if (contentType === "application/vrpc+json") {
242
+ const text = await response.text();
243
+ if (!text) throw new Error("Invalid vRPC response: empty response body.");
244
+ try {
245
+ return JSON.parse(text);
246
+ } catch {
247
+ throw new Error("Invalid vRPC response: JSON body cannot be parsed.");
248
+ }
247
249
  }
250
+ if (contentType !== "application/vrpc+cbor") throw new Error(`Invalid vRPC response content-type: ${contentType || "empty"}.`);
251
+ if (!resultSchema) throw new Error("Invalid vRPC response: unexpected CBOR body for a JSON method.");
252
+ if (!cborCodec) throw new Error("A cborCodec is required to decode a CBOR vRPC response.");
253
+ const decoded = await cborCodec.decode(new Uint8Array(await response.arrayBuffer()));
254
+ const result = readDecodedEnvelopeField(decoded, "result");
255
+ const error = readDecodedEnvelopeField(decoded, "error");
256
+ return {
257
+ result: fromCborWireValue(result, resultSchema),
258
+ error: normalizeCborValue(error)
259
+ };
260
+ } catch (cause) {
261
+ if (cause instanceof require_request_options.VrpcProtocolError) throw cause;
262
+ throw new require_request_options.VrpcProtocolError(response, cause instanceof Error ? cause.message : "Invalid vRPC response.", {}, { cause });
248
263
  }
249
- if (contentType !== "application/vrpc+cbor") throw new Error(`Invalid vRPC response content-type: ${contentType || "empty"}.`);
250
- if (!resultSchema) throw new Error("Invalid vRPC response: unexpected CBOR body for a JSON method.");
251
- if (!cborCodec) throw new Error("A cborCodec is required to decode a CBOR vRPC response.");
252
- const decoded = await cborCodec.decode(new Uint8Array(await response.arrayBuffer()));
253
- const result = readDecodedEnvelopeField(decoded, "result");
254
- const error = readDecodedEnvelopeField(decoded, "error");
255
- return {
256
- result: fromCborWireValue(result, resultSchema),
257
- error: normalizeCborValue(error)
258
- };
259
264
  }
260
265
  function normalizeResponseHeaders(headers) {
261
266
  if (!headers) return new Headers();
@@ -417,7 +422,18 @@ function createVrpcClient(options) {
417
422
  }
418
423
  };
419
424
  },
420
- parseResponse: (response, context) => decodeVrpcResponsePayload(response, cborCodec, context.options.wire?.result),
425
+ parseResponse: async (response, context) => {
426
+ try {
427
+ return await decodeVrpcResponsePayload(response, cborCodec, context.options.wire?.result);
428
+ } catch (cause) {
429
+ const vrpcStatus = response.headers.get("vrpc-status");
430
+ if (vrpcStatus && (!response.ok || vrpcStatus !== "OK")) throw new require_request_options.VrpcInvokeError(response, null, {
431
+ url: context.url,
432
+ method: String(context.init.method || "POST").toUpperCase()
433
+ }, { cause });
434
+ throw cause;
435
+ }
436
+ },
421
437
  validateRequest: (_context, requestMeta) => {
422
438
  if (requestMeta.method !== "POST") throw new Error(`Unsupported method: ${requestMeta.method}, only POST is allowed.`);
423
439
  },
@@ -442,11 +458,15 @@ function createVrpcClient(options) {
442
458
  //#endregion
443
459
  exports.DEFAULT_CLIENT_INSTANCE_ID_STORAGE_KEY = DEFAULT_CLIENT_INSTANCE_ID_STORAGE_KEY;
444
460
  exports.HTTP_TIMEOUT_ERROR_CODE = require_request_options.HTTP_TIMEOUT_ERROR_CODE;
461
+ exports.HttpAbortError = require_request_options.HttpAbortError;
462
+ exports.HttpClientError = require_request_options.HttpClientError;
445
463
  exports.HttpInvokeError = require_request_options.HttpInvokeError;
446
464
  exports.HttpTimeoutError = require_request_options.HttpTimeoutError;
465
+ exports.HttpTransportError = require_request_options.HttpTransportError;
447
466
  exports.VRPC_CBOR_CONTENT_TYPE = VRPC_CBOR_CONTENT_TYPE;
448
467
  exports.VRPC_JSON_CONTENT_TYPE = VRPC_JSON_CONTENT_TYPE;
449
468
  exports.VrpcInvokeError = require_request_options.VrpcInvokeError;
469
+ exports.VrpcProtocolError = require_request_options.VrpcProtocolError;
450
470
  exports.buildVrpcHeaders = buildVrpcHeaders;
451
471
  exports.buildVrpcPath = buildVrpcPath;
452
472
  exports.buildVrpcRequestBody = buildVrpcRequestBody;
@@ -458,5 +478,6 @@ exports.generateClientInstanceId = generateClientInstanceId;
458
478
  exports.generateVrpcId = generateVrpcId;
459
479
  exports.generateVrpcSpan = generateVrpcSpan;
460
480
  exports.getClientInstanceId = getClientInstanceId;
481
+ exports.isVrpcError = require_request_options.isVrpcError;
461
482
  exports.parseVrpcResponse = parseVrpcResponse;
462
483
  exports.unwrapVrpcResponse = unwrapVrpcResponse;
package/dist/client.d.cts CHANGED
@@ -19,6 +19,7 @@ type HttpRequestConfig = {
19
19
  };
20
20
  type HttpClientOptions = HttpRequestOptions & {
21
21
  prefixUrl: string | URL;
22
+ allowAbsoluteUrls?: boolean;
22
23
  fetchImpl?: typeof fetch;
23
24
  transport?: HttpTransport;
24
25
  interceptors?: HttpInterceptor[];
@@ -139,7 +140,7 @@ interface VrpcRequestOptions extends HttpRequestOptions {
139
140
  trace?: VrpcTrace;
140
141
  wire?: VrpcMethodWireSpec;
141
142
  }
142
- type VrpcClientOptions = Omit<HttpClientOptions, "interceptors" | "transport"> & {
143
+ type VrpcClientOptions = Omit<HttpClientOptions, "allowAbsoluteUrls" | "interceptors" | "transport"> & {
143
144
  clientInfo: VrpcClientInfo;
144
145
  traceMode?: VrpcTraceMode;
145
146
  cborCodec?: VrpcCborCodec;
@@ -184,13 +185,47 @@ type HttpErrorRequestMeta = {
184
185
  url?: string;
185
186
  method?: string;
186
187
  };
188
+ type HttpClientErrorOptions = {
189
+ cause?: unknown;
190
+ };
191
+ type HttpAbortErrorOptions = HttpClientErrorOptions & {
192
+ reason?: unknown;
193
+ };
194
+ type HttpClientErrorKind = "invoke" | "timeout" | "abort" | "transport" | "protocol";
187
195
  declare const HTTP_TIMEOUT_ERROR_CODE: "HTTP_TIMEOUT";
188
- declare class HttpTimeoutError extends Error {
189
- code: typeof HTTP_TIMEOUT_ERROR_CODE;
190
- timeoutMs: number;
191
- constructor(timeoutMs: number);
196
+ declare const HTTP_ABORT_ERROR_CODE: "HTTP_ABORTED";
197
+ declare const HTTP_TRANSPORT_ERROR_CODE: "HTTP_TRANSPORT_ERROR";
198
+ declare const VRPC_PROTOCOL_ERROR_CODE: "VRPC_PROTOCOL_ERROR";
199
+ declare class HttpClientError<TKind extends HttpClientErrorKind = HttpClientErrorKind> extends Error {
200
+ readonly isHttpClientError: true;
201
+ readonly kind: TKind;
202
+ readonly url: string;
203
+ readonly method: string;
204
+ constructor(message: string, kind: TKind, requestMeta?: HttpErrorRequestMeta, options?: HttpClientErrorOptions);
205
+ }
206
+ declare class HttpTimeoutError extends HttpClientError<"timeout"> {
207
+ readonly code: typeof HTTP_TIMEOUT_ERROR_CODE;
208
+ readonly timeoutMs: number;
209
+ constructor(timeoutMs: number, requestMeta?: HttpErrorRequestMeta, options?: HttpClientErrorOptions);
210
+ }
211
+ declare class HttpAbortError extends HttpClientError<"abort"> {
212
+ readonly code: typeof HTTP_ABORT_ERROR_CODE;
213
+ readonly reason?: unknown;
214
+ constructor(requestMeta?: HttpErrorRequestMeta, options?: HttpAbortErrorOptions);
192
215
  }
193
- declare class HttpInvokeError extends Error {
216
+ declare class HttpTransportError extends HttpClientError<"transport"> {
217
+ readonly code: typeof HTTP_TRANSPORT_ERROR_CODE;
218
+ constructor(requestMeta?: HttpErrorRequestMeta, options?: HttpClientErrorOptions);
219
+ }
220
+ declare class VrpcProtocolError extends HttpClientError<"protocol"> {
221
+ readonly code: typeof VRPC_PROTOCOL_ERROR_CODE;
222
+ readonly status: number;
223
+ readonly statusText: string;
224
+ readonly responseHeaders: Headers;
225
+ readonly vrpcStatus: string | null;
226
+ constructor(response: Response, message: string, requestMeta?: HttpErrorRequestMeta, options?: HttpClientErrorOptions);
227
+ }
228
+ declare class HttpInvokeError extends HttpClientError<"invoke"> {
194
229
  type?: string;
195
230
  code?: string;
196
231
  reason?: string;
@@ -199,15 +234,16 @@ declare class HttpInvokeError extends Error {
199
234
  statusText: string;
200
235
  responseHeaders: Headers;
201
236
  payload: unknown;
202
- url: string;
203
- method: string;
204
- constructor(response: Response, payload: unknown, requestMeta?: HttpErrorRequestMeta);
237
+ constructor(response: Response, payload: unknown, requestMeta?: HttpErrorRequestMeta, options?: HttpClientErrorOptions);
205
238
  }
206
239
  type VrpcErrorPayload = HttpErrorPayload;
207
240
  declare class VrpcInvokeError extends HttpInvokeError {
208
241
  vrpcStatus: string | null;
209
- constructor(response: Response, payload: unknown, requestMeta?: HttpErrorRequestMeta);
242
+ constructor(response: Response, payload: unknown, requestMeta?: HttpErrorRequestMeta, options?: HttpClientErrorOptions);
210
243
  }
244
+ type HttpError = HttpAbortError | HttpInvokeError | HttpTimeoutError | HttpTransportError;
245
+ type VrpcError = HttpAbortError | HttpTimeoutError | HttpTransportError | VrpcInvokeError | VrpcProtocolError;
246
+ declare function isVrpcError(error: unknown): error is VrpcError;
211
247
  //#endregion
212
248
  //#region src/protocol/id.d.ts
213
249
  declare const DEFAULT_CLIENT_INSTANCE_ID_STORAGE_KEY = "vrpc-client-instance-id";
@@ -244,4 +280,4 @@ declare function createVrpcClient(options: VrpcClientOptions): VrpcClient;
244
280
  //#region src/transports/fetch-transport.d.ts
245
281
  declare function createFetchTransport(fetchImpl?: typeof fetch): HttpTransport;
246
282
  //#endregion
247
- export { type BuildVrpcHeadersOptions, DEFAULT_CLIENT_INSTANCE_ID_STORAGE_KEY, type GetClientInstanceIdOptions, HTTP_TIMEOUT_ERROR_CODE, type HttpClient, type HttpClientOptions, type HttpErrorPayload, type HttpInterceptor, type HttpInvokeContext, HttpInvokeError, type HttpQueryParams, type HttpQueryPrimitive, type HttpQueryValue, type HttpRequestConfig, type HttpRequestInit, type HttpRequestOptions, HttpTimeoutError, type HttpTransport, type HttpTransportRequest, type HttpTransportResponse, type ParsedVrpcErrorResponse, type ParsedVrpcResponse, type ParsedVrpcSuccessResponse, VRPC_CBOR_CONTENT_TYPE, VRPC_JSON_CONTENT_TYPE, type VrpcCborCodec, type VrpcClient, type VrpcClientInfo, type VrpcClientOptions, type VrpcErrorPayload, type VrpcInterceptor, type VrpcInterceptors, type VrpcInvokeContext, VrpcInvokeError, type VrpcInvokeRequest, type VrpcMethodWireSpec, type VrpcRequestInit, type VrpcRequestOptions, type VrpcResponseLike, type VrpcTrace, type VrpcTraceMode, type VrpcTransport, type VrpcTransportRequest, type VrpcTransportResponse, type VrpcWireSchema, buildVrpcHeaders, buildVrpcPath, buildVrpcRequestBody, createFetchTransport, createVrpcClient, decodeVrpcResponsePayload, encodeVrpcRequestBody, generateClientInstanceId, generateVrpcId, generateVrpcSpan, getClientInstanceId, parseVrpcResponse, unwrapVrpcResponse };
283
+ export { type BuildVrpcHeadersOptions, DEFAULT_CLIENT_INSTANCE_ID_STORAGE_KEY, type GetClientInstanceIdOptions, HTTP_TIMEOUT_ERROR_CODE, HttpAbortError, type HttpAbortErrorOptions, type HttpClient, HttpClientError, type HttpClientErrorKind, type HttpClientErrorOptions, type HttpClientOptions, type HttpError, type HttpErrorPayload, type HttpErrorRequestMeta, type HttpInterceptor, type HttpInvokeContext, HttpInvokeError, type HttpQueryParams, type HttpQueryPrimitive, type HttpQueryValue, type HttpRequestConfig, type HttpRequestInit, type HttpRequestOptions, HttpTimeoutError, type HttpTransport, HttpTransportError, type HttpTransportRequest, type HttpTransportResponse, type ParsedVrpcErrorResponse, type ParsedVrpcResponse, type ParsedVrpcSuccessResponse, VRPC_CBOR_CONTENT_TYPE, VRPC_JSON_CONTENT_TYPE, type VrpcCborCodec, type VrpcClient, type VrpcClientInfo, type VrpcClientOptions, type VrpcError, type VrpcErrorPayload, type VrpcInterceptor, type VrpcInterceptors, type VrpcInvokeContext, VrpcInvokeError, type VrpcInvokeRequest, type VrpcMethodWireSpec, VrpcProtocolError, type VrpcRequestInit, type VrpcRequestOptions, type VrpcResponseLike, type VrpcTrace, type VrpcTraceMode, type VrpcTransport, type VrpcTransportRequest, type VrpcTransportResponse, type VrpcWireSchema, buildVrpcHeaders, buildVrpcPath, buildVrpcRequestBody, createFetchTransport, createVrpcClient, decodeVrpcResponsePayload, encodeVrpcRequestBody, generateClientInstanceId, generateVrpcId, generateVrpcSpan, getClientInstanceId, isVrpcError, parseVrpcResponse, unwrapVrpcResponse };
package/dist/client.d.ts CHANGED
@@ -19,6 +19,7 @@ type HttpRequestConfig = {
19
19
  };
20
20
  type HttpClientOptions = HttpRequestOptions & {
21
21
  prefixUrl: string | URL;
22
+ allowAbsoluteUrls?: boolean;
22
23
  fetchImpl?: typeof fetch;
23
24
  transport?: HttpTransport;
24
25
  interceptors?: HttpInterceptor[];
@@ -139,7 +140,7 @@ interface VrpcRequestOptions extends HttpRequestOptions {
139
140
  trace?: VrpcTrace;
140
141
  wire?: VrpcMethodWireSpec;
141
142
  }
142
- type VrpcClientOptions = Omit<HttpClientOptions, "interceptors" | "transport"> & {
143
+ type VrpcClientOptions = Omit<HttpClientOptions, "allowAbsoluteUrls" | "interceptors" | "transport"> & {
143
144
  clientInfo: VrpcClientInfo;
144
145
  traceMode?: VrpcTraceMode;
145
146
  cborCodec?: VrpcCborCodec;
@@ -184,13 +185,47 @@ type HttpErrorRequestMeta = {
184
185
  url?: string;
185
186
  method?: string;
186
187
  };
188
+ type HttpClientErrorOptions = {
189
+ cause?: unknown;
190
+ };
191
+ type HttpAbortErrorOptions = HttpClientErrorOptions & {
192
+ reason?: unknown;
193
+ };
194
+ type HttpClientErrorKind = "invoke" | "timeout" | "abort" | "transport" | "protocol";
187
195
  declare const HTTP_TIMEOUT_ERROR_CODE: "HTTP_TIMEOUT";
188
- declare class HttpTimeoutError extends Error {
189
- code: typeof HTTP_TIMEOUT_ERROR_CODE;
190
- timeoutMs: number;
191
- constructor(timeoutMs: number);
196
+ declare const HTTP_ABORT_ERROR_CODE: "HTTP_ABORTED";
197
+ declare const HTTP_TRANSPORT_ERROR_CODE: "HTTP_TRANSPORT_ERROR";
198
+ declare const VRPC_PROTOCOL_ERROR_CODE: "VRPC_PROTOCOL_ERROR";
199
+ declare class HttpClientError<TKind extends HttpClientErrorKind = HttpClientErrorKind> extends Error {
200
+ readonly isHttpClientError: true;
201
+ readonly kind: TKind;
202
+ readonly url: string;
203
+ readonly method: string;
204
+ constructor(message: string, kind: TKind, requestMeta?: HttpErrorRequestMeta, options?: HttpClientErrorOptions);
205
+ }
206
+ declare class HttpTimeoutError extends HttpClientError<"timeout"> {
207
+ readonly code: typeof HTTP_TIMEOUT_ERROR_CODE;
208
+ readonly timeoutMs: number;
209
+ constructor(timeoutMs: number, requestMeta?: HttpErrorRequestMeta, options?: HttpClientErrorOptions);
210
+ }
211
+ declare class HttpAbortError extends HttpClientError<"abort"> {
212
+ readonly code: typeof HTTP_ABORT_ERROR_CODE;
213
+ readonly reason?: unknown;
214
+ constructor(requestMeta?: HttpErrorRequestMeta, options?: HttpAbortErrorOptions);
192
215
  }
193
- declare class HttpInvokeError extends Error {
216
+ declare class HttpTransportError extends HttpClientError<"transport"> {
217
+ readonly code: typeof HTTP_TRANSPORT_ERROR_CODE;
218
+ constructor(requestMeta?: HttpErrorRequestMeta, options?: HttpClientErrorOptions);
219
+ }
220
+ declare class VrpcProtocolError extends HttpClientError<"protocol"> {
221
+ readonly code: typeof VRPC_PROTOCOL_ERROR_CODE;
222
+ readonly status: number;
223
+ readonly statusText: string;
224
+ readonly responseHeaders: Headers;
225
+ readonly vrpcStatus: string | null;
226
+ constructor(response: Response, message: string, requestMeta?: HttpErrorRequestMeta, options?: HttpClientErrorOptions);
227
+ }
228
+ declare class HttpInvokeError extends HttpClientError<"invoke"> {
194
229
  type?: string;
195
230
  code?: string;
196
231
  reason?: string;
@@ -199,15 +234,16 @@ declare class HttpInvokeError extends Error {
199
234
  statusText: string;
200
235
  responseHeaders: Headers;
201
236
  payload: unknown;
202
- url: string;
203
- method: string;
204
- constructor(response: Response, payload: unknown, requestMeta?: HttpErrorRequestMeta);
237
+ constructor(response: Response, payload: unknown, requestMeta?: HttpErrorRequestMeta, options?: HttpClientErrorOptions);
205
238
  }
206
239
  type VrpcErrorPayload = HttpErrorPayload;
207
240
  declare class VrpcInvokeError extends HttpInvokeError {
208
241
  vrpcStatus: string | null;
209
- constructor(response: Response, payload: unknown, requestMeta?: HttpErrorRequestMeta);
242
+ constructor(response: Response, payload: unknown, requestMeta?: HttpErrorRequestMeta, options?: HttpClientErrorOptions);
210
243
  }
244
+ type HttpError = HttpAbortError | HttpInvokeError | HttpTimeoutError | HttpTransportError;
245
+ type VrpcError = HttpAbortError | HttpTimeoutError | HttpTransportError | VrpcInvokeError | VrpcProtocolError;
246
+ declare function isVrpcError(error: unknown): error is VrpcError;
211
247
  //#endregion
212
248
  //#region src/protocol/id.d.ts
213
249
  declare const DEFAULT_CLIENT_INSTANCE_ID_STORAGE_KEY = "vrpc-client-instance-id";
@@ -244,4 +280,4 @@ declare function createVrpcClient(options: VrpcClientOptions): VrpcClient;
244
280
  //#region src/transports/fetch-transport.d.ts
245
281
  declare function createFetchTransport(fetchImpl?: typeof fetch): HttpTransport;
246
282
  //#endregion
247
- export { type BuildVrpcHeadersOptions, DEFAULT_CLIENT_INSTANCE_ID_STORAGE_KEY, type GetClientInstanceIdOptions, HTTP_TIMEOUT_ERROR_CODE, type HttpClient, type HttpClientOptions, type HttpErrorPayload, type HttpInterceptor, type HttpInvokeContext, HttpInvokeError, type HttpQueryParams, type HttpQueryPrimitive, type HttpQueryValue, type HttpRequestConfig, type HttpRequestInit, type HttpRequestOptions, HttpTimeoutError, type HttpTransport, type HttpTransportRequest, type HttpTransportResponse, type ParsedVrpcErrorResponse, type ParsedVrpcResponse, type ParsedVrpcSuccessResponse, VRPC_CBOR_CONTENT_TYPE, VRPC_JSON_CONTENT_TYPE, type VrpcCborCodec, type VrpcClient, type VrpcClientInfo, type VrpcClientOptions, type VrpcErrorPayload, type VrpcInterceptor, type VrpcInterceptors, type VrpcInvokeContext, VrpcInvokeError, type VrpcInvokeRequest, type VrpcMethodWireSpec, type VrpcRequestInit, type VrpcRequestOptions, type VrpcResponseLike, type VrpcTrace, type VrpcTraceMode, type VrpcTransport, type VrpcTransportRequest, type VrpcTransportResponse, type VrpcWireSchema, buildVrpcHeaders, buildVrpcPath, buildVrpcRequestBody, createFetchTransport, createVrpcClient, decodeVrpcResponsePayload, encodeVrpcRequestBody, generateClientInstanceId, generateVrpcId, generateVrpcSpan, getClientInstanceId, parseVrpcResponse, unwrapVrpcResponse };
283
+ export { type BuildVrpcHeadersOptions, DEFAULT_CLIENT_INSTANCE_ID_STORAGE_KEY, type GetClientInstanceIdOptions, HTTP_TIMEOUT_ERROR_CODE, HttpAbortError, type HttpAbortErrorOptions, type HttpClient, HttpClientError, type HttpClientErrorKind, type HttpClientErrorOptions, type HttpClientOptions, type HttpError, type HttpErrorPayload, type HttpErrorRequestMeta, type HttpInterceptor, type HttpInvokeContext, HttpInvokeError, type HttpQueryParams, type HttpQueryPrimitive, type HttpQueryValue, type HttpRequestConfig, type HttpRequestInit, type HttpRequestOptions, HttpTimeoutError, type HttpTransport, HttpTransportError, type HttpTransportRequest, type HttpTransportResponse, type ParsedVrpcErrorResponse, type ParsedVrpcResponse, type ParsedVrpcSuccessResponse, VRPC_CBOR_CONTENT_TYPE, VRPC_JSON_CONTENT_TYPE, type VrpcCborCodec, type VrpcClient, type VrpcClientInfo, type VrpcClientOptions, type VrpcError, type VrpcErrorPayload, type VrpcInterceptor, type VrpcInterceptors, type VrpcInvokeContext, VrpcInvokeError, type VrpcInvokeRequest, type VrpcMethodWireSpec, VrpcProtocolError, type VrpcRequestInit, type VrpcRequestOptions, type VrpcResponseLike, type VrpcTrace, type VrpcTraceMode, type VrpcTransport, type VrpcTransportRequest, type VrpcTransportResponse, type VrpcWireSchema, buildVrpcHeaders, buildVrpcPath, buildVrpcRequestBody, createFetchTransport, createVrpcClient, decodeVrpcResponsePayload, encodeVrpcRequestBody, generateClientInstanceId, generateVrpcId, generateVrpcSpan, getClientInstanceId, isVrpcError, parseVrpcResponse, unwrapVrpcResponse };