cooper-stack 0.5.2

package/src/bridge.ts

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+/**
+ * Cooper JS Worker Bridge
+ *
+ * Spawned by the Rust runtime as a subprocess. Communicates via
+ * JSON-RPC over stdin/stdout. Loads user TypeScript modules and
+ * executes handler functions on demand.
+ *
+ * Protocol:
+ *   → { "id": 1, "method": "call", "params": { "source": "services/users/api.ts", "export": "getUser", "input": {...}, "auth": {...} } }
+ *   ← { "id": 1, "result": {...} }
+ *   ← { "id": 1, "error": { "code": "NOT_FOUND", "message": "User not found" } }
+ */
+
+import { registry } from "./registry.js";
+import { CooperError } from "./error.js";
+import { createRequire } from "node:module";
+import { createInterface } from "node:readline";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const projectRoot = process.env.COOPER_PROJECT_ROOT ?? process.cwd();
+
+// Module cache — avoid re-importing on every request
+const moduleCache = new Map<string, any>();
+
+async function loadModule(sourcePath: string): Promise<any> {
+  if (moduleCache.has(sourcePath)) return moduleCache.get(sourcePath)!;
+
+  const fullPath = path.resolve(projectRoot, sourcePath);
+  const fileUrl = pathToFileURL(fullPath).href;
+
+  try {
+    const mod = await import(fileUrl);
+    moduleCache.set(sourcePath, mod);
+    return mod;
+  } catch (err: any) {
+    throw new Error(`Failed to load module "${sourcePath}": ${err.message}`);
+  }
+}
+
+interface RPCRequest {
+  id: number;
+  method: string;
+  params: any;
+}
+
+interface RPCResponse {
+  id: number;
+  result?: any;
+  error?: { code: string; message: string; statusCode?: number };
+}
+
+async function handleCall(params: {
+  source: string;
+  export: string;
+  input: any;
+  auth?: any;
+  headers?: Record<string, string>;
+}): Promise<any> {
+  const mod = await loadModule(params.source);
+  const exported = mod[params.export];
+
+  if (!exported) {
+    throw new CooperError("NOT_FOUND", `Export "${params.export}" not found in ${params.source}`);
+  }
+
+  // Get the handler function
+  let handler: Function;
+  let routeConfig: any = null;
+
+  if (exported._cooper_type === "api") {
+    handler = exported.handler;
+    routeConfig = exported.config;
+  } else if (typeof exported === "function") {
+    handler = exported;
+  } else {
+    throw new CooperError("INTERNAL", `Export "${params.export}" is not callable`);
+  }
+
+  // Validation — run Zod schema if present.
+  // Use passthrough() to preserve path params that aren't in the schema.
+  let validatedInput = params.input;
+  if (routeConfig?.validate) {
+    const schema = routeConfig.validate;
+    const lenient = typeof schema.passthrough === "function" ? schema.passthrough() : schema;
+    const result = lenient.safeParse(params.input);
+    if (!result.success) {
+      throw new CooperError(
+        "VALIDATION_FAILED",
+        result.error.issues.map((i: any) => `${i.path.join(".")}: ${i.message}`).join("; ")
+      );
+    }
+    validatedInput = result.data;
+  }
+
+  // Auth — verify token and inject principal
+  let principal: any = undefined;
+  if (routeConfig?.auth) {
+    if (!params.auth?.token) {
+      throw new CooperError("UNAUTHORIZED", "Authentication required");
+    }
+    if (registry.authHandler) {
+      principal = await registry.authHandler(params.auth.token);
+    } else {
+      throw new CooperError("INTERNAL", "No auth handler registered");
+    }
+  }
+
+  // Middleware chain
+  const middlewares = [
+    ...registry.globalMiddleware,
+    ...(routeConfig?.middleware ?? []),
+  ];
+
+  const req = {
+    ...validatedInput,
+    headers: params.headers ?? {},
+    ip: params.headers?.["x-forwarded-for"] ?? "127.0.0.1",
+    method: routeConfig?.method ?? "GET",
+    path: routeConfig?.path ?? "/",
+  };
+
+  // Build the middleware chain
+  let idx = 0;
+  const runMiddleware = async (currentReq: any): Promise<any> => {
+    if (idx < middlewares.length) {
+      const mw = middlewares[idx++];
+      return mw(currentReq, runMiddleware);
+    }
+    // End of chain — call the actual handler
+    if (routeConfig?.auth) {
+      return handler(validatedInput, principal);
+    }
+    return handler(validatedInput);
+  };
+
+  return runMiddleware(req);
+}
+
+async function handleCron(params: { source: string; export: string }): Promise<any> {
+  const mod = await loadModule(params.source);
+  const exported = mod[params.export];
+
+  if (!exported) {
+    throw new CooperError("NOT_FOUND", `Cron "${params.export}" not found in ${params.source}`);
+  }
+
+  if (exported._cooper_type === "cron") {
+    // The cron was registered via the SDK, find it in the registry
+    const cronEntry = registry.crons.get(exported.name);
+    if (cronEntry) {
+      await cronEntry.handler();
+      return { ok: true };
+    }
+  }
+
+  throw new CooperError("INTERNAL", `Cannot execute cron "${params.export}"`);
+}
+
+async function handlePubSub(params: {
+  topic: string;
+  subscriber: string;
+  data: any;
+}): Promise<any> {
+  const topicEntry = registry.topics.get(params.topic);
+  if (!topicEntry) {
+    throw new CooperError("NOT_FOUND", `Topic "${params.topic}" not registered`);
+  }
+
+  const sub = topicEntry.subscribers.get(params.subscriber);
+  if (!sub) {
+    throw new CooperError("NOT_FOUND", `Subscriber "${params.subscriber}" not found on topic "${params.topic}"`);
+  }
+
+  await sub.handler(params.data);
+  return { ok: true };
+}
+
+async function handleRequest(req: RPCRequest): Promise<RPCResponse> {
+  try {
+    let result: any;
+
+    switch (req.method) {
+      case "call":
+        result = await handleCall(req.params);
+        break;
+      case "cron":
+        result = await handleCron(req.params);
+        break;
+      case "pubsub":
+        result = await handlePubSub(req.params);
+        break;
+      case "ping":
+        result = { pong: true, pid: process.pid };
+        break;
+      case "invalidate":
+        // Clear module cache for hot reload
+        moduleCache.clear();
+        result = { ok: true };
+        break;
+      default:
+        throw new CooperError("INVALID_ARGUMENT", `Unknown method: ${req.method}`);
+    }
+
+    return { id: req.id, result };
+  } catch (err: any) {
+    if (err instanceof CooperError) {
+      return {
+        id: req.id,
+        error: { code: err.code, message: err.message, statusCode: err.statusCode },
+      };
+    }
+    return {
+      id: req.id,
+      error: { code: "INTERNAL", message: err.message ?? "Unknown error", statusCode: 500 },
+    };
+  }
+}
+
+// Main loop — read JSON lines from stdin, write responses to stdout
+const rl = createInterface({ input: process.stdin });
+
+rl.on("line", async (line) => {
+  if (!line.trim()) return;
+
+  try {
+    const req: RPCRequest = JSON.parse(line);
+    const res = await handleRequest(req);
+    process.stdout.write(JSON.stringify(res) + "\n");
+  } catch (err: any) {
+    process.stdout.write(
+      JSON.stringify({ id: 0, error: { code: "INTERNAL", message: `Bridge parse error: ${err.message}` } }) + "\n"
+    );
+  }
+});
+
+// Preload auth handlers and middleware — these register via side effects
+async function preloadSideEffects() {
+  const fs = await import("node:fs");
+  const servicesDir = path.join(projectRoot, "services");
+  if (!fs.existsSync(servicesDir)) return;
+
+  const scanDir = (dir: string) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        scanDir(fullPath);
+      } else if (entry.name.endsWith(".ts") || entry.name.endsWith(".js")) {
+        try {
+          const content = fs.readFileSync(fullPath, "utf-8");
+          if (content.includes("authHandler") || content.includes("middleware(")) {
+            const relative = path.relative(projectRoot, fullPath);
+            loadModule(relative).catch(() => {});
+          }
+        } catch {}
+      }
+    }
+  };
+
+  scanDir(servicesDir);
+}
+
+await preloadSideEffects();
+
+// Signal ready
+process.stdout.write(JSON.stringify({ id: 0, result: { ready: true, pid: process.pid } }) + "\n");

