@nestarc/inbox 0.0.0-stage → 0.2.0

package/examples/src/outbox-to-inbox/main.ts

@@ -0,0 +1,198 @@
+import "reflect-metadata";
+import assert from "node:assert/strict";
+import { randomUUID } from "node:crypto";
+import { Injectable, Module } from "@nestjs/common";
+import { NestFactory } from "@nestjs/core";
+import {
+  OutboxModule,
+  OutboxEvent,
+  OutboxEmitter,
+  OnOutboxEvent,
+  type OutboxHandlerContext,
+} from "@nestarc/outbox";
+import {
+  InboxModule,
+  InboxService,
+  InboxPermanentError,
+  type InboxHandler,
+} from "@nestarc/inbox";
+import {
+  createPrisma,
+  tenantId,
+  waitUntil,
+  type OrderPayload,
+} from "../common";
+import type { Prisma } from "../generated/prisma/client";
+
+class OrderCreated extends OutboxEvent {
+  static readonly eventType = "inbox-example.order.created";
+  constructor(public readonly orderId: string) {
+    super();
+  }
+}
+class OrderProjected extends OutboxEvent {
+  static readonly eventType = "inbox-example.order.projected";
+  constructor(public readonly orderId: string) {
+    super();
+  }
+}
+
+@Injectable()
+class Bridge {
+  constructor(private readonly inbox: InboxService) {}
+
+  @OnOutboxEvent(OrderCreated)
+  async created(payload: OrderPayload, context: OutboxHandlerContext) {
+    if (context.tenantId !== tenantId)
+      throw new Error("Unexpected fixture tenant");
+    await this.inbox.accept({
+      scope: { kind: "tenant", id: tenantId },
+      source: "example-order-service",
+      consumer: "example.projection.v1",
+      messageId: context.eventId,
+      eventType: OrderCreated.eventType,
+      schemaVersion: 1,
+      payload,
+    });
+  }
+
+  @OnOutboxEvent(OrderProjected)
+  async projected(payload: OrderPayload, context: OutboxHandlerContext) {
+    if (context.tenantId !== tenantId)
+      throw new Error("Unexpected fixture tenant");
+    await this.inbox.accept({
+      scope: { kind: "tenant", id: tenantId },
+      source: "example-projection-service",
+      consumer: "example.receipt.v1",
+      messageId: context.eventId,
+      eventType: OrderProjected.eventType,
+      schemaVersion: 1,
+      payload,
+    });
+  }
+}
+
+async function main() {
+  const prisma = createPrisma();
+  const outboxModule = OutboxModule.forRoot({
+    prisma,
+    polling: { interval: 25 },
+  });
+  @Module({
+    imports: [
+      outboxModule,
+      InboxModule.forRootAsync({
+        imports: [outboxModule],
+        inject: [OutboxEmitter],
+        useFactory: (outbox: OutboxEmitter) => {
+          const handlers: InboxHandler<
+            OrderPayload,
+            Prisma.TransactionClient
+          >[] = [
+            {
+              consumer: "example.projection.v1",
+              eventType: OrderCreated.eventType,
+              schemaVersion: 1,
+              async handle(payload, ctx) {
+                if (ctx.scope.kind !== "tenant")
+                  throw new InboxPermanentError();
+                await ctx.tx.exampleProjection.create({
+                  data: { tenantId: ctx.scope.id, orderId: payload.orderId },
+                });
+                // This insert, the projection, and Inbox COMPLETED share ctx.tx.
+                await outbox.emit(ctx.tx, new OrderProjected(payload.orderId), {
+                  tenantId: ctx.scope.id,
+                  aggregateId: payload.orderId,
+                  causationId: ctx.messageId,
+                });
+              },
+            },
+            {
+              consumer: "example.receipt.v1",
+              eventType: OrderProjected.eventType,
+              schemaVersion: 1,
+              async handle(payload, ctx) {
+                if (ctx.scope.kind !== "tenant")
+                  throw new InboxPermanentError();
+                await ctx.tx.exampleReceipt.create({
+                  data: { tenantId: ctx.scope.id, orderId: payload.orderId },
+                });
+              },
+            },
+          ];
+          return {
+            prisma,
+            handlers,
+            worker: { enabled: true, pollIntervalMs: 25, concurrency: 2 },
+          };
+        },
+      }),
+    ],
+    providers: [Bridge],
+  })
+  class AppModule {}
+
+  const app = await NestFactory.createApplicationContext(AppModule, {
+    logger: ["error", "warn"],
+  });
+  app.enableShutdownHooks();
+  try {
+    const orderId = randomUUID();
+    await prisma.$transaction(async (tx) => {
+      await tx.exampleOrder.create({ data: { id: orderId, tenantId } });
+      await app.get(OutboxEmitter).emit(tx, new OrderCreated(orderId), {
+        tenantId,
+        aggregateId: orderId,
+      });
+    });
+    await waitUntil(
+      async () =>
+        (await prisma.exampleReceipt.count({
+          where: { orderId, tenantId },
+        })) === 1,
+      "outbox → inbox → business write → outbox → downstream inbox",
+    );
+    const [event] = await prisma.$queryRawUnsafe<Array<{ id: string }>>(
+      "SELECT id FROM outbox_events WHERE aggregate_id = $1 AND event_type = $2",
+      orderId,
+      OrderCreated.eventType,
+    );
+    assert.ok(event);
+    const repeated = await app.get(InboxService).accept({
+      scope: { kind: "tenant", id: tenantId },
+      source: "example-order-service",
+      consumer: "example.projection.v1",
+      messageId: event.id,
+      eventType: OrderCreated.eventType,
+      schemaVersion: 1,
+      payload: { orderId },
+    });
+    assert.equal(repeated.kind, "duplicate");
+    assert.equal(
+      await prisma.exampleProjection.count({ where: { orderId, tenantId } }),
+      1,
+    );
+    assert.equal(
+      await prisma.exampleReceipt.count({ where: { orderId, tenantId } }),
+      1,
+    );
+    console.log(
+      JSON.stringify({
+        projections: 1,
+        downstreamReceipts: 1,
+        duplicateReplay: repeated.kind,
+      }),
+    );
+  } finally {
+    try {
+      await app.close();
+    } finally {
+      await prisma.$disconnect();
+    }
+  }
+}
+
+void main().catch((error: unknown) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/examples/src/rabbitmq-ingress/main.ts

@@ -0,0 +1,203 @@
+import assert from "node:assert/strict";
+import { randomUUID } from "node:crypto";
+import { setTimeout } from "node:timers/promises";
+import * as amqp from "amqplib";
+import {
+  InboxConflictError,
+  InboxService,
+  InboxValidationError,
+} from "@nestarc/inbox";
+import { startInbox, tenantId, waitUntil } from "../common";
+
+async function main() {
+  const brokerUrl =
+    process.env.INBOX_EXAMPLE_AMQP_URL ?? "amqp://guest:guest@127.0.0.1:55672";
+  if (
+    !["localhost", "127.0.0.1", "[::1]"].includes(new URL(brokerUrl).hostname)
+  ) {
+    throw new Error("This example connects only to a local RabbitMQ fixture.");
+  }
+  const fixture = await startInbox("example.rabbitmq.v1", "order.created");
+  const connection = await amqp
+    .connect(brokerUrl)
+    .catch(async (error: unknown) => {
+      await fixture.close();
+      throw error;
+    });
+  const channel = await connection
+    .createConfirmChannel()
+    .catch(async (error: unknown) => {
+      try {
+        await connection.close();
+      } finally {
+        await fixture.close();
+      }
+      throw error;
+    });
+  const prefix = `inbox-example-${randomUUID()}`;
+  const mainQueue = `${prefix}.main`;
+  const retryQueue = `${prefix}.retry`;
+  const deadQueue = `${prefix}.dead`;
+  let callbackError: unknown;
+  let acceptedDeliveries = 0;
+  const pending = new Set<Promise<void>>();
+  try {
+    await channel.assertQueue(deadQueue, { durable: true });
+    await channel.assertQueue(mainQueue, {
+      durable: true,
+      arguments: {
+        "x-dead-letter-exchange": "",
+        "x-dead-letter-routing-key": deadQueue,
+      },
+    });
+    await channel.assertQueue(retryQueue, {
+      durable: true,
+      arguments: {
+        "x-message-ttl": 1_000,
+        "x-dead-letter-exchange": "",
+        "x-dead-letter-routing-key": mainQueue,
+      },
+    });
+    await channel.prefetch(1);
+    const inbox = fixture.app.get(InboxService);
+    const subscription = await channel.consume(
+      mainQueue,
+      (message) => {
+        if (!message) return;
+        const processing = (async () => {
+          try {
+            if (
+              message.content.byteLength > 256 * 1024 ||
+              !message.properties.messageId
+            ) {
+              channel.nack(message, false, false);
+              return;
+            }
+            let payload: unknown;
+            try {
+              payload = JSON.parse(message.content.toString("utf8"));
+            } catch {
+              channel.nack(message, false, false);
+              return;
+            }
+            if (
+              !payload ||
+              typeof payload !== "object" ||
+              Array.isArray(payload) ||
+              typeof (payload as { orderId?: unknown }).orderId !== "string"
+            ) {
+              channel.nack(message, false, false);
+              return;
+            }
+            await inbox.accept({
+              // This fixture binds the authenticated broker route to one tenant.
+              // Production routes must derive this from trusted configuration.
+              scope: { kind: "tenant", id: tenantId },
+              source: "example-rabbitmq-orders",
+              consumer: "example.rabbitmq.v1",
+              messageId: message.properties.messageId,
+              eventType: "order.created",
+              schemaVersion: 1,
+              payload: payload as { orderId: string },
+            });
+            // Acceptance has committed. Handler failures are now Inbox's responsibility.
+            channel.ack(message);
+            acceptedDeliveries++;
+          } catch (error) {
+            if (
+              error instanceof InboxConflictError ||
+              error instanceof InboxValidationError
+            ) {
+              channel.nack(message, false, false);
+              return;
+            }
+            const previous = message.properties.headers?.["x-example-retries"];
+            const attempts =
+              typeof previous === "number" &&
+              Number.isSafeInteger(previous) &&
+              previous >= 0
+                ? previous
+                : 0;
+            if (attempts >= 3) {
+              channel.nack(message, false, false);
+              return;
+            }
+            try {
+              channel.sendToQueue(retryQueue, message.content, {
+                persistent: true,
+                messageId: message.properties.messageId,
+                contentType: "application/json",
+                headers: { "x-example-retries": attempts + 1 },
+              });
+              await channel.waitForConfirms();
+              channel.ack(message);
+            } catch (publishError) {
+              // Retain the unacknowledged delivery while backing off. With prefetch=1,
+              // this avoids an immediate nack/requeue loop during a database outage.
+              await setTimeout(1_000);
+              try {
+                channel.nack(message, false, true);
+              } catch {
+                /* connection loss requeues it */
+              }
+              callbackError = publishError;
+            }
+          }
+        })()
+          .catch((error: unknown) => {
+            callbackError = error;
+          })
+          .finally(() => {
+            pending.delete(processing);
+          });
+        pending.add(processing);
+      },
+      { noAck: false },
+    );
+
+    const orderId = randomUUID();
+    const messageId = randomUUID();
+    for (let attempt = 0; attempt < 2; attempt++) {
+      channel.sendToQueue(mainQueue, Buffer.from(JSON.stringify({ orderId })), {
+        persistent: true,
+        messageId,
+        contentType: "application/json",
+      });
+    }
+    await channel.waitForConfirms();
+    await waitUntil(async () => {
+      if (callbackError) throw callbackError;
+      return (
+        (await fixture.prisma.exampleProjection.count({
+          where: { orderId, tenantId },
+        })) === 1 && acceptedDeliveries === 2
+      );
+    }, "RabbitMQ duplicate delivery and one projection");
+    await channel.cancel(subscription.consumerTag);
+    await Promise.all(pending);
+    assert.equal(
+      await fixture.prisma.exampleProjection.count({
+        where: { orderId, tenantId },
+      }),
+      1,
+    );
+    console.log(
+      JSON.stringify({ deliveriesPublished: 2, projections: 1, deadQueue }),
+    );
+  } finally {
+    try {
+      await channel.close();
+    } finally {
+      try {
+        await connection.close();
+      } finally {
+        await fixture.close();
+      }
+    }
+  }
+}
+
+void main().catch((error: unknown) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/examples/src/sqs-ingress/main.ts

@@ -0,0 +1,273 @@
+import assert from "node:assert/strict";
+import { randomUUID } from "node:crypto";
+import {
+  ChangeMessageVisibilityCommand,
+  CreateQueueCommand,
+  DeleteMessageCommand,
+  DeleteQueueCommand,
+  GetQueueAttributesCommand,
+  ReceiveMessageCommand,
+  SendMessageCommand,
+  SQSClient,
+  type Message,
+} from "@aws-sdk/client-sqs";
+import {
+  InboxConflictError,
+  InboxService,
+  InboxValidationError,
+} from "@nestarc/inbox";
+import { tenantId, waitUntil } from "../common";
+import { startBrokerInbox } from "../broker-common";
+
+// This example checks the SQS API contract against local ElasticMQ. It is not an
+// AWS infrastructure, IAM, availability, or production SQS compatibility test.
+async function main() {
+  const configuredEndpoint = process.env.INBOX_EXAMPLE_SQS_ENDPOINT;
+  if (!configuredEndpoint)
+    throw new Error(
+      "Set INBOX_EXAMPLE_SQS_ENDPOINT to the local ElasticMQ fixture.",
+    );
+  const endpoint = new URL(configuredEndpoint);
+  if (
+    endpoint.protocol !== "http:" ||
+    !["localhost", "127.0.0.1", "[::1]"].includes(endpoint.hostname) ||
+    endpoint.username ||
+    endpoint.password ||
+    endpoint.pathname !== "/" ||
+    endpoint.search ||
+    endpoint.hash
+  ) {
+    throw new Error("This example connects only to a local HTTP SQS fixture.");
+  }
+  const client = new SQSClient({
+    region: "us-east-1",
+    endpoint: endpoint.origin,
+    // Explicit fixture credentials prevent the SDK from reading a real AWS profile.
+    credentials: {
+      accessKeyId: "local-fixture",
+      secretAccessKey: "local-fixture",
+    },
+    maxAttempts: 3,
+    requestHandler: { connectionTimeout: 2_000, requestTimeout: 10_000 },
+  });
+  const fixture = await startBrokerInbox("example.sqs.v1", "order.created").catch(
+    (error: unknown) => {
+      client.destroy();
+      throw error;
+    },
+  );
+  const inbox = fixture.app.get(InboxService);
+  const prefix = `inbox-example-${randomUUID()}`;
+  const createdQueues: string[] = [];
+  const eventId = randomUUID();
+  const orderId = randomUUID();
+  let acceptedDeliveries = 0;
+  let quarantinedDeliveries = 0;
+  let transientFailures = 0;
+  let redelivered = false;
+  let injectAcceptanceFailure = true;
+
+  function localQueueUrl(value: string | undefined): string {
+    if (!value) throw new Error("The SQS fixture did not return a queue URL.");
+    // ElasticMQ advertises its container port by default. Preserve the queue path
+    // while using the explicitly configured mapped loopback port for every call.
+    const queue = new URL(value);
+    return new URL(queue.pathname, endpoint.origin).href;
+  }
+
+  async function createQueue(
+    suffix: string,
+    attributes: Record<string, string> = {},
+  ): Promise<string> {
+    const result = await client.send(
+      new CreateQueueCommand({
+        QueueName: `${prefix}-${suffix}`,
+        Attributes: attributes,
+      }),
+    );
+    const url = localQueueUrl(result.QueueUrl);
+    createdQueues.push(url);
+    return url;
+  }
+
+  async function deleteMessage(queueUrl: string, message: Message) {
+    assert.ok(
+      message.ReceiptHandle,
+      "Received messages must have a receipt handle.",
+    );
+    await client.send(
+      new DeleteMessageCommand({
+        QueueUrl: queueUrl,
+        ReceiptHandle: message.ReceiptHandle,
+      }),
+    );
+  }
+
+  try {
+    const deadQueue = await createQueue("dead");
+    const attributes = await client.send(
+      new GetQueueAttributesCommand({
+        QueueUrl: deadQueue,
+        AttributeNames: ["QueueArn"],
+      }),
+    );
+    assert.ok(attributes.Attributes?.QueueArn);
+    const queue = await createQueue("main", {
+      VisibilityTimeout: "30",
+      ReceiveMessageWaitTimeSeconds: "1",
+      RedrivePolicy: JSON.stringify({
+        deadLetterTargetArn: attributes.Attributes.QueueArn,
+        maxReceiveCount: "3",
+      }),
+    });
+    const body = JSON.stringify({ eventId, orderId });
+    for (let index = 0; index < 2; index++) {
+      await client.send(
+        new SendMessageCommand({ QueueUrl: queue, MessageBody: body }),
+      );
+    }
+    await client.send(
+      new SendMessageCommand({
+        QueueUrl: queue,
+        MessageBody: "invalid-json-fixture",
+      }),
+    );
+
+    const deadline = Date.now() + 40_000;
+    while (acceptedDeliveries < 2 || quarantinedDeliveries < 1) {
+      if (Date.now() > deadline)
+        throw new Error("SQS ingress fixture timed out.");
+      const result = await client.send(
+        new ReceiveMessageCommand({
+          QueueUrl: queue,
+          MaxNumberOfMessages: 1,
+          WaitTimeSeconds: 1,
+          VisibilityTimeout: 30,
+          MessageSystemAttributeNames: ["ApproximateReceiveCount"],
+        }),
+      );
+      for (const message of result.Messages ?? []) {
+        assert.ok(message.ReceiptHandle);
+        if (Number(message.Attributes?.ApproximateReceiveCount) > 1)
+          redelivered = true;
+        try {
+          if (!message.Body || Buffer.byteLength(message.Body) > 256 * 1024)
+            throw new InboxValidationError("Missing or oversized SQS body.");
+          let value: unknown;
+          try {
+            value = JSON.parse(message.Body);
+          } catch {
+            throw new InboxValidationError("Invalid SQS JSON body.");
+          }
+          if (
+            !value ||
+            typeof value !== "object" ||
+            Array.isArray(value) ||
+            typeof (value as { eventId?: unknown }).eventId !== "string" ||
+            typeof (value as { orderId?: unknown }).orderId !== "string"
+          ) {
+            throw new InboxValidationError(
+              "SQS eventId and orderId must be strings.",
+            );
+          }
+          const incoming = value as { eventId: string; orderId: string };
+          // Fault injection proves that acceptance failure leaves the broker copy
+          // available. Production code simply calls accept without this branch.
+          if (injectAcceptanceFailure) {
+            injectAcceptanceFailure = false;
+            throw new Error("Injected pre-acceptance storage failure");
+          }
+          await inbox.accept({
+            // Bind authenticated queue/account routes to a trusted tenant. Neither
+            // the SQS MessageId nor the receipt handle is the producer's event ID.
+            scope: { kind: "tenant", id: tenantId },
+            source: "example-sqs-orders",
+            consumer: "example.sqs.v1",
+            messageId: incoming.eventId,
+            eventType: "order.created",
+            schemaVersion: 1,
+            payload: { orderId: incoming.orderId },
+          });
+        } catch (error) {
+          if (
+            error instanceof InboxConflictError ||
+            error instanceof InboxValidationError
+          ) {
+            // Confirm quarantine persistence before deleting the original copy.
+            // A failed publish leaves the original available after visibility expiry.
+            await client.send(
+              new SendMessageCommand({
+                QueueUrl: deadQueue,
+                MessageBody: message.Body ?? "missing-body",
+              }),
+            );
+            await deleteMessage(queue, message);
+            quarantinedDeliveries++;
+          } else {
+            transientFailures++;
+            // No DeleteMessage on failed/uncertain acceptance. A short visibility
+            // backoff allows redelivery; queue redrive bounds persistent failures.
+            await client.send(
+              new ChangeMessageVisibilityCommand({
+                QueueUrl: queue,
+                ReceiptHandle: message.ReceiptHandle,
+                VisibilityTimeout: 1,
+              }),
+            );
+          }
+          continue;
+        }
+        // Both accepted and duplicate mean durable receipt. Inbox now owns handler
+        // retries, so this acknowledgement does not wait for business completion.
+        await deleteMessage(queue, message);
+        acceptedDeliveries++;
+      }
+    }
+    await waitUntil(
+      async () =>
+        (await fixture.prisma.exampleProjection.count({
+          where: { orderId, tenantId },
+        })) === 1,
+      "SQS duplicate deliveries and one projection",
+    );
+    const dead = await client.send(
+      new ReceiveMessageCommand({
+        QueueUrl: deadQueue,
+        MaxNumberOfMessages: 1,
+        WaitTimeSeconds: 1,
+      }),
+    );
+    assert.equal(dead.Messages?.[0]?.Body, "invalid-json-fixture");
+    assert.equal(transientFailures, 1);
+    assert.equal(redelivered, true);
+    assert.equal(acceptedDeliveries, 2);
+    assert.equal(quarantinedDeliveries, 1);
+    assert.ok(fixture.retries() >= 1, "Inbox owns retries after SQS acceptance.");
+    console.log(
+      JSON.stringify({
+        transport: "ElasticMQ (SQS-compatible emulator)",
+        acceptedDeliveries,
+        projections: 1,
+        transientFailures,
+        handlerRetries: fixture.retries(),
+        redelivered,
+        quarantinedDeliveries,
+      }),
+    );
+  } finally {
+    const cleanup = await Promise.allSettled(
+      createdQueues
+        .reverse()
+        .map((QueueUrl) => client.send(new DeleteQueueCommand({ QueueUrl }))),
+    );
+    client.destroy();
+    await fixture.close();
+    const failed = cleanup.find((result) => result.status === "rejected");
+    if (failed?.status === "rejected") throw failed.reason;
+  }
+}
+
+void main().catch((error: unknown) => {
+  console.error(error);
+  process.exitCode = 1;
+});