playsocketjs 3.1.2 → 4.1.0

package/src/server/ws-extensions.d.ts

@@ -0,0 +1,13 @@
+// Custom properties that PlaySocketServer attaches to ws WebSocket instances,
+// added to the ws module's own WebSocket type via declaration merging
+import "ws";
+
+declare module "ws" {
+    interface WebSocket {
+        uuid: string;
+        isAlive: boolean;
+        clientId?: string;
+        isTerminating?: boolean;
+        willfulDisconnect?: boolean;
+    }
+}

package/src/universal/constants.js

@@ -0,0 +1,7 @@
+/**
+ * Heartbeat ping interval in milliseconds
+ * Also used as the minimum age for CRDT garbage collection - operations are
+ * retained for at least one heartbeat cycle to ensure even slow clients can never 
+ * be desynced as a result of gc
+ */
+export const HEARTBEAT_INTERVAL = 5000;

package/src/universal/crdtManager.js

@@ -0,0 +1,498 @@
+import { HEARTBEAT_INTERVAL } from "./constants.js";
+
+const CONSOLE_PREFIX = "PlaySocket CRDT manager: ";
+
+/** @typedef {"set" | "number-increment" | "array-add" | "array-add-unique" | "array-remove-matching" | "array-update-matching" | "object-set-key" | "object-remove-key"} PropertyUpdateType */
+
+/** @typedef {[string, number][]} VectorClockEntries */
+
+/**
+ * @typedef {object} OperationData
+ * @property {PropertyUpdateType} type - Operation type
+ * @property {*} value - Value
+ * @property {*} [secondValue] - Second value (needed for some operations)
+ */
+
+/**
+ * @typedef {object} Operation
+ * @property {OperationData} data - Operation data
+ * @property {VectorClockEntries} vectorClock - Vector clock entries at creation time
+ * @property {string} source - ID of the replica that created the operation
+ * @property {string} uuid - Unique operation ID
+ */
+
+/**
+ * @typedef {object} PropertyUpdate
+ * @property {string} key - Storage key
+ * @property {Operation} operation - New operation
+ * @property {VectorClockEntries} vectorClock - Vector clock entries of the replica
+ */
+
+/**
+ * @typedef {object} CRDTState
+ * @property {[string, Operation[]][]} keyOperations - Operations per storage key
+ * @property {VectorClockEntries} vectorClock - Vector clock entries
+ */
+
+/**
+ * CRDT Manager
+ * Custom conflict-free replicated data type system with vector clocks
+ */
+export default class CRDTManager {
+    // Storage
+    /** @type {string} */
+    #replicaId;
+    /** @type {Map<string, Operation[]>} */
+    #keyOperations = new Map();
+    /** @type {Map<string, number>} */
+    #vectorClock = new Map();
+
+    /** @type {Record<string, any>} */
+    #propertyStore = {}; // Current local values as key/value store object
+    /** @type {Record<string, any>} */
+    #lastPropertyStore = {}; // Last property store to compare against
+
+    // Local Garbage Collection
+    #lastGCCheck = 0;
+    /** @type {Map<string, number>} */
+    #opUuidTimestamp = new Map(); // Map every operation to a timestamp for garbage collection
+
+    // Debug
+    #debug = false;
+
+    /**
+     * Create a new instance
+     * @param {boolean} [debug=false] - Enable debug logging
+     */
+    constructor(debug) {
+        if (debug) this.#debug = true;
+        this.#replicaId = crypto.randomUUID();
+        this.#vectorClock.set(this.#replicaId, 0);
+    }
+
+    /**
+     * Import the entire state of the CRDT manager (this overwrites the old state)
+     * @param {CRDTState} state - Full state of the CRDT manager
+     */
+    importState(state) {
+        try {
+            const { keyOperations, vectorClock } = state;
+            if (this.#debug) console.log(CONSOLE_PREFIX + "Importing state:", state);
+
+            // Resets
+            this.#opUuidTimestamp.clear();
+            this.#propertyStore = {};
+            this.#lastPropertyStore = {};
+
+            this.#keyOperations = new Map(keyOperations); // Rebuild the operations map
+            this.#vectorClock = new Map(vectorClock); // Rebuild the vector clock map
+            if (!this.#vectorClock.has(this.#replicaId)) this.#vectorClock.set(this.#replicaId, 0); // Add own vector clock if it wasn't present in the imported state
+
+            // Map all operation uuids to current timestamp
+            this.#keyOperations.forEach((value, _key) => {
+                value.forEach((operation) => {
+                    this.#opUuidTimestamp.set(operation.uuid, Date.now());
+                })
+            });
+
+            // Process each key to update local values
+            for (const key of this.#keyOperations.keys()) this.#processLocalProperty(key);
+
+        } catch (error) {
+            console.error(CONSOLE_PREFIX + "Failed to import state:", error);
+        }
+    }
+
+    /**
+     * Import property update
+     * @param {PropertyUpdate} update - Property update
+     */
+    importPropertyUpdate(update) {
+        try {
+            const { key, operation: rawOperation, vectorClock } = update;
+            const operation = /** @type {Operation} */ (this.#sanitizeValue(rawOperation));
+            if (this.#debug) console.log(CONSOLE_PREFIX + "Importing update:", update); // Debug
+
+            // Check key limit to safeguard against too many keys
+            if (this.#keyOperations.size >= 100 && !this.#keyOperations.has(key)) throw new Error("Key limit exceeded!");
+
+            // Get COPY of current ops (or empty array if none yet)
+            const currentOps = [...(this.#keyOperations.get(key) || [])];
+            // Merge vector clocks (always take max value)
+            for (const [id, counter] of vectorClock) {
+                if (!this.#vectorClock.has(id) || this.#vectorClock.get(id) < counter) {
+                    this.#vectorClock.set(id, counter);
+                }
+            }
+
+            // Safeguard against massive vector clocks
+            if (this.#vectorClock.size > 1000) this.#vectorClock = new Map([...this.#vectorClock].slice(-100));
+
+            // Add new operation if it's not already added
+            const existingUuids = new Set(currentOps.map(op => op.uuid));
+            if (operation.uuid && !existingUuids.has(operation.uuid)) {
+                currentOps.push({ ...operation }); // Add operation
+                this.#opUuidTimestamp.set(operation.uuid, Date.now()); // Add timestamp for gc
+            }
+
+            // Sort, update operations & local value
+            this.#keyOperations.set(key, this.#sortByVectorClock(currentOps));
+            this.#processLocalProperty(key);
+            this.#checkGarbageCollection();
+
+        } catch (error) {
+            console.error(CONSOLE_PREFIX + "Failed to import property update:", error);
+        }
+    }
+
+    /**
+     * Revert a local property update by removing the operation and recomputing the affected key
+     * Should NOT be used on the server or for synced ops, only for reverting local optimistic updates
+     * @param {PropertyUpdate} update - Property update
+     */
+    revertPropertyUpdate(update) {
+        try {
+            const key = update.key;
+            const opUuid = update.operation.uuid;
+
+            const currentOps = this.#keyOperations.get(key);
+            if (!currentOps?.some(op => op.uuid === opUuid)) return; // Operation not found
+            if (this.#debug) console.log(CONSOLE_PREFIX + `Removing operation ${opUuid} for key ${key} as part of property update reversion.`);
+
+            // The own vector clock entry isn't decremented because later ops may already embed the incremented counter
+            // and reusing a counter value would corrupt operation ordering (while a gap is harmless)
+            const remainingOps = currentOps.filter(op => op.uuid !== opUuid);
+            this.#opUuidTimestamp.delete(opUuid);
+
+            if (remainingOps.length) this.#keyOperations.set(key, remainingOps);
+            else this.#keyOperations.delete(key); // This was the only operation for this key, remove key
+            this.#processLocalProperty(key);
+
+        } catch (error) {
+            console.error(CONSOLE_PREFIX + "Failed to revert property update:", error);
+        }
+    }
+
+    /**
+     * Update a property
+     * @param {string} key - Storage key
+     * @param {PropertyUpdateType} type - Operation type
+     * @param {*} value - Value
+     * @param {*} [secondValue] - Second value (needed for some operations)
+     * @returns {PropertyUpdate | undefined} - Returns the property update
+     */
+    updateProperty(key, type, value, secondValue) {
+        try {
+            // Sanitize inputs
+            value = this.#sanitizeValue(value);
+            secondValue = this.#sanitizeValue(secondValue);
+
+            // Debug log
+            if (this.#debug) console.log(CONSOLE_PREFIX + `Updating property with key ${key}, type ${type}, value ${value} and secondValue ${secondValue}.`);
+
+            // Increment vector clock
+            const counter = this.#vectorClock.get(this.#replicaId) || 0;
+            this.#vectorClock.set(this.#replicaId, counter + 1);
+
+            // Assign shallow copy of current ops or fall back to empty array
+            const currentOps = [...(this.#keyOperations.get(key) || [])];
+
+            // Add operation
+            const newOp = this.#createOperation({ type, value, secondValue }, Array.from(this.#vectorClock.entries()));
+            currentOps.push(newOp);
+            this.#keyOperations.set(key, currentOps); // Update the operations (no need to sort via vector clock since local updates are always the latest)
+            this.#processLocalProperty(key); // Process local value
+            this.#checkGarbageCollection();
+
+            // Return the property update with the new operation (this can be imported using importPropertyUpdate)
+            return {
+                key,
+                operation: { ...newOp },
+                vectorClock: Array.from(this.#vectorClock.entries())
+            };
+
+        } catch (error) {
+            console.error(CONSOLE_PREFIX + `Failed to add operation for key ${key}:`, error);
+        }
+    }
+
+    /**
+     * Check if garbage collected can be performed & run it
+     */
+    #checkGarbageCollection() {
+        const MIN_GC_DELAY = 1000; // Minimum 1s delay between garbage collection runs
+
+        try {
+            if (Date.now() - this.#lastGCCheck < MIN_GC_DELAY) return;
+            this.#lastGCCheck = Date.now()
+
+            for (const [key, operations] of this.#keyOperations.entries()) {
+                if (operations?.length < 5) continue; // Min op amount per key for garbage collection to run (otherwise not worth it)
+
+                let retainCount = operations.length;
+                operations.forEach((op, index) => {
+                    // Count how many ops, from last to latest, are older than the min-age in a row
+                    if (op.uuid && this.#opUuidTimestamp.has(op.uuid) && (Date.now() - this.#opUuidTimestamp.get(op.uuid)) > HEARTBEAT_INTERVAL) {
+                        const removeCount = index + 1;
+                        retainCount = operations.length - removeCount;
+                        this.#opUuidTimestamp.delete(op.uuid); // Remove from timestamps if set to be deleted
+                    }
+                });
+
+                if (retainCount < operations.length) {
+                    if (this.#debug) console.log(CONSOLE_PREFIX + `Running garbage collection for key ${key} with current operations:`, operations);
+                    const retainOps = operations.slice(-retainCount); // Newest ops
+                    const removeOps = operations.slice(0, -retainCount); // Oldest ops (start =  idx 0, end = retainCount counted from right side)
+                    const baselineVectorClock = removeOps[removeOps.length - 1]?.vectorClock || []; // Use the vector clock from the last operation that we remove/overwrite
+
+                    // Calculate the value at the point where retained operations start
+                    let baselineValue = null;
+                    for (const op of removeOps) {
+                        if (!op.data) continue;
+                        baselineValue = this.#handleOperation(
+                            baselineValue,
+                            op.data.type,
+                            op.data.value,
+                            op.data.secondValue
+                        );
+                    }
+
+                    // Create a compact operation with baseline value and appropriate vector clock
+                    const compactOp = this.#createOperation({ type: "set", value: baselineValue }, baselineVectorClock);
+
+                    // Debug log
+                    if (this.#debug) console.log(CONSOLE_PREFIX + "Operations after garbage collection for this key:", [compactOp, ...retainOps]);
+
+                    // Combine compact op with retained operations
+                    this.#keyOperations.set(key, [compactOp, ...retainOps]);
+                }
+            }
+        } catch (error) {
+            console.error(CONSOLE_PREFIX + "Error running garbage collection:", error);
+        }
+    }
+
+    /**
+     * Create an operation object
+     * @param {OperationData} data - Operation data, consists of type, value and secondValue
+     * @param {VectorClockEntries} vectorClock - Vector clock of the replica/client
+     * @returns {Operation} - Operation object
+     */
+    #createOperation(data, vectorClock) {
+        const newOperation = {
+            data,
+            vectorClock,
+            source: this.#replicaId,
+            uuid: crypto.randomUUID()
+        }
+        this.#opUuidTimestamp.set(newOperation.uuid, Date.now());
+        return newOperation;
+    }
+
+    /**
+     * Process a property's value by applying all operations and set it in the property store
+     * @param {string} key - Storage key
+     */
+    #processLocalProperty(key) {
+        try {
+            const ops = this.#keyOperations.get(key);
+            if (!ops?.length) {
+                delete this.#propertyStore[key]; // Delete empty key
+                return;
+            }
+
+            // Apply all operations in order
+            let value = null;
+
+            for (const op of ops) {
+                if (!op.data) continue;
+                value = this.#handleOperation(
+                    value,
+                    op.data.type,
+                    op.data.value,
+                    op.data.secondValue
+                );
+            }
+
+            this.#propertyStore[key] = value; // Save locally
+        } catch (error) {
+            console.error(CONSOLE_PREFIX + `Failed to process property for key ${key}:`, error);
+        }
+    }
+
+    /**
+     * Sort operations by vector clock (causal order)
+     * @param {Operation[]} operations - Full operations that include vector clocks, data and a source
+     * @returns {Operation[]} - Sorted operations
+     */
+    #sortByVectorClock(operations) {
+        return [...operations].sort((a, b) => {
+            const clockA = new Map(a.vectorClock || []);
+            const clockB = new Map(b.vectorClock || []);
+
+            // First sort by causal relationship
+            let aGreater = false, bGreater = false;
+
+            const allIds = new Set([...clockA.keys(), ...clockB.keys()]);
+            for (const id of allIds) {
+                const countA = clockA.get(id) || 0;
+                const countB = clockB.get(id) || 0;
+
+                if (countA > countB) aGreater = true;
+                if (countA < countB) bGreater = true;
+            }
+
+            // Determine causal relationship (if one is greater, and the other is smaller, it's clear)
+            if (aGreater && !bGreater) return 1;     // a happens after b
+            if (!aGreater && bGreater) return -1;    // a happens before b
+
+            // Concurrent (unclear): Compare highest counter in each (sort by which one is ahead)
+            const maxA = Math.max(...Array.from(clockA.values()), 0);
+            const maxB = Math.max(...Array.from(clockB.values()), 0);
+            if (maxA !== maxB) return maxA - maxB;
+
+            // Final tiebreak: Sort by ID of Replica that actually generated the operation
+            return a.source.localeCompare(b.source);
+        });
+    }
+
+    /**
+     * Handle an operation
+     * @param {*} curValue - Current value of the storage key
+     * @param {PropertyUpdateType} type - Operation type
+     * @param {*} value - Value
+     * @param {*} [secondValue] - Second value (needed for some operations)
+     * @returns {*} - Value after the operation
+     */
+    #handleOperation(curValue, type, value, secondValue) {
+        try {
+            // Deep copy to avoid reference issues in case value is or contains object(s)
+            curValue = structuredClone(curValue);
+
+            // Set operation
+            if (type === "set") return value;
+
+            // Number increment operation
+            if (type === "number-increment") {
+                if (!Number.isFinite(curValue)) curValue = 0; // Auto-convert to number if current value isn't a finite number
+                if (Number.isFinite(value)) curValue += value; // Negative values are allowed, increment can be used for decrementing (non-finite values are ignored)
+            }
+
+            // Array operations
+            if (type.startsWith("array")) {
+                if (!Array.isArray(curValue)) curValue = []; // Auto-convert to array if current value isn't one
+
+                // Comparison function
+                const isObject = typeof value === "object" && value !== null;
+                /** @param {*} item */
+                const compare = (item) => {
+                    if (isObject && typeof item === "object" && item !== null) return JSON.stringify(item) === JSON.stringify(value); // Deep comparison
+                    return item === value; // Value comparison
+                };
+
+                switch (type) {
+                    case "array-add":
+                        curValue.push(value);
+                        break;
+                    case "array-add-unique":
+                        if (!curValue.some(compare)) curValue.push(value);
+                        break;
+                    case "array-remove-matching":
+                        curValue = curValue.filter((/** @type {*} */ item) => !compare(item));
+                        break;
+                    case "array-update-matching": {
+                        const index = curValue.findIndex(compare);
+                        if (index !== -1) curValue[index] = secondValue;
+                        break;
+                    }
+                }
+            }
+
+            // Object operations
+            if (type.startsWith("object")) {
+                if (typeof curValue !== "object" || curValue === null || Array.isArray(curValue)) curValue = {}; // Auto-convert to object if current value isn't one
+
+                switch (type) {
+                    case "object-set-key":
+                        if (value !== "__proto__") curValue[value] = secondValue; // Assigning __proto__ is not allowed as it would break things
+                        break;
+                    case "object-remove-key":
+                        delete curValue[value];
+                        break;
+                }
+            }
+
+            return curValue;
+
+        } catch (error) {
+            console.error(CONSOLE_PREFIX + `Failed to handle operation with curValue ${curValue}:`, error);
+            return curValue;
+        }
+    }
+
+    /**
+     * Remove HTML to prevent XSS and enforce size limits
+     * @param {*} value - Value to sanitize
+     * @returns {*} - Sanitized value
+     */
+    #sanitizeValue(value) {
+        // Check total serialized size
+        const jsonString = JSON.stringify(value);
+        if (jsonString?.length > 50000) throw new Error("Value too large!"); // 50KB limit
+
+        if (typeof value === "string") return (value.includes("<") || value.includes(">")) ? value.replace(/[<>]/g, "") : value;
+        if (Array.isArray(value)) return value.map(item => this.#sanitizeValue(item));
+        if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, this.#sanitizeValue(v)]));
+        return value;
+    }
+
+    /**
+     * Get property store
+     * @returns {Record<string, any>} - Object with key value pairs
+     */
+    get propertyStore() {
+        try {
+            return structuredClone(this.#propertyStore); // Return deep clone
+        } catch {
+            console.error(CONSOLE_PREFIX + "Failed to parse property store")
+            return {}
+        }
+    }
+
+    /**
+     * Check for changes in the local property store
+     * @returns {boolean} - Check if any values changed going from the last to the current property update
+     */
+    get didPropertiesChange() {
+        try {
+            if (JSON.stringify(this.#propertyStore) !== JSON.stringify(this.#lastPropertyStore)) {
+                this.#lastPropertyStore = structuredClone(this.#propertyStore);
+                return true;
+            }
+        } catch {
+            console.error(CONSOLE_PREFIX + "Failed to stringify and compare property stores")
+        }
+        return false;
+    }
+
+    /**
+     * Export state (can be imported using importState, converts the maps to arrays for serialization)
+     * @returns {CRDTState} - State
+     */
+    get state() {
+        return {
+            keyOperations: [...this.#keyOperations.entries()],
+            vectorClock: [...this.#vectorClock.entries()]
+        };
+    }
+}
+
+/**
+ * Get the operation details from a property update
+ * @param {PropertyUpdate} update - Property update
+ * @returns {{key: string | undefined, type: PropertyUpdateType | undefined, value: *, secondValue: *}} - Operation details
+ */
+export function getUpdateDetails(update) {
+    const data = update?.operation?.data;
+    return { key: update?.key, type: data?.type, value: data?.value, secondValue: data?.secondValue };
+}

package/types/client/client.d.ts

@@ -0,0 +1,97 @@
+export type PropertyUpdateType = import("../universal/crdtManager.js").PropertyUpdateType;
+export type PlaySocketOptions = {
+    /**
+     * - WebSocket server endpoint (e.g. 'wss://example.com/socket')
+     */
+    endpoint: string;
+    /**
+     * - Custom registration data
+     */
+    customData?: object;
+    /**
+     * - Enable debug logging
+     */
+    debug?: boolean;
+};
+export type ServerMessage = {
+    /**
+     * - Message type
+     */
+    type: string;
+};
+export type PendingPromise = {
+    resolve: (value?: any) => void;
+    reject: (reason?: any) => void;
+};
+/** @typedef {import("../universal/crdtManager.js").PropertyUpdateType} PropertyUpdateType */
+/**
+ * @typedef {object} PlaySocketOptions
+ * @property {string} endpoint - WebSocket server endpoint (e.g. 'wss://example.com/socket')
+ * @property {object} [customData] - Custom registration data
+ * @property {boolean} [debug=false] - Enable debug logging
+ */
+/**
+ * @typedef {object} ServerMessage
+ * @property {string} type - Message type
+ */
+/** @typedef {{ resolve: (value?: any) => void, reject: (reason?: any) => void }} PendingPromise */
+/**
+ * PlaySocket Client
+ */
+export default class PlaySocket {
+    #private;
+    /**
+     * Create a new PlaySocket instance
+     * @param {string} [id] - Unique identifier for this client (assigned by the server if omitted)
+     * @param {PlaySocketOptions} options - Connection options
+     */
+    constructor(id?: string, options?: PlaySocketOptions);
+    /**
+     * Register an event callback
+     * @param {string} event - Event name
+     * @param {Function} callback - Callback function
+     * @returns {Function} - Unsubscribe
+     */
+    onEvent(event: string, callback: Function): Function;
+    /**
+     * Initialize the PlaySocket instance by connecting to the WS server
+     * @returns {Promise<string>} Resolves with the client ID when the connection is established
+     */
+    init(): Promise<string>;
+    /**
+     * Create a new room and become host
+     * @param {object} [initialStorage] - Initial state
+     * @param {number} [size] - Max number of participants
+     * @returns {Promise<string>} Resolves with room ID
+     */
+    createRoom(initialStorage?: object, size?: number): Promise<string>;
+    /**
+     * Join an existing room
+     * @param {string} roomId - ID of the room
+     * @returns {Promise<void>} - Resolves when connected
+     */
+    joinRoom(roomId: string): Promise<void>;
+    /**
+     * Update a value in the shared storage
+     * @param {string} key - Storage key
+     * @param {PropertyUpdateType} type - Operation type
+     * @param {*} value - Value
+     * @param {*} [secondValue] - Second value (needed for some operations)
+     */
+    updateStorage(key: string, type: PropertyUpdateType, value: any, secondValue?: any): void;
+    /**
+     * Send a custom request to the server
+     * @param {string} name - Name of the request
+     * @param {*} [data] - Custom data
+     * @returns {Promise<void>} - Request promise
+     */
+    sendRequest(name: string, data?: any): Promise<void>;
+    /**
+     * Destroy the PlaySocket instance and disconnect
+     */
+    destroy(): void;
+    get participantCount(): number;
+    get storage(): Record<string, any>;
+    get isHost(): boolean;
+    get id(): string;
+}