package/src/cache.ts

@@ -0,0 +1,86 @@
+export interface CacheConfig {
+  ttl?: string; // e.g. "10m", "1h", "30s"
+}
+
+export interface CacheClient<T> {
+  get(key: string): Promise<T | null>;
+  set(key: string, value: T, opts?: { ttl?: string }): Promise<void>;
+  getOrSet(key: string, factory: () => Promise<T>, opts?: { ttl?: string }): Promise<T>;
+  delete(key: string): Promise<void>;
+  invalidatePrefix(prefix: string): Promise<void>;
+  increment(key: string, opts?: { ttl?: string }): Promise<number>;
+}
+
+function parseTTL(ttl: string): number {
+  const match = ttl.match(/^(\d+)(s|m|h|d)$/);
+  if (!match) return 600;
+  const [, num, unit] = match;
+  const multipliers: Record<string, number> = { s: 1, m: 60, h: 3600, d: 86400 };
+  return parseInt(num) * (multipliers[unit] ?? 60);
+}
+
+/**
+ * Declare a typed cache.
+ *
+ * ```ts
+ * export const userCache = cache<User>("users", { ttl: "10m" });
+ * const user = await userCache.getOrSet(userId, () => db.queryRow(...));
+ * ```
+ */
+export function cache<T = any>(name: string, config?: CacheConfig): CacheClient<T> {
+  const defaultTTL = config?.ttl ?? "10m";
+  let redis: any = null;
+
+  const ensureRedis = async () => {
+    if (redis) return redis;
+    const Redis = (await import("ioredis")).default;
+    const url = process.env.COOPER_VALKEY_URL ?? "redis://localhost:6379";
+    redis = new Redis(url);
+    return redis;
+  };
+
+  const prefixed = (key: string) => `cooper:${name}:${key}`;
+
+  return {
+    async get(key: string): Promise<T | null> {
+      const r = await ensureRedis();
+      const val = await r.get(prefixed(key));
+      return val ? JSON.parse(val) : null;
+    },
+
+    async set(key: string, value: T, opts?: { ttl?: string }): Promise<void> {
+      const r = await ensureRedis();
+      const ttlSec = parseTTL(opts?.ttl ?? defaultTTL);
+      await r.setex(prefixed(key), ttlSec, JSON.stringify(value));
+    },
+
+    async getOrSet(key: string, factory: () => Promise<T>, opts?: { ttl?: string }): Promise<T> {
+      const existing = await this.get(key);
+      if (existing !== null) return existing;
+      const value = await factory();
+      await this.set(key, value, opts);
+      return value;
+    },
+
+    async delete(key: string): Promise<void> {
+      const r = await ensureRedis();
+      await r.del(prefixed(key));
+    },
+
+    async invalidatePrefix(prefix: string): Promise<void> {
+      const r = await ensureRedis();
+      const keys = await r.keys(prefixed(prefix) + "*");
+      if (keys.length > 0) await r.del(...keys);
+    },
+
+    async increment(key: string, opts?: { ttl?: string }): Promise<number> {
+      const r = await ensureRedis();
+      const k = prefixed(key);
+      const val = await r.incr(k);
+      if (val === 1 && opts?.ttl) {
+        await r.expire(k, parseTTL(opts.ttl));
+      }
+      return val;
+    },
+  };
+}

