@sockethub/server 5.0.0-alpha.4 → 5.0.0-alpha.6

package/src/janitor.ts

@@ -1,133 +1,156 @@
-import debug from 'debug';
-
-import PlatformInstance, { platformInstances } from './platform-instance';
-import listener, { SocketInstance } from "./listener";
-
-const rmLog = debug('sockethub:server:janitor');
-
-class Janitor {
-  cycleInterval = 15000;
-  cycleCount = 0;   // a counter for each cycleInterval
-  reportCount = 0;  // number of times a report is printed
-  protected stopTriggered = false;
-  protected sockets: Array<SocketInstance>;
-  private cycleRunning = false;
-
-  /**
-   * Every TICK the `Janitor` will compare existing platform instances with `socket.ids`
-   * (aka. `sessionId`). If all of the `sessionIds` associated with a `platformInstance` have
-   * no corresponding `socket.id` (from the `http.io` `socket.io` instance), then the
-   * `platformInstance` will first be flagged, if after the next `cycleInterval` the same
-   * state is determined, the platform will be destroyed (this allows for page
-   * refreshes not destroying platform instances)
-   */
-  start(): void {
-    rmLog('initializing');
-    this.clean().then(() => {
-      rmLog('cleaning cycle started');
-    });
-  }
-
-  async stop(): Promise<void> {
-    this.stopTriggered = true;
-    rmLog('stopping, terminating all sessions');
-    for (const platformInstance of platformInstances.values()) {
-      this.removeStaleSocketSessions(platformInstance);
-      await this.removeStalePlatformInstance(platformInstance);
-      await platformInstance.shutdown();
+import debug from "debug";
+
+import listener, { type SocketInstance } from "./listener.js";
+import type PlatformInstance from "./platform-instance.js";
+import { platformInstances } from "./platform-instance.js";
+
+const rmLog = debug("sockethub:server:janitor");
+
+export class Janitor {
+    cycleInterval = 15000;
+    cycleCount = 0; // a counter for each cycleInterval
+    reportCount = 0; // number of times a report is printed
+    protected stopTriggered = false;
+    protected sockets: Array<SocketInstance>;
+    private cycleRunning = false;
+
+    /**
+     * Every TICK the `Janitor` will compare existing platform instances with `socket.ids`
+     * (aka. `sessionId`). If all the `sessionIds` associated with a `platformInstance` have
+     * no corresponding `socket.id` (from the `http.io` `socket.io` instance), then the
+     * `platformInstance` will first be flagged, if after the next `cycleInterval` the same
+     * state is determined, the platform will be destroyed (this allows for page
+     * refreshes not destroying platform instances)
+     */
+    start(): void {
+        rmLog("initializing");
+        this.clean().then(() => {
+            rmLog("cleaning cycle started");
+        });
     }
-  }
 
-  private removeSessionCallbacks(platformInstance: PlatformInstance, sessionId: string): void {
-    for (const key in platformInstance.sessionCallbacks) {
-      platformInstance.process.removeListener(
-        key, platformInstance.sessionCallbacks[key].get(sessionId));
-      platformInstance.sessionCallbacks[key].delete(sessionId);
+    async stop(): Promise<void> {
+        this.stopTriggered = true;
+        rmLog("stopping, terminating all sessions");
+        for (const platformInstance of platformInstances.values()) {
+            this.removeStaleSocketSessions(platformInstance);
+            await this.removeStalePlatformInstance(platformInstance);
+            await platformInstance.shutdown();
+        }
     }
-  }
-
-  private removeStaleSocketSessions(
-    platformInstance: PlatformInstance
-  ): void {
-    for (const sessionId of platformInstance.sessions.values()) {
-      if ((this.stopTriggered) || (!this.socketExists(sessionId))) {
-        this.removeStaleSocketSession(platformInstance, sessionId);
-      }
+
+    private removeSessionCallbacks(
+        platformInstance: PlatformInstance,
+        sessionId: string,
+    ): void {
+        for (const key in platformInstance.sessionCallbacks) {
+            platformInstance.process.removeListener(
+                key,
+                platformInstance.sessionCallbacks[key].get(sessionId),
+            );
+            platformInstance.sessionCallbacks[key].delete(sessionId);
+        }
     }
-  }
-
-  private removeStaleSocketSession(platformInstance: PlatformInstance, sessionId: string) {
-    rmLog(
-      `removing ${!this.stopTriggered ? 'stale ' : ''}socket session reference ${sessionId} 
-          in platform instance ${platformInstance.id}`
-    );
-    platformInstance.sessions.delete(sessionId);
-    this.removeSessionCallbacks(platformInstance, sessionId);
-  }
-
-  private async removeStalePlatformInstance(platformInstance: PlatformInstance): Promise<void> {
-    if ((platformInstance.flaggedForTermination) || (this.stopTriggered)) {
-      rmLog(`terminating platform instance ${platformInstance.id}`);
-      await platformInstance.shutdown(); // terminate
-    } else {
-      rmLog(`flagging for termination platform instance ${platformInstance.id} ` +
-        `(no registered sessions found)`);
-      platformInstance.flaggedForTermination = true;
+
+    private removeStaleSocketSessions(
+        platformInstance: PlatformInstance,
+    ): void {
+        for (const sessionId of platformInstance.sessions.values()) {
+            if (this.stopTriggered || !this.socketExists(sessionId)) {
+                this.removeStaleSocketSession(platformInstance, sessionId);
+            }
+        }
     }
-  }
 
-  private socketExists(sessionId: string) {
-    for (const socket of this.sockets) {
-      if (socket.id === sessionId) {
-        return true;
-      }
+    private removeStaleSocketSession(
+        platformInstance: PlatformInstance,
+        sessionId: string,
+    ) {
+        rmLog(
+            `removing ${
+                !this.stopTriggered ? "stale " : ""
+            }socket session reference ${sessionId} 
+          in platform instance ${platformInstance.id}`,
+        );
+        platformInstance.sessions.delete(sessionId);
+        this.removeSessionCallbacks(platformInstance, sessionId);
     }
-    return false;
-  }
-
-  private async delay(ms): Promise<void> {
-    return await new Promise(resolve => setTimeout(resolve, ms));
-  }
-
-  private async getSockets(): Promise<Array<SocketInstance>> {
-    return await listener.io.fetchSockets();
-  }
-
-  private async performStaleCheck(platformInstance: PlatformInstance) {
-    this.removeStaleSocketSessions(platformInstance);
-    // Static platforms are for global use, not tied to a unique to session / eg. credentials)
-    if (!platformInstance.global) {
-      if ((!platformInstance.initialized) || (platformInstance.sessions.size === 0)) {
-        // either the platform failed to initialize, or there are no more sessions linked to it
-        await this.removeStalePlatformInstance(platformInstance);
-      }
+
+    private async removeStalePlatformInstance(
+        platformInstance: PlatformInstance,
+    ): Promise<void> {
+        if (platformInstance.flaggedForTermination || this.stopTriggered) {
+            rmLog(`terminating platform instance ${platformInstance.id}`);
+            await platformInstance.shutdown(); // terminate
+        } else {
+            rmLog(
+                `flagging for termination platform instance ${platformInstance.id} (no registered sessions found)`,
+            );
+            platformInstance.flaggedForTermination = true;
+        }
     }
-  }
-
-  private async clean(): Promise<void> {
-    if (this.stopTriggered) {
-      this.cycleRunning = false;
-      return;
-    } else if (this.cycleRunning) {
-      throw new Error('janitor cleanup cycle called while already running');
+
+    private socketExists(sessionId: string) {
+        for (const socket of this.sockets) {
+            if (socket.id === sessionId) {
+                return true;
+            }
+        }
+        return false;
     }
-    this.cycleRunning = true;
-    this.cycleCount++;
-    this.sockets = await this.getSockets();
-
-    if (!(this.cycleCount % 4)) {
-      this.reportCount++;
-      rmLog(
-        `socket sessions: ${this.sockets.length} platform instances: ${platformInstances.size}`);
+
+    private async delay(ms: number): Promise<void> {
+        return await new Promise((resolve) => setTimeout(resolve, ms));
+    }
+
+    private async getSockets(): Promise<Array<SocketInstance>> {
+        return listener.io.fetchSockets();
+    }
+
+    private async performStaleCheck(platformInstance: PlatformInstance) {
+        this.removeStaleSocketSessions(platformInstance);
+        // Static platforms are for global use, not tied to a unique to session
+        // (e.g. a stateful platform where credentials are supplied)
+        if (!platformInstance.global) {
+            if (
+                (platformInstance.config.persist &&
+                    !platformInstance.config.initialized) ||
+                platformInstance.sessions.size === 0
+            ) {
+                // either the platform failed to initialize, or there are no more sessions linked to it
+                await this.removeStalePlatformInstance(platformInstance);
+            }
+        }
     }
 
-    for (const platformInstance of platformInstances.values()) {
-      await this.performStaleCheck(platformInstance);
+    private async clean(): Promise<void> {
+        if (this.stopTriggered) {
+            this.cycleRunning = false;
+            return;
+        }
+        if (this.cycleRunning) {
+            throw new Error(
+                "janitor cleanup cycle called while already running",
+            );
+        }
+        this.cycleRunning = true;
+        this.cycleCount++;
+        this.sockets = await this.getSockets();
+
+        if (!(this.cycleCount % 4)) {
+            this.reportCount++;
+            rmLog(
+                `socket sessions: ${this.sockets.length} platform instances: ${platformInstances.size}`,
+            );
+        }
+
+        for (const platformInstance of platformInstances.values()) {
+            await this.performStaleCheck(platformInstance);
+        }
+        this.cycleRunning = false;
+        await this.delay(this.cycleInterval);
+        return this.clean();
     }
-    this.cycleRunning = false;
-    await this.delay(this.cycleInterval);
-    return this.clean();
-  }
 }
 
 const janitor = new Janitor();

package/src/listener.ts

@@ -1,13 +1,18 @@
-import debug from 'debug';
-import bodyParser from 'body-parser';
-import express from 'express';
-import * as HTTP from 'http';
-import { Server } from 'socket.io';
+import { existsSync, writeFileSync } from "node:fs";
+import * as HTTP from "node:http";
+import { createRequire } from "node:module";
+import path from "node:path";
+import bodyParser from "body-parser";
+import debug from "debug";
+import express from "express";
+import rateLimit from "express-rate-limit";
+import { Server } from "socket.io";
 
-import config from './config';
-import routes from './routes';
+import config from "./config.js";
+import routes from "./routes.js";
+const require = createRequire(import.meta.url);
 
-const log = debug('sockethub:server:listener');
+const log = debug("sockethub:server:listener");
 
 /**
  * Handles the initialization and access of Sockethub resources.
@@ -17,67 +22,152 @@ const log = debug('sockethub:server:listener');
  *  - Socket.io (bidirectional websocket communication)
  */
 class Listener {
-  io: Server;
-  http: HTTP.Server;
-
-  /**
-   * Starts the services needed for Sockethub to operate. After this command completes,
-   * the `http` and `io` class properties will be set.
-   */
-  start() {
-    // initialize express and socket.io objects
-    const app = Listener.initExpress();
-    this.http = new HTTP.Server(app);
-    this.io = new Server(this.http, {
-      path: config.get('sockethub:path') as string,
-      cors: {
-        origin: "*",
-        methods: [ "GET", "POST" ]
-      }
-    });
-    routes.setup(app);
-    this.startHttp();
-  }
-
-  private startHttp() {
-    this.http.listen(config.get('sockethub:port'), config.get('sockethub:host') as number, () => {
-      log(`sockethub listening on ` +
-        `${config.get('sockethub:host')}:${config.get('sockethub:port')}`);
-    });
-  }
-
-  private static initExpress() {
-    const app = express();
-    // templating engines
-    app.set('view engine', 'ejs');
-    // use bodyParser
-    app.use(bodyParser.urlencoded({extended: true}));
-    app.use(bodyParser.json());
-    return app;
-  }
+    io: Server;
+    http: HTTP.Server;
+
+    /**
+     * Starts the services needed for Sockethub to operate. After this command completes,
+     * the `http` and `io` class properties will be set.
+     */
+    start() {
+        // initialize express and socket.io objects
+        const app = Listener.initExpress();
+        this.http = new HTTP.Server(app);
+        this.io = new Server(this.http, {
+            path: config.get("sockethub:path") as string,
+            cors: {
+                origin: "*",
+                methods: ["GET", "POST"],
+            },
+        });
+
+        routes.setup(app);
+
+        if (config.get("examples")) {
+            this.addExamplesRoutes(app);
+        }
+
+        this.startHttp();
+    }
+
+    /**
+     * Resolves the path to the examples static files from @sockethub/examples package.
+     * Returns null if the package is not installed.
+     */
+    private resolveExamplesPath(): string | null {
+        try {
+            const examplesPkgPath = require.resolve(
+                "@sockethub/examples/package.json",
+            );
+            const examplesDir = path.join(
+                path.dirname(examplesPkgPath),
+                "build",
+            );
+            if (existsSync(examplesDir)) {
+                log(
+                    `examples resolved from @sockethub/examples: ${examplesDir}`,
+                );
+                return examplesDir;
+            }
+            log(
+                `@sockethub/examples found but build directory missing: ${examplesDir}`,
+            );
+            return null;
+        } catch {
+            return null;
+        }
+    }
+
+    private addExamplesRoutes(app) {
+        const examplesPath = this.resolveExamplesPath();
+
+        if (!examplesPath) {
+            console.error(
+                "\n❌ Error: --examples flag requires @sockethub/examples package\n\n" +
+                    "The examples package is not installed. To use the examples feature, install it:\n\n" +
+                    "  bun add @sockethub/examples\n\n" +
+                    "Or run sockethub without the --examples flag.\n",
+            );
+            process.exit(1);
+        }
+
+        // Set up rate limiter to prevent DoS attacks on file system access
+        const limiter = rateLimit({
+            windowMs: 1 * 60 * 1000, // 1 minute
+            max: 60, // max 60 requests per windowMs
+            standardHeaders: true,
+            legacyHeaders: false,
+        });
+
+        // Write runtime config for the examples app
+        writeFileSync(
+            path.join(examplesPath, "config.json"),
+            JSON.stringify({
+                sockethub: config.get("sockethub"),
+                public: config.get("public"),
+            }),
+        );
+
+        app.use(express.static(examplesPath));
+
+        const examplesIndex = path.join(examplesPath, "index.html");
+        app.get("*", limiter, (req, res) => {
+            res.sendFile(examplesIndex);
+        });
+
+        log(
+            `examples served at http://${config.get("sockethub:host")}:${config.get(
+                "sockethub:port",
+            )}`,
+        );
+    }
+
+    private startHttp() {
+        this.http.listen(
+            config.get("sockethub:port"),
+            config.get("sockethub:host") as number,
+            () => {
+                log(
+                    `sockethub listening on ws://${config.get("sockethub:host")}:${config.get(
+                        "sockethub:port",
+                    )}`,
+                );
+            },
+        );
+    }
+
+    private static initExpress() {
+        const app = express();
+        // templating engines
+        app.set("view engine", "ejs");
+        // use bodyParser
+        app.use(bodyParser.urlencoded({ extended: true }));
+        app.use(bodyParser.json());
+        return app;
+    }
 }
 
 const listener = new Listener();
 
 interface EmitFunction {
-  (type: string, data: unknown)
+    (type: string, data: unknown);
 }
 
 export interface SocketInstance {
-  id: string;
-  emit: EmitFunction;
+    id: string;
+    emit: EmitFunction;
 }
 
 export async function getSocket(sessionId: string): Promise<SocketInstance> {
-  const sockets: Array<SocketInstance> = await listener.io.fetchSockets();
-  return new Promise((resolve, reject) => {
-    for (const socket of sockets) {
-      if (sessionId === socket.id) {
-        return resolve(socket);
-      }
-    }
-    return reject(`unable to find socket for sessionId ${sessionId}`);
-  });
+    const sockets: Array<SocketInstance> = await listener.io.fetchSockets();
+    return new Promise((resolve, reject) => {
+        for (const socket of sockets) {
+            if (sessionId === socket.id) {
+                return resolve(socket);
+            }
+        }
+        return reject(`unable to find socket for sessionId ${sessionId}`);
+    });
 }
 
 export default listener;

package/src/middleware/create-activity-object.test.ts

@@ -1,10 +1,30 @@
-import createActivityObject from "./create-activity-object";
+import { describe, expect, it } from "bun:test";
+import createActivityObject from "./create-activity-object.js";
 
-describe('Middleware: createActivityObject', () => {
-  it('Calls activity.Object.create with incoming data', (done) => {
-    // @ts-ignore
-    createActivityObject({foo: 'bar'}, (msg) => {
-      done();
+describe("Middleware: createActivityObject", () => {
+    it("Calls activity.Object.create and fails with invalid property", async () => {
+        expect(() => {
+            createActivityObject({ foo: "bar" }, (o) => {
+                expect(o).not.toEqual({ foo: "bar" });
+            });
+        }).toThrow("ActivityStreams validation failed: the \"object\" property requires an 'id' property. Example: { id: \"user@example.com\", type: \"person\" }");
     });
-  });
-});
+    it("Calls activity.Object.create with incoming data", async () => {
+        createActivityObject(
+            {
+                id: "test",
+                context: "foo",
+                type: "bar",
+                content: "some text",
+            },
+            (o) => {
+                expect(o).toEqual({
+                    id: "test",
+                    context: "foo",
+                    type: "bar",
+                    content: "some text",
+                });
+            },
+        );
+    });
+});

package/src/middleware/create-activity-object.ts

@@ -1,16 +1,22 @@
-import ActivityStreams from '@sockethub/activity-streams';
-import config from "../config";
-import {IActivityStream} from "@sockethub/schemas";
-import {MiddlewareChainInterface} from "../middleware";
-const activity = ActivityStreams(config.get('activity-streams:opts'));
+import { ASFactory } from "@sockethub/activity-streams";
+import type { ActivityObject } from "@sockethub/schemas";
+
+import config from "../config.js";
+import type { MiddlewareChainInterface } from "../middleware.js";
+
+const activity = ASFactory(
+    config.get("packageConfig:@sockethub/activity-streams"),
+);
 
 /**
- * A simple middleware wrapper for the activity-streams Object.create method.
+ * A simple middleware wrapper for the activity-streams `Object.create` method.
  * @param obj
  * @param done
  */
-export default function createActivityObject(obj: IActivityStream,
-                                             done: MiddlewareChainInterface) {
-  activity.Object.create(obj);
-  done(obj);
+export default function createActivityObject(
+    obj: ActivityObject,
+    done: MiddlewareChainInterface,
+) {
+    activity.Object.create(obj);
+    done(obj);
 }