@sockethub/platform-irc 4.0.0-alpha.10 → 4.0.0-alpha.12

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sockethub/platform-irc",
   "description": "A sockethub platform module implementing IRC functionality",
-  "version": "4.0.0-alpha.10",
+  "version": "4.0.0-alpha.12",
   "private": false,
   "author": "Nick Jennings <nick@silverbucket.net>",
   "license": "LGPL-3.0+",
@@ -42,24 +42,25 @@
   "scripts": {
     "build": "bun build src/index.ts --outdir dist --target node --format esm --sourcemap=external",
     "clean": "rm -rf dist",
+    "clean:deps": "rm -rf node_modules",
     "doc": "typedoc --options typedoc.json"
   },
   "dependencies": {
-    "@sockethub/irc2as": "^4.0.0-alpha.10",
+    "@sockethub/irc2as": "^4.0.0-alpha.12",
     "irc-socket-sasl": "^4.0.0"
   },
   "devDependencies": {
-    "@sockethub/schemas": "^3.0.0-alpha.10",
+    "@sockethub/schemas": "^3.0.0-alpha.12",
     "@types/bun": "latest",
     "typedoc": "^0.28.14"
   },
   "peerDependencies": {
-    "@sockethub/server": "^5.0.0-alpha.10"
+    "@sockethub/server": "^5.0.0-alpha.12"
   },
   "peerDependenciesMeta": {
     "@sockethub/server": {
       "optional": true
     }
   },
-  "gitHead": "8e1abf116b2a6b57d33c6e1a4af9143870517bae"
+  "gitHead": "f039dab3c3f67cbbf204476fc397532e973f82a8"
 }

package/src/ambient.d.ts

@@ -0,0 +1,35 @@
+declare module "irc-socket-sasl" {
+    export interface IrcSocketInstance {
+        end?: () => void;
+        raw: (message: string) => void;
+        once: (
+            event: string,
+            handler: (...args: Array<unknown>) => void,
+        ) => void;
+        on: (event: string, handler: (...args: Array<unknown>) => void) => void;
+        connect: () => Promise<unknown>;
+    }
+    const IrcSocket: new (...args: Array<unknown>) => IrcSocketInstance;
+    export default IrcSocket;
+}
+
+declare module "@sockethub/irc2as" {
+    interface IrcToActivityStreamsOptions {
+        server: string;
+        contexts?: Array<string>;
+        context?: string;
+    }
+
+    export class IrcToActivityStreams {
+        constructor(options: IrcToActivityStreamsOptions);
+        input(data: unknown): void;
+        events: {
+            on(event: string, handler: (...args: Array<unknown>) => void): void;
+        };
+    }
+}
+
+declare module "./octal-hack.js" {
+    const buildCommand: (input: string) => string;
+    export default buildCommand;
+}

package/src/index.test.data.ts

