@yorun-ai/vrpc 0.9.3 → 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/dist/client.cjs +1 -1
- package/dist/client.d.cts +0 -2
- package/dist/client.d.ts +0 -2
- package/dist/client.es.js +1 -1
- 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/usage.md +14 -0
- package/docs/maintainers/protocol.md +1 -1
- package/docs/maintainers/releasing.md +34 -34
- package/docs/reference/README.md +8 -8
- package/package.json +1 -1
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-gljZwoeI.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) {
|
package/dist/client.d.cts
CHANGED
|
@@ -175,7 +175,6 @@ interface VrpcClient {
|
|
|
175
175
|
//#endregion
|
|
176
176
|
//#region src/contracts/errors.d.ts
|
|
177
177
|
type HttpErrorPayload = {
|
|
178
|
-
type?: string;
|
|
179
178
|
code?: string;
|
|
180
179
|
message?: string;
|
|
181
180
|
reason?: string;
|
|
@@ -226,7 +225,6 @@ declare class VrpcProtocolError extends HttpClientError<"protocol"> {
|
|
|
226
225
|
constructor(response: Response, message: string, requestMeta?: HttpErrorRequestMeta, options?: HttpClientErrorOptions);
|
|
227
226
|
}
|
|
228
227
|
declare class HttpInvokeError extends HttpClientError<"invoke"> {
|
|
229
|
-
type?: string;
|
|
230
228
|
code?: string;
|
|
231
229
|
reason?: string;
|
|
232
230
|
detail?: string;
|
package/dist/client.d.ts
CHANGED
|
@@ -175,7 +175,6 @@ interface VrpcClient {
|
|
|
175
175
|
//#endregion
|
|
176
176
|
//#region src/contracts/errors.d.ts
|
|
177
177
|
type HttpErrorPayload = {
|
|
178
|
-
type?: string;
|
|
179
178
|
code?: string;
|
|
180
179
|
message?: string;
|
|
181
180
|
reason?: string;
|
|
@@ -226,7 +225,6 @@ declare class VrpcProtocolError extends HttpClientError<"protocol"> {
|
|
|
226
225
|
constructor(response: Response, message: string, requestMeta?: HttpErrorRequestMeta, options?: HttpClientErrorOptions);
|
|
227
226
|
}
|
|
228
227
|
declare class HttpInvokeError extends HttpClientError<"invoke"> {
|
|
229
|
-
type?: string;
|
|
230
228
|
code?: string;
|
|
231
229
|
reason?: string;
|
|
232
230
|
detail?: string;
|
package/dist/client.es.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { _ as isVrpcError, c as HTTP_TIMEOUT_ERROR_CODE, d as HttpInvokeError, f as HttpTimeoutError, h as VrpcProtocolError, i as createFetchTransport, l as HttpAbortError, m as VrpcInvokeError, n as splitVrpcRequestOptions, o as buildRequestUrl, p as HttpTransportError, r as createClientCore, s as mergeHeaders, u as HttpClientError } from "./request-options-
|
|
1
|
+
import { _ as isVrpcError, c as HTTP_TIMEOUT_ERROR_CODE, d as HttpInvokeError, f as HttpTimeoutError, h as VrpcProtocolError, i as createFetchTransport, l as HttpAbortError, m as VrpcInvokeError, n as splitVrpcRequestOptions, o as buildRequestUrl, p as HttpTransportError, r as createClientCore, s as mergeHeaders, u as HttpClientError } from "./request-options-2g2EJjOi.js";
|
|
2
2
|
//#region src/protocol/id.ts
|
|
3
3
|
var DEFAULT_CLIENT_INSTANCE_ID_STORAGE_KEY = "vrpc-client-instance-id";
|
|
4
4
|
function getRandomByteArray(length) {
|
package/dist/http.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-gljZwoeI.cjs");
|
|
3
3
|
//#region src/core/create-http-client.ts
|
|
4
4
|
function resolveJsonBody(request) {
|
|
5
5
|
if (request.json !== void 0 && request.body !== void 0) throw new Error("Request json and body cannot be used together.");
|
package/dist/http.d.cts
CHANGED
|
@@ -62,7 +62,6 @@ type HttpClient = {
|
|
|
62
62
|
//#endregion
|
|
63
63
|
//#region src/contracts/errors.d.ts
|
|
64
64
|
type HttpErrorPayload = {
|
|
65
|
-
type?: string;
|
|
66
65
|
code?: string;
|
|
67
66
|
message?: string;
|
|
68
67
|
reason?: string;
|
|
@@ -104,7 +103,6 @@ declare class HttpTransportError extends HttpClientError<"transport"> {
|
|
|
104
103
|
constructor(requestMeta?: HttpErrorRequestMeta, options?: HttpClientErrorOptions);
|
|
105
104
|
}
|
|
106
105
|
declare class HttpInvokeError extends HttpClientError<"invoke"> {
|
|
107
|
-
type?: string;
|
|
108
106
|
code?: string;
|
|
109
107
|
reason?: string;
|
|
110
108
|
detail?: string;
|
package/dist/http.d.ts
CHANGED
|
@@ -62,7 +62,6 @@ type HttpClient = {
|
|
|
62
62
|
//#endregion
|
|
63
63
|
//#region src/contracts/errors.d.ts
|
|
64
64
|
type HttpErrorPayload = {
|
|
65
|
-
type?: string;
|
|
66
65
|
code?: string;
|
|
67
66
|
message?: string;
|
|
68
67
|
reason?: string;
|
|
@@ -104,7 +103,6 @@ declare class HttpTransportError extends HttpClientError<"transport"> {
|
|
|
104
103
|
constructor(requestMeta?: HttpErrorRequestMeta, options?: HttpClientErrorOptions);
|
|
105
104
|
}
|
|
106
105
|
declare class HttpInvokeError extends HttpClientError<"invoke"> {
|
|
107
|
-
type?: string;
|
|
108
106
|
code?: string;
|
|
109
107
|
reason?: string;
|
|
110
108
|
detail?: string;
|
package/dist/http.es.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { a as appendQueryToUrl, c as HTTP_TIMEOUT_ERROR_CODE, d as HttpInvokeError, f as HttpTimeoutError, g as isHttpError, i as createFetchTransport, l as HttpAbortError, o as buildRequestUrl, p as HttpTransportError, r as createClientCore, s as mergeHeaders, t as splitHttpRequestOptions, u as HttpClientError } from "./request-options-
|
|
1
|
+
import { a as appendQueryToUrl, c as HTTP_TIMEOUT_ERROR_CODE, d as HttpInvokeError, f as HttpTimeoutError, g as isHttpError, i as createFetchTransport, l as HttpAbortError, o as buildRequestUrl, p as HttpTransportError, r as createClientCore, s as mergeHeaders, t as splitHttpRequestOptions, u as HttpClientError } from "./request-options-2g2EJjOi.js";
|
|
2
2
|
//#region src/core/create-http-client.ts
|
|
3
3
|
function resolveJsonBody(request) {
|
|
4
4
|
if (request.json !== void 0 && request.body !== void 0) throw new Error("Request json and body cannot be used together.");
|
|
@@ -76,7 +76,6 @@ function readServerErrorStringField(payload, field) {
|
|
|
76
76
|
return typeof value === "string" ? value : void 0;
|
|
77
77
|
}
|
|
78
78
|
var HttpInvokeError = class extends HttpClientError {
|
|
79
|
-
type;
|
|
80
79
|
code;
|
|
81
80
|
reason;
|
|
82
81
|
detail;
|
|
@@ -95,7 +94,6 @@ var HttpInvokeError = class extends HttpClientError {
|
|
|
95
94
|
this.statusText = response.statusText;
|
|
96
95
|
this.responseHeaders = response.headers;
|
|
97
96
|
this.payload = payload;
|
|
98
|
-
this.type = readServerErrorStringField(payload, "type");
|
|
99
97
|
this.code = readServerErrorStringField(payload, "code");
|
|
100
98
|
this.reason = readServerErrorStringField(payload, "reason");
|
|
101
99
|
this.detail = readServerErrorStringField(payload, "detail");
|
|
@@ -76,7 +76,6 @@ function readServerErrorStringField(payload, field) {
|
|
|
76
76
|
return typeof value === "string" ? value : void 0;
|
|
77
77
|
}
|
|
78
78
|
var HttpInvokeError = class extends HttpClientError {
|
|
79
|
-
type;
|
|
80
79
|
code;
|
|
81
80
|
reason;
|
|
82
81
|
detail;
|
|
@@ -95,7 +94,6 @@ var HttpInvokeError = class extends HttpClientError {
|
|
|
95
94
|
this.statusText = response.statusText;
|
|
96
95
|
this.responseHeaders = response.headers;
|
|
97
96
|
this.payload = payload;
|
|
98
|
-
this.type = readServerErrorStringField(payload, "type");
|
|
99
97
|
this.code = readServerErrorStringField(payload, "code");
|
|
100
98
|
this.reason = readServerErrorStringField(payload, "reason");
|
|
101
99
|
this.detail = readServerErrorStringField(payload, "detail");
|
package/docs/guides/usage.md
CHANGED
|
@@ -228,6 +228,20 @@ Recommended application policy:
|
|
|
228
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.
|
|
229
229
|
- Treat values that fail `isVrpcError` as configuration, interceptor, or other unexpected application errors; do not silently classify them as network failures.
|
|
230
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
|
+
|
|
231
245
|
### Global `onError` and local `try/catch`
|
|
232
246
|
|
|
233
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.
|
package/docs/reference/README.md
CHANGED
|
@@ -156,14 +156,14 @@ isVrpcError(error): error is VrpcError;
|
|
|
156
156
|
isHttpError(error): error is HttpError;
|
|
157
157
|
```
|
|
158
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`, `
|
|
165
|
-
| `invoke` | `VrpcInvokeError` | vRPC | All `HttpInvokeError` fields plus `vrpcStatus`
|
|
166
|
-
| `protocol` | `VrpcProtocolError` | vRPC only | `status`, `statusText`, `responseHeaders`, `vrpcStatus`
|
|
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
167
|
|
|
168
168
|
`HttpError` is `HttpAbortError | HttpTimeoutError | HttpTransportError |
|
|
169
169
|
HttpInvokeError`. `VrpcError` adds `VrpcInvokeError` and `VrpcProtocolError`;
|