dzql 0.1.0-alpha.1

package/src/server/meta-route.js

@@ -0,0 +1,251 @@
+import { sql } from './db.js';
+
+export function metaRoute() {
+  return async (req) => {
+    try {
+      // Get entity metadata from dzql.entities
+      const entities = await sql`
+        SELECT table_name, label_field, searchable_fields,
+               fk_includes, notification_paths, permission_paths
+        FROM dzql.entities
+        ORDER BY table_name
+      `;
+
+      // Analyze foreign key relationships to determine relationship types
+      const foreignKeys = await sql`
+        SELECT
+          tc.table_name,
+          kcu.column_name,
+          ccu.table_name AS foreign_table_name,
+          ccu.column_name AS foreign_column_name
+        FROM
+          information_schema.table_constraints AS tc
+          JOIN information_schema.key_column_usage AS kcu
+            ON tc.constraint_name = kcu.constraint_name
+            AND tc.table_schema = kcu.table_schema
+          JOIN information_schema.constraint_column_usage AS ccu
+            ON ccu.constraint_name = tc.constraint_name
+            AND ccu.table_schema = tc.table_schema
+        WHERE tc.constraint_type = 'FOREIGN KEY'
+          AND tc.table_schema = 'public'
+        ORDER BY tc.table_name, kcu.column_name
+      `;
+
+      // Get complete table schema information
+      const schemaInfo = await sql`
+        SELECT
+          table_name,
+          column_name,
+          data_type,
+          is_nullable,
+          column_default,
+          character_maximum_length,
+          numeric_precision,
+          numeric_scale,
+          ordinal_position
+        FROM information_schema.columns
+        WHERE table_schema = 'public'
+          AND table_name = ANY(${entities.map(e => e.table_name)})
+        ORDER BY table_name, ordinal_position
+      `;
+
+      // Find junction tables for many-to-many relationships
+      const junctionTables = new Set();
+      const entityNames = new Set(entities.map(e => e.table_name));
+
+      // Group foreign keys by table to identify junction tables
+      const fksByTable = {};
+      foreignKeys.forEach(fk => {
+        if (!entityNames.has(fk.table_name)) return;
+        if (!fksByTable[fk.table_name]) fksByTable[fk.table_name] = [];
+        fksByTable[fk.table_name].push(fk);
+      });
+
+      // Identify junction tables (2+ foreign keys, minimal other fields)
+      Object.keys(fksByTable).forEach(tableName => {
+        const fks = fksByTable[tableName];
+        if (fks.length >= 2) {
+          const entity = entities.find(e => e.table_name === tableName);
+          const searchableFields = entity?.searchable_fields || [];
+          const nonFkFields = searchableFields.filter(field =>
+            !fks.some(fk => fk.column_name === field)
+          );
+          if (nonFkFields.length <= 1) {
+            junctionTables.add(tableName);
+          }
+        }
+      });
+
+      // Build relations array
+      const relations = [];
+
+      // Add foreign key relationships (both directions)
+      foreignKeys.forEach(fk => {
+        if (!entityNames.has(fk.table_name) || !entityNames.has(fk.foreign_table_name)) return;
+
+        // Skip junction tables - they'll be handled as many-to-many
+        if (junctionTables.has(fk.table_name)) return;
+
+        // Many-to-one: child.foreign_key → parent.primary_key
+        relations.push({
+          type: 'many_to_one',
+          from: `${fk.table_name}.${fk.column_name}`,
+          to: `${fk.foreign_table_name}.${fk.foreign_column_name}`
+        });
+
+        // One-to-many: parent.primary_key ← child.foreign_key
+        relations.push({
+          type: 'one_to_many',
+          from: `${fk.foreign_table_name}.${fk.foreign_column_name}`,
+          to: `${fk.table_name}.${fk.column_name}`
+        });
+      });
+
+      // Add many-to-many relationships through junction tables
+      junctionTables.forEach(tableName => {
+        const fks = fksByTable[tableName];
+        // For each pair of foreign keys in the junction table
+        for (let i = 0; i < fks.length; i++) {
+          for (let j = i + 1; j < fks.length; j++) {
+            const fk1 = fks[i];
+            const fk2 = fks[j];
+
+            // Both directions of many-to-many
+            relations.push({
+              type: 'many_to_many',
+              from: `${fk1.foreign_table_name}.${fk1.foreign_column_name}`,
+              to: `${fk2.foreign_table_name}.${fk2.foreign_column_name}`,
+              via: `${tableName}.${fk1.column_name}.${fk2.column_name}`
+            });
+
+            relations.push({
+              type: 'many_to_many',
+              from: `${fk2.foreign_table_name}.${fk2.foreign_column_name}`,
+              to: `${fk1.foreign_table_name}.${fk1.foreign_column_name}`,
+              via: `${tableName}.${fk2.column_name}.${fk1.column_name}`
+            });
+          }
+        }
+      });
+
+      // Build schema object grouped by table
+      const schema = {};
+      schemaInfo.forEach(col => {
+        if (!schema[col.table_name]) {
+          schema[col.table_name] = [];
+        }
+        schema[col.table_name].push({
+          column_name: col.column_name,
+          data_type: col.data_type,
+          is_nullable: col.is_nullable === 'YES',
+          column_default: col.column_default,
+          character_maximum_length: col.character_maximum_length,
+          numeric_precision: col.numeric_precision,
+          numeric_scale: col.numeric_scale,
+          ordinal_position: col.ordinal_position
+        });
+      });
+
+     // Build navigation graph from user starting point
+     const navigationGraph = buildNavigationGraph(entities, relations, schema);
+
+     const metadata = {
+        entities: entities,
+        relations: relations,
+        schema: schema,
+        navigationGraph: navigationGraph,
+        operations: ['get', 'save', 'delete', 'lookup', 'search'],
+        timestamp: new Date().toISOString()
+      };
+
+      return new Response(JSON.stringify(metadata, null, 2), {
+        headers: { 'Content-Type': 'application/json' }
+      });
+    } catch (error) {
+      return new Response(JSON.stringify({ error: error.message }), {
+        status: 500,
+        headers: { 'Content-Type': 'application/json' }
+      });
+    }
+  };
+}
+
+function buildNavigationGraph(entities, relations, schema) {
+  const graph = {};
+
+  // Helper to detect UI patterns from schema
+  function getUiHints(entityName) {
+    const entitySchema = schema[entityName] || [];
+    const hints = { primary_view: 'table', alternate_view: 'form', temporal_fields: [], geo_fields: [] };
+
+    entitySchema.forEach(col => {
+      if (col.data_type.includes('date') || col.data_type.includes('time')) {
+        hints.temporal_fields.push(col.column_name);
+      }
+      if (col.column_name.toLowerCase().includes('address') ||
+          col.column_name.toLowerCase().includes('location')) {
+        hints.geo_fields.push(col.column_name);
+        hints.primary_view = 'map';
+      }
+    });
+
+    if (hints.temporal_fields.length > 0) {
+      hints.alternate_view = 'calendar';
+    }
+
+    return hints;
+  }
+
+  // Build navigation paths starting from user
+  function buildPathsFrom(currentEntity, currentPath, visited, maxDepth) {
+    if (maxDepth <= 0 || visited.has(currentEntity)) return;
+
+    visited.add(currentEntity);
+    const pathKey = currentPath.join('→');
+
+    if (!graph[pathKey]) {
+      const entity = entities.find(e => e.table_name === currentEntity);
+      graph[pathKey] = {
+        path: pathKey,
+        current_entity: currentEntity,
+        available_actions: entity ? Object.keys(entity.permission_paths) : [],
+        navigation_options: [],
+        ui_hints: getUiHints(currentEntity),
+        breadcrumb: currentPath.map(p => p.split('.')[0])
+      };
+    }
+
+    // Find all outgoing relations from current entity
+    relations.forEach(rel => {
+      const fromEntity = rel.from.split('.')[0];
+      const toEntity = rel.to.split('.')[0];
+
+      if (fromEntity === currentEntity && !visited.has(toEntity)) {
+        graph[pathKey].navigation_options.push({
+          to: toEntity,
+          via: `${rel.from}→${rel.to}`,
+          relationship: rel.type
+        });
+
+        // Recursively build paths
+        const newPath = [...currentPath, rel.to];
+        buildPathsFrom(toEntity, newPath, new Set(visited), maxDepth - 1);
+      }
+    });
+
+    visited.delete(currentEntity);
+  }
+
+  // Start building from user
+  const userRelations = relations.filter(rel => rel.from.startsWith('users.') || rel.to.startsWith('users.'));
+  if (userRelations.length === 0) {
+    // If no direct user relations, start from all entities
+    entities.forEach(entity => {
+      buildPathsFrom(entity.table_name, [entity.table_name + '.id'], new Set(), 3);
+    });
+  } else {
+    buildPathsFrom('users', ['users.id'], new Set(), 4);
+  }
+
+  return graph;
+}

