@nestarc/inbox 0.0.0-stage → 0.1.0

package/examples/README.md

@@ -0,0 +1,124 @@
+# Runnable inbox examples
+
+These examples import the installed `@nestarc/inbox` package and use a real PostgreSQL database. The outbox and webhook examples run once, assert their results, and exit. The RabbitMQ example additionally requires the local broker fixture.
+
+Use Node 22.23.4+ or 24.22.1+ for the full examples project because it includes `@nestarc/tenancy` 0.16.2. The package's full `npm run test:examples` command builds a tarball, installs these examples in an isolated directory, and executes every example against temporary fixtures.
+
+## Install the package
+
+Run these commands from `examples/`:
+
+```sh
+npm install --no-save @nestarc/inbox@0.1.0
+npm run generate
+npm run build
+```
+
+To run against a local source build instead, run `npm ci` and `npm pack` from the repository root. Then, from `examples/`, install the tarball and regenerate/build:
+
+```sh
+npm install --no-save ../nestarc-inbox-0.1.0.tgz
+npm run generate
+npm run build
+```
+
+The automated test runners always install the tarball built from the checkout, so they exercise the exact candidate artifact. Prisma 7.10.1 uses the PostgreSQL driver adapter and the generated client in `src/generated/prisma`. Version 0.1.0 uses schema v2 and the runtime implementation validated under the local Preview.1 development version.
+
+## Start a dedicated database
+
+```sh
+docker compose -p nestarc-inbox-examples up -d --wait postgres
+export INBOX_EXAMPLE_DATABASE_URL='postgresql://example:example@127.0.0.1:55434/inbox_examples'
+npm run db:prepare
+```
+
+`db:prepare` applies the installed inbox and outbox SQL assets plus the example application tables. It only accepts a loopback database named `inbox_examples` or `inbox_examples_<suffix>`. It does not run Prisma schema synchronization: the package tables are owned by their SQL migrations and are absent from the example Prisma schema.
+
+The Compose database uses temporary storage. Stopping the container discards this fixture. Do not use these commands against an application database.
+
+## Outbox to inbox and downstream delivery
+
+```sh
+npm run outbox
+```
+
+The application commits an order and an outbox event together. A local outbox listener durably accepts that event into Inbox. Its Inbox handler creates a projection and another outbox event in the same transaction. A second Inbox consumer stores the downstream receipt. Repeating the first input returns `duplicate`.
+
+Expected stable output:
+
+```json
+{ "projections": 1, "downstreamReceipts": 1, "duplicateReplay": "duplicate" }
+```
+
+No email or external HTTP call is made. `OutboxEmitter` receives the exact transaction supplied by Inbox. Independent consumers have independent durable identities.
+
+## RabbitMQ ingress
+
+```sh
+docker compose -p nestarc-inbox-examples up -d --wait rabbitmq
+export INBOX_EXAMPLE_AMQP_URL='amqp://guest:guest@127.0.0.1:55672'
+npm run rabbitmq
+```
+
+The example uses `noAck: false`, prefetch 1, publisher confirms, and durable queues. It publishes two copies with the same stable `messageId` and verifies one projection. ACK follows `accept()` success. The broker delivery tag is never a deduplication key.
+
+Malformed input and identity conflicts go to the run's dead-letter queue. Transient failures before acceptance enter a one-second TTL retry queue, up to three retries. A failed retry publish retains/requeues the original delivery after a pause. Once accepted, handler retries belong solely to Inbox. Each run creates uniquely named fixture queues so unrelated broker data is not changed.
+
+The source and tenant come from trusted route configuration in this fixture. Production applications must authenticate the broker connection and map routes/accounts to tenants themselves.
+
+## Signed webhook ingress
+
+```sh
+export INBOX_EXAMPLE_WEBHOOK_SECRET="$(node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))")"
+npm run webhook
+```
+
+The example starts an HTTP server on an ephemeral loopback port and sends local fixture requests. It signs raw bytes with a timestamp, checks the HMAC using a constant-time comparison, rejects stale timestamps, and limits the request body. The server maps the authenticated account to a tenant; it never accepts a tenant chosen by the payload.
+
+It asserts that an invalid signature returns 401, the first valid event returns 202, a duplicate returns 200, and the projection appears once. HTTP success means durable acceptance. It does not mean the business handler has already completed.
+
+This HMAC convention is a local example. For a real provider, use that provider's documented raw-body signature and account verification protocol before calling Inbox.
+
+## Cleanup
+
+```sh
+docker compose -p nestarc-inbox-examples down
+```
+
+The examples close the Nest application before disconnecting the application-owned Prisma client. Database rows can remain across repeated runs while the fixture is running; every run uses fresh event and business IDs.
+
+## Kafka, SQS-compatible, and BullMQ ingress
+
+The repository runner supplies isolated Redpanda (Kafka protocol), Redis, and ElasticMQ (SQS protocol) containers, bound to loopback ports:
+
+```sh
+# After installing Inbox in examples/, run from the repository root:
+node examples/scripts/with-brokers.cjs
+```
+
+It also creates a disposable PostgreSQL database. Each ingress publishes distinct transport deliveries with the same stable producer event ID, injects one pre-acceptance storage failure and one handler failure, checks permanent-input rejection, and asserts one business projection. Only containers created by the runner are removed. The pinned fixtures are Redpanda v26.2.6, Redis 7.4.2, and ElasticMQ 1.7.1. ElasticMQ validates SQS API composition locally; this does not certify AWS IAM, service limits, network failures, or production SQS behavior.
+
+| Example          | Acknowledgment boundary                                                                                                    | Failure handling                                                                                                                                        |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `npm run kafka`  | Commit the next offset only after durable acceptance or confirmed dead-letter publish; process each partition sequentially | Bounded acceptance retries, then confirmed dead-letter publishing before offset advancement; a failed dead-letter publish leaves the offset uncommitted |
+| `npm run sqs`    | Delete the delivery only after durable acceptance or confirmed quarantine publish                                          | Failed acceptance retains the message for redelivery; receive-count limit directs repeated failures to the fixture's dead-letter queue                  |
+| `npm run bullmq` | Return from the queue processor only after durable acceptance                                                              | BullMQ attempts/backoff handle pre-acceptance failures; permanent input failures are retained as unrecoverable jobs                                     |
+
+The individual commands use `INBOX_EXAMPLE_KAFKA_BROKER`, `INBOX_EXAMPLE_SQS_ENDPOINT`, and `INBOX_EXAMPLE_REDIS_URL` provided by the runner. They require local fixture services. Kafka offsets, SQS receipt handles, and BullMQ job IDs are transport state, not the durable event identity. After acceptance, Inbox handles business retries independently of the transport.
+
+## Tenancy and HTTP idempotency composition
+
+`npm run tenancy` uses actual `TenancyModule`, `TenancyContext`, and `TenancyService` instances with `createInboxTenancyContext`. It creates a restricted PostgreSQL login role, applies the example RLS policies, and verifies tenant-specific reads/writes, cross-tenant rejection, transaction-local setting cleanup, and explicit global shared-table processing. Role creation is fixture setup performed with the dedicated example database owner; the handler role never bypasses RLS. Production policy/role provisioning remains an application migration responsibility.
+
+`npm run idempotency` uses actual `@nestarc/idempotency/postgres` storage at a local HTTP boundary. It verifies cached response replay and conflicting content, waits for the HTTP response record's real expiry, then resends the stable event ID. Inbox still returns `duplicate`, the durable content conflict still receives 422, and the business projection remains singular. HTTP response retention and Inbox receipt retention serve different lifetimes.
+
+## Automated fixture smoke checks
+
+After installing Inbox in `examples/`, run from the repository root:
+
+```sh
+node scripts/with-test-db.mjs node examples/scripts/smoke.cjs
+node examples/scripts/with-rabbitmq.cjs
+```
+
+The first command creates a disposable PostgreSQL instance and runs the outbox and webhook assertions. The second also creates a disposable RabbitMQ instance and runs all three. They remove only the containers they created. Missing Docker or an unhealthy fixture fails the command instead of skipping the checks. These repository runners are development tools; a copied package example can instead use the Compose setup above.

