@sockethub/server 5.0.0-alpha.10

package/src/bootstrap/load-platforms.ts

@@ -0,0 +1,151 @@
+/**
+ * bootstrap/platforms.ts
+ *
+ * A Singleton responsible for finding and loading all valid Sockethub
+ * platforms, and whitelisting or blacklisting (or neither) based on the
+ * config.
+ */
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import debug from "debug";
+
+import {
+    type PlatformConfig,
+    type PlatformInterface,
+    type PlatformSchemaStruct,
+    type PlatformSession,
+    validatePlatformSchema,
+} from "@sockethub/schemas";
+
+const log = debug("sockethub:server:bootstrap:platforms");
+
+export type PlatformStruct = {
+    id: string;
+    moduleName: string;
+    modulePath?: string;
+    config: PlatformConfig;
+    schemas: PlatformSchemaStruct;
+    version: string;
+    types: Array<string>;
+};
+
+export type PlatformMap = Map<string, PlatformStruct>;
+
+const dummySession: PlatformSession = {
+    debug: () => {},
+    sendToClient: () => {},
+    updateActor: async () => {},
+};
+
+// if the platform schema lists valid types it implements (essentially methods/verbs for
+// Sockethub to call) then add it to the supported types list.
+function platformListsSupportedTypes(p): boolean {
+    return (
+        p.schema.messages.properties?.type?.enum &&
+        p.schema.messages.properties.type.enum.length > 0
+    );
+}
+
+// Resolve the absolute filesystem path to a platform module
+function resolveModulePath(platformName: string): string | undefined {
+    try {
+        // Resolve to file:// URL
+        const resolved = import.meta.resolve(platformName);
+
+        // Convert to absolute path
+        const filePath = fileURLToPath(resolved);
+
+        // Walk up to find package.json (package root)
+        let dir = dirname(filePath);
+        for (let i = 0; i < 5; i++) {
+            const pkgPath = join(dir, "package.json");
+            if (existsSync(pkgPath)) {
+                return dir;
+            }
+            dir = dirname(dir);
+        }
+
+        // Fallback: return directory of entry point
+        return dirname(filePath);
+    } catch (err) {
+        log(
+            `failed to resolve module path for ${platformName}: ${err.message}`,
+        );
+        return undefined;
+    }
+}
+
+async function loadPlatform(platformName: string, injectRequire) {
+    log(`loading ${platformName}`);
+    let p: PlatformInterface;
+    if (injectRequire) {
+        const P = await injectRequire(platformName);
+        p = new P();
+    } else {
+        const P = await import(platformName);
+        p = new P.default(dummySession);
+    }
+    const err = validatePlatformSchema(p.schema);
+
+    if (err) {
+        throw new Error(`${platformName} ${err}`);
+    }
+    if (typeof p.config !== "object") {
+        throw new Error(
+            `${platformName} platform must have a config property that is an object.`,
+        );
+    }
+    return p;
+}
+
+export default async function loadPlatforms(
+    platformsList: Array<string>,
+    injectRequire = undefined,
+): Promise<PlatformMap> {
+    log(`platforms to load: ${platformsList}`);
+    // load platforms from config.platforms
+    const platforms = new Map();
+
+    if (platformsList.length <= 0) {
+        throw new Error(
+            "No platforms defined. Please check your sockethub.config.json",
+        );
+    }
+
+    for (const platformName of platformsList) {
+        const p = await loadPlatform(platformName, injectRequire);
+        let types = [];
+
+        if (p.schema.credentials) {
+            // register the platforms credentials schema
+            types.push("credentials");
+        } else {
+            p.config.requireCredentials = [];
+        }
+
+        if (platformListsSupportedTypes(p)) {
+            types = [...types, ...p.schema.messages.properties.type.enum];
+        }
+
+        // Resolve module path (skip in test mode with injectRequire)
+        const modulePath = injectRequire
+            ? undefined
+            : resolveModulePath(platformName);
+
+        platforms.set(p.schema.name, {
+            id: p.schema.name,
+            moduleName: p.schema.name,
+            modulePath: modulePath,
+            config: p.config,
+            schemas: {
+                credentials: p.schema.credentials || {},
+                messages: p.schema.messages || {},
+            },
+            version: p.schema.version,
+            types: types,
+        });
+    }
+
+    return platforms;
+}

