dzql 0.1.0-alpha.1

package/src/server/index.js

@@ -0,0 +1,141 @@
+import { createWebSocketHandlers, verify_jwt_token } from "./ws.js";
+import { closeConnections, setupListeners, sql, db } from "./db.js";
+import * as defaultApi from "./api.js";
+import { serverLogger, notifyLogger } from "./logger.js";
+
+// Re-export commonly used utilities
+export { sql, db } from "./db.js";
+export { metaRoute } from "./meta-route.js";
+export { createMCPRoute } from "./mcp.js";
+
+export function createServer(options = {}) {
+  const {
+    port = process.env.PORT || 3000,
+    customApi = {},
+    routes = {},
+    staticPath = null  // No default static path - applications should specify
+  } = options;
+
+  // Merge default API with custom API
+  const api = { ...defaultApi, ...customApi };
+
+  // Create WebSocket event handlers
+  const { broadcast, ...websocketHandlers } = createWebSocketHandlers({
+    customHandlers: api,
+  });
+
+  // Setup NOTIFY listeners for real-time events
+  setupListeners((event) => {
+    // Handle single dzql event with filtering
+    const { notify_users, ...eventData } = event;
+
+    // Create JSON-RPC notification
+    const message = JSON.stringify({
+      jsonrpc: "2.0",
+      method: `${event.table}:${event.op}`, // e.g., "venues:update"
+      params: eventData,
+    });
+
+    // Filter based on notify_users (null = broadcast to all)
+    if (notify_users && notify_users.length > 0) {
+      // Send to specific users only
+      notifyLogger.debug(`Broadcasting ${event.table}:${event.op} to ${notify_users.length} users`);
+      broadcast(message, notify_users);
+    } else {
+      // Send to all connected users
+      notifyLogger.debug(`Broadcasting ${event.table}:${event.op} to all users`);
+      broadcast(message);
+    }
+  });
+
+  routes['/health'] = () => new Response("OK", { status: 200 });
+
+  // Create and start the Bun server
+  const server = Bun.serve({
+    port,
+    routes,
+    async fetch(req, server) {
+      const url = new URL(req.url);
+
+      // WebSocket upgrade path
+      if (url.pathname === "/ws") {
+        // Extract token from Authorization header or query param
+        const auth_header = req.headers.get("Authorization");
+        const token =
+          auth_header?.replace("Bearer ", "") || url.searchParams.get("token");
+
+        let user_data = null;
+
+        // Verify JWT if provided
+        if (token) {
+          const payload = await verify_jwt_token(token);
+          if (payload) {
+            user_data = {
+              user_id: payload.user_id,
+              email: payload.email,
+            };
+          }
+        }
+
+        // Upgrade to WebSocket (allow anonymous for login/register)
+        const success = server.upgrade(req, {
+          data: user_data || {},
+        });
+
+        if (success) return undefined;
+        return new Response("WebSocket upgrade failed", { status: 400 });
+      }
+
+      // Static file serving (only if staticPath is configured)
+      if (staticPath) {
+        let filePath = url.pathname;
+
+        // Default to index.html for root or directory requests
+        if (!filePath || filePath === "/") {
+          filePath = "/index.html";
+        }
+
+        const file = Bun.file(`${staticPath}${filePath}`);
+        if (await file.exists()) {
+          return new Response(file);
+        }
+      }
+
+      return new Response("Not Found", { status: 404 });
+    },
+
+    websocket: websocketHandlers,
+  });
+
+  serverLogger.info(`🚀 DZQL server started`);
+  serverLogger.info(`   HTTP: http://localhost:${port}`);
+  serverLogger.info(`   WebSocket: ws://localhost:${port}/ws`);
+  serverLogger.info(`   Environment: ${process.env.NODE_ENV || "development"}`);
+  serverLogger.info(`   WS Ping Interval: ${process.env.WS_PING_INTERVAL || 30000}ms (Heroku safe: <55s)`);
+
+  // Add graceful shutdown handling
+  const shutdown = async () => {
+    serverLogger.info("Shutting down DZQL server...");
+    await closeConnections();
+    serverLogger.info("Server shutdown complete");
+  };
+
+  // Return server instance with utilities
+  return {
+    port,
+    server,
+    shutdown,
+    broadcast
+  };
+}
+
+// If this file is run directly (not imported), start the server
+if (import.meta.main) {
+  const server = createServer();
+
+  // Graceful shutdown
+  process.on("SIGINT", async () => {
+    await server.shutdown();
+    process.exit(0);
+  });
+}