package/examples/compose.yaml

@@ -0,0 +1,26 @@
+services:
+  postgres:
+    image: postgres:16
+    environment:
+      POSTGRES_USER: example
+      POSTGRES_PASSWORD: example
+      POSTGRES_DB: inbox_examples
+    ports:
+      - "127.0.0.1:55434:5432"
+    tmpfs:
+      - /var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U example -d inbox_examples"]
+      interval: 1s
+      timeout: 3s
+      retries: 30
+  rabbitmq:
+    image: rabbitmq:4-management
+    ports:
+      - "127.0.0.1:55672:5672"
+      - "127.0.0.1:55673:15672"
+    healthcheck:
+      test: ["CMD", "rabbitmq-diagnostics", "-q", "ping"]
+      interval: 3s
+      timeout: 5s
+      retries: 30

package/examples/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "nestarc-inbox-examples",
+  "private": true,
+  "version": "0.0.0",
+  "scripts": {
+    "generate": "prisma generate --config prisma.config.ts",
+    "db:prepare": "node scripts/prepare-db.cjs",
+    "build": "tsc -p tsconfig.json",
+    "outbox": "node dist/outbox-to-inbox/main.js",
+    "rabbitmq": "node dist/rabbitmq-ingress/main.js",
+    "webhook": "node dist/webhook-ingress/main.js",
+    "kafka": "node dist/kafka-ingress/main.js",
+    "sqs": "node dist/sqs-ingress/main.js",
+    "bullmq": "node dist/bullmq-ingress/main.js",
+    "tenancy": "node dist/tenancy/main.js",
+    "idempotency": "node dist/idempotency-ingress/main.js"
+  },
+  "dependencies": {
+    "@nestarc/outbox": "0.4.0",
+    "@nestjs/common": "11.2.8",
+    "@nestjs/core": "11.2.8",
+    "@nestjs/schedule": "5.0.1",
+    "@prisma/adapter-pg": "7.10.1",
+    "@prisma/client": "7.10.1",
+    "amqplib": "0.10.9",
+    "pg": "8.23.1",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "7.8.2",
+    "@nestarc/tenancy": "0.16.2",
+    "kafkajs": "2.2.4",
+    "bullmq": "5.81.5",
+    "@aws-sdk/client-sqs": "3.1158.0",
+    "@nestarc/idempotency": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/amqplib": "0.10.8",
+    "@types/node": "24.19.2",
+    "prisma": "7.10.1",
+    "typescript": "5.9.3",
+    "@types/pg": "8.23.1"
+  }
+}

