RpcClient: connect, request/response, ID routing

charles commented

2026-04-11 10:55:37 +00:00

Owner

User story

As a test author, I want to send a JSON-RPC request and await its response with one call, so that I never have to track message IDs or correlate responses by hand.

Acceptance criteria

Connection

RpcClient::connect(url, token: Option<&str>) opens a WebSocket via tokio-tungstenite.
If token is Some, it is sent as Authorization: Bearer <token> during the upgrade.
A configurable connect timeout (default 10 s) wraps the upgrade.
Returns Result<Self, TestError>; failures map to TestError::Connection.

Concurrency model

The client uses interior mutability — Arc<Inner> with channels — so that call, subscribe, wait_for, and wait_for_any all take &self and can be safely called from cloned handles in different tasks. This resolves the spec-review §1 ergonomics issue.
A background reader task drives the WebSocket; ID-bearing messages dispatch to a oneshot channel registered when the request was sent. Notifications (no id) are forwarded to the buffer (handled in a separate issue).

call / call_timeout

call(method, params) -> Result<Value, TestError> sends:
```
{"jsonrpc":"2.0","id":N,"method":"...","params":...}
```
where N is auto-incremented per client (u64).
Awaits the matching response by ID and returns the result field as serde_json::Value.
Per-call timeout default is 30 s; call_timeout(method, params, duration) lets callers override.
On timeout returns TestError::Timeout { event: format!("call:{method}"), duration }.
A JSON-RPC error response returns Err(TestError::RpcError { code, message }). This clarifies the spec-review §6 ambiguity: call returns Ok(Value) only on JSON-RPC success, JSON-RPC errors become Err(RpcError).
If the caller passes Value::Null as params, the framework rewrites it to {} before sending (per spec §4.1).

Out of scope

Notification buffering (separate issue).
Subscribe / wait_for (separate issue).
Auto-reconnect.

References

Spec §2.1, §2.2, §3.2, §4 (JSON-RPC protocol), spec review §1 and §6

## User story As a **test author**, I want to send a JSON-RPC request and `await` its response with one call, so that I never have to track message IDs or correlate responses by hand. ## Acceptance criteria ### Connection - [ ] `RpcClient::connect(url, token: Option<&str>)` opens a WebSocket via `tokio-tungstenite`. - [ ] If `token` is `Some`, it is sent as `Authorization: Bearer <token>` during the upgrade. - [ ] A configurable connect timeout (default 10 s) wraps the upgrade. - [ ] Returns `Result<Self, TestError>`; failures map to `TestError::Connection`. ### Concurrency model - [ ] The client uses interior mutability — `Arc<Inner>` with channels — so that `call`, `subscribe`, `wait_for`, and `wait_for_any` all take `&self` and can be safely called from cloned handles in different tasks. **This resolves the spec-review §1 ergonomics issue.** - [ ] A background reader task drives the WebSocket; ID-bearing messages dispatch to a oneshot channel registered when the request was sent. Notifications (no `id`) are forwarded to the buffer (handled in a separate issue). ### call / call_timeout - [ ] `call(method, params) -> Result<Value, TestError>` sends: ```json {"jsonrpc":"2.0","id":N,"method":"...","params":...} ``` where `N` is auto-incremented per client (`u64`). - [ ] Awaits the matching response by ID and returns the `result` field as `serde_json::Value`. - [ ] Per-call timeout default is 30 s; `call_timeout(method, params, duration)` lets callers override. - [ ] On timeout returns `TestError::Timeout { event: format!("call:{method}"), duration }`. - [ ] A JSON-RPC error response returns `Err(TestError::RpcError { code, message })`. **This clarifies the spec-review §6 ambiguity: `call` returns `Ok(Value)` only on JSON-RPC success, JSON-RPC errors become `Err(RpcError)`.** - [ ] If the caller passes `Value::Null` as params, the framework rewrites it to `{}` before sending (per spec §4.1). ## Out of scope - Notification buffering (separate issue). - Subscribe / wait_for (separate issue). - Auto-reconnect. ## References - Spec §2.1, §2.2, §3.2, §4 (JSON-RPC protocol), spec review §1 and §6

charles added this to the v0.1.0 milestone

2026-04-11 10:55:37 +00:00

charles added the

area:client

type:user-story

labels

2026-04-11 10:55:37 +00:00

charles referenced this issue from a commit

2026-04-11 12:12:54 +00:00

feat(client): WebSocket connect, call/call_timeout, id routing (closes #4)

charles referenced this issue from a pull request that will close it,

2026-04-11 12:13:22 +00:00