@sockethub/platform-xmpp 5.0.0-alpha.10 → 5.0.0-alpha.11

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sockethub/platform-xmpp",
   "description": "A sockethub platform module implementing XMPP functionality",
-  "version": "5.0.0-alpha.10",
+  "version": "5.0.0-alpha.11",
   "private": false,
   "type": "module",
   "author": "Nick Jennings <nick@silverbucket.net>",
@@ -42,24 +42,25 @@
   "scripts": {
     "build": "bun build src/index.js --outdir dist --target node --format esm --sourcemap=external",
     "clean": "rm -rf dist",
+    "clean:deps": "rm -rf node_modules",
     "doc": "jsdoc2md --no-gfm --heading-depth 1 src/index.js > API.md"
   },
   "dependencies": {
     "@xmpp/client": "^0.13.6"
   },
   "devDependencies": {
-    "@sockethub/schemas": "^3.0.0-alpha.10",
+    "@sockethub/schemas": "^3.0.0-alpha.11",
     "@xmpp/xml": "^0.13.2",
     "jsdoc-to-markdown": "^8.0.3",
     "sinon": "^17.0.2"
   },
   "peerDependencies": {
-    "@sockethub/server": "^5.0.0-alpha.10"
+    "@sockethub/server": "^5.0.0-alpha.11"
   },
   "peerDependenciesMeta": {
     "@sockethub/server": {
       "optional": true
     }
   },
-  "gitHead": "8e1abf116b2a6b57d33c6e1a4af9143870517bae"
+  "gitHead": "c243fa9e76c688ce5ffcf524400b1dd27dcce615"
 }

package/src/incoming-handlers.js

@@ -63,7 +63,9 @@ export class IncomingHandlers {
             return;
         }
 
-        this.session.debug("received close event with no handler specified");
+        this.session.log.debug(
+            "received close event with no handler specified",
+        );
         if (this.session.actor && this.session.sendToClient) {
             this.session.sendToClient({
                 context: "xmpp",
@@ -71,7 +73,7 @@ export class IncomingHandlers {
                 actor: this.session.actor,
                 target: this.session.actor,
             });
-            this.session.debug(
+            this.session.log.debug(
                 `**** xmpp this.session.for ${this.session.actor.id} closed`,
             );
         }
@@ -95,7 +97,7 @@ export class IncomingHandlers {
                 },
             });
         } catch (e) {
-            this.session.debug("*** XMPP ERROR (rl catch): ", e);
+            this.session.log.debug("*** XMPP ERROR (rl catch): ", e);
         }
     }
 
@@ -120,14 +122,14 @@ export class IncomingHandlers {
         } else {
             obj.actor.name = stanza.attrs.from.split("/")[1];
         }
