@relaymesh/relaybus-nats 0.1.0

package/README.md

@@ -0,0 +1,3 @@
+# relaybus-nats (TypeScript)
+
+NATS publisher and subscriber utilities for Relaybus.

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@relaymesh/relaybus-nats",
+  "version": "0.1.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@relaymesh/relaybus-core": "workspace:*",
+    "nats": "^2.29.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,138 @@
+import { decodeEnvelope, encodeEnvelope, DecodedMessage, OutgoingMessage } from "@relaybus/relaybus-core";
+import { connect, NatsConnection } from "nats";
+
+export type NatsClient = {
+  publish: (subject: string, data: Buffer) => Promise<void> | void;
+};
+
+export type NatsPublisherConfig = {
+  client: NatsClient;
+  subjectPrefix?: string;
+};
+
+export type NatsPublisherConnectConfig = {
+  url: string;
+  subjectPrefix?: string;
+};
+
+export class NatsPublisher {
+  private readonly client: NatsClient;
+  private readonly prefix: string;
+  private connection?: NatsConnection;
+
+  constructor(config: NatsPublisherConfig) {
+    if (!config.client) {
+      throw new Error("client is required");
+    }
+    this.client = config.client;
+    this.prefix = config.subjectPrefix ?? "";
+  }
+
+  static async connect(config: NatsPublisherConnectConfig): Promise<NatsPublisher> {
+    const connection = await connect({ servers: config.url });
+    const publisher = new NatsPublisher({
+      client: {
+        publish: async (subject, data) => {
+          connection.publish(subject, data);
+        }
+      },
+      subjectPrefix: config.subjectPrefix
+    });
+    publisher.connection = connection;
+    return publisher;
+  }
+
+  async publish(topic: string, message: OutgoingMessage): Promise<void> {
+    const resolved = resolveTopic(topic, message.topic);
+    const payload = encodeEnvelope({ ...message, topic: resolved });
+    const subject = joinSubject(this.prefix, resolved);
+    await Promise.resolve(this.client.publish(subject, payload));
+  }
+
+  async close(): Promise<void> {
+    if (this.connection) {
+      await this.connection.drain();
+    }
+  }
+}
+
+export type NatsSubscriberConfig = {
+  onMessage: (msg: DecodedMessage) => void | Promise<void>;
+};
+
+export type NatsSubscriberConnectConfig = {
+  url: string;
+  onMessage: (msg: DecodedMessage) => void | Promise<void>;
+  subjectPrefix?: string;
+  maxMessages?: number;
+};
+
+export class NatsSubscriber {
+  private readonly onMessage: (msg: DecodedMessage) => void | Promise<void>;
+  private connection?: NatsConnection;
+  private prefix?: string;
+  private maxMessages?: number;
+
+  constructor(config: NatsSubscriberConfig) {
+    this.onMessage = config.onMessage;
+  }
+
+  static async connect(config: NatsSubscriberConnectConfig): Promise<NatsSubscriber> {
+    const connection = await connect({ servers: config.url });
+    const subscriber = new NatsSubscriber({ onMessage: config.onMessage });
+    subscriber.connection = connection;
+    subscriber.prefix = config.subjectPrefix ?? "";
+    subscriber.maxMessages = config.maxMessages ?? 1;
+    return subscriber;
+  }
+
+  async handleMessage(data: Buffer | string): Promise<void> {
+    const decoded = decodeEnvelope(data);
+    await this.onMessage(decoded);
+  }
+
+  async start(topic: string): Promise<void> {
+    if (!this.connection) {
+      throw new Error("connection is not initialized");
+    }
+    const subject = joinSubject(this.prefix ?? "", topic);
+    const sub = this.connection.subscribe(subject);
+    let count = 0;
+    for await (const msg of sub) {
+      const data = Buffer.from(msg.data);
+      await this.handleMessage(data);
+      count++;
+      if (this.maxMessages && count >= this.maxMessages) {
+        sub.unsubscribe();
+        break;
+      }
+    }
+  }
+
+  async close(): Promise<void> {
+    if (this.connection) {
+      await this.connection.drain();
+    }
+  }
+}
+
+function resolveTopic(argumentTopic: string, messageTopic?: string): string {
+  const topic = messageTopic && messageTopic.length > 0 ? messageTopic : argumentTopic;
+  if (!topic) {
+    throw new Error("topic is required");
+  }
+  if (argumentTopic && messageTopic && argumentTopic !== messageTopic) {
+    throw new Error(`topic mismatch: ${messageTopic} vs ${argumentTopic}`);
+  }
+  return topic;
+}
+
+function joinSubject(prefix: string, topic: string): string {
+  if (!prefix) {
+    return topic;
+  }
+  if (prefix.endsWith(".")) {
+    return `${prefix}${topic}`;
+  }
+  return `${prefix}.${topic}`;
+}

package/test/nats.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import { NatsPublisher, NatsSubscriber } from "../src/index";
+import { decodeEnvelope } from "@relaybus/relaybus-core";
+
+describe("NatsPublisher", () => {
+  it("publishes encoded envelope with subject prefix", async () => {
+    const calls: any[] = [];
+    const publisher = new NatsPublisher({
+      client: {
+        publish: async (subject, data) => {
+          calls.push({ subject, data });
+        }
+      },
+      subjectPrefix: "events"
+    });
+
+    await publisher.publish("alpha", {
+      id: "id-1",
+      topic: "alpha",
+      payload: Buffer.from("hi")
+    });
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].subject).toBe("events.alpha");
+    const decoded = decodeEnvelope(calls[0].data);
+    expect(decoded.id).toBe("id-1");
+  });
+});
+
+describe("NatsSubscriber", () => {
+  it("decodes messages", async () => {
+    let seen = "";
+    const subscriber = new NatsSubscriber({
+      onMessage: (msg) => {
+        seen = msg.topic;
+      }
+    });
+
+    await subscriber.handleMessage(
+      Buffer.from(
+        JSON.stringify({
+          v: "v1",
+          id: "id",
+          topic: "alpha",
+          ts: "2024-01-01T00:00:00Z",
+          content_type: "text/plain",
+          payload_b64: "aGVsbG8=",
+          meta: {}
+        })
+      )
+    );
+
+    expect(seen).toBe("alpha");
+  });
+
+  it("rejects invalid base64", async () => {
+    const subscriber = new NatsSubscriber({ onMessage: () => {} });
+    await expect(
+      subscriber.handleMessage(
+        Buffer.from(
+          JSON.stringify({
+            v: "v1",
+            id: "id",
+            topic: "alpha",
+            ts: "2024-01-01T00:00:00Z",
+            content_type: "text/plain",
+            payload_b64: "???",
+            meta: {}
+          })
+        )
+      )
+    ).rejects.toThrow(/invalid payload_b64/);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "types": ["node"],
+    "baseUrl": ".",
+    "paths": {
+      "@relaybus/relaybus-core": ["../../core/typescript/dist"]
+    }
+  },
+  "include": ["src/**/*.ts"]
+}