88 lines
2.5 KiB
Markdown
88 lines
2.5 KiB
Markdown
# @wrnexus/realtime
|
|
|
|
Typed rooms, secure message envelopes, browser room helpers, presence utilities, and complete realtime UI blocks for WRNexusJS.
|
|
|
|
## Server rooms
|
|
|
|
```ts
|
|
import { defineRoom } from "@wrnexus/realtime";
|
|
|
|
export default defineRoom("support", {
|
|
async authorize(context) {
|
|
return Boolean(context.user);
|
|
},
|
|
message(client, message) {
|
|
client.broadcast(message);
|
|
},
|
|
});
|
|
```
|
|
|
|
The package re-exports the hardened realtime registry from `@wrnexus/core`, including authentication, origin checks, quotas, message-size limits, schema validation hooks, and room authorization.
|
|
|
|
## Messages and browser helpers
|
|
|
|
```ts
|
|
import {
|
|
createRealtimeMessage,
|
|
createPresenceEvent,
|
|
createTypingEvent,
|
|
connectRoom,
|
|
sendRoomMessage,
|
|
} from "@wrnexus/realtime";
|
|
|
|
const room = connectRoom("support", { query: { ticket: "T-100" } });
|
|
sendRoomMessage(
|
|
room,
|
|
createRealtimeMessage({
|
|
type: "message",
|
|
room: "support",
|
|
data: { text: "Hello" },
|
|
}),
|
|
);
|
|
```
|
|
|
|
Message IDs use Web Crypto. A runtime without secure randomness must provide an explicit message ID.
|
|
|
|
## Components
|
|
|
|
Enable `realtimePlugin()` and use:
|
|
|
|
- `<RealtimeRoom />`
|
|
- `<RealtimeMessageBubble />`
|
|
- `<MessageComposer />`
|
|
- `<RoomStatus />`
|
|
- `<RoomMeta />`
|
|
- `<PresenceList />`
|
|
- `<TypingIndicator />`
|
|
|
|
These package-owned blocks compose existing `@wrnexus/ui` components such as `Card`, `Alert`, `Avatar`, `Badge`, `Button`, `Input`, and `ChatBubble`.
|
|
|
|
Incoming messages can be bounded and constrained:
|
|
|
|
```ts
|
|
const message = parseRealtimeMessage(rawMessage, {
|
|
maxBytes: 64 * 1024,
|
|
maxDepth: 12,
|
|
allowedTypes: ["message", "typing", "presence"],
|
|
room: "support",
|
|
});
|
|
```
|
|
|
|
The parser rejects oversized payloads, circular/unsupported values, unsafe object keys, invalid message types, invalid room names, and room mismatches.
|
|
|
|
## Replay, acknowledgements, SSE, and monitoring
|
|
|
|
`createRealtimeHistory()` keeps a bounded sequenced log per room. Clients acknowledge a
|
|
sequence and `resume(room, clientId)` returns only missed events. A snapshot exposes room,
|
|
message, acknowledgement, and sequence counts for monitoring without exposing payloads.
|
|
|
|
```ts
|
|
const history = createRealtimeHistory({ limitPerRoom: 100 });
|
|
const entry = history.publish("support", message);
|
|
history.acknowledge("support", clientId, entry.sequence);
|
|
const missed = history.resume("support", clientId);
|
|
```
|
|
|
|
`realtimeSseResponse(stream, signal)` converts the same sequenced envelope into standards-based
|
|
Server-Sent Events with event IDs, event types, JSON data, cancellation, and no-cache headers.
|