@dotdo/postgres 0.1.0

package/src/worker/types.ts

@@ -0,0 +1,873 @@
+/**
+ * Worker Types for PostgresDO
+ * Task: postgres-6u6.1 - Worker Types (Env, QueryRequest, QueryResponse, WSMessage, PostgresConfig)
+ */
+
+/**
+ * Environment bindings for the Cloudflare Worker
+ */
+export interface Env {
+  POSTGRES_DO: DurableObjectNamespace
+  POSTGRES_DEFAULT_DB?: string
+  POSTGRES_MAX_CONNECTIONS?: string
+}
+
+/**
+ * SQL query parameter types
+ */
+export type QueryParam = string | number | boolean | null | Uint8Array | Date
+
+/**
+ * Query method hints
+ */
+export type QueryMethod = 'all' | 'one' | 'run' | 'exec'
+
+/**
+ * Request to execute a SQL query
+ */
+export interface QueryRequest {
+  sql: string
+  params?: QueryParam[] | undefined
+  preserveCase?: boolean | undefined
+  method?: QueryMethod | undefined
+}
+
+/**
+ * Field metadata from query results
+ */
+export interface QueryField {
+  name: string
+  dataTypeID: number
+  tableID?: number | undefined
+  columnID?: number | undefined
+  dataTypeSize?: number | undefined
+  dataTypeModifier?: number | undefined
+  format?: string | undefined
+}
+
+/**
+ * Generic row type for query results
+ */
+export type QueryResultRow = Record<string, unknown>
+
+/**
+ * Response from a SQL query
+ */
+export interface QueryResponse<T extends QueryResultRow = QueryResultRow> {
+  rows: T[]
+  fields: QueryField[]
+  rowCount: number
+  durationMs?: number | undefined
+}
+
+/**
+ * Batch query request
+ */
+export interface BatchRequest {
+  queries: QueryRequest[]
+  transaction?: boolean | undefined
+}
+
+/**
+ * Batch query response
+ */
+export interface BatchResponse {
+  results: QueryResponse[]
+  durationMs?: number | undefined
+}
+
+/**
+ * Transaction isolation levels
+ */
+export type IsolationLevel = 'READ UNCOMMITTED' | 'READ COMMITTED' | 'REPEATABLE READ' | 'SERIALIZABLE'
+
+/**
+ * Transaction actions
+ */
+export type TransactionAction = 'begin' | 'commit' | 'rollback'
+
+/**
+ * Transaction request
+ */
+export interface TransactionRequest {
+  action: TransactionAction
+  transactionId?: string | undefined
+  isolationLevel?: IsolationLevel | undefined
+}
+
+/**
+ * Error response structure
+ */
+export interface ErrorResponse {
+  error: true
+  code: string
+  message: string
+  details?: Record<string, unknown> | undefined
+}
+
+/**
+ * WebSocket message types
+ */
+export type WSMessageType =
+  | 'query'
+  | 'subscribe'
+  | 'unsubscribe'
+  | 'ping'
+  | 'pong'
+  | 'result'
+  | 'error'
+  | 'change'
+  | 'subscribed'
+  | 'unsubscribed'
+  | 'heartbeat'
+  | 'heartbeat_ack'
+  | 'reconnect'
+  | 'welcome'
+
+/**
+ * CDC event types
+ */
+export type CDCEventType = 'INSERT' | 'UPDATE' | 'DELETE'
+
+/**
+ * Subscription payload
+ */
+export interface SubscribePayload {
+  table: string
+  events?: CDCEventType[] | undefined
+  filter?: string | undefined
+}
+
+/**
+ * Unsubscription payload
+ */
+export interface UnsubscribePayload {
+  subscriptionId: string
+}
+
+/**
+ * Change notification payload (CDC)
+ */
+export interface ChangePayload {
+  table: string
+  operation: CDCEventType
+  newRow?: QueryResultRow | undefined
+  oldRow?: QueryResultRow | undefined
+  timestamp?: number | undefined
+  /** Subscription ID that matched this change */
+  subscriptionId?: string | undefined
+  /** Log Sequence Number for ordering */
+  lsn?: string | undefined
+}
+
+/**
+ * Heartbeat payload for connection keepalive
+ */
+export interface HeartbeatPayload {
+  /** Timestamp when heartbeat was sent */
+  timestamp: number
+  /** Server-side sequence number for ordering */
+  seq?: number | undefined
+}
+
+/**
+ * Welcome payload sent on initial connection
+ */
+export interface WelcomePayload {
+  /** Connection ID for reconnection */
+  connectionId: string
+  /** Server timestamp */
+  timestamp: number
+  /** Heartbeat interval in milliseconds */
+  heartbeatInterval: number
+  /** Server version */
+  version: string
+}
+
+/**
+ * Reconnect payload for restoring subscriptions
+ */
+export interface ReconnectPayload {
+  /** Previous connection ID */
+  connectionId: string
+  /** Last received LSN for resumption */
+  lastLsn?: string | undefined
+  /** Subscription IDs to restore */
+  subscriptionIds?: string[] | undefined
+}
+
+/**
+ * Subscribed payload confirming subscription
+ */
+export interface SubscribedPayload {
+  /** Generated subscription ID */
+  subscriptionId: string
+  /** Table being subscribed to */
+  table: string
+  /** Events being subscribed to */
+  events: CDCEventType[]
+  /** Filter expression if provided */
+  filter?: string | undefined
+}
+
+/**
+ * Unsubscribed payload confirming unsubscription
+ */
+export interface UnsubscribedPayload {
+  /** Subscription ID that was removed */
+  subscriptionId: string
+}
+
+/**
+ * Error payload
+ */
+export interface ErrorPayload {
+  code: string
+  message: string
+  details?: Record<string, unknown> | undefined
+}
+
+/**
+ * WebSocket message structure
+ */
+export interface WSMessage {
+  type: WSMessageType
+  id: string
+  payload?: QueryRequest | QueryResponse | SubscribePayload | UnsubscribePayload | ChangePayload | ErrorPayload | HeartbeatPayload | WelcomePayload | ReconnectPayload | SubscribedPayload | UnsubscribedPayload | Record<string, unknown> | undefined
+}
+
+/**
+ * CDC WebSocket configuration
+ */
+export interface CDCWebSocketConfig {
+  /** Heartbeat interval in milliseconds (default: 30000) */
+  heartbeatInterval?: number
+  /** Heartbeat timeout - close connection if no response (default: 10000) */
+  heartbeatTimeout?: number
+  /** Max reconnection attempts (default: 5) */
+  maxReconnectAttempts?: number
+  /** Reconnection delay in milliseconds (default: 1000) */
+  reconnectDelay?: number
+  /** Max subscriptions per connection (default: 100) */
+  maxSubscriptions?: number
+  /** Enable change buffering during reconnection (default: true) */
+  bufferChanges?: boolean
+  /** Max buffered changes per subscription (default: 1000) */
+  maxBufferedChanges?: number
+}
+
+/**
+ * Plugin configuration value - boolean or options object
+ */
+export type PluginValue = boolean | {
+  enabled: boolean
+  autoCreate?: boolean
+  config?: Record<string, unknown>
+}
+
+/**
+ * Supported plugin names for PostgresDO
+ */
+export type SupportedPlugin =
+  | 'vector'
+  | 'pgsearch'
+  | 'postgis'
+  | 'pg_lake'
+  | 'pgmq'
+  | 'pg_trgm'
+  | 'hstore'
+  | 'citext'
+  | 'uuid_ossp'
+  | 'pgcrypto'
+  | 'btree_gin'
+  | 'btree_gist'
+  | 'fuzzystrmatch'
+  | 'intarray'
+  | 'ltree'
+  | 'tablefunc'
+  | 'unaccent'
+
+/**
+ * PostgreSQL configuration for PGlite
+ */
+export interface PostgresConfig {
+  database: string
+  extensions?: string[]
+  memoryLimitMB?: number
+  preserveCase?: boolean
+  dataDir?: string
+  debug?: boolean
+  /** Migration configuration for automatic schema management */
+  migrations?: MigrationConfig
+
+  /**
+   * Plugin/extension configuration for PGLite
+   *
+   * Enable extensions using simple flags or configuration objects.
+   * Extensions are loaded during PGLite initialization.
+   *
+   * @example
+   * ```typescript
+   * // Simple boolean flags
+   * plugins: {
+   *   vector: true,
+   *   pg_trgm: true,
+   * }
+   *
+   * // With auto-create option
+   * plugins: {
+   *   vector: { enabled: true, autoCreate: true },
+   *   hstore: { enabled: true, autoCreate: true },
+   * }
+   * ```
+   */
+  plugins?: Partial<Record<SupportedPlugin, PluginValue>>
+
+  /**
+   * Injected concerns for dependency injection and testing.
+   * Each concern can be independently instantiated and injected
+   * for modularity and testability.
+   */
+  concerns?: {
+    auth?: unknown
+    queryExecution?: unknown
+    cdc?: unknown
+    storageOrchestration?: unknown
+  }
+}
+
+// ============================================================================
+// Schema Versioning Types
+// ============================================================================
+
+/**
+ * Migration status values
+ */
+export type MigrationStatus = 'pending' | 'applied' | 'failed' | 'rolled_back'
+
+/**
+ * Individual migration record stored in the migrations table
+ */
+export interface MigrationRecord {
+  /** Migration identifier (e.g., '0001_initial') */
+  id: string
+  /** Human-readable name */
+  name: string
+  /** Numeric version for ordering */
+  version: number
+  /** SHA-256 checksum of migration content */
+  checksum: string
+  /** ISO timestamp when migration was applied */
+  applied_at: string
+  /** Execution time in milliseconds */
+  execution_time_ms: number
+  /** Current status of the migration */
+  status: MigrationStatus
+}
+
+/**
+ * Schema version metadata for a DO instance
+ */
+export interface SchemaVersion {
+  /** Current schema version number (highest applied migration) */
+  currentVersion: number
+  /** Total number of applied migrations */
+  appliedCount: number
+  /** Timestamp of last migration */
+  lastMigrationAt: string | null
+  /** List of all migration records */
+  migrations: MigrationRecord[]
+}
+
+/**
+ * Migration input for applying a new migration
+ */
+export interface MigrationInput {
+  /** Migration identifier (e.g., '0001_initial') */
+  id: string
+  /** Human-readable name */
+  name: string
+  /** Numeric version for ordering */
+  version: number
+  /** SQL to execute for this migration */
+  sql: string
+}
+
+/**
+ * Result of applying a migration
+ */
+export interface MigrationResult {
+  /** Whether the migration was successful */
+  success: boolean
+  /** Migration ID */
+  id: string
+  /** Execution time in milliseconds */
+  executionTimeMs: number
+  /** Error message if failed */
+  error?: string
+  /** Whether this migration was already applied (skipped) */
+  skipped?: boolean
+}
+
+/**
+ * Version comparison result
+ */
+export interface VersionComparison {
+  /** Current schema version in the DO */
+  current: number
+  /** Target version being compared against */
+  target: number
+  /** Whether the schema needs migration */
+  needsMigration: boolean
+  /** Number of migrations needed to reach target */
+  pendingCount: number
+  /** List of missing migration versions */
+  missingVersions: number[]
+}
+
+/**
+ * Migration progress event for callbacks
+ */
+export interface MigrationProgressEvent {
+  /** The migration being processed */
+  migration: MigrationInput
+  /** Zero-based index of current migration */
+  index: number
+  /** Total number of migrations to run */
+  total: number
+  /** Phase of the migration */
+  phase: 'starting' | 'executing' | 'completed' | 'failed'
+  /** Duration in milliseconds (only set on completion) */
+  durationMs?: number
+  /** Error message if failed */
+  error?: string
+}
+
+/**
+ * Migration timing strategy
+ *
+ * - 'on-create': Run migrations during DO initialization (default)
+ * - 'on-demand': Defer migrations until first query (lazy migration)
+ */
+export type MigrationStrategy = 'on-create' | 'on-demand'
+
+/**
+ * Migration state tracked in DO storage
+ */
+export interface MigrationState {
+  /** Current migration status */
+  status: 'pending' | 'in-progress' | 'completed' | 'failed'
+  /** Schema version after migrations */
+  version: number
+  /** Last migration attempt timestamp (ISO string) */
+  lastAttemptAt?: string
+  /** Error message if failed */
+  error?: string
+  /** Duration of last migration run in ms */
+  durationMs?: number
+}
+
+/**
+ * Migration configuration for PostgresDO
+ */
+export interface MigrationConfig {
+  /** Migrations to run (will be sorted by version) */
+  migrations: MigrationInput[]
+  /** Callback when migration progress changes */
+  onProgress?: (event: MigrationProgressEvent) => void
+  /** Timeout for each individual migration in milliseconds (default: 30000) */
+  migrationTimeoutMs?: number
+  /** Whether to run migrations automatically on first connection (default: true) */
+  autoMigrate?: boolean
+  /**
+   * Migration timing strategy (default: 'on-create')
+   *
+   * - 'on-create': Run migrations during DO initialization (immediate)
+   * - 'on-demand': Defer migrations until first query (lazy)
+   *
+   * Use 'on-demand' to reduce cold start latency when migrations are expensive.
+   * The first query will incur the migration cost.
+   */
+  strategy?: MigrationStrategy
+}
+
+/**
+ * Batch migration result
+ */
+export interface BatchMigrationResult {
+  /** Whether all migrations completed successfully */
+  success: boolean
+  /** Starting schema version */
+  fromVersion: number
+  /** Ending schema version */
+  toVersion: number
+  /** Total duration in milliseconds */
+  durationMs: number
+  /** Individual migration results */
+  results: MigrationResult[]
+  /** Number of migrations executed */
+  migrationsRun: number
+  /** Number of migrations skipped (already applied) */
+  migrationsSkipped: number
+}
+
+// ============================================================================
+// Plugin Management Types
+// ============================================================================
+
+/**
+ * Plugin status information
+ */
+export interface PluginStatus {
+  /** Plugin name */
+  name: string
+  /** Display name for UI */
+  displayName: string
+  /** Plugin description */
+  description: string
+  /** Plugin category */
+  category: string
+  /** Whether the plugin is available in PGLite WASM */
+  available: boolean
+  /** Whether the plugin is enabled in configuration */
+  enabled: boolean
+  /** Whether the extension has been created in the database */
+  created: boolean
+  /** PostgreSQL extension name */
+  extensionName: string
+  /** Dependencies on other plugins */
+  dependencies?: string[]
+}
+
+/**
+ * Response for listing all plugins
+ */
+export interface PluginListResponse {
+  /** All available plugins with their status */
+  plugins: PluginStatus[]
+  /** Number of enabled plugins */
+  enabledCount: number
+  /** Number of available plugins */
+  availableCount: number
+  /** Timestamp of the response */
+  timestamp: string
+}
+
+/**
+ * Request to enable or disable a plugin
+ */
+export interface PluginToggleRequest {
+  /** Plugin name to enable/disable */
+  name: string
+  /** Whether to enable or disable */
+  enabled: boolean
+  /** Whether to auto-create the extension */
+  autoCreate?: boolean
+}
+
+/**
+ * Response for plugin toggle operation
+ */
+export interface PluginToggleResponse {
+  /** Whether the operation was successful */
+  success: boolean
+  /** Plugin name */
+  name: string
+  /** New enabled state */
+  enabled: boolean
+  /** Whether the extension was created */
+  created?: boolean
+  /** Error message if failed */
+  error?: string
+  /** Timestamp of the response */
+  timestamp: string
+}
+
+/**
+ * Request to enable multiple plugins
+ */
+export interface PluginBatchToggleRequest {
+  /** Plugins to enable */
+  enable?: string[]
+  /** Plugins to disable */
+  disable?: string[]
+  /** Whether to auto-create enabled extensions */
+  autoCreate?: boolean
+}
+
+/**
+ * Response for batch plugin toggle operation
+ */
+export interface PluginBatchToggleResponse {
+  /** Whether all operations were successful */
+  success: boolean
+  /** Results for each plugin */
+  results: PluginToggleResponse[]
+  /** Timestamp of the response */
+  timestamp: string
+}
+
+// ============================================================================
+// Memory Pressure Monitoring Types
+// ============================================================================
+
+/**
+ * Memory pressure levels for OOM protection
+ *
+ * - 'normal': Memory usage is within acceptable bounds
+ * - 'warning': Memory usage is elevated, consider reducing allocations
+ * - 'critical': Memory usage is near the limit, take immediate action
+ * - 'oom': Out of memory - operations may fail
+ */
+export type MemoryPressureLevel = 'normal' | 'warning' | 'critical' | 'oom'
+
+/**
+ * Memory usage statistics
+ */
+export interface MemoryStats {
+  /** Estimated WASM heap size in bytes */
+  heapUsed: number
+  /** Maximum heap size in bytes (Cloudflare Workers: 128MB) */
+  heapLimit: number
+  /** Memory usage as a percentage (0-100) */
+  usagePercent: number
+  /** Current memory pressure level */
+  pressureLevel: MemoryPressureLevel
+  /** Timestamp of measurement */
+  timestamp: Date
+}
+
+/**
+ * Memory pressure event for callbacks
+ */
+export interface MemoryPressureEvent {
+  /** Previous pressure level */
+  previousLevel: MemoryPressureLevel
+  /** Current pressure level */
+  currentLevel: MemoryPressureLevel
+  /** Memory statistics at time of event */
+  stats: MemoryStats
+  /** Actions taken in response to pressure */
+  actionsTaken: MemoryPressureAction[]
+  /** Timestamp of event */
+  timestamp: Date
+}
+
+/**
+ * Actions that can be taken under memory pressure
+ */
+export type MemoryPressureAction =
+  | 'extension_unloaded'
+  | 'cache_cleared'
+  | 'query_cancelled'
+  | 'gc_triggered'
+  | 'warning_emitted'
+
+/**
+ * Result of a memory pressure action
+ */
+export interface MemoryPressureActionResult {
+  /** Action type */
+  action: MemoryPressureAction
+  /** Whether the action was successful */
+  success: boolean
+  /** Bytes freed (if applicable) */
+  bytesFreed?: number
+  /** Extension name (if action was extension_unloaded) */
+  extensionName?: string
+  /** Error message if action failed */
+  error?: string
+}
+
+/**
+ * Memory pressure configuration
+ */
+export interface MemoryPressureConfig {
+  /** Enable memory pressure monitoring (default: true) */
+  enabled?: boolean
+  /** Memory limit in bytes (default: 128MB for Cloudflare Workers) */
+  memoryLimitBytes?: number
+  /** Warning threshold as percentage (default: 70) */
+  warningThresholdPercent?: number
+  /** Critical threshold as percentage (default: 85) */
+  criticalThresholdPercent?: number
+  /** OOM threshold as percentage (default: 95) */
+  oomThresholdPercent?: number
+  /** How often to check memory pressure in ms (default: 5000) */
+  checkIntervalMs?: number
+  /** Auto-unload extensions under critical pressure (default: true) */
+  autoUnloadExtensions?: boolean
+  /** Extensions to prioritize for unloading (lowest priority first) */
+  extensionUnloadPriority?: string[]
+  /** Maximum number of listeners (default: 50) */
+  maxListeners?: number
+}
+
+/**
+ * Listener for memory pressure events
+ */
+export type MemoryPressureListener = (event: MemoryPressureEvent) => void
+
+// ============================================================================
+// Discriminated Union Types for WebSocket Messages
+// ============================================================================
+
+/**
+ * Query message - client requests SQL execution
+ */
+export interface WSQueryMessage {
+  type: 'query'
+  id: string
+  payload: QueryRequest
+}
+
+/**
+ * Subscribe message - client subscribes to CDC events
+ */
+export interface WSSubscribeMessage {
+  type: 'subscribe'
+  id: string
+  payload: SubscribePayload
+}
+
+/**
+ * Unsubscribe message - client unsubscribes from CDC events
+ */
+export interface WSUnsubscribeMessage {
+  type: 'unsubscribe'
+  id: string
+  payload: UnsubscribePayload
+}
+
+/**
+ * Ping message - client keepalive
+ */
+export interface WSPingMessage {
+  type: 'ping'
+  id: string
+  payload?: undefined
+}
+
+/**
+ * Pong message - server response to ping
+ */
+export interface WSPongMessage {
+  type: 'pong'
+  id: string
+  payload?: undefined
+}
+
+/**
+ * Result message - server response with query results
+ */
+export interface WSResultMessage {
+  type: 'result'
+  id: string
+  payload: QueryResponse
+}
+
+/**
+ * Error message - server error response
+ */
+export interface WSErrorMessage {
+  type: 'error'
+  id: string
+  payload: ErrorPayload
+}
+
+/**
+ * Change message - CDC change notification
+ */
+export interface WSChangeMessage {
+  type: 'change'
+  id: string
+  payload: ChangePayload
+}
+
+/**
+ * Subscribed message - confirmation of subscription
+ */
+export interface WSSubscribedMessage {
+  type: 'subscribed'
+  id: string
+  payload: SubscribedPayload
+}
+
+/**
+ * Unsubscribed message - confirmation of unsubscription
+ */
+export interface WSUnsubscribedMessage {
+  type: 'unsubscribed'
+  id: string
+  payload?: UnsubscribedPayload
+}
+
+/**
+ * Heartbeat message - server keepalive
+ */
+export interface WSHeartbeatMessage {
+  type: 'heartbeat'
+  id: string
+  payload?: HeartbeatPayload
+}
+
+/**
+ * Heartbeat acknowledgment message - client response to heartbeat
+ */
+export interface WSHeartbeatAckMessage {
+  type: 'heartbeat_ack'
+  id: string
+  payload?: HeartbeatPayload
+}
+
+/**
+ * Reconnect message - client reconnection request
+ */
+export interface WSReconnectMessage {
+  type: 'reconnect'
+  id: string
+  payload: ReconnectPayload
+}
+
+/**
+ * Welcome message - server greeting on connection
+ */
+export interface WSWelcomeMessage {
+  type: 'welcome'
+  id: string
+  payload: WelcomePayload
+}
+
+/**
+ * Discriminated union of all WebSocket message types
+ *
+ * This enables exhaustive switch checking and clean type narrowing:
+ * ```typescript
+ * function handleMessage(msg: WSTypedMessage) {
+ *   switch (msg.type) {
+ *     case 'query':
+ *       // TypeScript knows msg.payload is QueryRequest
+ *       return handleQuery(msg.payload)
+ *     case 'result':
+ *       // TypeScript knows msg.payload is QueryResponse
+ *       return handleResult(msg.payload)
+ *     // ... other cases
+ *   }
+ * }
+ * ```
+ */
+export type WSTypedMessage =
+  | WSQueryMessage
+  | WSSubscribeMessage
+  | WSUnsubscribeMessage
+  | WSPingMessage
+  | WSPongMessage
+  | WSResultMessage
+  | WSErrorMessage
+  | WSChangeMessage
+  | WSSubscribedMessage
+  | WSUnsubscribedMessage
+  | WSHeartbeatMessage
+  | WSHeartbeatAckMessage
+  | WSReconnectMessage
+  | WSWelcomeMessage