deepline 0.3.88 → 0.3.90

package/dist/bundling-sources/shared_libs/monitors/provider-monitor-batch-operation.ts

@@ -0,0 +1,305 @@
+/**
+ * Shared, provider-agnostic vocabulary for a durable monitor operation.
+ *
+ * A batch operation is deliberately a small control document.  It names a
+ * stable scope and a retry key; monitor definitions remain the source of
+ * truth for every individual item and the retained operation evidence is only
+ * a log of what the runner observed or did.  Keeping this vocabulary pure
+ * makes CLI/API parsing, Convex admission and the background runner agree on
+ * the exact same request identity.
+ */
+
+import { requireMonitorDeactivationReason } from './deactivation-reasons';
+
+export const PROVIDER_MONITOR_BATCH_OPERATION_KINDS = [
+  'deploy',
+  'deactivate',
+  'reactivate',
+  'audit',
+  'repair',
+] as const;
+
+export type ProviderMonitorBatchOperationKind =
+  (typeof PROVIDER_MONITOR_BATCH_OPERATION_KINDS)[number];
+
+export const PROVIDER_MONITOR_BATCH_TARGETS = [
+  'all',
+  'all-active',
+  'billing-suspended',
+  'needs-repair',
+] as const;
+
+export type ProviderMonitorBatchTarget =
+  (typeof PROVIDER_MONITOR_BATCH_TARGETS)[number];
+
+/**
+ * A manifest lives in durable blob storage.  The runner reads it in bounded
+ * pages; never embed its definitions or a growing result array in a run
+ * record.  `count` is declared at upload time and is used for honest progress
+ * before the first item has been processed.
+ */
+export type ProviderMonitorBatchManifestScope = {
+  kind: 'manifest';
+  storageId: string;
+  count: number;
+  /** Content address used for idempotent retries; storage ids are ephemeral. */
+  sha256?: string;
+};
+
+export type ProviderMonitorBatchScope =
+  | { kind: 'keys'; monitorKeys: readonly string[] }
+  | { kind: 'target'; target: ProviderMonitorBatchTarget }
+  | { kind: 'fleet'; fleetId: string }
+  | ProviderMonitorBatchManifestScope;
+
+export type ProviderMonitorBatchOperationRequest = {
+  kind: ProviderMonitorBatchOperationKind;
+  scope: ProviderMonitorBatchScope;
+  dryRun: boolean;
+  /**
+   * The application deployment that accepted this operation. A provider
+   * callback is part of the create side effect, so a continuation must retain
+   * this origin instead of recomputing it from a later deployment.
+   */
+  callbackBaseUrl?: string;
+  /** Required for deactivate; absent for every other operation. */
+  deactivationReason?: string;
+};
+
+export type ProviderMonitorBatchOperationState =
+  | 'running'
+  | 'retry_scheduled'
+  | 'completed'
+  | 'failed';
+
+const IDEMPOTENCY_KEY = /^[A-Za-z0-9][A-Za-z0-9._-]{0,95}$/;
+
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function normalizeCallbackBaseUrl(
+  value: string | undefined,
+): string | undefined {
+  if (value === undefined) return undefined;
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error('callbackBaseUrl must be an absolute HTTP(S) origin.');
+  }
+  if (
+    (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') ||
+    parsed.username ||
+    parsed.password ||
+    parsed.search ||
+    parsed.hash ||
+    (parsed.pathname !== '' && parsed.pathname !== '/')
+  ) {
+    throw new Error('callbackBaseUrl must be an absolute HTTP(S) origin.');
+  }
+  return parsed.origin;
+}
+
+/**
+ * A job id is deterministic on purpose.  Convex's existing `by_run` point
+ * lookup is then the idempotency index: the same org/key can only own one run,
+ * and its canonical request below decides whether it is a rejoin or conflict.
+ */
+export function providerMonitorBatchOperationId(input: {
+  orgId: string;
+  idempotencyKey: string;
+}): string {
+  const orgId = input.orgId.trim();
+  const idempotencyKey = input.idempotencyKey.trim();
+  if (!orgId)
+    throw new Error('A monitor batch operation requires an organization.');
+  if (!IDEMPOTENCY_KEY.test(idempotencyKey)) {
+    throw new Error(
+      'idempotencyKey must be 1-96 characters of letters, numbers, dot, underscore, or hyphen.',
+    );
+  }
+  return `monitor-batch:${orgId}:${idempotencyKey}`;
+}
+
+export function isProviderMonitorBatchOperationKind(
+  value: string,
+): value is ProviderMonitorBatchOperationKind {
+  return (PROVIDER_MONITOR_BATCH_OPERATION_KINDS as readonly string[]).includes(
+    value,
+  );
+}
+
+export function isProviderMonitorBatchTarget(
+  value: string,
+): value is ProviderMonitorBatchTarget {
+  return (PROVIDER_MONITOR_BATCH_TARGETS as readonly string[]).includes(value);
+}
+
+/**
+ * Validate the representation shared by all entry points before any state is
+ * mutated.  A request chooses exactly one selection mechanism.  Key lists are
+ * kept intentionally small because a large explicit selection is a manifest,
+ * not an unbounded mutation argument.
+ */
+export function validateProviderMonitorBatchOperationRequest(
+  request: ProviderMonitorBatchOperationRequest,
+): ProviderMonitorBatchOperationRequest {
+  if (!isProviderMonitorBatchOperationKind(request.kind)) {
+    throw new Error(`Unknown monitor batch operation '${request.kind}'.`);
+  }
+  const callbackBaseUrl = normalizeCallbackBaseUrl(request.callbackBaseUrl);
+  if (callbackBaseUrl !== undefined && request.kind !== 'deploy') {
+    throw new Error('callbackBaseUrl is only valid for a batch deploy.');
+  }
+  if (!request.scope || typeof request.scope !== 'object') {
+    throw new Error('A monitor batch operation requires exactly one scope.');
+  }
+  const scope = request.scope;
+  if (scope.kind === 'keys') {
+    const keys = [...new Set(scope.monitorKeys.map((key) => key.trim()))];
+    if (
+      keys.length === 0 ||
+      keys.length !== scope.monitorKeys.length ||
+      keys.some((key) => key.length === 0)
+    ) {
+      throw new Error(
+        'Monitor key scopes must contain unique, non-empty keys.',
+      );
+    }
+    if (keys.length > 100) {
+      throw new Error(
+        'An explicit monitor batch contains at most 100 keys. Upload a manifest for larger selections.',
+      );
+    }
+    if (request.kind === 'deploy') {
+      throw new Error(
+        'Batch deploy requires a durable manifest of complete definitions.',
+      );
+    }
+    if (request.kind === 'deactivate' && !request.deactivationReason) {
+      throw new Error(
+        'Batch deactivate requires a declared deactivation reason.',
+      );
+    }
+    if (request.kind === 'deactivate') {
+      requireMonitorDeactivationReason(request.deactivationReason!);
+    }
+    return {
+      ...request,
+      scope: { kind: 'keys', monitorKeys: keys },
+      ...(callbackBaseUrl === undefined ? {} : { callbackBaseUrl }),
+    };
+  }
+  if (scope.kind === 'target') {
+    if (request.kind === 'deploy') {
+      throw new Error(
+        'Batch deploy requires a durable manifest of complete definitions.',
+      );
+    }
+    if (!isProviderMonitorBatchTarget(scope.target)) {
+      throw new Error(`Unknown monitor batch target '${scope.target}'.`);
+    }
+    if (request.kind === 'deactivate' && !request.deactivationReason) {
+      throw new Error(
+        'Batch deactivate requires a declared deactivation reason.',
+      );
+    }
+    if (request.kind === 'deactivate') {
+      requireMonitorDeactivationReason(request.deactivationReason!);
+    }
+    return {
+      ...request,
+      ...(callbackBaseUrl === undefined ? {} : { callbackBaseUrl }),
+    };
+  }
+  if (scope.kind === 'fleet') {
+    if (request.kind === 'deploy') {
+      throw new Error(
+        'Batch deploy requires a durable manifest of complete definitions.',
+      );
+    }
+    if (!scope.fleetId.trim())
+      throw new Error('A Fleet scope requires fleetId.');
+    if (request.kind === 'deactivate' && !request.deactivationReason) {
+      throw new Error(
+        'Batch deactivate requires a declared deactivation reason.',
+      );
+    }
+    if (request.kind === 'deactivate') {
+      requireMonitorDeactivationReason(request.deactivationReason!);
+    }
+    return {
+      ...request,
+      scope: { kind: 'fleet', fleetId: scope.fleetId.trim() },
+      ...(callbackBaseUrl === undefined ? {} : { callbackBaseUrl }),
+    };
+  }
+  if (scope.kind === 'manifest') {
+    if (
+      !scope.storageId.trim() ||
+      !Number.isSafeInteger(scope.count) ||
+      scope.count < 1
+    ) {
+      throw new Error(
+        'A manifest scope requires a storage id and a positive item count.',
+      );
+    }
+    if (request.kind !== 'deploy') {
+      throw new Error('Only batch deploy accepts a manifest scope.');
+    }
+    if (
+      scope.sha256 !== undefined &&
+      !/^[a-f0-9]{64}$/i.test(scope.sha256.trim())
+    ) {
+      throw new Error('A manifest sha256 must be a 64-character hex digest.');
+    }
+    return {
+      ...request,
+      scope: {
+        kind: 'manifest',
+        storageId: scope.storageId.trim(),
+        count: scope.count,
+        ...(scope.sha256 === undefined
+          ? {}
+          : { sha256: scope.sha256.trim().toLowerCase() }),
+      },
+      ...(callbackBaseUrl === undefined ? {} : { callbackBaseUrl }),
+    };
+  }
+  throw new Error(
+    'A monitor batch operation requires exactly one supported scope.',
+  );
+}
+
+/**
+ * The persisted fingerprint is an equality proof, not a display hash.  It is
+ * compact for normal target/key requests, collision-free, and avoids a Node
+ * crypto dependency in code shared with Convex.
+ */
+export function providerMonitorBatchOperationRequestFingerprint(
+  request: ProviderMonitorBatchOperationRequest,
+): string {
+  const normalized = validateProviderMonitorBatchOperationRequest(request);
+  // A storage id is an implementation detail of an uploaded immutable file.
+  // Re-uploading identical bytes after a lost HTTP response must rejoin the
+  // same operation, not conflict merely because storage issued another id.
+  if (normalized.scope.kind === 'manifest' && normalized.scope.sha256) {
+    return canonicalJson({
+      ...normalized,
+      scope: {
+        kind: 'manifest',
+        count: normalized.scope.count,
+        sha256: normalized.scope.sha256,
+      },
+    });
+  }
+  return canonicalJson(normalized);
+}