sonic-ws 1.2.2 → 1.3.0

package/dist/index.d.ts

@@ -2,5 +2,6 @@ export { SonicWS } from './ws/client/node/ClientNode';
 export { SonicWSConnection } from './ws/server/SonicWSConnection';
 export { SonicWSServer } from './ws/server/SonicWSServer';
 export { PacketType } from './ws/packets/PacketType';
+export { BasicMiddleware, ConnectionMiddleware, ServerMiddleware, BCInfo } from './ws/PacketProcessor';
 export { CreatePacket, CreateObjPacket, CreateEnumPacket, FlattenData, UnFlattenData } from './ws/util/packets/PacketUtils';
 export { DefineEnum, WrapEnum } from './ws/util/enums/EnumHandler';

package/dist/version.d.ts

@@ -1,5 +1,5 @@
 /** Current protocol version */
-export declare const VERSION = 17;
+export declare const VERSION = 19;
 /** Server data suffix */
 export declare const SERVER_SUFFIX = "SWS";
 /** Server data suffix in array */

package/dist/version.js

@@ -18,7 +18,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SERVER_SUFFIX_NUMS = exports.SERVER_SUFFIX = exports.VERSION = void 0;
 const StringUtil_1 = require("./ws/util/StringUtil");
 /** Current protocol version */
-exports.VERSION = 17;
+exports.VERSION = 19;
 /** Server data suffix */
 exports.SERVER_SUFFIX = "SWS";
 /** Server data suffix in array */

package/dist/ws/Connection.d.ts

@@ -1,15 +1,8 @@
-export interface BasicMiddleware {
-    init?(conn: Connection): void;
-    onReceive_pre(tag: string, data: Uint8Array): boolean | void;
-    onSend_pre(tag: string, values: any[]): boolean | void;
-    onReceive_post(tag: string, values: any[]): boolean | void;
-    onSend_post(tag: string, data: Uint8Array): boolean | void;
-    onStatusChange(status: number): void;
-}
+import { ConnectionMiddleware, MiddlewareHolder } from "./PacketProcessor";
 /**
  * Holds shared connection values. Lets helper functions work on client and server.
  */
