@arcote.tech/arc-host 0.3.4 → 0.4.1

package/src/create-server.ts

@@ -0,0 +1,213 @@
+import type { ArcContextAny, DatabaseAdapter } from "@arcote.tech/arc";
+import type { Server } from "bun";
+import jwt from "jsonwebtoken";
+import { ConnectionManager } from "./connection-manager";
+import { ContextHandler } from "./context-handler";
+import { CronScheduler } from "./cron-scheduler";
+import {
+  arcHttpHandlers,
+  arcWsHandlers,
+  cleanupClientSubs,
+  cleanupStreams,
+} from "./middleware";
+import type {
+  ArcHttpHandler,
+  ArcRequestContext,
+  ArcWsContext,
+  ArcWsHandler,
+} from "./middleware/types";
+import type { TokenPayload } from "./types";
+
+type WebSocketData = { clientId: string };
+
+export interface ArcServerConfig {
+  context: ArcContextAny;
+  dbAdapterFactory: (ctx: any) => Promise<DatabaseAdapter>;
+  httpHandlers?: ArcHttpHandler[];
+  wsHandlers?: ArcWsHandler[];
+  port?: number;
+  jwtSecret?: string;
+  /** Extra callback when a WS client disconnects (e.g. to clean up platform state) */
+  onWsClose?: (clientId: string) => void;
+}
+
+export interface ArcServer {
+  server: Server<WebSocketData>;
+  contextHandler: ContextHandler;
+  connectionManager: ConnectionManager;
+  cronScheduler: CronScheduler;
+  stop: () => void;
+}
+
+/**
+ * Create an Arc server with composable HTTP + WS middleware.
+ *
+ * By default includes all Arc handlers (command, query, stream, route, eventSync, health,
+ * scope:auth, sync-events, request-sync, execute-command, view subscriptions).
+ * Platform servers add their own handlers on top.
+ */
+export async function createArcServer(
+  config: ArcServerConfig,
+): Promise<ArcServer> {
+  const jwtSecret =
+    config.jwtSecret ||
+    process.env.JWT_SECRET ||
+    "arc-host-secret-change-in-production";
+  const port = config.port || 5005;
+
+  // Init context handler
+  const dbAdapter = config.dbAdapterFactory(config.context);
+  const contextHandler = new ContextHandler(config.context, dbAdapter);
+  await contextHandler.init();
+
+  // Start cron scheduler
+  const cronScheduler = new CronScheduler(contextHandler);
+  cronScheduler.start();
+
+  const connectionManager = new ConnectionManager();
+
+  const corsHeaders = {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS",
+    "Access-Control-Allow-Headers":
+      "Content-Type, Authorization, X-Arc-Scope",
+  };
+
+  function verifyToken(token: string): TokenPayload | null {
+    try {
+      const decoded = jwt.verify(token, jwtSecret) as any;
+      if (decoded.tokenName && !decoded.tokenType) {
+        return {
+          tokenType: decoded.tokenName,
+          params: decoded.params || {},
+          iat: decoded.iat,
+          exp: decoded.exp,
+        };
+      }
+      return decoded as TokenPayload;
+    } catch {
+      try {
+        const parts = token.split(".");
+        if (parts.length !== 3) return null;
+        const payload = JSON.parse(atob(parts[1]));
+        return {
+          tokenType: payload.tokenName,
+          params: payload.params || {},
+          iat: payload.iat,
+          exp: payload.exp,
+        };
+      } catch {
+        return null;
+      }
+    }
+  }
+
+  // Build handler chains — Arc defaults + user-provided extras
+  const defaultHttp = arcHttpHandlers(contextHandler, connectionManager);
+  const defaultWs = arcWsHandlers();
+
+  const httpHandlers = config.httpHandlers
+    ? [...defaultHttp, ...config.httpHandlers]
+    : defaultHttp;
+
+  const wsHandlers = config.wsHandlers
+    ? [...defaultWs, ...config.wsHandlers]
+    : defaultWs;
+
+  const wsCtx: ArcWsContext = {
+    contextHandler,
+    connectionManager,
+    verifyToken,
+  };
+
+  const server = Bun.serve<WebSocketData>({
+    port,
+    idleTimeout: 255,
+
+    async fetch(req, server) {
+      const url = new URL(req.url);
+
+      // CORS preflight
+      if (req.method === "OPTIONS") {
+        return new Response(null, { headers: corsHeaders });
+      }
+
+      // Token extraction
+      const authHeader = req.headers.get("Authorization");
+      const rawToken =
+        authHeader?.replace("Bearer ", "") ||
+        url.searchParams.get("token");
+      const tokenPayload = rawToken ? verifyToken(rawToken) : null;
+
+      // WebSocket upgrade
+      if (
+        url.pathname === "/ws" &&
+        req.headers.get("Upgrade") === "websocket"
+      ) {
+        if (server.upgrade(req, { data: { clientId: "" } })) return undefined;
+        return new Response("WebSocket upgrade failed", {
+          status: 500,
+          headers: corsHeaders,
+        });
+      }
+
+      // Run HTTP handler chain
+      const reqCtx: ArcRequestContext = {
+        rawToken,
+        tokenPayload,
+        corsHeaders,
+      };
+      for (const handler of httpHandlers) {
+        const response = await handler(req, url, reqCtx);
+        if (response) return response;
+      }
+
+      return new Response("Not Found", {
+        status: 404,
+        headers: corsHeaders,
+      });
+    },
+
+    websocket: {
+      open(ws) {
+        connectionManager.addClient(ws as any);
+      },
+      async message(ws, messageStr) {
+        const client = connectionManager.getClientByWs(ws as any);
+        if (!client) return;
+
+        try {
+          const message = JSON.parse(messageStr as string);
+          for (const handler of wsHandlers) {
+            const handled = await handler(client, message, wsCtx);
+            if (handled) break;
+          }
+        } catch (error) {
+          console.error("Failed to parse WS message:", error);
+        }
+      },
+      close(ws) {
+        const client = connectionManager.getClientByWs(ws as any);
+        if (client) {
+          cleanupClientSubs(client.id);
+          config.onWsClose?.(client.id);
+          connectionManager.removeClient(client.id);
+        }
+      },
+    },
+  });
+
+  console.log(`Arc Server running on http://localhost:${port}`);
+
+  return {
+    server,
+    contextHandler,
+    connectionManager,
+    cronScheduler,
+    stop: () => {
+      cronScheduler.stop();
+      cleanupStreams();
+      server.stop();
+    },
+  };
+}