-        this.session.debug(
+        this.session.log.debug(
             `received contact presence update from ${stanza.attrs.from}`,
         );
         this.session.sendToClient(obj);
     }
 
     subscribe(to, from, name) {
-        this.session.debug(`received subscribe request from ${from}`);
+        this.session.log.debug(`received subscribe request from ${from}`);
         const actor = { id: from, type: "person" };
         if (name) {
             actor.name = name;
@@ -141,7 +143,7 @@ export class IncomingHandlers {
     }
 
     // unsubscribe(from) {
-    //   this.session.debug('received unsubscribe request from ' + from);
+    //   this.session.log.debug('received unsubscribe request from ' + from);
     //   this.session.sendToClient({
     //     type: "remove-friend",
     //     actor: { id: from },
@@ -262,7 +264,7 @@ export class IncomingHandlers {
     }
 
     online() {
-        this.session.debug("online");
+        this.session.log.debug("online");
     }
 
     /**
@@ -281,7 +283,7 @@ export class IncomingHandlers {
                 stanza.attrs.id === "muc_id" &&
                 stanza.attrs.type === "result"
             ) {
-                this.session.debug("got room attendance list");
+                this.session.log.debug("got room attendance list");
                 return this.notifyRoomAttendance(stanza);
             }
 
@@ -293,7 +295,7 @@ export class IncomingHandlers {
                     if (!entries.hasOwn(e)) {
                         continue;
                     }
-                    this.session.debug("STANZA ATTRS: ", entries[e].attrs);
+                    this.session.log.debug("STANZA ATTRS: ", entries[e].attrs);
                     if (entries[e].attrs.subscription === "both") {
                         this.session.sendToClient({
                             context: "xmpp",
@@ -342,7 +344,7 @@ export class IncomingHandlers {
                 }
             }
         } else {
-            this.session.debug(`got XMPP unknown stanza... ${stanza}`);
+            this.session.log.debug(`got XMPP unknown stanza... ${stanza}`);
         }
     }
 }

package/src/incoming-handlers.test.js

@@ -15,7 +15,7 @@ describe("Incoming handlers", () => {
             sendToClient = sinon.fake();
             ih = new IncomingHandlers({
                 sendToClient: sendToClient,
-                debug: sinon.fake(),
+                log: { debug: sinon.fake() },
             });
         });
 
@@ -43,11 +43,16 @@ describe("Incoming handlers", () => {
 
         it("close() should handle session without actor gracefully", () => {
             const sendToClient = sinon.fake();
-            const debug = sinon.fake();
+            const log = {
+                error: sinon.fake(),
+                warn: sinon.fake(),
+                info: sinon.fake(),
+                debug: sinon.fake(),
+            };
             
             const ih = new IncomingHandlers({
                 sendToClient: sendToClient,
-                debug: debug,
+                log: log,
                 actor: undefined,
                 connection: undefined
             });
@@ -55,17 +60,22 @@ describe("Incoming handlers", () => {
             // This should not throw an error
             expect(() => ih.close()).not.toThrow();
             
-            // Should still call debug
-            sinon.assert.calledWith(debug, "received close event with no handler specified");
+            // Should still call log.debug
+            sinon.assert.calledWith(log.debug, "received close event with no handler specified");
         });
 
         it("close() should handle session without connection gracefully", () => {
             const sendToClient = sinon.fake();
-            const debug = sinon.fake();
+            const log = {
+                error: sinon.fake(),
+                warn: sinon.fake(),
+                info: sinon.fake(),
+                debug: sinon.fake(),
+            };
             
             const ih = new IncomingHandlers({
                 sendToClient: sendToClient,
-                debug: debug,
+                log: log,
                 actor: { id: "test@example.com" },
                 connection: undefined
             });
@@ -76,11 +86,16 @@ describe("Incoming handlers", () => {
 
         it("close() should handle session with invalid connection gracefully", () => {
             const sendToClient = sinon.fake();
-            const debug = sinon.fake();
+            const log = {
+                error: sinon.fake(),
+                warn: sinon.fake(),
+                info: sinon.fake(),
+                debug: sinon.fake(),
+            };
             
             const ih = new IncomingHandlers({
                 sendToClient: sendToClient,
-                debug: debug,
+                log: log,
                 actor: { id: "test@example.com" },
                 connection: { disconnect: null } // invalid disconnect method
             });

package/src/index.js

@@ -40,10 +40,10 @@ export default class XMPP {
         this.config = {
             connectTimeoutMs: 10000,
             persist: true,
-            initialized: false,
             requireCredentials: ["connect"],
         };
-        this.debug = session.debug;
+        this.__initialized = false; // Private state for initialization tracking
+        this.log = session.log;
         this.sendToClient = session.sendToClient;
         this.createClient();
         this.createXml();
@@ -61,15 +61,15 @@ export default class XMPP {
      * @param {boolean} stopReconnection - If true, stop automatic reconnection
      */
     __markDisconnected(stopReconnection = false) {
-        this.debug(`marking client as disconnected for ${this.id}`);
+        this.log.debug(`marking client as disconnected for ${this.id}`);
 
         if (stopReconnection && this.__client) {
-            this.debug(`stopping automatic reconnection for ${this.id}`);
+            this.log.debug(`stopping automatic reconnection for ${this.id}`);
             this.__client.stop();
         }
 
         this.__client = undefined;
-        this.config.initialized = false;
+        this.__initialized = false;
     }
 
     /**
@@ -132,7 +132,7 @@ export default class XMPP {
                 this.__client.status === "online"
             );
         } catch (err) {
-            this.debug("Error checking client connection status:", err);
+            this.log.debug("Error checking client connection status:", err);
             return false;
         }
     }
@@ -183,6 +183,17 @@ export default class XMPP {
         return PlatformSchema;
     }
 
+    /**
+     * Returns whether the platform is ready to handle jobs.
+     * For XMPP, this means we have successfully connected to the server.
+     * During temporary network interruptions with automatic reconnection,
+     * remains true to allow queued jobs to retry rather than fail.
+     * @returns {boolean} true if ready to handle jobs
+     */
+    isInitialized() {
+        return this.__initialized;
+    }
+
     /**
      * Connect to the XMPP server.
      *
@@ -205,15 +216,17 @@ export default class XMPP {
      */
     connect(job, credentials, done) {
         if (this.__isClientConnected()) {
-            this.debug(`client connection already exists for ${job.actor.id}`);
-            this.config.initialized = true;
+            this.log.debug(
+                `client connection already exists for ${job.actor.id}`,
+            );
+            this.__initialized = true;
             return done();
         }
-        this.debug(`connect() called for ${job.actor.id}`);
+        this.log.debug(`connect() called for ${job.actor.id}`);
 
         // Log credential processing
         const xmppCreds = utils.buildXmppCredentials(credentials);
-        this.debug(
+        this.log.debug(
             `building XMPP credentials for ${job.actor.id}:`,
             JSON.stringify({
                 service: xmppCreds.service,
@@ -224,26 +237,59 @@ export default class XMPP {
         );
 
         // Log before client creation
-        this.debug(`creating XMPP client for ${job.actor.id}`);
+        this.log.debug(`creating XMPP client for ${job.actor.id}`);
 
         try {
             this.__client = this.__clientConstructor({
                 ...xmppCreds,
                 ...{ timeout: this.config.connectTimeoutMs, tls: false },
             });
-            this.debug(`XMPP client created successfully for ${job.actor.id}`);
+            this.log.debug(
+                `XMPP client created successfully for ${job.actor.id}`,
+            );
         } catch (err) {
-            this.debug(`XMPP client creation failed for ${job.actor.id}:`, err);
+            this.log.debug(
+                `XMPP client creation failed for ${job.actor.id}:`,
+                err,
+            );
             return done(`client creation failed: ${err.message}`);
         }
 
         this.__client.on("offline", () => {
-            this.debug(`offline event received for ${job.actor.id}`);
-            this.__markDisconnected();
+            this.log.debug(`offline event received for ${job.actor.id}`);
+            // If we were never initialized, mark as disconnected (connection failed)
+            // If we were previously initialized, keep state (will auto-reconnect)
+            // This preserves initialized state during brief network interruptions
+            // while properly handling initial connection failures
+            if (!this.__initialized) {
+                this.log.debug(
+                    `offline during initial connection for ${job.actor.id}`,
+                );
+                this.__markDisconnected();
+            } else {
+                this.log.debug(
+                    `offline after successful connection for ${job.actor.id}, will auto-reconnect`,
+                );
+            }
         });
 
         this.__client.on("error", (err) => {
-            this.debug(
+            // Internal code errors (TypeError, ReferenceError, etc.) indicate bugs
+            // in our code. These should crash the platform process immediately
+            // as we can't trust the state after such errors.
+            if (
+                err instanceof TypeError ||
+                err instanceof ReferenceError ||
+                err instanceof SyntaxError
+            ) {
+                this.log.error(
+                    `FATAL: Internal code error in XMPP platform: ${err.toString()}`,
+                );
+                this.log.error(err.stack);
+                process.exit(1);
+            }
+
+            this.log.debug(
                 `network error event for ${job.actor.id}:${err.toString()}`,
             );
 
@@ -256,9 +302,9 @@ export default class XMPP {
             };
 
             if (errorType === "RECOVERABLE") {
-                // Clean up state but allow reconnection
-                this.__markDisconnected(false);
-
+                // For recoverable errors, keep initialized=true and let the client
+                // auto-reconnect. Don't call stop() or clear the client reference.
+                // This allows queued jobs to wait for reconnection instead of failing.
                 as.error = `Connection lost: ${err.toString()}. Attempting automatic reconnection...`;
                 as.object = {
                     type: "connect",
@@ -266,7 +312,7 @@ export default class XMPP {
                     condition: err.condition || "network",
                 };
             } else {
-                // Clean up state and stop reconnection
+                // On unrecoverable errors, mark as uninitialized and stop reconnection
                 this.__markDisconnected(true);
 
                 as.error = `Connection failed: ${err.toString()}. Manual reconnection required.`;
@@ -280,10 +326,10 @@ export default class XMPP {
         });
 
         this.__client.on("online", () => {
-            this.debug(`online event received for ${job.actor.id}`);
+            this.log.debug(`online event received for ${job.actor.id}`);
         });
 
-        this.debug(`starting XMPP client connection for ${job.actor.id}`);
+        this.log.debug(`starting XMPP client connection for ${job.actor.id}`);
         const startTime = Date.now();
 
         this.__client
@@ -291,16 +337,16 @@ export default class XMPP {
             .then(() => {
                 // connected
                 const duration = Date.now() - startTime;
-                this.debug(
+                this.log.debug(
                     `connection successful for ${job.actor.id} after ${duration}ms`,
                 );
-                this.config.initialized = true;
+                this.__initialized = true;
                 this.__registerHandlers();
                 return done();
             })
             .catch((err) => {
                 const duration = Date.now() - startTime;
-                this.debug(
+                this.log.debug(
                     `connection failed for ${job.actor.id} after ${duration}ms:`,
                     {
                         error: err,
@@ -339,7 +385,7 @@ export default class XMPP {
      * }
      */
     async join(job, done) {
-        this.debug(
+        this.log.debug(
             `sending join from ${job.actor.id} to ` +
                 `${job.target.id}/${job.actor.name}`,
         );
@@ -382,7 +428,7 @@ export default class XMPP {
      * }
      */
     leave(job, done) {
-        this.debug(
+        this.log.debug(
             `sending leave from ${job.actor.id} to ` +
                 `${job.target.id}/${job.actor.name}`,
         );
@@ -452,7 +498,7 @@ export default class XMPP {
      *
      */
     send(job, done) {
-        this.debug(`send() called for ${job.actor.id}`);
+        this.log.debug(`send() called for ${job.actor.id}`);
         // send message
         const message = this.__xml(
             "message",
@@ -496,7 +542,7 @@ export default class XMPP {
      * }
      */
     update(job, done) {
-        this.debug(`update() called for ${job.actor.id}`);
+        this.log.debug(`update() called for ${job.actor.id}`);
         const props = {};
         const show = {};
         const status = {};
@@ -510,7 +556,7 @@ export default class XMPP {
                 status.status = job.object.content;
             }
             // setting presence
-            this.debug(`setting presence: ${job.object.presence}`);
+            this.log.debug(`setting presence: ${job.object.presence}`);
             this.__client
                 .send(this.__xml("presence", props, show, status))
                 .then(done);
@@ -540,7 +586,7 @@ export default class XMPP {
      * }
      */
     "request-friend"(job, done) {
-        this.debug(`request-friend() called for ${job.actor.id}`);
+        this.log.debug(`request-friend() called for ${job.actor.id}`);
         this.__client
             .send(
                 this.__xml("presence", {
@@ -572,7 +618,7 @@ export default class XMPP {
      * }
      */
     "remove-friend"(job, done) {
-        this.debug(`remove-friend() called for ${job.actor.id}`);
+        this.log.debug(`remove-friend() called for ${job.actor.id}`);
         this.__client
             .send(
                 this.__xml("presence", {
@@ -604,7 +650,7 @@ export default class XMPP {
      * }
      */
     "make-friend"(job, done) {
-        this.debug(`make-friend() called for ${job.actor.id}`);
+        this.log.debug(`make-friend() called for ${job.actor.id}`);
         this.__client
             .send(
                 this.__xml("presence", {
@@ -664,7 +710,9 @@ export default class XMPP {
      *  }
      */
     query(job, done) {
-        this.debug(`sending query from ${job.actor.id} for ${job.target.id}`);
+        this.log.debug(
+            `sending query from ${job.actor.id} for ${job.target.id}`,
+        );
         this.__client
             .send(
                 this.__xml(
@@ -700,7 +748,7 @@ export default class XMPP {
      *  }
      */
     disconnect(job, done) {
-        this.debug("disconnecting");
+        this.log.debug("disconnecting");
         this.cleanup(done);
     }
 
@@ -710,8 +758,8 @@ export default class XMPP {
      * @param {function} done - callback when complete
      */
     cleanup(done) {
-        this.debug("cleanup");
-        this.config.initialized = false;
+        this.log.debug("cleanup");
+        this.__initialized = false;
         this.__client.stop();
         done();
     }

package/src/index.test.js

@@ -185,7 +185,12 @@ describe("XMPP", () => {
 
         xp = new TestXMPP({
             id: actor,
-            debug: sinon.fake(),
+            log: {
+                error: sinon.fake(),
+                warn: sinon.fake(),
+                info: sinon.fake(),
+                debug: sinon.fake(),
+            },
             sendToClient: sinon.fake(),
         });
     });
@@ -240,6 +245,107 @@ describe("XMPP", () => {
         });
     });
 
+    describe("Error handling", () => {
+        let processExitStub;
+
+        beforeEach(() => {
+            // Stub process.exit to prevent test process from exiting
+            processExitStub = sinon.stub(process, "exit");
+        });
+
+        afterEach(() => {
+            processExitStub.restore();
+        });
+
+        it("terminates process on TypeError (internal code error)", (done) => {
+            xp.connect(job.connect, credentials, () => {
+                // Get the error event handler that was registered
+                const errorHandler = clientObjectFake.on.getCalls().find(
+                    (call) => call.args[0] === "error",
+                ).args[1];
+
+                // Simulate a TypeError (internal code error)
+                const typeError = new TypeError("this.session.debug is not a function");
+                errorHandler(typeError);
+
+                // Verify process.exit(1) was called
+                sinon.assert.calledOnce(processExitStub);
+                sinon.assert.calledWith(processExitStub, 1);
+
+                // Verify error was logged
+                sinon.assert.called(xp.log.error);
+                expect(
+                    xp.log.error
+                        .getCalls()
+                        .some((call) =>
+                            call.args[0].includes("FATAL: Internal code error"),
+                        ),
+                ).toBeTrue();
+
+                done();
+            });
+        });
+
+        it("terminates process on ReferenceError (internal code error)", (done) => {
+            xp.connect(job.connect, credentials, () => {
+                const errorHandler = clientObjectFake.on.getCalls().find(
+                    (call) => call.args[0] === "error",
+                ).args[1];
+
+                const refError = new ReferenceError("foo is not defined");
+                errorHandler(refError);
+
+                sinon.assert.calledOnce(processExitStub);
+                sinon.assert.calledWith(processExitStub, 1);
+                sinon.assert.called(xp.log.error);
+
+                done();
+            });
+        });
+
+        it("does NOT terminate process on network errors (recoverable)", (done) => {
+            xp.connect(job.connect, credentials, () => {
+                const errorHandler = clientObjectFake.on.getCalls().find(
+                    (call) => call.args[0] === "error",
+                ).args[1];
+
+                // Simulate a network error
+                const networkError = new Error("ECONNRESET");
+                networkError.code = "ECONNRESET";
+                errorHandler(networkError);
+
+                // Should NOT call process.exit for network errors
+                sinon.assert.notCalled(processExitStub);
+
+                // Should send error to client instead
+                sinon.assert.called(xp.sendToClient);
+
+                done();
+            });
+        });
+
+        it("does NOT terminate process on XMPP protocol errors (non-recoverable)", (done) => {
+            xp.connect(job.connect, credentials, () => {
+                const errorHandler = clientObjectFake.on.getCalls().find(
+                    (call) => call.args[0] === "error",
+                ).args[1];
+
+                // Simulate an XMPP protocol error (e.g., auth failure)
+                const authError = new Error("not-authorized");
+                authError.condition = "not-authorized";
+                errorHandler(authError);
+
+                // Should NOT call process.exit for XMPP errors
+                sinon.assert.notCalled(processExitStub);
+
+                // Should send error to client and mark disconnected
+                sinon.assert.called(xp.sendToClient);
+
+                done();
+            });
+        });
+    });
+
     describe("Platform functionality", () => {
         beforeEach((done) => {
             xp.connect(job.join, credentials, () => done());
@@ -484,9 +590,9 @@ describe("XMPP", () => {
 
         describe("#cleanup", () => {
             it("calls client.stop", (done) => {
-                expect(xp.config.initialized).toEqual(true);
+                expect(xp.isInitialized()).toEqual(true);
                 xp.cleanup(() => {
-                    expect(xp.config.initialized).toEqual(false);
+                    expect(xp.isInitialized()).toEqual(false);
                     sinon.assert.calledOnce(xp.__client.stop);
                     done()
                 });