redweb 0.8.0 → 0.9.0

package/src/ws/DistributionBridge.js

@@ -0,0 +1,271 @@
+const { randomUUID } = require('crypto');
+const { performance } = require('perf_hooks');
+const { throwCleanupErrors } = require('../serverLifecycle');
+
+class DistributionBridge {
+    constructor(options, onEvent, logger = console, clock = () => performance.now()) {
+        if (!options || typeof options !== 'object' || Array.isArray(options)) {
+            throw new TypeError('`distribution` must be an object.');
+        }
+        const {
+            adapter,
+            channel,
+            nodeId = randomUUID(),
+            maxEventBytes = 64 * 1024,
+            maxSeenEvents = 10_000,
+            seenTtlMs = 60_000,
+            lifecycleTimeoutMs = 5000,
+            publishTimeoutMs = lifecycleTimeoutMs,
+            maxConcurrentPublishes = 64,
+            maxConcurrentEvents = 64,
+            required = false,
+        } = options;
+        if (!adapter || typeof adapter !== 'object') throw new TypeError('`distribution.adapter` is required.');
+        ['publish', 'subscribe'].forEach(method => {
+            if (typeof adapter[method] !== 'function') throw new TypeError(`\`distribution.adapter.${method}\` must be a function.`);
+        });
+        ['start', 'unsubscribe', 'close'].forEach(method => {
+            if (adapter[method] !== undefined && typeof adapter[method] !== 'function') {
+                throw new TypeError(`\`distribution.adapter.${method}\` must be a function.`);
+            }
+        });
+        if (typeof channel !== 'string' || !channel) throw new TypeError('`distribution.channel` must be a non-empty string.');
+        if (typeof nodeId !== 'string' || !nodeId || nodeId.length > 256) {
+            throw new TypeError('`distribution.nodeId` must be a non-empty string of at most 256 characters.');
+        }
+        const integers = {
+            maxEventBytes,
+            maxSeenEvents,
+            seenTtlMs,
+            lifecycleTimeoutMs,
+            publishTimeoutMs,
+            maxConcurrentPublishes,
+            maxConcurrentEvents,
+        };
+        for (const [name, value] of Object.entries(integers)) {
+            if (!Number.isInteger(value) || value < 1) throw new TypeError(`\`distribution.${name}\` must be a positive integer.`);
+        }
+        if (typeof required !== 'boolean') throw new TypeError('`distribution.required` must be a boolean.');
+        if (typeof onEvent !== 'function') throw new TypeError('`distribution.onEvent` must be a function.');
+        if (typeof clock !== 'function') throw new TypeError('`clock` must be a function.');
+        Object.assign(this, {
+            adapter,
+            channel,
+            nodeId,
+            maxEventBytes,
+            maxSeenEvents,
+            seenTtlMs,
+            lifecycleTimeoutMs,
+            publishTimeoutMs,
+            maxConcurrentPublishes,
+            maxConcurrentEvents,
+            required,
+            onEvent,
+            logger,
+            clock,
+        });
+        this.seen = new Map();
+        this.publishes = new Set();
+        this.events = new Set();
+        this.closed = false;
+        this.healthy = false;
+        this.subscribed = false;
+        this.ready = this.start();
+    }
+
+    async start() {
+        try {
+            await this.withTimeout(
+                signal => this.adapter.start?.(signal),
+                this.lifecycleTimeoutMs,
+                'start',
+                () => this.adapter.close?.()
+            );
+            if (this.closed) return false;
+            const unsubscribe = await this.withTimeout(
+                signal => this.adapter.subscribe(this.channel, event => this.receive(event), signal),
+                this.lifecycleTimeoutMs,
+                'subscribe',
+                lateUnsubscribe => typeof lateUnsubscribe === 'function'
+                    ? lateUnsubscribe()
+                    : this.adapter.unsubscribe?.(this.channel)
+            );
+            if (typeof unsubscribe === 'function') this.unsubscribe = unsubscribe;
+            this.subscribed = true;
+            this.healthy = true;
+            return true;
+        } catch (error) {
+            this.logger?.error?.('Distribution adapter failed to start:', error);
+            return false;
+        }
+    }
+
+    withTimeout(operation, timeoutMs, name, compensateLate) {
+        let timer;
+        let timedOut = false;
+        const controller = new AbortController();
+        const task = Promise.resolve().then(() => operation(controller.signal));
+        void task.then(value => {
+            if (!timedOut || !compensateLate) return;
+            Promise.resolve()
+                .then(() => compensateLate(value))
+                .catch(error => this.logger?.error?.(`Late distribution ${name} cleanup failed:`, error));
+        }, error => {
+            if (timedOut) this.logger?.error?.(`Distribution adapter ${name} failed after timeout:`, error);
+        });
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                timedOut = true;
+                controller.abort();
+                reject(new Error(`Distribution adapter ${name} timed out.`));
+            }, timeoutMs);
+            timer.unref();
+        });
+        return Promise.race([task, timeout]).finally(() => clearTimeout(timer));
+    }
+
+    isReady() {
+        return this.healthy && !this.closed;
+    }
+
+    publish(type, payload) {
+        if (this.closed || typeof type !== 'string' || !type || this.publishes.size >= this.maxConcurrentPublishes) {
+            return Promise.resolve(false);
+        }
+        const event = { id: randomUUID(), source: this.nodeId, type, payload };
+        const serialized = this.serialize(event);
+        if (!serialized) return Promise.resolve(false);
+        const task = this.performPublish(serialized);
+        this.track(this.publishes, task);
+        return task;
+    }
+
+    async performPublish(serialized) {
+        if (!await this.ready || this.closed) return false;
+        try {
+            await this.withTimeout(
+                signal => this.adapter.publish(this.channel, serialized, signal),
+                this.publishTimeoutMs,
+                'publish'
+            );
+            this.healthy = true;
+            return true;
+        } catch (error) {
+            this.healthy = false;
+            this.logger?.error?.('Distribution publish failed:', error);
+            return false;
+        }
+    }
+
+    track(collection, task) {
+        collection.add(task);
+        const cleanup = () => collection.delete(task);
+        void task.then(cleanup, cleanup);
+    }
+
+    receive(input) {
+        if (this.closed || this.events.size >= this.maxConcurrentEvents) return false;
+        let event;
+        try {
+            const serialized = typeof input === 'string' ? input : JSON.stringify(input);
+            if (Buffer.byteLength(serialized) > this.maxEventBytes) return false;
+            event = typeof input === 'string' ? JSON.parse(input) : input;
+        } catch {
+            return false;
+        }
+        if (!this.isValid(event) || event.source === this.nodeId || this.hasSeen(event.id)) return false;
+        this.remember(event.id);
+        const task = Promise.resolve()
+            .then(() => this.onEvent(event))
+            .catch(error => this.logger?.error?.('Distribution event handler failed:', error));
+        this.track(this.events, task);
+        return true;
+    }
+
+    isValid(event) {
+        return Boolean(
+            event &&
+            typeof event === 'object' &&
+            typeof event.id === 'string' && event.id && event.id.length <= 256 &&
+            typeof event.source === 'string' && event.source && event.source.length <= 256 &&
+            typeof event.type === 'string' && event.type && event.type.length <= 256
+        );
+    }
+
+    serialize(event) {
+        try {
+            const serialized = JSON.stringify(event);
+            return Buffer.byteLength(serialized) <= this.maxEventBytes ? serialized : null;
+        } catch {
+            return null;
+        }
+    }
+
+    hasSeen(id) {
+        const expiry = this.seen.get(id);
+        if (expiry === undefined) return false;
+        if (expiry <= this.clock()) {
+            this.seen.delete(id);
+            return false;
+        }
+        return true;
+    }
+
+    evictExpired(now) {
+        while (this.seen.size) {
+            const [eventId, expiry] = this.seen.entries().next().value;
+            if (expiry > now) return;
+            this.seen.delete(eventId);
+        }
+    }
+
+    remember(id) {
+        const now = this.clock();
+        this.evictExpired(now);
+        while (this.seen.size >= this.maxSeenEvents) this.seen.delete(this.seen.keys().next().value);
+        this.seen.set(id, now + this.seenTtlMs);
+    }
+
+    async stopSubscription() {
+        if (!this.subscribed) return;
+        this.subscribed = false;
+        await this.withTimeout(
+            signal => this.unsubscribe ? this.unsubscribe() : this.adapter.unsubscribe?.(this.channel, signal),
+            this.lifecycleTimeoutMs,
+            'unsubscribe'
+        );
+    }
+
+    async drainActivity() {
+        await this.withTimeout(
+            () => Promise.allSettled([...this.publishes, ...this.events]),
+            this.lifecycleTimeoutMs,
+            'drain'
+        );
+    }
+
+    async close() {
+        if (this.closed) return;
+        this.closed = true;
+        this.healthy = false;
+        await this.ready;
+        const errors = [];
+        for (const operation of [
+            () => this.stopSubscription(),
+            () => this.drainActivity(),
+            () => this.withTimeout(signal => this.adapter.close?.(signal), this.lifecycleTimeoutMs, 'close'),
+        ]) {
+            try {
+                await operation();
+            } catch (error) {
+                errors.push(error);
+            }
+        }
+        this.seen.clear();
+        this.publishes.clear();
+        this.events.clear();
+        throwCleanupErrors(errors, 'One or more distribution adapter cleanup operations failed.');
+    }
+}
+
+module.exports = DistributionBridge;