package/examples/prisma/schema.prisma

@@ -0,0 +1,29 @@
+generator client {
+  provider     = "prisma-client"
+  output       = "../src/generated/prisma"
+  moduleFormat = "cjs"
+}
+
+datasource db {
+  provider = "postgresql"
+}
+
+model ExampleOrder {
+  id       String @id
+  tenantId String @map("tenant_id")
+  @@map("inbox_example_orders")
+}
+
+model ExampleProjection {
+  tenantId String @map("tenant_id")
+  orderId  String @map("order_id")
+  @@id([tenantId, orderId])
+  @@map("inbox_example_projections")
+}
+
+model ExampleReceipt {
+  tenantId String @map("tenant_id")
+  orderId  String @map("order_id")
+  @@id([tenantId, orderId])
+  @@map("inbox_example_receipts")
+}

package/examples/prisma.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "prisma/config";
+
+export default defineConfig({
+  schema: "prisma/schema.prisma",
+  datasource: {
+    url:
+      process.env.INBOX_EXAMPLE_DATABASE_URL ??
+      "postgresql://example:example@127.0.0.1:55434/inbox_examples",
+  },
+});

package/examples/scripts/prepare-db.cjs

@@ -0,0 +1,45 @@
+const { readFileSync } = require("node:fs");
+const { join } = require("node:path");
+const { Client } = require("pg");
+
+async function main() {
+  const connectionString = process.env.INBOX_EXAMPLE_DATABASE_URL;
+  if (!connectionString)
+    throw new Error(
+      "Set INBOX_EXAMPLE_DATABASE_URL to the dedicated local fixture.",
+    );
+  const url = new URL(connectionString);
+  const isolatedTest =
+    process.env.INBOX_TEST_DATABASE === "1" &&
+    process.env.INBOX_TEST_DATABASE_URL === connectionString &&
+    process.env.INBOX_TEST_DATABASE_NAME === url.pathname.slice(1) &&
+    /^\/nestarc_inbox_test_[a-f0-9]{16}$/.test(url.pathname) &&
+    url.username === "inbox_test";
+  if (
+    !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname) ||
+    (!/^\/inbox_examples(?:_[a-zA-Z0-9_]+)?$/.test(url.pathname) &&
+      !isolatedTest)
+  ) {
+    throw new Error(
+      "Examples only prepare a local database named inbox_examples or inbox_examples_<suffix>.",
+    );
+  }
+  const client = new Client({ connectionString });
+  await client.connect();
+  try {
+    for (const path of [
+      require.resolve("@nestarc/inbox/sql/create-inbox-table.sql"),
+      require.resolve("@nestarc/outbox/src/sql/create-outbox-table.sql"),
+      join(__dirname, "../sql/application.sql"),
+    ]) {
+      await client.query(readFileSync(path, "utf8"));
+    }
+    console.log("Prepared the dedicated inbox example database.");
+  } finally {
+    await client.end();
+  }
+}
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/examples/scripts/smoke.cjs

