@yorun-ai/vrpc 0.9.1 → 0.9.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTRIBUTING.md +24 -2
- package/README.md +147 -163
- package/README.zh-CN.md +128 -158
- package/dist/client.cjs +46 -24
- package/dist/client.d.cts +47 -11
- package/dist/client.d.ts +47 -11
- package/dist/client.es.js +42 -25
- package/dist/http.cjs +7 -3
- package/dist/http.d.cts +35 -9
- package/dist/http.d.ts +35 -9
- package/dist/http.es.js +4 -4
- package/dist/{request-options-disym648.js → request-options-Bjy2LvRE.js} +175 -47
- package/dist/{request-options-2HZzkj4w.cjs → request-options-m8_63jpk.cjs} +210 -46
- package/docs/guides/axios.md +46 -21
- package/docs/guides/cdn.md +221 -0
- package/docs/guides/usage.md +172 -7
- package/docs/maintainers/architecture.md +26 -4
- package/docs/maintainers/protocol.md +16 -1
- package/docs/reference/README.md +240 -0
- package/package.json +2 -2
|
@@ -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
|
}
|