138 lines
7.6 KiB
Markdown
138 lines
7.6 KiB
Markdown
<!-- markdownlint-disable MD024 -->
|
|
|
|
# Capability Spec Delta: api-worker-rpc (api-worker-rpc)
|
|
|
|
**Package**: `@suaveplan/api-worker-rpc`
|
|
**Status**: PROPOSED
|
|
|
|
> Every requirement below carries a `**Verified by:**` line at authoring time. (See `openspec/AGENTS.md` Section 13.)
|
|
|
|
## ADDED Requirements
|
|
|
|
### Requirement: Request/response correlation via monotonic message ids
|
|
|
|
The package SHALL assign every `RpcRequest` a monotonically-increasing `bigint` id from a per-port counter. Responses SHALL include the same id; the caller's response-table lookup MUST match by exact id. A response whose id has no outstanding entry MUST be rejected with `RPC_ORPHAN_RESPONSE` (not silently dropped — orphans indicate a protocol bug worth surfacing).
|
|
|
|
#### Scenario: ids are strictly monotonic per port
|
|
|
|
- **WHEN** 1000 requests are issued on one port
|
|
- **THEN** the issued ids form a strictly-increasing sequence with no gaps
|
|
|
|
#### Scenario: orphan response is rejected loudly
|
|
|
|
- **WHEN** a response arrives whose id has no outstanding entry
|
|
- **THEN** the callee logs `RPC_ORPHAN_RESPONSE` AND no caller promise is settled by it
|
|
|
|
**Verified by:** `src/correlation/correlation.test.ts::"ids are strictly monotonic per port"` AND `src/correlation/correlation.test.ts::"orphan response throws RPC_ORPHAN_RESPONSE"`
|
|
|
|
---
|
|
|
|
### Requirement: AbortSignal forwarding cancels in-flight calls
|
|
|
|
The package SHALL accept an optional `AbortSignal` per `createRpcCaller` call. When the caller's signal aborts, the protocol MUST send an `RpcAbort` message and the in-flight caller promise MUST reject with `AbortError` (DOMException, name `"AbortError"`). The callee MUST surface a fresh `AbortSignal` to its implementation function so user code can react. Aborting after settlement MUST be a no-op.
|
|
|
|
#### Scenario: caller abort rejects the promise
|
|
|
|
- **WHEN** a caller issues a request with `signal: ac.signal` AND calls `ac.abort()` before the response arrives
|
|
- **THEN** the promise rejects with an `AbortError`
|
|
|
|
#### Scenario: abort after settle is a no-op
|
|
|
|
- **WHEN** a request has already resolved AND `ac.abort()` is called
|
|
- **THEN** no error is thrown AND no `RpcAbort` is sent
|
|
|
|
**Verified by:** `src/abort/abort.test.ts::"caller abort rejects in-flight call"` AND `src/abort/abort.test.ts::"abort after settle is no-op"`
|
|
|
|
---
|
|
|
|
### Requirement: Streaming via Transferable ReadableStream
|
|
|
|
The package SHALL marshal `ReadableStream` arguments and return values via `Transferable` so chunks transfer zero-copy. The protocol SHALL carry per-chunk `ack` so the producing side cannot outrun the consumer; missing acks within a configurable window count against backpressure budget. Consumer cancellation MUST propagate back to the producer.
|
|
|
|
#### Scenario: large stream transfers in chunks
|
|
|
|
- **WHEN** a 64 MiB stream is sent across the port
|
|
- **THEN** the receiver observes the full byte sequence AND the producer is throttled by backpressure ack
|
|
|
|
#### Scenario: consumer cancel propagates to producer
|
|
|
|
- **WHEN** the receiver cancels the stream mid-transfer
|
|
- **THEN** the producer's stream receives a cancellation signal
|
|
|
|
**Verified by:** `src/streaming/streaming.test.ts::"large stream transfers in chunks"` AND `src/streaming/streaming.test.ts::"consumer cancel propagates to producer"`
|
|
|
|
---
|
|
|
|
### Requirement: SuaveplanError reconstruction across the wire
|
|
|
|
The package SHALL reconstruct `SuaveplanError` on the receiving side with the same `code`, the same `details` (Zod-validated), and a depth-bounded `cause` chain (default depth 5). Throws that are NOT `SuaveplanError` MUST be wrapped on the receiving side in a `SuaveplanError` with code `RPC_REMOTE_THROW` carrying the original `name` and `message` in `details`. The original stack is preserved as a `details.remoteStack` string field — never as a live `Error.stack` (which would not survive structured-clone).
|
|
|
|
#### Scenario: SuaveplanError round-trips with cause
|
|
|
|
- **WHEN** the callee throws `new SuaveplanError("PLUGIN.X.Y", { cause: new SuaveplanError("PLUGIN.X.Z") })`
|
|
- **THEN** the caller receives a `SuaveplanError` with `code === "PLUGIN.X.Y"` AND `(err.cause as SuaveplanError).code === "PLUGIN.X.Z"`
|
|
|
|
#### Scenario: plain Error becomes RPC_REMOTE_THROW
|
|
|
|
- **WHEN** the callee throws `new TypeError("boom")`
|
|
- **THEN** the caller receives `SuaveplanError` with code `RPC_REMOTE_THROW` AND `details.remoteName === "TypeError"`
|
|
|
|
**Verified by:** `src/error-reconstruction/error-reconstruction.test.ts::"SuaveplanError round-trips with cause"` AND `src/error-reconstruction/error-reconstruction.test.ts::"plain Error wraps as RPC_REMOTE_THROW"`
|
|
|
|
---
|
|
|
|
### Requirement: Backpressure rejects new calls before memory exhaustion
|
|
|
|
The package SHALL enforce a configurable bounded outstanding-message budget per port (default 1024). When the budget is exhausted, new `createRpcCaller` method calls MUST throw `RPC_BACKPRESSURE` synchronously at the call site — they MUST NOT queue indefinitely or allocate without bound. Acks AND response receipts return capacity.
|
|
|
|
#### Scenario: budget exceeded throws synchronously
|
|
|
|
- **WHEN** 1025 simultaneous calls are issued against a budget of 1024
|
|
- **THEN** the 1025th call throws `RPC_BACKPRESSURE` synchronously (no microtask delay)
|
|
|
|
**Verified by:** `src/backpressure/backpressure.test.ts::"budget exceeded throws RPC_BACKPRESSURE synchronously"`
|
|
|
|
---
|
|
|
|
### Requirement: Cloneable guard rejects non-structured-clone values at call site
|
|
|
|
The package SHALL pre-check arguments and return values for structured-clone safety before sending. Values that are NOT structured-clone-safe (functions, class instances without an explicit `serialize` hook, `Symbol`s) MUST throw `RPC_NOT_CLONEABLE` synchronously at the call site, naming the offending path (e.g. `"args[0].onCallback"`). Silent corruption of the wire MUST NOT be possible.
|
|
|
|
#### Scenario: function argument throws at call site
|
|
|
|
- **WHEN** `caller.method({ onProgress: () => {} })` is invoked
|
|
- **THEN** the call throws `RPC_NOT_CLONEABLE` synchronously AND `details.path === "args[0].onProgress"`
|
|
|
|
#### Scenario: cloneable nested object passes
|
|
|
|
- **WHEN** `caller.method({ a: { b: { c: 1 } } })` is invoked with a deeply-nested plain object
|
|
- **THEN** the call proceeds without error
|
|
|
|
**Verified by:** `src/cloneable-guard/cloneable-guard.test.ts::"function argument throws RPC_NOT_CLONEABLE"` AND `src/cloneable-guard/cloneable-guard.test.ts::"cloneable nested object passes"`
|
|
|
|
---
|
|
|
|
### Requirement: Caller type wraps every return type in Promise
|
|
|
|
The package SHALL expose `createRpcCaller<T>(port): WorkerProxyOf<T>`. The proxy's method signatures SHALL match `WorkerProxyOf<T>` from `api-types/worker-rpc`: every return type wrapped in `Promise<R>`, every method name preserved, non-cloneable parameter types flagged via the type system.
|
|
|
|
#### Scenario: every method's return type is Promise-wrapped
|
|
|
|
- **WHEN** `expectTypeOf<ReturnType<Caller<T>["someMethod"]>>()` is checked
|
|
- **THEN** it equals `Promise<R>` where `R` is the original return type
|
|
|
|
**Verified by:** `src/caller/caller.spec-conformance.test.ts::"every method return is Promise-wrapped"`
|
|
|
|
---
|
|
|
|
### Requirement: Wire protocol versions explicitly with mismatch rejection
|
|
|
|
The package SHALL embed a `protocolVersion` string (semver) in every `RpcRequest` and `RpcResponse`. Receivers MUST reject messages whose version is outside the supported range with `RPC_PROTOCOL_VERSION_MISMATCH`. The version is fixed at `"1.0.0"` for this Stage-3 ship; future incompatible changes MUST bump the major.
|
|
|
|
#### Scenario: mismatched protocol version rejects
|
|
|
|
- **WHEN** a message arrives with `protocolVersion: "2.0.0"`
|
|
- **THEN** the receiver throws `RPC_PROTOCOL_VERSION_MISMATCH` AND no impl method runs
|
|
|
|
**Verified by:** `tests/conformance/round-trip.test.ts::"mismatched protocol version is rejected"`
|