@rocketmq/core 0.1.0

package/src/client.test.ts

@@ -0,0 +1,333 @@
+/**
+ * Tests for RocketMQ client and connect().
+ *
+ * Mocks AmqpConnection to avoid real AMQP connections.
+ * Covers: connect (success/failure), assertQueue (with/without schema),
+ * assertExchange, bindQueue, sendToQueue (valid/invalid),
+ * publish, consume, ack, nack, prefetch, close.
+ */
+
+import { Field, Schema, SchemaRegistry } from '@rocketmq/schema';
+import { JsonSerializer } from '@rocketmq/serializer';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { connect, RocketMQ } from './client.js';
+import { ConnectionError, ConsumeError, PublishError, QueueError } from './errors.js';
+
+// Mock AmqpConnection for connect() tests
+vi.mock('@rocketmq/amqp', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@rocketmq/amqp')>();
+  return {
+    ...actual,
+    AmqpConnection: {
+      connect: vi.fn().mockResolvedValue({
+        createChannel: vi.fn().mockResolvedValue({
+          assertQueue: vi.fn().mockResolvedValue({ queue: 'q', messageCount: 0, consumerCount: 0 }),
+          close: vi.fn().mockResolvedValue(undefined),
+        }),
+        close: vi.fn().mockResolvedValue(undefined),
+      }),
+    },
+  };
+});
+/** Named fake channel mock. */
+class FakeAmqpChannel {
+  raw = this;
+  assertQueue = vi.fn().mockResolvedValue({ queue: 'q', messageCount: 0, consumerCount: 0 });
+  assertExchange = vi.fn().mockResolvedValue({ exchange: 'ex' });
+  bindQueue = vi.fn().mockResolvedValue({});
+  sendToQueue = vi.fn().mockReturnValue(true);
+  publish = vi.fn().mockReturnValue(true);
+  consume = vi.fn().mockResolvedValue({ consumerTag: 'tag-1' });
+  ack = vi.fn();
+  nack = vi.fn();
+  prefetch = vi.fn().mockResolvedValue(undefined);
+  close = vi.fn().mockResolvedValue(undefined);
+}
+
+/** Named fake connection mock. */
+class FakeAmqpConnection {
+  close = vi.fn().mockResolvedValue(undefined);
+}
+
+describe('RocketMQ', () => {
+  let ch: FakeAmqpChannel;
+  let conn: FakeAmqpConnection;
+  let registry: SchemaRegistry;
+  let mq: RocketMQ;
+
+  beforeEach(() => {
+    ch = new FakeAmqpChannel();
+    conn = new FakeAmqpConnection();
+    registry = new SchemaRegistry();
+    mq = new RocketMQ(conn as never, ch as never, registry, new JsonSerializer());
+  });
+
+  it('exposes channel via .channel', () => {
+    expect(mq.channel).toBe(ch);
+  });
+
+  describe('assertQueue', () => {
+    it('asserts queue without schema', async () => {
+      await mq.assertQueue('plain-q');
+      expect(ch.assertQueue).toHaveBeenCalledWith('plain-q', undefined);
+    });
+
+    it('asserts queue with schema and registers entry', async () => {
+      @Schema()
+      class TestItem {
+        @Field()
+        id!: string;
+      }
+      new TestItem();
+
+      await mq.assertQueue('items', TestItem);
+
+      expect(ch.assertQueue).toHaveBeenCalledWith(
+        'items',
+        expect.objectContaining({
+          arguments: expect.objectContaining({
+            'x-schema': expect.stringContaining('proto3'),
+            'x-schema-type': 'protobuf',
+            'x-schema-message': 'TestItem',
+          }),
+        }),
+      );
+
+      // Verify registry was populated
+      const entry = registry.lookup('items');
+      expect(entry).toBeDefined();
+      expect(entry?.name).toBe('TestItem');
+    });
+
+    it('merges user-provided queue options with schema args', async () => {
+      @Schema()
+      class MergeTest {
+        @Field()
+        x!: string;
+      }
+      new MergeTest();
+
+      await mq.assertQueue('merge-q', MergeTest, {
+        durable: true,
+        arguments: { 'x-max-length': 1000 },
+      });
+
+      expect(ch.assertQueue).toHaveBeenCalledWith(
+        'merge-q',
+        expect.objectContaining({
+          durable: true,
+          arguments: expect.objectContaining({
+            'x-max-length': 1000,
+            'x-schema': expect.any(String),
+          }),
+        }),
+      );
+    });
+
+    it('throws QueueError when channel rejects', async () => {
+      @Schema()
+      class QErr {
+        @Field()
+        v!: string;
+      }
+      new QErr();
+
+      ch.assertQueue.mockRejectedValue(new Error('PRECONDITION_FAILED'));
+      await expect(mq.assertQueue('fail-q', QErr)).rejects.toThrow(QueueError);
+    });
+
+    it('never sends x-schema-subject as queue arg (triggers Confluent wire validation)', async () => {
+      @Schema('notifications.v1')
+      class SubjectTest {
+        @Field()
+        id!: string;
+      }
+      new SubjectTest();
+
+      await mq.assertQueue('subject-q', SubjectTest);
+      const callArgs = ch.assertQueue.mock.calls[0][1];
+      expect(callArgs.arguments).not.toHaveProperty('x-schema-subject');
+    });
+
+    it('stores subject in client registry even though it is not sent to broker', async () => {
+      @Schema('orders.v2')
+      class RegistrySubject {
+        @Field()
+        x!: string;
+      }
+      new RegistrySubject();
+
+      await mq.assertQueue('reg-q', RegistrySubject);
+      const entry = registry.lookup('reg-q');
+      expect(entry?.subject).toBe('orders.v2');
+    });
+  });
+
+  describe('queue (typed handle)', () => {
+    it('returns a QueueHandle after asserting', async () => {
+      @Schema()
+      class HandleTest {
+        @Field()
+        id!: string;
+      }
+      new HandleTest();
+
+      const handle = await mq.queue('handle-q', HandleTest);
+      expect(handle).toBeDefined();
+      expect(typeof handle.send).toBe('function');
+      expect(typeof handle.consume).toBe('function');
+    });
+  });
+
+  describe('assertExchange', () => {
+    it('delegates to channel', async () => {
+      await mq.assertExchange('my-ex', 'direct', { durable: true });
+      expect(ch.assertExchange).toHaveBeenCalledWith('my-ex', 'direct', { durable: true });
+    });
+  });
+
+  describe('bindQueue', () => {
+    it('delegates to channel', async () => {
+      await mq.bindQueue('q', 'ex', 'key');
+      expect(ch.bindQueue).toHaveBeenCalledWith('q', 'ex', 'key');
+    });
+  });
+
+  describe('sendToQueue (untyped)', () => {
+    it('serializes and sends valid payload', () => {
+      const result = mq.sendToQueue('plain-q', { key: 'value' });
+      expect(result).toBe(true);
+      expect(ch.sendToQueue).toHaveBeenCalledWith(
+        'plain-q',
+        expect.any(Buffer),
+        expect.objectContaining({ contentType: 'application/json', persistent: true }),
+      );
+    });
+
+    it('throws PublishError when channel.sendToQueue throws', () => {
+      ch.sendToQueue.mockImplementation(() => {
+        throw new Error('closed');
+      });
+      expect(() => mq.sendToQueue('q', { ok: true })).toThrow(PublishError);
+    });
+  });
+
+  describe('publish', () => {
+    it('serializes and publishes to exchange', () => {
+      const result = mq.publish('ex', 'key', { data: 1 });
+      expect(result).toBe(true);
+      expect(ch.publish).toHaveBeenCalledWith(
+        'ex',
+        'key',
+        expect.any(Buffer),
+        expect.objectContaining({ contentType: 'application/json' }),
+      );
+    });
+
+    it('throws PublishError when channel.publish throws', () => {
+      ch.publish.mockImplementation(() => {
+        throw new Error('closed');
+      });
+      expect(() => mq.publish('ex', 'key', {})).toThrow(PublishError);
+    });
+  });
+
+  describe('consume (untyped)', () => {
+    it('subscribes and returns consumer tag', async () => {
+      const handler = vi.fn();
+      const tag = await mq.consume('q', handler);
+      expect(tag).toBe('tag-1');
+    });
+
+    it('deserializes and calls handler', async () => {
+      const handler = vi.fn();
+      ch.consume.mockImplementation(async (_q: string, cb: Function) => {
+        cb({ content: Buffer.from('{"a":1}'), fields: {}, properties: {} });
+        return { consumerTag: 't' };
+      });
+      await mq.consume('q', handler);
+      expect(handler).toHaveBeenCalledWith({ a: 1 }, expect.anything());
+    });
+
+    it('ignores null messages', async () => {
+      const handler = vi.fn();
+      ch.consume.mockImplementation(async (_q: string, cb: Function) => {
+        cb(null);
+        return { consumerTag: 't' };
+      });
+      await mq.consume('q', handler);
+      expect(handler).not.toHaveBeenCalled();
+    });
+
+    it('logs deserialization errors without crashing', async () => {
+      const handler = vi.fn();
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      ch.consume.mockImplementation(async (_q: string, cb: Function) => {
+        cb({ content: Buffer.from('not-json'), fields: {}, properties: {} });
+        return { consumerTag: 't' };
+      });
+      await mq.consume('q', handler);
+      expect(handler).not.toHaveBeenCalled();
+      expect(consoleSpy).toHaveBeenCalled();
+      consoleSpy.mockRestore();
+    });
+
+    it('throws ConsumeError when channel.consume rejects', async () => {
+      ch.consume.mockRejectedValue(new Error('NOT_FOUND'));
+      await expect(mq.consume('q', vi.fn())).rejects.toThrow(ConsumeError);
+    });
+  });
+
+  describe('ack / nack', () => {
+    it('delegates ack to channel', () => {
+      const msg = { content: Buffer.from('') } as never;
+      mq.ack(msg);
+      expect(ch.ack).toHaveBeenCalledWith(msg);
+    });
+
+    it('delegates nack to channel', () => {
+      const msg = { content: Buffer.from('') } as never;
+      mq.nack(msg, true);
+      expect(ch.nack).toHaveBeenCalledWith(msg, true);
+    });
+  });
+
+  describe('prefetch', () => {
+    it('delegates to channel', async () => {
+      await mq.prefetch(10);
+      expect(ch.prefetch).toHaveBeenCalledWith(10);
+    });
+  });
+
+  describe('close', () => {
+    it('closes channel and connection', async () => {
+      await mq.close();
+      expect(ch.close).toHaveBeenCalled();
+      expect(conn.close).toHaveBeenCalled();
+    });
+  });
+});
+
+describe('connect()', () => {
+  it('returns a RocketMQ instance on success', async () => {
+    const mq = await connect({ url: 'amqp://localhost' });
+    expect(mq).toBeInstanceOf(RocketMQ);
+  });
+
+  it('uses default URL when none provided', async () => {
+    const mq = await connect();
+    expect(mq).toBeInstanceOf(RocketMQ);
+  });
+
+  it('accepts a custom serializer', async () => {
+    const custom = new JsonSerializer();
+    const mq = await connect({ serializer: custom });
+    expect(mq).toBeInstanceOf(RocketMQ);
+  });
+
+  it('throws ConnectionError when connection fails', async () => {
+    const { AmqpConnection } = await import('@rocketmq/amqp');
+    vi.mocked(AmqpConnection.connect).mockRejectedValueOnce(new Error('ECONNREFUSED'));
+    await expect(connect({ url: 'amqp://bad-host' })).rejects.toThrow(ConnectionError);
+  });
+});

