redweb 0.11.0 → 0.13.0

package/src/ws/SocketContract.js

@@ -0,0 +1,112 @@
+'use strict';
+
+const { BaseHandler } = require('./BaseHandler');
+const { ProtocolClient } = require('../../client');
+const { ContractValidationError, InboundContractValidationError } = require('./ContractValidationError');
+const { SchemaValidator } = require('../validation/SchemaValidator');
+
+function boundedName(value, label) {
+    if (typeof value !== 'string' || !value || value.length > 256) throw new TypeError(`${label} must be a non-empty string of at most 256 characters.`);
+    return value;
+}
+
+async function validatedWirePayload(contract, type, payload) {
+    let serialized, input;
+    try {
+        serialized = JSON.stringify(payload);
+        input = JSON.parse(serialized);
+    }
+    catch { throw new ContractValidationError(); }
+    await contract.parse(type, input);
+    // A validator may mutate its argument. Always send the original input snapshot.
+    return JSON.parse(serialized);
+}
+
+class ContractClient {
+    constructor(contract, socket) {
+        this.contract = contract;
+        this.protocol = new ProtocolClient(socket, contract.version);
+    }
+
+    async envelope(type, payload, metadata) {
+        const input = await validatedWirePayload(this.contract, type, payload);
+        // Validate the input, but keep its wire representation. Receiver-side transforms run exactly once.
+        return this.protocol.envelope(type, input, metadata);
+    }
+
+    async send(type, payload, metadata) {
+        this.protocol.socket.send(JSON.stringify(await this.envelope(type, payload, metadata)));
+    }
+
+    async parse(input) {
+        const message = this.protocol.parse(input);
+        if (message.type === 'error') return message;
+        return { ...message, payload: await this.contract.parse(message.type, message.payload) };
+    }
+}
+
+class SocketContract {
+    #validators;
+
+    constructor(version, schemas, options) {
+        boundedName(version, 'Contract version');
+        if (version.length > 64) throw new TypeError('Contract version must be at most 64 characters.');
+        if (!schemas || typeof schemas !== 'object' || Array.isArray(schemas)) throw new TypeError('Contract schemas must be an object.');
+        if (!options || typeof options !== 'object' || Array.isArray(options)) throw new TypeError('Contract options must be an object.');
+        const timeout = options.validationTimeoutMs ?? 5000;
+        const entries = Object.entries(schemas);
+        if (!entries.length || entries.length > 256) throw new TypeError('A socket contract must define between 1 and 256 message types.');
+        this.#validators = new Map(entries.map(([type, schema]) => {
+            boundedName(type, 'Contract message type');
+            if (type === 'error') throw new TypeError('The error message type is reserved by the protocol.');
+            return [type, new SchemaValidator(schema, timeout)];
+        }));
+        this.version = version;
+        this.validationTimeoutMs = timeout;
+        this.types = Object.freeze(entries.map(([type]) => type));
+        this.protocol = Object.freeze({ versions: Object.freeze([version]) });
+        Object.freeze(this);
+    }
+
+    async parse(type, payload) {
+        const validate = this.#validators.get(type);
+        if (!validate) throw new ContractValidationError('UNKNOWN_HANDLER');
+        try {
+            return await validate.parse(payload);
+        } catch {
+            // Validator details can contain application data. Never expose them as protocol errors.
+            throw new ContractValidationError();
+        }
+    }
+
+    handler(type, callback) {
+        if (!this.#validators.has(type)) throw new TypeError('Handler message type is not defined in the contract.');
+        if (typeof callback !== 'function') throw new TypeError('A contract handler requires a callback.');
+        const contract = this;
+        return class ContractHandler extends BaseHandler {
+            constructor() { super(type); }
+            async handleMessage(socket, message) {
+                if (socket.context?.protocol?.version !== contract.version) throw new TypeError('The route must negotiate this contract version before handling messages.');
+                let payload;
+                try { payload = await contract.parse(type, message.payload); }
+                catch { throw new InboundContractValidationError(); }
+                return super.handleMessage(socket, { ...message, payload });
+            }
+            onMessage(socket, message) { return callback(socket, message.payload, message); }
+        };
+    }
+
+    client(socket) { return new ContractClient(this, socket); }
+
+    async send(socket, type, payload, metadata) {
+        if (socket.context?.protocol?.version !== this.version) throw new TypeError('The socket must negotiate this contract version before sending events.');
+        const input = await validatedWirePayload(this, type, payload);
+        return socket.sendEvent(type, input, metadata);
+    }
+}
+
+function defineSocketContract(version, schemas, options = {}) {
+    return new SocketContract(version, schemas, options);
+}
+
+module.exports = { defineSocketContract };

package/src/ws/SocketRoute.js

@@ -8,6 +8,8 @@ const TransportPolicy = require('./TransportPolicy');
 const Metrics = require('./Metrics');
 const RouteRuntime = require('./RouteRuntime');
 const { ProtocolPolicy, ERROR_CODES } = require('./ProtocolPolicy');