package/src/server/logger.js

@@ -0,0 +1,246 @@
+// logger.js - Flexible logging system with categories and levels
+
+// Log levels
+const LOG_LEVELS = {
+  ERROR: 0,
+  WARN: 1,
+  INFO: 2,
+  DEBUG: 3,
+  TRACE: 4,
+};
+
+// Default log level from environment or INFO
+const DEFAULT_LEVEL = process.env.LOG_LEVEL?.toUpperCase() || "INFO";
+
+// Parse LOG_CATEGORIES from environment
+// Format: "ws:debug,db:trace,auth:info" or "*:debug" for all
+const parseCategories = () => {
+  const categories = {};
+  const envCategories = process.env.LOG_CATEGORIES || "";
+
+  if (!envCategories) {
+    // Default settings for development vs production
+    if (process.env.NODE_ENV === "production") {
+      categories["*"] = LOG_LEVELS.WARN;
+    } else if (process.env.NODE_ENV === "test") {
+      categories["*"] = LOG_LEVELS.ERROR;
+    } else {
+      // Development defaults
+      categories["*"] = LOG_LEVELS[DEFAULT_LEVEL] ?? LOG_LEVELS.INFO;
+    }
+    return categories;
+  }
+
+  // Parse category:level pairs
+  envCategories.split(",").forEach((pair) => {
+    const [category, level] = pair.trim().split(":");
+    if (category && level) {
+      const levelValue = LOG_LEVELS[level.toUpperCase()];
+      if (levelValue !== undefined) {
+        categories[category] = levelValue;
+      }
+    }
+  });
+
+  // Set default for non-specified categories
+  if (!categories["*"]) {
+    categories["*"] = LOG_LEVELS[DEFAULT_LEVEL] ?? LOG_LEVELS.INFO;
+  }
+
+  return categories;
+};
+
+// Initialize categories
+let logCategories = parseCategories();
+
+// Colors for terminal output
+const colors = {
+  reset: "\x1b[0m",
+  bright: "\x1b[1m",
+  dim: "\x1b[2m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+  white: "\x1b[37m",
+  gray: "\x1b[90m",
+};
+
+// Level colors
+const levelColors = {
+  ERROR: colors.red,
+  WARN: colors.yellow,
+  INFO: colors.blue,
+  DEBUG: colors.cyan,
+  TRACE: colors.gray,
+};
+
+// Category colors
+const categoryColors = {
+  ws: colors.green,
+  db: colors.magenta,
+  auth: colors.yellow,
+  api: colors.cyan,
+  server: colors.blue,
+  notify: colors.magenta,
+};
+
+// Format timestamp
+const timestamp = () => {
+  const now = new Date();
+  return now.toISOString().replace("T", " ").slice(0, -5);
+};
+
+// Check if logging is enabled for category and level
+const shouldLog = (category, level) => {
+  const categoryLevel = logCategories[category] ?? logCategories["*"] ?? LOG_LEVELS.INFO;
+  return LOG_LEVELS[level] <= categoryLevel;
+};
+
+// Format log message with colors
+const formatMessage = (category, level, message, ...args) => {
+  const useColors = process.env.NO_COLOR !== "1" && process.env.NODE_ENV !== "test";
+
+  if (useColors) {
+    const catColor = categoryColors[category] || colors.white;
+    const lvlColor = levelColors[level];
+
+    return [
+      `${colors.gray}${timestamp()}${colors.reset}`,
+      `${lvlColor}[${level}]${colors.reset}`,
+      `${catColor}[${category}]${colors.reset}`,
+      message,
+      ...args,
+    ];
+  } else {
+    return [
+      timestamp(),
+      `[${level}]`,
+      `[${category}]`,
+      message,
+      ...args,
+    ];
+  }
+};
+
+// Create logger for a specific category
+export const createLogger = (category) => {
+  return {
+    error: (message, ...args) => {
+      if (shouldLog(category, "ERROR")) {
+        console.error(...formatMessage(category, "ERROR", message, ...args));
+      }
+    },
+    warn: (message, ...args) => {
+      if (shouldLog(category, "WARN")) {
+        console.warn(...formatMessage(category, "WARN", message, ...args));
+      }
+    },
+    info: (message, ...args) => {
+      if (shouldLog(category, "INFO")) {
+        console.log(...formatMessage(category, "INFO", message, ...args));
+      }
+    },
+    debug: (message, ...args) => {
+      if (shouldLog(category, "DEBUG")) {
+        console.log(...formatMessage(category, "DEBUG", message, ...args));
+      }
+    },
+    trace: (message, ...args) => {
+      if (shouldLog(category, "TRACE")) {
+        console.log(...formatMessage(category, "TRACE", message, ...args));
+      }
+    },
+    // Special method for request/response logging
+    request: (method, params) => {
+      if (shouldLog(category, "DEBUG")) {
+        console.log(...formatMessage(
+          category,
+          "DEBUG",
+          `→ ${method}`,
+          params ? JSON.stringify(params) : "no params"
+        ));
+      }
+    },
+    response: (method, result, duration) => {
+      if (shouldLog(category, "DEBUG")) {
+        const resultStr = result === undefined
+          ? "void"
+          : typeof result === "object"
+            ? `${JSON.stringify(result).slice(0, 100)}...`
+            : result;
+        console.log(...formatMessage(
+          category,
+          "DEBUG",
+          `← ${method} (${duration}ms)`,
+          resultStr
+        ));
+      }
+    },
+  };
+};
+
+// Pre-configured loggers for common categories
+export const wsLogger = createLogger("ws");
+export const dbLogger = createLogger("db");
+export const authLogger = createLogger("auth");
+export const serverLogger = createLogger("server");
+export const notifyLogger = createLogger("notify");
+
+// Reload configuration (useful for runtime changes)
+export const reloadConfig = () => {
+  logCategories = parseCategories();
+};
+
+// Get current configuration
+export const getConfig = () => {
+  return {
+    categories: logCategories,
+    levels: LOG_LEVELS,
+  };
+};
+
+// Middleware for timing operations
+export const timed = async (category, operation, fn) => {
+  const logger = createLogger(category);
+  const start = Date.now();
+
+  try {
+    logger.trace(`Starting ${operation}`);
+    const result = await fn();
+    const duration = Date.now() - start;
+    logger.debug(`Completed ${operation} in ${duration}ms`);
+    return result;
+  } catch (error) {
+    const duration = Date.now() - start;
+    logger.error(`Failed ${operation} after ${duration}ms:`, error.message);
+    throw error;
+  }
+};
+
+// Log configuration on startup (only in development)
+if (process.env.NODE_ENV !== "production" && process.env.NODE_ENV !== "test") {
+  const config = getConfig();
+  console.log(colors.bright + "=== Logger Configuration ===" + colors.reset);
+  console.log("Categories:", config.categories);
+  console.log("Available levels:", Object.keys(config.levels).join(", "));
+  console.log("");
+  console.log("Set LOG_CATEGORIES env var to configure:");
+  console.log('  Example: LOG_CATEGORIES="ws:debug,db:trace,auth:info"');
+  console.log('  Or use "*:debug" to set all categories to debug');
+  console.log(colors.bright + "===========================" + colors.reset + "\n");
+}
+
+export default {
+  createLogger,
+  wsLogger,
+  dbLogger,
+  authLogger,
+  serverLogger,
+  notifyLogger,
+  reloadConfig,
+  getConfig,
+  timed,
+};