@everystack/events 0.1.0

package/src/handler/index.ts

@@ -0,0 +1,160 @@
+import type { WebSocketHandlerOptions } from '../types';
+
+interface WebSocketEvent {
+  requestContext: {
+    connectionId: string;
+    routeKey: string;
+  };
+  queryStringParameters?: Record<string, string> | null;
+  body?: string | null;
+}
+
+interface WebSocketResult {
+  statusCode: number;
+  body?: string;
+}
+
+// --- SQL helpers ---
+// These create tagged template objects compatible with Drizzle's db.execute(sql`...`)
+// We use raw string queries passed to execute() for simplicity
+
+interface DbLike {
+  execute(query: unknown): Promise<unknown>;
+}
+
+function rawSql(strings: TemplateStringsArray, ...values: unknown[]) {
+  // Build a { sql, params } object that Drizzle's execute can handle
+  // However, Drizzle's sql tagged template is the proper way.
+  // For handler use, we'll pass pre-built query objects.
+  let text = '';
+  const params: unknown[] = [];
+  for (let i = 0; i < strings.length; i++) {
+    text += strings[i];
+    if (i < values.length) {
+      params.push(values[i]);
+      text += `$${params.length}`;
+    }
+  }
+  return { sql: text, params };
+}
+
+// --- $connect ---
+
+export function createConnectHandler(options: {
+  db: DbLike;
+  verifyToken: (token: string) => Promise<Record<string, unknown> | null>;
+}) {
+  const { db, verifyToken } = options;
+
+  return async function handler(event: WebSocketEvent): Promise<WebSocketResult> {
+    const connectionId = event.requestContext.connectionId;
+    const token = event.queryStringParameters?.token;
+
+    if (!token) {
+      return { statusCode: 401 };
+    }
+
+    const payload = await verifyToken(token);
+    if (!payload) {
+      return { statusCode: 401 };
+    }
+
+    const channels = event.queryStringParameters?.subscribe?.split(',') ?? [];
+
+    // Persist for cold path recovery
+    await db.execute(
+      rawSql`INSERT INTO ws_connections (connection_id, channels) VALUES (${connectionId}, ${channels}) ON CONFLICT (connection_id) DO UPDATE SET channels = EXCLUDED.channels, last_ping_at = now()`
+    );
+
+    // Notify running listener (hot path)
+    await db.execute(
+      rawSql`SELECT pg_notify('_subs', ${JSON.stringify({
+        action: 'connect',
+        connectionId,
+        channels,
+      })})`
+    );
+
+    return { statusCode: 200 };
+  };
+}
+
+// --- $disconnect ---
+
+export function createDisconnectHandler(options: { db: DbLike }) {
+  const { db } = options;
+
+  return async function handler(event: WebSocketEvent): Promise<WebSocketResult> {
+    const connectionId = event.requestContext.connectionId;
+
+    await db.execute(
+      rawSql`DELETE FROM ws_connections WHERE connection_id = ${connectionId}`
+    );
+
+    await db.execute(
+      rawSql`SELECT pg_notify('_subs', ${JSON.stringify({
+        action: 'disconnect',
+        connectionId,
+      })})`
+    );
+
+    return { statusCode: 200 };
+  };
+}
+
+// --- $default ---
+
+export function createDefaultHandler(options: { db: DbLike }) {
+  const { db } = options;
+
+  return async function handler(event: WebSocketEvent): Promise<WebSocketResult> {
+    const connectionId = event.requestContext.connectionId;
+    const body = event.body ? JSON.parse(event.body) : {};
+
+    switch (body.action) {
+      case 'subscribe': {
+        const channels: string[] = body.channels ?? [];
+        await db.execute(
+          rawSql`UPDATE ws_connections SET channels = channels || ${channels}::text[], last_ping_at = now() WHERE connection_id = ${connectionId}`
+        );
+        await db.execute(
+          rawSql`SELECT pg_notify('_subs', ${JSON.stringify({
+            action: 'subscribe',
+            connectionId,
+            channels,
+          })})`
+        );
+        break;
+      }
+
+      case 'unsubscribe': {
+        const channels: string[] = body.channels ?? [];
+        // Remove all channels in a single UPDATE using array subtraction
+        await db.execute(
+          rawSql`UPDATE ws_connections SET channels = (SELECT array_agg(elem) FROM unnest(channels) AS elem WHERE elem != ALL(${channels}::text[])) WHERE connection_id = ${connectionId}`
+        );
+        await db.execute(
+          rawSql`SELECT pg_notify('_subs', ${JSON.stringify({
+            action: 'unsubscribe',
+            connectionId,
+            channels,
+          })})`
+        );
+        break;
+      }
+
+      case 'ping': {
+        await db.execute(
+          rawSql`UPDATE ws_connections SET last_ping_at = now() WHERE connection_id = ${connectionId}`
+        );
+        break;
+      }
+
+      default:
+        // Unknown action — no-op
+        break;
+    }
+
+    return { statusCode: 200 };
+  };
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+export { createListener, createListenerInternal } from './listener';
+export { generateTriggerSQL, generateEventActionsTriggerSQL } from './triggers';
+export { matchEventActions, needsRowFetch, filterByTenant, applyFilter, resolveTemplate, createActionCache } from './actions';
+export { dispatchActions, dispatchRpc, dispatchJob, dispatchCachePurge } from './dispatchers';
+export { createConnectHandler, createDisconnectHandler, createDefaultHandler } from './handler/index';
+export { createEventsClient, EventsProvider, useEventsClient, useSignal, useSubscription } from './client/index';
+export type {
+  EventPayload,
+  EventSignal,
+  EventsClient,
+  EventsClientOptions,
+  ListenerOptions,
+  ListenerRoutes,
+  WebSocketRoute,
+  LambdaRoute,
+  SubAction,
+  WebSocketHandlerOptions,
+  JobHandler,
+  JobHandlerOptions,
+  EventAction,
+  EventActionType,
+  EventOperation,
+  EventActionsOptions,
+  RpcActionConfig,
+  JobActionConfig,
+  CachePurgeActionConfig,
+  WebhookActionConfig,
+} from './types';

package/src/listener.ts

@@ -0,0 +1,473 @@
+import type { EventPayload, EventAction, EventActionsOptions, ListenerOptions, ListenerRoutes, SubAction } from './types';
+import { matchEventActions, createActionCache } from './actions';
+import { dispatchActions } from './dispatchers';
+import type { KvsClient } from './dispatchers';
+
+// --- Subscription state (in-memory) ---
+
+interface SubscriptionState {
+  // channel → Set<connectionId>
+  channels: Map<string, Set<string>>;
+  // connectionId → Set<channel> (reverse map for cleanup)
+  connections: Map<string, Set<string>>;
+}
+
+function createSubscriptionState(): SubscriptionState {
+  return {
+    channels: new Map(),
+    connections: new Map(),
+  };
+}
+
+function addSubscription(state: SubscriptionState, channel: string, connectionId: string): void {
+  let conns = state.channels.get(channel);
+  if (!conns) {
+    conns = new Set();
+    state.channels.set(channel, conns);
+  }
+  conns.add(connectionId);
+
+  let chans = state.connections.get(connectionId);
+  if (!chans) {
+    chans = new Set();
+    state.connections.set(connectionId, chans);
+  }
+  chans.add(channel);
+}
+
+function removeConnection(state: SubscriptionState, connectionId: string): void {
+  const chans = state.connections.get(connectionId);
+  if (chans) {
+    for (const channel of chans) {
+      const conns = state.channels.get(channel);
+      if (conns) {
+        conns.delete(connectionId);
+        if (conns.size === 0) state.channels.delete(channel);
+      }
+    }
+    state.connections.delete(connectionId);
+  }
+}
+
+function removeSubscription(state: SubscriptionState, channel: string, connectionId: string): void {
+  const conns = state.channels.get(channel);
+  if (conns) {
+    conns.delete(connectionId);
+    if (conns.size === 0) state.channels.delete(channel);
+  }
+
+  const chans = state.connections.get(connectionId);
+  if (chans) {
+    chans.delete(channel);
+    if (chans.size === 0) state.connections.delete(connectionId);
+  }
+}
+
+// --- Event processing ---
+
+async function fanOut(
+  state: SubscriptionState,
+  event: EventPayload,
+  apigw: { postToConnection(params: { ConnectionId: string; Data: Buffer }): Promise<unknown> },
+): Promise<void> {
+  const channel = `table:${event.table}`;
+  const connectionIds = state.channels.get(channel);
+  if (!connectionIds?.size) return;
+
+  const signal = JSON.stringify({
+    channel,
+    table: event.table,
+    op: event.op,
+    id: event.id,
+    ts: Date.now(),
+  });
+
+  const ids = [...connectionIds];
+  const results = await Promise.allSettled(
+    ids.map((id) =>
+      apigw.postToConnection({
+        ConnectionId: id,
+        Data: Buffer.from(signal),
+      })
+    )
+  );
+
+  for (let i = 0; i < results.length; i++) {
+    const r = results[i];
+    if (r.status === 'rejected' && r.reason?.$metadata?.httpStatusCode === 410) {
+      removeConnection(state, ids[i]);
+    }
+  }
+}
+
+async function invokeLambda(
+  lambdaClient: { invoke(params: unknown): Promise<unknown> },
+  functionName: string,
+  event: EventPayload,
+): Promise<void> {
+  await lambdaClient.invoke({
+    FunctionName: functionName,
+    InvocationType: 'Event',
+    Payload: JSON.stringify(event),
+  });
+}
+
+async function routeEvent(
+  state: SubscriptionState,
+  event: EventPayload,
+  routes: ListenerRoutes,
+  apigw: { postToConnection(params: { ConnectionId: string; Data: Buffer }): Promise<unknown> },
+  lambdaClient: { invoke(params: unknown): Promise<unknown> },
+): Promise<void> {
+  const tasks: Promise<void>[] = [];
+
+  // WebSocket fan-out
+  if (routes.websocket) {
+    tasks.push(fanOut(state, event, apigw));
+  }
+
+  // Lambda invocation
+  if (routes.lambda?.[event.table]) {
+    const route = routes.lambda[event.table];
+    const fnName = route.functionName || route.functionArn;
+    if (fnName) {
+      tasks.push(invokeLambda(lambdaClient, fnName, event));
+    }
+  }
+
+  // Callbacks
+  if (routes.callbacks) {
+    // Table-specific callback
+    if (routes.callbacks[event.table]) {
+      tasks.push(routes.callbacks[event.table](event));
+    }
+    // Wildcard callback
+    if (routes.callbacks['*']) {
+      tasks.push(routes.callbacks['*'](event));
+    }
+  }
+
+  await Promise.allSettled(tasks);
+}
+
+function handleSubAction(state: SubscriptionState, action: SubAction): void {
+  switch (action.action) {
+    case 'connect':
+      for (const channel of action.channels) {
+        addSubscription(state, channel, action.connectionId);
+      }
+      break;
+    case 'disconnect':
+      removeConnection(state, action.connectionId);
+      break;
+    case 'subscribe':
+      for (const channel of action.channels) {
+        addSubscription(state, channel, action.connectionId);
+      }
+      break;
+    case 'unsubscribe':
+      for (const channel of action.channels) {
+        removeSubscription(state, channel, action.connectionId);
+      }
+      break;
+  }
+}
+
+// --- Event actions helpers ---
+
+function rowToEventAction(row: Record<string, unknown>): EventAction {
+  const config = row.config;
+  const filter = row.filter;
+  return {
+    id: row.id as string,
+    tenantId: (row.tenant_id as string) ?? null,
+    name: row.name as string,
+    schemaName: row.schema_name as string,
+    tableName: row.table_name as string,
+    operation: row.operation as EventAction['operation'],
+    actionType: row.action_type as EventAction['actionType'],
+    config: typeof config === 'string' ? JSON.parse(config) : (config as Record<string, unknown>) ?? {},
+    filter: filter ? (typeof filter === 'string' ? JSON.parse(filter) : filter as Record<string, unknown>) : null,
+    enabled: row.enabled as boolean,
+    priority: row.priority as number,
+  };
+}
+
+async function loadEventActions(
+  pgClient: { query(text: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }> },
+  cache: ReturnType<typeof createActionCache>,
+): Promise<void> {
+  try {
+    const { rows } = await pgClient.query(
+      `SELECT id, tenant_id, name, schema_name, table_name, operation,
+              action_type, config, filter, enabled, priority
+       FROM ops.event_actions
+       WHERE enabled = true
+       ORDER BY priority DESC`
+    );
+    cache.set(rows.map(rowToEventAction));
+  } catch {
+    // Table might not exist yet — keep existing cache (empty on first load)
+  }
+}
+
+// --- Cold path reconciliation ---
+
+async function reconcile(
+  pgClient: { query(text: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }> },
+  state: SubscriptionState,
+  routes: ListenerRoutes,
+  lambdaClient: { invoke(params: unknown): Promise<unknown> },
+  actionCache: ReturnType<typeof createActionCache>,
+): Promise<void> {
+  // 1. Rebuild subscription map from auth.sessions (domain='ws')
+  try {
+    const { rows: connections } = await pgClient.query(
+      `SELECT data->>'connectionId' AS connection_id, data->'channels' AS channels
+       FROM auth.sessions
+       WHERE domain = 'ws' AND status = 'active' AND last_used_at > now() - interval '15 minutes'`
+    );
+    for (const conn of connections) {
+      const channels = conn.channels as string[];
+      const connectionId = conn.connection_id as string;
+      if (connectionId && channels) {
+        for (const channel of channels) {
+          addSubscription(state, channel, connectionId);
+        }
+      }
+    }
+  } catch {
+    // Table might not exist yet — skip subscription rebuild
+  }
+
+  // 2. Process pending jobs
+  if (routes.lambda?.jobs) {
+    try {
+      const { rows: pendingJobs } = await pgClient.query(
+        `SELECT id FROM jobs WHERE status = 'pending' AND run_at <= now() ORDER BY priority DESC, run_at ASC`
+      );
+      const fnName = routes.lambda.jobs.functionName || routes.lambda.jobs.functionArn;
+      if (fnName) {
+        for (const job of pendingJobs) {
+          await invokeLambda(lambdaClient, fnName, {
+            table: 'jobs',
+            op: 'insert',
+            id: job.id as string,
+          });
+        }
+      }
+    } catch {
+      // jobs table might not exist
+    }
+  }
+
+  // 3. Purge stale WS sessions
+  try {
+    await pgClient.query(
+      `UPDATE auth.sessions SET status = 'disconnected', ended_at = now()
+       WHERE domain = 'ws' AND status = 'active' AND last_used_at < now() - interval '15 minutes'`
+    );
+  } catch {
+    // Table might not exist yet
+  }
+
+  // 4. Load event_actions cache
+  await loadEventActions(pgClient, actionCache);
+}
+
+// --- Internal (testable) listener factory ---
+
+interface InternalListenerOptions {
+  pgClient: {
+    connect(): Promise<void>;
+    query(text: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
+    on(event: string, cb: (msg: { channel: string; payload: string }) => void): void;
+    end(): Promise<void>;
+  };
+  channels: string[];
+  lockId: number;
+  routes: ListenerRoutes;
+  apigw: { postToConnection(params: { ConnectionId: string; Data: Buffer }): Promise<unknown> };
+  lambdaClient: { invoke(params: unknown): Promise<unknown> };
+  reconcile?: (db: unknown) => Promise<void>;
+  heartbeatInterval?: number;
+  eventActions?: EventActionsOptions;
+  kvsClient?: KvsClient | null;
+}
+
+interface HandlerEvent {
+  _testMaxMs?: number;
+}
+
+export function createListenerInternal(options: InternalListenerOptions) {
+  const {
+    pgClient,
+    channels,
+    lockId,
+    routes,
+    apigw,
+    lambdaClient,
+    heartbeatInterval = 30000,
+    eventActions,
+    kvsClient = null,
+  } = options;
+
+  return async function handler(event: HandlerEvent = {}): Promise<{ status: string; reason?: string }> {
+    // 1. Connect
+    await pgClient.connect();
+
+    // 2. Acquire advisory lock
+    const { rows } = await pgClient.query(
+      'SELECT pg_try_advisory_lock($1)',
+      [lockId]
+    );
+    const lockAcquired = rows[0]?.pg_try_advisory_lock;
+    if (!lockAcquired) {
+      await pgClient.end();
+      return { status: 'skipped', reason: 'lock_held' };
+    }
+
+    // 3. LISTEN on channels
+    for (const channel of channels) {
+      await pgClient.query(`LISTEN "${channel}"`);
+    }
+
+    // 4. Set up subscription state + action cache
+    const state = createSubscriptionState();
+    const actionCache = createActionCache();
+
+    // 5. Cold path reconciliation (includes loading event_actions)
+    await reconcile(pgClient, state, routes, lambdaClient, actionCache);
+
+    // 6. Set up notification handler
+    pgClient.on('notification', (msg: { channel: string; payload: string }) => {
+      try {
+        if (msg.channel === '_subs') {
+          const action = JSON.parse(msg.payload) as SubAction;
+          handleSubAction(state, action);
+        } else if (msg.channel === '_event_actions') {
+          // Reload event_actions cache
+          loadEventActions(pgClient, actionCache);
+        } else if (msg.channel === 'events') {
+          const ev = JSON.parse(msg.payload) as EventPayload;
+          // Existing hardcoded routing (backwards compatible)
+          routeEvent(state, ev, routes, apigw, lambdaClient);
+          // Data-driven routing via event_actions
+          const matched = matchEventActions(actionCache.get(), ev);
+          if (matched.length > 0) {
+            dispatchActions(matched, ev, pgClient, lambdaClient, kvsClient, {
+              workerFunctionName: eventActions?.workerFunctionName,
+              defaultKvsArn: eventActions?.defaultKvsArn,
+            });
+          }
+        }
+      } catch {
+        // Malformed payload — skip
+      }
+    });
+
+    // 7. Run event loop
+    const maxMs = event._testMaxMs ?? 14 * 60 * 1000; // 14 minutes default
+    const heartbeat = setInterval(async () => {
+      try {
+        await pgClient.query('SELECT 1');
+      } catch {
+        // Connection lost — exit will happen naturally
+      }
+    }, heartbeatInterval);
+
+    await new Promise<void>((resolve) => setTimeout(resolve, maxMs));
+
+    clearInterval(heartbeat);
+
+    // 8. Cleanup
+    await pgClient.end();
+
+    return { status: 'completed' };
+  };
+}
+
+// --- Public API ---
+
+export function createListener(options: ListenerOptions) {
+  return async function handler(_event?: unknown): Promise<{ status: string; reason?: string }> {
+    // Dynamic imports to avoid bundling AWS SDK when not needed
+    const { default: pg } = await import('pg' as string);
+    const pgClient = new pg.Client({ connectionString: options.connectionString });
+
+    let apigw: { postToConnection(params: { ConnectionId: string; Data: Buffer }): Promise<unknown> } = {
+      postToConnection: async () => {},
+    };
+    let lambdaClient: { invoke(params: unknown): Promise<unknown> } = {
+      invoke: async () => {},
+    };
+
+    if (options.routes.websocket) {
+      const { ApiGatewayManagementApiClient, PostToConnectionCommand } = await import(
+        '@aws-sdk/client-apigatewaymanagementapi' as string
+      );
+      const client = new ApiGatewayManagementApiClient({
+        endpoint: options.routes.websocket.endpoint,
+        region: options.routes.websocket.region,
+      });
+      apigw = {
+        postToConnection: (params) =>
+          client.send(new PostToConnectionCommand(params)),
+      };
+    }
+
+    if (options.routes.lambda || options.eventActions?.workerFunctionName) {
+      const { LambdaClient, InvokeCommand } = await import(
+        '@aws-sdk/client-lambda' as string
+      );
+      const client = new LambdaClient({});
+      lambdaClient = {
+        invoke: (params) => client.send(new InvokeCommand(params as any)),
+      };
+    }
+
+    // KVS client for cache_purge event actions
+    let kvsClient: KvsClient | null = null;
+    if (options.eventActions?.defaultKvsArn) {
+      try {
+        await import('@aws-sdk/signature-v4a' as string);
+        const {
+          CloudFrontKeyValueStoreClient,
+          DescribeKeyValueStoreCommand,
+          PutKeyCommand,
+        } = await import('@aws-sdk/client-cloudfront-keyvaluestore' as string);
+        const client = new CloudFrontKeyValueStoreClient({});
+        kvsClient = {
+          describe: async (kvsArn: string) => {
+            const desc = await client.send(new DescribeKeyValueStoreCommand({ KvsARN: kvsArn }));
+            return { ETag: desc.ETag! };
+          },
+          put: async (kvsArn: string, key: string, value: string, etag: string) => {
+            await client.send(new PutKeyCommand({
+              KvsARN: kvsArn,
+              Key: key,
+              Value: value,
+              IfMatch: etag,
+            }));
+          },
+        };
+      } catch {
+        // KVS SDK not available — skip cache_purge actions
+      }
+    }
+
+    const internal = createListenerInternal({
+      pgClient: pgClient as any,
+      channels: options.channels ?? ['events', '_subs', '_event_actions'],
+      lockId: options.lockId ?? 74736,
+      routes: options.routes,
+      apigw,
+      lambdaClient,
+      heartbeatInterval: options.heartbeatInterval,
+      eventActions: options.eventActions,
+      kvsClient,
+    });
+
+    return internal({});
+  };
+}