dzql 0.5.33 → 0.6.1

package/src/runtime/ws.ts

@@ -0,0 +1,197 @@
+import { ServerWebSocket } from "bun";
+import { handleRequest } from "./server.js"; // The secure router
+import { verifyToken, signToken } from "./auth.js";
+import { Database } from "./db.js";
+
+interface WSContext {
+  id: string;
+  userId?: number;
+  subscriptions: Set<string>; // Set of subscription IDs
+  lastPing: number;
+  token?: string; // Token passed from URL query params during upgrade
+}
+
+export class WebSocketServer {
+  private connections = new Map<string, ServerWebSocket<WSContext>>();
+  private db: Database;
+
+  constructor(db: Database) {
+    this.db = db;
+    // Start heartbeat interval
+    setInterval(() => this.heartbeat(), 30000);
+  }
+
+  // Bun.serve websocket handler hooks
+  get handlers() {
+    return {
+      open: (ws: ServerWebSocket<WSContext>) => this.handleOpen(ws),
+      message: (ws: ServerWebSocket<WSContext>, message: string) => this.handleMessage(ws, message),
+      close: (ws: ServerWebSocket<WSContext>) => this.handleClose(ws),
+      drain: (ws: ServerWebSocket<WSContext>) => {}
+    };
+  }
+
+  private async handleOpen(ws: ServerWebSocket<WSContext>) {
+    const id = Math.random().toString(36).slice(2);
+    const token = ws.data?.token;
+
+    ws.data = {
+      id,
+      subscriptions: new Set(),
+      lastPing: Date.now()
+    };
+    this.connections.set(id, ws);
+    console.log(`[WS] Client ${id} connected`);
+
+    // Subscribe to global broadcast channel initially
+    ws.subscribe("broadcast");
+
+    // If token was provided in URL, verify and authenticate
+    let user: any = null;
+    if (token) {
+      try {
+        const session = await verifyToken(token);
+        ws.data.userId = session.userId;
+        console.log(`[WS] Client ${id} authenticated via token as user ${session.userId}`);
+
+        // Fetch user profile using get_users
+        try {
+          const profile = await handleRequest(this.db, 'get_users', { id: session.userId }, session.userId);
+          if (profile) {
+            // Remove sensitive data
+            const { password_hash, ...safeProfile } = profile;
+            user = safeProfile;
+          }
+        } catch (e) {
+          console.error(`[WS] Failed to fetch profile for user ${session.userId}:`, e);
+          // Still authenticated, just no profile
+          user = { id: session.userId };
+        }
+      } catch (e: any) {
+        console.log(`[WS] Client ${id} token verification failed:`, e.message);
+        // Token invalid, user remains null (anonymous connection)
+      }
+    }
+
+    // Send connection:ready message
+    ws.send(JSON.stringify({
+      jsonrpc: "2.0",
+      method: "connection:ready",
+      params: { user }
+    }));
+  }
+
+  private async handleMessage(ws: ServerWebSocket<WSContext>, message: string) {
+    ws.data.lastPing = Date.now(); // Update activity
+
+    try {
+      const req = JSON.parse(message);
+
+      // Handle Ping (Client-side heartbeat)
+      if (req.method === 'ping') {
+          ws.send(JSON.stringify({ id: req.id, result: 'pong' }));
+          return;
+      }
+
+      // Handle Auth Handshake
+      if (req.method === 'auth') {
+          try {
+              const session = await verifyToken(req.params.token);
+              ws.data.userId = session.userId;
+              ws.send(JSON.stringify({ id: req.id, result: { success: true, userId: session.userId } }));
+              console.log(`[WS] Client ${ws.data.id} authenticated as user ${session.userId}`);
+          } catch (e: any) {
+              ws.send(JSON.stringify({ id: req.id, error: { code: 'UNAUTHORIZED', message: e.message } }));
+          }
+          return;
+      }
+
+      // Require Auth for other methods?
+      // V2 spec says `p_user_id` is passed to functions.
+      // If not auth'd, we can pass null or throw.
+      const userId = ws.data.userId || null;
+
+      // Handle RPC
+      if (req.method) {
+          if (req.method.startsWith("subscribe_")) {
+             // Handle Subscription Registration
+             const subscribableName = req.method.replace("subscribe_", "");
+             const getFnName = `get_${subscribableName}`;
+
+             try {
+               // Call the get_ function to fetch initial data
+               const snapshot = await handleRequest(this.db, getFnName, req.params, userId);
+
+               // Register subscription
+               const subId = `${subscribableName}:${JSON.stringify(req.params)}`;
+               ws.data.subscriptions.add(subId);
+
+               // Return snapshot with subscription_id and schema
+               ws.send(JSON.stringify({
+                 id: req.id,
+                 result: {
+                   subscription_id: subId,
+                   data: snapshot.data,
+                   schema: snapshot.schema
+                 }
+               }));
+             } catch (e: any) {
+               ws.send(JSON.stringify({
+                 id: req.id,
+                 error: { code: e.code || 'INTERNAL_ERROR', message: e.message }
+               }));
+             }
+          } else {
+             // Normal Function Call
+             const result = await handleRequest(this.db, req.method, req.params, userId);
+
+             // Auto-generate token for auth methods
+             if (req.method === 'login_user' || req.method === 'register_user') {
+                 const token = await signToken({ user_id: result.user_id, role: 'user' });
+                 // Return profile + token
+                 ws.send(JSON.stringify({ id: req.id, result: { ...result, token } }));
+             } else {
+                 ws.send(JSON.stringify({ id: req.id, result }));
+             }
+          }
+      }
+
+    } catch (e: any) {
+      console.error(`[WS] Error processing message from ${ws.data.id}:`, e);
+      // Try to send error back if JSON parse didn't fail
+      try {
+          const reqId = JSON.parse(message).id;
+          ws.send(JSON.stringify({ id: reqId, error: { code: 'INTERNAL_ERROR', message: e.message } }));
+      } catch (ignore) {}
+    }
+  }
+
+  private handleClose(ws: ServerWebSocket<WSContext>) {
+    this.connections.delete(ws.data.id);
+    console.log(`[WS] Client ${ws.data.id} disconnected`);
+  }
+
+  private heartbeat() {
+    const now = Date.now();
+    for (const [id, ws] of this.connections) {
+        if (now - ws.data.lastPing > 60000) {
+            console.log(`[WS] Client ${id} timed out`);
+            ws.close();
+            this.connections.delete(id);
+        }
+    }
+  }
+
+  public broadcast(message: string) {
+      // Use Bun's native publish for efficiency
+      // 'broadcast' topic is subscribed by all on connect
+      // In V2, we might have specific topics per subscription key
+      // server.publish("broadcast", message);
+      // Since this class doesn't hold the 'server' instance directly,
+      // we iterate or need to pass server in.
+      // For now, iteration is fine for prototype.
+      for (const ws of this.connections.values()) {
+          ws.send(message);
+      }
+  }
+}

