deepline 0.1.0 → 0.1.1

package/dist/repo/shared_libs/play-runtime/db-session.ts

@@ -0,0 +1,462 @@
+import type {
+  EncryptedPostgresUrl,
+  PostgresUrlEncryptionRequest,
+} from './db-session-crypto';
+
+export const DB_SESSION_DEFAULT_TTL_SECONDS = 10 * 60;
+export const DB_SESSION_MAX_TTL_SECONDS = 30 * 60;
+
+export const DB_SESSION_OPERATIONS = [
+  'rows.read',
+  'rows.append',
+  'rows.upsert',
+  'rows.replace',
+] as const;
+export type DbSessionOperation = (typeof DB_SESSION_OPERATIONS)[number];
+
+export const DB_LOGICAL_TABLES = [
+  'sheet_rows',
+  'dataset_rows',
+  'play_output',
+] as const;
+export type DbLogicalTable = (typeof DB_LOGICAL_TABLES)[number];
+
+export type DbSessionTarget = {
+  orgId: string;
+  tableNamespace: string;
+  logicalTable: DbLogicalTable;
+};
+
+export type DbSessionLimits = {
+  maxRows?: number;
+  maxBytes?: number;
+  maxRequests?: number;
+};
+
+export type CreateDbSessionRequest = {
+  playName: string;
+  target: Omit<DbSessionTarget, 'orgId'>;
+  operations: DbSessionOperation[];
+  limits?: DbSessionLimits;
+  sheetContract?: unknown | null;
+  ttlSeconds?: number;
+  userEmail?: string | null;
+  postgresUrlEncryption?: PostgresUrlEncryptionRequest | null;
+};
+
+export type CreateDbSessionResponse = {
+  sessionId: string;
+  postgresUrl?: string;
+  encryptedPostgresUrl?: EncryptedPostgresUrl;
+  postgres?: {
+    schema: string;
+    sheetTable: string;
+    eventTable: string;
+    summaryTable: string;
+    columnSummaryTable: string;
+  };
+  expiresAt: string;
+  playName: string;
+  target: DbSessionTarget;
+  operations: DbSessionOperation[];
+  limits: DbSessionLimits;
+};
+
+export type PreloadedRuntimeDbSession = {
+  tableNamespace: string;
+  logicalTable: DbLogicalTable;
+  operations: DbSessionOperation[];
+  limits?: DbSessionLimits;
+  session: CreateDbSessionResponse;
+};
+
+export type RowsWriteDisposition = 'completed' | 'accepted';
+
+export type RowsWriteResponse = {
+  disposition: RowsWriteDisposition;
+  writtenRows?: number;
+  jobId?: string;
+};
+
+type SafeParseSuccess<T> = { success: true; data: T };
+type SafeParseFailure = { success: false; error: Error };
+type SafeParseResult<T> = SafeParseSuccess<T> | SafeParseFailure;
+
+type RuntimeSchema<T> = {
+  parse(value: unknown): T;
+  safeParse(value: unknown): SafeParseResult<T>;
+};
+
+function createSchema<T>(parse: (value: unknown) => T): RuntimeSchema<T> {
+  return {
+    parse,
+    safeParse(value) {
+      try {
+        return { success: true, data: parse(value) };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error : new Error(String(error)),
+        };
+      }
+    },
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function parseString(value: unknown, path: string): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`${path} must be a non-empty string.`);
+  }
+  return value;
+}
+
+function parseOptionalString(value: unknown, path: string): string | undefined {
+  if (value === undefined) return undefined;
+  return parseString(value, path);
+}
+
+function parseLiteral<T extends string>(
+  value: unknown,
+  expected: T,
+  path: string,
+): T {
+  if (value !== expected) {
+    throw new Error(`${path} must be ${expected}.`);
+  }
+  return expected;
+}
+
+function parseNullableString(
+  value: unknown,
+  path: string,
+): string | null | undefined {
+  if (value === undefined) return undefined;
+  if (value === null) return null;
+  return parseString(value, path);
+}
+
+function parsePositiveInteger(value: unknown, path: string): number {
+  if (
+    typeof value !== 'number' ||
+    !Number.isInteger(value) ||
+    value <= 0
+  ) {
+    throw new Error(`${path} must be a positive integer.`);
+  }
+  return value;
+}
+
+function parseNonnegativeInteger(
+  value: unknown,
+  path: string,
+): number {
+  if (
+    typeof value !== 'number' ||
+    !Number.isInteger(value) ||
+    value < 0
+  ) {
+    throw new Error(`${path} must be a nonnegative integer.`);
+  }
+  return value;
+}
+
+function parseEnum<T extends readonly string[]>(
+  value: unknown,
+  allowed: T,
+  path: string,
+): T[number] {
+  if (
+    typeof value === 'string' &&
+    (allowed as readonly string[]).includes(value)
+  ) {
+    return value as T[number];
+  }
+  throw new Error(`${path} must be one of: ${allowed.join(', ')}.`);
+}
+
+function parseArray<T>(
+  value: unknown,
+  path: string,
+  parseItem: (item: unknown, itemPath: string) => T,
+): T[] {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error(`${path} must be a non-empty array.`);
+  }
+  return value.map((item, index) => parseItem(item, `${path}[${index}]`));
+}
+
+function parseLimits(value: unknown, path: string): DbSessionLimits {
+  if (!isRecord(value)) {
+    throw new Error(`${path} must be an object.`);
+  }
+  return {
+    ...(value.maxRows !== undefined
+      ? { maxRows: parsePositiveInteger(value.maxRows, `${path}.maxRows`) }
+      : {}),
+    ...(value.maxBytes !== undefined
+      ? { maxBytes: parsePositiveInteger(value.maxBytes, `${path}.maxBytes`) }
+      : {}),
+    ...(value.maxRequests !== undefined
+      ? {
+          maxRequests: parsePositiveInteger(
+            value.maxRequests,
+            `${path}.maxRequests`,
+          ),
+        }
+      : {}),
+  };
+}
+
+function parseOperation(value: unknown, path: string): DbSessionOperation {
+  return parseEnum(value, DB_SESSION_OPERATIONS, path);
+}
+
+function parseLogicalTable(value: unknown, path: string): DbLogicalTable {
+  return parseEnum(value, DB_LOGICAL_TABLES, path);
+}
+
+function parseTarget(value: unknown, path: string): DbSessionTarget {
+  if (!isRecord(value)) {
+    throw new Error(`${path} must be an object.`);
+  }
+  return {
+    orgId: parseString(value.orgId, `${path}.orgId`),
+    tableNamespace: parseString(value.tableNamespace, `${path}.tableNamespace`),
+    logicalTable: parseLogicalTable(value.logicalTable, `${path}.logicalTable`),
+  };
+}
+
+function parseRequestTarget(
+  value: unknown,
+  path: string,
+): Omit<DbSessionTarget, 'orgId'> {
+  if (!isRecord(value)) {
+    throw new Error(`${path} must be an object.`);
+  }
+  return {
+    tableNamespace: parseString(value.tableNamespace, `${path}.tableNamespace`),
+    logicalTable: parseLogicalTable(value.logicalTable, `${path}.logicalTable`),
+  };
+}
+
+function parsePostgresMetadata(
+  value: unknown,
+  path: string,
+): CreateDbSessionResponse['postgres'] {
+  if (value === undefined) return undefined;
+  if (!isRecord(value)) {
+    throw new Error(`${path} must be an object.`);
+  }
+  return {
+    schema: parseString(value.schema, `${path}.schema`),
+    sheetTable: parseString(value.sheetTable, `${path}.sheetTable`),
+    eventTable: parseString(value.eventTable, `${path}.eventTable`),
+    summaryTable: parseString(value.summaryTable, `${path}.summaryTable`),
+    columnSummaryTable: parseString(
+      value.columnSummaryTable,
+      `${path}.columnSummaryTable`,
+    ),
+  };
+}
+
+function parseEncryptedPostgresUrl(
+  value: unknown,
+  path: string,
+): EncryptedPostgresUrl {
+  if (!isRecord(value)) {
+    throw new Error(`${path} must be an object.`);
+  }
+  const alg = parseString(value.alg, `${path}.alg`);
+  if (alg === 'A256GCM') {
+    return {
+      alg,
+      kid: parseLiteral(
+        value.kid,
+        'deepline-runtime-db-session-url:v1',
+        `${path}.kid`,
+      ),
+      iv: parseString(value.iv, `${path}.iv`),
+      ciphertext: parseString(value.ciphertext, `${path}.ciphertext`),
+      tag: parseString(value.tag, `${path}.tag`),
+    };
+  }
+  if (alg === 'RSA-OAEP-256+A256GCM') {
+    return {
+      alg,
+      kid: parseLiteral(
+        value.kid,
+        'deepline-runtime-db-session-url:v2',
+        `${path}.kid`,
+      ),
+      wrappedKey: parseString(value.wrappedKey, `${path}.wrappedKey`),
+      iv: parseString(value.iv, `${path}.iv`),
+      ciphertext: parseString(value.ciphertext, `${path}.ciphertext`),
+      tag: parseString(value.tag, `${path}.tag`),
+    };
+  }
+  throw new Error(`${path}.alg must be a supported encryption algorithm.`);
+}
+
+function parsePostgresUrlEncryptionRequest(
+  value: unknown,
+  path: string,
+): PostgresUrlEncryptionRequest {
+  if (!isRecord(value)) {
+    throw new Error(`${path} must be an object.`);
+  }
+  const alg = parseLiteral(
+    value.alg,
+    'RSA-OAEP-256+A256GCM',
+    `${path}.alg`,
+  );
+  const publicKeyJwkValue = value.publicKeyJwk;
+  if (!isRecord(publicKeyJwkValue)) {
+    throw new Error(`${path}.publicKeyJwk must be an object.`);
+  }
+  const publicKeyJwk = { ...publicKeyJwkValue } as unknown as JsonWebKey;
+  if (publicKeyJwk.kty !== 'RSA') {
+    throw new Error(`${path}.publicKeyJwk.kty must be RSA.`);
+  }
+  if (
+    typeof publicKeyJwk.n !== 'string' ||
+    typeof publicKeyJwk.e !== 'string'
+  ) {
+    throw new Error(`${path}.publicKeyJwk must include RSA n and e values.`);
+  }
+  return {
+    alg,
+    publicKeyJwk,
+  };
+}
+
+export const dbSessionOperationSchema = createSchema<DbSessionOperation>(
+  (value) => parseOperation(value, 'operation'),
+);
+
+export const dbLogicalTableSchema = createSchema<DbLogicalTable>(
+  (value) => parseLogicalTable(value, 'logicalTable'),
+);
+
+export const dbSessionTargetSchema = createSchema<DbSessionTarget>(
+  (value) => parseTarget(value, 'target'),
+);
+
+export const dbSessionLimitsSchema = createSchema<DbSessionLimits>(
+  (value) => parseLimits(value, 'limits'),
+);
+
+export const createDbSessionRequestSchema = createSchema<CreateDbSessionRequest>(
+  (value) => {
+    if (!isRecord(value)) {
+      throw new Error('Create DB session request must be an object.');
+    }
+    const ttlSeconds =
+      value.ttlSeconds === undefined
+        ? undefined
+        : parsePositiveInteger(value.ttlSeconds, 'ttlSeconds');
+    if (
+      ttlSeconds !== undefined &&
+      ttlSeconds > DB_SESSION_MAX_TTL_SECONDS
+    ) {
+      throw new Error(
+        `ttlSeconds must be <= ${DB_SESSION_MAX_TTL_SECONDS}.`,
+      );
+    }
+    return {
+      playName: parseString(value.playName, 'playName'),
+      target: parseRequestTarget(value.target, 'target'),
+      operations: parseArray(
+        value.operations,
+        'operations',
+        parseOperation,
+      ),
+      ...(value.limits !== undefined
+        ? { limits: parseLimits(value.limits, 'limits') }
+        : {}),
+      ...(value.sheetContract !== undefined
+        ? { sheetContract: value.sheetContract }
+        : {}),
+      ...(ttlSeconds !== undefined ? { ttlSeconds } : {}),
+      ...(value.userEmail !== undefined
+        ? { userEmail: parseNullableString(value.userEmail, 'userEmail') }
+        : {}),
+      ...(value.postgresUrlEncryption !== undefined
+        ? {
+            postgresUrlEncryption:
+              value.postgresUrlEncryption === null
+                ? null
+                : parsePostgresUrlEncryptionRequest(
+                    value.postgresUrlEncryption,
+                    'postgresUrlEncryption',
+                  ),
+          }
+        : {}),
+    };
+  },
+);
+
+export const createDbSessionResponseSchema =
+  createSchema<CreateDbSessionResponse>((value) => {
+    if (!isRecord(value)) {
+      throw new Error('Create DB session response must be an object.');
+    }
+    return {
+      sessionId: parseString(value.sessionId, 'sessionId'),
+      ...(value.postgresUrl !== undefined
+        ? { postgresUrl: parseOptionalString(value.postgresUrl, 'postgresUrl') }
+        : {}),
+      ...(value.encryptedPostgresUrl !== undefined
+        ? {
+            encryptedPostgresUrl: parseEncryptedPostgresUrl(
+              value.encryptedPostgresUrl,
+              'encryptedPostgresUrl',
+            ),
+          }
+        : {}),
+      ...(value.postgres !== undefined
+        ? { postgres: parsePostgresMetadata(value.postgres, 'postgres') }
+        : {}),
+      expiresAt: parseString(value.expiresAt, 'expiresAt'),
+      playName: parseString(value.playName, 'playName'),
+      target: parseTarget(value.target, 'target'),
+      operations: parseArray(
+        value.operations,
+        'operations',
+        parseOperation,
+      ),
+      limits:
+        value.limits === undefined
+          ? {}
+          : parseLimits(value.limits, 'limits'),
+    };
+  });
+
+export const rowsWriteResponseSchema = createSchema<RowsWriteResponse>(
+  (value) => {
+    if (!isRecord(value)) {
+      throw new Error('Rows write response must be an object.');
+    }
+    return {
+      disposition: parseEnum(
+        value.disposition,
+        ['completed', 'accepted'] as const,
+        'disposition',
+      ),
+      ...(value.writtenRows !== undefined
+        ? {
+            writtenRows: parseNonnegativeInteger(
+              value.writtenRows,
+              'writtenRows',
+            ),
+          }
+        : {}),
+      ...(value.jobId !== undefined
+        ? { jobId: parseOptionalString(value.jobId, 'jobId') }
+        : {}),
+    };
+  },
+);