+const { InboundContractValidationError } = require('./ContractValidationError');
+const { RequestFailure } = require('../access/RequestFailure');
 
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
@@ -272,6 +274,7 @@ class SocketRoute {
         if (!this.allowDuplicateConnections) {
             const existing = this.clients.get(clientKey);
             if (existing) {
+                this.runtime.detach(existing);
                 this.logger.warn?.(`Client ${ip} already connected, disconnecting existing connection.`);
                 if (existing.sendEvent) {
                     existing.sendEvent('system.disconnect', { reason: 'replaced' });
@@ -344,6 +347,14 @@ class SocketRoute {
         );
     }
 
+    sendAccessFailure(socket, error, metadata) {
+        const failure = RequestFailure.from(error);
+        if (!failure.code.startsWith('ACCESS_')) return false;
+        if (this.protocolPolicy && socket.context?.protocol) this.sendFailure(socket, failure.code, failure.message, metadata);
+        else this.send(socket, { code: failure.code, error: failure.message });
+        return true;
+    }
+
     async sendBinary(socket, value) {
         try {
             const encoded = await this.protocolPolicy.encodeBinary(value, socket.context);
@@ -440,6 +451,12 @@ class SocketRoute {
                 await handler.handleMessage(sock, data);
                 return true;
             } catch (error) {
+                if (this.sendAccessFailure(sock, error, { requestId: data.requestId })) return false;
+                if (error instanceof InboundContractValidationError) {
+                    this.sendFailure(sock, error.code, error.message, { requestId: data.requestId });
+                    sock.close?.(1008, 'Invalid contract payload');
+                    return false;
+                }
                 this.logger.error?.(`Error handling message in handler ${handler.name}:`, error);
                 this.metrics?.increment('redweb.handlers.failed');
                 this.sendFailure(sock, ERROR_CODES.HANDLER_FAILED, this.exposeErrors ? errorMessage(error) : 'Handler failed', { requestId: data.requestId });
@@ -476,6 +493,7 @@ class SocketRoute {
             await handler.handleBinaryMessage(socket, buffer);
             return true;
         } catch (error) {
+            if (this.sendAccessFailure(socket, error)) return false;
             this.logger.error?.('Error handling binary message:', error);
             this.metrics?.increment('redweb.handlers.failed');
             this.sendFailure(socket, ERROR_CODES.HANDLER_FAILED, this.exposeErrors ? errorMessage(error) : 'Binary handler failed');

package/src/ws/protocol-schema.json

@@ -2,12 +2,17 @@
   "schemaVersion": 1,
   "errorCodes": [
     "INVALID_MESSAGE",
+    "INVALID_PAYLOAD",
     "UNKNOWN_HANDLER",
     "HANDLER_FAILED",
     "BINARY_UNSUPPORTED",
     "RATE_LIMITED",
     "QUEUE_FULL",
     "CAPACITY_REACHED",
-    "INITIALIZATION_FAILED"
+    "INITIALIZATION_FAILED",
+    "ACCESS_DENIED",
+    "ACCESS_TIMEOUT",
+    "ACCESS_CANCELLED",
+    "ACCESS_CAPACITY"
   ]
 }

package/examples/live-html/chatroom.ts

@@ -1,217 +0,0 @@
-import { action, component, each, html, page, start, state, type HtmlFragment } from 'redweb';
-
-const MAX_VISIBLE_MEMBERS = 100;
-const UNSAFE_TEXT = /[\p{Cc}\p{Cf}]/u;
-
-interface JoinForm {
-    name?: string;
-}
-
-interface MessageForm {
-    message?: string;
-}
-
-interface StoredMessage {
-    sender: string;
-    text: string;
-}
-
-interface RoomParticipant {
-    readonly displayName: string;
-    updateMessages(messages: HtmlFragment): void;
-    updatePresence(presence: HtmlFragment): void;
-}
-
-function messageView(messages: readonly StoredMessage[]) {
-    return messages.length
-        ? each([...messages], entry => html`<li><strong>${entry.sender}</strong><p>${entry.text}</p></li>`)
-        : html`<li class="empty-message">No messages yet. Say hello.</li>`;
-}
-
-function presenceView(members: readonly string[]) {
-    const visible = members.slice(0, MAX_VISIBLE_MEMBERS);
-    const remaining = members.length - visible.length;
-    return html`
-        <p class="eyebrow">Online · ${members.length}</p>
-        <ul>
-            ${each([...visible], member => html`<li>${member}</li>`)}
-            ${remaining ? html`<li class="more-members">+${remaining} more</li>` : html``}
-        </ul>
-    `;
-}
-
-class ChatRoom {
-    private history: StoredMessage[] = [];
-    private readonly participants = new Set<RoomParticipant>();
-    private readonly online = new Set<RoomParticipant>();
-
-    join(participant: RoomParticipant) {
-        const name = participant.displayName.toLocaleLowerCase();
-        if ([...this.participants].some(member => member !== participant && member.displayName.toLocaleLowerCase() === name)) {
-            return false;
-        }
-        this.participants.add(participant);
-        this.online.add(participant);
-        participant.updateMessages(messageView(this.history));
-        this.publishPresence();
-        return true;
-    }
-
-    disconnect(participant: RoomParticipant) {
-        if (!this.online.delete(participant)) return;
-        this.publishPresence();
-    }
-
-    leave(participant: RoomParticipant) {
-        this.online.delete(participant);
-        if (!this.participants.delete(participant)) return;
-        this.publishPresence();
-    }
-
-    send(participant: RoomParticipant, text: string) {
-        if (!this.online.has(participant)) return false;
-        this.history = [...this.history, { sender: participant.displayName, text }].slice(-100);
-        const messages = messageView(this.history);
-        for (const member of this.participants) member.updateMessages(messages);
-        return true;
-    }
-
-    private publishPresence() {
-        const members = [...this.online].map(participant => participant.displayName);
-        const presence = presenceView(members);
-        for (const participant of this.participants) participant.updatePresence(presence);
-    }
-}
-
-@component()
-export class ChatroomComponent implements RoomParticipant {
-    displayName = '';
-
-    @state()
-    screen = this.joinScreen();
-
-    @state()
-    messages = messageView([]);
-
-    @state()
-    presence = presenceView([]);
-
-    constructor(private readonly room: ChatRoom) {}
-
-    connected() {
-        if (this.displayName) this.room.join(this);
-    }
-
-    disconnected() {
-        this.room.disconnect(this);
-    }
-
-    disposed() {
-        this.room.leave(this);
-    }
-
-    @action()
-    join({ name }: JoinForm) {
-        if (this.displayName) return false;
-        if (typeof name !== 'string') {
-            this.screen = this.joinScreen('Display name must be text.');
-            return false;
-        }
-        const displayName = name.normalize('NFKC').trim();
-        if (!displayName || displayName.length > 40 || UNSAFE_TEXT.test(displayName)) {
-            this.screen = this.joinScreen('Choose a visible display name of at most 40 characters.');
-            return false;
-        }
-        this.displayName = displayName;
-        if (this.room.join(this)) {
-            this.screen = this.roomScreen();
-            return true;
-        }
-        this.displayName = '';
-        this.screen = this.joinScreen('That display name is already in use.');
-        return false;
-    }
-
-    @action()
-    send({ message }: MessageForm) {
-        if (typeof message !== 'string') return false;
-        const text = message.normalize('NFKC').trim();
-        if (!text || text.length > 500 || UNSAFE_TEXT.test(text)) return false;
-        return this.room.send(this, text);
-    }
-
-    @action()
-    leave() {
-        this.room.leave(this);
-        this.displayName = '';
-        this.screen = this.joinScreen();
-    }
-
-    updateMessages(messages: HtmlFragment) {
-        this.messages = messages;
-    }
-
-    updatePresence(presence: HtmlFragment) {
-        this.presence = presence;
-    }
-
-    render() {
-        return html`<section class="chatroom" data-rw-state="screen">${this.screen}</section>`;
-    }
-
-    private joinScreen(error = '') {
-        const feedback = error ? html`<p class="form-error" role="alert">${error}</p>` : html``;
-        return html`
-            <section class="join-panel">
-                <p class="eyebrow">Live room</p>
-                <h1>Join the chatroom</h1>
-                <p>Choose a name once, then chat in realtime with everyone currently in the room.</p>
-                ${feedback}
-                <form rw-submit="join" class="join-form">
-                    <label for="display-name">Display name</label>
-                    <div class="input-row">
-                        <input id="display-name" name="name" maxlength="40" autocomplete="nickname" required autofocus>
-                        <button type="submit">Join room</button>
-                    </div>
-                </form>
-            </section>
-        `;
-    }
-
-    private roomScreen() {
-        return html`
-            <div class="room-layout">
-                <section class="conversation">
-                    <header class="room-header">
-                        <div><p class="eyebrow">Connected as</p><h1>${this.displayName}</h1></div>
-                        <button type="button" class="quiet-button" rw-click="leave">Leave</button>
-                    </header>
-                    <ol class="message-list" aria-live="polite" data-rw-state="messages">${this.messages}</ol>
-                    <form rw-submit="send" class="composer">
-                        <label class="sr-only" for="chat-message">Message</label>
-                        <input id="chat-message" name="message" maxlength="500" autocomplete="off" placeholder="Message the room…" required autofocus>
-                        <button type="submit">Send</button>
-                    </form>
-                </section>
-                <aside class="presence" aria-label="People in the room" data-rw-state="presence">${this.presence}</aside>
-            </div>
-        `;
-    }
-}
-
-export function createChatroomPage() {
-    const room = new ChatRoom();
-
-    @page('/', { css: 'chatroom.css' })
-    class ChatroomPage {
-        chat = new ChatroomComponent(room);
-
-        render() {
-            return html`<main>${this.chat}</main>`;
-        }
-    }
-
-    return ChatroomPage;
-}
-
-if (require.main === module) start(createChatroomPage(), { port: 8080 });