package/src/ws/FixedStepService.js

@@ -0,0 +1,74 @@
+const { performance } = require('perf_hooks');
+const SocketService = require('./SocketService');
+
+class FixedStepService extends SocketService {
+    constructor(name, tickRateMs, maxCatchUpTicks = 5, maxRetainedLagMs = tickRateMs * maxCatchUpTicks) {
+        super(name, tickRateMs);
+        if (!Number.isInteger(tickRateMs) || tickRateMs < 1) {
+            throw new TypeError('`tickRateMs` must be a positive integer.');
+        }
+        if (!Number.isInteger(maxCatchUpTicks) || maxCatchUpTicks < 1) {
+            throw new TypeError('`maxCatchUpTicks` must be a positive integer.');
+        }
+        if (!Number.isInteger(maxRetainedLagMs) || maxRetainedLagMs < tickRateMs) {
+            throw new TypeError('`maxRetainedLagMs` must be an integer greater than or equal to `tickRateMs`.');
+        }
+        this.maxCatchUpTicks = maxCatchUpTicks;
+        this.maxRetainedLagMs = maxRetainedLagMs;
+        this.tick = 0;
+        this.accumulatorMs = 0;
+        this._runningPromise = null;
+    }
+
+    now() {
+        return performance.now();
+    }
+
+    onInit(route) {
+        this.route = route;
+        this.lastTime = this.now();
+        this._tickHandle = setInterval(() => this.pulse(), this.tickRateMs);
+        this._tickHandle.unref?.();
+    }
+
+    pulse() {
+        if (this._runningPromise) return this._runningPromise;
+        const now = this.now();
+        const accumulated = this.accumulatorMs + Math.max(0, now - this.lastTime);
+        const droppedLagMs = Math.max(0, accumulated - this.maxRetainedLagMs);
+        this.accumulatorMs = Math.min(accumulated, this.maxRetainedLagMs);
+        this.lastTime = now;
+        if (droppedLagMs) {
+            this.route?.metrics?.observe('redweb.fixed_step.lag_dropped', droppedLagMs);
+            try {
+                this.onLagDropped?.(droppedLagMs);
+            } catch (error) {
+                this.route?.logger?.error?.('Fixed-step lag hook failed:', error);
+            }
+        }
+        const due = Math.min(this.maxCatchUpTicks, Math.floor(this.accumulatorMs / this.tickRateMs));
+        if (!due) return Promise.resolve();
+        this.accumulatorMs -= due * this.tickRateMs;
+        this._runningPromise = this.runTicks(due).finally(() => { this._runningPromise = null; });
+        return this._runningPromise;
+    }
+
+    async runTicks(count) {
+        for (let index = 0; index < count; index += 1) {
+            this.tick += 1;
+            try {
+                await this.onTick?.(this.tickRateMs, this.tick);
+            } catch (error) {
+                this.route?.logger?.error?.('Fixed-step service tick failed:', error);
+            }
+        }
+    }
+
+    async onShutdown() {
+        if (this._tickHandle) clearInterval(this._tickHandle);
+        this._tickHandle = null;
+        await this._runningPromise;
+    }
+}
+
+module.exports = FixedStepService;