-export interface Connection {
+export interface Connection extends MiddlewareHolder<ConnectionMiddleware> {
     /**
      * List of timers.
      * For internal use only.
@@ -50,8 +43,16 @@ export interface Connection {
      * Closes the connection
      */
     close(code?: number, reason?: string): void;
-    /**
-     * Adds a basic middleware which can interact with packets
-     */
-    addBasicMiddleware(middleware: BasicMiddleware): void;
 }
+export declare enum CloseCodes {
+    RATELIMIT = 4000,
+    SMALL = 4001,
+    INVALID_KEY = 4002,
+    INVALID_PACKET = 4003,
+    INVALID_DATA = 4004,
+    REPEATED_HANDSHAKE = 4005,
+    DISABLED_PACKET = 4006,
+    MIDDLEWARE = 4007,
+    MANUAL_SHUTDOWN = 4008
+}
+export declare function getClosureCause(id: number): string;

package/dist/ws/Connection.js

@@ -15,4 +15,36 @@
  * limitations under the License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-;
+exports.CloseCodes = void 0;
+exports.getClosureCause = getClosureCause;
+var CloseCodes;
+(function (CloseCodes) {
+    CloseCodes[CloseCodes["RATELIMIT"] = 4000] = "RATELIMIT";
+    CloseCodes[CloseCodes["SMALL"] = 4001] = "SMALL";
+    CloseCodes[CloseCodes["INVALID_KEY"] = 4002] = "INVALID_KEY";
+    CloseCodes[CloseCodes["INVALID_PACKET"] = 4003] = "INVALID_PACKET";
+    CloseCodes[CloseCodes["INVALID_DATA"] = 4004] = "INVALID_DATA";
+    CloseCodes[CloseCodes["REPEATED_HANDSHAKE"] = 4005] = "REPEATED_HANDSHAKE";
+    CloseCodes[CloseCodes["DISABLED_PACKET"] = 4006] = "DISABLED_PACKET";
+    CloseCodes[CloseCodes["MIDDLEWARE"] = 4007] = "MIDDLEWARE";
+    CloseCodes[CloseCodes["MANUAL_SHUTDOWN"] = 4008] = "MANUAL_SHUTDOWN";
+})(CloseCodes || (exports.CloseCodes = CloseCodes = {}));
+function getClosureCause(id) {
+    if (id >= 4000) {
+        return CloseCodes[id] ?? 'UNKNOWN';
+    }
+    switch (id) {
+        case 1000:
+            return 'NORMAL_CLOSURE';
+        case 1001:
+            return 'GOING_AWAY';
+        case 1002:
+            return 'PROTOCOL_ERROR';
+        case 1003:
+            return 'UNSUPPORTED_DATA';
+        case 1006:
+            return 'ABNORMAL_CLOSURE';
+        default:
+            return 'UNKNOWN';
+    }
+}

package/dist/ws/PacketProcessor.d.ts

@@ -0,0 +1,124 @@
+import { Connection } from "./Connection";
+import { SonicWSConnection } from "./server/SonicWSConnection";
+/**
+ * A basic middleware interface; extended by other middleware types
+ */
+export interface BasicMiddleware {
+    /**
+     * Called when the middleware is initialized
+     * @param conn The connection instance
+     */
+    init?(conn: Connection): void;
+}
+export type FuncKeys<T> = {
+    [K in keyof T]: NonNullable<T[K]> extends (...args: any[]) => any ? K : never;
+}[keyof T];
+export interface MiddlewareHolder<T extends BasicMiddleware> {
+    /**
+     * Adds middleware which can interact with packets and other events
+     */
+    addMiddleware(middleware: T): void;
+    /**
+     * Calls a middleware method on all middlewares
+     * @param method The method to call
+     * @param values The values to pass to the method
+     */
+    callMiddleware<K extends FuncKeys<T> & keyof T>(method: K, ...values: Parameters<NonNullable<Extract<T[K], (...args: any[]) => any>>>): Promise<boolean>;
+}
+/**
+ * A connection middleware interface, used in SonicWSConnection and ClientCore
+ */
+export interface ConnectionMiddleware extends BasicMiddleware {
+    /**
+     * Called before a packet is received
+     * @param tag The packet tag
+     * @param data The raw packet data
+     * @param recvSize The size of the received packet
+     * @returns `true` to cancel processing, `false` or nothing to continue
+     */
+    onReceive_pre?(tag: string, data: Uint8Array, recvSize: number): boolean | void;
+    /**
+     * Called before a packet is sent
+     * @param tag The packet tag
+     * @param values The packet values
+     * @param processedAt The time the packet was processed at; Date.now()
+     * @param perfTime The performance time the packet was processed at; performance.now()
+     * @returns `true` to cancel processing, `false` or nothing to continue
+     */
+    onSend_pre?(tag: string, values: any[], processedAt: number, perfTime: number): boolean | void;
+    /**
+     * Called after a packet is received and listeners have been processed
+     * @param tag The packet tag
+     * @param values The packet values
+     */
+    onReceive_post?(tag: string, values: any[]): void;
+    /**
+     * Called after a packet is sent
+     * @param tag The packet tag
+     * @param data The raw packet data
+     * @param sendSize The size of the sent packet
+     */
+    onSend_post?(tag: string, data: Uint8Array, sendSize: number): void;
+    /**
+     * Called when the connection status changes
+     * @param status The new connection status
+     */
+    onStatusChange?(status: number): void;
+    /**
+     * Called when the name of the connection changes; server-side only
+     * @param name The new name of the connection
+     * @returns `true` to cancel setting the name, `false` or nothing to continue
+     */
+    onNameChange?(name: string): boolean | void;
+}
+/**
+ * Different types of broadcast information
+ */
+export type BCInfo = {
+    recipients: SonicWSConnection[];
+} & ({
+    type: "all";
+} | {
+    type: "tagged";
+    tag: string;
+} | {
+    type: "filter";
+    filter: (connection: SonicWSConnection) => boolean;
+});
+/**
+ * Server-sided middleware, used in SonicWSServer for a more broad range of events
+ * This does not include information for packets sent and received, as that is handled by ConnectionMiddleware
+ */
+export interface ServerMiddleware extends BasicMiddleware {
+    /**
+     * Called when a client connects
+     * @param connection The connection instance
+     */
+    onClientConnect?(connection: SonicWSConnection): boolean | void;
+    /**
+     * Called when a client disconnects
+     * @param connection The connection instance
+     * @param code The disconnect code
+     * @param reason The disconnect reason
+     */
+    onClientDisconnect?(connection: SonicWSConnection, code: number, reason?: Buffer<ArrayBufferLike>): void;
+    /**
+     * Called when a packet is broadcasted
+     * @param tag The packet tag
+     * @param info The broadcast information
+     * @param values The packet values
+     */
+    onPacketBroadcast_pre?(tag: string, info: BCInfo, ...values: any[]): boolean | void;
+    /**
+     * Called when a packet is processed after being broadcasted
+     * @param tag The packet tag
+     * @param info The broadcast information
+     * @param values The packet values
+     */
+    onPacketBroadcast_post?(tag: string, info: BCInfo, data: Uint8Array, sendSize: number): boolean | void;
+}
+export type ServerPQ = [tag: string, value: Uint8Array];
+export type ClientPQ = Uint8Array;
+export type PacketQueue<T> = (T | null)[];
+export type AsyncPQ<T> = [boolean, PacketQueue<T>];
+export type SendQueue = [boolean, [Function, string, any[]][], string?];

package/dist/ws/PacketProcessor.js

@@ -0,0 +1,19 @@
+"use strict";
+/*
+ * Copyright 2026 Lily (liwybloc)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+;
+;

package/dist/ws/client/core/ClientCore.d.ts

@@ -1,5 +1,6 @@
 import { PacketHolder } from '../../util/packets/PacketHolder';
-import { BasicMiddleware, Connection } from '../../Connection';
+import { Connection } from '../../Connection';
+import { AsyncPQ, ConnectionMiddleware, ClientPQ, PacketQueue, FuncKeys } from '../../PacketProcessor';
 export declare abstract class SonicWSCore implements Connection {
     /** Raw 'ws' library connection / webjs WebSocket class */
     socket: WebSocket;
@@ -24,7 +25,6 @@ export declare abstract class SonicWSCore implements Connection {
     _timers: Record<number, [number, (closed: boolean) => void, boolean]>;
     private asyncData;
     private asyncMap;
-    private _state;
     constructor(ws: WebSocket, bufferHandler: (val: MessageEvent) => Promise<Uint8Array>);
     private reading;
     private readQueue;
@@ -32,12 +32,14 @@ export declare abstract class SonicWSCore implements Connection {
     private invalidPacket;
     private listenLock;
     private packetQueue;
-    listenPacket(data: string | [any[], boolean], code: number): Promise<void>;
+    listenPacket(data: string | [any[], boolean], code: number, packetQueue: PacketQueue<ClientPQ>, isAsync: boolean, asyncData: AsyncPQ<ClientPQ>): Promise<void>;
     private isAsync;
     private enqueuePacket;
-    private basicMiddlewares;
-    addBasicMiddleware(middleware: BasicMiddleware): void;
-    private callMiddleware;
+    private triggerNextPacket;
+    private middlewares;
+    addMiddleware(middleware: ConnectionMiddleware): void;
+    callMiddleware<K extends FuncKeys<ConnectionMiddleware> & keyof ConnectionMiddleware>(method: K, ...values: Parameters<NonNullable<Extract<ConnectionMiddleware[K], (...args: any[]) => any>>>): Promise<boolean>;
+    private dataHandler;
     private messageHandler;
     protected listen(key: string, listener: (data: any[]) => void): void;
     /**
@@ -50,6 +52,7 @@ export declare abstract class SonicWSCore implements Connection {
      * @param listener Callback for when data is received
      */
     raw_onsend(listener: (data: Uint8Array) => void): void;
+    private sendQueue;
     /**
      * Sends a packet to the server
      * @param tag The tag of the packet

package/dist/ws/client/core/ClientCore.js

@@ -38,7 +38,6 @@ class SonicWSCore {
     _timers = {};
     asyncData = {};
     asyncMap = {};
-    _state = WebSocket.OPEN;
     constructor(ws, bufferHandler) {
         this.socket = ws;
         this.listeners = {
@@ -62,6 +61,12 @@ class SonicWSCore {
                 if (shouldCall)
                     callback(true);
             }
+            for (const packet of this.clientPackets.getPackets()) {
+                delete packet.lastSent[0];
+            }
+            for (const packet of this.serverPackets.getPackets()) {
+                delete packet.lastReceived[0];
+            }
         });
         this.bufferHandler = bufferHandler;
     }
@@ -118,54 +123,34 @@ class SonicWSCore {
     }
     listenLock = false;
     packetQueue = [];
-    async listenPacket(data, code) {
-        if (await this.callMiddleware('onReceive_post', this.serverPackets.getTag(code), typeof data == 'string' ? [data] : data[0]))
-            return;
+    async listenPacket(data, code, packetQueue, isAsync, asyncData) {
+        const tag = this.serverPackets.getTag(code);
         const listeners = this.listeners.event[code];
         if (!listeners)
-            return console.warn("Warn: No listener for packet " + code);
-        this.enqueuePacket(data, code, listeners);
+            return console.warn("Warn: No listener for packet " + tag);
+        await this.enqueuePacket(data, listeners, packetQueue, isAsync, asyncData);
+        await this.callMiddleware('onReceive_post', tag, typeof data == 'string' ? [data] : data[0]);
     }
     isAsync(code) {
         return this.asyncMap[code];
     }
-    async enqueuePacket(data, code, listeners) {
-        const isAsync = this.isAsync(code);
-        let locked;
-        let packetQueue;
-        let asyncData;
-        if (isAsync) {
-            asyncData = this.asyncData[code];
-            locked = asyncData[0];
-            packetQueue = asyncData[1];
-        }
-        else {
-            locked = this.listenLock;
-            packetQueue = this.packetQueue;
-        }
-        if (locked) {
-            packetQueue.push(data);
-            return;
-        }
-        if (isAsync)
-            asyncData[0] = true;
-        else
-            this.listenLock = true;
-        let currentData = data;
-        while (true) {
-            await (0, PacketUtils_1.listenPacket)(currentData, listeners, this.invalidPacket);
-            if (packetQueue.length === 0)
-                break;
-            currentData = packetQueue.shift();
-        }
+    async enqueuePacket(data, listeners, packetQueue, isAsync, asyncData) {
+        await (0, PacketUtils_1.listenPacket)(data, listeners, this.invalidPacket);
+        await this.triggerNextPacket(packetQueue, isAsync, asyncData);
+    }
+    async triggerNextPacket(packetQueue, isAsync, asyncData) {
         if (isAsync)
             asyncData[0] = false;
         else
             this.listenLock = false;
+        if (packetQueue.length > 0) {
+            this.dataHandler(packetQueue.shift());
+            return;
+        }
     }
-    basicMiddlewares = [];
-    addBasicMiddleware(middleware) {
-        this.basicMiddlewares.push(middleware);
+    middlewares = [];
+    addMiddleware(middleware) {
+        this.middlewares.push(middleware);
         const m = middleware;
         try {
             if (typeof m.init === 'function')
@@ -177,7 +162,7 @@ class SonicWSCore {
     }
     async callMiddleware(method, ...values) {
         let cancelled = false;
-        for (const middleware of this.basicMiddlewares) {
+        for (const middleware of this.middlewares) {
             const fn = middleware[method];
             if (!fn)
                 continue;
@@ -192,31 +177,55 @@ class SonicWSCore {
         }
         return cancelled;
     }
-    async messageHandler(event) {
-        const data = await this.bufferHandler(event);
-        this.listeners.message.forEach(listener => listener(data));
-        if (data.length < 1)
-            return;
+    async dataHandler(data) {
         const key = data[0];
         const value = data.slice(1);
+        const isAsync = this.isAsync(key);
+        let locked;
+        let packetQueue;
+        let asyncData;
+        if (isAsync) {
+            asyncData = this.asyncData[key];
+            locked = asyncData[0];
+            packetQueue = asyncData[1];
+        }
+        else {
+            locked = this.listenLock;
+            packetQueue = this.packetQueue;
+        }
+        if (locked) {
+            packetQueue.push(data);
+            return;
+        }
+        if (isAsync)
+            asyncData[0] = true;
+        else
+            this.listenLock = true;
         const packet = this.serverPackets.getPacket(this.serverPackets.getTag(key));
-        if (await this.callMiddleware('onReceive_pre', packet.tag, data))
+        if (await this.callMiddleware('onReceive_pre', packet.tag, data, data.length))
             return;
         if (packet.rereference && value.length == 0) {
             if (packet.lastReceived[0] === undefined)
                 return this.invalidPacket("No previous value to rereference");
-            this.listenPacket(packet.lastReceived[0], key);
+            this.listenPacket(packet.lastReceived[0], key, packetQueue, isAsync, asyncData);
             return;
         }
         if (packet.dataBatching == 0) {
             const res = packet.lastReceived[0] = await packet.listen(value, null);
-            this.listenPacket(res, key);
+            this.listenPacket(res, key, packetQueue, isAsync, asyncData);
             return;
         }
         const batchData = await BatchHelper_1.BatchHelper.unravelBatch(packet, value, null);
         if (typeof batchData == 'string')
             return this.invalidPacket(batchData);
-        batchData.forEach(data => this.listenPacket(data, key));
+        batchData.forEach(data => this.listenPacket(data, key, packetQueue, isAsync, asyncData));
+    }
+    async messageHandler(event) {
+        const data = await this.bufferHandler(event);
+        this.listeners.message.forEach(listener => listener(data));
+        if (data.length < 1)
+            return;
+        await this.dataHandler(data);
     }
     listen(key, listener) {
         const skey = this.serverPackets.getKey(key);
@@ -242,21 +251,21 @@ class SonicWSCore {
     raw_onsend(listener) {
         this.listeners.send.push(listener);
     }
+    sendQueue = [false, [], undefined];
     /**
      * Sends a packet to the server
      * @param tag The tag of the packet
      * @param values The values to send
      */
     async send(tag, ...values) {
-        if (await this.callMiddleware('onSend_pre', tag, values))
-            return;
-        const [code, data, packet] = await (0, PacketUtils_1.processPacket)(this.clientPackets, tag, values, 0);
-        if (await this.callMiddleware('onSend_post', tag, data))
+        if (await this.callMiddleware('onSend_pre', tag, values, Date.now(), performance.now()))
             return;
+        const [code, data, packet] = await (0, PacketUtils_1.processPacket)(this.clientPackets, tag, values, this.sendQueue, 0);
         if (packet.dataBatching == 0)
             this.raw_send((0, BufferUtil_1.toPacketBuffer)(code, data));
         else
             this.batcher.batchPacket(code, data);
+        await this.callMiddleware('onSend_post', tag, data, data.length);
     }
     /**
      * Listens for when the client connects

package/dist/ws/packets/Packets.d.ts

@@ -31,7 +31,7 @@ export declare class Packet<T extends (PacketType | readonly PacketType[])> {
     validate: (data: Uint8Array) => Promise<[Uint8Array, boolean]>;
     customValidator: ((socket: SonicWSConnection, ...values: any[]) => boolean) | null;
     lastReceived: Record<number, any>;
-    lastSent: Record<number, any>;
+    lastSent: Record<number, number | bigint>;
     constructor(tag: string, schema: PacketSchema<T>, customValidator: ValidatorFunction, enabled: boolean, client: boolean);
     listen(value: Uint8Array, socket: SonicWSConnection | null): Promise<[processed: any, flatten: boolean] | string>;
     serialize(): number[];

package/dist/ws/server/SonicWSConnection.d.ts

@@ -1,13 +1,15 @@
 import * as WS from 'ws';
 import { SonicWSServer } from './SonicWSServer';
 import { Packet } from '../packets/Packets';
-import { BasicMiddleware, Connection } from '../Connection';
+import { Connection } from '../Connection';
+import { ConnectionMiddleware, FuncKeys } from '../PacketProcessor';
 export declare class SonicWSConnection implements Connection {
     /** Raw 'ws' library socket */
     socket: WS.WebSocket;
     private host;
     private listeners;
     private print;
+    private name;
     private handshakePacket;
     private handshakeLambda;
     private messageLambda;
@@ -23,7 +25,6 @@ export declare class SonicWSConnection implements Connection {
     private asyncMap;
     private asyncData;
     private closed;
-    private _state;
     constructor(socket: WS.WebSocket, host: SonicWSServer, id: number, handshakePacket: string | null, clientRateLimit: number, serverRateLimit: number);
     private parseData;
     private handshakeHandler;
@@ -33,9 +34,9 @@ export declare class SonicWSConnection implements Connection {
     private packetQueue;
     private listenPacket;
     private messageHandler;
-    private basicMiddlewares;
-    addBasicMiddleware(middleware: BasicMiddleware): void;
-    private callMiddleware;
+    private middlewares;
+    addMiddleware(middleware: ConnectionMiddleware): void;
+    callMiddleware<K extends FuncKeys<ConnectionMiddleware> & keyof ConnectionMiddleware>(method: K, ...values: Parameters<NonNullable<Extract<ConnectionMiddleware[K], (...args: any[]) => any>>>): Promise<boolean>;
     /**
      * Enables a packet for the client.
      * @param tag The tag of the packet
@@ -66,6 +67,7 @@ export declare class SonicWSConnection implements Connection {
      * For internal use.
      */
     send_processed(code: number, data: Uint8Array, packet: Packet<any>): void;
+    private sendQueue;
     /**
      * Sends a packet with the tag and values
      * @param tag The tag to send
@@ -100,4 +102,12 @@ export declare class SonicWSConnection implements Connection {
      * @param replace If it should replace a previous tag; defaults to true. If using false, you can add multiple tags.
      */
     tag(tag: string, replace?: boolean): void;
+    /**
+     * Sets the name of this connection for the debug menu; good for setting e.g. usernames on games
+     */
+    setName(name: string): Promise<void>;
+    /**
+     * @returns Name of the socket, defaults to Socket [ID] unless set with setName()
+     */
+    getName(): string;
 }