@nestarc/inbox 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,172 @@
+import assert from "node:assert/strict";
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { createServer, type IncomingMessage } from "node:http";
+import {
+  InboxConflictError,
+  InboxService,
+  InboxValidationError,
+} from "@nestarc/inbox";
+import { startInbox, tenantId, waitUntil } from "../common";
+
+const maxBytes = 16 * 1024;
+
+async function body(request: IncomingMessage): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of request) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += buffer.length;
+    if (size > maxBytes)
+      throw new InboxValidationError("Webhook body is too large.");
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks);
+}
+
+async function main() {
+  const secret = process.env.INBOX_EXAMPLE_WEBHOOK_SECRET;
+  if (!secret || Buffer.byteLength(secret) < 32) {
+    throw new Error(
+      "Set INBOX_EXAMPLE_WEBHOOK_SECRET to a random secret of at least 32 bytes.",
+    );
+  }
+  const fixture = await startInbox("example.webhook.v1", "order.created");
+  const inbox = fixture.app.get(InboxService);
+  const server = createServer((request, response) => {
+    void (async () => {
+      if (
+        request.method !== "POST" ||
+        request.url !== "/webhooks/example-account"
+      ) {
+        response.writeHead(404).end();
+        return;
+      }
+      const bytes = await body(request);
+      const timestamp = request.headers["x-example-timestamp"];
+      const signature = request.headers["x-example-signature"];
+      if (
+        typeof timestamp !== "string" ||
+        !/^\d{10}$/.test(timestamp) ||
+        Math.abs(Date.now() / 1000 - Number(timestamp)) > 300 ||
+        typeof signature !== "string" ||
+        !/^[a-f0-9]{64}$/.test(signature)
+      ) {
+        response.writeHead(401).end();
+        return;
+      }
+      const expected = createHmac("sha256", secret)
+        .update(timestamp)
+        .update(".")
+        .update(bytes)
+        .digest();
+      if (!timingSafeEqual(expected, Buffer.from(signature, "hex"))) {
+        response.writeHead(401).end();
+        return;
+      }
+      // Signature verification precedes JSON interpretation and tenant assignment.
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(bytes.toString("utf8"));
+      } catch {
+        response.writeHead(400).end();
+        return;
+      }
+      if (
+        !parsed ||
+        typeof parsed !== "object" ||
+        Array.isArray(parsed) ||
+        typeof (parsed as { id?: unknown }).id !== "string" ||
+        typeof (parsed as { orderId?: unknown }).orderId !== "string"
+      ) {
+        response.writeHead(400).end();
+        return;
+      }
+      const event = parsed as { id: string; orderId: string };
+      const result = await inbox.accept({
+        scope: { kind: "tenant", id: tenantId }, // server-side account → tenant mapping
+        source: "example-webhook-account",
+        consumer: "example.webhook.v1",
+        messageId: event.id,
+        eventType: "order.created",
+        schemaVersion: 1,
+        payload: { orderId: event.orderId },
+      });
+      response.writeHead(result.kind === "accepted" ? 202 : 200, {
+        "content-type": "application/json",
+      });
+      response.end(JSON.stringify({ kind: result.kind }));
+    })().catch((error: unknown) => {
+      const status =
+        error instanceof InboxConflictError
+          ? 409
+          : error instanceof InboxValidationError
+            ? 400
+            : 503;
+      if (!response.headersSent) response.writeHead(status);
+      response.end();
+    });
+  });
+  try {
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", () => {
+        server.off("error", reject);
+        resolve();
+      });
+    });
+    const address = server.address();
+    assert.ok(address && typeof address !== "string");
+    const url = `http://127.0.0.1:${address.port}/webhooks/example-account`;
+    const orderId = randomUUID();
+    const content = JSON.stringify({ id: randomUUID(), orderId });
+    const timestamp = String(Math.floor(Date.now() / 1000));
+    const signature = createHmac("sha256", secret)
+      .update(`${timestamp}.${content}`)
+      .digest("hex");
+    const headers = {
+      "content-type": "application/json",
+      "x-example-timestamp": timestamp,
+      "x-example-signature": signature,
+    };
+    const rejected = await fetch(url, {
+      method: "POST",
+      body: content,
+      headers: { ...headers, "x-example-signature": "0".repeat(64) },
+    });
+    assert.equal(rejected.status, 401);
+    await rejected.arrayBuffer();
+    const first = await fetch(url, { method: "POST", body: content, headers });
+    assert.equal(first.status, 202);
+    assert.deepEqual(await first.json(), { kind: "accepted" });
+    const duplicate = await fetch(url, {
+      method: "POST",
+      body: content,
+      headers,
+    });
+    assert.equal(duplicate.status, 200);
+    assert.deepEqual(await duplicate.json(), { kind: "duplicate" });
+    await waitUntil(
+      async () =>
+        (await fixture.prisma.exampleProjection.count({
+          where: { tenantId, orderId },
+        })) === 1,
+      "signed webhook projection",
+    );
+    console.log(
+      JSON.stringify({
+        invalidSignature: 401,
+        accepted: 202,
+        duplicate: 200,
+        projections: 1,
+      }),
+    );
+  } finally {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    await fixture.close();
+  }
+}
+
+void main().catch((error: unknown) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/examples/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "rootDir": "src",
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "skipLibCheck": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/package.json

@@ -1,6 +1,92 @@
 {
   "name": "@nestarc/inbox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Transactional inbox for NestJS, Prisma and PostgreSQL with durable deduplication, fenced processing and retries.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nestarc/inbox.git"
+  },
+  "homepage": "https://github.com/nestarc/inbox#readme",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./sql/create-inbox-table.sql": "./src/sql/create-inbox-table.sql",
+    "./sql/migrate-v1-to-v2.sql": "./src/sql/migrate-v1-to-v2.sql"
+  },
+  "files": [
+    "dist",
+    "src/sql",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "docs",
+    "examples",
+    "!examples/node_modules",
+    "!examples/dist",
+    "!examples/src/generated",
+    "!examples/package-lock.json"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "pretypecheck": "prisma generate --config test/prisma/prisma.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run test/unit",
+    "test:release": "node --test test/release/*.test.mjs",
+    "test:integration": "node scripts/with-test-db.mjs npm run test:integration:run",
+    "test:integration:run": "vitest run test/integration test/failure",
+    "test:package": "node scripts/with-test-db.mjs node scripts/test-package.mjs",
+    "test:examples": "node scripts/with-test-db.mjs node scripts/test-examples.mjs",
+    "prebenchmark": "npm run build",
+    "benchmark": "node scripts/with-test-db.mjs node scripts/benchmark.mjs",
+    "format": "prettier --write src test scripts .github/workflows README.md CHANGELOG.md docs/usage.md docs/releasing.md package.json tsconfig*.json vitest.config.mts",
+    "format:check": "prettier --check src test scripts .github/workflows README.md CHANGELOG.md docs/usage.md docs/releasing.md package.json tsconfig*.json vitest.config.mts",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.2.8",
+    "@nestjs/core": "^11.2.8",
+    "@prisma/client": "^7.10.1",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
+    "@nestarc/tenancy": "^0.16.2"
+  },
+  "devDependencies": {
+    "@nestjs/common": "11.2.8",
+    "@nestjs/core": "11.2.8",
+    "@nestjs/testing": "11.2.8",
+    "@prisma/adapter-pg": "7.10.1",
+    "@prisma/client": "7.10.1",
+    "@types/node": "24.19.2",
+    "@types/pg": "8.23.1",
+    "pg": "8.23.1",
+    "prettier": "3.8.3",
+    "prisma": "7.10.1",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "7.8.2",
+    "tsx": "4.23.15",
+    "typescript": "5.9.3",
+    "vitest": "5.0.5",
+    "@nestarc/tenancy": "0.16.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "peerDependenciesMeta": {
+    "@nestarc/tenancy": {
+      "optional": true
+    }
+  },
+  "workspaces": [
+    "src/internal/reliability-core"
+  ]
+}