package/src/ws/HeartbeatMonitor.js

@@ -0,0 +1,75 @@
+const { performance } = require('perf_hooks');
+
+function acknowledgePong() {
+    const state = this.__redwebHeartbeatState;
+    if (state) state.awaitingPong = false;
+}
+
+class HeartbeatMonitor {
+    constructor({ intervalMs, timeoutMs }, logger = console, clock = () => performance.now()) {
+        if (!Number.isInteger(intervalMs) || intervalMs < 1) {
+            throw new TypeError('`heartbeat.intervalMs` must be a positive integer.');
+        }
+        if (!Number.isInteger(timeoutMs) || timeoutMs < 1) {
+            throw new TypeError('`heartbeat.timeoutMs` must be a positive integer.');
+        }
+        if (typeof clock !== 'function') throw new TypeError('`clock` must be a function.');
+        this.intervalMs = intervalMs;
+        this.timeoutMs = timeoutMs;
+        this.logger = logger;
+        this.clock = clock;
+        this.sockets = new Map();
+        this.timer = setInterval(() => this.tick(), Math.min(intervalMs, timeoutMs));
+        this.timer.unref();
+    }
+
+    attach(socket) {
+        this.detach(socket);
+        const state = { awaitingPong: false, lastPing: null };
+        socket.__redwebHeartbeatState = state;
+        this.sockets.set(socket, state);
+        socket.on('pong', acknowledgePong);
+    }
+
+    detach(socket) {
+        const state = this.sockets.get(socket);
+        if (!state) return false;
+        socket.off?.('pong', acknowledgePong);
+        delete socket.__redwebHeartbeatState;
+        this.sockets.delete(socket);
+        return true;
+    }
+
+    tick() {
+        const now = this.clock();
+        this.sockets.forEach((state, socket) => {
+            if (state.awaitingPong && now - state.lastPing >= this.timeoutMs) {
+                this.detach(socket);
+                try {
+                    socket.terminate?.();
+                } catch (error) {
+                    this.logger?.error?.('Error terminating unresponsive socket:', error);
+                }
+                return;
+            }
+            if (!state.awaitingPong && (state.lastPing === null || now - state.lastPing >= this.intervalMs)) {
+                state.lastPing = now;
+                state.awaitingPong = true;
+                try {
+                    socket.ping?.();
+                } catch (error) {
+                    this.logger?.error?.('Error pinging socket:', error);
+                }
+            }
+        });
+    }
+
+    stop() {
+        if (!this.timer) return;
+        clearInterval(this.timer);
+        this.timer = null;
+        [...this.sockets.keys()].forEach(socket => this.detach(socket));
+    }
+}
+
+module.exports = HeartbeatMonitor;