package/src/shared/ir.ts

@@ -0,0 +1,197 @@
+// ============================================
+// INPUT TYPES - Used for domain configuration
+// ============================================
+
+/** Action types supported in graph rules */
+export type GraphRuleActionType = 'create' | 'update' | 'delete' | 'validate' | 'execute' | 'reactor';
+
+/** Configuration for a graph rule action */
+export interface GraphRuleActionConfig {
+  type: GraphRuleActionType;
+  entity?: string;           // Target entity for create action
+  target?: string;           // Target entity for update/delete actions
+  name?: string;             // Reactor name for reactor type
+  function?: string;         // Function name for validate/execute
+  data?: Record<string, string>;   // Data for create/update (field -> @variable)
+  match?: Record<string, string>;  // Match condition for update/delete
+  params?: Record<string, string>; // Parameters for reactor/validate/execute
+  error_message?: string;    // Error message for validate
+}
+
+/** Configuration for a named graph rule */
+export interface GraphRuleConfig {
+  description?: string;
+  condition?: string;        // e.g., "@before.status = 'draft' AND @after.status = 'posted'"
+  actions: GraphRuleActionConfig[];
+}
+
+/** Include configuration - either a simple string (entity name) or full object */
+export interface IncludeConfig {
+  entity: string;
+  filter?: Record<string, string>;
+  includes?: Record<string, string | IncludeConfig>;
+}
+
+/** Many-to-many relationship configuration */
+export interface ManyToManyConfig {
+  junctionTable: string;
+  localKey: string;
+  foreignKey: string;
+  targetEntity: string;
+  idField: string;
+  expand?: boolean;
+}
+
+/** Permission paths configuration */
+export interface PermissionPathsConfig {
+  view?: string[];
+  create?: string[];
+  update?: string[];
+  delete?: string[];
+}
+
+/** Temporal fields configuration */
+export interface TemporalConfig {
+  validFrom: string;
+  validTo: string;
+}
+
+/** Graph rules grouped by trigger */
+export interface GraphRulesConfig {
+  on_create?: Record<string, GraphRuleConfig>;
+  on_update?: Record<string, GraphRuleConfig>;
+  on_delete?: Record<string, GraphRuleConfig>;
+  primary_key?: string[];    // Composite primary key fields
+  many_to_many?: Record<string, ManyToManyConfig>;
+}
+
+/** Entity configuration as provided in domain file */
+export interface EntityConfig {
+  schema: Record<string, string>;
+  label?: string;
+  searchable?: string[];
+  hidden?: string[];
+  primaryKey?: string[];
+  managed?: boolean;
+  softDelete?: boolean;
+  fieldDefaults?: Record<string, string>;
+  permissions?: PermissionPathsConfig;
+  includes?: Record<string, string | IncludeConfig>;
+  manyToMany?: Record<string, ManyToManyConfig>;
+  graphRules?: GraphRulesConfig;
+  temporal?: TemporalConfig;
+  constraints?: string[];
+  indexes?: string[];
+  notifications?: Record<string, string[]>;
+}
+
+/** Subscribable configuration as provided in domain file */
+export interface SubscribableConfig {
+  params: Record<string, string>;
+  root: { entity: string; key: string };
+  includes?: Record<string, string | IncludeConfig>;
+  scopeTables?: string[];
+  canSubscribe?: string[];
+}
+
+/** Custom function configuration */
+export interface CustomFunctionConfig {
+  name: string;
+  sql: string;
+  args?: string[];
+}
+
+/** Complete domain configuration as provided in domain file */
+export interface DomainConfig {
+  entities: Record<string, EntityConfig>;
+  subscribables?: Record<string, SubscribableConfig>;
+  customFunctions?: CustomFunctionConfig[];
+}
+
+// ============================================
+// IR TYPES - Intermediate representation
+// ============================================
+
+export interface EntityIR {
+  name: string;
+  table: string;
+  primaryKey: string[];
+  columns: Array<{ name: string; type: string; isArray: boolean }>;
+  labelField?: string;
+  softDelete?: boolean;
+  managed?: boolean; // If false, skip CRUD function generation (for junction tables)
+  hidden?: string[]; // Fields to exclude from query results (e.g., password_hash)
+  fieldDefaults?: Record<string, string>;
+  permissions: {
+    view: string[];
+    create: string[];
+    update: string[];
+    delete: string[];
+  };
+  relationships: Record<string, RelationshipIR>;
+  manyToMany: Record<string, ManyToManyIR>;
+  graphRules: {
+    onCreate: GraphRuleIR[];
+    onUpdate: GraphRuleIR[];
+    onDelete: GraphRuleIR[];
+  };
+}
+
+export interface ManyToManyIR {
+  junctionTable: string;
+  localKey: string;
+  foreignKey: string;
+  targetEntity: string;
+  idField: string;
+  expand: boolean;
+}
+
+export interface RelationshipIR {
+  type: 'one_to_many' | 'many_to_one' | 'many_to_many';
+  targetEntity: string;
+  localKey: string;
+  foreignKey: string;
+}
+
+export interface GraphRuleIR {
+  trigger: 'create' | 'update' | 'delete';
+  action: 'create' | 'update' | 'delete' | 'reactor' | 'validate' | 'execute';
+  target: string; // entity name, reactor name, or function name
+  ruleName?: string; // The name of the rule (for comments)
+  description?: string; // Human-readable description
+  condition?: string; // e.g., "@before.status = 'draft' AND @after.status = 'posted'"
+  params: Record<string, string>; // Data for create, or params for reactor/validate/execute
+  match?: Record<string, string>; // WHERE clause for update/delete actions
+  error_message?: string; // Error message for validate action
+}
+
+export interface SubscribableIR {
+  name: string;
+  params: Record<string, string>;
+  root: {
+    entity: string;
+    key: string;
+  };
+  includes: Record<string, IncludeIR>;
+  scopeTables: string[];
+  canSubscribe: string[]; // Permission paths
+}
+
+export interface IncludeIR {
+  relation: string; // The key (e.g., 'sites')
+  entity: string; // The target table (e.g., 'sites')
+  filter?: Record<string, string>;
+  includes?: Record<string, IncludeIR>; // Nested includes
+}
+
+export interface CustomFunctionIR {
+  name: string;
+  sql: string;
+  args?: string[];  // For manifest allowlist
+}
+
+export interface DomainIR {
+  entities: Record<string, EntityIR>;
+  subscribables: Record<string, SubscribableIR>;
+  customFunctions: CustomFunctionIR[];
+}

