deepline 0.3.479 → 0.3.481

package/dist/bundling-sources/shared_libs/monitors/legacy-radar-forward-routes.ts

@@ -0,0 +1,569 @@
+// Forward-route provisioning for a customer forwarder Play (W3 of the legacy
+// radar retirement): pure planning and SQL text.
+//
+// A forwarder delivers a finding only when a route row matches the finding's
+// `monitor_id`, `binding_version` and `account_id`. A re-bound monitor
+// therefore stops forwarding silently until its route pins the new binding.
+// This planner only ever inserts a missing (monitor_id, account_id) route or
+// refreshes the binding pin of an existing one. It never deletes, re-enables,
+// or changes an account, and it leaves every other column of an existing row
+// untouched (the upsert updates `binding_version` alone).
+
+import {
+  isLegacyContactRadarType,
+  LEGACY_RETIREMENT_ROUTE_TABLE_PATTERN,
+  type LegacyRequiredMonitorFacts,
+} from './legacy-radar-retirement';
+
+export const FORWARD_ROUTE_WRITE_BATCH = 200;
+/**
+ * The platform-admin Customer DB SQL endpoint refuses longer statements
+ * (`ADMIN_SQL_MAX_LENGTH` in `apps/deepline-api/src/lib/admin/customer-db-sql.ts`).
+ */
+export const ADMIN_CUSTOMER_DB_SQL_MAX_LENGTH = 100_000;
+export const FORWARD_ROUTE_READ_PAGE = 200;
+
+export const FORWARD_ROUTE_COLUMNS = [
+  'monitor_id',
+  'binding_version',
+  'radar_type',
+  'domain',
+  'profile_url',
+  'account_id',
+  'destination',
+  'deactivated_at',
+  'disposition',
+  'custom_fields',
+  'enabled',
+] as const;
+
+export type ForwardRouteRow = {
+  monitor_id: string;
+  binding_version: string;
+  radar_type: string;
+  domain: string;
+  profile_url: string | null;
+  account_id: string;
+  destination: string;
+  deactivated_at: string;
+  disposition: string;
+  custom_fields: Record<string, unknown>;
+  enabled: boolean;
+};
+
+export type ForwardRouteKey = { monitor_id: string; account_id: string };
+
+export function forwardRouteKey(route: ForwardRouteKey): string {
+  return JSON.stringify([route.monitor_id, route.account_id]);
+}
+
+export function assertForwardRouteTable(table: string): string {
+  if (!LEGACY_RETIREMENT_ROUTE_TABLE_PATTERN.test(table)) {
+    throw new Error(
+      `Route table ${JSON.stringify(table)} must match ${String(LEGACY_RETIREMENT_ROUTE_TABLE_PATTERN)}.`,
+    );
+  }
+  return table;
+}
+
+const SALESFORCE_CHECKSUM_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ012345';
+
+/** The three-character case checksum Salesforce appends to a 15-character id. */
+export function salesforceIdChecksum(id15: string): string {
+  let suffix = '';
+  for (let chunk = 0; chunk < 3; chunk += 1) {
+    let flags = 0;
+    for (let index = 0; index < 5; index += 1) {
+      const char = id15[chunk * 5 + index] ?? '';
+      if (char >= 'A' && char <= 'Z') flags |= 1 << index;
+    }
+    suffix += SALESFORCE_CHECKSUM_ALPHABET[flags];
+  }
+  return suffix;
+}
+
+/** An 18-character Salesforce id whose case checksum is consistent. */
+export function isSalesforceId18(value: string): boolean {
+  if (!/^[a-zA-Z0-9]{18}$/.test(value)) return false;
+  return (
+    salesforceIdChecksum(value.slice(0, 15)) === value.slice(15).toUpperCase()
+  );
+}
+
+/**
+ * E-string literal, correct whatever `standard_conforming_strings` says:
+ * backslashes and quotes are doubled. NUL cannot be stored in text and is
+ * refused rather than truncated.
+ */
+export function sqlTextLiteral(value: string): string {
+  if (value.includes('\u0000')) {
+    throw new Error('SQL text values cannot contain NUL characters.');
+  }
+  return `E'${value.replace(/\\/g, '\\\\').replace(/'/g, "''")}'`;
+}
+
+function sqlNullableText(value: string | null): string {
+  return value === null ? 'NULL' : sqlTextLiteral(value);
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .filter(([, entry]) => entry !== undefined)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+}
+
+function text(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+/**
+ * The route subject a monitor's own payload names; `domain` is '' when the
+ * payload names no company (the plan's route domain then fills it in).
+ */
+export function forwardRouteSubject(payload: unknown): {
+  radar_type: string;
+  domain: string;
+  profile_url: string | null;
+} | null {
+  const value =
+    payload && typeof payload === 'object' && !Array.isArray(payload)
+      ? (payload as Record<string, unknown>)
+      : null;
+  const radarType = text(value?.radar_type);
+  if (!value || !radarType) return null;
+  return {
+    radar_type: radarType,
+    domain: text(value.domain) ?? '',
+    profile_url: isLegacyContactRadarType(radarType)
+      ? text(value.profile_url)
+      : null,
+  };
+}
+
+function normalizeRouteDomain(domain: string): string {
+  return domain
+    .trim()
+    .toLowerCase()
+    .replace(/^[a-z]+:\/\//, '')
+    .split('/')[0]!
+    .replace(/^www\d?\./, '');
+}
+
+function monitorRefusal(
+  facts: LegacyRequiredMonitorFacts | null,
+): string | null {
+  if (!facts) return 'monitor_missing';
+  if (facts.status !== 'active') return 'monitor_not_active';
+  if (facts.desired !== 'active') return 'monitor_not_desired_active';
+  if (facts.observed !== 'active') return 'monitor_not_observed_active';
+  if (!facts.bindingVersion) return 'monitor_unbound';
+  return null;
+}
+
+export type ForwardRouteRequest = {
+  monitorKey: string;
+  accountId: string;
+  /**
+   * The account's company domain. Every existing route carries one, and the
+   * forwarder compares findings against it, so it is required even for a
+   * contact monitor whose payload names no company.
+   */
+  routeDomain: string;
+  customFields: Record<string, unknown>;
+  deactivatedAt: string;
+};
+
+export type ForwardRouteRefusal = {
+  monitorKey: string;
+  accountId: string | null;
+  reason: string;
+};
+
+export type ForwardRoutePlan = {
+  inserts: ForwardRouteRow[];
+  /** Existing rows, unchanged except for `binding_version`. */
+  refreshes: Array<ForwardRouteRow & { previous_binding_version: string }>;
+  unchanged: number;
+  refused: ForwardRouteRefusal[];
+};
+
+/** Insert missing routes and refresh stale pins for the given plan rows. */
+export function planForwardRouteProvisioning(input: {
+  requests: readonly ForwardRouteRequest[];
+  monitorFacts: ReadonlyMap<string, LegacyRequiredMonitorFacts | null>;
+  existing: readonly ForwardRouteRow[];
+  destination: string;
+  disposition: string;
+}): ForwardRoutePlan {
+  const plan: ForwardRoutePlan = {
+    inserts: [],
+    refreshes: [],
+    unchanged: 0,
+    refused: [],
+  };
+  const existingByKey = new Map(
+    input.existing.map((route) => [forwardRouteKey(route), route]),
+  );
+  const accountsByMonitor = new Map<string, Set<string>>();
+  for (const route of input.existing) {
+    const accounts = accountsByMonitor.get(route.monitor_id) ?? new Set();
+    accounts.add(route.account_id);
+    accountsByMonitor.set(route.monitor_id, accounts);
+  }
+  // The same unrouted monitor planned for two accounts is the same conflict
+  // as one already routed elsewhere: refuse every such row, never pick one.
+  const plannedAccountsByMonitor = new Map<string, Set<string>>();
+  for (const request of input.requests) {
+    const accounts =
+      plannedAccountsByMonitor.get(request.monitorKey) ?? new Set();
+    accounts.add(request.accountId);
+    plannedAccountsByMonitor.set(request.monitorKey, accounts);
+  }
+  const seen = new Set<string>();
+  for (const request of input.requests) {
+    const refuse = (reason: string) =>
+      plan.refused.push({
+        monitorKey: request.monitorKey,
+        accountId: request.accountId,
+        reason,
+      });
+    if (!isSalesforceId18(request.accountId)) {
+      refuse('account_id_not_salesforce_18');
+      continue;
+    }
+    const key = forwardRouteKey({
+      monitor_id: request.monitorKey,
+      account_id: request.accountId,
+    });
+    if (seen.has(key)) {
+      refuse('duplicate_plan_row');
+      continue;
+    }
+    seen.add(key);
+    const facts = input.monitorFacts.get(request.monitorKey) ?? null;
+    const refusal = monitorRefusal(facts);
+    if (refusal) {
+      refuse(refusal);
+      continue;
+    }
+    const bindingVersion = facts!.bindingVersion!;
+    const existing = existingByKey.get(key);
+    if (existing) {
+      if (existing.binding_version === bindingVersion) plan.unchanged += 1;
+      else
+        plan.refreshes.push({
+          ...existing,
+          binding_version: bindingVersion,
+          previous_binding_version: existing.binding_version,
+        });
+      continue;
+    }
+    // A monitor already forwarding to another account is a mapping conflict
+    // for a human, never a second destination added silently.
+    if ((accountsByMonitor.get(request.monitorKey)?.size ?? 0) > 0) {
+      refuse('monitor_routed_to_other_account');
+      continue;
+    }
+    if ((plannedAccountsByMonitor.get(request.monitorKey)?.size ?? 0) > 1) {
+      refuse('monitor_planned_for_multiple_accounts');
+      continue;
+    }
+    const subject = forwardRouteSubject(facts!.payload);
+    if (!subject) {
+      refuse('monitor_payload_has_no_radar_type');
+      continue;
+    }
+    const routeDomain = normalizeRouteDomain(request.routeDomain);
+    if (!routeDomain) {
+      refuse('route_domain_missing');
+      continue;
+    }
+    if (
+      subject.domain &&
+      normalizeRouteDomain(subject.domain) !== routeDomain
+    ) {
+      refuse('route_domain_differs_from_monitor');
+      continue;
+    }
+    // The forwarder holds every finding whose route's custom fields do not
+    // attribute it to the route's own account.
+    if (request.customFields['Account Long ID'] !== request.accountId) {
+      refuse('custom_fields_account_long_id_mismatch');
+      continue;
+    }
+    plan.inserts.push({
+      monitor_id: request.monitorKey,
+      binding_version: bindingVersion,
+      ...subject,
+      domain: subject.domain || routeDomain,
+      account_id: request.accountId,
+      destination: input.destination,
+      deactivated_at: request.deactivatedAt,
+      disposition: input.disposition,
+      custom_fields: request.customFields,
+      enabled: true,
+    });
+  }
+  return plan;
+}
+
+/** Refresh the pin of every enabled route whose monitor was re-bound. */
+export function planStaleForwardRoutePins(input: {
+  existing: readonly ForwardRouteRow[];
+  monitorFacts: ReadonlyMap<string, LegacyRequiredMonitorFacts | null>;
+}): ForwardRoutePlan {
+  const plan: ForwardRoutePlan = {
+    inserts: [],
+    refreshes: [],
+    unchanged: 0,
+    refused: [],
+  };
+  for (const route of input.existing) {
+    if (!route.enabled) continue;
+    const facts = input.monitorFacts.get(route.monitor_id) ?? null;
+    const refusal = monitorRefusal(facts);
+    if (refusal) {
+      plan.refused.push({
+        monitorKey: route.monitor_id,
+        accountId: route.account_id,
+        reason: refusal,
+      });
+      continue;
+    }
+    if (route.binding_version === facts!.bindingVersion) {
+      plan.unchanged += 1;
+      continue;
+    }
+    plan.refreshes.push({
+      ...route,
+      binding_version: facts!.bindingVersion!,
+      previous_binding_version: route.binding_version,
+    });
+  }
+  return plan;
+}
+
+function rowValues(row: ForwardRouteRow): string {
+  return `(${[
+    sqlTextLiteral(row.monitor_id),
+    sqlTextLiteral(row.binding_version),
+    sqlTextLiteral(row.radar_type),
+    sqlTextLiteral(row.domain),
+    sqlNullableText(row.profile_url),
+    sqlTextLiteral(row.account_id),
+    sqlTextLiteral(row.destination),
+    sqlTextLiteral(row.deactivated_at),
+    sqlTextLiteral(row.disposition),
+    `${sqlTextLiteral(JSON.stringify(row.custom_fields))}::jsonb`,
+    row.enabled ? 'true' : 'false',
+  ].join(', ')})`;
+}
+
+/**
+ * One transaction per batch. A conflicting row only ever gets its
+ * `binding_version` replaced, and only when it differs.
+ */
+export function buildForwardRouteUpsertSql(
+  table: string,
+  rows: readonly ForwardRouteRow[],
+): string {
+  assertForwardRouteTable(table);
+  if (rows.length === 0 || rows.length > FORWARD_ROUTE_WRITE_BATCH) {
+    throw new Error(
+      `A route write batch holds 1..${FORWARD_ROUTE_WRITE_BATCH} rows.`,
+    );
+  }
+  return [
+    'BEGIN;',
+    `INSERT INTO ${table} (${FORWARD_ROUTE_COLUMNS.join(', ')}) VALUES`,
+    rows.map(rowValues).join(',\n'),
+    'ON CONFLICT (monitor_id, account_id) DO UPDATE',
+    'SET binding_version = EXCLUDED.binding_version',
+    `WHERE ${table}.binding_version <> EXCLUDED.binding_version;`,
+    'COMMIT;',
+  ].join('\n');
+}
+
+/**
+ * Every write statement for `rows`, each within both the row cap and the SQL
+ * endpoint's length limit. Built in full before any write, so an unwritable
+ * plan fails before its first batch commits; a single row too long to send
+ * alone is an error.
+ */
+export function buildForwardRouteUpsertBatches(
+  table: string,
+  rows: readonly ForwardRouteRow[],
+  maxLength: number = ADMIN_CUSTOMER_DB_SQL_MAX_LENGTH,
+): string[] {
+  const batches: string[] = [];
+  let batch: ForwardRouteRow[] = [];
+  const flush = () => {
+    if (batch.length) batches.push(buildForwardRouteUpsertSql(table, batch));
+    batch = [];
+  };
+  for (const row of rows) {
+    if (buildForwardRouteUpsertSql(table, [row]).length > maxLength) {
+      throw new Error(
+        `Route ${forwardRouteKey(row)} alone exceeds the ${maxLength}-character SQL limit.`,
+      );
+    }
+    const next = [...batch, row];
+    if (
+      next.length > FORWARD_ROUTE_WRITE_BATCH ||
+      buildForwardRouteUpsertSql(table, next).length > maxLength
+    ) {
+      flush();
+      batch = [row];
+    } else {
+      batch = next;
+    }
+  }
+  flush();
+  return batches;
+}
+
+/** One keyset page of the whole table, inside a READ ONLY transaction. */
+export function buildForwardRoutePageSql(
+  table: string,
+  after: ForwardRouteKey | null,
+): string {
+  assertForwardRouteTable(table);
+  const where = after
+    ? `WHERE (monitor_id, account_id) > (${sqlTextLiteral(after.monitor_id)}, ${sqlTextLiteral(after.account_id)})`
+    : '';
+  return [
+    'BEGIN TRANSACTION READ ONLY;',
+    `SELECT ${FORWARD_ROUTE_COLUMNS.join(', ')} FROM ${table} ${where}`.trim(),
+    `ORDER BY monitor_id, account_id LIMIT ${FORWARD_ROUTE_READ_PAGE};`,
+    'COMMIT;',
+  ].join('\n');
+}
+
+/** Parse one SELECT row; a malformed row is an error, never skipped. */
+export function parseForwardRouteRow(raw: unknown): ForwardRouteRow {
+  const row =
+    raw && typeof raw === 'object' && !Array.isArray(raw)
+      ? (raw as Record<string, unknown>)
+      : null;
+  const required = (name: string) => {
+    const value = row?.[name];
+    if (typeof value !== 'string') {
+      throw new Error(`Route row column ${name} is not text.`);
+    }
+    return value;
+  };
+  let customFields = row?.custom_fields;
+  if (typeof customFields === 'string') customFields = JSON.parse(customFields);
+  if (
+    !customFields ||
+    typeof customFields !== 'object' ||
+    Array.isArray(customFields)
+  ) {
+    throw new Error('Route row column custom_fields is not a JSON object.');
+  }
+  if (typeof row?.enabled !== 'boolean') {
+    throw new Error('Route row column enabled is not boolean.');
+  }
+  const profileUrl = row.profile_url;
+  if (profileUrl !== null && typeof profileUrl !== 'string') {
+    throw new Error('Route row column profile_url is not text.');
+  }
+  return {
+    monitor_id: required('monitor_id'),
+    binding_version: required('binding_version'),
+    radar_type: required('radar_type'),
+    domain: required('domain'),
+    profile_url: profileUrl,
+    account_id: required('account_id'),
+    destination: required('destination'),
+    deactivated_at: required('deactivated_at'),
+    disposition: required('disposition'),
+    custom_fields: customFields as Record<string, unknown>,
+    enabled: row.enabled,
+  };
+}
+
+/** Every planned row must read back exactly as planned. */
+export function forwardRouteReadbackMismatches(input: {
+  planned: readonly ForwardRouteRow[];
+  actual: readonly ForwardRouteRow[];
+}): string[] {
+  const actual = new Map(
+    input.actual.map((row) => [forwardRouteKey(row), row]),
+  );
+  const mismatches: string[] = [];
+  for (const planned of input.planned) {
+    const key = forwardRouteKey(planned);
+    const row = actual.get(key);
+    if (!row) {
+      mismatches.push(`${key}: missing`);
+      continue;
+    }
+    for (const column of FORWARD_ROUTE_COLUMNS) {
+      const left =
+        column === 'custom_fields'
+          ? stableJson(planned.custom_fields)
+          : planned[column];
+      const right =
+        column === 'custom_fields'
+          ? stableJson(row.custom_fields)
+          : row[column];
+      if (left !== right) mismatches.push(`${key}: ${column} differs`);
+    }
+  }
+  return mismatches;
+}
+
+/**
+ * Plan and, unless `dryRun`, write forward routes. The dry run and the real
+ * run share every step up to the first write: the same plan, the same
+ * refusals and the same write batches (built even when dry, so a plan that
+ * cannot be written fails there). The real run then requires every planned
+ * row to read back exactly.
+ */
+export async function runForwardRoutePlan(input: {
+  table: string;
+  requests: readonly ForwardRouteRequest[] | null;
+  monitorFacts: ReadonlyMap<string, LegacyRequiredMonitorFacts | null>;
+  existing: readonly ForwardRouteRow[];
+  destination: string;
+  disposition: string;
+  dryRun: boolean;
+  runSql: (sql: string) => Promise<unknown>;
+  readRoutes: () => Promise<readonly ForwardRouteRow[]>;
+}): Promise<{ plan: ForwardRoutePlan; writeBatches: number; written: number }> {
+  const plan = input.requests
+    ? planForwardRouteProvisioning({
+        requests: input.requests,
+        monitorFacts: input.monitorFacts,
+        existing: input.existing,
+        destination: input.destination,
+        disposition: input.disposition,
+      })
+    : planStaleForwardRoutePins({
+        existing: input.existing,
+        monitorFacts: input.monitorFacts,
+      });
+  const planned = [...plan.inserts, ...plan.refreshes];
+  const batches = buildForwardRouteUpsertBatches(input.table, planned);
+  if (input.dryRun || planned.length === 0) {
+    return { plan, writeBatches: batches.length, written: 0 };
+  }
+  for (const sql of batches) await input.runSql(sql);
+  const mismatches = forwardRouteReadbackMismatches({
+    planned,
+    actual: [...(await input.readRoutes())],
+  });
+  if (mismatches.length) {
+    throw new Error(
+      `Forward-route readback did not match ${mismatches.length} planned row(s): ${mismatches.slice(0, 20).join('; ')}`,
+    );
+  }
+  return { plan, writeBatches: batches.length, written: planned.length };
+}