package/src/config.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "bun:test";
+
+import { Config } from "./config.js";
+
+describe("config", () => {
+    it("loads default values", () => {
+        const config = new Config();
+        expect(config).toHaveProperty("get");
+        expect(config.get("sockethub:host")).toEqual("localhost");
+    });
+
+    it("host overrides from env", () => {
+        const hostname = "a host string";
+        process.env = { HOST: hostname };
+        const config = new Config();
+        expect(config).toHaveProperty("get");
+        expect(config.get("sockethub:host")).toEqual(hostname);
+    });
+
+    it("defaults to redis config", () => {
+        process.env = { REDIS_URL: "" };
+        const config = new Config();
+        expect(config).toHaveProperty("get");
+        expect(config.get("redis")).toEqual({ url: "redis://127.0.0.1:6379" });
+    });
+
+    // it("redis url overridden by env var", () => {
+    //     process.env = { REDIS_URL: "foobar83" };
+    //     const config = new Config();
+    //     expect(config).toHaveProperty("get");
+    //     expect(config.get("redis")).toEqual({ url: "foobar83" });
+    // });
+});

package/src/config.ts

@@ -0,0 +1,98 @@
+import fs from "node:fs";
+import path from "node:path";
+import debug from "debug";
+import nconf from "nconf";
+
+import { __dirname } from "./util.js";
+
+const log = debug("sockethub:server:bootstrap:config");
+const data = JSON.parse(
+    fs.readFileSync(path.resolve(__dirname, "defaults.json"), "utf-8"),
+);
+
+const defaultConfig = "sockethub.config.json";
+
+export class Config {
+    constructor() {
+        log("initializing config");
+        // assign config loading priorities (command-line, environment, cfg, defaults)
+        nconf.argv({
+            info: {
+                type: "boolean",
+                describe: "Display Sockethub runtime information",
+            },
+            examples: {
+                type: "boolean",
+                describe:
+                    "Enable the examples pages served at [host]:[port]/examples",
+            },
+            config: {
+                alias: "c",
+                type: "string",
+                describe: "Path to sockethub.config.json",
+            },
+            port: {
+                type: "number",
+                alias: "sockethub.port",
+            },
+            host: {
+                type: "string",
+                alias: "sockethub.host",
+            },
+            "redis.url": {
+                type: "string",
+                describe: "Redis URL e.g. redis://host:port",
+            },
+            "sentry.dsn": {
+                type: "string",
+                describe: "Provide your Sentry DSN",
+            },
+        });
+
+        // get value of flags defined by any command-line params
+        const examples = nconf.get("examples");
+
+        // Load the main config
+        let configFile = nconf.get("config");
+        if (configFile) {
+            configFile = path.resolve(configFile);
+            if (!fs.existsSync(configFile)) {
+                throw new Error(`Config file not found: ${configFile}`);
+            }
+            log(`reading config file at ${configFile}`);
+            nconf.file(configFile);
+        } else {
+            if (fs.existsSync(`${process.cwd()}/${defaultConfig}`)) {
+                log(`loading local ${defaultConfig}`);
+                nconf.file(`${process.cwd()}/${defaultConfig}`);
+            }
+            nconf.use("memory");
+        }
+
+        // only override config file if explicitly mentioned in command-line params
+        nconf.set("examples", examples ? true : nconf.get("examples"));
+
+        // load defaults
+        nconf.defaults(data);
+
+        nconf.required(["platforms"]);
+
+        nconf.set(
+            "sockethub:host",
+            process.env.HOST || nconf.get("sockethub:host"),
+        );
+        nconf.set(
+            "sockethub:port",
+            process.env.PORT || nconf.get("sockethub:port"),
+        );
+
+        // allow a redis://user:host:port url, takes precedence
+        if (process.env.REDIS_URL) {
+            nconf.set("redis:url", process.env.REDIS_URL);
+        }
+    }
+    get = (key: string) => nconf.get(key);
+}
+
+const config = new Config();
+export default config;