package/src/sql/create-inbox-table.sql

@@ -0,0 +1,100 @@
+-- @nestarc/inbox schema version 2. Run explicitly with your application's migrations.
+-- Existing version 1 installations must apply migrate-v1-to-v2.sql instead.
+-- Runtime never creates or upgrades tables. Do not let Prisma db push remove these tables.
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS public.nestarc_inbox_schema (
+  singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton),
+  version integer NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS public.nestarc_inbox (
+  id uuid PRIMARY KEY,
+  scope_kind text NOT NULL CHECK (scope_kind IN ('tenant', 'global')),
+  scope_id text NOT NULL,
+  source text NOT NULL CHECK (octet_length(source) BETWEEN 1 AND 128),
+  consumer text NOT NULL CHECK (octet_length(consumer) BETWEEN 1 AND 128),
+  message_id text NOT NULL CHECK (octet_length(message_id) BETWEEN 1 AND 256),
+  event_type text NOT NULL CHECK (octet_length(event_type) BETWEEN 1 AND 128),
+  schema_version integer NOT NULL CHECK (schema_version > 0),
+  payload jsonb,
+  payload_purged boolean NOT NULL DEFAULT false,
+  fingerprint text NOT NULL CHECK (fingerprint ~ '^[0-9a-f]{64}$'),
+  fingerprint_version integer NOT NULL CHECK (fingerprint_version = 1),
+  status text NOT NULL DEFAULT 'PENDING'
+    CHECK (status IN ('PENDING', 'PROCESSING', 'RETRYABLE', 'COMPLETED', 'DEAD')),
+  claim_token bigint NOT NULL DEFAULT 0 CHECK (claim_token >= 0),
+  row_version bigint NOT NULL DEFAULT 1 CHECK (row_version > 0),
+  attempt_count integer NOT NULL DEFAULT 0 CHECK (attempt_count >= 0),
+  cycle_attempt_count integer NOT NULL DEFAULT 0 CHECK (cycle_attempt_count >= 0),
+  requeue_count integer NOT NULL DEFAULT 0 CHECK (requeue_count >= 0),
+  received_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+  completed_at timestamptz,
+  next_attempt_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+  lease_expires_at timestamptz,
+  worker_id text,
+  last_error_code text,
+  last_error_message text,
+  last_requeue_reason text,
+  last_requeue_actor text,
+  last_requeue_at timestamptz,
+  correlation_id text,
+  causation_id text,
+  headers jsonb NOT NULL DEFAULT '{}'::jsonb,
+  replay_of uuid,
+  replay_request_id uuid,
+  replay_source_version bigint,
+  replay_actor text,
+  replay_reason text,
+  replayed_at timestamptz,
+  CONSTRAINT nestarc_inbox_identity_key
+    UNIQUE (scope_kind, scope_id, source, consumer, message_id),
+  CONSTRAINT nestarc_inbox_replay_request_key
+    UNIQUE (scope_kind, scope_id, replay_request_id),
+  CONSTRAINT nestarc_inbox_replay_original_fk
+    FOREIGN KEY (replay_of) REFERENCES public.nestarc_inbox(id),
+  CONSTRAINT nestarc_inbox_replay_check CHECK (
+    (replay_of IS NULL AND replay_request_id IS NULL AND replay_source_version IS NULL
+      AND replay_actor IS NULL AND replay_reason IS NULL AND replayed_at IS NULL) OR
+    (replay_of IS NOT NULL AND replay_of <> id AND replay_request_id IS NOT NULL
+      AND replay_source_version IS NOT NULL AND replay_source_version > 0
+      AND replay_actor IS NOT NULL AND octet_length(replay_actor) BETWEEN 1 AND 256
+      AND replay_reason IS NOT NULL AND octet_length(replay_reason) BETWEEN 1 AND 1024
+      AND replayed_at IS NOT NULL)
+  ),
+  CONSTRAINT nestarc_inbox_scope_check CHECK (
+    (scope_kind = 'global' AND scope_id = '') OR
+    (scope_kind = 'tenant' AND octet_length(scope_id) BETWEEN 1 AND 128)
+  ),
+  CONSTRAINT nestarc_inbox_payload_check CHECK (
+    (payload_purged AND payload IS NULL AND status = 'COMPLETED') OR
+    (NOT payload_purged AND payload IS NOT NULL)
+  ),
+  CONSTRAINT nestarc_inbox_lease_check CHECK (
+    (status = 'PROCESSING' AND lease_expires_at IS NOT NULL AND worker_id IS NOT NULL) OR
+    (status <> 'PROCESSING' AND lease_expires_at IS NULL AND worker_id IS NULL)
+  ),
+  CONSTRAINT nestarc_inbox_completion_check CHECK (
+    (status = 'COMPLETED' AND completed_at IS NOT NULL) OR
+    (status <> 'COMPLETED' AND completed_at IS NULL)
+  )
+);
+
+CREATE INDEX IF NOT EXISTS nestarc_inbox_due_idx
+  ON public.nestarc_inbox (consumer, next_attempt_at, id)
+  WHERE status IN ('PENDING', 'RETRYABLE');
+CREATE INDEX IF NOT EXISTS nestarc_inbox_expired_idx
+  ON public.nestarc_inbox (consumer, lease_expires_at, id)
+  WHERE status = 'PROCESSING';
+CREATE INDEX IF NOT EXISTS nestarc_inbox_scope_list_idx
+  ON public.nestarc_inbox (scope_kind, scope_id, id);
+CREATE INDEX IF NOT EXISTS nestarc_inbox_completed_payload_idx
+  ON public.nestarc_inbox (completed_at, id)
+  WHERE status = 'COMPLETED' AND NOT payload_purged;
+CREATE INDEX IF NOT EXISTS nestarc_inbox_replay_original_idx
+  ON public.nestarc_inbox (replay_of) WHERE replay_of IS NOT NULL;
+
+INSERT INTO public.nestarc_inbox_schema (singleton, version)
+VALUES (true, 2) ON CONFLICT (singleton) DO NOTHING;
+
+COMMIT;