package/src/ws/Metrics.js

@@ -0,0 +1,34 @@
+class Metrics {
+    constructor(sink, routePath, logger = console) {
+        if (!sink || typeof sink !== 'object' || Array.isArray(sink)) {
+            throw new TypeError('`metrics` must be an object.');
+        }
+        ['increment', 'gauge', 'observe'].forEach(method => {
+            if (sink[method] !== undefined && typeof sink[method] !== 'function') {
+                throw new TypeError(`\`metrics.${method}\` must be a function.`);
+            }
+        });
+        if (!['increment', 'gauge', 'observe'].some(method => typeof sink[method] === 'function')) {
+            throw new TypeError('`metrics` requires at least one metric method.');
+        }
+        this.sink = sink;
+        this.attributes = Object.freeze({ route: routePath });
+        this.logger = logger;
+    }
+
+    emit(method, name, value = 1) {
+        if (typeof this.sink[method] !== 'function') return;
+        try {
+            Promise.resolve(this.sink[method](name, value, this.attributes))
+                .catch(error => this.logger?.error?.('Metrics sink failed:', error));
+        } catch (error) {
+            this.logger?.error?.('Metrics sink failed:', error);
+        }
+    }
+
+    increment(name, value) { this.emit('increment', name, value); }
+    gauge(name, value) { this.emit('gauge', name, value); }
+    observe(name, value) { this.emit('observe', name, value); }
+}
+
+module.exports = Metrics;

package/src/ws/ProtocolPolicy.js