package/src/defaults.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://sockethub.org/schemas/3.0.0-alpha.4/sockethub-config.json",
+  "examples": true,
+  "log_file": "",
+  "packageConfig": {
+    "@sockethub/activity-streams": {
+      "specialObjs": ["credentials"],
+      "failOnUnknownObjectProperties": true
+    }
+  },
+  "platforms": [
+    "@sockethub/platform-dummy",
+    "@sockethub/platform-feeds",
+    "@sockethub/platform-irc",
+    "@sockethub/platform-metadata",
+    "@sockethub/platform-xmpp"
+  ],
+  "public": {
+    "protocol": "http",
+    "host": "localhost",
+    "port": 10550,
+    "path": "/"
+  },
+  "redis": {
+    "url": "redis://127.0.0.1:6379"
+  },
+  "sentry": {
+    "dsn": "",
+    "traceSampleRate": 1.0
+  },
+  "sockethub": {
+    "port": 10550,
+    "host": "localhost",
+    "path": "/sockethub"
+  }
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+import debug from "debug";
+import config from "./config";
+import Sockethub from "./sockethub";
+
+let sentry: { readonly reportError: (err: Error) => void } = {
+    reportError: (err: Error) => {},
+};
+
+export async function server() {
+    let sockethub: Sockethub;
+    const log = debug("sockethub:init");
+
+    // conditionally initialize sentry
+    if (config.get("sentry:dsn")) {
+        log("initializing sentry");
+        sentry = await import("./sentry");
+    }
+
+    try {
+        sockethub = new Sockethub();
+    } catch (err) {
+        sentry.reportError(err);
+        console.error(err);
+        process.exit(1);
+    }
+
+    process.once("uncaughtException", (err: Error) => {
+        console.error(
+            `${(new Date()).toUTCString()} UNCAUGHT EXCEPTION\n`,
+            err.stack,
+        );
+        sentry.reportError(err);
+        process.exit(1);
+    });
+
+    process.once("unhandledRejection", (err: Error) => {
+        console.error(
+            `${(new Date()).toUTCString()} UNHANDLED REJECTION\n`,
+            err,
+        );
+        sentry.reportError(err);
+        process.exit(1);
+    });
+
+    process.once("SIGTERM", () => {
+        console.log("Received TERM signal. Exiting.");
+        process.exit(0);
+    });
+
+    process.once("SIGINT", () => {
+        console.log("Received INT signal. Exiting.");
+        process.exit(0);
+    });
+
+    process.once("exit", async () => {
+        console.log("sockethub shutdown...");
+        await sockethub.shutdown();
+        process.exit(0);
+    });
+
+    try {
+        await sockethub.boot();
+    } catch (err) {
+        sentry.reportError(err);
+        console.error(err);
+        process.exit(1);
+    }
+}

package/src/janitor.test.ts

