RpcClient: bounded notification buffer with overflow policy #5

New issue

Closed

opened 2026-04-11 10:55:37 +00:00 by charles · 0 comments

charles commented

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

Owner

User story

As a test author, I want events that arrive before I call wait_for to still be observable, so that my tests don't race the server.

Acceptance criteria

The reader task classifies incoming JSON-RPC messages:
- id present → response routing (handled in the request/response issue).
- No id → notification.
Notifications are stored in a bounded VecDeque<NotificationRecord> of configurable capacity (RpcClient::with_buffer_size, default 1000), behind a Mutex or RwLock.
On overflow the oldest notification is dropped.
Drop policy is logged via eprintln! rate-limited to once per 100 drops to avoid log spam. The log message names the buffer's current size and the drop count since the last warning.
Notifications also fan out to a tokio::sync::broadcast channel (capacity = buffer capacity) so that wait_for waiters are woken up on new arrivals.
An internal API drains matching items from the buffer (used by wait_for and collect_events).
On Drop / explicit close(), the reader task is signalled to stop and the WebSocket is closed cleanly.
Unit-test the buffer in isolation: fill past capacity, verify oldest are dropped, verify drain matches predicate.

Notes

The drop-warning behaviour is opinionated but not configurable in v0.1; it can be promoted to a builder option later if users need silent mode.

References

Spec §4.3 (Notification buffering)

## User story As a **test author**, I want events that arrive **before** I call `wait_for` to still be observable, so that my tests don't race the server. ## Acceptance criteria - [ ] The reader task classifies incoming JSON-RPC messages: - `id` present → response routing (handled in the request/response issue). - No `id` → notification. - [ ] Notifications are stored in a bounded `VecDeque<NotificationRecord>` of configurable capacity (`RpcClient::with_buffer_size`, default **1000**), behind a `Mutex` or `RwLock`. - [ ] On overflow the **oldest** notification is dropped. - [ ] Drop policy is logged via `eprintln!` rate-limited to once per 100 drops to avoid log spam. The log message names the buffer's current size and the drop count since the last warning. - [ ] Notifications also fan out to a `tokio::sync::broadcast` channel (capacity = buffer capacity) so that `wait_for` waiters are woken up on new arrivals. - [ ] An internal API drains matching items from the buffer (used by `wait_for` and `collect_events`). - [ ] On `Drop` / explicit `close()`, the reader task is signalled to stop and the WebSocket is closed cleanly. - [ ] Unit-test the buffer in isolation: fill past capacity, verify oldest are dropped, verify drain matches predicate. ## Notes The drop-warning behaviour is opinionated but not configurable in v0.1; it can be promoted to a builder option later if users need silent mode. ## References - Spec §4.3 (Notification buffering)

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

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