@@ -4,7 +4,11 @@ export default [
         valid: true,
         type: "credentials",
         input: {
-            context: "irc",
+            "@context": [
+                "https://www.w3.org/ns/activitystreams",
+                "https://sockethub.org/ns/context/v1.jsonld",
+                "https://sockethub.org/ns/context/platform/irc/v1.jsonld",
+            ],
             type: "credentials",
             actor: {
                 id: "sh-9K3Vk@irc.freenode.net",
@@ -33,7 +37,11 @@ export default [
         valid: false,
         type: "credentials",
         input: {
-            context: "irc",
+            "@context": [
+                "https://www.w3.org/ns/activitystreams",
+                "https://sockethub.org/ns/context/v1.jsonld",
+                "https://sockethub.org/ns/context/platform/irc/v1.jsonld",
+            ],
             type: "credentials",
             actor: {
                 id: "sh-9K3Vk@irc.freenode.net",

package/src/index.test.ts

@@ -3,7 +3,9 @@ import { beforeEach, describe, expect, it } from "bun:test";
 import {
     type ActivityStream,
     type CredentialsObject,
+    addPlatformContext,
     addPlatformSchema,
+    buildCanonicalContext,
     getPlatformSchema,
     validateCredentials,
     validatePlatformSchema,
@@ -30,8 +32,12 @@ const targetRoom = {
     name: "#a-room",
 };
 
+const IRC_CONTEXT = buildCanonicalContext(
+    "https://sockethub.org/ns/context/platform/irc/v1.jsonld",
+);
+
 const validCredentials = {
-    context: "irc",
+    "@context": IRC_CONTEXT,
     type: "credentials",
     actor: actor,
     object: {
@@ -45,7 +51,12 @@ describe("Initialize IRC Platform", () => {
     let platform;
     beforeEach(() => {
         platform = new IRC({
-            debug: () => {},
+            log: {
+                error: () => {},
+                warn: () => {},
+                info: () => {},
+                debug: () => {},
+            },
             updateActor: function async() {
                 return Promise.resolve();
             },
@@ -64,6 +75,7 @@ describe("Initialize IRC Platform", () => {
         if (!getPlatformSchema("irc/credentials")) {
             addPlatformSchema(platform.schema.credentials, `irc/credentials`);
         }
+        addPlatformContext("irc", platform.schema.contextUrl);
     });
 
     it("lists required types enum", () => {
@@ -84,7 +96,6 @@ describe("Initialize IRC Platform", () => {
             connectTimeoutMs: 30000,
             persist: true,
             requireCredentials: ["connect", "update"],
-            initialized: false,
         });
     });
 
@@ -98,25 +109,30 @@ describe("Initialize IRC Platform", () => {
         });
 
         it("invalid credentials type", () => {
-            expect(
-                validateCredentials({
-                    context: "irc",
-                    type: "credentials",
-                    // @ts-expect-error test invalid params
-                    object: {
-                        host: "example.com",
-                        port: "6667",
-                    },
-                }),
-            ).toEqual("[irc] /object: must have required property 'type'");
+            const result = validateCredentials({
+                "@context": IRC_CONTEXT,
+                type: "credentials",
+                actor,
+                // @ts-expect-error test invalid params
+                object: {
+                    host: "example.com",
+                    port: "6667",
+                },
+            });
+            expect([
+                "[irc] /object: must have required property 'type'",
+                "[irc] /object/port: must be number",
+                "[irc] /object: must match exactly one schema in oneOf: credentials, feed, message, me, person, room, service, platform, website, attendance, presence, relationship, topic, address, heartbeat",
+            ]).toContain(result);
         });
 
         it("invalid credentials port", () => {
             expect(
                 // @ts-expect-error test invalid params
                 validateCredentials({
-                    context: "irc",
+                    "@context": IRC_CONTEXT,
                     type: "credentials",
+                    actor,
                     object: {
                         type: "credentials",
                         host: "example.com",
@@ -130,8 +146,9 @@ describe("Initialize IRC Platform", () => {
             expect(
                 // @ts-expect-error test invalid params
                 validateCredentials({
-                    context: "irc",
+                    "@context": IRC_CONTEXT,
                     type: "credentials",
+                    actor,
                     object: {
                         type: "credentials",
                         host: "example.com",
@@ -148,7 +165,7 @@ describe("Initialize IRC Platform", () => {
         beforeEach((done) => {
             platform.connect(
                 {
-                    context: "irc",
+                    "@context": IRC_CONTEXT,
                     type: "connect",
                     actor: actor,
                 },
@@ -161,7 +178,7 @@ describe("Initialize IRC Platform", () => {
             beforeEach((done) => {
                 platform.join(
                     {
-                        context: "irc",
+                        "@context": IRC_CONTEXT,
                         type: "join",
                         actor: actor,
                         target: targetRoom,
@@ -178,7 +195,7 @@ describe("Initialize IRC Platform", () => {
             it("leave()", (done) => {
                 platform.leave(
                     {
-                        context: "irc",
+                        "@context": IRC_CONTEXT,
                         type: "leave",
                         actor: actor,
                         target: targetRoom,
@@ -191,7 +208,7 @@ describe("Initialize IRC Platform", () => {
             it("send()", (done) => {
                 platform.send(
                     {
-                        context: "irc",
+                        "@context": IRC_CONTEXT,
                         type: "send",
                         actor: actor,
                         object: { content: "har dee dar" },
@@ -205,7 +222,7 @@ describe("Initialize IRC Platform", () => {
             it("update() topic", (done) => {
                 platform.update(
                     {
-                        context: "irc",
+                        "@context": IRC_CONTEXT,
                         type: "update",
                         actor: actor,
                         object: { type: "topic", content: "important details" },
@@ -220,7 +237,7 @@ describe("Initialize IRC Platform", () => {
             it("update() nick change", (done) => {
                 platform.update(
                     {
-                        context: "irc",
+                        "@context": IRC_CONTEXT,
                         type: "update",
                         actor: actor,
                         object: { type: "address" },
@@ -235,7 +252,7 @@ describe("Initialize IRC Platform", () => {
             it("query()", (done) => {
                 platform.query(
                     {
-                        context: "irc",
+                        "@context": IRC_CONTEXT,
                         type: "query",
                         actor: actor,
                         target: targetRoom,
@@ -247,28 +264,28 @@ describe("Initialize IRC Platform", () => {
             });
 
             it("disconnect()", (done) => {
-                expect(platform.config.initialized).toEqual(true);
+                expect(platform.isInitialized()).toEqual(true);
                 let cleanupCalled = false;
                 platform.cleanup = (cb) => {
                     cleanupCalled = true;
                     cb();
                 }
                 platform.disconnect({
-                        context: "irc",
+                        "@context": IRC_CONTEXT,
                         type: "disconnect",
                         actor: actor,
                     },
                     () => {
-                    expect(platform.config.initialized).toEqual(true);
+                    expect(platform.isInitialized()).toEqual(true);
                     expect(cleanupCalled).toEqual(true);
                     done();
                 });
             });
 
             it("cleanup()", (done) => {
-                expect(platform.config.initialized).toEqual(true);
+                expect(platform.isInitialized()).toEqual(true);
                 platform.cleanup(() => {
-                    expect(platform.config.initialized).toEqual(false);
+                    expect(platform.isInitialized()).toEqual(false);
                     done();
                 });
             });

package/src/index.ts

@@ -18,8 +18,6 @@
 
 import net from "node:net";
 import tls from "node:tls";
-import IrcSocket from "irc-socket-sasl";
-
 import { IrcToActivityStreams } from "@sockethub/irc2as";
 import type {
     ActivityStream,
@@ -32,15 +30,19 @@ import type {
     PlatformSession,
     PlatformUpdateActor,
 } from "@sockethub/schemas";
+import { buildCanonicalContext } from "@sockethub/schemas";
+import IrcSocket, { type IrcSocketInstance } from "irc-socket-sasl";
 
 import { PlatformIrcSchema } from "./schema.js";
 import type { PlatformIrcCredentialsObject } from "./types.js";
 
 export type GetClientCallback = (
     err: string | null,
-    client?: typeof IrcSocket,
+    client?: IrcSocketInstance,
 ) => void;
 
+type JobQueueHandler = (err?: Error | string) => void | Promise<void>;
+
 interface IrcSocketOptionsCapabilities {
     requires: string[];
 }
@@ -77,26 +79,26 @@ interface IrcSocketOptions {
  * @param {object} cfg a unique config object for this instance
  */
 export default class IRC implements PersistentPlatformInterface {
-    debug: Logger;
+    private readonly log: Logger;
     credentialsHash: string;
     config: PersistentPlatformConfig = {
         persist: true,
         requireCredentials: ["connect", "update"],
-        initialized: false,
         connectTimeoutMs: 30000,
     };
     private readonly updateActor: PlatformUpdateActor;
     private readonly sendToClient: PlatformSendToClient;
-    private irc2as: typeof IrcToActivityStreams;
+    private irc2as!: IrcToActivityStreams;
     private forceDisconnect = false;
     private clientConnecting = false;
-    private client: typeof IrcSocket;
-    private jobQueue = []; // list of handlers to confirm when message delivery confirmed
+    private initialized = false;
+    private client?: IrcSocketInstance;
+    private jobQueue: Array<JobQueueHandler> = []; // list of handlers to confirm when message delivery confirmed
     private channels = new Set();
     private handledActors = new Set();
 
     constructor(session: PlatformSession) {
-        this.debug = session.debug;
+        this.log = session.log;
         this.sendToClient = session.sendToClient;
         this.updateActor = session.updateActor;
     }
@@ -146,6 +148,14 @@ export default class IRC implements PersistentPlatformInterface {
         return PlatformIrcSchema;
     }
 
+    /**
+     * Returns whether the platform is ready to handle jobs.
+     * For IRC, this means we have successfully connected to the server.
+     */
+    isInitialized(): boolean {
+        return this.initialized;
+    }
+
     /**
      * Function: connect
      *
@@ -196,13 +206,13 @@ export default class IRC implements PersistentPlatformInterface {
      *
      */
     join(job: ActivityStream, done: PlatformCallback) {
-        this.debug(`join() called for ${job.actor.id}`);
+        this.log.debug(`join() called for ${job.actor.id}`);
         this.getClient(job.actor.id, false, (err, client) => {
             if (err) {
                 return done(err);
             }
             if (this.channels.has(job.target.name)) {
-                this.debug(`channel ${job.target.name} already joined`);
+                this.log.debug(`channel ${job.target.name} already joined`);
                 return done();
             }
             // join channel
@@ -210,7 +220,7 @@ export default class IRC implements PersistentPlatformInterface {
                 this.hasJoined(job.target.name);
                 done();
             });
-            this.debug(`sending join ${job.target.name}`);
+            this.log.debug(`sending join ${job.target.name}`);
             client.raw(["JOIN", job.target.name]);
             client.raw(`PING ${job.actor.name}`);
         });
@@ -243,7 +253,7 @@ export default class IRC implements PersistentPlatformInterface {
      *
      */
     leave(job: ActivityStream, done: PlatformCallback) {
-        this.debug(`leave() called for ${job.actor.name}`);
+        this.log.debug(`leave() called for ${job.actor.name}`);
         this.getClient(job.actor.id, false, (err, client) => {
             if (err) {
                 return done(err);
@@ -287,7 +297,7 @@ export default class IRC implements PersistentPlatformInterface {
      *
      */
     send(job: ActivityStream, done: PlatformCallback) {
-        this.debug(
+        this.log.debug(
             `send() called for ${job.actor.id} target: ${job.target.id}`,
         );
         this.getClient(job.actor.id, false, async (err, client) => {
@@ -322,9 +332,11 @@ export default class IRC implements PersistentPlatformInterface {
                 // so the following line needs to be commented out when the API doc is built.
                 // investigate:
                 // https://github.com/jsdoc2md/jsdoc-to-markdown/issues/197#issuecomment-976851915
-                const buildCommand = await import("./octal-hack.js");
+                const { default: buildCommand } = await import(
+                    "./octal-hack.js"
+                );
                 const message = buildCommand(job.object.content);
-                // biome-ignore lint/style/useTemplate: <explanation>
+                // biome-ignore lint/style/useTemplate: IRC raw command formatting
                 client.raw("PRIVMSG " + job.target.name + " :" + message);
                 return done("IRC commands temporarily disabled");
             }
@@ -398,13 +410,13 @@ export default class IRC implements PersistentPlatformInterface {
         credentials: PlatformIrcCredentialsObject,
         done: PlatformCallback,
     ) {
-        this.debug(`update() called for ${job.actor.id}`);
+        this.log.debug(`update() called for ${job.actor.id}`);
         this.getClient(job.actor.id, false, (err, client) => {
             if (err) {
                 return done(err);
             }
             if (job.object.type === "address") {
-                this.debug(
+                this.log.debug(
                     `changing nick from ${job.actor.name} to ${job.target.name}`,
                 );
                 this.handledActors.add(job.target.id);
@@ -423,7 +435,7 @@ export default class IRC implements PersistentPlatformInterface {
                 client.raw(["NICK", job.target.name]);
             } else if (job.object.type === "topic") {
                 // update topic
-                this.debug(`changing topic in channel ${job.target.name}`);
+                this.log.debug(`changing topic in channel ${job.target.name}`);
                 this.jobQueue.push(done);
                 client.raw(["topic", job.target.name, job.object.content]);
             } else {
@@ -487,14 +499,16 @@ export default class IRC implements PersistentPlatformInterface {
      *
      */
     query(job: ActivityStream, done: PlatformCallback) {
-        this.debug(`query() called for ${job.actor.id}`);
+        this.log.debug(`query() called for ${job.actor.id}`);
         this.getClient(job.actor.id, false, (err, client) => {
             if (err) {
                 return done(err);
             }
 
             if (job.object.type === "attendance") {
-                this.debug(`query() - sending NAMES for ${job.target.name}`);
+                this.log.debug(
+                    `query() - sending NAMES for ${job.target.name}`,
+                );
                 client.raw(["NAMES", job.target.name]);
                 done();
             } else {
@@ -520,13 +534,13 @@ export default class IRC implements PersistentPlatformInterface {
      *  }
      */
     disconnect(job: ActivityStream, done: PlatformCallback) {
-        this.debug(`disconnect called for ${job.actor.id}`);
+        this.log.debug(`disconnect called for ${job.actor.id}`);
         this.cleanup(done);
     }
 
     cleanup(done: PlatformCallback) {
-        this.debug("cleanup() called");
-        this.config.initialized = false;
+        this.log.debug("cleanup() called");
+        this.initialized = false;
         this.forceDisconnect = true;
         if (typeof this.client === "object") {
             if (typeof this.client.end === "function") {
@@ -551,7 +565,7 @@ export default class IRC implements PersistentPlatformInterface {
     }
 
     private hasJoined(channel: string) {
-        this.debug(`joined ${channel}`);
+        this.log.debug(`joined ${channel}`);
         // keep track of channels joined
         if (!this.channels.has(channel)) {
             this.channels.add(channel);
@@ -559,7 +573,7 @@ export default class IRC implements PersistentPlatformInterface {
     }
 
     private hasLeft(channel: string) {
-        this.debug(`left ${channel}`);
+        this.log.debug(`left ${channel}`);
         // keep track of channels left
         if (this.channels.has(channel)) {
             this.channels.delete(channel);
@@ -571,7 +585,9 @@ export default class IRC implements PersistentPlatformInterface {
         credentials: PlatformIrcCredentialsObject | false,
         cb: GetClientCallback,
     ) {
-        this.debug(`getClient called, connecting: ${this.clientConnecting}`);
+        this.log.debug(
+            `getClient called, connecting: ${this.clientConnecting}`,
+        );
         if (this.client) {
             this.handledActors.add(key);
             return cb(null, this.client);
@@ -581,7 +597,9 @@ export default class IRC implements PersistentPlatformInterface {
             // client is in the process of connecting, wait
             setTimeout(() => {
                 if (this.client) {
-                    this.debug(`resolving delayed getClient call for ${key}`);
+                    this.log.debug(
+                        `resolving delayed getClient call for ${key}`,
+                    );
                     this.handledActors.add(key);
                     return cb(null, this.client);
                 }
@@ -598,13 +616,13 @@ export default class IRC implements PersistentPlatformInterface {
 
         this.ircConnect(credentials, (err, client) => {
             if (err) {
-                this.config.initialized = false;
+                this.initialized = false;
                 return cb(err);
             }
             this.handledActors.add(key);
             this.client = client;
             this.registerListeners(credentials.object.server);
-            this.config.initialized = true;
+            this.initialized = true;
             return cb(null, client);
         });
     }
@@ -645,16 +663,13 @@ export default class IRC implements PersistentPlatformInterface {
             module_options.capabilities = { requires: ["sasl"] };
         }
 
-        this.debug(
+        this.log.debug(
             `attempting to connect to ${module_options.server}:${module_options.port} transport: ${
                 is_secure ? "secure" : "clear"
             } sasl: ${is_sasl}`,
         );
 
-        const client: IrcSocket = new IrcSocket(
-            module_options,
-            is_secure ? tls : net,
-        );
+        const client = new IrcSocket(module_options, is_secure ? tls : net);
 
         const forceDisconnect = (err: string) => {
             this.forceDisconnect = true;
@@ -669,17 +684,17 @@ export default class IRC implements PersistentPlatformInterface {
         };
 
         client.once("error", (err: string) => {
-            this.debug(`irc client 'error' occurred. `, err);
+            this.log.debug(`irc client 'error' occurred.`, { err });
             forceDisconnect("error connecting to server.");
         });
 
         client.once("close", () => {
-            this.debug(`irc client 'close' event fired.`);
+            this.log.debug(`irc client 'close' event fired.`);
             forceDisconnect("connection to server closed.");
         });
 
         client.once("timeout", () => {
-            this.debug("timeout occurred, force-disconnect");
+            this.log.debug("timeout occurred, force-disconnect");
             forceDisconnect("connection timeout to server.");
         });
 
@@ -694,33 +709,36 @@ export default class IRC implements PersistentPlatformInterface {
                 return cb("force disconnect active, aborting connect.");
             }
 
-            this.debug(
+            this.log.debug(
                 `connected to ${module_options.server} capabilities: `,
-                capabilities,
+                { capabilities },
             );
             return cb(null, client);
         });
     }
 
     private completeJob(err?: string) {
-        this.debug(`completing job, queue count: ${this.jobQueue.length}`);
+        this.log.debug(`completing job, queue count: ${this.jobQueue.length}`);
         const done = this.jobQueue.shift();
         if (typeof done === "function") {
             done(err);
         } else if (this.jobQueue.length === 0) {
-            this.debug(
+            this.log.debug(
                 "WARNING: job completion event received with an empty job queue.",
             );
         } else {
-            this.debug(
+            this.log.debug(
                 `WARNING: job completion found non-function in queue (${typeof done}), ${this.jobQueue.length} items remain.`,
             );
         }
     }
 
     private registerListeners(server: string) {
-        this.irc2as = new IrcToActivityStreams({ server: server });
-        this.client.on("data", (data: never) => {
+        this.irc2as = new IrcToActivityStreams({
+            server: server,
+            contexts: buildCanonicalContext(this.schema.contextUrl),
+        });
+        this.client.on("data", (data: unknown) => {
             this.irc2as.input(data);
         });
 
@@ -732,32 +750,33 @@ export default class IRC implements PersistentPlatformInterface {
             ) {
                 this.completeJob();
             } else {
-                this.debug(`calling sendToClient for ${asObject.actor.id}`, [
-                    ...this.handledActors.keys(),
-                ]);
+                this.log.debug(
+                    `calling sendToClient for ${asObject.actor.id}`,
+                    [...this.handledActors.keys()],
+                );
                 this.sendToClient(asObject);
             }
         });
 
         this.irc2as.events.on("unprocessed", (s: string) => {
-            this.debug(`unprocessed irc message:> ${s}`);
+            this.log.debug(`unprocessed irc message:> ${s}`);
         });
 
         // The generated eslint error expects that the `error` event is propagating an Error object
         // however for irc2as this event delivers an AS object of type `error`.
 
         this.irc2as.events.on("error", (asObject: ActivityStream) => {
-            this.debug(`message error response ${asObject.object.content}`);
+            this.log.debug(`message error response ${asObject.object.content}`);
             this.completeJob(asObject.object.content);
         });
 
         this.irc2as.events.on("pong", (timestamp: string) => {
-            this.debug(`received PONG at ${timestamp}`);
+            this.log.debug(`received PONG at ${timestamp}`);
             this.completeJob();
         });
 
         this.irc2as.events.on("ping", (timestamp: string) => {
-            this.debug(`received PING at ${timestamp}`);
+            this.log.debug(`received PING at ${timestamp}`);
             this.client.raw("PONG");
         });
     }

package/src/octal-hack.d.ts

@@ -0,0 +1,2 @@
+declare const buildCommand: (input: string) => string;
+export default buildCommand;