package/src/client.ts

@@ -0,0 +1,272 @@
+/**
+ * RocketMQ TypeScript client — schema-aware AMQP wrapper.
+ *
+ * Composes schema, validation, serialization, and AMQP packages into
+ * a single user-facing API. Hides all internal wiring behind `connect()`
+ * and `mq.queue()`.
+ *
+ * Usage:
+ *   const mq = await connect();
+ *   const orders = mq.queue("orders", Order);
+ *   orders.send({ id: "1", customerId: "c1", qty: 5 });
+ */
+
+import {
+  AmqpConnection,
+  type AmqpChannel,
+  type AssertExchangeOptions,
+  type AssertExchangeReply,
+  type AssertQueueOptions,
+  type AssertQueueReply,
+  type ConsumeMessage,
+  type EmptyReply,
+  type PublishOptions,
+} from '@rocketmq/amqp';
+import { toProto } from '@rocketmq/protobuf';
+import { defaultRegistry, type SchemaRegistry } from '@rocketmq/schema';
+import { JsonSerializer, type Serializer } from '@rocketmq/serializer';
+import { ConnectionError, ConsumeError, PublishError, QueueError } from './errors.js';
+import { QueueHandle } from './queue-handle.js';
+
+export interface RocketOptions {
+  /** AMQP connection URL. Default: amqp://guest:guest@localhost:5672 */
+  url?: string;
+  /** Custom serializer. Default: JsonSerializer. */
+  serializer?: Serializer;
+}
+
+/** Opens a connection + channel ready for schema-aware operations. */
+export async function connect(opts: RocketOptions = {}): Promise<RocketMQ> {
+  const url = opts.url ?? 'amqp://guest:guest@localhost:5672';
+  const serializer = opts.serializer ?? new JsonSerializer();
+
+  try {
+    const conn = await AmqpConnection.connect(url);
+    const ch = await conn.createChannel();
+    return new RocketMQ(conn, ch, defaultRegistry, serializer);
+  } catch (err) {
+    throw new ConnectionError(`Failed to connect to ${url}`, err);
+  }
+}
+
+export class RocketMQ {
+  constructor(
+    private readonly conn: AmqpConnection,
+    private readonly ch: AmqpChannel,
+    private readonly registry: SchemaRegistry,
+    private readonly serializer: Serializer,
+  ) {}
+
+  /** Exposes the raw AmqpChannel for event listeners (e.g. broker errors). */
+  get channel(): AmqpChannel {
+    return this.ch;
+  }
+
+  /**
+   * Creates a typed queue handle bound to a schema class.
+   *
+   * Declares the queue with schema metadata in AMQP arguments so the
+   * broker compiles and validates messages. Returns a QueueHandle<T>
+   * for type-safe send/consume.
+   */
+  async queue<T>(
+    name: string,
+    schema: new (...args: unknown[]) => T,
+    opts?: AssertQueueOptions,
+  ): Promise<QueueHandle<T>> {
+    await this.assertQueue(name, schema, opts);
+    return new QueueHandle<T>(name, this.ch, this.registry, this.serializer);
+  }
+
+  /**
+   * Declares a queue with an optional schema class.
+   *
+   * When a schema is provided the proto3 definition is sent as AMQP
+   * queue arguments (`x-schema`, `x-schema-type`, `x-schema-message`)
+   * so the broker compiles and validates messages inline.
+   */
+  async assertQueue(
+    name: string,
+    schema?: Function,
+    opts?: AssertQueueOptions,
+  ): Promise<AssertQueueReply> {
+    if (!schema) {
+      return this.ch.assertQueue(name, opts);
+    }
+
+    const proto = toProto(schema);
+    // WHY: decorators write to defaultRegistry, not the instance registry
+    const fields = defaultRegistry.getFields(schema);
+    const subject = defaultRegistry.getSubject(schema);
+
+    this.registry.register(name, {
+      ctor: schema,
+      name: schema.name,
+      subject,
+      fields: [...fields],
+    });
+
+    // Schema metadata sent as queue arguments so the broker compiles
+    // a proto descriptor and validates JSON payloads on publish.
+    const schemaArgs: Record<string, string> = {
+      'x-schema': proto,
+      'x-schema-type': 'protobuf',
+      'x-schema-message': schema.name,
+    };
+
+    try {
+      return await this.ch.assertQueue(name, {
+        ...opts,
+        arguments: {
+          ...opts?.arguments,
+          ...schemaArgs,
+        },
+      });
+    } catch (err) {
+      throw new QueueError(`Failed to assert queue '${name}'`, err);
+    }
+  }
+
+  /** Declares an exchange (passthrough to AMQP layer). */
+  async assertExchange(
+    name: string,
+    type: string,
+    opts?: AssertExchangeOptions,
+  ): Promise<AssertExchangeReply> {
+    return this.ch.assertExchange(name, type, opts);
+  }
+
+  /** Binds a queue to an exchange (passthrough to AMQP layer). */
+  async bindQueue(queue: string, exchange: string, routingKey: string): Promise<EmptyReply> {
+    return this.ch.bindQueue(queue, exchange, routingKey);
+  }
+
+  /**
+   * Publishes a JSON message directly to a queue (untyped path).
+   *
+   * Prefer `mq.queue("name", Schema).send()` for type safety.
+   * Validation is handled broker-side via the queue's compiled schema.
+   */
+  sendToQueue(queue: string, payload: Record<string, unknown>, opts?: PublishOptions): boolean {
+    try {
+      const buf = this.serializer.serialize(payload);
+      return this.ch.sendToQueue(queue, buf, {
+        contentType: this.serializer.contentType,
+        persistent: true,
+        ...opts,
+      });
+    } catch (err) {
+      throw new PublishError(queue, err);
+    }
+  }
+
+  /**
+   * Publishes a JSON message to an exchange with a routing key.
+   */
+  publish(
+    exchange: string,
+    routingKey: string,
+    payload: Record<string, unknown>,
+    opts?: PublishOptions,
+  ): boolean {
+    try {
+      const buf = this.serializer.serialize(payload);
+      return this.ch.publish(exchange, routingKey, buf, {
+        contentType: this.serializer.contentType,
+        persistent: true,
+        ...opts,
+      });
+    } catch (err) {
+      throw new PublishError(`exchange:${exchange} routingKey:${routingKey}`, err);
+    }
+  }
+
+  /**
+   * Subscribes to a queue with JSON deserialization.
+   *
+   * When a schema was registered via `assertQueue(name, Schema)`,
+   * the consumer's proto definition is sent to the broker for subset
+   * checking — the broker rejects consumers expecting fields the
+   * queue's schema doesn't define.
+   *
+   * Usage:
+   *   await mq.assertQueue("orders", Order);
+   *   await mq.consume("orders", (msg) => console.log(msg));
+   */
+  async consume<T = Record<string, unknown>>(
+    queue: string,
+    handler: (msg: T, raw: ConsumeMessage) => void,
+    opts?: import('@rocketmq/amqp').ConsumeOptions,
+  ): Promise<string> {
+    // Build consumer schema arguments for broker-side subset validation.
+    const consumerArgs = this.buildConsumerSchemaArgs(queue);
+
+    try {
+      const reply = await this.ch.consume(
+        queue,
+        (msg) => {
+          if (!msg) return;
+          try {
+            const body = this.serializer.deserialize(msg.content) as T;
+            handler(body, msg);
+          } catch (err) {
+            console.error(`[rocketmq] deserialization error on queue '${queue}':`, err);
+          }
+        },
+        {
+          ...opts,
+          arguments: {
+            ...opts?.arguments,
+            ...consumerArgs,
+          },
+        },
+      );
+      return reply.consumerTag;
+    } catch (err) {
+      throw new ConsumeError(`Failed to consume from queue '${queue}'`, err);
+    }
+  }
+
+  /**
+   * Builds AMQP arguments for consumer schema compatibility checking.
+   *
+   * Returns `x-consumer-schema` + `x-consumer-schema-message` if the
+   * queue has a registered schema, otherwise an empty object.
+   */
+  private buildConsumerSchemaArgs(queue: string): Record<string, string> {
+    const meta = this.registry.lookup(queue);
+    if (!meta) return {};
+
+    try {
+      const proto = toProto(meta.ctor);
+      return {
+        'x-consumer-schema': proto,
+        'x-consumer-schema-message': meta.name,
+      };
+    } catch {
+      // WHY: ctor may lack @Field() decorators (e.g. untyped consumers)
+      return {};
+    }
+  }
+
+  /** Acknowledges a message. */
+  ack(msg: ConsumeMessage): void {
+    this.ch.ack(msg);
+  }
+
+  /** Negative-acknowledges a message. */
+  nack(msg: ConsumeMessage, requeue?: boolean): void {
+    this.ch.nack(msg, requeue);
+  }
+
+  /** Sets prefetch count on the channel. */
+  async prefetch(count: number): Promise<void> {
+    await this.ch.prefetch(count);
+  }
+
+  /** Closes channel and connection. */
+  async close(): Promise<void> {
+    await this.ch.close();
+    await this.conn.close();
+  }
+}