@@ -0,0 +1,37 @@
+const { spawnSync } = require("node:child_process");
+const { randomBytes } = require("node:crypto");
+const { resolve } = require("node:path");
+
+if (
+  process.env.INBOX_TEST_DATABASE !== "1" ||
+  !process.env.INBOX_TEST_DATABASE_URL
+) {
+  throw new Error(
+    "Run through scripts/with-test-db.mjs so only a disposable database is used.",
+  );
+}
+const env = {
+  ...process.env,
+  INBOX_EXAMPLE_DATABASE_URL: process.env.INBOX_TEST_DATABASE_URL,
+  INBOX_EXAMPLE_WEBHOOK_SECRET: randomBytes(32).toString("hex"),
+};
+const steps = [
+  "generate",
+  "build",
+  "db:prepare",
+  "outbox",
+  "webhook",
+  "tenancy",
+  "idempotency",
+];
+if (process.argv.includes("--rabbitmq")) steps.push("rabbitmq");
+if (process.argv.includes("--brokers")) steps.push("kafka", "sqs", "bullmq");
+for (const step of steps) {
+  const result = spawnSync("npm", ["run", step], {
+    cwd: resolve(__dirname, ".."),
+    env,
+    stdio: "inherit",
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) process.exit(result.status ?? 1);
+}

package/examples/scripts/with-brokers.cjs

@@ -0,0 +1,249 @@
+const { spawn } = require("node:child_process");
+const { randomBytes } = require("node:crypto");
+const { createServer } = require("node:net");
+const { resolve } = require("node:path");
+const { setTimeout } = require("node:timers/promises");
+
+const root = resolve(__dirname, "../..");
+const images = {
+  kafka: "docker.redpanda.com/redpandadata/redpanda:v26.2.6",
+  redis: "redis:7.4.2-alpine",
+  sqs: "softwaremill/elasticmq-native:1.7.1",
+};
+
+function capture(command, args) {
+  return new Promise((done, reject) => {
+    const process = spawn(command, args, { cwd: root });
+    let output = "";
+    let error = "";
+    process.stdout.on("data", (chunk) => {
+      output += chunk;
+    });
+    process.stderr.on("data", (chunk) => {
+      error += chunk;
+    });
+    process.on("error", reject);
+    process.on("close", (code) =>
+      code === 0
+        ? done(output.trim())
+        : reject(new Error(`${command} failed: ${error || output}`)),
+    );
+  });
+}
+
+async function unusedLoopbackPort() {
+  const server = createServer();
+  return new Promise((done, reject) => {
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const port = server.address().port;
+      server.close((error) => (error ? reject(error) : done(port)));
+    });
+  });
+}
+
+/** Each call owns and removes only the container IDs it creates. */
+async function withBrokers(run) {
+  const containers = [];
+  let interrupted;
+  const onSignal = (signal) => {
+    interrupted = signal;
+  };
+  const onInt = () => onSignal("SIGINT");
+  const onTerm = () => onSignal("SIGTERM");
+  process.on("SIGINT", onInt);
+  process.on("SIGTERM", onTerm);
+  const checkInterrupted = () => {
+    if (interrupted) throw new Error(`Interrupted by ${interrupted}`);
+  };
+  async function create(kind, args) {
+    checkInterrupted();
+    const id = await capture("docker", [
+      "create",
+      "--name",
+      `nestarc-inbox-${kind}-${randomBytes(8).toString("hex")}`,
+      "--label",
+      "dev.nestarc.inbox.fixture=true",
+      ...args,
+    ]);
+    if (!/^[a-f0-9]{64}$/.test(id))
+      throw new Error("Unexpected fixture container identity");
+    containers.push(id);
+    checkInterrupted();
+    await capture("docker", ["start", id]);
+    return id;
+  }
+  async function binding(id, port) {
+    const result = await capture("docker", ["port", id, `${port}/tcp`]);
+    if (!/^127\.0\.0\.1:\d+$/.test(result))
+      throw new Error("Broker must have one loopback port binding");
+    return result;
+  }
+  async function ready(label, probe) {
+    const deadline = Date.now() + 60_000;
+    let lastError;
+    while (Date.now() < deadline) {
+      checkInterrupted();
+      try {
+        await probe();
+        return;
+      } catch (error) {
+        lastError = error;
+        await setTimeout(300);
+      }
+    }
+    throw new Error(
+      `${label} fixture did not become ready: ${String(lastError)}`,
+    );
+  }
+  try {
+    await capture("docker", ["info", "--format", "{{.ServerVersion}}"]);
+    // Kafka metadata advertises the actual random host port. If another process
+    // acquires this port before Docker binds it, creation fails and cleans up.
+    const kafkaPort = await unusedLoopbackPort();
+    const kafkaId = await create("kafka", [
+      "--publish",
+      `127.0.0.1:${kafkaPort}:9092`,
+      images.kafka,
+      "redpanda",
+      "start",
+      "--mode",
+      "dev-container",
+      "--smp",
+      "1",
+      "--memory",
+      "1G",
+      "--reserve-memory",
+      "0M",
+      "--kafka-addr",
+      "0.0.0.0:9092",
+      "--advertise-kafka-addr",
+      `127.0.0.1:${kafkaPort}`,
+    ]);
+    const redisId = await create("redis", [
+      "--publish",
+      "127.0.0.1::6379",
+      "--tmpfs",
+      "/data",
+      images.redis,
+    ]);
+    const sqsId = await create("sqs", [
+      "--publish",
+      "127.0.0.1::9324",
+      images.sqs,
+    ]);
+    const kafkaBroker = await binding(kafkaId, 9092);
+    const redisBroker = await binding(redisId, 6379);
+    const sqsEndpoint = `http://${await binding(sqsId, 9324)}`;
+    const { Kafka, logLevel } = require("kafkajs");
+    await ready("Kafka", async () => {
+      const admin = new Kafka({
+        brokers: [kafkaBroker],
+        logLevel: logLevel.NOTHING,
+        connectionTimeout: 1_000,
+        requestTimeout: 2_000,
+        retry: { retries: 0 },
+      }).admin();
+      try {
+        await admin.connect();
+        await admin.listTopics();
+      } finally {
+        await admin.disconnect();
+      }
+    });
+    await ready("Redis", async () => {
+      if (
+        (await capture("docker", ["exec", redisId, "redis-cli", "ping"])) !==
+        "PONG"
+      )
+        throw new Error("Redis did not respond PONG");
+    });
+    const { SQSClient, ListQueuesCommand } = require("@aws-sdk/client-sqs");
+    const sqs = new SQSClient({
+      endpoint: sqsEndpoint,
+      region: "us-east-1",
+      credentials: { accessKeyId: "local", secretAccessKey: "local" },
+      maxAttempts: 1,
+      requestHandler: { connectionTimeout: 1_000, requestTimeout: 2_000 },
+    });
+    try {
+      await ready("ElasticMQ", () => sqs.send(new ListQueuesCommand({})));
+    } finally {
+      sqs.destroy();
+    }
+    checkInterrupted();
+    console.log(
+      "Disposable Kafka (Redpanda), Redis, and SQS-compatible ElasticMQ fixtures ready.",
+    );
+    return await run({
+      INBOX_EXAMPLE_KAFKA_BROKER: kafkaBroker,
+      INBOX_EXAMPLE_REDIS_URL: `redis://${redisBroker}`,
+      INBOX_EXAMPLE_SQS_ENDPOINT: sqsEndpoint,
+    });
+  } catch (error) {
+    for (const id of containers) {
+      try {
+        console.error(await capture("docker", ["logs", "--tail", "20", id]));
+      } catch {
+        /* preserve the original test failure */
+      }
+    }
+    throw error;
+  } finally {
+    process.removeListener("SIGINT", onInt);
+    process.removeListener("SIGTERM", onTerm);
+    const results = await Promise.allSettled(
+      containers.map((id) =>
+        capture("docker", ["rm", "--force", "--volumes", id]),
+      ),
+    );
+    for (const result of results) {
+      if (result.status === "rejected") {
+        console.error(`Fixture cleanup failed: ${result.reason}`);
+        process.exitCode = 1;
+      }
+    }
+  }
+}
+
+async function main() {
+  let child;
+  const onInt = () => child?.kill("SIGINT");
+  const onTerm = () => child?.kill("SIGTERM");
+  process.on("SIGINT", onInt);
+  process.on("SIGTERM", onTerm);
+  try {
+    await withBrokers(
+      (env) =>
+        new Promise((done, reject) => {
+          child = spawn(
+            process.execPath,
+            [
+              "scripts/with-test-db.mjs",
+              process.execPath,
+              "examples/scripts/smoke.cjs",
+              "--brokers",
+            ],
+            { cwd: root, env: { ...process.env, ...env }, stdio: "inherit" },
+          );
+          child.on("error", reject);
+          child.on("close", (code) => {
+            child = undefined;
+            code === 0
+              ? done()
+              : reject(new Error(`Broker examples exited ${code}`));
+          });
+        }),
+    );
+  } finally {
+    process.removeListener("SIGINT", onInt);
+    process.removeListener("SIGTERM", onTerm);
+  }
+}
+
+module.exports = { withBrokers };
+if (require.main === module)
+  main().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+  });