@yorun-ai/vrpc 0.9.2 → 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 +132 -248
- package/README.zh-CN.md +112 -242
- package/dist/client.cjs +2 -1
- package/dist/client.es.js +2 -1
- package/docs/guides/axios.md +3 -0
- package/docs/guides/cdn.md +221 -0
- package/docs/guides/usage.md +5 -0
- package/docs/reference/README.md +240 -0
- package/package.json +2 -2
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
# Browser CDN usage
|
|
2
|
+
|
|
3
|
+
This guide shows how to use `@yorun-ai/vrpc` from a CDN in a plain HTML page,
|
|
4
|
+
without a bundler or a package install. For packaged applications, prefer the
|
|
5
|
+
npm installation and the [Usage guide](./usage.md).
|
|
6
|
+
|
|
7
|
+
## 1. Overview
|
|
8
|
+
|
|
9
|
+
Use the CDN builds when you want to:
|
|
10
|
+
|
|
11
|
+
- prototype against a real vRPC or HTTP endpoint from a static page,
|
|
12
|
+
- embed the client in a CodePen, JSFiddle, or documentation snippet,
|
|
13
|
+
- keep a small internal tool free of a build step.
|
|
14
|
+
|
|
15
|
+
Two constraints apply to every CDN setup:
|
|
16
|
+
|
|
17
|
+
- **ES modules only.** The published package ships ES module and CommonJS
|
|
18
|
+
builds, not an IIFE/UMD bundle. There is no `window.Vrpc` or `window.Http`
|
|
19
|
+
global, and a classic `<script src="...">` without `type="module"` fails with
|
|
20
|
+
a syntax error because the file contains `import` statements.
|
|
21
|
+
- **Pin the version.** Use an exact version such as `@0.9.3` so a new release
|
|
22
|
+
cannot change the behavior of a page you already published.
|
|
23
|
+
|
|
24
|
+
The runtime needs native ES modules, `fetch`, `AbortController`, and `Headers`.
|
|
25
|
+
All current evergreen browsers provide these.
|
|
26
|
+
|
|
27
|
+
## 2. Available bundles
|
|
28
|
+
|
|
29
|
+
| Import | File | Format |
|
|
30
|
+
| ------------------------------ | ------------------- | -------------------------------------------------------- |
|
|
31
|
+
| vRPC client + protocol helpers | `dist/client.es.js` | ES module; imports one relative shared chunk |
|
|
32
|
+
| Generic HTTP client | `dist/http.es.js` | ES module; imports the same shared chunk |
|
|
33
|
+
| vRPC client (bundled) | `+esm` | ES module; single self-contained file, no extra requests |
|
|
34
|
+
| Generic HTTP client (bundled) | `/http/+esm` | ES module; single self-contained file, no extra requests |
|
|
35
|
+
|
|
36
|
+
Notes:
|
|
37
|
+
|
|
38
|
+
- `dist/client.cjs` and `dist/http.cjs` are CommonJS builds and cannot be
|
|
39
|
+
loaded directly by a browser.
|
|
40
|
+
- `dist/client.es.min.js` and `dist/http.es.min.js` are minified on demand by
|
|
41
|
+
jsDelivr from the published `.es.js` files. They are still ES modules, and
|
|
42
|
+
because they are generated they must not be used with subresource integrity
|
|
43
|
+
hashes.
|
|
44
|
+
- `dist/client.es.js` and `dist/http.es.js` import a build-specific shared chunk
|
|
45
|
+
whose name changes on every release. Do not copy a chunk filename into your
|
|
46
|
+
page; import the entry file and let the browser resolve it, or use `+esm` to
|
|
47
|
+
avoid the extra request entirely.
|
|
48
|
+
|
|
49
|
+
## 3. Loading the module
|
|
50
|
+
|
|
51
|
+
Browser ESM with jsDelivr:
|
|
52
|
+
|
|
53
|
+
```html
|
|
54
|
+
<script type="module">
|
|
55
|
+
import { createVrpcClient } from "https://cdn.jsdelivr.net/npm/@yorun-ai/vrpc@0.9.3/+esm";
|
|
56
|
+
|
|
57
|
+
// ...
|
|
58
|
+
</script>
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The same API is available from the unbundled entry file:
|
|
62
|
+
|
|
63
|
+
```html
|
|
64
|
+
<script type="module">
|
|
65
|
+
import { createVrpcClient } from "https://cdn.jsdelivr.net/npm/@yorun-ai/vrpc@0.9.3/dist/client.es.js";
|
|
66
|
+
</script>
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Import the HTTP client from its own module path:
|
|
70
|
+
|
|
71
|
+
```html
|
|
72
|
+
<script type="module">
|
|
73
|
+
import { createHttpClient } from "https://cdn.jsdelivr.net/npm/@yorun-ai/vrpc@0.9.3/http/+esm";
|
|
74
|
+
</script>
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
This form does **not** work, because the bundle is an ES module:
|
|
78
|
+
|
|
79
|
+
```html
|
|
80
|
+
<!-- Fails: the runtime has no global build. -->
|
|
81
|
+
<script src="https://cdn.jsdelivr.net/npm/@yorun-ai/vrpc@0.9.3/dist/client.es.js"></script>
|
|
82
|
+
<script>
|
|
83
|
+
const client = Vrpc.createVrpcClient({/* ... */}); // Vrpc is undefined
|
|
84
|
+
</script>
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## 4. Complete vRPC example
|
|
88
|
+
|
|
89
|
+
Save this as `vrpc-demo.html` and open it in a browser. It creates a client,
|
|
90
|
+
invokes a method, and renders either the result or a classified error.
|
|
91
|
+
|
|
92
|
+
```html
|
|
93
|
+
<!doctype html>
|
|
94
|
+
<html lang="en">
|
|
95
|
+
<head>
|
|
96
|
+
<meta charset="utf-8" />
|
|
97
|
+
<title>vRPC CDN demo</title>
|
|
98
|
+
</head>
|
|
99
|
+
<body>
|
|
100
|
+
<pre id="output">loading…</pre>
|
|
101
|
+
|
|
102
|
+
<script type="module">
|
|
103
|
+
import {
|
|
104
|
+
createVrpcClient,
|
|
105
|
+
getClientInstanceId,
|
|
106
|
+
isVrpcError,
|
|
107
|
+
} from "https://cdn.jsdelivr.net/npm/@yorun-ai/vrpc@0.9.3/+esm";
|
|
108
|
+
|
|
109
|
+
const output = document.getElementById("output");
|
|
110
|
+
|
|
111
|
+
const client = createVrpcClient({
|
|
112
|
+
prefixUrl: "https://api.example.com/invoke",
|
|
113
|
+
clientInfo: {
|
|
114
|
+
clientName: "demo.browser",
|
|
115
|
+
clientVersion: "1.0.0",
|
|
116
|
+
clientInstanceId: getClientInstanceId(),
|
|
117
|
+
},
|
|
118
|
+
});
|
|
119
|
+
|
|
120
|
+
try {
|
|
121
|
+
const profile = await client.invoke({
|
|
122
|
+
serviceName: "user.UserService",
|
|
123
|
+
methodName: "getProfile",
|
|
124
|
+
params: { userId: 1 },
|
|
125
|
+
});
|
|
126
|
+
output.textContent = JSON.stringify(profile, null, 2);
|
|
127
|
+
} catch (error) {
|
|
128
|
+
if (!isVrpcError(error)) {
|
|
129
|
+
output.textContent = String(error);
|
|
130
|
+
} else if (error.kind === "invoke") {
|
|
131
|
+
output.textContent = `${error.vrpcStatus} ${error.code} ${error.reason}`;
|
|
132
|
+
} else {
|
|
133
|
+
output.textContent = `${error.kind}: ${error.message}`;
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
</script>
|
|
137
|
+
</body>
|
|
138
|
+
</html>
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Top-level `await` is valid inside a module script, so no wrapper function is
|
|
142
|
+
required.
|
|
143
|
+
|
|
144
|
+
## 5. Complete HTTP example
|
|
145
|
+
|
|
146
|
+
The generic HTTP client is a separate module and does not use vRPC protocol
|
|
147
|
+
headers.
|
|
148
|
+
|
|
149
|
+
```html
|
|
150
|
+
<!doctype html>
|
|
151
|
+
<html lang="en">
|
|
152
|
+
<head>
|
|
153
|
+
<meta charset="utf-8" />
|
|
154
|
+
<title>HTTP CDN demo</title>
|
|
155
|
+
</head>
|
|
156
|
+
<body>
|
|
157
|
+
<pre id="output">loading…</pre>
|
|
158
|
+
|
|
159
|
+
<script type="module">
|
|
160
|
+
import {
|
|
161
|
+
createHttpClient,
|
|
162
|
+
isHttpError,
|
|
163
|
+
} from "https://cdn.jsdelivr.net/npm/@yorun-ai/vrpc@0.9.3/http/+esm";
|
|
164
|
+
|
|
165
|
+
const output = document.getElementById("output");
|
|
166
|
+
|
|
167
|
+
const http = createHttpClient({
|
|
168
|
+
prefixUrl: "https://api.example.com",
|
|
169
|
+
timeoutMs: 5_000,
|
|
170
|
+
});
|
|
171
|
+
|
|
172
|
+
try {
|
|
173
|
+
const profile = await http.request({ path: "/users/me" });
|
|
174
|
+
output.textContent = JSON.stringify(profile, null, 2);
|
|
175
|
+
} catch (error) {
|
|
176
|
+
output.textContent = isHttpError(error) ? `${error.kind}: ${error.message}` : String(error);
|
|
177
|
+
}
|
|
178
|
+
</script>
|
|
179
|
+
</body>
|
|
180
|
+
</html>
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
## 6. Version pinning
|
|
184
|
+
|
|
185
|
+
Always pin an exact version in the URL:
|
|
186
|
+
|
|
187
|
+
```text
|
|
188
|
+
https://cdn.jsdelivr.net/npm/@yorun-ai/vrpc@0.9.3/+esm
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
`@0.9.3` is immutable on jsDelivr. A floating range such as `@0` resolves to the
|
|
192
|
+
newest `0.x` release and can pick up behavior changes; use it only for a
|
|
193
|
+
throwaway prototype. Keep the pinned version aligned with the version in your
|
|
194
|
+
`package.json` when the same project uses both.
|
|
195
|
+
|
|
196
|
+
## 7. Troubleshooting
|
|
197
|
+
|
|
198
|
+
| Symptom | Cause and fix |
|
|
199
|
+
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
200
|
+
| `Cannot use import statement outside a module` | The script tag is missing `type="module"`. |
|
|
201
|
+
| `window.Vrpc is undefined` / `window.Http is undefined` | There is no global build. Import the module instead. |
|
|
202
|
+
| `Failed to resolve module specifier` | A bare specifier such as `@yorun-ai/vrpc` was used in a browser import without a CDN URL or an import map. |
|
|
203
|
+
| `404` when importing the shared chunk | A hashed chunk filename was copied into a page. Import `dist/client.es.js` / `dist/http.es.js` and let the browser resolve it, or use `+esm`. |
|
|
204
|
+
| Blocked by CORS | The target API must return `Access-Control-Allow-Origin`. Cookies additionally require `requestInit: { credentials: "include" }` on the client and `Access-Control-Allow-Credentials: true` on the server. |
|
|
205
|
+
| Unexpected behavior after a release | The CDN URL is not pinned to an exact version. |
|
|
206
|
+
| `fetch is not available in current runtime` | The page runs in an environment without a global `fetch`, such as a very old browser. |
|
|
207
|
+
| An interceptor is never called | `client.use(...)` must be called on the same client instance that performs the request. |
|
|
208
|
+
|
|
209
|
+
For protocol-level failures such as a missing `vrpc-status` or `vrpc-server`
|
|
210
|
+
header, see the [vRPC protocol](../maintainers/protocol.md) reference.
|
|
211
|
+
|
|
212
|
+
## 8. Verification status
|
|
213
|
+
|
|
214
|
+
The examples in this guide were checked against the `0.9.3` bundle in a real
|
|
215
|
+
browser: the bundled `+esm` imports, the unbundled `dist/*.es.js` entry files,
|
|
216
|
+
and the jsDelivr-generated `dist/*.es.min.js` variants all load as ES modules
|
|
217
|
+
and complete a real invocation. Loading any of them as a classic script fails,
|
|
218
|
+
and no global variable is created.
|
|
219
|
+
|
|
220
|
+
Each version ships its own build, so re-check these loading modes when you move
|
|
221
|
+
the pinned version.
|
package/docs/guides/usage.md
CHANGED
|
@@ -1,5 +1,10 @@
|
|
|
1
1
|
# Usage
|
|
2
2
|
|
|
3
|
+
This guide is the canonical reference for client configuration and extension
|
|
4
|
+
points. For a no-build browser setup see [Browser CDN usage](./cdn.md), for the
|
|
5
|
+
public API surface see the [API Reference](../reference/README.md), and for
|
|
6
|
+
wire-level details see the [vRPC protocol](../maintainers/protocol.md).
|
|
7
|
+
|
|
3
8
|
## 1. Generic HTTP client
|
|
4
9
|
|
|
5
10
|
```ts
|
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
# API Reference
|
|
2
|
+
|
|
3
|
+
Public exports of the published `@yorun-ai/vrpc` package. For task-oriented
|
|
4
|
+
guidance, start with the [Usage guide](../guides/usage.md); for wire-level
|
|
5
|
+
details, see the [vRPC protocol](../maintainers/protocol.md).
|
|
6
|
+
|
|
7
|
+
Everything listed here is exported from `src/entrypoints/`. Anything not listed
|
|
8
|
+
is internal and may change in any release.
|
|
9
|
+
|
|
10
|
+
## Package entry points
|
|
11
|
+
|
|
12
|
+
| Import | Contents |
|
|
13
|
+
| ----------------------- | ------------------------------------------------------------------------ |
|
|
14
|
+
| `@yorun-ai/vrpc` | Identical to `@yorun-ai/vrpc/client`. |
|
|
15
|
+
| `@yorun-ai/vrpc/client` | vRPC client, protocol helpers, id helpers, transport, errors, and types. |
|
|
16
|
+
| `@yorun-ai/vrpc/http` | Generic HTTP client, Fetch transport, HTTP errors, and HTTP types. |
|
|
17
|
+
|
|
18
|
+
Each entry point publishes an ESM build (`import`), a CommonJS build
|
|
19
|
+
(`require`), and matching type declarations.
|
|
20
|
+
|
|
21
|
+
## Client factories
|
|
22
|
+
|
|
23
|
+
### `createVrpcClient(options)`
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
function createVrpcClient(options: VrpcClientOptions): VrpcClient;
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
| Option | Type | Default | Notes |
|
|
30
|
+
| --------------------- | ---------------------------------------------------- | --------------- | ----------------------------------------------------------------------------- |
|
|
31
|
+
| `prefixUrl` | `string \| URL` | required | Base URL. The runtime appends `/<serviceName>/<methodName>`. |
|
|
32
|
+
| `clientInfo` | `VrpcClientInfo` | required | Sent as `vrpc-client`; see the validation rules below. |
|
|
33
|
+
| `traceMode` | `"portal" \| "direct"` | `"portal"` | Controls only the generated `vrpc-trace` header. |
|
|
34
|
+
| `cborCodec` | `VrpcCborCodec` | — | Required when a request supplies `options.wire`. |
|
|
35
|
+
| `headers` | `HeadersInit` | — | Cannot override `accept`, `content-type`, or any `vrpc-*` header. |
|
|
36
|
+
| `timeoutMs` | `number` | — | Client default for the local timer and `vrpc-options`. Disabled when omitted. |
|
|
37
|
+
| `requestInit` | `Omit<RequestInit, "method" \| "body" \| "headers">` | — | Merged per request. |
|
|
38
|
+
| `suppressGlobalToast` | `boolean` | — | Interceptor-only metadata; a per-request value overrides it. |
|
|
39
|
+
| `fetchImpl` | `typeof fetch` | global `fetch` | Custom Fetch implementation for the built-in transport. |
|
|
40
|
+
| `transport` | `VrpcTransport` | Fetch transport | Replaces the built-in transport. |
|
|
41
|
+
| `interceptors` | `VrpcInterceptor[]` | `[]` | Same as calling `client.use()` for each entry. |
|
|
42
|
+
|
|
43
|
+
`VrpcClientInfo` fields are validated before the request is sent:
|
|
44
|
+
|
|
45
|
+
- `clientName`: lower-case dot-separated identifier, for example `demo.browser`.
|
|
46
|
+
- `clientVersion`: valid SemVer, for example `1.0.0`.
|
|
47
|
+
- `clientInstanceId`: UUID, for example from `getClientInstanceId()`.
|
|
48
|
+
|
|
49
|
+
### `client.invoke(request)`
|
|
50
|
+
|
|
51
|
+
```ts
|
|
52
|
+
client.invoke<TResponse = unknown>(request: VrpcInvokeRequest): Promise<TResponse>;
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
`VrpcInvokeRequest`:
|
|
56
|
+
|
|
57
|
+
| Field | Type | Notes |
|
|
58
|
+
| ------------- | --------------------------------- | --------------------------------------------------------------- |
|
|
59
|
+
| `serviceName` | `string` | Encoded into the request path. |
|
|
60
|
+
| `methodName` | `string` | Encoded into the request path. |
|
|
61
|
+
| `params` | `Record<string, unknown> \| null` | Required. Both `null` and `{}` are accepted for no-arg methods. |
|
|
62
|
+
| `options` | `VrpcRequestOptions` | Optional per-request overrides. |
|
|
63
|
+
|
|
64
|
+
The returned promise resolves to the envelope `result` and rejects with a
|
|
65
|
+
`VrpcError` (or an ordinary developer error for invalid configuration). vRPC
|
|
66
|
+
always uses `POST`.
|
|
67
|
+
|
|
68
|
+
### `createHttpClient(options)`
|
|
69
|
+
|
|
70
|
+
```ts
|
|
71
|
+
function createHttpClient(options: HttpClientOptions): HttpClient;
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
| Option | Type | Default | Notes |
|
|
75
|
+
| --------------------- | ---------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- |
|
|
76
|
+
| `prefixUrl` | `string \| URL` | required | Base URL for relative request paths. |
|
|
77
|
+
| `allowAbsoluteUrls` | `boolean` | `false` | Allows absolute `http:`/`https:` request paths. Protocol-relative URLs stay rejected. |
|
|
78
|
+
| `headers` | `HeadersInit` | — | Merged with per-request headers. |
|
|
79
|
+
| `timeoutMs` | `number` | — | Disabled when omitted. |
|
|
80
|
+
| `requestInit` | `Omit<RequestInit, "method" \| "body" \| "headers">` | — | Merged per request. |
|
|
81
|
+
| `suppressGlobalToast` | `boolean` | — | Interceptor-only metadata. |
|
|
82
|
+
| `fetchImpl` | `typeof fetch` | global `fetch` | |
|
|
83
|
+
| `transport` | `HttpTransport` | Fetch transport | |
|
|
84
|
+
| `interceptors` | `HttpInterceptor[]` | `[]` | |
|
|
85
|
+
|
|
86
|
+
### `client.request(config)`
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
client.request<TResponse = unknown>(config: HttpRequestConfig): Promise<TResponse>;
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
| Field | Type | Notes |
|
|
93
|
+
| --------- | ------------------------------------ | ------------------------------------------------------------------- |
|
|
94
|
+
| `path` | `string` | Required. Relative to `prefixUrl` unless absolute URLs are allowed. |
|
|
95
|
+
| `method` | `string` | Defaults to `GET`. |
|
|
96
|
+
| `query` | `HttpQueryParams \| URLSearchParams` | Appended to the URL. `null` and `undefined` values are skipped. |
|
|
97
|
+
| `json` | `unknown` | Serialized body; sets `content-type: application/json` when unset. |
|
|
98
|
+
| `body` | `BodyInit \| null` | Raw body, for example `FormData` or `URLSearchParams`. |
|
|
99
|
+
| `options` | `HttpRequestOptions` | Per-request overrides. |
|
|
100
|
+
|
|
101
|
+
`json` and `body` are mutually exclusive. Response parsing is independent of
|
|
102
|
+
`content-type`: an empty body resolves to `null`, valid JSON is decoded, and any
|
|
103
|
+
other body resolves to text.
|
|
104
|
+
|
|
105
|
+
## Request options
|
|
106
|
+
|
|
107
|
+
`HttpRequestOptions` is the base shape; `VrpcRequestOptions` extends it.
|
|
108
|
+
|
|
109
|
+
| Field | Type | Applies to | Notes |
|
|
110
|
+
| --------------------- | ---------------------------------------------------- | ---------- | --------------------------------------------------------------- |
|
|
111
|
+
| `headers` | `HeadersInit` | both | Merged over client defaults. |
|
|
112
|
+
| `timeoutMs` | `number` | both | Overrides the client default. |
|
|
113
|
+
| `requestInit` | `Omit<RequestInit, "method" \| "body" \| "headers">` | both | Shallow-merged over the client default. |
|
|
114
|
+
| `suppressGlobalToast` | `boolean` | both | Read by application interceptors; the runtime never touches UI. |
|
|
115
|
+
| `trace` | `{ id: string; span?: string }` | vRPC | Replaces the generated trace. |
|
|
116
|
+
| `wire` | `VrpcMethodWireSpec` | vRPC | Selects JSON or CBOR. Never sent on the wire. |
|
|
117
|
+
|
|
118
|
+
Create-time scalar values and `requestInit` fields are overridden by
|
|
119
|
+
per-request values. `context.options` always contains the merged result.
|
|
120
|
+
|
|
121
|
+
## Interceptors
|
|
122
|
+
|
|
123
|
+
```ts
|
|
124
|
+
type VrpcInterceptor = {
|
|
125
|
+
beforeRequest?: (context: VrpcInvokeContext) => void | Promise<void>;
|
|
126
|
+
afterResponse?: (response: Response, context: VrpcInvokeContext) => void | Promise<void>;
|
|
127
|
+
onError?: (error: unknown, context: VrpcInvokeContext) => void | Promise<void>;
|
|
128
|
+
};
|
|
129
|
+
|
|
130
|
+
type VrpcInvokeContext = {
|
|
131
|
+
url: string;
|
|
132
|
+
init: RequestInit;
|
|
133
|
+
request: VrpcInvokeRequest;
|
|
134
|
+
options: VrpcRequestOptions;
|
|
135
|
+
};
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
`HttpInterceptor` and `HttpInvokeContext` have the same shape with
|
|
139
|
+
`HttpRequestConfig` / `HttpRequestOptions`. Register an interceptor with
|
|
140
|
+
`client.use(interceptor)`.
|
|
141
|
+
|
|
142
|
+
- `options` is the merged configuration, including resolved headers, timeout,
|
|
143
|
+
trace, and `suppressGlobalToast`.
|
|
144
|
+
- `request` is the original call shape and `init` is the resolved `RequestInit`.
|
|
145
|
+
- `onError` completes before the request promise rejects. Returning normally
|
|
146
|
+
does not swallow the error.
|
|
147
|
+
- Request-construction failures that occur before a context exists reject
|
|
148
|
+
directly and never reach an interceptor.
|
|
149
|
+
|
|
150
|
+
## Errors
|
|
151
|
+
|
|
152
|
+
Use the guard for your client, then branch on `kind`:
|
|
153
|
+
|
|
154
|
+
```ts
|
|
155
|
+
isVrpcError(error): error is VrpcError;
|
|
156
|
+
isHttpError(error): error is HttpError;
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
| `kind` | Class | Entry point | Extra fields |
|
|
160
|
+
| ----------- | -------------------- | ----------- | ---------------------------------------------------------------------------------------- |
|
|
161
|
+
| `abort` | `HttpAbortError` | both | `reason` (the `AbortSignal` reason), `url`, `method`, `cause` |
|
|
162
|
+
| `timeout` | `HttpTimeoutError` | both | `timeoutMs`, `code: "HTTP_TIMEOUT"`, `url`, `method`, `cause` |
|
|
163
|
+
| `transport` | `HttpTransportError` | both | `url`, `method`, `cause` |
|
|
164
|
+
| `invoke` | `HttpInvokeError` | both | `status`, `statusText`, `responseHeaders`, `payload`, `type`, `code`, `reason`, `detail` |
|
|
165
|
+
| `invoke` | `VrpcInvokeError` | vRPC | All `HttpInvokeError` fields plus `vrpcStatus` |
|
|
166
|
+
| `protocol` | `VrpcProtocolError` | vRPC only | `status`, `statusText`, `responseHeaders`, `vrpcStatus` |
|
|
167
|
+
|
|
168
|
+
`HttpError` is `HttpAbortError | HttpTimeoutError | HttpTransportError |
|
|
169
|
+
HttpInvokeError`. `VrpcError` adds `VrpcInvokeError` and `VrpcProtocolError`;
|
|
170
|
+
`isHttpError` does not accept a `VrpcProtocolError`.
|
|
171
|
+
|
|
172
|
+
`VrpcInvokeError.message` combines the server `message` and `detail` fields with
|
|
173
|
+
a newline. Use `vrpcStatus` for the protocol outcome and `code` plus `reason`
|
|
174
|
+
for business branching; do not parse `message`. Error classes remain exported
|
|
175
|
+
for advanced use, but application policy normally needs only the guard and
|
|
176
|
+
`kind`.
|
|
177
|
+
|
|
178
|
+
## Protocol helpers
|
|
179
|
+
|
|
180
|
+
Exported from `@yorun-ai/vrpc` and `@yorun-ai/vrpc/client`:
|
|
181
|
+
|
|
182
|
+
| Export | Signature |
|
|
183
|
+
| --------------------------- | -------------------------------------------------------------------------------- |
|
|
184
|
+
| `buildVrpcPath` | `(serviceName: string, methodName: string) => string` |
|
|
185
|
+
| `buildVrpcRequestBody` | `(params: Record<string, unknown> \| null \| undefined) => string` |
|
|
186
|
+
| `encodeVrpcRequestBody` | `(params, schema, cborCodec) => Promise<string \| ArrayBuffer>` |
|
|
187
|
+
| `buildVrpcHeaders` | `(options: BuildVrpcHeadersOptions) => Headers` |
|
|
188
|
+
| `decodeVrpcResponsePayload` | `(response: Response, cborCodec, resultSchema) => Promise<unknown>` |
|
|
189
|
+
| `parseVrpcResponse` | `<T>(responseLike: VrpcResponseLike, payload: unknown) => ParsedVrpcResponse<T>` |
|
|
190
|
+
| `unwrapVrpcResponse` | `<T>(responseLike: VrpcResponseLike, payload: unknown) => T` |
|
|
191
|
+
| `generateVrpcId` | `() => string` (32 lowercase hex characters) |
|
|
192
|
+
| `generateVrpcSpan` | `() => string` (16 lowercase hex characters) |
|
|
193
|
+
| `generateClientInstanceId` | `() => string` (lowercase UUID) |
|
|
194
|
+
| `getClientInstanceId` | `(options?: { key?: string }) => string` |
|
|
195
|
+
| `createFetchTransport` | `(fetchImpl?: typeof fetch) => HttpTransport` |
|
|
196
|
+
|
|
197
|
+
Constants and stores:
|
|
198
|
+
|
|
199
|
+
| Export | Value |
|
|
200
|
+
| ---------------------------------------- | --------------------------- |
|
|
201
|
+
| `VRPC_JSON_CONTENT_TYPE` | `"application/vrpc+json"` |
|
|
202
|
+
| `VRPC_CBOR_CONTENT_TYPE` | `"application/vrpc+cbor"` |
|
|
203
|
+
| `HTTP_TIMEOUT_ERROR_CODE` | `"HTTP_TIMEOUT"` |
|
|
204
|
+
| `DEFAULT_CLIENT_INSTANCE_ID_STORAGE_KEY` | `"vrpc-client-instance-id"` |
|
|
205
|
+
|
|
206
|
+
`BuildVrpcHeadersOptions` is `{ clientInfo, trace, timeoutMs?, requestUsesCbor?,
|
|
207
|
+
responseUsesCbor? }`. `parseVrpcResponse` never throws and returns a
|
|
208
|
+
discriminated result; `unwrapVrpcResponse` throws `VrpcInvokeError` for a
|
|
209
|
+
non-OK response. `getClientInstanceId` reads and writes `localStorage`, and
|
|
210
|
+
falls back to a fresh id when storage is unavailable.
|
|
211
|
+
|
|
212
|
+
## Types
|
|
213
|
+
|
|
214
|
+
Exported from `@yorun-ai/vrpc` and `@yorun-ai/vrpc/client`:
|
|
215
|
+
|
|
216
|
+
| Type | Purpose |
|
|
217
|
+
| ------------------------------------------------------------------------------------------------ | ------------------------------- |
|
|
218
|
+
| `VrpcClient`, `VrpcInvokeRequest`, `VrpcClientOptions` | vRPC client contracts. |
|
|
219
|
+
| `VrpcRequestOptions`, `VrpcRequestInit` | vRPC request configuration. |
|
|
220
|
+
| `VrpcInvokeContext`, `VrpcInterceptor`, `VrpcInterceptors` | Interceptor contracts. |
|
|
221
|
+
| `VrpcClientInfo`, `VrpcTrace`, `VrpcTraceMode` | Client identity and tracing. |
|
|
222
|
+
| `VrpcWireSchema`, `VrpcMethodWireSpec`, `VrpcCborCodec` | JSON/CBOR wire selection. |
|
|
223
|
+
| `VrpcResponseLike`, `ParsedVrpcResponse`, `ParsedVrpcSuccessResponse`, `ParsedVrpcErrorResponse` | Response helpers. |
|
|
224
|
+
| `VrpcTransport`, `VrpcTransportRequest`, `VrpcTransportResponse` | Custom transport contracts. |
|
|
225
|
+
| `VrpcError`, `VrpcErrorPayload`, `HttpClientErrorKind` | Error unions and payload shape. |
|
|
226
|
+
| `GetClientInstanceIdOptions`, `BuildVrpcHeadersOptions` | Helper options. |
|
|
227
|
+
|
|
228
|
+
`@yorun-ai/vrpc/http` exports the HTTP subset: `HttpClient`,
|
|
229
|
+
`HttpRequestConfig`, `HttpClientOptions`, `HttpRequestOptions`, `HttpRequestInit`,
|
|
230
|
+
`HttpQueryParams`, `HttpQueryValue`, `HttpQueryPrimitive`, `HttpInvokeContext`,
|
|
231
|
+
`HttpInterceptor`, `HttpTransport`, `HttpTransportRequest`,
|
|
232
|
+
`HttpTransportResponse`, `HttpError`, `HttpErrorPayload`,
|
|
233
|
+
`HttpErrorRequestMeta`, `HttpClientErrorOptions`, `HttpAbortErrorOptions`, and
|
|
234
|
+
`HttpClientErrorKind`.
|
|
235
|
+
|
|
236
|
+
## Stability
|
|
237
|
+
|
|
238
|
+
The package is in the `0.x` line. The public API is not yet covered by a stable
|
|
239
|
+
`1.x` compatibility commitment, and a breaking change may ship in a new `0.x`
|
|
240
|
+
minor release with migration guidance.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@yorun-ai/vrpc",
|
|
3
|
-
"version": "0.9.
|
|
3
|
+
"version": "0.9.3",
|
|
4
4
|
"description": "vRPC and HTTP request library",
|
|
5
5
|
"homepage": "https://github.com/yorun-ai/vrpc-ts#readme",
|
|
6
6
|
"bugs": {
|
|
@@ -61,5 +61,5 @@
|
|
|
61
61
|
"access": "public",
|
|
62
62
|
"registry": "https://registry.npmjs.org/"
|
|
63
63
|
},
|
|
64
|
-
"packageManager": "pnpm@
|
|
64
|
+
"packageManager": "pnpm@12.5.1"
|
|
65
65
|
}
|