package/src/cron.ts

@@ -0,0 +1,32 @@
+import { registry } from "./registry.js";
+
+export interface CronConfig {
+  schedule: string;
+  handler: () => Promise<void>;
+}
+
+/**
+ * Declare a cron job.
+ *
+ * ```ts
+ * export const cleanup = cron("cleanup", {
+ *   schedule: "every 1 hour",
+ *   handler: async () => {
+ *     await db.query("DELETE FROM sessions WHERE expires_at < NOW()");
+ *   },
+ * });
+ * ```
+ */
+export function cron(name: string, config: CronConfig) {
+  registry.registerCron(name, {
+    name,
+    schedule: config.schedule,
+    handler: config.handler,
+  });
+
+  return {
+    _cooper_type: "cron" as const,
+    name,
+    schedule: config.schedule,
+  };
+}

package/src/db.ts

@@ -0,0 +1,109 @@
+import { registry } from "./registry.js";
+
+export interface DatabaseConfig {
+  engine?: "postgres" | "mysql" | "mongodb" | "dynamodb";
+  migrations?: string;
+  partitionKey?: string;
+  sortKey?: string;
+}
+
+export interface DatabaseClient {
+  /** Run a query returning multiple rows */
+  query<T = any>(sql: string, params?: any[]): Promise<T[]>;
+  /** Run a query returning a single row or null */
+  queryRow<T = any>(sql: string, params?: any[]): Promise<T | null>;
+  /** Run a query returning affected row count */
+  exec(sql: string, params?: any[]): Promise<{ rowCount: number }>;
+  /** Insert and return the inserted row */
+  insert<T = any>(table: string, data: Record<string, any>): Promise<T>;
+  /** Access the underlying connection pool (for ORMs like Drizzle) */
+  pool: any;
+}
+
+/**
+ * Declare a database.
+ *
+ * ```ts
+ * export const db = database("main", { migrations: "./migrations" });
+ * const user = await db.queryRow<User>("SELECT * FROM users WHERE id = $1", [id]);
+ * ```
+ */
+export function database(name: string, config?: DatabaseConfig): DatabaseClient {
+  const engine = config?.engine ?? "postgres";
+
+  // Connection details injected by the Rust runtime via env vars
+  const connStr = process.env[`COOPER_DB_${name.toUpperCase()}_URL`]
+    ?? `postgres://cooper:cooper@localhost:5432/cooper_${name}`;
+
+  let pool: any = null;
+
+  const ensurePool = async () => {
+    if (pool) return pool;
+
+    if (engine === "postgres") {
+      const pg = await import("pg");
+      pool = new pg.default.Pool({ connectionString: connStr });
+      return pool;
+    }
+
+    if (engine === "mysql") {
+      const mysql = await import("mysql2/promise");
+      pool = await mysql.createPool(connStr);
+      return pool;
+    }
+
+    throw new Error(`Database engine "${engine}" not yet supported in JS runtime`);
+  };
+
+  const client: DatabaseClient = {
+    async query<T = any>(sql: string, params?: any[]): Promise<T[]> {
+      const p = await ensurePool();
+      if (engine === "postgres") {
+        const res = await p.query(sql, params);
+        return res.rows as T[];
+      }
+      if (engine === "mysql") {
+        const [rows] = await p.execute(sql, params);
+        return rows as T[];
+      }
+      return [];
+    },
+
+    async queryRow<T = any>(sql: string, params?: any[]): Promise<T | null> {
+      const rows = await client.query<T>(sql, params);
+      return rows[0] ?? null;
+    },
+
+    async exec(sql: string, params?: any[]): Promise<{ rowCount: number }> {
+      const p = await ensurePool();
+      if (engine === "postgres") {
+        const res = await p.query(sql, params);
+        return { rowCount: res.rowCount ?? 0 };
+      }
+      if (engine === "mysql") {
+        const [result] = await p.execute(sql, params);
+        return { rowCount: (result as any).affectedRows ?? 0 };
+      }
+      return { rowCount: 0 };
+    },
+
+    async insert<T = any>(table: string, data: Record<string, any>): Promise<T> {
+      const keys = Object.keys(data);
+      const values = Object.values(data);
+      const placeholders = keys.map((_, i) =>
+        engine === "postgres" ? `$${i + 1}` : "?"
+      );
+      const sql = `INSERT INTO ${table} (${keys.join(", ")}) VALUES (${placeholders.join(", ")}) RETURNING *`;
+      const row = await client.queryRow<T>(sql, values);
+      return row!;
+    },
+
+    get pool() {
+      return pool;
+    },
+  };
+
+  registry.registerDatabase(name, { name, engine, pool: client });
+
+  return client;
+}