@@ -0,0 +1,211 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import * as sinon from "sinon";
+
+import { Janitor } from "./janitor.js";
+
+const sockets = [
+    { id: "socket foo", emit: () => {} },
+    { id: "socket bar", emit: () => {} },
+];
+
+function getPlatformInstanceFake() {
+    return {
+        flaggedForTermination: false,
+        config: {
+            initialized: false,
+            persist: true,
+            requireCredentials: ["foo", "bar"],
+        },
+        global: false,
+        shutdown: sinon.stub(),
+        process: {
+            removeListener: sinon.stub(),
+        },
+        sessions: new Set(["session foo", "session bar"]),
+        sessionCallbacks: {
+            close: (() =>
+                new Map([
+                    ["session foo", function sessionFooClose() {}],
+                    ["session bar", function sessionBarClose() {}],
+                ]))(),
+            message: (() =>
+                new Map([
+                    ["session foo", function sessionFooMessage() {}],
+                    ["session bar", function sessionBarMessage() {}],
+                ]))(),
+        },
+    };
+}
+
+const cycleInterval = 10;
+
+describe("Janitor", () => {
+    let sandbox, fetchSocketsFake, janitor;
+
+    beforeEach((done) => {
+        sandbox = sinon.createSandbox();
+        fetchSocketsFake = sandbox.stub().returns(sockets);
+
+        janitor = new Janitor();
+        janitor.getSockets = fetchSocketsFake;
+        expect(janitor.cycleInterval).not.toEqual(cycleInterval);
+        janitor.cycleInterval = cycleInterval;
+        expect(janitor.cycleInterval).toEqual(cycleInterval);
+        janitor.start();
+        setTimeout(() => {
+            expect(janitor.cycleCount).toEqual(1);
+            done();
+        }, cycleInterval);
+    });
+
+    afterEach((done) => {
+        sandbox.reset();
+        janitor.stop();
+        setTimeout(() => {
+            done();
+        }, janitor.cycleInterval * 2);
+    });
+
+    it("runs cycle at every cycleInterval", (done) => {
+        const currCycleCount = janitor.cycleCount;
+        expect(currCycleCount).not.toEqual(0);
+        setTimeout(() => {
+            expect(janitor.cycleCount).toEqual(currCycleCount + 1);
+            setTimeout(() => {
+                expect(janitor.cycleCount).toEqual(currCycleCount + 2);
+                done();
+            }, cycleInterval);
+        }, cycleInterval);
+    });
+
+    describe("removeSessionCallbacks", () => {
+        it("removes session listeners and callbacks for a given platform", () => {
+            const pi = getPlatformInstanceFake();
+            const barMessage = pi.sessionCallbacks.message.get("session bar");
+            const barClose = pi.sessionCallbacks.close.get("session bar");
+            pi.flaggedForTermination = true;
+            janitor.removeSessionCallbacks(pi, "session foo");
+            sinon.assert.calledTwice(pi.process.removeListener);
+            expect(
+                pi.sessionCallbacks.message.get("session foo"),
+            ).toBeUndefined();
+            expect(pi.sessionCallbacks.message.get("session bar")).toEqual(
+                barMessage,
+            );
+            expect(
+                pi.sessionCallbacks.close.get("session foo"),
+            ).toBeUndefined();
+            expect(pi.sessionCallbacks.close.get("session bar")).toEqual(
+                barClose,
+            );
+        });
+    });
+
+    describe("removeStaleSocketSessions", () => {
+        it("doesnt do anything if the socket is active and stop is not flagged", async () => {
+            const pi = getPlatformInstanceFake();
+            janitor.removeSessionCallbacks = sinon.stub();
+            janitor.socketExists = sinon.stub().returns(true);
+            expect(janitor.stopTriggered).toBeFalse();
+            await janitor.removeStaleSocketSessions(pi);
+            sinon.assert.notCalled(janitor.removeSessionCallbacks);
+        });
+
+        it("removes session if the socket is active and stop is flagged", async () => {
+            const pi = getPlatformInstanceFake();
+            janitor.removeSessionCallbacks = sinon.stub();
+            janitor.socketExists = sinon.stub().returns(true);
+            janitor.stop();
+            expect(janitor.stopTriggered).toBeTrue();
+            await janitor.removeStaleSocketSessions(pi);
+            sinon.assert.calledTwice(janitor.removeSessionCallbacks);
+            sinon.assert.calledWith(
+                janitor.removeSessionCallbacks,
+                pi,
+                "session foo",
+            );
+            sinon.assert.calledWith(
+                janitor.removeSessionCallbacks,
+                pi,
+                "session bar",
+            );
+        });
+
+        it("removes session if the socket is inactive", async () => {
+            const pi = getPlatformInstanceFake();
+            janitor.removeSessionCallbacks = sinon.stub();
+            janitor.socketExists = sinon
+                .stub()
+                .onFirstCall()
+                .returns(false)
+                .onSecondCall()
+                .returns(true);
+            expect(janitor.stopTriggered).toBeFalse();
+            await janitor.removeStaleSocketSessions(pi);
+            sinon.assert.calledOnce(janitor.removeSessionCallbacks);
+            sinon.assert.calledWith(
+                janitor.removeSessionCallbacks,
+                pi,
+                "session foo",
+            );
+        });
+    });
+
+    describe("performStaleCheck", () => {
+        it("removes flagged and uninitialized platform instances", async () => {
+            const pi = getPlatformInstanceFake();
+            pi.flaggedForTermination = true;
+            pi.config.initialized = false;
+            janitor.removeStaleSocketSessions = sandbox.stub();
+            janitor.removeStalePlatformInstance = sandbox.stub();
+            await janitor.performStaleCheck(pi);
+            sinon.assert.calledOnce(janitor.removeStaleSocketSessions);
+            sinon.assert.calledOnce(janitor.removeStalePlatformInstance);
+            expect(pi.flaggedForTermination).toBeTrue();
+        });
+
+        it("flags for termination when there are not sockets", async () => {
+            const pi = getPlatformInstanceFake();
+            pi.sessions = new Set();
+            pi.flaggedForTermination = false;
+            pi.config.initialized = true;
+            janitor.removeStaleSocketSessions = sandbox.stub();
+            janitor.removeStalePlatformInstance = sandbox.stub();
+            await janitor.performStaleCheck(pi);
+            sinon.assert.calledOnce(janitor.removeStaleSocketSessions);
+            sinon.assert.calledOnce(janitor.removeStalePlatformInstance);
+        });
+    });
+
+    describe("removeStalePlatformInstance", () => {
+        it("flags stale platform", async () => {
+            const pi = getPlatformInstanceFake();
+            expect(pi.flaggedForTermination).toBeFalse();
+            await janitor.removeStalePlatformInstance(pi);
+            sinon.assert.notCalled(pi.shutdown);
+            expect(pi.flaggedForTermination).toBeTrue();
+        });
+
+        it("removes flagged stale platform", async () => {
+            const pi = getPlatformInstanceFake();
+            pi.flaggedForTermination = true;
+            await janitor.removeStalePlatformInstance(pi);
+            sinon.assert.calledOnce(pi.shutdown);
+        });
+    });
+
+    it("closes all connections when stop() is called", (done) => {
+        const prevCycle = janitor.cycleCount;
+        janitor.stop();
+        setTimeout(() => {
+            expect(janitor.cycleCount).toEqual(prevCycle);
+            setTimeout(() => {
+                expect(janitor.cycleCount).toEqual(prevCycle);
+                setTimeout(() => {
+                    expect(janitor.cycleCount).toEqual(prevCycle);
+                    done();
+                }, cycleInterval);
+            }, cycleInterval);
+        }, cycleInterval);
+    });
+});