@yorun-ai/vrpc 0.9.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.
@@ -0,0 +1,135 @@
1
+ # vRPC Protocol
2
+
3
+ This document defines the vRPC wire contract implemented by `@yorun-ai/vrpc`. It is intended for runtime maintainers, transport authors, and code-generator maintainers. For application usage, see the [usage guide](../guides/usage.md).
4
+
5
+ ## Request routing and envelope
6
+
7
+ Every invocation uses `POST`. The request path is formed from the encoded service and method names:
8
+
9
+ ```text
10
+ <prefixUrl>/<encodeURIComponent(serviceName)>/<encodeURIComponent(methodName)>
11
+ ```
12
+
13
+ JSON requests use this envelope. An argument-free method may supply either `null` or `{}`; the runtime serializes a missing value as `null`.
14
+
15
+ ```json
16
+ {
17
+ "params": {
18
+ "userId": 1
19
+ }
20
+ }
21
+ ```
22
+
23
+ `options.wire` is client-only metadata and must never be serialized into the envelope or copied into a transport request.
24
+
25
+ ## Response envelope and status
26
+
27
+ A successful response has a result and a null error:
28
+
29
+ ```json
30
+ {
31
+ "result": {
32
+ "name": "Ada"
33
+ },
34
+ "error": null
35
+ }
36
+ ```
37
+
38
+ An error response has a null result and may carry a structured error:
39
+
40
+ ```json
41
+ {
42
+ "result": null,
43
+ "error": {
44
+ "message": "user not found"
45
+ }
46
+ }
47
+ ```
48
+
49
+ The client treats a response as successful only when the HTTP status is successful and `vrpc-status` is `OK`. Other responses are unwrapped as `VrpcInvokeError`. Every response must contain valid `content-type`, `vrpc-status`, and `vrpc-server` headers; a JSON body must be non-empty and parseable.
50
+
51
+ ## Content negotiation
52
+
53
+ `VrpcMethodWireSpec` is sparse:
54
+
55
+ ```ts
56
+ type VrpcMethodWireSpec = {
57
+ arguments?: VrpcWireSchema;
58
+ result?: VrpcWireSchema;
59
+ };
60
+ ```
61
+
62
+ Property presence selects CBOR independently in each direction:
63
+
64
+ | Wire metadata | Request `content-type` | Response `accept` |
65
+ | ---------------- | ----------------------- | ---------------------------------------------- |
66
+ | None | `application/vrpc+json` | `application/vrpc+json` |
67
+ | `wire.arguments` | `application/vrpc+cbor` | `application/vrpc+json` |
68
+ | `wire.result` | `application/vrpc+json` | `application/vrpc+cbor, application/vrpc+json` |
69
+ | Both properties | `application/vrpc+cbor` | `application/vrpc+cbor, application/vrpc+json` |
70
+
71
+ If either property is present, the client requires a `cborCodec` before invoking the transport. A CBOR response is accepted only when `wire.result` is present. The codec must encode to `Uint8Array`; it may decode an envelope as either a JavaScript object or a `Map`.
72
+
73
+ ## Protocol headers
74
+
75
+ | Header | Value and rule |
76
+ | -------------- | -------------------------------------------------------------------------------------------------------------------------------- |
77
+ | `content-type` | The request media type selected above. |
78
+ | `accept` | The response media types selected above. |
79
+ | `vrpc-client` | `name=<name>,version=<semver>,instanceId=<uuid>`. |
80
+ | `vrpc-trace` | `id=<32 lowercase hex>` and optional `span=<16 lowercase hex>`. Portal mode allows an id-only trace; direct mode creates a span. |
81
+ | `vrpc-options` | `timeout=<positive integer>ms`; omitted when no timeout is configured. |
82
+ | `vrpc-server` | Required response identity with the same name, version, and instance-id shape as `vrpc-client`. |
83
+ | `vrpc-status` | Required response status; `OK` is the success value. |
84
+
85
+ Client names use lower-case dot-separated identifiers. Versions must be valid SemVer and instance IDs must be UUIDs. The runtime validates client information, traces, and timeouts before sending the request.
86
+
87
+ Application headers cannot override `accept`, `content-type`, or any header whose name starts with `vrpc-`.
88
+
89
+ ## Wire schema conversion
90
+
91
+ `VrpcWireSchema` describes values that require shape preservation across generated TypeScript, JavaScript, and CBOR:
92
+
93
+ - `value`: no shape conversion.
94
+ - `binary`: normalize to `Uint8Array`.
95
+ - `list`: recursively convert array items.
96
+ - `map`: recursively convert values; integer-keyed records become `Map<number, T>` for CBOR and return to `Record<number, T>` after decoding.
97
+ - `object`: recursively convert declared fields while preserving other fields. Its field map may be a thunk to support recursive types.
98
+ - `nullable`: records nullability for generated contracts. The conversion functions preserve `null` and `undefined` for every schema and do not validate this flag.
99
+
100
+ String-keyed maps remain ordinary objects. Error values decoded from CBOR are normalized recursively from maps into objects, but binary values remain `Uint8Array`.
101
+
102
+ ## Generated TypeScript contract
103
+
104
+ Generated TypeScript follows these rules:
105
+
106
+ - Values in `methods` are strings.
107
+ - A service without Binary methods omits `wire`.
108
+ - Only methods containing Binary have a `wire.<method>` entry and referenced schemas.
109
+ - Each method includes only the `arguments` or `result` side that contains Binary.
110
+ - `ArgumentsContainsBinaryType` and `ResultContainsBinaryType` are not emitted in TypeScript.
111
+ - Binary uses `Uint8Array`; Map uses `Record`.
112
+ - CBOR method wrappers use `{ ...options, wire: Spec.wire.method }`, so generated wire metadata overrides a caller field with the same name.
113
+ - Ordinary method wrappers pass options through unchanged.
114
+ - Argument-free method wrappers use `params: null`; the runtime also accepts `{}`.
115
+
116
+ Example:
117
+
118
+ ```ts
119
+ export const FileServiceSpec = {
120
+ serviceName: "file.FileService",
121
+ methods: {
122
+ ping: "ping",
123
+ upload: "upload",
124
+ },
125
+ wire: {
126
+ upload: {
127
+ arguments: uploadArgumentsSchema,
128
+ },
129
+ },
130
+ } as const;
131
+ ```
132
+
133
+ ## Changing the protocol
134
+
135
+ Protocol changes affect more than this package. Review all producers and consumers, including Vine server behavior, `skelc` generation, runtime parsing, custom transports, and generated clients. Update protocol tests and this document in the same change.
@@ -0,0 +1,92 @@
1
+ # Releasing
2
+
3
+ The root `package.json#version` is the authoritative package version. Release scripts publish the build artifacts for that version to npm.
4
+
5
+ ## Release policy
6
+
7
+ The package starts at `0.9.0` as a usable pre-1.0 release. Until `1.0.0`, the public API is not guaranteed to remain stable:
8
+
9
+ - A `0.x` minor release may contain breaking API changes.
10
+ - Patch releases contain backward-compatible fixes.
11
+ - Every breaking change requires release notes and migration guidance.
12
+ - `1.0.0` marks the start of the stable public API commitment.
13
+
14
+ ## Preparing a version
15
+
16
+ Version commands only update the root `package.json#version`; they do not run `npm publish`:
17
+
18
+ ```bash
19
+ pnpm version:alpha:patch
20
+ pnpm version:alpha:minor
21
+ pnpm version:alpha:major
22
+ pnpm version:patch
23
+ pnpm version:minor
24
+ pnpm version:major
25
+ ```
26
+
27
+ Version examples use the initial `0.9.0` release as the starting point:
28
+
29
+ | Command | Result |
30
+ | --------------------- | ---------------- |
31
+ | `version:alpha:patch` | `0.9.1-alpha.0` |
32
+ | `version:alpha:minor` | `0.10.0-alpha.0` |
33
+ | `version:alpha:major` | `1.0.0-alpha.0` |
34
+ | `version:patch` | `0.9.1` |
35
+ | `version:minor` | `0.10.0` |
36
+ | `version:major` | `1.0.0` |
37
+
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
+
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`. A successful release creates and pushes only the Git tag `v<version>` for that release.
41
+
42
+ ## Publishing
43
+
44
+ Before publishing, point `NPM_CONFIG_USERCONFIG` to the npm configuration used for publishing:
45
+
46
+ ```bash
47
+ export NPM_CONFIG_USERCONFIG=/path/to/npmrc
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.
63
+
64
+ ## Release gates
65
+
66
+ The release script runs:
67
+
68
+ ```bash
69
+ pnpm install --frozen-lockfile
70
+ pnpm type-check
71
+ pnpm test
72
+ pnpm fmt:check
73
+ pnpm lint
74
+ pnpm build
75
+ pnpm test:package
76
+ ```
77
+
78
+ The script then assembles the package in a system temporary directory, verifies the npm identity, confirms that the target version does not already exist, and runs `npm publish`. The temporary directory is removed after either success or failure.
79
+
80
+ ## Recovering a tag push
81
+
82
+ Publishing to npm and pushing a Git tag cannot be one atomic operation. If npm publishing succeeds but the final tag push fails, do not publish the version again.
83
+
84
+ If the local `v<version>` tag exists and points to the release commit, restore the remote tag with:
85
+
86
+ ```bash
87
+ git push origin refs/tags/v<version>
88
+ ```
89
+
90
+ If local tag creation failed, first verify the release commit, create `v<version>` at that exact commit, and then run the command above. Never use `git push --tags` as recovery because it may publish unrelated local tags.
91
+
92
+ `package.json` must declare a reviewed license and the repository must contain the matching `LICENSE` file. Both staging and the post-build smoke test validate it. The published package contains JavaScript, type declarations, the bilingual root README, English guides and maintainer documentation, the contribution guide, LICENSE, and the package manifest.
package/package.json ADDED
@@ -0,0 +1,65 @@
1
+ {
2
+ "name": "@yorun-ai/vrpc",
3
+ "version": "0.9.0",
4
+ "description": "vRPC and HTTP request library",
5
+ "homepage": "https://github.com/yorun-ai/vrpc-ts#readme",
6
+ "bugs": {
7
+ "url": "https://github.com/yorun-ai/vrpc-ts/issues"
8
+ },
9
+ "license": "Apache-2.0",
10
+ "repository": {
11
+ "type": "git",
12
+ "url": "git+https://github.com/yorun-ai/vrpc-ts.git"
13
+ },
14
+ "files": [
15
+ "dist",
16
+ "README.md",
17
+ "README.zh-CN.md",
18
+ "CONTRIBUTING.md",
19
+ "docs",
20
+ "LICENSE",
21
+ "package.json"
22
+ ],
23
+ "type": "module",
24
+ "sideEffects": false,
25
+ "main": "./dist/client.cjs",
26
+ "module": "./dist/client.es.js",
27
+ "types": "./dist/client.d.ts",
28
+ "exports": {
29
+ ".": {
30
+ "import": {
31
+ "types": "./dist/client.d.ts",
32
+ "default": "./dist/client.es.js"
33
+ },
34
+ "require": {
35
+ "types": "./dist/client.d.cts",
36
+ "default": "./dist/client.cjs"
37
+ }
38
+ },
39
+ "./client": {
40
+ "import": {
41
+ "types": "./dist/client.d.ts",
42
+ "default": "./dist/client.es.js"
43
+ },
44
+ "require": {
45
+ "types": "./dist/client.d.cts",
46
+ "default": "./dist/client.cjs"
47
+ }
48
+ },
49
+ "./http": {
50
+ "import": {
51
+ "types": "./dist/http.d.ts",
52
+ "default": "./dist/http.es.js"
53
+ },
54
+ "require": {
55
+ "types": "./dist/http.d.cts",
56
+ "default": "./dist/http.cjs"
57
+ }
58
+ }
59
+ },
60
+ "publishConfig": {
61
+ "access": "public",
62
+ "registry": "https://registry.npmjs.org/"
63
+ },
64
+ "packageManager": "pnpm@11.15.0"
65
+ }