@yorun-ai/vrpc 0.9.1 → 0.9.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTRIBUTING.md +24 -2
- package/README.md +147 -163
- package/README.zh-CN.md +128 -158
- package/dist/client.cjs +46 -24
- package/dist/client.d.cts +47 -11
- package/dist/client.d.ts +47 -11
- package/dist/client.es.js +42 -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 +46 -21
- package/docs/guides/cdn.md +221 -0
- package/docs/guides/usage.md +172 -7
- package/docs/maintainers/architecture.md +26 -4
- package/docs/maintainers/protocol.md +16 -1
- package/docs/reference/README.md +240 -0
- package/package.json +2 -2
package/README.zh-CN.md
CHANGED
|
@@ -1,14 +1,39 @@
|
|
|
1
1
|
# @yorun-ai/vrpc
|
|
2
2
|
|
|
3
|
+
[](https://www.npmjs.com/package/@yorun-ai/vrpc)
|
|
4
|
+
[](https://github.com/yorun-ai/vrpc-ts/actions/workflows/ci.yml)
|
|
5
|
+
[](https://packagephobia.com/result?p=%40yorun-ai%2Fvrpc)
|
|
6
|
+
[](https://www.npmjs.com/package/@yorun-ai/vrpc)
|
|
7
|
+
[](https://www.npmjs.com/package/@yorun-ai/vrpc)
|
|
8
|
+
[](https://github.com/yorun-ai/vrpc-ts/blob/main/LICENSE)
|
|
9
|
+
|
|
3
10
|
[English](README.md) | **简体中文**
|
|
4
11
|
|
|
5
|
-
用于 Vine vRPC 与通用 HTTP
|
|
12
|
+
用于 [Vine](https://github.com/yorun-ai/vine) vRPC 与通用 HTTP 请求的轻量 TypeScript 客户端运行时。
|
|
6
13
|
|
|
7
|
-
|
|
14
|
+
## 这是什么?
|
|
8
15
|
|
|
9
|
-
|
|
16
|
+
本包对外提供两种 client,它们共享同一套请求运行时:
|
|
17
|
+
|
|
18
|
+
- **vRPC client**:通过 HTTP 调用 Vine vRPC method。它会构造 vRPC path 与
|
|
19
|
+
envelope,生成 `vrpc-trace`、`vrpc-client`、`vrpc-options` Header,协商 JSON
|
|
20
|
+
或 CBOR,并规范化 vRPC 响应。
|
|
21
|
+
- **通用 HTTP client**:调用普通 HTTP API,提供统一配置、interceptor、timeout、
|
|
22
|
+
取消与规范化错误。它不感知 vRPC 协议。
|
|
10
23
|
|
|
11
|
-
|
|
24
|
+
服务端是 Vine vRPC service 时使用 vRPC client,其他场景使用通用 HTTP client。
|
|
25
|
+
两者都基于 Fetch,以浏览器为优先目标,并可在任何提供 `fetch` 的 JavaScript 运行时中运行。
|
|
26
|
+
|
|
27
|
+
## 特性
|
|
28
|
+
|
|
29
|
+
- TypeScript 优先的 API,每个入口都发布类型声明。
|
|
30
|
+
- 基于浏览器 Fetch 的 transport,可替换为自定义 transport。
|
|
31
|
+
- 同时提供 Vine vRPC 与通用 HTTP 两种 client。
|
|
32
|
+
- client 级默认值与单次请求覆盖。
|
|
33
|
+
- 支持请求、响应、错误生命周期的 interceptor。
|
|
34
|
+
- 规范化且可分类的错误,以及 `AbortSignal` 取消。
|
|
35
|
+
- 通过用户提供的 codec 可选集成 CBOR,不内置任何 codec 依赖。
|
|
36
|
+
- 提供 ESM 与 CommonJS 构建,并支持浏览器 ES module CDN 用法。
|
|
12
37
|
|
|
13
38
|
## 安装
|
|
14
39
|
|
|
@@ -16,20 +41,19 @@
|
|
|
16
41
|
pnpm add @yorun-ai/vrpc
|
|
17
42
|
```
|
|
18
43
|
|
|
19
|
-
|
|
44
|
+
```bash
|
|
45
|
+
npm install @yorun-ai/vrpc
|
|
46
|
+
```
|
|
20
47
|
|
|
21
|
-
|
|
22
|
-
- `@yorun-ai/vrpc/http`:通用 HTTP client。
|
|
48
|
+
## 快速开始
|
|
23
49
|
|
|
24
|
-
|
|
50
|
+
### 1. 调用一个 vRPC method
|
|
25
51
|
|
|
26
52
|
```ts
|
|
27
|
-
import {
|
|
53
|
+
import { createVrpcClient, getClientInstanceId } from "@yorun-ai/vrpc";
|
|
28
54
|
|
|
29
55
|
const client = createVrpcClient({
|
|
30
56
|
prefixUrl: "https://api.example.com/invoke",
|
|
31
|
-
timeoutMs: 15_000,
|
|
32
|
-
suppressGlobalToast: false,
|
|
33
57
|
clientInfo: {
|
|
34
58
|
clientName: "demo.browser",
|
|
35
59
|
clientVersion: "1.0.0",
|
|
@@ -37,194 +61,140 @@ const client = createVrpcClient({
|
|
|
37
61
|
},
|
|
38
62
|
});
|
|
39
63
|
|
|
40
|
-
client.use({
|
|
41
|
-
onError(error, context) {
|
|
42
|
-
if (context.options.suppressGlobalToast) {
|
|
43
|
-
return;
|
|
44
|
-
}
|
|
45
|
-
console.error(error);
|
|
46
|
-
},
|
|
47
|
-
});
|
|
48
|
-
|
|
49
64
|
const profile = await client.invoke<{ id: number; name: string }>({
|
|
50
65
|
serviceName: "user.UserService",
|
|
51
66
|
methodName: "getProfile",
|
|
52
67
|
params: { userId: 1 },
|
|
53
|
-
options: {
|
|
54
|
-
timeoutMs: 3_000,
|
|
55
|
-
suppressGlobalToast: true,
|
|
56
|
-
},
|
|
57
68
|
});
|
|
58
|
-
|
|
59
|
-
// 无参 method 可以传 null 或空对象。
|
|
60
|
-
await client.invoke({
|
|
61
|
-
serviceName: "user.UserService",
|
|
62
|
-
methodName: "ping",
|
|
63
|
-
params: null,
|
|
64
|
-
});
|
|
65
|
-
|
|
66
|
-
try {
|
|
67
|
-
await client.invoke({
|
|
68
|
-
serviceName: "user.UserService",
|
|
69
|
-
methodName: "missing",
|
|
70
|
-
params: {},
|
|
71
|
-
});
|
|
72
|
-
} catch (error) {
|
|
73
|
-
if (error instanceof VrpcInvokeError) {
|
|
74
|
-
console.error(error.status, error.vrpcStatus, error.code, error.reason);
|
|
75
|
-
}
|
|
76
|
-
}
|
|
77
69
|
```
|
|
78
70
|
|
|
79
|
-
|
|
71
|
+
最终 URL 为 `<prefixUrl>/<serviceName>/<methodName>`。无参 method 可以传
|
|
72
|
+
`params: null` 或 `params: {}`。
|
|
80
73
|
|
|
81
|
-
###
|
|
74
|
+
### 2. 调用普通 HTTP API
|
|
82
75
|
|
|
83
76
|
```ts
|
|
84
|
-
|
|
85
|
-
headers?: HeadersInit;
|
|
86
|
-
timeoutMs?: number;
|
|
87
|
-
requestInit?: Omit<RequestInit, "method" | "body" | "headers">;
|
|
88
|
-
suppressGlobalToast?: boolean;
|
|
89
|
-
trace?: { id: string; span?: string };
|
|
90
|
-
wire?: VrpcMethodWireSpec;
|
|
91
|
-
};
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
- create 时的 `suppressGlobalToast` 是默认值,单次调用的 `true` 或 `false` 会覆盖它。
|
|
95
|
-
- `timeoutMs` 默认不启用;未配置时内置 transport 不创建本地 timeout,也不发送 `vrpc-options`。
|
|
96
|
-
- `wire` 只能用于单次调用,并且不会进入 HTTP payload。
|
|
97
|
-
- 无参 method 兼容 `params: null` 和 `params: {}`。
|
|
98
|
-
- 浏览器 transport 默认 `credentials: "omit"`;需要 cookie 时使用 `requestInit.credentials`。
|
|
77
|
+
import { createHttpClient } from "@yorun-ai/vrpc/http";
|
|
99
78
|
|
|
100
|
-
|
|
79
|
+
const http = createHttpClient({
|
|
80
|
+
prefixUrl: "https://api.example.com",
|
|
81
|
+
timeoutMs: 5_000,
|
|
82
|
+
});
|
|
101
83
|
|
|
102
|
-
|
|
84
|
+
const profile = await http.request<{ id: number }>({ path: "/users/me" });
|
|
103
85
|
|
|
104
|
-
|
|
105
|
-
|
|
86
|
+
await http.request({
|
|
87
|
+
path: "/users",
|
|
88
|
+
method: "POST",
|
|
89
|
+
json: { name: "Vine" },
|
|
90
|
+
});
|
|
91
|
+
```
|
|
106
92
|
|
|
107
|
-
|
|
108
|
-
kind: "object",
|
|
109
|
-
fields: {
|
|
110
|
-
content: { kind: "binary" },
|
|
111
|
-
},
|
|
112
|
-
};
|
|
93
|
+
JSON 请求体使用 `json`,`FormData` 等原始 `BodyInit` 使用 `body`。
|
|
113
94
|
|
|
114
|
-
|
|
115
|
-
encode: (value) => yourCborLibrary.encode(value),
|
|
116
|
-
decode: (bytes) => yourCborLibrary.decode(bytes),
|
|
117
|
-
};
|
|
95
|
+
### 3. 处理错误
|
|
118
96
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
clientInfo: {
|
|
122
|
-
clientName: "demo.browser",
|
|
123
|
-
clientVersion: "1.0.0",
|
|
124
|
-
clientInstanceId: getClientInstanceId(),
|
|
125
|
-
},
|
|
126
|
-
cborCodec,
|
|
127
|
-
});
|
|
97
|
+
```ts
|
|
98
|
+
import { isVrpcError } from "@yorun-ai/vrpc";
|
|
128
99
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
100
|
+
try {
|
|
101
|
+
await client.invoke({
|
|
102
|
+
serviceName: "user.UserService",
|
|
103
|
+
methodName: "getProfile",
|
|
104
|
+
params: { userId: 1 },
|
|
105
|
+
});
|
|
106
|
+
} catch (error) {
|
|
107
|
+
if (isVrpcError(error) && error.kind === "invoke") {
|
|
108
|
+
// 服务端拒绝了本次调用。
|
|
109
|
+
console.error(error.vrpcStatus, error.code, error.reason);
|
|
110
|
+
}
|
|
111
|
+
}
|
|
137
112
|
```
|
|
138
113
|
|
|
139
|
-
|
|
114
|
+
通用 HTTP client 提供等价的 `isHttpError`。
|
|
140
115
|
|
|
141
|
-
|
|
142
|
-
- `wire.result`:`accept` 使用 `application/vrpc+cbor, application/vrpc+json`。
|
|
143
|
-
- 两者都没有:JSON。
|
|
144
|
-
- wire 存在但没有 `cborCodec`:在网络请求前抛出配置错误。
|
|
116
|
+
## 浏览器 CDN
|
|
145
117
|
|
|
146
|
-
|
|
118
|
+
不想安装依赖或配置打包工具时,可以直接使用发布的 ES module 构建:
|
|
147
119
|
|
|
148
|
-
|
|
120
|
+
```html
|
|
121
|
+
<script type="module">
|
|
122
|
+
import { createVrpcClient } from "https://cdn.jsdelivr.net/npm/@yorun-ai/vrpc@0.9.3/+esm";
|
|
149
123
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
```text
|
|
153
|
-
content-type: application/vrpc+json
|
|
154
|
-
accept: application/vrpc+json
|
|
155
|
-
vrpc-trace: id=<32hex>
|
|
156
|
-
vrpc-client: name=demo.browser,version=1.0.0,instanceId=<uuid>
|
|
157
|
-
vrpc-options: timeout=3000ms
|
|
124
|
+
// ...
|
|
125
|
+
</script>
|
|
158
126
|
```
|
|
159
127
|
|
|
160
|
-
|
|
128
|
+
本包只发布 ES module,没有 global 构建,因此不能使用经典
|
|
129
|
+
`<script src="...">` 标签,标签必须带 `type="module"`。
|
|
161
130
|
|
|
162
|
-
|
|
131
|
+
完整 HTML 示例、通用 HTTP 入口、版本固定与常见问题见
|
|
132
|
+
[Browser CDN 使用指南](docs/guides/cdn.md)。
|
|
163
133
|
|
|
164
|
-
|
|
165
|
-
import { createHttpClient } from "@yorun-ai/vrpc/http";
|
|
134
|
+
## 入口
|
|
166
135
|
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
136
|
+
| Import | 内容 |
|
|
137
|
+
| ----------------------- | ---------------------------------------------------- |
|
|
138
|
+
| `@yorun-ai/vrpc` | vRPC client、协议 helper、transport、错误与类型。 |
|
|
139
|
+
| `@yorun-ai/vrpc/client` | 显式 vRPC 入口,与包根入口一致。 |
|
|
140
|
+
| `@yorun-ai/vrpc/http` | 通用 HTTP client、Fetch transport、HTTP 错误与类型。 |
|
|
171
141
|
|
|
172
|
-
|
|
173
|
-
path: "/users/me",
|
|
174
|
-
query: { withProfile: true },
|
|
175
|
-
options: {
|
|
176
|
-
requestInit: { credentials: "include" },
|
|
177
|
-
suppressGlobalToast: true,
|
|
178
|
-
},
|
|
179
|
-
});
|
|
142
|
+
## 配置概览
|
|
180
143
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
});
|
|
186
|
-
```
|
|
144
|
+
两种 client 都接受 `prefixUrl`、`headers`、`timeoutMs`、`requestInit`、
|
|
145
|
+
`suppressGlobalToast`、`fetchImpl`、`transport` 和 `interceptors`。vRPC client
|
|
146
|
+
额外要求 `clientInfo`,并接受 `traceMode` 与 `cborCodec`。单次请求的 `options`
|
|
147
|
+
会覆盖 client 默认值,`context.options` 始终是合并后的结果。
|
|
187
148
|
|
|
188
|
-
|
|
149
|
+
vRPC client 还提供两个请求选项:`trace` 覆盖自动生成的 `vrpc-trace` Header,
|
|
150
|
+
`wire` 为单次调用选择 JSON 或 CBOR。wire schema 永远不会被序列化进 HTTP body,
|
|
151
|
+
但使用它必须配置 `cborCodec`。
|
|
189
152
|
|
|
190
|
-
##
|
|
153
|
+
## 进阶能力
|
|
191
154
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
clientInstanceId: getClientInstanceId(),
|
|
205
|
-
},
|
|
206
|
-
trace: { id: generateVrpcId() },
|
|
207
|
-
timeoutMs: 3_000,
|
|
208
|
-
});
|
|
155
|
+
- **Interceptor**:通过 `client.use()` 注册 `beforeRequest`、`afterResponse`
|
|
156
|
+
和 `onError`。`onError` 在请求 Promise reject 之前执行,且不会吞掉错误。
|
|
157
|
+
- **取消请求**:通过 `requestInit.signal` 传入 `AbortSignal`。取消会 reject
|
|
158
|
+
一个 `kind` 为 `"abort"` 的错误;超时保持 `kind: "timeout"`。
|
|
159
|
+
- **Trace**:`traceMode: "portal"`(默认)只生成 trace id,
|
|
160
|
+
`traceMode: "direct"` 还会生成 span。它不会改变路由或 `prefixUrl`。
|
|
161
|
+
- **CBOR**:当 arguments 或 result 含 `Binary` 时,提供 `cborCodec` 与单次调用的
|
|
162
|
+
`wire` schema。
|
|
163
|
+
- **自定义 transport**:实现 `VrpcTransport` 或 `HttpTransport`,用其他 I/O 层
|
|
164
|
+
替换 Fetch。
|
|
165
|
+
- **`suppressGlobalToast`**:应用自定义错误 UI 的策略元数据。包本身不会展示 UI、
|
|
166
|
+
不会跳过 `onError`,也不会吞掉 reject。
|
|
209
167
|
|
|
210
|
-
|
|
211
|
-
const body = buildVrpcRequestBody({ userId: 1 });
|
|
212
|
-
```
|
|
168
|
+
每项能力的具体示例见 [Usage 指南](docs/guides/usage.md)。
|
|
213
169
|
|
|
214
170
|
## 文档
|
|
215
171
|
|
|
216
|
-
|
|
172
|
+
### 使用指南
|
|
173
|
+
|
|
174
|
+
- [Usage(English)](docs/guides/usage.md):client 配置、请求选项、interceptor、
|
|
175
|
+
错误、取消、CBOR 与自定义 transport。
|
|
176
|
+
- [Browser CDN(English)](docs/guides/cdn.md):CDN 加载方式与完整 HTML 示例。
|
|
177
|
+
- [Axios integration(English)](docs/guides/axios.md):自定义 Axios transport 与
|
|
178
|
+
JSON 协议 helper。
|
|
217
179
|
|
|
218
|
-
|
|
219
|
-
- [Axios integration(English)](./docs/guides/axios.md):自定义 Axios transport 与 JSON 协议 helper。
|
|
180
|
+
### Reference 与维护者文档
|
|
220
181
|
|
|
221
|
-
|
|
182
|
+
- [API Reference(English)](docs/reference/README.md):公开导出、类型、配置项、
|
|
183
|
+
默认值与错误。
|
|
184
|
+
- [Architecture(English)](docs/maintainers/architecture.md):模块边界与请求数据流。
|
|
185
|
+
- [vRPC protocol(English)](docs/maintainers/protocol.md):path、envelope、Header、
|
|
186
|
+
内容协商、wire schema 与生成 client 的要求。
|
|
187
|
+
- [Releasing(English)](docs/maintainers/releasing.md):版本管理与 npm 发布流程。
|
|
188
|
+
- [Contributing(English)](CONTRIBUTING.md):开发、测试、文档与 PR 流程。
|
|
222
189
|
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
190
|
+
根 README 与 `docs/guides/` 面向包使用者;`docs/maintainers/` 面向仓库维护者,
|
|
191
|
+
以及需要实现 transport 或 codegen 的接入方。
|
|
192
|
+
|
|
193
|
+
## 稳定性
|
|
226
194
|
|
|
227
|
-
|
|
195
|
+
本包处于 `0.x` 发布阶段,已经可以使用,但 `1.0.0` 之前暂不承诺公开 API 稳定。
|
|
196
|
+
不兼容的变更可以随新的 `0.x` minor 版本发布,并会提供迁移说明;`1.0.0` 将作为
|
|
197
|
+
稳定 API 承诺的起点。
|
|
228
198
|
|
|
229
199
|
## License
|
|
230
200
|
|
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-
|
|
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(
|
|
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,34 @@ 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
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
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
|
+
const message = cause instanceof Error ? cause.message : "Invalid vRPC response.";
|
|
263
|
+
throw new require_request_options.VrpcProtocolError(response, message, {}, { cause });
|
|
248
264
|
}
|
|
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
265
|
}
|
|
260
266
|
function normalizeResponseHeaders(headers) {
|
|
261
267
|
if (!headers) return new Headers();
|
|
@@ -417,7 +423,18 @@ function createVrpcClient(options) {
|
|
|
417
423
|
}
|
|
418
424
|
};
|
|
419
425
|
},
|
|
420
|
-
parseResponse: (response, context) =>
|
|
426
|
+
parseResponse: async (response, context) => {
|
|
427
|
+
try {
|
|
428
|
+
return await decodeVrpcResponsePayload(response, cborCodec, context.options.wire?.result);
|
|
429
|
+
} catch (cause) {
|
|
430
|
+
const vrpcStatus = response.headers.get("vrpc-status");
|
|
431
|
+
if (vrpcStatus && (!response.ok || vrpcStatus !== "OK")) throw new require_request_options.VrpcInvokeError(response, null, {
|
|
432
|
+
url: context.url,
|
|
433
|
+
method: String(context.init.method || "POST").toUpperCase()
|
|
434
|
+
}, { cause });
|
|
435
|
+
throw cause;
|
|
436
|
+
}
|
|
437
|
+
},
|
|
421
438
|
validateRequest: (_context, requestMeta) => {
|
|
422
439
|
if (requestMeta.method !== "POST") throw new Error(`Unsupported method: ${requestMeta.method}, only POST is allowed.`);
|
|
423
440
|
},
|
|
@@ -442,11 +459,15 @@ function createVrpcClient(options) {
|
|
|
442
459
|
//#endregion
|
|
443
460
|
exports.DEFAULT_CLIENT_INSTANCE_ID_STORAGE_KEY = DEFAULT_CLIENT_INSTANCE_ID_STORAGE_KEY;
|
|
444
461
|
exports.HTTP_TIMEOUT_ERROR_CODE = require_request_options.HTTP_TIMEOUT_ERROR_CODE;
|
|
462
|
+
exports.HttpAbortError = require_request_options.HttpAbortError;
|
|
463
|
+
exports.HttpClientError = require_request_options.HttpClientError;
|
|
445
464
|
exports.HttpInvokeError = require_request_options.HttpInvokeError;
|
|
446
465
|
exports.HttpTimeoutError = require_request_options.HttpTimeoutError;
|
|
466
|
+
exports.HttpTransportError = require_request_options.HttpTransportError;
|
|
447
467
|
exports.VRPC_CBOR_CONTENT_TYPE = VRPC_CBOR_CONTENT_TYPE;
|
|
448
468
|
exports.VRPC_JSON_CONTENT_TYPE = VRPC_JSON_CONTENT_TYPE;
|
|
449
469
|
exports.VrpcInvokeError = require_request_options.VrpcInvokeError;
|
|
470
|
+
exports.VrpcProtocolError = require_request_options.VrpcProtocolError;
|
|
450
471
|
exports.buildVrpcHeaders = buildVrpcHeaders;
|
|
451
472
|
exports.buildVrpcPath = buildVrpcPath;
|
|
452
473
|
exports.buildVrpcRequestBody = buildVrpcRequestBody;
|
|
@@ -458,5 +479,6 @@ exports.generateClientInstanceId = generateClientInstanceId;
|
|
|
458
479
|
exports.generateVrpcId = generateVrpcId;
|
|
459
480
|
exports.generateVrpcSpan = generateVrpcSpan;
|
|
460
481
|
exports.getClientInstanceId = getClientInstanceId;
|
|
482
|
+
exports.isVrpcError = require_request_options.isVrpcError;
|
|
461
483
|
exports.parseVrpcResponse = parseVrpcResponse;
|
|
462
484
|
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
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
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
|
|
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
|
-
|
|
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 };
|