package/src/error.ts

@@ -0,0 +1,42 @@
+/**
+ * Structured error codes with automatic HTTP status mapping.
+ */
+export type ErrorCode =
+  | "NOT_FOUND"
+  | "UNAUTHORIZED"
+  | "PERMISSION_DENIED"
+  | "RATE_LIMITED"
+  | "INVALID_ARGUMENT"
+  | "VALIDATION_FAILED"
+  | "INTERNAL";
+
+const STATUS_MAP: Record<ErrorCode, number> = {
+  NOT_FOUND: 404,
+  UNAUTHORIZED: 401,
+  PERMISSION_DENIED: 403,
+  RATE_LIMITED: 429,
+  INVALID_ARGUMENT: 400,
+  VALIDATION_FAILED: 422,
+  INTERNAL: 500,
+};
+
+export class CooperError extends Error {
+  public readonly code: ErrorCode;
+  public readonly statusCode: number;
+
+  constructor(code: ErrorCode, message: string) {
+    super(message);
+    this.name = "CooperError";
+    this.code = code;
+    this.statusCode = STATUS_MAP[code] ?? 500;
+  }
+
+  toJSON() {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+      },
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export { api } from "./api.js";
+export { CooperError, type ErrorCode } from "./error.js";
+export { database, type DatabaseClient } from "./db.js";
+export { middleware, cooper } from "./middleware.js";
+export { authHandler } from "./auth.js";
+export { topic, type Topic } from "./pubsub.js";
+export { cron } from "./cron.js";
+export { cache, type CacheClient } from "./cache.js";
+export { bucket, type BucketClient } from "./storage.js";
+export { secret } from "./secrets.js";
+export { queue, type QueueClient } from "./queue.js";
+export { page, layout, pageLoader, Suspense } from "./ssr.js";
+export { island } from "./islands.js";
+export { vectorStore, llmGateway } from "./ai.js";
+export { registry } from "./registry.js";

package/src/islands.ts

@@ -0,0 +1,28 @@
+export type HydrationStrategy = "load" | "visible" | "idle" | "interaction" | "none";
+
+/**
+ * Mark a component as an island — it will be hydrated on the client.
+ *
+ * ```tsx
+ * // islands/LikeButton.island.tsx
+ * export default island(function LikeButton({ userId, initialCount }) {
+ *   const [count, setCount] = useState(initialCount);
+ *   return <button onClick={...}>Like ({count})</button>;
+ * });
+ * ```
+ */
+export function island<P = any>(
+  component: (props: P) => any
+): (props: P & { hydrate?: HydrationStrategy }) => any {
+  // Mark the component for the bundler
+  const wrapper = (props: P & { hydrate?: HydrationStrategy }) => {
+    // Server-side: render the component to HTML
+    // Client-side: hydrate based on strategy
+    return component(props);
+  };
+
+  (wrapper as any)._cooper_island = true;
+  (wrapper as any)._cooper_hydrate = "load"; // default strategy
+
+  return wrapper;
+}

package/src/middleware.ts

@@ -0,0 +1,27 @@
+import { registry, type MiddlewareFn } from "./registry.js";
+
+/**
+ * Define a middleware function.
+ *
+ * ```ts
+ * const rateLimiter = middleware(async (req, next) => {
+ *   const count = await userCache.increment(`rate:${req.ip}`, { ttl: "1m" });
+ *   if (count > 100) throw new CooperError("RATE_LIMITED");
+ *   return next(req);
+ * });
+ * ```
+ */
+export function middleware(fn: MiddlewareFn): MiddlewareFn {
+  return fn;
+}
+
+/**
+ * Cooper instance for global middleware registration.
+ */
+export const cooper = {
+  use(...middlewares: MiddlewareFn[]) {
+    for (const mw of middlewares) {
+      registry.addGlobalMiddleware(mw);
+    }
+  },
+};

package/src/pubsub.ts

@@ -0,0 +1,69 @@
+import { registry } from "./registry.js";
+
+export interface TopicConfig {
+  deliveryGuarantee?: "at-least-once" | "exactly-once";
+  orderBy?: string;
+}
+
+export interface SubscribeConfig {
+  concurrency?: number;
+  handler: (data: any) => Promise<void>;
+}
+
+export interface Topic<T> {
+  publish(data: T): Promise<void>;
+  subscribe(name: string, config: SubscribeConfig): any;
+}
+
+/**
+ * Declare a typed Pub/Sub topic.
+ *
+ * ```ts
+ * export const UserSignedUp = topic<{ userId: string; email: string }>(
+ *   "user-signed-up",
+ *   { deliveryGuarantee: "at-least-once" }
+ * );
+ * ```
+ */
+export function topic<T = any>(name: string, config?: TopicConfig): Topic<T> {
+  const subscribers = new Map<string, { handler: Function; options: any }>();
+
+  const t: Topic<T> = {
+    async publish(data: T) {
+      // In local dev, deliver directly to subscribers
+      // In production, publish to NATS/SNS/Pub/Sub
+      const natsUrl = process.env.COOPER_NATS_URL ?? "nats://localhost:4222";
+
+      // Direct local delivery for development
+      for (const [subName, sub] of subscribers) {
+        try {
+          await sub.handler(data);
+        } catch (err) {
+          console.error(`[cooper] Subscriber "${subName}" failed:`, err);
+        }
+      }
+    },
+
+    subscribe(subName: string, subConfig: SubscribeConfig) {
+      subscribers.set(subName, {
+        handler: subConfig.handler,
+        options: subConfig,
+      });
+
+      registry.registerTopic(name, {
+        name,
+        subscribers,
+      });
+
+      return {
+        _cooper_type: "subscription",
+        topic: name,
+        name: subName,
+      };
+    },
+  };
+
+  registry.registerTopic(name, { name, subscribers });
+
+  return t;
+}