package/tests/client.test.ts

@@ -0,0 +1,38 @@
+import { describe, test, expect } from "bun:test";
+import { generateClientSDK } from "../src/cli/codegen/client.js";
+import { generateManifest } from "../src/cli/codegen/manifest.js";
+import { generateIR } from "../src/cli/compiler/ir.js";
+
+const mockManifest = generateManifest(generateIR({
+    entities: {
+        posts: {
+            schema: { id: "serial primary key", title: "text" },
+            permissions: { create: [], view: [] }
+        }
+    },
+    subscribables: {}
+}));
+
+describe("Client SDK Generation", () => {
+  test("should generate a TypeScript SDK with typed API", () => {
+    const tsCode = generateClientSDK(mockManifest);
+
+    // Check imports
+    expect(tsCode).toContain("import { WebSocketManager } from 'tzql/client'");
+
+    // Check interface definition
+    expect(tsCode).toContain("export interface TzqlAPI {");
+    expect(tsCode).toContain("save_posts: (params: SavePostsParams) => Promise<Posts>");
+    expect(tsCode).toContain("get_posts: (params: PostsPK) => Promise<Posts | null>");
+
+    // Check class definition
+    expect(tsCode).toContain("export class GeneratedWebSocketManager extends WebSocketManager");
+    expect(tsCode).toContain("api: TzqlAPI");
+
+    // Check API implementation
+    expect(tsCode).toContain("this.call('save_posts', params)");
+
+    // Check singleton export
+    expect(tsCode).toContain("export const ws = new GeneratedWebSocketManager()");
+  });
+});

