@yorun-ai/vrpc 0.9.2 → 0.10.0
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 +3 -2
- package/dist/client.d.cts +0 -2
- package/dist/client.d.ts +0 -2
- package/dist/client.es.js +3 -2
- package/dist/http.cjs +1 -1
- package/dist/http.d.cts +0 -2
- package/dist/http.d.ts +0 -2
- package/dist/http.es.js +1 -1
- package/dist/{request-options-Bjy2LvRE.js → request-options-2g2EJjOi.js} +0 -2
- package/dist/{request-options-m8_63jpk.cjs → request-options-gljZwoeI.cjs} +0 -2
- package/docs/guides/axios.md +3 -0
- package/docs/guides/cdn.md +221 -0
- package/docs/guides/usage.md +19 -0
- package/docs/maintainers/protocol.md +1 -1
- package/docs/maintainers/releasing.md +34 -34
- 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
|
|
@@ -223,6 +228,20 @@ Recommended application policy:
|
|
|
223
228
|
- 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
229
|
- Treat values that fail `isVrpcError` as configuration, interceptor, or other unexpected application errors; do not silently classify them as network failures.
|
|
225
230
|
|
|
231
|
+
### Upgrading to 0.10
|
|
232
|
+
|
|
233
|
+
Version 0.10 removes the obsolete `type` field from `HttpErrorPayload`,
|
|
234
|
+
`VrpcErrorPayload`, `HttpInvokeError`, and `VrpcInvokeError`. The current vRPC
|
|
235
|
+
error payload contains `code`, `message`, `reason`, and `detail`.
|
|
236
|
+
|
|
237
|
+
Replace checks of `error.type` according to their purpose: use `kind` after
|
|
238
|
+
`isHttpError` or `isVrpcError` to distinguish client error categories, use
|
|
239
|
+
`vrpcStatus` on vRPC invocation errors for the protocol outcome, and use `code`
|
|
240
|
+
with `reason` for business-specific handling. These fields already existed in
|
|
241
|
+
0.9, so callers can migrate before upgrading. Generic HTTP callers that consume
|
|
242
|
+
a custom server field can still read the original response through `payload`
|
|
243
|
+
after validating its shape.
|
|
244
|
+
|
|
226
245
|
### Global `onError` and local `try/catch`
|
|
227
246
|
|
|
228
247
|
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.
|
|
@@ -46,7 +46,7 @@ An error response has a null result and may carry a structured error:
|
|
|
46
46
|
}
|
|
47
47
|
```
|
|
48
48
|
|
|
49
|
-
The client treats a response as successful only when the HTTP status is successful and `vrpc-status` is `OK`. `vrpc-status` is the authoritative vRPC outcome; the body `error` supplies auxiliary `
|
|
49
|
+
The client treats a response as successful only when the HTTP status is successful and `vrpc-status` is `OK`. `vrpc-status` is the authoritative vRPC outcome; the body `error` supplies auxiliary `code`, `reason`, `message`, and `detail` fields. The runtime does not infer success from body fields or require `result` and `error` to form a strictly validated mutually exclusive envelope.
|
|
50
50
|
|
|
51
51
|
Other responses are unwrapped as `VrpcInvokeError`. If a response already carries a failing `vrpc-status` but its body or auxiliary protocol metadata cannot be decoded, it remains a `VrpcInvokeError` with `payload: null`, while the decoding failure is preserved as `cause`. Every response must contain valid `content-type`, `vrpc-status`, and `vrpc-server` headers; a JSON body must be non-empty and parseable. A missing `vrpc-status`, or an otherwise undecodable successful response, produces `VrpcProtocolError` with the HTTP response metadata intact.
|
|
52
52
|
|
|
@@ -37,29 +37,20 @@ Version examples use the initial `0.9.0` release as the starting point:
|
|
|
37
37
|
|
|
38
38
|
Running an alpha command again on its prerelease line increments the prerelease number, for example from `0.9.1-alpha.0` to `0.9.1-alpha.1`. Running the matching stable command on that prerelease removes the prerelease suffix.
|
|
39
39
|
|
|
40
|
-
Review and commit the version change before publishing. A prerelease automatically uses its SemVer identifier as the dist-tag, such as `alpha`; a stable version uses `latest`.
|
|
40
|
+
Review and commit the version change before publishing. A prerelease automatically uses its SemVer identifier as the dist-tag, such as `alpha`; a stable version uses `latest`. After the version PR passes CI and is merged, sync main and push only its reviewed `v<version>` tag. The tag starts publication.
|
|
41
41
|
|
|
42
42
|
## Publishing
|
|
43
43
|
|
|
44
|
-
|
|
44
|
+
Run `pnpm release:dry-run` locally to check the package without publishing.
|
|
45
|
+
Actual publication runs only in GitHub Actions after pushing the version tag;
|
|
46
|
+
`pnpm release` does not publish from a developer machine. The workflow checks
|
|
47
|
+
that the checkout matches the tag, belongs to main history and has exactly the
|
|
48
|
+
same version in package.json. It never creates, moves or pushes tags.
|
|
45
49
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
Run the full checks and an npm dry-run first:
|
|
51
|
-
|
|
52
|
-
```bash
|
|
53
|
-
pnpm release:dry-run
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
After confirming the package name, version, file list, and dist-tag, publish:
|
|
57
|
-
|
|
58
|
-
```bash
|
|
59
|
-
pnpm release
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
The release script publishes the committed version from the root `package.json` and never changes the version during publishing. Before contacting npm, it verifies that the target tag does not exist locally or on `origin`, pulls with fast-forward only, and pushes the release commit. It never pushes unrelated local tags.
|
|
50
|
+
Keep the `npm-publish` environment and npm trusted publisher configured for
|
|
51
|
+
this repository and `release.yml`. Environment deployment rules must allow
|
|
52
|
+
version tags, not only the main branch; existing required approvals still apply.
|
|
53
|
+
The workflow uses OIDC with `id-token: write` and the pinned npm CLI.
|
|
63
54
|
|
|
64
55
|
## Release gates
|
|
65
56
|
|
|
@@ -75,18 +66,27 @@ pnpm build
|
|
|
75
66
|
pnpm test:package
|
|
76
67
|
```
|
|
77
68
|
|
|
78
|
-
The script
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
69
|
+
The script assembles the package in a temporary directory, runs npm pack once,
|
|
70
|
+
and publishes that exact tarball with provenance. A stable version uses `latest`;
|
|
71
|
+
a prerelease uses its SemVer identifier. The registry SHA-512 integrity must match
|
|
72
|
+
the packed tarball before GitHub Release is created. Release notes are generated
|
|
73
|
+
from GitHub history; this repository does not maintain a CHANGELOG. Prerelease
|
|
74
|
+
tags create GitHub prereleases. Temporary package files are removed on exit.
|
|
75
|
+
|
|
76
|
+
## Recovery
|
|
77
|
+
|
|
78
|
+
Rerun the failed workflow or dispatch it with the same existing tag. If npm
|
|
79
|
+
already contains the version, compare its integrity with the rebuilt tarball:
|
|
80
|
+
only an exact match skips npm upload and resumes GitHub Release creation.
|
|
81
|
+
A mismatch, authentication failure or registry error stops publication. Recovery
|
|
82
|
+
does not rewrite npm dist-tags, which may already point to a newer release.
|
|
83
|
+
An existing published GitHub Release is left unchanged; an unpublished draft
|
|
84
|
+
can finish publication. Do not move tags or unpublish npm versions to retry.
|
|
85
|
+
|
|
86
|
+
For workflow changes, run `bash .github/scripts/release_test.sh`, ShellCheck,
|
|
87
|
+
actionlint and the normal package checks. Full OIDC and hosted publication still
|
|
88
|
+
require an actual version-tag run.
|
|
89
|
+
|
|
90
|
+
`package.json` must declare a reviewed license and the repository must contain
|
|
91
|
+
the matching LICENSE. Published contents include JavaScript, declarations, both
|
|
92
|
+
READMEs, guides, maintainer documentation, CONTRIBUTING, LICENSE and the manifest.
|
|
@@ -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`, `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.
|
|
3
|
+
"version": "0.10.0",
|
|
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
|
}
|