@aethervtt/shard-net-websocket 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Dias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @aethervtt/shard-net-websocket
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import type { NetTransport } from '@aethervtt/shard-net';
+import { type SocketLike } from './socket.js';
+export interface WebSocketTransportOptions {
+    /** Defaults to 1 MiB. Larger reliable messages are split by the net core. */
+    maxMessage?: number;
+    /** The WebSocket class. Defaults to the global one (browsers, Node 22+). */
+    WebSocket?: new (url: string) => SocketLike;
+}
+/**
+ * Connects to a Shard server over WebSocket (0086). Every message is reliable underneath, so
+ * `caps.unreliable` is false. Servers use `webSocketServer` from `@aethervtt/shard-net-websocket/server`.
+ */
+export declare function webSocketTransport(options?: WebSocketTransportOptions): NetTransport;
+export { SocketConnection, type SocketLike } from './socket.js';

package/dist/index.js

@@ -0,0 +1,25 @@
+import { ShardError } from "@aethervtt/shard-core";
+import { openSocket, SocketConnection } from "./socket.js";
+function webSocketTransport(options = {}) {
+  const maxMessage = options.maxMessage ?? 1 << 20;
+  const Socket = options.WebSocket ?? globalThis.WebSocket;
+  return {
+    name: "websocket",
+    caps: { unreliable: false, maxMessage },
+    async connect(address) {
+      if (!Socket) {
+        throw new ShardError("net/no-websocket", "This runtime has no global WebSocket", {
+          hint: "Pass one: webSocketTransport({ WebSocket })."
+        });
+      }
+      const socket = new Socket(address);
+      await openSocket(socket, address);
+      return new SocketConnection(socket, 0, maxMessage);
+    }
+  };
+}
+import { SocketConnection as SocketConnection2 } from "./socket.js";
+export {
+  SocketConnection2 as SocketConnection,
+  webSocketTransport
+};

package/dist/server.d.ts

@@ -0,0 +1,17 @@
+import type { NetListener, NetTransport } from '@aethervtt/shard-net';
+export interface WebSocketServerOptions {
+    /** 0 picks a free port: read it from the listener's `port`. */
+    port?: number;
+    host?: string;
+    maxMessage?: number;
+}
+export interface WebSocketListener extends NetListener {
+    readonly port: number;
+}
+/**
+ * A Node WebSocket server for Shard (0086), through `ws`. It also connects out like
+ * `webSocketTransport`, so one transport serves both roles in tests.
+ */
+export declare function webSocketServer(options?: WebSocketServerOptions): NetTransport & {
+    listen(): Promise<WebSocketListener>;
+};

package/dist/server.js

@@ -0,0 +1,51 @@
+import { WebSocketServer } from "ws";
+import { webSocketTransport } from "./index.js";
+import { SocketConnection } from "./socket.js";
+function webSocketServer(options = {}) {
+  const maxMessage = options.maxMessage ?? 1 << 20;
+  const client = webSocketTransport({ maxMessage });
+  return {
+    name: "websocket",
+    caps: client.caps,
+    connect: client.connect,
+    async listen() {
+      const server = new WebSocketServer({
+        port: options.port ?? 0,
+        host: options.host ?? "127.0.0.1",
+        maxPayload: maxMessage + 1
+      });
+      await new Promise((resolve, reject) => {
+        server.once("listening", resolve);
+        server.once("error", reject);
+      });
+      const fns = [];
+      let nextPeer = 1;
+      server.on("connection", (socket) => {
+        const connection = new SocketConnection(
+          socket,
+          nextPeer++,
+          maxMessage
+        );
+        for (const fn of fns) fn(connection);
+      });
+      const address = server.address();
+      return {
+        port: typeof address === "object" && address ? address.port : 0,
+        onConnection(fn) {
+          fns.push(fn);
+          return () => {
+            const i = fns.indexOf(fn);
+            if (i !== -1) fns.splice(i, 1);
+          };
+        },
+        close: () => new Promise((resolve) => {
+          for (const socket of server.clients) socket.terminate();
+          server.close(() => resolve());
+        })
+      };
+    }
+  };
+}
+export {
+  webSocketServer
+};

package/dist/socket.d.ts

