181 lines
9.2 KiB
Markdown
181 lines
9.2 KiB
Markdown
<!-- markdownlint-disable MD024 -->
|
|
|
|
# Capability Spec Delta: broadcast-channel (add-broadcast-channel)
|
|
|
|
**Package**: `@suaveplan/broadcast-channel`
|
|
**Status**: PROPOSED
|
|
|
|
> Every requirement below carries a `**Verified by:**` line at authoring time. (See `openspec/AGENTS.md` §13.)
|
|
|
|
## ADDED Requirements
|
|
|
|
### Requirement: Typed cross-tab channel lifecycle
|
|
|
|
The package SHALL expose `TypedBroadcastChannel` providing `open()`, `close()`, `send<T>(type, payload)`, `on<T>(type, handler)`, `getTabId()`, `getTabs()`, `getTabCount()`, `getIsLeader()`, and `isOpen()`. `open()` MUST be idempotent (re-opening an open channel is a no-op); `close()` SHALL be safe to call before `open()` and SHALL clear all tracked tabs and handlers.
|
|
|
|
#### Scenario: open then close is reversible
|
|
|
|
- **WHEN** a consumer calls `open()` then `close()`
|
|
- **THEN** `isOpen()` returns `false`, `getTabs()` returns `[]`, and the underlying `ChannelLike.close()` has been invoked exactly once
|
|
|
|
#### Scenario: open is idempotent
|
|
|
|
- **WHEN** `open()` is called twice without a `close()` in between
|
|
- **THEN** only one `ChannelLike` is created via the injected factory
|
|
|
|
**Verified by:** `src/channel/channel.test.ts::"opens and closes the channel"` AND `src/channel/channel.test.ts::"open is idempotent"` AND `src/channel/channel.test.ts::"close is safe before open"`
|
|
|
|
---
|
|
|
|
### Requirement: Leader election by lowest tab ID
|
|
|
|
The package SHALL elect a leader by sorted lowest tab ID across all known tabs. When a tab joins or leaves, the leader SHALL be re-elected; the local tab SHALL emit `leader:elected` once when it transitions from non-leader to leader.
|
|
|
|
#### Scenario: solo tab is leader
|
|
|
|
- **WHEN** a `TypedBroadcastChannel` opens with no peers
|
|
- **THEN** `getIsLeader()` returns `true`
|
|
|
|
#### Scenario: lower-ID peer wins
|
|
|
|
- **WHEN** a peer with lexicographically lower ID joins
|
|
- **THEN** `getIsLeader()` returns `false` and `getTabs()` reports the peer as `isLeader: true`
|
|
|
|
**Verified by:** `src/channel/channel.test.ts::"becomes leader when alone"` AND `src/channel/channel.test.ts::"yields leadership to lower tab id"`
|
|
|
|
---
|
|
|
|
### Requirement: Tab presence with heartbeats and stale cleanup
|
|
|
|
The channel SHALL emit periodic `heartbeat` frames at the configured `heartbeatInterval` and SHALL evict tabs whose `lastSeen` exceeds `tabTimeout`. `tab:joined` and `tab:left` SHALL fire on the corresponding inbound frames.
|
|
|
|
#### Scenario: heartbeat fires on interval
|
|
|
|
- **WHEN** the channel has been open longer than two `heartbeatInterval` ticks
|
|
- **THEN** at least one `heartbeat` frame has been posted to the underlying channel
|
|
|
|
#### Scenario: stale tab is evicted
|
|
|
|
- **WHEN** a peer's `lastSeen` exceeds `tabTimeout`
|
|
- **THEN** the peer is removed from `getTabs()` on the next cleanup tick
|
|
|
|
**Verified by:** `src/channel/channel.test.ts::"emits heartbeat on interval"` AND `src/channel/channel.test.ts::"evicts stale peers"`
|
|
|
|
---
|
|
|
|
### Requirement: Zod boundary on inbound frames
|
|
|
|
Every inbound frame SHALL be validated against `ChannelMessageSchema` before dispatch. Malformed frames SHALL be dropped silently (no handlers invoked, no tab state mutated) and SHALL increment the `channel.message.dropped` counter; the optional injected `LoggerLike.warn` SHALL be called with the validation issue.
|
|
|
|
#### Scenario: well-formed frame is dispatched
|
|
|
|
- **WHEN** an inbound frame matches `ChannelMessageSchema`
|
|
- **THEN** registered handlers for its `type` are invoked
|
|
|
|
#### Scenario: malformed frame is dropped
|
|
|
|
- **WHEN** an inbound frame is missing required fields (e.g. no `id`)
|
|
- **THEN** no handler runs, `getTabCount()` is unchanged for the malformed senderId, and `channel.message.dropped` increments
|
|
|
|
**Verified by:** `src/channel/channel.test.ts::"dispatches valid frames to handlers"` AND `src/channel/channel.test.ts::"drops malformed frames and warns"` AND `src/schemas/messages.test.ts::"accepts valid frames"` AND `src/schemas/messages.test.ts::"rejects frames missing required fields"`
|
|
|
|
---
|
|
|
|
### Requirement: Typed `MessageEvent` listener
|
|
|
|
`ChannelLike.addEventListener` SHALL accept `(type: "message", listener: (event: MessageEvent) => void)`. The `any`-typed listener parameter present upstream MUST NOT appear in the genesis surface.
|
|
|
|
#### Scenario: native transport hands back `MessageEvent`
|
|
|
|
- **WHEN** a frame is posted through the native factory's underlying `BroadcastChannel`
|
|
- **THEN** the listener receives an object whose `data` is the original payload and whose static type at the call site is `MessageEvent`
|
|
|
|
**Verified by:** `src/transport/native.test.ts::"round-trips a frame through native BroadcastChannel"`
|
|
|
|
---
|
|
|
|
### Requirement: `BroadcastChannel`-less fallback via `StorageLike`
|
|
|
|
When the host environment lacks `BroadcastChannel`, callers SHALL be able to use `createLocalStorageChannelFactory(storage, options)`. The factory MUST produce `ChannelLike` instances that round-trip `postMessage` payloads to every other open channel of the same name through the injected `StorageLike`. `close()` MUST stop the polling loop and remove all listeners.
|
|
|
|
#### Scenario: two channels exchange a frame
|
|
|
|
- **WHEN** channel A posts a frame on name `"x"` and channel B is also open on `"x"`
|
|
- **THEN** channel B's `message` listener fires with `event.data` deep-equal to the posted frame
|
|
|
|
#### Scenario: closed channel stops polling
|
|
|
|
- **WHEN** channel A is closed
|
|
- **THEN** subsequent posts on `"x"` MUST NOT invoke A's listener
|
|
|
|
**Verified by:** `src/transport/local-storage.test.ts::"round-trips a frame between two channels"` AND `src/transport/local-storage.test.ts::"stops receiving after close"`
|
|
|
|
---
|
|
|
|
### Requirement: OpenTelemetry observability
|
|
|
|
The package SHALL emit six instruments under meter `@suaveplan/broadcast-channel`: counter `channel.message.sent`, counter `channel.message.received`, counter `channel.message.dropped`, counter `channel.tab.joined`, counter `channel.tab.left`, counter `channel.leader.elected`. `refreshBroadcastChannelMeters()` SHALL re-resolve every instrument against the current global `MeterProvider` so test setups can rebind to an in-memory exporter.
|
|
|
|
#### Scenario: send emits sent counter
|
|
|
|
- **WHEN** a consumer calls `send("greet", payload)`
|
|
- **THEN** `channel.message.sent` has been incremented by 1 with attribute `{type: "greet"}`
|
|
|
|
#### Scenario: malformed frame emits dropped counter
|
|
|
|
- **WHEN** the channel receives a malformed frame
|
|
- **THEN** `channel.message.dropped` has been incremented by 1 with attribute `{reason: "malformed"}`
|
|
|
|
#### Scenario: leadership transition emits leader counter
|
|
|
|
- **WHEN** the local tab becomes leader
|
|
- **THEN** `channel.leader.elected` has been incremented by 1
|
|
|
|
**Verified by:** `src/otel/metrics.test.ts::"send increments channel.message.sent"` AND `src/otel/metrics.test.ts::"malformed frame increments channel.message.dropped"` AND `src/otel/metrics.test.ts::"tab join increments channel.tab.joined"` AND `src/otel/metrics.test.ts::"tab leave increments channel.tab.left"` AND `src/otel/metrics.test.ts::"leadership transition increments channel.leader.elected"`
|
|
|
|
---
|
|
|
|
### Requirement: Payload-size guard
|
|
|
|
`send<T>(type, payload)` SHALL serialize the message frame and reject any payload whose serialized JSON byte length exceeds `config.maxMessageBytes` (default 1 MiB) by throwing `BroadcastChannelPayloadTooLargeError` with code `BROADCAST_CHANNEL.PAYLOAD_TOO_LARGE`.
|
|
|
|
#### Scenario: over-budget payload is rejected
|
|
|
|
- **WHEN** `send("big", payload)` is called with a payload whose JSON encoding exceeds `maxMessageBytes`
|
|
- **THEN** the call throws `BroadcastChannelPayloadTooLargeError` and no frame is posted to the underlying channel
|
|
|
|
**Verified by:** `src/channel/channel.test.ts::"rejects payloads above maxMessageBytes"`
|
|
|
|
---
|
|
|
|
### Requirement: Stable `BROADCAST_CHANNEL_*` error registry
|
|
|
|
The package SHALL export `BROADCAST_CHANNEL_CODES` built via `defineCodes("BROADCAST_CHANNEL", [...])` with reasons `CHANNEL_CLOSED`, `MESSAGE_MALFORMED`, `PAYLOAD_TOO_LARGE`, `STORAGE_FAILED`. Every code SHALL be thrown from at least one production code path and the registry SHALL be frozen.
|
|
|
|
#### Scenario: registry is frozen
|
|
|
|
- **WHEN** a caller attempts to mutate `BROADCAST_CHANNEL_CODES`
|
|
- **THEN** the mutation throws in strict mode
|
|
|
|
#### Scenario: every code reachable
|
|
|
|
- **WHEN** the test suite exercises closed-channel send, malformed frame, oversized payload, and a failing storage backend
|
|
- **THEN** each of the four codes is observed on a thrown error or a `Report.code` field
|
|
|
|
**Verified by:** `src/errors/codes.test.ts::"registry is frozen and shape matches"` AND `src/errors/codes.test.ts::"every code is thrown by a production path"`
|
|
|
|
---
|
|
|
|
### Requirement: Injectable `Clock` / `Rng` / `LoggerLike`
|
|
|
|
`TypedBroadcastChannel` SHALL accept optional `clock`, `rng`, and `logger` injections matching `Clock`, `Rng`, and `LoggerLike` from `@suaveplan/types`. Defaults SHALL use `Date.now`, `crypto.getRandomValues`, and a no-op logger. All timestamps and IDs in produced frames SHALL derive from the injected sources.
|
|
|
|
#### Scenario: deterministic IDs from seeded Rng
|
|
|
|
- **WHEN** the channel is constructed with a seeded `Rng`
|
|
- **THEN** the produced tab ID and outbound message IDs match a fixed expected hex string
|
|
|
|
**Verified by:** `src/channel/channel.test.ts::"derives tab id from injected rng"` AND `src/id/id.test.ts::"derives a 16-hex id from rng bytes"`
|
|
|
|
<!-- markdownlint-enable MD024 -->
|