@beespoke/micro-server-websocket-bun 0.0.0-stage → 2.0.5

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# @beespoke/micro-server-websocket-bun
 
-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.
+Bun-native WebSocket server, handler discovery, and application lifecycle integration. The WebSocket listener requires Bun 1.3.14+ and uses its own port, separate from core's HTTP server.
+
+## Install
+
+```sh
+bun add @beespoke/micro-server @beespoke/micro-server-websocket-bun
+```
+
+## Configure
+
+Save `micro-server.config.ts`:
+
+```ts
+import { defineConfig } from '@beespoke/micro-server';
+
+export default defineConfig({
+    plugins: ['@beespoke/micro-server-websocket-bun'],
+    pluginOptions: {
+        '@beespoke/micro-server-websocket-bun': {
+            port: 5001,
+            folder: './sockets',
+        },
+    },
+});
+```
+
+Create `sockets/echo.ts`:
+
+```ts
+import { BaseSocketHandler } from '@beespoke/micro-server-websocket-bun';
+import type { ServerWebSocket } from 'bun';
+
+export default class EchoSocket extends BaseSocketHandler {
+    async connect(_socket: ServerWebSocket<any>) {}
+    async disconnect(_socket: ServerWebSocket<any>, _code: number, _reason: string) {}
+
+    async accept(socket: ServerWebSocket<any>, message: string) {
+        socket.send(message);
+    }
+}
+```
+
+## Start the application
+
+Save the configuration as `micro-server.config.ts` next to your application's `package.json`, then create `index.ts`:
+
+```ts
+import { ApplicationServer } from '@beespoke/micro-server';
+
+await ApplicationServer.bootstrap();
+for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+    process.once(signal, () => {
+        void ApplicationServer.close().catch(error => {
+            console.error(error);
+            process.exitCode = 1;
+        });
+    });
+}
+```
+
+Run `bun index.ts` and connect a WebSocket client to `ws://localhost:5001/echo`. Install `@types/bun` as a development dependency when typechecking application handler files.
+
+## Options and handlers
+
+`port` defaults to 5001. `folder` defaults to `sockets`; `dir` can select the discovery root. Relative paths resolve from the app configuration directory. Discovered files default-export handler classes implementing `connect`, `accept`, and `disconnect`.
+
+For explicit registration, supply `handlers: [{ path: 'echo', handler: new EchoSocket() }]` instead of relying on files. Handler paths and effective channels must be unique. `BaseSocketHandler.channel` supports application channel selection; a default channel follows the registered path. `getInstance()` exposes the handler's active socket when available.
+
+This listener does not automatically inherit HTTP middleware or JWT route authentication from core. Applications own WebSocket upgrade/access policy. Plugin shutdown closes its listener and sockets. The root exports `WebSocketServer` as a named/default export, `BaseSocketHandler`, and WebSocket data/options types. Standalone applications own initialization and shutdown.
+
+## TypeScript
+
+```ts
+// plugin-types.d.ts
+import type {} from '@beespoke/micro-server-websocket-bun/plugin';
+```
+
+This import enables typed plugin options without importing the adapter at runtime. Application handler files also need Bun types. A Node application may import package metadata/types, but starting the native WebSocket server requires Bun.

package/dist/BaseSocketHandler.d.ts

@@ -0,0 +1,13 @@
+import type { Server, ServerWebSocket } from 'bun';
+import type { WebSocketData } from './BaseSocketType.js';
+export default class BaseSocketHandler {
+    static channel: string;
+    static server: Server<WebSocketData>;
+    static websocket: ServerWebSocket<any>;
+    upgrade(req: Request, server: Server<WebSocketData>): Promise<boolean | void>;
+    accept(ws: ServerWebSocket<any>, message: string): Promise<void>;
+    connect(ws: ServerWebSocket<any>): Promise<void>;
+    disconnect(ws: ServerWebSocket<any>, code: number, reason: string): Promise<void>;
+    getInstance(): ServerWebSocket<any>;
+    static parse(url: String): any;
+}

package/dist/BaseSocketType.d.ts

@@ -0,0 +1,5 @@
+export type WebSocketData = {
+    userId?: number;
+    channel?: string;
+    room?: string;
+};

package/dist/PluginContext.d.ts