package/tests/codegen.test.ts

@@ -0,0 +1,71 @@
+import { describe, test, expect } from "bun:test";
+import { generateCoreSQL, generateEntitySQL } from "../src/cli/codegen/sql.js"; 
+import { generateManifest } from "../src/cli/codegen/manifest.js";
+import { generateIR } from "../src/cli/compiler/ir.js";
+
+const mockEntityIR = {
+  name: "posts",
+  table: "posts",
+  primaryKey: ["id"],
+  columns: [
+    { name: "id", type: "serial PRIMARY KEY" },
+    { name: "title", type: "text NOT NULL" }
+  ],
+  permissions: {
+    create: [],
+    view: []
+  },
+  graphRules: {
+    onCreate: []
+  }
+};
+
+describe("SQL Code Generation", () => {
+  test("generateCoreSQL should produce migration table", () => {
+    const sql = generateCoreSQL();
+    expect(sql).toContain("CREATE SCHEMA IF NOT EXISTS dzql_v2");
+    expect(sql).toContain("CREATE TABLE IF NOT EXISTS dzql_v2.migrations");
+  });
+
+  test("generateEntitySQL should produce save function", () => {
+    const sql = generateEntitySQL("posts", mockEntityIR);
+    expect(sql).toContain("CREATE OR REPLACE FUNCTION dzql_v2.save_posts");
+    expect(sql).toContain("AND EXISTS(SELECT 1 FROM posts WHERE"); // Check existence check (composite PK support)
+    expect(sql).toContain("UPDATE posts SET"); // Check update branch
+    expect(sql).toContain("INSERT INTO posts"); // Check insert branch
+  });
+});
+
+const mockRawEntity = {
+  schema: {
+    id: "serial PRIMARY KEY",
+    title: "text NOT NULL"
+  },
+  permissions: {
+    create: [],
+    view: []
+  }
+};
+
+describe("Manifest Generation", () => {
+  test("should generate allowlist", () => {
+    // Create IR first
+    const ir = generateIR({
+        entities: { posts: mockRawEntity },
+        subscribables: {}
+    });
+
+    const manifest = generateManifest(ir);
+    
+    expect(manifest.version).toBe("2.0.0");
+    expect(manifest.functions).toBeDefined();
+    
+    // Check allowlist
+    expect(manifest.functions["save_posts"]).toBeDefined();
+    expect(manifest.functions["get_posts"]).toBeDefined();
+    expect(manifest.functions["delete_posts"]).toBeDefined();
+    
+    // Check signatures (basic check for now)
+    expect(manifest.functions["save_posts"].args).toEqual(["p_user_id", "p_data"]);
+  });
+});

package/tests/compiler.test.ts

@@ -0,0 +1,45 @@
+import { describe, test, expect } from "bun:test";
+import { analyzeDomain } from "../src/cli/compiler/analyzer.js";
+
+// Mock domain for testing
+const validDomain = {
+  entities: {
+    users: { schema: { id: "serial primary key" } },
+    posts: { schema: { id: "serial primary key", user_id: "int" } }
+  },
+  subscribables: {
+    user_posts: {
+      root: { entity: "users" },
+      includes: {
+        posts: { entity: "posts" }
+      }
+    }
+  }
+};
+
+const invalidDomain = {
+  entities: {
+    users: { schema: { id: "serial primary key" } }
+  },
+  subscribables: {
+    broken_feed: {
+      root: { entity: "users" },
+      includes: {
+        posts: { entity: "missing_posts" } // <--- Reference to missing entity
+      }
+    }
+  }
+};
+
+describe("Compiler Analyzer", () => {
+  test("should pass for valid domain", () => {
+    const errors = analyzeDomain(validDomain);
+    expect(errors).toHaveLength(0);
+  });
+
+  test("should fail for missing entity reference", () => {
+    const errors = analyzeDomain(invalidDomain);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toContain("references unknown entity 'missing_posts'");
+  });
+});