@@ -0,0 +1,130 @@
+const { Buffer } = require('buffer');
+const schema = require('./protocol-schema.json');
+const { validateEnvelope } = require('./protocol-validation');
+
+const PROTOCOL_CONTEXT = Symbol('redweb.protocolContext');
+const PROTOCOL_REJECTION = Symbol('redweb.protocolRejection');
+
+const ERROR_CODES = Object.freeze(Object.fromEntries(schema.errorCodes.map(code => [code, code])));
+
+function nonEmptyBoundedString(value, name, maxLength = 64) {
+    if (typeof value !== 'string' || !value || value.length > maxLength) {
+        throw new TypeError(`\`${name}\` must be a non-empty string of at most ${maxLength} characters.`);
+    }
+    return value;
+}
+
+class ProtocolPolicy {
+    constructor(options) {
+        if (!options || typeof options !== 'object' || Array.isArray(options)) {
+            throw new TypeError('`protocol` must be an object.');
+        }
+        const {
+            versions,
+            required = true,
+            queryParameter = 'redwebVersion',
+            header = 'x-redweb-version',
+            binary,
+        } = options;
+        if (!Array.isArray(versions) || versions.length === 0 || versions.length > 16) {
+            throw new TypeError('`protocol.versions` must contain between 1 and 16 versions.');
+        }
+        this.versions = versions.map(version => nonEmptyBoundedString(version, 'protocol version'));
+        if (new Set(this.versions).size !== this.versions.length) {
+            throw new TypeError('`protocol.versions` entries must be unique.');
+        }
+        if (typeof required !== 'boolean') throw new TypeError('`protocol.required` must be a boolean.');
+        this.queryParameter = nonEmptyBoundedString(queryParameter, 'protocol.queryParameter');
+        this.header = nonEmptyBoundedString(header, 'protocol.header').toLowerCase();
+        this.required = required;
+        this.binary = this.validateBinary(binary);
+    }
+
+    validateBinary(binary) {
+        if (binary === undefined || binary === false) return null;
+        if (!binary || typeof binary !== 'object' || Array.isArray(binary)) {
+            throw new TypeError('`protocol.binary` must be an object.');
+        }
+        if (typeof binary.encode !== 'function' || typeof binary.decode !== 'function') {
+            throw new TypeError('`protocol.binary` requires `encode` and `decode` functions.');
+        }
+        const maxBytes = binary.maxBytes ?? 64 * 1024;
+        if (!Number.isInteger(maxBytes) || maxBytes < 1) {
+            throw new TypeError('`protocol.binary.maxBytes` must be a positive integer.');
+        }
+        return { encode: binary.encode, decode: binary.decode, maxBytes };
+    }
+
+    negotiate(request) {
+        let requested;
+        try {
+            const host = request.headers?.host || 'localhost';
+            requested = new URL(request.url || '/', `http://${host}`).searchParams.get(this.queryParameter)
+                || request.headers?.[this.header];
+        } catch {
+            return this.reject(request, 'Malformed protocol negotiation request.');
+        }
+        if (Array.isArray(requested)) requested = requested[0];
+        const version = requested || (this.required ? null : this.versions[0]);
+        if (!version || !this.versions.includes(version)) {
+            return this.reject(request, 'A supported protocol version is required.');
+        }
+        request[PROTOCOL_CONTEXT] = Object.freeze({ version });
+        return true;
+    }
+
+    reject(request, message) {
+        request[PROTOCOL_REJECTION] = {
+            statusCode: 426,
+            statusText: 'Upgrade Required',
+            headers: { 'Redweb-Versions': this.versions.join(', ') },
+            message,
+        };
+        return false;
+    }
+
+    envelope(version, type, payload, metadata = {}) {
+        nonEmptyBoundedString(type, 'protocol event type', 256);
+        const envelope = { v: version, type, payload };
+        if (metadata.requestId !== undefined) {
+            envelope.requestId = nonEmptyBoundedString(metadata.requestId, 'protocol requestId', 256);
+        }
+        if (metadata.sequence !== undefined) {
+            if (!Number.isSafeInteger(metadata.sequence) || metadata.sequence < 0) {
+                throw new TypeError('`protocol sequence` must be a non-negative safe integer.');
+            }
+            envelope.sequence = metadata.sequence;
+        }
+        return envelope;
+    }
+
+    error(version, code, message, metadata = {}) {
+        nonEmptyBoundedString(code, 'protocol error code', 256);
+        nonEmptyBoundedString(message, 'protocol error message', 1024);
+        const envelope = this.envelope(version, 'error', undefined, metadata);
+        delete envelope.payload;
+        envelope.error = { code, message };
+        return envelope;
+    }
+
+    validateEnvelope(message, version) {
+        return validateEnvelope(message, version);
+    }
+
+    async decodeBinary(buffer, context) {
+        if (!this.binary || buffer.length > this.binary.maxBytes) return null;
+        return this.binary.decode(buffer, context);
+    }
+
+    async encodeBinary(value, context) {
+        if (!this.binary) return null;
+        const encoded = await this.binary.encode(value, context);
+        if (!(Buffer.isBuffer(encoded) || encoded instanceof Uint8Array || encoded instanceof ArrayBuffer)) {
+            throw new TypeError('`protocol.binary.encode` must return Buffer, Uint8Array, or ArrayBuffer.');
+        }
+        const buffer = Buffer.from(encoded);
+        return buffer.length <= this.binary.maxBytes ? buffer : null;
+    }
+}
+
+module.exports = { ProtocolPolicy, PROTOCOL_CONTEXT, PROTOCOL_REJECTION, ERROR_CODES };