# WebSocket push
> Status: **SCAFFOLD.**
Status: planned
Source: https://github.com/bhmortim/quidnug/tree/main/integrations/websocket
# Quidnug WebSocket stream subscriber (scaffold)

Status: **SCAFFOLD.**

Long-lived WebSocket push interface for real-time Quidnug event
streams, block updates, and guardian-lifecycle notifications.

## Planned protocol

```
Client → Server:
  { "type": "subscribe", "topic": "stream:<subjectId>", "since": <sequence> }
  { "type": "subscribe", "topic": "blocks:<domain>", "fromHeight": N }
  { "type": "subscribe", "topic": "guardian:<quidId>" }

Server → Client:
  { "type": "event",  "topic": "stream:…",    "payload": { event } }
  { "type": "block",  "topic": "blocks:…",    "payload": { block } }
  { "type": "ping" }   # every 30s
  { "type": "error",  "reason": "…" }
```

Transport: JSON over WS or MessagePack over WS, negotiated via the
`Sec-WebSocket-Protocol` header.

## Use cases

- React hook `useLiveStream(subjectId)`, real-time event feed
  without polling.
- Guardian dashboards that reflect set-updates and pending recoveries
  the instant they're accepted.
- Cross-domain bridges that react to anchor-gossip arrivals.

## Roadmap

1. Implement server-side WS endpoint at `/api/ws/stream` inside the
   Go node. Reuse existing event-stream + block-ledger internals.
2. Client ports to JS, Python, Go, Rust.
3. Backpressure + reconnection semantics documented in the protocol
   guide.

## License

Apache-2.0.