@@ -0,0 +1,40 @@
+import { ShardError } from '@aethervtt/shard-core';
+import type { Channel, ConnectionStats, NetConnection, PeerId } from '@aethervtt/shard-net';
+/** What both a browser `WebSocket` and a `ws` socket offer. */
+export interface SocketLike {
+    readonly readyState: number;
+    binaryType: string;
+    send(data: Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: 'message', fn: (event: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: 'close', fn: (event: {
+        code: number;
+        reason: string;
+    }) => void): void;
+    addEventListener(type: 'error', fn: (event: unknown) => void): void;
+}
+/**
+ * One WebSocket as a net connection. Each frame starts with a channel byte; both channels are
+ * reliable underneath (`caps.unreliable` is false).
+ */
+export declare class SocketConnection implements NetConnection {
+    readonly peer: PeerId;
+    private readonly socket;
+    private readonly maxMessage;
+    private readonly messageFns;
+    private readonly closeFns;
+    private readonly counters;
+    private closed;
+    private closing;
+    constructor(socket: SocketLike, peer: PeerId, maxMessage: number);
+    send(channel: Channel, bytes: Uint8Array): void;
+    onMessage(fn: (channel: Channel, bytes: Uint8Array) => void): () => void;
+    onClose(fn: (reason: ShardError | undefined) => void): () => void;
+    close(reason?: string): void;
+    private shut;
+    stats(): ConnectionStats;
+}
+/** Opens a socket and resolves once it's open. */
+export declare function openSocket(socket: SocketLike, address: string): Promise<void>;

package/dist/socket.js

@@ -0,0 +1,103 @@
+import { ShardError } from "@aethervtt/shard-core";
+const OPEN = 1;
+const CHANNELS = ["reliable", "unreliable"];
+class SocketConnection {
+  peer;
+  socket;
+  maxMessage;
+  messageFns = [];
+  closeFns = [];
+  counters = { rtt: 0, sentBytes: 0, receivedBytes: 0, lost: 0 };
+  closed = false;
+  closing = false;
+  constructor(socket, peer, maxMessage) {
+    this.socket = socket;
+    this.peer = peer;
+    this.maxMessage = maxMessage;
+    socket.binaryType = "arraybuffer";
+    socket.addEventListener("message", (event) => {
+      const data = event.data;
+      const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : ArrayBuffer.isView(data) ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength) : void 0;
+      if (!bytes || bytes.length < 1) return;
+      this.counters.receivedBytes += bytes.length;
+      const channel = CHANNELS[bytes[0]] ?? "reliable";
+      const body = bytes.subarray(1);
+      for (const fn of this.messageFns) fn(channel, body);
+    });
+    socket.addEventListener("close", (event) => {
+      this.shut(
+        this.closing ? void 0 : new ShardError(
+          "net/transport-closed",
+          event.reason || `WebSocket closed (${event.code})`
+        )
+      );
+    });
+  }
+  send(channel, bytes) {
+    if (this.closed || this.socket.readyState !== OPEN) return;
+    if (bytes.length > this.maxMessage) {
+      throw new ShardError(
+        "net/message-too-large",
+        `A ${bytes.length}-byte message is over ${this.maxMessage} bytes`,
+        {
+          hint: "Reliable messages are split automatically; keep unreliable ones under maxMessage."
+        }
+      );
+    }
+    const frame = new Uint8Array(bytes.length + 1);
+    frame[0] = channel === "reliable" ? 0 : 1;
+    frame.set(bytes, 1);
+    this.counters.sentBytes += frame.length;
+    this.socket.send(frame);
+  }
+  onMessage(fn) {
+    this.messageFns.push(fn);
+    return () => remove(this.messageFns, fn);
+  }
+  onClose(fn) {
+    this.closeFns.push(fn);
+    return () => remove(this.closeFns, fn);
+  }
+  close(reason) {
+    if (this.closed) return;
+    this.closing = true;
+    this.socket.close(1e3, reason?.slice(0, 120));
+    this.shut(void 0);
+  }
+  shut(reason) {
+    if (this.closed) return;
+    this.closed = true;
+    for (const fn of [...this.closeFns]) fn(reason);
+  }
+  stats() {
+    return { ...this.counters };
+  }
+}
+function remove(list, item) {
+  const i = list.indexOf(item);
+  if (i !== -1) list.splice(i, 1);
+}
+function openSocket(socket, address) {
+  return new Promise((resolve, reject) => {
+    if (socket.readyState === OPEN) return resolve();
+    let settled = false;
+    const open = socket;
+    open.addEventListener("open", () => {
+      settled = true;
+      resolve();
+    });
+    socket.addEventListener("error", () => {
+      if (settled) return;
+      settled = true;
+      reject(
+        new ShardError("net/connect-failed", `Couldn't open a WebSocket to ${address}`, {
+          hint: "Check the server is listening and the URL (ws:// or wss://) is right."
+        })
+      );
+    });
+  });
+}
+export {
+  SocketConnection,
+  openSocket
+};

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@aethervtt/shard-net-websocket",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@aethervtt/shard-core": "0.3.0",
+    "@aethervtt/shard-net": "0.3.0",
+    "ws": "^8.21.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aethervtt/shard.git",
+    "directory": "packages/net-websocket"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "shard": {
+    "buildSha": "7c8c46fee30f86eff262af53b9249bdae6ce4927"
+  }
+}