package/src/cron-scheduler.ts

@@ -0,0 +1,124 @@
+/**
+ * CronScheduler
+ *
+ * Discovers aggregate cron methods from context elements and schedules them
+ * using node-cron. For each cron trigger, queries all instances of the aggregate
+ * and executes the command for each instance.
+ */
+
+import type { ArcContextAny, AggregateCronMethodEntry } from "@arcote.tech/arc";
+import { Cron } from "croner";
+import type { ContextHandler } from "./context-handler";
+
+interface CronJob {
+  entry: AggregateCronMethodEntry;
+  task: Cron;
+}
+
+export class CronScheduler {
+  private jobs: CronJob[] = [];
+  private contextHandler: ContextHandler;
+
+  constructor(contextHandler: ContextHandler) {
+    this.contextHandler = contextHandler;
+  }
+
+  /**
+   * Discover cron methods from all aggregates in the context and start scheduling.
+   */
+  start(): void {
+    const context = this.contextHandler.context;
+    const cronEntries = this.discoverCronMethods(context);
+
+    if (cronEntries.length === 0) return;
+
+    console.log(
+      `[ARC:Cron] Discovered ${cronEntries.length} cron method(s):`,
+    );
+
+    for (const entry of cronEntries) {
+      console.log(
+        `[ARC:Cron]   ${entry.aggregateName}.${entry.methodName} → "${entry.cronExpression}"`,
+      );
+
+      const task = new Cron(entry.cronExpression, async () => {
+        await this.executeCronMethod(entry);
+      });
+
+      this.jobs.push({ entry, task });
+    }
+  }
+
+  /**
+   * Stop all cron jobs.
+   */
+  stop(): void {
+    for (const job of this.jobs) {
+      job.task.stop();
+    }
+    this.jobs = [];
+    console.log("[ARC:Cron] All cron jobs stopped.");
+  }
+
+  /**
+   * Extract cron method entries from all aggregate context elements.
+   */
+  private discoverCronMethods(
+    context: ArcContextAny,
+  ): AggregateCronMethodEntry[] {
+    const entries: AggregateCronMethodEntry[] = [];
+
+    for (const element of context.elements) {
+      const ctor = (element as any).ctor;
+      if (ctor?.__aggregateCronMethods) {
+        entries.push(...ctor.__aggregateCronMethods);
+      }
+    }
+
+    return entries;
+  }
+
+  /**
+   * Execute a cron method for all instances of the aggregate.
+   */
+  private async executeCronMethod(
+    entry: AggregateCronMethodEntry,
+  ): Promise<void> {
+    const commandName = `${entry.aggregateName}.${entry.methodName}`;
+
+    try {
+      // Query all instances of this aggregate
+      const dataStorage = this.contextHandler.getDataStorage();
+      const store = dataStorage.getStore<any>(entry.aggregateName);
+      const instances = await store.find({});
+
+      if (instances.length === 0) {
+        console.log(
+          `[ARC:Cron] ${commandName}: no instances found, skipping.`,
+        );
+        return;
+      }
+
+      console.log(
+        `[ARC:Cron] ${commandName}: executing for ${instances.length} instance(s)...`,
+      );
+
+      for (const instance of instances) {
+        try {
+          await this.contextHandler.executeCommand(
+            commandName,
+            { _id: instance._id },
+            null,
+          );
+        } catch (error) {
+          console.error(
+            `[ARC:Cron] ${commandName} failed for instance ${instance._id}:`,
+            error,
+          );
+        }
+      }
+    } catch (error) {
+      console.error(`[ARC:Cron] ${commandName} failed:`, error);
+    }
+  }
+}

