@yorun-ai/vrpc 0.9.1 → 0.9.2
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/README.md +103 -3
- package/README.zh-CN.md +103 -3
- package/dist/client.cjs +45 -24
- package/dist/client.d.cts +47 -11
- package/dist/client.d.ts +47 -11
- package/dist/client.es.js +41 -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 +43 -21
- package/docs/guides/usage.md +167 -7
- package/docs/maintainers/architecture.md +26 -4
- package/docs/maintainers/protocol.md +16 -1
- package/package.json +1 -1
|
@@ -20,13 +20,35 @@ A transport response must preserve the original `Uint8Array | null`. The generic
|
|
|
20
20
|
## Generic HTTP flow
|
|
21
21
|
|
|
22
22
|
1. Create options define defaults for headers, timeout, requestInit, and suppressGlobalToast. Timeout has no built-in default, so the built-in transport creates no local timer unless configured.
|
|
23
|
-
2.
|
|
24
|
-
3.
|
|
25
|
-
4.
|
|
26
|
-
5. The
|
|
23
|
+
2. Request paths are joined to `prefixUrl`. Absolute paths are rejected before transport unless the HTTP client was created with `allowAbsoluteUrls: true`; the opt-in permits only HTTP(S), while protocol-relative URLs remain invalid. This policy is HTTP-only and does not constrain a vRPC client's `prefixUrl`.
|
|
24
|
+
3. Per-request `request.options` override defaults. Headers are merged, requestInit is shallow-merged, and per-request scalar values take precedence.
|
|
25
|
+
4. Interceptors receive `{ url, init, request, options }`; `options` contains the merged configuration.
|
|
26
|
+
5. The transport sends the request and returns raw bytes.
|
|
27
|
+
6. The core reconstructs a `Response`, parses JSON, text, or an empty response, and throws `HttpInvokeError` for a non-success status.
|
|
27
28
|
|
|
28
29
|
Request options and interceptor-only fields must not enter `HttpTransportRequest`.
|
|
29
30
|
|
|
31
|
+
## Error model
|
|
32
|
+
|
|
33
|
+
Normalized transport, protocol, and invocation errors extend `HttpClientError` and carry a stable `kind`, request URL and method, plus the original error in `cause` when one exists. Request-construction and user-interceptor exceptions remain ordinary developer errors. The public entry points expose a single guard followed by kind-based classification:
|
|
34
|
+
|
|
35
|
+
- vRPC: `isVrpcError(error)`
|
|
36
|
+
- Generic HTTP: `isHttpError(error)`
|
|
37
|
+
|
|
38
|
+
`HttpError` is the discriminated union of caller abort, timeout, transport, and HTTP invoke errors. `VrpcError` adds vRPC invoke and protocol errors to the three shared lifecycle errors. In particular, a generic `HttpInvokeError` is not a `VrpcError`; after `isVrpcError`, `kind: "invoke"` narrows directly to `VrpcInvokeError`. Application code therefore does not need to mix `kind` checks with `instanceof` checks.
|
|
39
|
+
|
|
40
|
+
The built-in Fetch transport determines whether its composed signal was aborted by the caller or by the configured timeout. Caller cancellation becomes `HttpAbortError`; timeout becomes `HttpTimeoutError`; other Fetch failures become `HttpTransportError`. The core preserves known package errors and wraps unknown custom-transport failures as `HttpTransportError`. Native `AbortError` and common adapter cancellation shapes are normalized internally rather than exposed through an additional public cancellation guard.
|
|
41
|
+
|
|
42
|
+
Generic HTTP response parsing is deliberately lenient and independent of `content-type`: an empty body becomes `null`, valid JSON is decoded, and a body that is not valid JSON remains text. JSON syntax is therefore not an HTTP failure category. The transport owns body reading; a failure to obtain complete response bytes becomes `HttpTransportError`.
|
|
43
|
+
|
|
44
|
+
vRPC decoding remains strict about its media type and required protocol metadata. A malformed successful vRPC response becomes `VrpcProtocolError` and retains HTTP status, response headers, `vrpc-status` when present, and the decoding failure as `cause`.
|
|
45
|
+
|
|
46
|
+
For a failed vRPC response, `vrpc-status` remains authoritative and the body error remains auxiliary. If the body cannot be decoded but a failing `vrpc-status` is present, the client throws `VrpcInvokeError` with `payload: null` and preserves the decoding error in `cause`. It does not replace the invocation failure with a protocol error or validate `result` and `error` as a strict mutually exclusive envelope.
|
|
47
|
+
|
|
48
|
+
Caller cancellation still reaches `onError` and still rejects the request promise. Applications that want quiet cancellation should return early from their global error handler when `error.kind === "abort"`; the transport and core must not convert cancellation into a successful result.
|
|
49
|
+
|
|
50
|
+
`suppressGlobalToast` is interceptor-only application policy metadata. The runtime merges the client default with the per-request override and exposes the resolved value through `context.options`; it never performs UI work, skips `onError`, consumes the rejection, or copies the field into a transport request. A normally completed `onError` chain is followed by rejection of the request Promise, allowing a local `try/catch` to implement feature-specific recovery.
|
|
51
|
+
|
|
30
52
|
## Protocol boundary
|
|
31
53
|
|
|
32
54
|
The vRPC protocol layer owns path construction, request and response envelopes, content negotiation, protocol headers, wire-schema conversion, and protocol-level errors. `core` orchestrates those operations; `transports` only send HTTP requests and preserve raw response bytes.
|
|
@@ -46,7 +46,22 @@ 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`.
|
|
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 `type`, `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
|
+
|
|
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
|
+
|
|
53
|
+
### Error message construction
|
|
54
|
+
|
|
55
|
+
`VrpcInvokeError.message` deliberately combines the auxiliary body fields `message` and `detail`. When `message` is a non-empty string and trimmed `detail` is non-empty, the runtime produces:
|
|
56
|
+
|
|
57
|
+
```text
|
|
58
|
+
<message>
|
|
59
|
+
<detail>
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
The newline keeps the primary human-readable summary separate from the additional diagnostic or explanatory text while preserving both in ordinary logs, error boundaries, and UI fallbacks that display only `Error.message`. This behavior also preserves compatibility for applications that already surface the combined message.
|
|
63
|
+
|
|
64
|
+
The combined text is presentation data, not a classification contract. Applications must use `vrpc-status` for the protocol outcome and `code` plus `reason` for business branching; they must not parse `message` or `detail`. If the body has no usable `message`, the runtime falls back to the HTTP status-based error message.
|
|
50
65
|
|
|
51
66
|
## Content negotiation
|
|
52
67
|
|