cooper-stack 0.1.0

package/src/pubsub.ts

@@ -0,0 +1,208 @@
+import { registry } from "./registry.js";
+import {
+  ensureConnected,
+  getJetStream,
+  getJetStreamManager,
+  jsonCodec,
+  streamName,
+  consumerName,
+  ensureStream,
+} from "./nats.js";
+import { headers as natsHeaders, AckPolicy } from "nats";
+
+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" }
+ * );
+ * ```
+ *
+ * Local dev uses embedded NATS with JetStream for durable delivery.
+ * Falls back to in-memory if NATS is unavailable.
+ */
+export function topic<T = any>(name: string, config?: TopicConfig): Topic<T> {
+  const subscribers = new Map<string, { handler: Function; options: any }>();
+  const useDedup = config?.deliveryGuarantee === "exactly-once";
+  const subject = `cooper.topic.${name}`;
+
+  // Track whether JetStream consumers have been started
+  const activeConsumers = new Set<string>();
+
+  /**
+   * Start a JetStream pull consumer for a subscriber.
+   * Runs in the background, processing messages until the connection closes.
+   */
+  async function startConsumer(
+    subName: string,
+    handler: Function,
+    concurrency: number
+  ): Promise<void> {
+    if (activeConsumers.has(subName)) return;
+    activeConsumers.add(subName);
+
+    const js = getJetStream();
+    const jsm = getJetStreamManager();
+    if (!js || !jsm) return;
+
+    const stream = streamName(name);
+    const durable = consumerName(subName);
+
+    // Ensure consumer exists
+    try {
+      await jsm.consumers.info(stream, durable);
+    } catch {
+      await jsm.consumers.add(stream, {
+        durable_name: durable,
+        ack_policy: AckPolicy.Explicit,
+        max_ack_pending: concurrency,
+        filter_subject: subject,
+      });
+    }
+
+    const consumer = await js.consumers.get(stream, durable);
+
+    // Process messages in the background
+    (async () => {
+      try {
+        const messages = await consumer.consume();
+        for await (const msg of messages) {
+          try {
+            const data = jsonCodec.decode(msg.data);
+            await handler(data);
+            msg.ack();
+          } catch (err) {
+            console.error(
+              `[cooper] Subscriber "${subName}" on topic "${name}" failed:`,
+              err
+            );
+            // NAK with delay for retry (5 second backoff)
+            msg.nak(5000);
+          }
+        }
+      } catch (err: any) {
+        // Consumer iteration ended (connection closed, etc.)
+        activeConsumers.delete(subName);
+        if (!err.message?.includes("closed")) {
+          console.error(
+            `[cooper] Consumer "${subName}" on topic "${name}" stopped:`,
+            err
+          );
+        }
+      }
+    })();
+  }
+
+  const t: Topic<T> = {
+    async publish(data: T) {
+      const connected = await ensureConnected();
+
+      if (connected) {
+        const js = getJetStream();
+        if (js) {
+          await ensureStream(name, { dedup: useDedup });
+
+          const headers =
+            useDedup && data && typeof data === "object"
+              ? createDedup(data as any, config?.orderBy)
+              : undefined;
+
+          await js.publish(subject, jsonCodec.encode(data), { headers });
+          return;
+        }
+      }
+
+      // Fallback: in-memory delivery
+      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,
+      });
+
+      // Start JetStream consumer in the background
+      const concurrency = subConfig.concurrency ?? 1;
+      ensureConnected().then(async (connected) => {
+        if (connected) {
+          await ensureStream(name, { dedup: useDedup });
+          startConsumer(subName, subConfig.handler, concurrency).catch(
+            (err) => {
+              console.error(
+                `[cooper] Failed to start consumer "${subName}":`,
+                err
+              );
+            }
+          );
+        }
+      });
+
+      return {
+        _cooper_type: "subscription",
+        topic: name,
+        name: subName,
+      };
+    },
+  };
+
+  registry.registerTopic(name, { name, subscribers });
+
+  return t;
+}
+
+/**
+ * Create NATS headers for exactly-once dedup.
+ * Uses Nats-Msg-Id header — JetStream deduplicates within the stream's
+ * duplicate_window based on this ID.
+ */
+function createDedup(
+  data: Record<string, any>,
+  orderBy?: string
+): any {
+  const h = natsHeaders();
+
+  // Generate a deterministic dedup ID.
+  // If an ordering key is set, use that field's value as the dedup key.
+  // Otherwise, hash the entire payload for content-based dedup.
+  if (orderBy && data[orderBy] !== undefined) {
+    h.set("Nats-Msg-Id", `${orderBy}-${String(data[orderBy])}`);
+  } else {
+    const payload = JSON.stringify(data);
+    let hash = 0;
+    for (let i = 0; i < payload.length; i++) {
+      hash = ((hash << 5) - hash + payload.charCodeAt(i)) | 0;
+    }
+    h.set("Nats-Msg-Id", `msg-${Math.abs(hash)}`);
+  }
+
+  return h;
+}

package/src/queue.ts

@@ -0,0 +1,414 @@
+import { registry } from "./registry.js";
+import {
+  ensureConnected,
+  getJetStream,
+  getJetStreamManager,
+  jsonCodec,
+  consumerName,
+  ensureQueueStream,
+  ensureDLQStream,
+} from "./nats.js";
+import { headers as natsHeaders, AckPolicy } from "nats";
+
+export interface QueueConfig {
+  concurrency?: number;
+  retries?: number;
+  retryDelay?: "fixed" | "exponential";
+  timeout?: string;
+  deadLetter?: string;
+}
+
+export interface EnqueueOptions {
+  delay?: string;
+  priority?: "low" | "normal" | "high";
+  dedupeKey?: string;
+}
+
+export interface QueueClient<T> {
+  enqueue(data: T, opts?: EnqueueOptions): Promise<void>;
+  worker(
+    name: string,
+    config: {
+      handler: (data: T) => Promise<void>;
+      onFailure?: (data: T, error: Error) => Promise<void>;
+    }
+  ): any;
+  list(): Promise<{ id: string; data: T }[]>;
+  delete(id: string): Promise<void>;
+}
+
+const parseDuration = (dur: string): number => {
+  const m = dur.match(/^(\d+)(s|m|h|d)$/);
+  if (!m) return 0;
+  const mult: Record<string, number> = {
+    s: 1000,
+    m: 60000,
+    h: 3600000,
+    d: 86400000,
+  };
+  return parseInt(m[1]) * (mult[m[2]] ?? 1000);
+};
+
+/**
+ * Declare a job queue.
+ *
+ * ```ts
+ * export const EmailQueue = queue<{ to: string; subject: string; body: string }>(
+ *   "email-queue",
+ *   { concurrency: 10, retries: 3, retryDelay: "exponential", timeout: "30s", deadLetter: "email-dlq" }
+ * );
+ * ```
+ *
+ * Local dev uses NATS JetStream for persistent, durable queues.
+ * Falls back to in-memory if NATS is unavailable.
+ */
+export function queue<T = any>(
+  name: string,
+  config?: QueueConfig
+): QueueClient<T> {
+  const subject = `cooper.queue.${name}`;
+  const concurrency = config?.concurrency ?? 1;
+  const maxRetries = config?.retries ?? 0;
+  const timeoutMs = config?.timeout ? parseDuration(config.timeout) : 0;
+  const dlqName = config?.deadLetter;
+
+  // In-memory fallback state
+  const memJobs: {
+    id: string;
+    data: T;
+    attempts: number;
+    priority: string;
+    scheduledAt: number;
+  }[] = [];
+  let memProcessing = false;
+  let workerHandler: ((data: T) => Promise<void>) | null = null;
+  let failureHandler: ((data: T, error: Error) => Promise<void>) | null = null;
+  let consumerStarted = false;
+
+  // Track retry attempts per message (NATS redelivers original message on NAK)
+  const attemptTracker = new Map<number, number>();
+
+  // In-memory fallback processor
+  const processMemQueue = async () => {
+    if (memProcessing || !workerHandler) return;
+    memProcessing = true;
+
+    while (memJobs.length > 0) {
+      const batch = memJobs.splice(0, concurrency);
+      await Promise.allSettled(
+        batch.map(async (job) => {
+          if (job.scheduledAt > Date.now()) {
+            memJobs.push(job);
+            return;
+          }
+          try {
+            await executeWithTimeout(workerHandler!, job.data);
+          } catch (err) {
+            job.attempts++;
+            if (job.attempts <= maxRetries) {
+              const delay =
+                config?.retryDelay === "exponential"
+                  ? Math.pow(2, job.attempts - 1) * 1000
+                  : 1000;
+              job.scheduledAt = Date.now() + delay;
+              memJobs.push(job);
+            } else if (failureHandler) {
+              await failureHandler(job.data, err as Error);
+            }
+          }
+        })
+      );
+    }
+
+    memProcessing = false;
+  };
+
+  async function executeWithTimeout(
+    handler: (data: T) => Promise<void>,
+    data: T
+  ): Promise<void> {
+    if (!timeoutMs) {
+      return handler(data);
+    }
+    const result = await Promise.race([
+      handler(data),
+      new Promise<never>((_, reject) =>
+        setTimeout(
+          () => reject(new Error(`Job timed out after ${config!.timeout}`)),
+          timeoutMs
+        )
+      ),
+    ]);
+    return result;
+  }
+
+  /**
+   * Start a JetStream consumer to process queue jobs.
+   */
+  async function startConsumer(
+    workerName: string,
+    handler: (data: T) => Promise<void>,
+    onFailure?: (data: T, error: Error) => Promise<void>
+  ): Promise<void> {
+    if (consumerStarted) return;
+    consumerStarted = true;
+
+    const js = getJetStream();
+    const jsm = getJetStreamManager();
+    if (!js || !jsm) return;
+
+    const streamName =
+      "QUEUE_" + name.replace(/[^a-zA-Z0-9_-]/g, "_").toUpperCase();
+    const durable = consumerName(workerName);
+
+    // Ensure consumer exists
+    try {
+      await jsm.consumers.info(streamName, durable);
+    } catch {
+      await jsm.consumers.add(streamName, {
+        durable_name: durable,
+        ack_policy: AckPolicy.Explicit,
+        max_ack_pending: concurrency,
+        filter_subject: subject,
+        // Redeliver unacked messages after ack_wait
+        ack_wait: 30 * 1_000_000_000, // 30 seconds in nanos
+      });
+    }
+
+    const consumer = await js.consumers.get(streamName, durable);
+
+    // Process jobs in the background
+    (async () => {
+      try {
+        const messages = await consumer.consume();
+        for await (const msg of messages) {
+          let jobData: T;
+          try {
+            jobData = jsonCodec.decode(msg.data) as T;
+          } catch {
+            // Malformed message — ack to remove from queue
+            msg.ack();
+            continue;
+          }
+
+          // Track retries using sequence number — msg.seq is the stream seq
+          const seq = msg.seq;
+          const attempts = attemptTracker.get(seq) ?? 0;
+
+          try {
+            await executeWithTimeout(handler, jobData);
+            msg.ack();
+            attemptTracker.delete(seq);
+          } catch (err) {
+            const nextAttempt = attempts + 1;
+            attemptTracker.set(seq, nextAttempt);
+
+            if (nextAttempt <= maxRetries) {
+              // NAK with backoff delay for retry
+              const delay =
+                config?.retryDelay === "exponential"
+                  ? Math.pow(2, nextAttempt - 1) * 1000
+                  : 1000;
+              msg.nak(delay);
+            } else {
+              // Max retries exceeded — move to DLQ if configured
+              if (dlqName) {
+                try {
+                  await moveToDLQ(dlqName, name, jobData, err as Error);
+                } catch (dlqErr) {
+                  console.error(
+                    `[cooper] Failed to move job to DLQ "${dlqName}":`,
+                    dlqErr
+                  );
+                }
+              }
+
+              if (onFailure) {
+                try {
+                  await onFailure(jobData, err as Error);
+                } catch (failErr) {
+                  console.error(
+                    `[cooper] onFailure handler for queue "${name}" threw:`,
+                    failErr
+                  );
+                }
+              }
+
+              // Ack to remove from main queue (it's in DLQ now)
+              msg.ack();
+              attemptTracker.delete(seq);
+            }
+          }
+        }
+      } catch (err: any) {
+        consumerStarted = false;
+        if (!err.message?.includes("closed")) {
+          console.error(
+            `[cooper] Queue consumer "${name}" stopped:`,
+            err
+          );
+        }
+      }
+    })();
+  }
+
+  const client: QueueClient<T> = {
+    async enqueue(data: T, opts?: EnqueueOptions) {
+      const connected = await ensureConnected();
+
+      if (connected) {
+        const js = getJetStream();
+        if (js) {
+          await ensureQueueStream(name, { dedup: !!opts?.dedupeKey });
+
+          const h = natsHeaders();
+
+          // Dedup key
+          if (opts?.dedupeKey) {
+            h.set("Nats-Msg-Id", opts.dedupeKey);
+          }
+
+          // Priority as header (for visibility — JetStream doesn't natively prioritize)
+          if (opts?.priority && opts.priority !== "normal") {
+            h.set("Cooper-Priority", opts.priority);
+          }
+
+          // Initial attempt count
+          h.set("Cooper-Attempts", "0");
+
+          if (opts?.delay) {
+            // For delayed jobs: JetStream doesn't have native delay.
+            // We publish immediately but set a header; consumer-side can
+            // NAK with delay or we use a timer.
+            const delayMs = parseDuration(opts.delay);
+            h.set("Cooper-Delay-Until", String(Date.now() + delayMs));
+          }
+
+          await js.publish(subject, jsonCodec.encode(data), { headers: h });
+          return;
+        }
+      }
+
+      // Fallback: in-memory
+      const delay = opts?.delay ? parseDuration(opts.delay) : 0;
+      memJobs.push({
+        id: crypto.randomUUID(),
+        data,
+        attempts: 0,
+        priority: opts?.priority ?? "normal",
+        scheduledAt: Date.now() + delay,
+      });
+
+      const priorityOrder: Record<string, number> = {
+        high: 0,
+        normal: 1,
+        low: 2,
+      };
+      memJobs.sort(
+        (a, b) =>
+          (priorityOrder[a.priority] ?? 1) - (priorityOrder[b.priority] ?? 1)
+      );
+
+      setImmediate(() => processMemQueue());
+    },
+
+    worker(workerName: string, workerConfig) {
+      workerHandler = workerConfig.handler;
+      failureHandler = workerConfig.onFailure ?? null;
+
+      registry.registerQueue(name, {
+        name,
+        options: config ?? {},
+        worker: {
+          name: workerName,
+          handler: workerConfig.handler,
+          onFailure: workerConfig.onFailure,
+        },
+      });
+
+      // Start JetStream consumer
+      ensureConnected().then(async (connected) => {
+        if (connected) {
+          await ensureQueueStream(name);
+          if (dlqName) await ensureDLQStream(dlqName);
+          startConsumer(
+            workerName,
+            workerConfig.handler,
+            workerConfig.onFailure
+          ).catch((err) => {
+            console.error(
+              `[cooper] Failed to start queue consumer "${name}":`,
+              err
+            );
+          });
+        }
+      });
+
+      // Kick in-memory fallback processing
+      setImmediate(() => processMemQueue());
+
+      return { _cooper_type: "queue_worker", queue: name, name: workerName };
+    },
+
+    async list() {
+      const connected = await ensureConnected();
+
+      if (connected) {
+        const jsm = getJetStreamManager();
+        if (jsm) {
+          const streamName =
+            "QUEUE_" + name.replace(/[^a-zA-Z0-9_-]/g, "_").toUpperCase();
+          try {
+            const info = await jsm.streams.info(streamName);
+            // Return stream message count as approximation
+            // JetStream doesn't support listing individual messages directly
+            return Array.from(
+              { length: Number(info.state.messages) },
+              (_, i) => ({
+                id: `js-${i}`,
+                data: {} as T,
+              })
+            );
+          } catch {
+            return [];
+          }
+        }
+      }
+
+      return memJobs.map((j) => ({ id: j.id, data: j.data }));
+    },
+
+    async delete(id: string) {
+      // In-memory fallback
+      const idx = memJobs.findIndex((j) => j.id === id);
+      if (idx >= 0) memJobs.splice(idx, 1);
+    },
+  };
+
+  registry.registerQueue(name, { name, options: config ?? {} });
+
+  return client;
+}
+
+/**
+ * Move a failed job to the dead-letter queue.
+ */
+async function moveToDLQ<T>(
+  dlqName: string,
+  sourceQueue: string,
+  data: T,
+  error: Error
+): Promise<void> {
+  const js = getJetStream();
+  if (!js) return;
+
+  await ensureDLQStream(dlqName);
+
+  const dlqSubject = `cooper.dlq.${dlqName}`;
+  const h = natsHeaders();
+  h.set("Cooper-Source-Queue", sourceQueue);
+  h.set("Cooper-Error", error.message.slice(0, 256));
+  h.set("Cooper-Failed-At", new Date().toISOString());
+
+  await js.publish(dlqSubject, jsonCodec.encode(data), { headers: h });
+}

package/src/rateLimit.ts

@@ -0,0 +1,89 @@
+import { CooperError } from "./error.js";
+import type { MiddlewareFn } from "./registry.js";
+
+export interface RateLimitConfig {
+  /** Time window — e.g. "1m", "10s", "1h" */
+  window: string;
+  /** Max requests allowed within the window */
+  max: number;
+  /** Function to derive the rate limit key from the request. Defaults to IP address. */
+  key?: (req: any) => string;
+}
+
+function parseTTL(ttl: string): number {
+  const match = ttl.match(/^(\d+)(s|m|h|d)$/);
+  if (!match) return 60;
+  const [, num, unit] = match;
+  const multipliers: Record<string, number> = { s: 1, m: 60, h: 3600, d: 86400 };
+  return parseInt(num) * (multipliers[unit] ?? 60);
+}
+
+function parseWindowMs(window: string): number {
+  return parseTTL(window) * 1000;
+}
+
+let redis: any = null;
+
+async function ensureRedis(): Promise<any> {
+  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;
+}
+
+/**
+ * Create a rate limiting middleware.
+ *
+ * Can be used globally:
+ * ```ts
+ * cooper.use(rateLimit({ window: "1m", max: 100 }));
+ * ```
+ *
+ * Or per-route via middleware config:
+ * ```ts
+ * export default api({
+ *   method: "POST",
+ *   path: "/api/login",
+ *   middleware: [rateLimit({ window: "1m", max: 5 })],
+ *   handler: async (input) => { ... }
+ * });
+ * ```
+ */
+export function rateLimit(config: RateLimitConfig): MiddlewareFn {
+  const { window, max, key: keyFn } = config;
+  const ttlSec = parseTTL(window);
+  const windowMs = parseWindowMs(window);
+
+  return async (req: any, next: (req: any) => Promise<any>) => {
+    const identifier = keyFn ? keyFn(req) : (req.ip ?? "unknown");
+    const redisKey = `cooper:rl:${identifier}:${Math.floor(Date.now() / windowMs)}`;
+
+    const r = await ensureRedis();
+    const count = await r.incr(redisKey);
+
+    // Set TTL on first increment
+    if (count === 1) {
+      await r.expire(redisKey, ttlSec);
+    }
+
+    if (count > max) {
+      // Calculate retry-after in seconds
+      const ttl = await r.ttl(redisKey);
+      const retryAfter = ttl > 0 ? ttl : ttlSec;
+
+      const error = new CooperError("RATE_LIMITED", `Rate limit exceeded. Try again in ${retryAfter}s.`);
+      error.retryAfter = retryAfter;
+      throw error;
+    }
+
+    // Attach rate limit headers info to request for downstream use
+    req._rateLimit = {
+      limit: max,
+      remaining: max - count,
+      reset: Math.ceil(Date.now() / 1000) + ttlSec,
+    };
+
+    return next(req);
+  };
+}