@sockethub/server 5.0.0-alpha.11 → 5.0.0-alpha.12

package/src/platform-instance.ts

@@ -2,6 +2,7 @@ import { type ChildProcess, fork } from "node:child_process";
 import { join } from "node:path";
 
 import { type JobDataDecrypted, JobQueue } from "@sockethub/data-layer";
+import { createLogger } from "@sockethub/logger";
 import type {
     ActivityStream,
     CompletedJobHandler,
@@ -9,9 +10,11 @@ import type {
     Logger,
     PlatformConfig,
 } from "@sockethub/schemas";
+import {
+    buildCanonicalContext,
+    INTERNAL_PLATFORM_CONTEXT_URL,
+} from "@sockethub/schemas";
 import type { Socket } from "socket.io";
-
-import { createLogger } from "@sockethub/logger";
 import config from "./config.js";
 import { getSocket } from "./listener.js";
 import { __dirname } from "./util.js";
@@ -29,19 +32,29 @@ export interface PlatformInstanceParams {
 type EnvFormat = {
     LOG_LEVEL?: string;
     REDIS_URL: string;
+    SOCKETHUB_PLATFORM_CHILD?: string;
+    SOCKETHUB_PLATFORM_HEARTBEAT_INTERVAL_MS?: string;
+    SOCKETHUB_PLATFORM_HEARTBEAT_TIMEOUT_MS?: string;
 };
 
-interface MessageFromPlatform extends Array<string | ActivityStream> {
-    0: string;
-    1: ActivityStream;
-    2: string;
-}
+type MessageFromPlatform =
+    | ["updateActor", ActivityStream | undefined, string]
+    | ["error", string]
+    | ["heartbeat", ActivityStream]
+    | [string, ActivityStream, string?];
 
 export interface MessageFromParent extends Array<string | unknown> {
     0: string;
     1: unknown;
 }
 
+const HEARTBEAT_INTERVAL_MS = Number(
+    config.get("platformHeartbeat:intervalMs") ?? 5000,
+);
+const HEARTBEAT_TIMEOUT_MS = Number(
+    config.get("platformHeartbeat:timeoutMs") ?? 15000,
+);
+
 export default class PlatformInstance {
     id: string;
     flaggedForTermination = false;
@@ -51,16 +64,24 @@ export default class PlatformInstance {
     readonly global: boolean = false;
     readonly completedJobHandlers: Map<string, CompletedJobHandler> = new Map();
     config: PlatformConfig;
+    contextUrl?: string;
     private initialized = false;
     readonly name: string;
     process: ChildProcess;
     readonly log: Logger;
     readonly parentId: string;
     readonly sessions: Set<string> = new Set();
-    readonly sessionCallbacks: object = {
-        close: (() => new Map())(),
-        message: (() => new Map())(),
+    readonly sessionCallbacks: Record<
+        "close" | "message",
+        Map<string, (...args: Array<unknown>) => void | Promise<void>>
+    > = {
+        close: new Map(),
+        message: new Map(),
     };
+    private heartbeatLastSeen = Date.now();
+    private heartbeatMonitor?: NodeJS.Timeout;
+    private heartbeatListener?: (message: MessageFromPlatform) => void;
+    private heartbeatFailureHandled = false;
     private readonly actor?: string;
 
     constructor(params: PlatformInstanceParams) {
@@ -81,9 +102,20 @@ export default class PlatformInstance {
         if (process.env.LOG_LEVEL) {
             env.LOG_LEVEL = process.env.LOG_LEVEL;
         }
+        const heartbeatInterval = config.get("platformHeartbeat:intervalMs");
+        if (typeof heartbeatInterval !== "undefined") {
+            env.SOCKETHUB_PLATFORM_HEARTBEAT_INTERVAL_MS =
+                String(heartbeatInterval);
+        }
+        const heartbeatTimeout = config.get("platformHeartbeat:timeoutMs");
+        if (typeof heartbeatTimeout !== "undefined") {
+            env.SOCKETHUB_PLATFORM_HEARTBEAT_TIMEOUT_MS =
+                String(heartbeatTimeout);
+        }
 
         this.createQueue();
         this.initProcess(this.parentId, this.name, this.id, env);
+        this.startHeartbeatMonitor();
         this.createGetSocket();
     }
 
@@ -119,23 +151,31 @@ export default class PlatformInstance {
         this.flaggedForTermination = true;
 
         try {
+            if (this.heartbeatMonitor) {
+                clearInterval(this.heartbeatMonitor);
+                this.heartbeatMonitor = undefined;
+            }
+            if (this.heartbeatListener) {
+                this.process.removeListener("message", this.heartbeatListener);
+                this.heartbeatListener = undefined;
+            }
             this.process.removeAllListeners("close");
             this.process.unref();
             this.process.kill();
-        } catch (e) {
+        } catch (_e) {
             // needs to happen
         }
 
         try {
             await this.queue.shutdown();
             this.queue = undefined;
-        } catch (e) {
+        } catch (_e) {
             // this needs to happen
         }
 
         try {
             platformInstances.delete(this.id);
-        } catch (e) {
+        } catch (_e) {
             // this needs to happen
         }
     }
@@ -179,7 +219,9 @@ export default class PlatformInstance {
     public registerSession(sessionId: string) {
         if (!this.sessions.has(sessionId)) {
             this.sessions.add(sessionId);
-            for (const type of Object.keys(this.sessionCallbacks)) {
+            for (const type of Object.keys(this.sessionCallbacks) as Array<
+                "close" | "message"
+            >) {
                 const cb = this.callbackFunction(type, sessionId);
                 this.process.on(type, cb);
                 this.sessionCallbacks[type].set(sessionId, cb);
@@ -197,11 +239,11 @@ export default class PlatformInstance {
         return this.getSocket(sessionId).then(
             (socket: Socket) => {
                 try {
-                    // this property should never be exposed externally
-                    // biome-ignore lint/performance/noDelete: <explanation>
-                    delete msg.sessionSecret;
+                    this.toExternalPayload(msg as ActivityStream);
                 } finally {
-                    msg.context = this.name;
+                    const contextUrl =
+                        this.contextUrl ?? INTERNAL_PLATFORM_CONTEXT_URL;
+                    msg["@context"] = buildCanonicalContext(contextUrl);
                     if (
                         msg.type === "error" &&
                         typeof msg.actor === "undefined" &&
@@ -213,7 +255,7 @@ export default class PlatformInstance {
                     socket.emit("message", msg as ActivityStream);
                 }
             },
-            (err) => this.log.error(`sendToClient ${err}`),
+            (err) => this.log.error(`sendToClient ${String(err)}`),
         );
     }
 
@@ -227,6 +269,24 @@ export default class PlatformInstance {
         }
     }
 
+    /**
+     * Remove internal-only transport metadata before returning payloads to clients.
+     */
+    private toExternalPayload(payload: ActivityStream): ActivityStream {
+        const external = payload as InternalActivityStream & {
+            context?: unknown;
+        };
+        delete external.sessionSecret;
+        delete external.context;
+        if (
+            typeof external.platform !== "string" ||
+            external.platform.length === 0
+        ) {
+            external.platform = this.name;
+        }
+        return payload;
+    }
+
     // handle job results coming in on the queue from platform instances
     private async handleJobResult(
         state: string,
@@ -248,6 +308,8 @@ export default class PlatformInstance {
             payload = job.msg;
         }
 
+        payload = this.toExternalPayload(payload);
+
         // send result to client
         const callback = this.completedJobHandlers.get(job.title);
         if (callback) {
@@ -300,7 +362,9 @@ export default class PlatformInstance {
      */
     private async reportError(sessionId: string, errorMessage: string) {
         const errorObject: ActivityStream = {
-            context: this.name,
+            "@context": buildCanonicalContext(
+                this.contextUrl ?? INTERNAL_PLATFORM_CONTEXT_URL,
+            ),
             type: "error",
             actor: { id: this.actor, type: "unknown" },
             error: errorMessage,
@@ -312,7 +376,11 @@ export default class PlatformInstance {
                 await this.sendToClient(sessionId, errorObject);
             }
         } catch (err) {
-            this.log.error(`Failed to send error to client: ${err.message}`);
+            this.log.error(
+                `Failed to send error to client: ${
+                    err instanceof Error ? err.message : String(err)
+                }`,
+            );
         }
 
         this.sessions.clear();
@@ -335,8 +403,11 @@ export default class PlatformInstance {
      * @param listener
      * @param sessionId
      */
-    private callbackFunction(listener: string, sessionId: string) {
-        const funcs = {
+    private callbackFunction(listener: "close" | "message", sessionId: string) {
+        const funcs: Record<
+            "close" | "message",
+            (...args: Array<unknown>) => Promise<void>
+        > = {
             close: async (e: object) => {
                 this.log.error(`close event triggered ${this.id}: ${e}`);
                 // Check if process is still connected before attempting error reporting
@@ -354,10 +425,33 @@ export default class PlatformInstance {
             },
             message: async ([first, second, third]: MessageFromPlatform) => {
                 if (first === "updateActor") {
+                    // Internal control message: platform process is reporting a new actor id.
                     // We need to update the key to the store in order to find it in the future.
                     this.updateIdentifier(third);
-                } else if (first === "error" && typeof second === "string") {
-                    await this.reportError(sessionId, second);
+                } else if (first === "error") {
+                    // Error messages travel over IPC as plain objects; normalize to a string.
+                    let normalizedError: string;
+                    if (typeof second === "string") {
+                        normalizedError = second;
+                    } else if (
+                        second &&
+                        typeof second === "object" &&
+                        "message" in (second as Record<string, unknown>)
+                    ) {
+                        normalizedError = String(
+                            (second as Record<string, unknown>).message,
+                        );
+                    } else {
+                        try {
+                            normalizedError = JSON.stringify(second);
+                        } catch {
+                            normalizedError = String(second);
+                        }
+                    }
+                    await this.reportError(sessionId, normalizedError);
+                } else if (first === "heartbeat") {
+                    // Internal heartbeat signals are handled by the monitor listener only.
+                    return;
                 } else {
                     // treat like a message to clients
                     await this.sendToClient(sessionId, second);
@@ -366,4 +460,49 @@ export default class PlatformInstance {
         };
         return funcs[listener];
     }
+
+    private markHeartbeat() {
+        this.heartbeatLastSeen = Date.now();
+    }
+
+    private startHeartbeatMonitor() {
+        if (
+            !Number.isFinite(HEARTBEAT_INTERVAL_MS) ||
+            HEARTBEAT_INTERVAL_MS <= 0 ||
+            !Number.isFinite(HEARTBEAT_TIMEOUT_MS) ||
+            HEARTBEAT_TIMEOUT_MS <= 0
+        ) {
+            return;
+        }
+        if (!this.process?.on) {
+            return;
+        }
+        // Track last heartbeat to detect hung platform processes.
+        this.heartbeatLastSeen = Date.now();
+        this.heartbeatListener = (message: MessageFromPlatform) => {
+            if (Array.isArray(message) && message[0] === "heartbeat") {
+                this.markHeartbeat();
+            }
+        };
+        this.process.on("message", this.heartbeatListener);
+        this.heartbeatMonitor = setInterval(() => {
+            // Avoid double-handling once shutdown starts or a timeout was already handled.
+            if (this.flaggedForTermination || this.heartbeatFailureHandled) {
+                return;
+            }
+            if (!this.process?.connected) {
+                return;
+            }
+            const elapsed = Date.now() - this.heartbeatLastSeen;
+            if (elapsed > HEARTBEAT_TIMEOUT_MS) {
+                this.heartbeatFailureHandled = true;
+                this.log.error(
+                    `heartbeat timeout for ${this.id} after ${elapsed}ms`,
+                );
+                // The child is unresponsive; mark for termination and trigger shutdown.
+                this.flaggedForTermination = true;
+                void this.shutdown();
+            }
+        }, HEARTBEAT_INTERVAL_MS);
+    }
 }

package/src/platform.test.ts

@@ -42,7 +42,11 @@ describe("platform.ts credential handling", () => {
 
         validCredentials = {
             type: "credentials",
-            context: "xmpp",
+            "@context": [
+                "https://www.w3.org/ns/activitystreams",
+                "https://sockethub.org/ns/context/v1.jsonld",
+                "https://sockethub.org/ns/context/platform/xmpp/v1.jsonld",
+            ],
             actor: {
                 id: "testuser@localhost",
                 type: "person",
@@ -75,7 +79,12 @@ describe("platform.ts credential handling", () => {
             title: "xmpp-job-1",
             msg: {
                 type: "connect",
-                context: "xmpp",
+                "@context": [
+                    "https://www.w3.org/ns/activitystreams",
+                    "https://sockethub.org/ns/context/v1.jsonld",
+                    "https://sockethub.org/ns/context/platform/xmpp/v1.jsonld",
+                ],
+                platform: "xmpp",
                 actor: { id: "testuser@localhost", type: "person" },
                 sessionSecret: "secret123",
             },

package/src/platform.ts

@@ -10,13 +10,13 @@
  * it and sockethub will start up another process. This ensures memory safety.
  */
 import { crypto, getPlatformId } from "@sockethub/crypto";
+import type { JobHandler } from "@sockethub/data-layer";
 import {
     CredentialsStore,
     type JobDataDecrypted,
     JobWorker,
 } from "@sockethub/data-layer";
-import type { JobHandler } from "@sockethub/data-layer";
-import { type Logger, createLogger, setLoggerContext } from "@sockethub/logger";
+import { createLogger, type Logger, setLoggerContext } from "@sockethub/logger";
 import type {
     ActivityStream,
     CredentialsObject,
@@ -25,6 +25,10 @@ import type {
     PlatformInterface,
     PlatformSession,
 } from "@sockethub/schemas";
+import {
+    buildCanonicalContext,
+    INTERNAL_PLATFORM_CONTEXT_URL,
+} from "@sockethub/schemas";
 import config from "./config";
 
 // Simple wrapper function to help with testing
@@ -53,7 +57,16 @@ async function startPlatformProcess() {
 
     // conditionally initialize sentry
     let sentry: { readonly reportError: (err: Error) => void } = {
-        reportError: (err: Error) => {},
+        reportError: (err: Error) => {
+            logger.debug(
+                "Sentry not configured; error not reported to Sentry",
+                {
+                    error: err,
+                    errorMessage: err?.message ?? String(err),
+                    errorStack: err?.stack,
+                },
+            );
+        },
     };
     (async () => {
         if (config.get("sentry:dsn")) {
@@ -103,16 +116,43 @@ async function startPlatformProcess() {
         return p as PlatformInterface;
     })();
 
+    type PlatformHandlerWithCredentials = (
+        msg: ActivityStream,
+        credentials: CredentialsObject,
+        cb: PlatformCallback,
+    ) => void;
+    type PlatformHandler = (msg: ActivityStream, cb: PlatformCallback) => void;
+    function getPlatformHandler(
+        instance: PlatformInterface,
+        name: string,
+    ): PlatformHandlerWithCredentials | PlatformHandler | undefined {
+        const candidate = (
+            instance as PlatformInterface & Record<string, unknown>
+        )[name];
+        return typeof candidate === "function"
+            ? (candidate as PlatformHandlerWithCredentials | PlatformHandler)
+            : undefined;
+    }
+
+    const heartbeatIntervalMs = Number(
+        config.get("platformHeartbeat:intervalMs") ?? 5000,
+    );
+    let heartbeatTimer: NodeJS.Timeout | undefined;
+
     /**
-     * Safely send error message to parent process, handling IPC channel closure
+     * Safely send message to parent process, handling IPC channel closure
      */
-    function safeProcessSend(message: [string, string]) {
+    function safeProcessSend(message: [string, unknown]) {
         if (process.send && process.connected) {
             try {
                 process.send(message);
             } catch (ipcErr) {
                 console.error(
-                    `Failed to report error via IPC: ${ipcErr.message}`,
+                    `Failed to report error via IPC: ${
+                        ipcErr instanceof Error
+                            ? ipcErr.message
+                            : String(ipcErr)
+                    }`,
                 );
             }
         } else {
@@ -120,6 +160,34 @@ async function startPlatformProcess() {
         }
     }
 
+    function startHeartbeat() {
+        if (!Number.isFinite(heartbeatIntervalMs) || heartbeatIntervalMs <= 0) {
+            return;
+        }
+        if (heartbeatTimer) {
+            return;
+        }
+        heartbeatTimer = setInterval(() => {
+            safeProcessSend([
+                "heartbeat",
+                {
+                    type: "heartbeat",
+                    "@context": buildCanonicalContext(
+                        INTERNAL_PLATFORM_CONTEXT_URL,
+                    ),
+                    actor: {
+                        id: "sockethub",
+                        type: "platform",
+                    },
+                    object: {
+                        type: "heartbeat",
+                        timestamp: Date.now(),
+                    },
+                } as ActivityStream,
+            ]);
+        }, heartbeatIntervalMs);
+    }
+
     /**
      * Type guard to check if a platform is persistent and has credentialsHash.
      */
@@ -157,6 +225,12 @@ async function startPlatformProcess() {
         process.exit(1);
     });
 
+    process.once("exit", () => {
+        if (heartbeatTimer) {
+            clearInterval(heartbeatTimer);
+        }
+    });
+
     /**
      * Incoming messages from the worker to this platform. Data is an array, the first property is the
      * method to call, the rest are params.
@@ -170,6 +244,7 @@ async function startPlatformProcess() {
             parentSecret1 = parentSecret;
             parentSecret2 = parentSecret3;
             await startQueueListener();
+            startHeartbeat();
         } else {
             throw new Error("received unknown command from parent thread");
         }
@@ -202,7 +277,6 @@ async function startPlatformProcess() {
                         url: redisUrl,
                     },
                 );
-                // biome-ignore lint/performance/noDelete: <explanation>
                 delete job.msg.sessionSecret;
 
                 let jobCallbackCalled = false;
@@ -223,10 +297,12 @@ async function startPlatformProcess() {
                         try {
                             errMsg = err.toString();
                         } catch (err) {
-                            errMsg = err;
+                            errMsg = err instanceof Error ? err : String(err);
                         }
-                        sentry.reportError(new Error(errMsg as string));
-                        reject(new Error(errMsg as string));
+                        const errorMessage =
+                            errMsg instanceof Error ? errMsg.message : errMsg;
+                        sentry.reportError(new Error(errorMessage));
+                        reject(new Error(errorMessage));
                     } else {
                         jobLog.debug(`completed ${job.title} ${job.msg.type}`);
 
@@ -280,7 +356,21 @@ async function startPlatformProcess() {
                             };
 
                             // Proceed with platform method call
-                            platform[job.msg.type](
+                            const handler = getPlatformHandler(
+                                platform,
+                                job.msg.type,
+                            );
+                            if (!handler) {
+                                doneCallback(
+                                    new Error(
+                                        `platform method ${job.msg.type} not available`,
+                                    ),
+                                    null,
+                                );
+                                return;
+                            }
+                            (handler as PlatformHandlerWithCredentials).call(
+                                platform,
                                 job.msg,
                                 credentials,
                                 wrappedCallback,
@@ -288,7 +378,7 @@ async function startPlatformProcess() {
                         })
                         .catch((err) => {
                             // Credential store error (invalid/missing credentials)
-                            jobLog.error(`credential error ${err.toString()}`);
+                            jobLog.error(`credential error ${String(err)}`);
 
                             /**
                              * Critical distinction: handle credential errors differently based on platform state.
@@ -315,11 +405,20 @@ async function startPlatformProcess() {
                              */
                             if (platform.isInitialized()) {
                                 // Platform already running - reject job only, preserve platform instance
-                                doneCallback(err, null);
+                                doneCallback(
+                                    err instanceof Error
+                                        ? err
+                                        : new Error(String(err)),
+                                    null,
+                                );
                             } else {
                                 // Platform not initialized - terminate platform process
-                                sentry.reportError(err);
-                                reject(err);
+                                const error =
+                                    err instanceof Error
+                                        ? err
+                                        : new Error(String(err));
+                                sentry.reportError(error);
+                                reject(error);
                             }
                         });
                 } else if (
@@ -333,11 +432,28 @@ async function startPlatformProcess() {
                     );
                 } else {
                     try {
-                        platform[job.msg.type](job.msg, doneCallback);
+                        const handler = getPlatformHandler(
+                            platform,
+                            job.msg.type,
+                        );
+                        if (!handler) {
+                            throw new Error(
+                                `platform method ${job.msg.type} not available`,
+                            );
+                        }
+                        (handler as PlatformHandler).call(
+                            platform,
+                            job.msg,
+                            doneCallback,
+                        );
                     } catch (err) {
-                        jobLog.error(`platform call failed ${err.toString()}`);
-                        sentry.reportError(err);
-                        reject(err);
+                        const error =
+                            err instanceof Error ? err : new Error(String(err));
+                        jobLog.error(
+                            `platform call failed ${error.toString()}`,
+                        );
+                        sentry.reportError(error);
+                        reject(error);
                     }
                 }
             });

package/src/process-manager.ts

@@ -2,9 +2,9 @@ import { getPlatformId } from "@sockethub/crypto";
 
 import type { IInitObject } from "./bootstrap/init.js";
 import PlatformInstance, {
-    platformInstances,
-    type PlatformInstanceParams,
     type MessageFromParent,
+    type PlatformInstanceParams,
+    platformInstances,
 } from "./platform-instance.js";
 
 class ProcessManager {
@@ -41,6 +41,7 @@ class ProcessManager {
             pi = this.ensureProcess(platform);
         }
         pi.config = platformDetails.config;
+        pi.contextUrl = platformDetails.contextUrl;
         return pi;
     }
 
@@ -74,15 +75,40 @@ class ProcessManager {
         actor?: string,
     ): PlatformInstance {
         const identifier = getPlatformId(platform, actor);
+        const existing = platformInstances.get(identifier);
         const platformInstance =
-            platformInstances.get(identifier) ||
-            this.createPlatformInstance(identifier, platform, actor);
+            existing && this.isProcessAlive(existing)
+                ? existing
+                : this.createPlatformInstance(identifier, platform, actor);
+        if (existing && existing !== platformInstance) {
+            void existing.shutdown();
+        }
         if (sessionId) {
             platformInstance.registerSession(sessionId);
         }
         platformInstances.set(identifier, platformInstance);
         return platformInstance;
     }
+
+    private isProcessAlive(platformInstance: PlatformInstance): boolean {
+        const pid = platformInstance.process?.pid;
+        if (!pid) {
+            return false;
+        }
+        if (platformInstance.process.exitCode !== null) {
+            return false;
+        }
+        try {
+            process.kill(pid, 0);
+            return true;
+        } catch (error) {
+            const err = error as NodeJS.ErrnoException;
+            if (err && err.code === "EPERM") {
+                return true;
+            }
+            return false;
+        }
+    }
 }
 
 export default ProcessManager;