@@ -0,0 +1,13 @@
+/** Structural subset of the core context; standalone clients need no HTTP dependency. */
+export interface Logger {
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+}
+export interface PluginContext {
+    readonly logger: Logger;
+    readonly configDir: string;
+    onStart(hook: () => void | Promise<void>): void;
+    onClose(hook: () => void | Promise<void>): void;
+}

package/dist/WebSocketServer.d.ts

@@ -0,0 +1,36 @@
+import type { ServerWebSocket } from 'bun';
+import type { PluginContext } from './PluginContext.js';
+import BaseSocketHandler from './BaseSocketHandler.js';
+export type SocketHandlerRegistration = {
+    path: string;
+    handler: BaseSocketHandler;
+};
+export interface WebSocketServerOptions {
+    port?: number;
+    /** Relative directories resolve against PluginContext.configDir during setup. */
+    dir?: string;
+    folder?: string;
+    /** Explicit handlers bypass directory discovery. */
+    handlers?: SocketHandlerRegistration[];
+}
+export default class WebSocketServer {
+    private readonly options;
+    readonly name = "websocket-bun";
+    static socketHandlers: SocketHandlerRegistration[];
+    private static server?;
+    private static initializing?;
+    private static closing?;
+    private static readonly pendingHooks;
+    private static hookErrors;
+    private static stopping;
+    private static runHook;
+    constructor(options?: WebSocketServerOptions);
+    setup(context: PluginContext): Promise<void>;
+    /** Await discovery before serving. The leading arguments match the existing API. */
+    static init(port?: number, dir?: string, folder?: string): Promise<SocketHandlerRegistration[]>;
+    private static start;
+    static getSocketHandlers(): SocketHandlerRegistration[];
+    static getHandler(path: string): ServerWebSocket<any> | null;
+    private static stopServer;
+    static close(): Promise<void>;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { default, default as WebSocketServer } from './WebSocketServer.js';
+export type { WebSocketServerOptions, SocketHandlerRegistration } from './WebSocketServer.js';
+export { default as BaseSocketHandler } from './BaseSocketHandler.js';
+export type { WebSocketData } from './BaseSocketType.js';

package/dist/index.js

@@ -0,0 +1,224 @@
+// src/WebSocketServer.ts
+import { readdir } from "node:fs/promises";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+function assertBun() {
+  if (typeof Bun === "undefined" || typeof Bun.serve !== "function") {
+    throw new Error("@beespoke/micro-server-websocket-bun requires the Bun runtime to initialize WebSockets");
+  }
+}
+
+class WebSocketServer {
+  options;
+  name = "websocket-bun";
+  static socketHandlers = [];
+  static server;
+  static initializing;
+  static closing;
+  static pendingHooks = new Set;
+  static hookErrors = [];
+  static stopping = false;
+  static runHook(hook) {
+    const task = Promise.resolve().then(hook).catch((error) => {
+      this.hookErrors.push(error);
+    }).finally(() => {
+      this.pendingHooks.delete(task);
+    });
+    this.pendingHooks.add(task);
+    return task;
+  }
+  constructor(options = {}) {
+    this.options = options;
+  }
+  async setup(context) {
+    assertBun();
+    await WebSocketServer.start(this.options.port ?? 5001, resolve(context.configDir, this.options.dir ?? "."), this.options.folder ?? "sockets", this.options.handlers, context.logger, (server) => context.onClose(() => WebSocketServer.server === server ? WebSocketServer.close() : undefined));
+  }
+  static async init(port = 5001, dir = process.cwd(), folder = "sockets") {
+    return this.start(port, dir, folder);
+  }
+  static async start(port, dir, folder, explicitHandlers, logger = console, onAcquire) {
+    assertBun();
+    if (this.server || this.initializing || this.closing)
+      throw new Error("A WebSocketServer is already active or changing state");
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+      throw new Error("WebSocket port must be an integer between 0 and 65535");
+    this.initializing = (async () => {
+      const handlers = [];
+      if (explicitHandlers) {
+        handlers.push(...explicitHandlers);
+      } else {
+        const fullDirectory = resolve(dir, folder);
+        const files = (await readdir(fullDirectory)).filter((file) => /\.(?:ts|mts|js|mjs)$/.test(file) && !/\.d\.(?:ts|mts)$/.test(file)).sort();
+        for (const file of files) {
+          const Handler = (await import(pathToFileURL(resolve(fullDirectory, file)).href)).default;
+          if (typeof Handler !== "function")
+            throw new Error(`Socket handler ${file} must default-export a class`);
+          handlers.push({ path: file.replace(/\.(?:ts|mts|js|mjs)$/, ""), handler: new Handler });
+        }
+      }
+      const channels = new Map;
+      const routes = new Set;
+      for (const record of handlers) {
+        record.path = record.path.replace(/^\/+|\/+$/g, "");
+        if (routes.has(record.path))
+          throw new Error(`Duplicate WebSocket handler path: ${record.path}`);
+        routes.add(record.path);
+        const Handler = record.handler.constructor;
+        const channel = Handler.channel === "default" ? record.path : Handler.channel;
+        if (channels.has(channel))
+          throw new Error(`Duplicate WebSocket channel: ${channel}`);
+        Handler.channel = channel;
+        channels.set(channel, record.handler);
+      }
+      let server;
+      server = Bun.serve({
+        port,
+        async fetch(req, server2) {
+          const pathname = new URL(req.url).pathname.replace(/^\/+|\/+$/g, "");
+          const record = handlers.find((record2) => record2.path === pathname);
+          if (!record)
+            return new Response("WebSocket handler not found", { status: 404 });
+          const upgraded = await record.handler.upgrade(req, server2);
+          if (upgraded === false)
+            return new Response("WebSocket upgrade failed", { status: 400 });
+          return;
+        },
+        websocket: {
+          message(ws, message) {
+            if (WebSocketServer.closing || WebSocketServer.stopping) {
+              ws.close(1001, "Server shutting down");
+              return;
+            }
+            const handler = channels.get(ws.data.channel ?? "");
+            if (handler)
+              return WebSocketServer.runHook(() => handler.accept(ws, typeof message === "string" ? message : message.toString()));
+          },
+          open(ws) {
+            if (WebSocketServer.closing || WebSocketServer.stopping) {
+              ws.close(1001, "Server shutting down");
+              return;
+            }
+            const handler = channels.get(ws.data.channel ?? "");
+            if (handler) {
+              handler.constructor.websocket = ws;
+              return WebSocketServer.runHook(() => handler.connect(ws));
+            }
+          },
+          close(ws, code, reason) {
+            const handler = channels.get(ws.data.channel ?? "");
+            if (!handler)
+              return;
+            return WebSocketServer.runHook(async () => {
+              try {
+                await handler.disconnect(ws, code, reason);
+              } finally {
+                const Handler = handler.constructor;
+                if (Handler.websocket === ws)
+                  Handler.websocket = undefined;
+              }
+            });
+          }
+        }
+      });
+      this.server = server;
+      this.socketHandlers = handlers;
+      try {
+        onAcquire?.(server);
+        for (const { handler } of handlers)
+          handler.constructor.server = server;
+        logger.info(`Web Socket Server ready at: http://127.0.0.1:${server.port}`);
+      } catch (error) {
+        await this.stopServer();
+        throw error;
+      }
+      return handlers;
+    })();
+    try {
+      return await this.initializing;
+    } finally {
+      this.initializing = undefined;
+    }
+  }
+  static getSocketHandlers() {
+    return this.socketHandlers;
+  }
+  static getHandler(path) {
+    return this.socketHandlers.find((socket) => socket.path === path)?.handler.getInstance() ?? null;
+  }
+  static async stopServer() {
+    const server = this.server;
+    this.stopping = true;
+    const errors = [];
+    try {
+      try {
+        if (server)
+          await server.stop(true);
+      } catch (error) {
+        errors.push(error);
+      }
+      while (this.pendingHooks.size)
+        await Promise.all([...this.pendingHooks]);
+      errors.push(...this.hookErrors.splice(0));
+      if (errors.length)
+        throw new AggregateError(errors, "Failed to close WebSocket server");
+    } finally {
+      for (const { handler } of this.socketHandlers) {
+        const Handler = handler.constructor;
+        Handler.server = undefined;
+        Handler.websocket = undefined;
+      }
+      this.socketHandlers = [];
+      this.server = undefined;
+      this.stopping = false;
+    }
+  }
+  static async close() {
+    if (this.closing)
+      return this.closing;
+    this.closing = (async () => {
+      try {
+        await this.initializing;
+      } catch {}
+      await this.stopServer();
+    })();
+    try {
+      await this.closing;
+    } finally {
+      this.closing = undefined;
+    }
+  }
+}
+// src/BaseSocketHandler.ts
+class BaseSocketHandler {
+  static channel = "default";
+  static server;
+  static websocket;
+  async upgrade(req, server) {
+    const Handler = this.constructor;
+    return server.upgrade(req, { data: { channel: Handler.channel } });
+  }
+  async accept(ws, message) {
+    throw new Error("accept(ws:ServerWebSocket<any>, message:string) - not yet implemented!");
+  }
+  async connect(ws) {
+    throw new Error("connect(ws:ServerWebSocket<any>) - not yet implemented!");
+  }
+  async disconnect(ws, code, reason) {
+    throw new Error("disconnect(ws:ServerWebSocket<any>, code:number, reason:string) - not yet implemented!");
+  }
+  getInstance() {
+    const Handler = this.constructor;
+    if (!Handler.websocket)
+      throw new Error("No active WebSocket for this handler");
+    return Handler.websocket;
+  }
+  static parse(url) {
+    return Object.fromEntries(new URL(String(url)).searchParams);
+  }
+}
+export {
+  WebSocketServer as default,
+  WebSocketServer,
+  BaseSocketHandler
+};

package/dist/plugin/index.d.ts

@@ -0,0 +1,10 @@
+import type { PluginDefinition } from '@beespoke/micro-server';
+import { type WebSocketServerOptions } from '../index.js';
+export type WebSocketPluginOptions = WebSocketServerOptions;
+declare module '@beespoke/micro-server' {
+    interface PluginOptionsRegistry {
+        '@beespoke/micro-server-websocket-bun': WebSocketPluginOptions;
+    }
+}
+declare const definition: PluginDefinition<WebSocketPluginOptions>;
+export default definition;

package/dist/plugin/index.js

@@ -0,0 +1,49 @@
+// src/plugin/index.ts
+import { WebSocketServer, BaseSocketHandler } from "../index.js";
+var definition = {
+  name: "@beespoke/micro-server-websocket-bun",
+  validate(options) {
+    if (!options || typeof options !== "object" || Array.isArray(options))
+      throw new Error("WebSocket options must be an object");
+    const values = options;
+    const keys = ["port", "dir", "folder", "handlers"];
+    if (Object.keys(values).some((key) => !keys.includes(key)))
+      throw new Error("WebSocket options contain an unknown field");
+    if (values.port !== undefined && (!Number.isInteger(values.port) || values.port < 0 || values.port > 65535))
+      throw new Error("WebSocket port must be an integer between 0 and 65535");
+    for (const key of ["dir", "folder"]) {
+      if (values[key] !== undefined && (typeof values[key] !== "string" || !values[key].trim()))
+        throw new Error(`WebSocket ${key} must be a nonempty string`);
+    }
+    if (values.handlers !== undefined) {
+      if (!Array.isArray(values.handlers))
+        throw new Error("WebSocket handlers must be an array");
+      const paths = new Set;
+      const channels = new Set;
+      for (const entry of values.handlers) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry) || Object.keys(entry).some((key) => !["path", "handler"].includes(key)))
+          throw new Error("WebSocket handlers entries must contain path and handler");
+        if (typeof entry.path !== "string")
+          throw new Error("WebSocket handlers.path must be a string");
+        if (!(entry.handler instanceof BaseSocketHandler))
+          throw new Error("WebSocket handlers.handler must be a BaseSocketHandler");
+        const path = entry.path.replace(/^\/+|\/+$/g, "");
+        if (paths.has(path))
+          throw new Error("WebSocket handlers.path must be unique");
+        paths.add(path);
+        const Handler = entry.handler.constructor;
+        const channel = Handler.channel === "default" ? path : Handler.channel;
+        if (channels.has(channel))
+          throw new Error("WebSocket handlers channels must be unique");
+        channels.add(channel);
+      }
+    }
+  },
+  create(options) {
+    return new WebSocketServer(options);
+  }
+};
+var plugin_default = definition;
+export {
+  plugin_default as default
+};

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@beespoke/micro-server-websocket-bun",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.5",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin/index.d.ts",
+      "import": "./dist/plugin/index.js",
+      "default": "./dist/plugin/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun ../../scripts/build-package.ts"
+  },
+  "dependencies": {
+    "@types/bun": "1.3.14",
+    "@types/node": "^24.0.0"
+  },
+  "peerDependencies": {
+    "@beespoke/micro-server": "^2.0.5"
+  },
+  "peerDependenciesMeta": {
+    "@beespoke/micro-server": {
+      "optional": true
+    }
+  }
+}