@adcp/sdk 14.0.0-beta.14 → 14.0.0-beta.15

package/dist/lib/server/decisioning/runtime/postgres-task-settlement.js

@@ -0,0 +1,391 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var postgres_task_settlement_exports = {};
+__export(postgres_task_settlement_exports, {
+  TaskPushSettlementConfigurationError: () => TaskPushSettlementConfigurationError,
+  completeScopedPushTask: () => completeScopedPushTask,
+  createPostgresTaskSettlementCoordinator: () => createPostgresTaskSettlementCoordinator,
+  failScopedPushTask: () => failScopedPushTask
+});
+module.exports = __toCommonJS(postgres_task_settlement_exports);
+var import_node_crypto = require("node:crypto");
+var import_jcs = require('../../../utils/jcs.js');
+var import_adcp_version_config = require('../../../utils/adcp-version-config.js');
+var import_errors = require('../../errors.js');
+var import_common = require('../../webhook-delivery/common.js');
+var import_recovery = require('../../webhook-delivery/recovery.js');
+var import_pg = require('../../webhook-delivery/pg.js');
+var import_protocol_for_tool = require('./protocol-for-tool.js');
+var import_postgres_task_registry = require('./postgres-task-registry.js');
+var import_task_registry = require('./task-registry.js');
+class TaskPushSettlementConfigurationError extends Error {
+  name = "TaskPushSettlementConfigurationError";
+}
+const TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "rejected", "canceled"]);
+const MAX_RESULT_BYTES = 4 * 1024 * 1024;
+const TOKEN_CONTROL_CHAR_RE = /[\x00-\x1f\x7f]/;
+function createPostgresTaskSettlementCoordinator(options) {
+  const binding = (0, import_postgres_task_registry._postgresTaskRegistryBinding)(options.registry);
+  if (!binding) {
+    throw new TypeError("createPostgresTaskSettlementCoordinator requires a registry from createPostgresTaskRegistry");
+  }
+  const pool = binding.pool;
+  if (typeof pool.connect !== "function") {
+    throw new TypeError(
+      "Crash-safe task settlement requires a pg Pool with connect(); a query-only adapter cannot own a transaction"
+    );
+  }
+  if (typeof options.registry.registryId !== "string" || options.registry.registryId.length === 0) {
+    throw new TypeError("Crash-safe task settlement requires task registry storageId/registryId binding");
+  }
+  if (typeof options.publisherScope !== "string" || options.publisherScope.length === 0) {
+    throw new TypeError("publisherScope must be a non-empty string");
+  }
+  const outboxOptions = options.outbox ?? {};
+  const outboxTable = (0, import_common.quoteWebhookTable)(outboxOptions.tableName ?? "adcp_webhook_outbox");
+  const claimScope = {
+    publisherScope: options.publisherScope,
+    tenantScope: stableRegistryScope(options.registry.registryId, binding.namespace)
+  };
+  const backend = (0, import_pg.pgWebhookDeliveryRecoveryBackend)(binding.pool, { ...outboxOptions, claimScope });
+  const recovery = (0, import_recovery.createWebhookDeliveryRecovery)({
+    ...options.recovery,
+    backend,
+    ...options.authenticationAdapter && { authenticationAdapter: options.authenticationAdapter }
+  });
+  const retries = resolveRetries(options.retries);
+  return {
+    durability: "durable",
+    recovery,
+    async settle(ref, terminal, push) {
+      if (ref.registryId !== options.registry.registryId) {
+        return { outcome: "not_found_in_scope", delivery: "not_applicable" };
+      }
+      let client;
+      try {
+        client = await pool.connect();
+        await client.query("BEGIN");
+        const locked = await client.query(
+          `SELECT tool, status, result, error, has_webhook
+             FROM ${binding.tableName}
+            WHERE task_id = $1 AND registry_namespace = $2 AND account_id = $3 AND owner_scope = $4
+            FOR UPDATE`,
+          [ref.taskId, binding.namespace, ref.accountId, ref.ownerScope]
+        );
+        if (locked.rows.length === 0) {
+          await client.query("ROLLBACK");
+          return { outcome: "not_found_in_scope", delivery: "not_applicable" };
+        }
+        const row = locked.rows[0];
+        validatePush(push);
+        if (row.has_webhook !== true) {
+          throw new TaskPushSettlementConfigurationError(
+            "Crash-safe push settlement requires a task created with hasWebhook: true"
+          );
+        }
+        let result;
+        let error;
+        try {
+          result = terminal.status === "completed" ? (0, import_task_registry.sanitizeTaskResultForWire)(structuredClone(terminal.result), ref) : terminal.result === void 0 ? { errors: [(0, import_errors.sanitizeStructuredAdcpError)(terminal.error)] } : (0, import_task_registry.sanitizeTaskResultForWire)(structuredClone(terminal.result), ref);
+          error = terminal.status === "failed" ? (0, import_errors.sanitizeStructuredAdcpError)(terminal.error) : void 0;
+          (0, import_jcs.canonicalJsonSha256)({ result, error });
+          assertPayloadSize(result, error);
+        } catch (cause) {
+          if (cause instanceof TaskPushSettlementConfigurationError) throw cause;
+          throw new TaskPushSettlementConfigurationError("Task terminal result/error must be serializable JSON", {
+            cause
+          });
+        }
+        const compatible = terminalMatches(row, terminal.status, result, error);
+        if (TERMINAL.has(row.status) && !compatible) {
+          await client.query("COMMIT");
+          return {
+            outcome: "already_terminal",
+            status: row.status,
+            compatibility: "conflicting",
+            delivery: "not_applicable"
+          };
+        }
+        const deliveryKey = {
+          ...claimScope,
+          deliveryId: stableScope("task-webhook", ref)
+        };
+        const existing = await readOutbox(client, outboxTable, deliveryKey);
+        if (TERMINAL.has(row.status) && !existing) {
+          throw new TaskPushSettlementConfigurationError(
+            "Terminal task has no atomic webhook delivery checkpoint; refusing to create a duplicate notification"
+          );
+        }
+        let inserted = false;
+        let delivery = existing ? deliveryState(existing) : void 0;
+        if (!import_protocol_for_tool.SPEC_WEBHOOK_TASK_TYPES.has(row.tool)) {
+          throw new TaskPushSettlementConfigurationError(
+            `Task type ${row.tool} cannot be emitted by the closed AdCP task-webhook schema`
+          );
+        }
+        const existingTimestamp = existing?.state === "pending" ? existing.snapshot.payload.timestamp : void 0;
+        const payload = {
+          idempotency_key: `pending.${deliveryKey.deliveryId.slice(-48)}`,
+          operation_id: resolveOperationId(push, row.tool, ref.taskId),
+          task_id: ref.taskId,
+          task_type: row.tool,
+          status: terminal.status,
+          timestamp: typeof existingTimestamp === "string" ? existingTimestamp : (/* @__PURE__ */ new Date()).toISOString(),
+          protocol: (0, import_protocol_for_tool.protocolForTool)(row.tool),
+          result,
+          ...push.token !== void 0 && { token: push.token },
+          ...terminal.status === "failed" && { message: error.message }
+        };
+        let prepared;
+        try {
+          prepared = await recovery.prepare(
+            deliveryKey,
+            {
+              url: push.url,
+              payload,
+              authentication: push.authentication ?? null,
+              retries
+            },
+            { protectPayloadToken: push.token !== void 0 }
+          );
+        } catch (cause) {
+          if (cause instanceof import_recovery.WebhookAuthenticationProtectionError) throw cause;
+          throw new TaskPushSettlementConfigurationError("Terminal webhook delivery configuration is invalid", {
+            cause
+          });
+        }
+        const intentFingerprint = taskPushIntentFingerprint(prepared.snapshot);
+        if (existing?.state === "settled") {
+          if (!TERMINAL.has(row.status)) {
+            throw new Error("Settled webhook outbox row exists for a non-terminal task");
+          }
+          if (existing.intent_fingerprint && existing.intent_fingerprint !== intentFingerprint) {
+            throw new TaskPushSettlementConfigurationError(
+              "Terminal webhook delivery identity is already bound to a conflicting route or payload"
+            );
+          }
+          await client.query("COMMIT");
+          return {
+            outcome: "already_terminal",
+            status: row.status,
+            compatibility: "compatible",
+            delivery: deliveryState(existing)
+          };
+        }
+        if (existing && existing.snapshot_fingerprint !== prepared.snapshotFingerprint) {
+          throw new TaskPushSettlementConfigurationError(
+            "Terminal webhook delivery identity is already bound to a conflicting route or payload"
+          );
+        }
+        if (!existing) {
+          const write = await client.query(
+            `INSERT INTO ${outboxTable} (
+               publisher_scope, tenant_scope, delivery_id, snapshot, snapshot_fingerprint,
+               storage_fingerprint, intent_fingerprint, state, attempt_count, next_attempt_at
+             ) VALUES ($1, $2, $3, $4::jsonb, $5, $6, $7, 'pending', 0, clock_timestamp())
+             ON CONFLICT (publisher_scope, tenant_scope, delivery_id) DO NOTHING`,
+            [
+              deliveryKey.publisherScope,
+              deliveryKey.tenantScope,
+              deliveryKey.deliveryId,
+              JSON.stringify(prepared.snapshot),
+              prepared.snapshotFingerprint,
+              prepared.storageFingerprint,
+              intentFingerprint
+            ]
+          );
+          if ((write.rowCount ?? 0) !== 1) {
+            const raced = await readOutbox(client, outboxTable, deliveryKey);
+            if (!raced || raced.snapshot_fingerprint !== prepared.snapshotFingerprint) {
+              throw new TaskPushSettlementConfigurationError(
+                "Terminal webhook delivery identity is already bound to a conflicting route or payload"
+              );
+            }
+            delivery = deliveryState(raced);
+          } else {
+            inserted = true;
+            delivery = "durably_bound";
+          }
+        }
+        if (!TERMINAL.has(row.status)) {
+          const update = terminal.status === "completed" ? await client.query(
+            `UPDATE ${binding.tableName}
+                      SET status = 'completed', result = $5::jsonb, error = NULL,
+                          status_message = NULL, updated_at = clock_timestamp()
+                    WHERE task_id = $1 AND registry_namespace = $2 AND account_id = $3 AND owner_scope = $4`,
+            [ref.taskId, binding.namespace, ref.accountId, ref.ownerScope, JSON.stringify(result)]
+          ) : await client.query(
+            `UPDATE ${binding.tableName}
+                      SET status = 'failed', result = $5::jsonb, error = $6::jsonb,
+                          status_message = $7, updated_at = clock_timestamp()
+                    WHERE task_id = $1 AND registry_namespace = $2 AND account_id = $3 AND owner_scope = $4`,
+            [
+              ref.taskId,
+              binding.namespace,
+              ref.accountId,
+              ref.ownerScope,
+              JSON.stringify(result),
+              JSON.stringify(error),
+              error.message
+            ]
+          );
+          if ((update.rowCount ?? 0) !== 1) throw new Error("Task disappeared while holding its settlement lock");
+          await client.query("COMMIT");
+          return { outcome: "applied", delivery: "durably_bound" };
+        }
+        await client.query("COMMIT");
+        return {
+          outcome: "already_terminal",
+          status: row.status,
+          compatibility: "compatible",
+          delivery: inserted ? "durably_bound" : delivery ?? "recoverable"
+        };
+      } catch (cause) {
+        if (client) await rollbackQuietly(client);
+        if (cause instanceof TaskPushSettlementConfigurationError) throw cause;
+        throw new Error("PostgresTaskSettlementCoordinator.settle: transaction failed", { cause });
+      } finally {
+        client?.release();
+      }
+    }
+  };
+}
+async function completeScopedPushTask(coordinator, ref, push, result) {
+  return coordinator.settle(ref, { status: "completed", result }, push);
+}
+async function failScopedPushTask(coordinator, ref, push, error, result) {
+  return coordinator.settle(ref, { status: "failed", error, ...result !== void 0 && { result } }, push);
+}
+function terminalMatches(row, status, result, error) {
+  if (row.status !== status) return false;
+  return (0, import_jcs.canonicalJsonSha256)(row.result) === (0, import_jcs.canonicalJsonSha256)(result) && (status === "completed" || (0, import_jcs.canonicalJsonSha256)(row.error) === (0, import_jcs.canonicalJsonSha256)(error));
+}
+function stableScope(prefix, ref) {
+  const digest = (0, import_node_crypto.createHash)("sha256").update(JSON.stringify([ref.registryId, ref.accountId, ref.ownerScope, ref.taskId])).digest("hex");
+  return `${prefix}:${digest}`;
+}
+function stableRegistryScope(registryId, namespace) {
+  const digest = (0, import_node_crypto.createHash)("sha256").update(JSON.stringify([registryId, namespace])).digest("hex");
+  return `task-registry:${digest}`;
+}
+function taskPushIntentFingerprint(snapshot) {
+  const { timestamp: _generatedTimestamp, ...payload } = snapshot.payload;
+  return (0, import_jcs.canonicalJsonSha256)({
+    url: snapshot.url,
+    payload,
+    retries: snapshot.retries,
+    authentication: snapshot.authentication.kind === "none" ? { kind: "none" } : { kind: "protected", fingerprint: snapshot.authentication.fingerprint },
+    ...snapshot.payloadToken && { payloadToken: { fingerprint: snapshot.payloadToken.fingerprint } }
+  });
+}
+function validatePush(push) {
+  if (!push || typeof push !== "object") {
+    throw new TaskPushSettlementConfigurationError("push settlement config is required");
+  }
+  const allowHttp = process.env.NODE_ENV === "test" || process.env.NODE_ENV === "development" || process.env.ADCP_DECISIONING_ALLOW_HTTP_WEBHOOKS === "1";
+  let parsedUrl;
+  try {
+    parsedUrl = typeof push.url === "string" ? new URL(push.url) : void 0;
+  } catch {
+  }
+  if (parsedUrl === void 0 || parsedUrl.hostname.length === 0 || parsedUrl.username.length > 0 || parsedUrl.password.length > 0 || parsedUrl.protocol !== "https:" && !(allowHttp && parsedUrl.protocol === "http:")) {
+    throw new TaskPushSettlementConfigurationError(
+      "push settlement url must be a request-validated HTTPS destination (HTTP requires the development allowlist)"
+    );
+  }
+  if (push.operationId !== void 0 && (typeof push.operationId !== "string" || !/^[A-Za-z0-9_.:-]{1,255}$/.test(push.operationId))) {
+    throw new TaskPushSettlementConfigurationError("push settlement operationId must match /^[A-Za-z0-9_.:-]{1,255}$/");
+  }
+  if (push.operationId === void 0 && (!(0, import_adcp_version_config.isValidAdcpVersion)(push.servedAdcpVersion) || (0, import_adcp_version_config.isAdcpVersionAtLeast)(push.servedAdcpVersion, "3.2.0-beta.5"))) {
+    throw new TaskPushSettlementConfigurationError(
+      "push settlement operationId is required unless servedAdcpVersion is an explicit valid pre-3.2.0-beta.5 version"
+    );
+  }
+  if (push.token !== void 0 && (typeof push.token !== "string" || push.token.length < 16 || push.token.length > 4096 || TOKEN_CONTROL_CHAR_RE.test(push.token))) {
+    throw new TaskPushSettlementConfigurationError(
+      "push settlement token must be a string from 16 through 4096 characters"
+    );
+  }
+  if (push.authentication !== void 0 && push.authentication !== null) {
+    const authentication = push.authentication;
+    const validBearer = authentication.type === "bearer" && typeof authentication.token === "string" && authentication.token.length >= 32;
+    const validHmac = authentication.type === "hmac_sha256" && typeof authentication.secret === "string" && authentication.secret.length >= 32;
+    if (!validBearer && !validHmac) {
+      throw new TaskPushSettlementConfigurationError(
+        "push settlement authentication must be a WebhookAuthentication value"
+      );
+    }
+  }
+}
+function resolveOperationId(push, tool, taskId) {
+  return push.operationId ?? `${tool}.${taskId}`;
+}
+function resolveRetries(retries) {
+  const resolved = {
+    maxAttempts: retries?.maxAttempts ?? 5,
+    initialDelayMs: retries?.initialDelayMs ?? 1e3,
+    maxDelayMs: retries?.maxDelayMs ?? 6e4,
+    jitter: retries?.jitter ?? 0.25
+  };
+  if (!Number.isSafeInteger(resolved.maxAttempts) || resolved.maxAttempts < 1) {
+    throw new TypeError("retries.maxAttempts must be an integer of at least 1");
+  }
+  for (const key of ["initialDelayMs", "maxDelayMs"]) {
+    if (!Number.isFinite(resolved[key]) || resolved[key] < 0) {
+      throw new TypeError(`retries.${key} must be a finite non-negative number`);
+    }
+  }
+  if (!Number.isFinite(resolved.jitter) || resolved.jitter < 0 || resolved.jitter > 1) {
+    throw new TypeError("retries.jitter must be a finite number from 0 through 1");
+  }
+  return resolved;
+}
+function assertPayloadSize(result, error) {
+  const bytes = Buffer.byteLength(JSON.stringify({ result, error }), "utf8");
+  if (bytes > MAX_RESULT_BYTES) {
+    throw new TaskPushSettlementConfigurationError(`Task result/error JSON exceeds ${MAX_RESULT_BYTES} bytes`);
+  }
+}
+async function readOutbox(client, table, key) {
+  const found = await client.query(
+    `SELECT snapshot, snapshot_fingerprint, intent_fingerprint, state, disposition
+       FROM ${table}
+      WHERE publisher_scope = $1 AND tenant_scope = $2 AND delivery_id = $3
+      FOR UPDATE`,
+    [key.publisherScope, key.tenantScope, key.deliveryId]
+  );
+  return found.rows[0];
+}
+function deliveryState(row) {
+  if (row.state !== "settled") return "recoverable";
+  return row.disposition === "delivered" ? "delivered" : "terminal";
+}
+async function rollbackQuietly(client) {
+  try {
+    await client.query("ROLLBACK");
+  } catch {
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TaskPushSettlementConfigurationError,
+  completeScopedPushTask,
+  createPostgresTaskSettlementCoordinator,
+  failScopedPushTask
+});