@nestarc/inbox 0.0.0-stage → 0.1.0

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;
+});

package/examples/src/tenancy/main.ts

@@ -0,0 +1,210 @@
+import "reflect-metadata";
+import assert from "node:assert/strict";
+import { randomBytes, randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { Module } from "@nestjs/common";
+import { NestFactory } from "@nestjs/core";
+import { PrismaPg } from "@prisma/adapter-pg";
+import { Pool } from "pg";
+import {
+  TenancyContext,
+  TenancyModule,
+  TenancyService,
+} from "@nestarc/tenancy";
+import {
+  InboxModule,
+  InboxService,
+  createInboxTenancyContext,
+  type InboxHandler,
+  type InboxScope,
+} from "@nestarc/inbox";
+import { PrismaClient, type Prisma } from "../generated/prisma/client";
+import { exampleDatabaseUrl } from "../common";
+
+type Payload = { targetTenant: string };
+const consumer = "example.tenancy.v1";
+const eventType = "example.tenant-work";
+
+async function main() {
+  // This credential is only the isolated fixture's schema administrator. Business
+  // handlers use the separate role below, which cannot bypass RLS or own tables.
+  const admin = new Pool({ connectionString: exampleDatabaseUrl(), max: 2 });
+  const role = `inbox_example_${randomBytes(8).toString("hex")}`;
+  const password = randomBytes(24).toString("hex");
+  let roleCreated = false;
+  let prisma: PrismaClient | undefined;
+  let app:
+    | Awaited<ReturnType<typeof NestFactory.createApplicationContext>>
+    | undefined;
+  try {
+    await admin.query(
+      await readFile(resolve(__dirname, "../../sql/tenancy.sql"), "utf8"),
+    );
+    // Identifiers and credentials here consist exclusively of generated hex.
+    await admin.query(`CREATE ROLE ${role} LOGIN PASSWORD '${password}'
+      NOSUPERUSER NOCREATEDB NOCREATEROLE NOINHERIT NOBYPASSRLS`);
+    roleCreated = true;
+    await admin.query(`
+      GRANT USAGE ON SCHEMA public TO ${role};
+      GRANT SELECT ON public.nestarc_inbox_schema TO ${role};
+      GRANT SELECT, INSERT, UPDATE ON public.nestarc_inbox TO ${role};
+      GRANT SELECT, INSERT, UPDATE ON public.example_tenancy_records TO ${role};
+      GRANT SELECT, INSERT ON public.example_tenancy_shared TO ${role};
+    `);
+    const appUrl = new URL(exampleDatabaseUrl());
+    appUrl.username = role;
+    appUrl.password = password;
+    const client = new PrismaClient({
+      adapter: new PrismaPg({ connectionString: appUrl.toString(), max: 1 }),
+    });
+    prisma = client;
+    const tenancyModule = TenancyModule.forRoot({
+      tenantExtractor: "x-tenant-id",
+    });
+
+    @Module({
+      imports: [
+        tenancyModule,
+        InboxModule.forRootAsync({
+          imports: [tenancyModule],
+          inject: [TenancyService],
+          useFactory: (tenancy: TenancyService) => {
+            // TenancyModule exports the configured service, but not the context
+            // provider. Public TenancyContext instances share the package's ALS.
+            const context = new TenancyContext();
+            const handler: InboxHandler<Payload, Prisma.TransactionClient> = {
+              consumer,
+              eventType,
+              schemaVersion: 1,
+              async handle(payload, ctx) {
+                if (ctx.scope.kind === "global") {
+                  assert.equal(tenancy.getCurrentTenant(), null);
+                  assert.deepEqual(
+                    await ctx.tx.$queryRawUnsafe(
+                      "SELECT * FROM public.example_tenancy_records",
+                    ),
+                    [],
+                  );
+                  await ctx.tx.$executeRawUnsafe(
+                    "INSERT INTO public.example_tenancy_shared VALUES ($1::uuid, $2::uuid)",
+                    randomUUID(),
+                    ctx.inboxId,
+                  );
+                  return;
+                }
+                assert.equal(tenancy.getCurrentTenantOrThrow(), ctx.scope.id);
+                const rows = await ctx.tx.$queryRawUnsafe<
+                  Array<{ tenant_id: string }>
+                >("SELECT tenant_id FROM public.example_tenancy_records");
+                const tenantId = ctx.scope.id;
+                assert.ok(rows.every((row) => row.tenant_id === tenantId));
+                // Deliberately use the payload value so the forged fixture below
+                // demonstrates the database's WITH CHECK policy rejecting it.
+                await ctx.tx.$executeRawUnsafe(
+                  "INSERT INTO public.example_tenancy_records VALUES ($1::uuid, $2, $3::uuid, 'handled')",
+                  randomUUID(),
+                  payload.targetTenant,
+                  ctx.inboxId,
+                );
+              },
+            };
+            return {
+              prisma: client,
+              handlers: [handler],
+              handlerContext: createInboxTenancyContext({
+                context,
+                tenancy,
+                global: "shared",
+              }),
+              worker: { enabled: false, concurrency: 1, maxAttempts: 1 },
+            };
+          },
+        }),
+      ],
+    })
+    class AppModule {}
+    app = await NestFactory.createApplicationContext(AppModule, {
+      logger: ["error", "warn"],
+      abortOnError: false,
+    });
+    const inbox = app.get(InboxService);
+    const tenancy = app.get(TenancyService);
+    const runId = randomUUID();
+    const tenantA = `${runId}-a`;
+    const tenantB = `${runId}-b`;
+    const accept = (scope: InboxScope, targetTenant: string) =>
+      inbox.accept({
+        scope,
+        source: "trusted-fixture-route",
+        consumer,
+        messageId: randomUUID(),
+        eventType,
+        schemaVersion: 1,
+        payload: { targetTenant },
+      });
+    // Scope comes from trusted routing. A producer payload cannot choose its scope.
+    const accepted = await Promise.all([
+      accept({ kind: "tenant", id: tenantA }, tenantA),
+      accept({ kind: "tenant", id: tenantB }, tenantB),
+      accept({ kind: "tenant", id: tenantA }, tenantB),
+      accept({ kind: "global" }, ""),
+    ]);
+    for (let i = 0; i < accepted.length; i++) await inbox.runOnce();
+    const results = await Promise.all(
+      accepted.map(async (receipt) => {
+        const result = await admin.query<{ status: string }>(
+          "SELECT status FROM public.nestarc_inbox WHERE id=$1",
+          [receipt.id],
+        );
+        return result.rows[0].status;
+      }),
+    );
+    assert.deepEqual(results, ["COMPLETED", "COMPLETED", "DEAD", "COMPLETED"]);
+    const rejected = await admin.query(
+      "SELECT * FROM public.example_tenancy_records WHERE inbox_id=$1",
+      [accepted[2].id],
+    );
+    assert.equal(rejected.rowCount, 0);
+    assert.equal(tenancy.getCurrentTenant(), null);
+    const [setting] = await client.$queryRawUnsafe<
+      Array<{ tenant: string | null }>
+    >(
+      "SELECT NULLIF(current_setting('app.current_tenant', true), '') AS tenant",
+    );
+    assert.equal(setting.tenant, null);
+    const [permissions] = await client.$queryRawUnsafe<
+      Array<{ rolsuper: boolean; rolbypassrls: boolean }>
+    >("SELECT rolsuper, rolbypassrls FROM pg_roles WHERE rolname=current_user");
+    assert.equal(permissions.rolsuper, false);
+    assert.equal(permissions.rolbypassrls, false);
+    console.log(
+      JSON.stringify({
+        tenantsCompleted: 2,
+        crossTenantWrite: "rejected",
+        globalShared: "completed",
+        contextAfterProcessing: null,
+      }),
+    );
+  } finally {
+    try {
+      await app?.close();
+    } finally {
+      try {
+        await prisma?.$disconnect();
+      } finally {
+        try {
+          if (roleCreated)
+            await admin.query(`DROP OWNED BY ${role}; DROP ROLE ${role}`);
+        } finally {
+          await admin.end();
+        }
+      }
+    }
+  }
+}
+
+void main().catch((error: unknown) => {
+  console.error(error);
+  process.exitCode = 1;
+});