package/src/sql/migrate-v1-to-v2.sql

@@ -0,0 +1,53 @@
+-- Add completed-message replay lineage to an existing @nestarc/inbox v1 installation.
+-- Run explicitly during deployment before starting the v2 application. Transactional
+-- DDL preserves all receipts, fingerprints, processing state, and business writes.
+BEGIN;
+
+LOCK TABLE public.nestarc_inbox IN ACCESS EXCLUSIVE MODE;
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM public.nestarc_inbox_schema WHERE singleton = true AND version IN (1, 2)
+  ) THEN
+    RAISE EXCEPTION 'Expected inbox schema version 1 or 2';
+  END IF;
+END $$;
+
+ALTER TABLE public.nestarc_inbox
+  ADD COLUMN IF NOT EXISTS replay_of uuid,
+  ADD COLUMN IF NOT EXISTS replay_request_id uuid,
+  ADD COLUMN IF NOT EXISTS replay_source_version bigint,
+  ADD COLUMN IF NOT EXISTS replay_actor text,
+  ADD COLUMN IF NOT EXISTS replay_reason text,
+  ADD COLUMN IF NOT EXISTS replayed_at timestamptz;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint
+    WHERE conrelid='public.nestarc_inbox'::regclass AND conname='nestarc_inbox_replay_request_key') THEN
+    ALTER TABLE public.nestarc_inbox ADD CONSTRAINT nestarc_inbox_replay_request_key
+      UNIQUE (scope_kind, scope_id, replay_request_id);
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint
+    WHERE conrelid='public.nestarc_inbox'::regclass AND conname='nestarc_inbox_replay_original_fk') THEN
+    ALTER TABLE public.nestarc_inbox ADD CONSTRAINT nestarc_inbox_replay_original_fk
+      FOREIGN KEY (replay_of) REFERENCES public.nestarc_inbox(id);
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint
+    WHERE conrelid='public.nestarc_inbox'::regclass AND conname='nestarc_inbox_replay_check') THEN
+    ALTER TABLE public.nestarc_inbox ADD CONSTRAINT nestarc_inbox_replay_check CHECK (
+      (replay_of IS NULL AND replay_request_id IS NULL AND replay_source_version IS NULL
+        AND replay_actor IS NULL AND replay_reason IS NULL AND replayed_at IS NULL) OR
+      (replay_of IS NOT NULL AND replay_of <> id AND replay_request_id IS NOT NULL
+        AND replay_source_version IS NOT NULL AND replay_source_version > 0
+        AND replay_actor IS NOT NULL AND octet_length(replay_actor) BETWEEN 1 AND 256
+        AND replay_reason IS NOT NULL AND octet_length(replay_reason) BETWEEN 1 AND 1024
+        AND replayed_at IS NOT NULL)
+    );
+  END IF;
+END $$;
+
+CREATE INDEX IF NOT EXISTS nestarc_inbox_replay_original_idx
+  ON public.nestarc_inbox (replay_of) WHERE replay_of IS NOT NULL;
+UPDATE public.nestarc_inbox_schema SET version=2 WHERE singleton=true;
+COMMIT;