package/src/server/ws.js

@@ -0,0 +1,464 @@
+import { SignJWT, jwtVerify } from "jose";
+import {
+  callAuthFunction,
+  callUserFunction,
+  getUserProfile,
+  db,
+} from "./db.js";
+import { wsLogger, authLogger } from "./logger.js";
+
+// Environment configuration
+const JWT_SECRET_STRING = process.env.JWT_SECRET;
+const JWT_EXPIRES_IN = process.env.JWT_EXPIRES_IN || "7d";
+
+// WebSocket ping/pong configuration (important for Heroku and other platforms)
+// Heroku terminates WebSocket connections after 55 seconds of inactivity (H15 error)
+// Default 30s interval keeps connections alive well within that limit
+const WS_PING_INTERVAL = parseInt(process.env.WS_PING_INTERVAL || "30000", 10); // 30 seconds default
+const WS_PING_TIMEOUT = parseInt(process.env.WS_PING_TIMEOUT || "5000", 10);    // 5 seconds default
+const WS_MAX_MESSAGE_SIZE = parseInt(process.env.WS_MAX_MESSAGE_SIZE || "1048576", 10); // 1MB default
+
+// Validate JWT_SECRET in production
+if (process.env.NODE_ENV === "production" && !JWT_SECRET_STRING) {
+  throw new Error(
+    "JWT_SECRET environment variable is required in production. Generate one with: openssl rand -base64 32"
+  );
+}
+
+// Warn if using default secret in development
+if (!JWT_SECRET_STRING && process.env.NODE_ENV !== "test") {
+  console.warn(
+    "⚠️  WARNING: Using default JWT secret. Set JWT_SECRET environment variable for security."
+  );
+}
+
+const JWT_SECRET = new TextEncoder().encode(
+  JWT_SECRET_STRING || "dev-secret-at-least-32-chars-long!!"
+);
+
+// JWT helpers
+export async function create_jwt(payload) {
+  return await new SignJWT(payload)
+    .setProtectedHeader({ alg: "HS256" })
+    .setIssuedAt()
+    .setExpirationTime(JWT_EXPIRES_IN)
+    .sign(JWT_SECRET);
+}
+
+export async function verify_jwt_token(token) {
+  try {
+    const { payload } = await jwtVerify(token, JWT_SECRET);
+    return payload;
+  } catch (error) {
+    return null;
+  }
+}
+
+// JSON-RPC helpers
+export function create_rpc_response(id, result) {
+  return JSON.stringify({
+    jsonrpc: "2.0",
+    result,
+    id,
+  });
+}
+
+export function create_rpc_error(id, code, message, data = null) {
+  return JSON.stringify({
+    jsonrpc: "2.0",
+    error: { code, message, data },
+    id,
+  });
+}
+
+// SID (Session ID) Promise Management for bidirectional client-server communication
+// Used for async operations where server requests data from client
+const sidPromises = new Map();
+
+/**
+ * Create a promise with a unique SID that can be resolved/rejected later
+ * @param {number} timeout - Timeout in milliseconds (default: 30000)
+ * @returns {Object} - { sid, promise }
+ */
+export function createSIDPromise(timeout = 30000) {
+  const sid = crypto.randomUUID();
+
+  const promise = new Promise((resolve, reject) => {
+    // Store resolve/reject functions
+    sidPromises.set(sid, { resolve, reject });
+
+    // Set timeout
+    const timer = setTimeout(() => {
+      if (sidPromises.has(sid)) {
+        sidPromises.delete(sid);
+        reject(new Error(`SID request timeout after ${timeout}ms`));
+      }
+    }, timeout);
+
+    // Store timer so it can be cleared on resolution
+    const entry = sidPromises.get(sid);
+    if (entry) {
+      entry.timer = timer;
+    }
+  });
+
+  return { sid, promise };
+}
+
+/**
+ * Resolve a pending SID promise with a result
+ * @param {string} sid - The session ID
+ * @param {any} result - The result to resolve with
+ * @returns {boolean} - True if SID was found and resolved
+ */
+export function resolveSID(sid, result) {
+  const entry = sidPromises.get(sid);
+  if (!entry) {
+    wsLogger.warn(`Attempted to resolve unknown SID: ${sid}`);
+    return false;
+  }
+
+  clearTimeout(entry.timer);
+  sidPromises.delete(sid);
+  entry.resolve(result);
+  wsLogger.debug(`SID resolved: ${sid}`);
+  return true;
+}
+
+/**
+ * Reject a pending SID promise with an error
+ * @param {string} sid - The session ID
+ * @param {Error|string} error - The error to reject with
+ * @returns {boolean} - True if SID was found and rejected
+ */
+export function rejectSID(sid, error) {
+  const entry = sidPromises.get(sid);
+  if (!entry) {
+    wsLogger.warn(`Attempted to reject unknown SID: ${sid}`);
+    return false;
+  }
+
+  clearTimeout(entry.timer);
+  sidPromises.delete(sid);
+  entry.reject(typeof error === 'string' ? new Error(error) : error);
+  wsLogger.debug(`SID rejected: ${sid}`);
+  return true;
+}
+
+// Create RPC handler function
+export function createRPCHandler(customHandlers = {}) {
+  return async function handle_rpc(ws, message) {
+    let id = null;
+    let method = null;
+    const startTime = Date.now();
+
+    try {
+      const parsed = JSON.parse(message);
+      method = parsed.method;
+      const params = parsed.params;
+      id = parsed.id;
+
+      // Log incoming request
+      wsLogger.request(method, params);
+
+      // Handle SID responses from client (special internal method)
+      if (method === "_sid_response") {
+        const { sid, result, error } = params || {};
+        if (!sid) {
+          return create_rpc_error(id, -32602, "Missing sid parameter");
+        }
+
+        if (error) {
+          rejectSID(sid, error);
+        } else {
+          resolveSID(sid, result);
+        }
+
+        return create_rpc_response(id, { success: true });
+      }
+
+      // Validate method doesn't start with underscore (private)
+      if (method.startsWith("_")) {
+        wsLogger.warn(`Blocked private function call: ${method}`);
+        return create_rpc_error(id, -32601, "Cannot call private functions");
+      }
+
+      // Handle DZQL operations (require auth, identifiable by signature)
+      if (method.startsWith("dzql.")) {
+        if (!ws.data.user_id) {
+          return create_rpc_error(id, -32603, "Not authenticated");
+        }
+
+        const [, operation, entity] = method.split(".");
+        if (!operation || !entity) {
+          return create_rpc_error(
+            id,
+            -32602,
+            "Invalid DZQL method format. Use: dzql.operation.entity",
+          );
+        }
+
+        if (
+          !["get", "save", "delete", "lookup", "search"].includes(operation)
+        ) {
+          return create_rpc_error(
+            id,
+            -32602,
+            `Unknown DZQL operation: ${operation}`,
+          );
+        }
+
+        wsLogger.debug(`DZQL: Calling ${operation}.${entity} with params:`, JSON.stringify(params));
+        const result = await db.api[operation][entity](
+          params || {},
+          ws.data.user_id,
+        );
+        wsLogger.debug(`DZQL: ${operation}.${entity} returned successfully`);
+        return create_rpc_response(id, result);
+      }
+
+      // Local API functions that don't require auth
+      if (method === "login_user") {
+        authLogger.debug(`Login attempt for: ${params.email}`);
+        const data = await callAuthFunction(
+          "login_user",
+          params.email,
+          params.password,
+        );
+
+        // On successful auth, set user_id on WebSocket connection
+        if (data && data.user_id) {
+          ws.data.user_id = data.user_id;
+          authLogger.info(`User logged in: ${params.email} (id: ${data.user_id})`);
+
+          // Create JWT token for client storage
+          const token = await create_jwt({
+            user_id: data.user_id,
+            email: data.email,
+          });
+
+          // Get full profile
+          const profile = await getUserProfile(data.user_id);
+
+          const result = {
+            user_id: data.user_id,
+            email: data.email,
+            token,
+            profile,
+          };
+          wsLogger.response(method, result, Date.now() - startTime);
+          return create_rpc_response(id, result);
+        }
+
+        authLogger.warn(`Login failed for: ${params.email}`);
+        wsLogger.response(method, data, Date.now() - startTime);
+        return create_rpc_response(id, data);
+      }
+
+      if (method === "register_user") {
+        authLogger.debug(`Registration attempt for: ${params.email}`);
+        const data = await callAuthFunction(
+          "register_user",
+          params.email,
+          params.password,
+        );
+
+        // On successful registration, set user_id on WebSocket connection
+        if (data && data.user_id) {
+          ws.data.user_id = data.user_id;
+          authLogger.info(`User registered: ${params.email} (id: ${data.user_id})`);
+
+          // Create JWT token for client storage
+          const token = await create_jwt({
+            user_id: data.user_id,
+            email: data.email,
+          });
+
+          const result = {
+            user_id: data.user_id,
+            email: data.email,
+            token,
+            profile: data,
+          };
+          wsLogger.response(method, result, Date.now() - startTime);
+          return create_rpc_response(id, result);
+        }
+
+        authLogger.warn(`Registration failed for: ${params.email}`);
+        wsLogger.response(method, data, Date.now() - startTime);
+        return create_rpc_response(id, data);
+      }
+
+      // Everything else requires authentication
+      if (!ws.data.user_id) {
+        wsLogger.warn(`Unauthenticated request to: ${method}`);
+        return create_rpc_error(id, -32603, "Not authenticated");
+      }
+
+      // Authenticated-only local functions
+      if (method === "logout") {
+        authLogger.info(`User logged out (id: ${ws.data.user_id})`);
+        ws.data.user_id = null;
+        const result = { success: true };
+        wsLogger.response(method, result, Date.now() - startTime);
+        return create_rpc_response(id, result);
+      }
+
+      // Check for custom handlers
+      if (customHandlers[method]) {
+        wsLogger.debug(`Calling custom handler: ${method}`);
+        const result = await customHandlers[method](ws.data.user_id, params);
+        wsLogger.response(method, result, Date.now() - startTime);
+        return create_rpc_response(id, result);
+      }
+
+      // Call stored function with user_id as first parameter
+      wsLogger.debug(`Calling database function: ${method}`);
+      const result = await callUserFunction(method, ws.data.user_id, params);
+      wsLogger.response(method, result, Date.now() - startTime);
+      return create_rpc_response(id, result);
+    } catch (error) {
+      wsLogger.error(`RPC error in ${method}:`, error.message);
+      wsLogger.debug(`RPC error stack:`, error.stack);
+
+      // PostgreSQL error codes
+      if (error.code) {
+        wsLogger.debug(`Returning PostgreSQL error for id=${id}`);
+        return create_rpc_error(id, -32603, String(error), {
+          code: error.code,
+        });
+      }
+
+      // Generic error
+      wsLogger.debug(`Returning generic error for id=${id}: ${error.message}`);
+      return create_rpc_error(id, -32603, "Internal error", {
+        message: error.message,
+      });
+    }
+  };
+}
+
+// Create WebSocket event handlers
+export function createWebSocketHandlers(options = {}) {
+  const {
+    rpcHandler = null,
+    customHandlers = {},
+    onConnection = null,
+    onDisconnection = null,
+  } = options;
+
+  // Active WebSocket connections
+  const connections = new Map();
+
+  // Create RPC handler if not provided
+  const handler = rpcHandler || createRPCHandler(customHandlers);
+
+  // Create broadcaster function
+  const broadcast = createBroadcaster(connections);
+
+  return {
+    connections,
+    broadcast,
+
+    // WebSocket configuration for Bun.serve
+    // These properties are required for proper ping/pong support (especially on Heroku)
+    perMessageDeflate: true,
+    maxPayloadLength: WS_MAX_MESSAGE_SIZE,
+    idleTimeout: WS_PING_INTERVAL / 1000, // Convert to seconds for Bun
+    closeOnBackpressureLimit: true, // Close connection if backpressure limit exceeded
+
+    // Connection opened
+    async open(ws) {
+      const id = crypto.randomUUID();
+      ws.data.connection_id = id;
+      connections.set(id, ws);
+
+      wsLogger.info(
+        `Connection opened: ${id.slice(0, 8)}...`,
+        ws.data.user_id ? `(user: ${ws.data.user_id})` : "(anonymous)",
+      );
+
+      // Get full profile if authenticated
+      let profile = null;
+      if (ws.data.user_id) {
+        try {
+          profile = await getUserProfile(ws.data.user_id);
+        } catch (error) {
+          wsLogger.error("Failed to load profile:", error.message);
+        }
+      }
+
+      // Send welcome message as JSON-RPC method call
+      ws.send(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          method: "connected",
+          params: {
+            connection_id: id,
+            authenticated: !!ws.data.user_id,
+            profile,
+          },
+        }),
+      );
+
+      // Call custom connection handler
+      if (onConnection) {
+        onConnection(ws, id);
+      }
+    },
+
+    // Message received
+    async message(ws, message) {
+      const response = await handler(ws, message);
+      ws.send(response);
+    },
+
+    // Connection closed
+    close(ws) {
+      const id = ws.data.connection_id;
+      connections.delete(id);
+      wsLogger.info(`Connection closed: ${id?.slice(0, 8)}...`);
+
+      // Call custom disconnection handler
+      if (onDisconnection) {
+        onDisconnection(ws, id);
+      }
+    },
+
+    // Error occurred
+    error(ws, error) {
+      wsLogger.error(`WebSocket error for ${ws.data.connection_id?.slice(0, 8)}...:`, error.message);
+    },
+  };
+}
+
+// Broadcast message to all authenticated connections or specific client_ids
+export function createBroadcaster(connections) {
+  return function broadcastToConnections(message, client_ids = null) {
+    if (client_ids && Array.isArray(client_ids)) {
+      // Send to specific user_ids
+      for (const [id, ws] of connections) {
+        if (ws.data.user_id && client_ids.includes(ws.data.user_id)) {
+          ws.send(message);
+        }
+      }
+    } else {
+      // Send to all authenticated connections
+      for (const [id, ws] of connections) {
+        if (ws.data.user_id) {
+          ws.send(message);
+        }
+      }
+    }
+  };
+}
+
+// Legacy export for backward compatibility
+export function broadcastToConnections(connections, message) {
+  // Send to all authenticated connections
+  for (const [id, ws] of connections) {
+    if (ws.data.user_id) {
+      ws.send(message);
+    }
+  }
+}