@dotdo/postgres 0.1.0

package/dist/worker/websocket.js

@@ -0,0 +1,227 @@
+import { WebSocketMessageError } from './errors';
+/**
+ * WebSocket ready states
+ */
+const WS_OPEN = 1;
+/**
+ * Parse a WebSocket message from string
+ */
+export function parseWSMessage(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new WebSocketMessageError('Invalid JSON message', { cause: e instanceof Error ? e : undefined });
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new WebSocketMessageError('Message must be an object');
+    }
+    const obj = parsed;
+    if (typeof obj.type !== 'string') {
+        throw new WebSocketMessageError('Message must have a type field', { messageType: 'unknown' });
+    }
+    if (typeof obj.id !== 'string') {
+        throw new WebSocketMessageError('Message must have an id field', { messageType: obj.type });
+    }
+    return {
+        type: obj.type,
+        id: obj.id,
+        payload: obj.payload,
+    };
+}
+/**
+ * Serialize a WebSocket message to string
+ */
+export function serializeWSMessage(message) {
+    return JSON.stringify(message);
+}
+/**
+ * WebSocket handler for PostgresDO with hibernation support
+ */
+export class WebSocketHandler {
+    state;
+    executor;
+    constructor(state, executor) {
+        this.state = state;
+        this.executor = executor;
+    }
+    /**
+     * Handle WebSocket upgrade request with hibernation
+     */
+    handleUpgrade(request, webSocketPair) {
+        const upgradeHeader = request.headers.get('Upgrade');
+        if (upgradeHeader !== 'websocket' || !webSocketPair) {
+            return new Response('Expected WebSocket upgrade', { status: 400 });
+        }
+        const client = webSocketPair[0];
+        const server = webSocketPair[1];
+        // Accept the WebSocket with hibernation
+        // This is critical for 95% cost savings!
+        this.state.acceptWebSocket(server);
+        return new Response(null, {
+            status: 101,
+            webSocket: client,
+        });
+    }
+    /**
+     * Handle incoming WebSocket message
+     * Called by webSocketMessage() hibernation callback
+     */
+    async handleMessage(ws, rawMessage) {
+        const messageStr = typeof rawMessage === 'string'
+            ? rawMessage
+            : new TextDecoder().decode(rawMessage);
+        try {
+            const message = parseWSMessage(messageStr);
+            switch (message.type) {
+                case 'ping':
+                    this.sendMessage(ws, {
+                        type: 'pong',
+                        id: message.id,
+                    });
+                    break;
+                case 'query':
+                    await this.handleQuery(ws, message);
+                    break;
+                case 'subscribe':
+                    await this.handleSubscribe(ws, message);
+                    break;
+                case 'unsubscribe':
+                    await this.handleUnsubscribe(ws, message);
+                    break;
+                default:
+                    this.sendError(ws, message.id, 'UNKNOWN_TYPE', `Unknown message type: ${message.type}`);
+            }
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            this.sendError(ws, 'unknown', 'PARSE_ERROR', errorMessage);
+        }
+    }
+    /**
+     * Handle query message
+     */
+    async handleQuery(ws, message) {
+        try {
+            const payload = message.payload;
+            if (!payload?.sql) {
+                this.sendError(ws, message.id, 'INVALID_REQUEST', 'Missing sql in payload');
+                return;
+            }
+            const result = await this.executor.executeQuery(payload);
+            this.sendMessage(ws, {
+                type: 'result',
+                id: message.id,
+                payload: result,
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Query failed';
+            this.sendError(ws, message.id, 'QUERY_ERROR', errorMessage);
+        }
+    }
+    /**
+     * Handle subscribe message (placeholder for CDC)
+     */
+    async handleSubscribe(ws, message) {
+        // CDC subscription will be implemented in postgres-6u6.6
+        this.sendMessage(ws, {
+            type: 'subscribed',
+            id: message.id,
+            payload: {
+                subscriptionId: `sub-${Date.now()}`,
+            },
+        });
+    }
+    /**
+     * Handle unsubscribe message (placeholder for CDC)
+     */
+    async handleUnsubscribe(ws, message) {
+        // CDC unsubscription will be implemented in postgres-6u6.6
+        this.sendMessage(ws, {
+            type: 'unsubscribed',
+            id: message.id,
+        });
+    }
+    /**
+     * Handle WebSocket close
+     * Called by webSocketClose() hibernation callback
+     */
+    handleClose(_ws, code, reason) {
+        // Clean up any subscriptions for this WebSocket
+        // This will be enhanced in postgres-6u6.6
+        console.log(`WebSocket closed: ${code} - ${reason}`);
+    }
+    /**
+     * Handle WebSocket error
+     * Called by webSocketError() hibernation callback
+     */
+    handleError(ws, error) {
+        console.error('WebSocket error:', error);
+        try {
+            ws.close(1011, 'Internal error');
+        }
+        catch {
+            // WebSocket might already be closed
+        }
+    }
+    /**
+     * Broadcast a message to all connected WebSockets
+     */
+    broadcast(message, filter) {
+        const webSockets = this.state.getWebSockets();
+        const messageStr = serializeWSMessage(message);
+        for (const ws of webSockets) {
+            if (ws.readyState !== WS_OPEN) {
+                continue;
+            }
+            if (filter && !filter(ws)) {
+                continue;
+            }
+            try {
+                ws.send(messageStr);
+            }
+            catch (error) {
+                console.error('Failed to send to WebSocket:', error);
+            }
+        }
+    }
+    /**
+     * Get number of connected WebSockets
+     */
+    getConnectedCount() {
+        return this.state.getWebSockets().length;
+    }
+    /**
+     * Send a message to a specific WebSocket
+     */
+    sendMessage(ws, message) {
+        try {
+            ws.send(serializeWSMessage(message));
+        }
+        catch (error) {
+            console.error('Failed to send message:', error);
+        }
+    }
+    /**
+     * Send an error message
+     */
+    sendError(ws, id, code, message) {
+        this.sendMessage(ws, {
+            type: 'error',
+            id,
+            payload: {
+                code,
+                message,
+            },
+        });
+    }
+}
+/**
+ * Factory function to create a WebSocketHandler
+ */
+export function createWebSocketHandler(state, executor) {
+    return new WebSocketHandler(state, executor);
+}
+//# sourceMappingURL=websocket.js.map

package/dist/worker/websocket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.js","sourceRoot":"","sources":["../../src/worker/websocket.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,108 @@
+{
+  "name": "@dotdo/postgres",
+  "version": "0.1.0",
+  "description": "PostgreSQL server for Cloudflare Workers/DOs with PGLite WASM and tiered storage",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./pglite": {
+      "types": "./dist/pglite/index.d.ts",
+      "import": "./dist/pglite/index.js"
+    },
+    "./worker": {
+      "types": "./dist/worker/index.d.ts",
+      "import": "./dist/worker/index.js"
+    },
+    "./observability": {
+      "types": "./dist/observability/index.d.ts",
+      "import": "./dist/observability/index.js"
+    },
+    "./iceberg": {
+      "types": "./dist/iceberg/index.d.ts",
+      "import": "./dist/iceberg/index.js"
+    },
+    "./migrations": {
+      "types": "./dist/migrations/index.d.ts",
+      "import": "./dist/migrations/index.js"
+    },
+    "./migrations/validator": {
+      "types": "./dist/migrations/validator.d.ts",
+      "import": "./dist/migrations/validator.js"
+    },
+    "./migrations/testing": {
+      "types": "./dist/migrations/testing.d.ts",
+      "import": "./dist/migrations/testing.js"
+    },
+    "./migration-tooling": {
+      "types": "./dist/migration-tooling/index.d.ts",
+      "import": "./dist/migration-tooling/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc && pnpm copy-assets",
+    "copy-assets": "mkdir -p dist/pglite-assets && cp src/pglite-assets/* dist/pglite-assets/",
+    "dev": "tsc --watch",
+    "dev:worker": "wrangler dev",
+    "deploy": "pnpm build && wrangler deploy",
+    "deploy:dry-run": "pnpm build && wrangler deploy --dry-run",
+    "tail": "wrangler tail",
+    "test": "vitest run",
+    "test:unit": "vitest run --config vitest.config.ts",
+    "test:workers": "vitest run --config vitest.workers.config.ts",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@dotdo/pglite": "^0.1.0",
+    "@dotdo/postgres-shared": "^0.1.0",
+    "capnweb": "^0.4.0",
+    "hono": "^4.0.0",
+    "postgres.do": "^0.1.0"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.8.0",
+    "@cloudflare/workers-types": "^4.20260115.0",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^2.1.0",
+    "async-mutex": "^0.4.1",
+    "miniflare": "^3.20250718.0",
+    "pg-protocol": "^1.11.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0",
+    "wrangler": "^3.101.0"
+  },
+  "keywords": [
+    "postgres",
+    "postgresql",
+    "pglite",
+    "wasm",
+    "cloudflare",
+    "workers",
+    "durable-objects",
+    "serverless",
+    "iceberg",
+    "parquet",
+    "time-travel"
+  ],
+  "author": "dot.do",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dot-do/postgres.git",
+    "directory": "packages/postgres"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cdc/change-stream.ts

@@ -0,0 +1,137 @@
+/**
+ * Change Stream Implementation
+ * Task: postgres-lp00 - CDC/Change Data Capture streaming
+ *
+ * Stub file - full implementation pending
+ */
+
+import type {
+  ChangeEvent,
+  ChangeStreamOptions,
+  ChangeStreamFilter,
+  ResumeToken,
+  CDCOperation,
+} from './types'
+import { createResumeToken } from './resume-token'
+
+// ============================================================================
+// ChangeStream Class
+// ============================================================================
+
+/**
+ * Change stream for CDC events
+ * Provides async iteration and event-based APIs
+ */
+export class ChangeStream<T = Record<string, unknown>>
+  implements AsyncIterable<ChangeEvent<T>>
+{
+  readonly tables: string[]
+  readonly options: ChangeStreamOptions
+  private closed = false
+
+  constructor(tables: string | string[], options?: ChangeStreamOptions) {
+    this.tables = Array.isArray(tables) ? tables : [tables]
+    this.options = options ?? {}
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterableIterator<ChangeEvent<T>> {
+    // Stub - would connect to transport and yield events
+    yield* []
+  }
+
+  on(_event: string, _handler: (...args: unknown[]) => void): this {
+    return this
+  }
+
+  off(_event: string, _handler: (...args: unknown[]) => void): this {
+    return this
+  }
+
+  async close(): Promise<void> {
+    this.closed = true
+  }
+
+  isClosed(): boolean {
+    return this.closed
+  }
+
+  getResumeToken(): ResumeToken | null {
+    return null
+  }
+}
+
+// ============================================================================
+// Factory Functions
+// ============================================================================
+
+/**
+ * Create a change stream for one or more tables
+ */
+export function createChangeStream<T = Record<string, unknown>>(
+  tables: string | string[],
+  options?: ChangeStreamOptions
+): ChangeStream<T> {
+  return new ChangeStream<T>(tables, options)
+}
+
+/**
+ * Create a change stream with filtering
+ */
+export function createFilteredChangeStream<T = Record<string, unknown>>(
+  tables: string | string[],
+  filter: ChangeStreamFilter,
+  options?: ChangeStreamOptions
+): ChangeStream<T> {
+  return new ChangeStream<T>(tables, {
+    ...options,
+    filter,
+  })
+}
+
+/**
+ * Watch all tables
+ */
+export function watchAll<T = Record<string, unknown>>(
+  options?: ChangeStreamOptions
+): ChangeStream<T> {
+  return new ChangeStream<T>('*', options)
+}
+
+// ============================================================================
+// Test Utilities
+// ============================================================================
+
+/**
+ * Create a mock change stream for testing
+ */
+export function createMockChangeStream<T = Record<string, unknown>>(
+  events: ChangeEvent<T>[]
+): ChangeStream<T> {
+  const stream = new ChangeStream<T>([])
+  // Override the iterator to yield provided events
+  ;(stream as unknown as { events: ChangeEvent<T>[] }).events = events
+  return stream
+}
+
+/**
+ * Create a test change event
+ */
+export function createTestChangeEvent<T = Record<string, unknown>>(
+  operation: CDCOperation,
+  table: string,
+  data: Partial<ChangeEvent<T>> = {}
+): ChangeEvent<T> {
+  const timestamp = Date.now()
+  const lsn = String(timestamp)
+
+  return {
+    id: `test-${timestamp}-${Math.random().toString(36).slice(2)}`,
+    lsn,
+    operation,
+    schema: 'public',
+    table,
+    timestamp,
+    resumeToken: createResumeToken(lsn, timestamp),
+    ...data,
+  } as ChangeEvent<T>
+}