package/dist/repo/shared_libs/play-runtime/default-batch-strategies.ts

@@ -0,0 +1,124 @@
+import {
+  defineBatchStrategyMap,
+  type AnyBatchOperationStrategy,
+  type BatchOperationStrategy,
+} from './batching-types';
+
+type TestRateLimitPayload = {
+  key: string;
+  stage?: string;
+  lead_id?: string;
+  row_number?: number;
+  simulated_delay_ms?: number;
+};
+
+type TestRateLimitBatchPayload = {
+  key: string;
+  stage?: string;
+  simulated_delay_ms?: number;
+  items: Array<{
+    itemKey: string;
+    payload: TestRateLimitPayload;
+  }>;
+};
+
+type TestRateLimitBatchResult = {
+  status: 'completed';
+  key: string;
+  stage?: string;
+  batch: true;
+  batch_size: number;
+  items: Array<{
+    itemKey: string;
+    result: {
+      status: 'completed';
+      key: string;
+      batch: false;
+      lead_id: string | null;
+      row_number: number | null;
+    };
+  }>;
+};
+
+const testRateLimitBatchStrategy: BatchOperationStrategy<
+  TestRateLimitPayload,
+  TestRateLimitBatchPayload,
+  TestRateLimitBatchResult
+> = {
+  sourceOperation: 'test_rate_limit',
+  batchOperation: 'test_batch_rate_limit',
+  kind: 'identifier_batch',
+  maxBatchSize: 200,
+  canBatchWith(left, right) {
+    return String(left.stage || '') === String(right.stage || '');
+  },
+  toBucketKey(payload) {
+    return `test_batch_rate_limit:${String(payload.stage || '')}`;
+  },
+  toItemKey(payload) {
+    return String(payload.lead_id || payload.row_number || payload.key || '');
+  },
+  compile(payloads) {
+    const stage = String(payloads[0]?.stage || '');
+    const simulatedDelayMs =
+      typeof payloads[0]?.simulated_delay_ms === 'number'
+        ? payloads[0].simulated_delay_ms
+        : undefined;
+    const items = payloads.map((payload, index) => ({
+      itemKey: String(payload.lead_id || payload.row_number || `row_${index}`),
+      payload,
+    }));
+    return {
+      batchOperation: 'test_batch_rate_limit',
+      batchPayload: {
+        key: 'batch',
+        ...(stage ? { stage } : {}),
+        ...(simulatedDelayMs !== undefined
+          ? { simulated_delay_ms: simulatedDelayMs }
+          : {}),
+        items,
+      },
+      items,
+    };
+  },
+  splitResult(fullResult, compiled) {
+    const container =
+      fullResult && typeof fullResult === 'object'
+        ? (fullResult as { data?: { items?: unknown[] }; items?: unknown[] })
+        : {};
+    const nestedItems =
+      container.data && typeof container.data === 'object'
+        ? container.data.items
+        : undefined;
+    const resultItems = Array.isArray(container.items)
+      ? (container.items as Array<{ itemKey?: string; result?: unknown }>)
+      : Array.isArray(nestedItems)
+        ? (nestedItems as Array<{ itemKey?: string; result?: unknown }>)
+        : [];
+    return compiled.items.map((item, index) => ({
+      itemKey: item.itemKey,
+      result:
+        index < resultItems.length
+          ? (resultItems[index]?.result ?? null)
+          : null,
+      rawResult:
+        index < resultItems.length
+          ? (resultItems[index]?.result ?? null)
+          : null,
+    }));
+  },
+};
+
+export const DEFAULT_PLAY_RUNTIME_BATCH_STRATEGIES =
+  defineBatchStrategyMap({
+    test_rate_limit: testRateLimitBatchStrategy,
+  });
+
+export function getDefaultPlayRuntimeBatchStrategy(
+  operation: string | null | undefined,
+): AnyBatchOperationStrategy | null {
+  if (!operation) {
+    return null;
+  }
+  return DEFAULT_PLAY_RUNTIME_BATCH_STRATEGIES[operation] ?? null;
+}