package/src/event-auth.ts

@@ -109,7 +109,7 @@ function checkConditionsMatch(
 }
 
 /**
- * Filter events that a token can receive
+ * Filter events that a single token can receive
  */
 export function filterEventsForToken(
   token: TokenPayload | null,
@@ -125,3 +125,28 @@ export function filterEventsForToken(
     return canTokenReceiveEvent(token, eventDef, eventInstance);
   });
 }
+
+/**
+ * Filter events visible to ANY of the provided tokens.
+ * Used for multi-scope clients where an event visible to any scope should be sent.
+ */
+export function filterEventsForTokens(
+  tokens: TokenPayload[],
+  events: SyncableEvent[],
+  eventDefinitions: Map<string, ArcEventAny>,
+): SyncableEvent[] {
+  if (tokens.length === 0) {
+    // No tokens — only public events
+    return filterEventsForToken(null, events, eventDefinitions);
+  }
+
+  return events.filter((eventInstance) => {
+    const eventDef = eventDefinitions.get(eventInstance.type);
+    if (!eventDef) return false;
+
+    // Event is visible if ANY token can receive it
+    return tokens.some((token) =>
+      canTokenReceiveEvent(token, eventDef, eventInstance),
+    );
+  });
+}

package/src/index.ts

@@ -1,7 +1,44 @@
-// Main exports
-export { ArcHost } from "./arc-host";
+// Server
+export { createArcServer } from "./create-server";
+export type { ArcServer, ArcServerConfig } from "./create-server";
+
+// Middleware (composable handlers)
+export {
+  arcHttpHandlers,
+  arcWsHandlers,
+  cleanupClientSubs,
+  cleanupStreams,
+  commandHandler,
+  eventSyncHandler,
+  executeCommandHandler,
+  healthHandler,
+  queryHandler,
+  requestSyncHandler,
+  routeHandler,
+  scopeAuthHandler,
+  streamHandler,
+  syncEventsHandler,
+  querySubscriptionHandler,
+} from "./middleware";
+export type {
+  ArcHttpHandler,
+  ArcRequestContext,
+  ArcWsContext,
+  ArcWsHandler,
+} from "./middleware";
+
+// Core (unchanged)
 export { ConnectionManager } from "./connection-manager";
 export { ContextHandler } from "./context-handler";
+export { CronScheduler } from "./cron-scheduler";
+
+// Auth utilities
+export {
+  canTokenEmitEvent,
+  canTokenReceiveEvent,
+  filterEventsForToken,
+  filterEventsForTokens,
+} from "./event-auth";
 
 // Types
 export type {
@@ -12,10 +49,3 @@ export type {
   SyncableEvent,
   TokenPayload,
 } from "./types";
-
-// Auth utilities
-export {
-  canTokenEmitEvent,
-  canTokenReceiveEvent,
-  filterEventsForToken,
-} from "./event-auth";