hybridq 0.1.1

package/dist/server/index.d.ts

@@ -0,0 +1,463 @@
+/**
+ * Core type contracts for hybridq.
+ *
+ * These are intentionally dependency-free so they can be shared by the
+ * server bundle (queueing + execution) and stay tree-shakeable.
+ */
+/** Lifecycle states a job moves through inside the store. */
+type JobStatus = "pending" | "active" | "completed" | "failed" | "delayed";
+/**
+ * A unit of deferred work.
+ *
+ * `payload` is whatever the producer enqueued. When payload encryption is
+ * enabled the adapter stores a ciphertext envelope on disk/Redis and only
+ * decrypts back into `payload` when the engine claims the job.
+ */
+interface Job<TPayload = unknown> {
+    /** Globally unique id. Also used as the idempotency key when provided. */
+    id: string;
+    /** Logical queue/topic name. Lets one store host many independent queues. */
+    queue: string;
+    /** The work to perform. Decrypted in-memory; never logged. */
+    payload: TPayload;
+    /** Current lifecycle state. */
+    status: JobStatus;
+    /** How many times this job has been attempted (claimed). */
+    attempts: number;
+    /** Hard cap on attempts before the job is moved to `failed`. */
+    maxAttempts: number;
+    /** Epoch ms when the job becomes eligible to run (for delays/backoff). */
+    runAt: number;
+    /** Epoch ms when the job was first enqueued. */
+    createdAt: number;
+    /**
+     * Epoch ms when the current lease expires. While `status === "active"` and
+     * `now < leaseUntil`, no other trigger may claim this job. Once the lease
+     * lapses (e.g. the serverless function was killed mid-run) the job becomes
+     * reclaimable — this is what makes processing crash-safe.
+     */
+    leaseUntil?: number;
+    /** Last error message, recorded on failure for observability. */
+    lastError?: string;
+}
+/** The result the engine derives from each handler invocation. */
+type JobResult = {
+    status: "completed";
+} | {
+    status: "failed";
+    error: string;
+    retry?: boolean;
+};
+/**
+ * Storage Adapter contract.
+ *
+ * Implementations must be safe to construct per-request in stateless
+ * serverless environments. Every method takes the queue name so a single
+ * adapter instance can serve multiple queues.
+ *
+ * The claim/ack model is lease-based: `shiftBatch` atomically moves jobs to
+ * `active` with a lease; the engine must later `complete`, `fail`, or
+ * `release` each claimed job. Crashed runs simply let the lease expire.
+ */
+interface StorageAdapter {
+    /** Append a job to the tail of its queue. */
+    push(job: Job): Promise<void>;
+    /**
+     * Atomically claim up to `count` eligible jobs (pending + runAt <= now, or
+     * active jobs whose lease has expired), mark them `active`, and stamp a
+     * lease of `leaseMs`. Returns the claimed jobs with decrypted payloads.
+     */
+    shiftBatch(queue: string, count: number, leaseMs: number): Promise<Job[]>;
+    /** Mark a claimed job done and remove it from the working set. */
+    complete(queue: string, jobId: string): Promise<void>;
+    /**
+     * Mark a claimed job as failed. If `retry` is true and attempts remain, the
+     * job is requeued as `pending` with `runAt = now + backoffMs`; otherwise it
+     * lands in `failed`.
+     */
+    fail(queue: string, jobId: string, error: string, retry: boolean, backoffMs: number): Promise<void>;
+    /**
+     * Release a still-leased job back to `pending` without consuming an attempt.
+     * Used when a budget is exhausted mid-run so unprocessed jobs return cleanly.
+     */
+    release(queue: string, jobId: string): Promise<void>;
+    /** Approximate number of pending (claimable) jobs — for triggers/metrics. */
+    size(queue: string): Promise<number>;
+}
+/**
+ * Self-limiting execution budget. Enforced on every trigger run so a single
+ * invocation can never exceed the platform's wall-clock or cost limits.
+ */
+interface BudgetConfig {
+    /** Hard cap on total jobs processed in one trigger run. */
+    maxJobsPerTrigger: number;
+    /**
+     * Wall-clock budget in ms. The loop stops *before* starting a new job once
+     * elapsed time would risk the platform timeout. Set comfortably under your
+     * function's limit (e.g. 8000 for a 10s Vercel function).
+     */
+    maxExecutionTimeMs: number;
+    /**
+     * Optional soft ceiling on estimated CPU utilisation (0-100). Best-effort:
+     * derived from event-loop/CPU sampling where available, ignored otherwise.
+     */
+    maxCpuBudgetPct?: number;
+}
+/** A single job handler. Throwing is treated as a retryable failure. */
+type JobHandler<TPayload = unknown> = (job: Job<TPayload>) => Promise<void> | void;
+/** Outcome summary returned to the trigger caller. */
+interface DrainReport {
+    /** Jobs that completed successfully. */
+    processed: number;
+    /** Jobs that errored this run (may still retry later). */
+    failed: number;
+    /** Jobs released unprocessed because a budget was hit. */
+    released: number;
+    /** Why the loop stopped. */
+    stoppedBy: "drained" | "jobCap" | "timeBudget" | "cpuBudget" | "lockBusy";
+    /** Total wall-clock spent in the loop. */
+    elapsedMs: number;
+}
+
+/**
+ * Optional payload-at-rest encryption. When a secret is configured, payloads
+ * are sealed with AES-256-GCM before they ever touch the store, so sensitive
+ * data (emails, tokens) is never plaintext in Redis.
+ */
+interface PayloadCipher {
+    encrypt(plaintext: string): string;
+    decrypt(envelope: string): string;
+}
+/**
+ * Build a cipher from a secret. Returns `null` when no secret is supplied so
+ * callers can transparently no-op (store plaintext) in dev.
+ */
+declare function createPayloadCipher(secret?: string): PayloadCipher | null;
+/**
+ * HMAC trigger tokens. A trigger presents `t=<ts>,v=<sig>` where
+ * sig = HMAC-SHA256(secret, `${ts}.${path}`). Tokens expire to blunt replay.
+ */
+declare function signTrigger(secret: string, path: string, ts?: number): string;
+declare function verifyTrigger(secret: string, path: string, token: string, maxSkewMs?: number): boolean;
+
+/**
+ * In-memory storage adapter.
+ *
+ * For local dev and tests only — state lives in the process, so it does NOT
+ * survive across serverless invocations. The locking/lease semantics mirror
+ * the Redis adapter so handler code behaves identically in both.
+ */
+
+interface MemoryAdapterOptions {
+    /** Optional cipher to encrypt payloads at rest, matching prod behaviour. */
+    cipher?: PayloadCipher | null;
+}
+declare class MemoryAdapter implements StorageAdapter {
+    private readonly queues;
+    private readonly cipher;
+    constructor(opts?: MemoryAdapterOptions);
+    private bucket;
+    private seal;
+    private open;
+    push(job: Job): Promise<void>;
+    shiftBatch(queue: string, count: number, leaseMs: number): Promise<Job[]>;
+    complete(queue: string, jobId: string): Promise<void>;
+    fail(queue: string, jobId: string, error: string, retry: boolean, backoffMs: number): Promise<void>;
+    release(queue: string, jobId: string): Promise<void>;
+    size(queue: string): Promise<number>;
+}
+
+/**
+ * Serverless-optimized Redis storage adapter.
+ *
+ * Works with either:
+ *   - `@upstash/redis` (HTTP/fetch — ideal for edge & connectionless runtimes)
+ *   - `ioredis`        (TCP — uses a module-level singleton so we don't open a
+ *                       new socket on every cold-ish invocation)
+ *
+ * Both clients differ in their `eval` signature, so we normalize them behind a
+ * tiny `RedisDriver` and do all the claim logic in a single atomic Lua script.
+ *
+ * Data model (per queue `q`):
+ *   hq:{q}:pending  LIST  — ids waiting to be claimed, FIFO
+ *   hq:{q}:delayed  ZSET  — id -> runAt (promoted to pending when due)
+ *   hq:{q}:active   ZSET  — id -> leaseUntil (reclaimed when the lease lapses)
+ *   hq:{q}:jobs     HASH  — id -> envelope JSON (see JobEnvelope)
+ *
+ * The user payload is stored as an opaque string field (`payloadJson`) so the
+ * server-side Lua `cjson` round-trip can never mangle nested structures.
+ */
+
+/** Minimal normalized Redis surface the adapter needs. */
+interface RedisDriver {
+    eval(script: string, keys: string[], args: (string | number)[]): Promise<unknown>;
+    hget(key: string, field: string): Promise<string | null>;
+    hset(key: string, field: string, value: string): Promise<unknown>;
+    hdel(key: string, field: string): Promise<unknown>;
+    rpush(key: string, value: string): Promise<unknown>;
+    zadd(key: string, score: number, member: string): Promise<unknown>;
+    zrem(key: string, member: string): Promise<unknown>;
+    llen(key: string): Promise<number>;
+}
+interface RedisAdapterOptions {
+    /** Optional namespace prefix (default "hq"). Lets you isolate apps/envs. */
+    namespace?: string;
+    /** Optional cipher for payload-at-rest encryption. */
+    cipher?: PayloadCipher | null;
+}
+declare class RedisAdapter implements StorageAdapter {
+    private readonly redis;
+    private readonly ns;
+    private readonly cipher;
+    constructor(redis: RedisDriver, opts?: RedisAdapterOptions);
+    private k;
+    private toEnvelope;
+    private fromEnvelope;
+    push(job: Job): Promise<void>;
+    shiftBatch(queue: string, count: number, leaseMs: number): Promise<Job[]>;
+    complete(queue: string, jobId: string): Promise<void>;
+    fail(queue: string, jobId: string, error: string, retry: boolean, backoffMs: number): Promise<void>;
+    release(queue: string, jobId: string): Promise<void>;
+    size(queue: string): Promise<number>;
+}
+/**
+ * Wrap an `@upstash/redis` client. Connectionless (HTTP), so it's safe to
+ * construct per request — no pooling needed.
+ */
+declare function fromUpstash(client: {
+    eval: (script: string, keys: string[], args: unknown[]) => Promise<unknown>;
+    hget: (k: string, f: string) => Promise<string | null>;
+    hset: (k: string, v: Record<string, string>) => Promise<unknown>;
+    hdel: (k: string, f: string) => Promise<unknown>;
+    rpush: (k: string, ...v: string[]) => Promise<unknown>;
+    zadd: (k: string, m: {
+        score: number;
+        member: string;
+    }) => Promise<unknown>;
+    zrem: (k: string, m: string) => Promise<unknown>;
+    llen: (k: string) => Promise<number>;
+}): RedisDriver;
+/**
+ * Wrap an `ioredis` client. ioredis opens a real TCP socket, so callers should
+ * reuse ONE client across invocations — see `getSharedIORedis` below.
+ */
+declare function fromIORedis(client: {
+    eval: (script: string, numKeys: number, ...rest: (string | number)[]) => Promise<unknown>;
+    hget: (k: string, f: string) => Promise<string | null>;
+    hset: (k: string, f: string, v: string) => Promise<unknown>;
+    hdel: (k: string, f: string) => Promise<unknown>;
+    rpush: (k: string, v: string) => Promise<unknown>;
+    zadd: (k: string, score: number, member: string) => Promise<unknown>;
+    zrem: (k: string, m: string) => Promise<unknown>;
+    llen: (k: string) => Promise<number>;
+}): RedisDriver;
+/**
+ * Connection-pool-safe ioredis singleton for serverless. Stashes the client on
+ * `globalThis` so warm invocations reuse the same socket instead of exhausting
+ * Redis connections under load.
+ */
+declare function getSharedIORedis(factory: () => RedisDriver, key?: string): RedisDriver;
+
+/**
+ * Distributed lock used to guarantee single-flight processing.
+ *
+ * When several inbound requests fire a trigger at the same instant we don't
+ * want N concurrent drain loops fighting over the same jobs. Each run first
+ * tries to grab a short-TTL lock; losers exit immediately (the winner is
+ * already draining). The TTL is short and auto-expires, so a crashed run never
+ * wedges the queue.
+ */
+
+interface DistributedLock {
+    /** Try to acquire `key` for `ttlMs`. Returns a release token, or null. */
+    acquire(key: string, ttlMs: number): Promise<string | null>;
+    /** Release `key` only if we still own it (compare-and-delete). */
+    release(key: string, token: string): Promise<void>;
+}
+/** Redis-backed lock (SET NX PX + compare-and-delete). */
+declare class RedisLock implements DistributedLock {
+    private readonly redis;
+    constructor(redis: RedisDriver);
+    acquire(key: string, ttlMs: number): Promise<string | null>;
+    release(key: string, token: string): Promise<void>;
+}
+/** In-process lock for the MemoryAdapter / single-instance dev. */
+declare class MemoryLock implements DistributedLock {
+    private readonly held;
+    acquire(key: string, ttlMs: number): Promise<string | null>;
+    release(key: string, token: string): Promise<void>;
+}
+
+/**
+ * The processing engine.
+ *
+ * A trigger calls `drain()`. It claims jobs in batches and runs the handler,
+ * checking the budget *between every job*. The moment the time or job-count
+ * (or optional CPU) budget is exhausted it stops claiming, releases any jobs it
+ * grabbed-but-didn't-run back to the queue, and returns — guaranteeing the
+ * serverless function never blows past its wall-clock limit.
+ *
+ * Crash-safety comes from the lease model in the adapter: anything claimed but
+ * not completed/failed/released simply becomes reclaimable once its lease
+ * lapses, so a killed function loses no work.
+ */
+
+interface DrainOptions<TPayload = unknown> {
+    queue: string;
+    adapter: StorageAdapter;
+    handler: JobHandler<TPayload>;
+    budget: BudgetConfig;
+    /** Optional single-flight lock so concurrent triggers don't double-drain. */
+    lock?: DistributedLock;
+    /** Jobs claimed per round trip to the store. Default 10. */
+    batchSize?: number;
+    /**
+     * Lease length for claimed jobs. Should exceed how long one job can take.
+     * Defaults to `maxExecutionTimeMs` so a whole run is covered by one lease.
+     */
+    leaseMs?: number;
+    /** Retry backoff in ms given the attempt number (1-based). */
+    backoff?: (attempt: number) => number;
+    /** Observability hook for handler errors. Never throws into the loop. */
+    onError?: (err: unknown, job: Job<TPayload>) => void;
+}
+declare function drain<TPayload = unknown>(opts: DrainOptions<TPayload>): Promise<DrainReport>;
+
+/**
+ * High-level Queue facade.
+ *
+ * Wires a storage adapter, optional lock, and the engine into an ergonomic
+ * producer/consumer surface:
+ *   - `enqueue()` from any API route to defer work.
+ *   - `process()` from a trigger to drain a budgeted batch.
+ */
+
+interface QueueConfig {
+    /** Logical queue name (a single store can host many). */
+    name: string;
+    /** Where jobs live. */
+    adapter: StorageAdapter;
+    /** Default execution budget; overridable per `process()` call. */
+    budget?: Partial<BudgetConfig>;
+    /** Single-flight lock to prevent concurrent drains double-processing. */
+    lock?: DistributedLock;
+    /** Default retry ceiling for enqueued jobs. Default 3. */
+    defaultMaxAttempts?: number;
+    /** Jobs claimed per round trip while draining. Default 10. */
+    batchSize?: number;
+    /** Retry backoff in ms for attempt N (1-based). */
+    backoff?: (attempt: number) => number;
+}
+interface EnqueueOptions {
+    /** Delay before the job becomes eligible to run. */
+    delayMs?: number;
+    /** Override retry ceiling for this job. */
+    maxAttempts?: number;
+    /**
+     * Stable id → idempotency key. Re-enqueuing with the same id is a no-op at
+     * the application layer (callers should treat enqueue as best-effort unique).
+     */
+    id?: string;
+}
+declare class Queue<TPayload = unknown> {
+    private readonly config;
+    private readonly budget;
+    constructor(config: QueueConfig);
+    get name(): string;
+    /** Producer side: push a unit of work. Returns the created job. */
+    enqueue(payload: TPayload, opts?: EnqueueOptions): Promise<Job<TPayload>>;
+    /** How many jobs are currently claimable. Handy for trigger gating. */
+    size(): Promise<number>;
+    /**
+     * Consumer side: drain a budgeted batch with the given handler. Safe to call
+     * from many concurrent requests — the lock ensures only one actually runs.
+     */
+    process(handler: JobHandler<TPayload>, budgetOverride?: Partial<BudgetConfig>): Promise<DrainReport>;
+}
+/** Convenience factory. */
+declare function defineQueue<TPayload = unknown>(config: QueueConfig): Queue<TPayload>;
+
+/**
+ * Hybrid trigger middleware.
+ *
+ * Two ways to kick off a drain without a dedicated worker daemon:
+ *
+ *  1. `withTrigger(handler)` — wraps a normal API route / webhook. It runs your
+ *     real handler, returns the response immediately, and drains the queue
+ *     *after* the response is flushed using the platform's "keep the function
+ *     alive a bit longer" primitive (`waitUntil`). Inbound traffic = free CPU.
+ *
+ *  2. `createTriggerEndpoint(...)` — a dedicated, authenticated endpoint that
+ *     client pings (see ../client/trigger) or a cron hits to force a drain.
+ *
+ * Both verify a shared secret (X-Worker-Trigger-Secret) or an HMAC token so a
+ * stranger can't pound the endpoint and turn your worker into a money pit.
+ */
+
+/** Anything with `waitUntil` — Vercel/Cloudflare give you one per request. */
+interface ExecutionContextLike {
+    waitUntil(promise: Promise<unknown>): void;
+}
+declare const TRIGGER_SECRET_HEADER = "x-worker-trigger-secret";
+declare const TRIGGER_TOKEN_HEADER = "x-worker-trigger-token";
+interface TriggerAuthConfig {
+    /** Pre-shared secret compared in constant time against the header. */
+    secret?: string;
+    /** HMAC secret enabling short-lived signed tokens (replay-resistant). */
+    hmacSecret?: string;
+    /** Path bound into the HMAC signature. Default the request pathname. */
+    path?: string;
+}
+/**
+ * Verify a trigger request. Accepts EITHER a valid pre-shared secret header OR
+ * a valid HMAC token. Returns true only when at least one configured method
+ * passes — so an endpoint with no auth configured always rejects.
+ */
+declare function authorizeTrigger(req: Request, auth: TriggerAuthConfig): boolean;
+interface WithTriggerOptions<TPayload> {
+    queue: Queue<TPayload>;
+    handler: JobHandler<TPayload>;
+    /** Platform execution context exposing `waitUntil`. */
+    ctx?: ExecutionContextLike;
+    /** Optional per-trigger budget override. */
+    budget?: Partial<BudgetConfig>;
+    /** Skip draining when the queue is empty to avoid pointless work. */
+    skipIfEmpty?: boolean;
+}
+/**
+ * Wrap a normal request handler so each inbound request opportunistically
+ * drains the queue *after* responding. This is the core "hybrid trigger".
+ *
+ * @example
+ * export const POST = withTrigger(
+ *   async (req) => Response.json({ ok: true }),
+ *   { queue, handler: sendEmail, ctx },
+ * );
+ */
+declare function withTrigger<TPayload>(route: (req: Request) => Promise<Response> | Response, opts: WithTriggerOptions<TPayload>): (req: Request) => Promise<Response>;
+interface TriggerEndpointOptions<TPayload> {
+    queue: Queue<TPayload>;
+    handler: JobHandler<TPayload>;
+    auth: TriggerAuthConfig;
+    ctx?: ExecutionContextLike;
+    budget?: Partial<BudgetConfig>;
+    /**
+     * When true (default) the drain runs in the background via waitUntil and the
+     * endpoint returns 202 immediately. Set false to await the drain and return
+     * the full report (useful for cron jobs that want the result).
+     */
+    background?: boolean;
+}
+/**
+ * Build a standalone authenticated trigger endpoint (Fetch-API style). Mount it
+ * at e.g. `app/api/_worker/route.ts` and point client pings / cron at it.
+ */
+declare function createTriggerEndpoint<TPayload>(opts: TriggerEndpointOptions<TPayload>): (req: Request) => Promise<Response>;
+
+/**
+ * Small id helper. Prefers crypto.randomUUID where present (Node 18+ and all
+ * serverless edge runtimes), with a cheap fallback for exotic environments.
+ */
+declare function newId(prefix?: string): string;
+
+export { type BudgetConfig, type DistributedLock, type DrainOptions, type DrainReport, type EnqueueOptions, type ExecutionContextLike, type Job, type JobHandler, type JobResult, type JobStatus, MemoryAdapter, type MemoryAdapterOptions, MemoryLock, type PayloadCipher, Queue, type QueueConfig, RedisAdapter, type RedisAdapterOptions, type RedisDriver, RedisLock, type StorageAdapter, TRIGGER_SECRET_HEADER, TRIGGER_TOKEN_HEADER, type TriggerAuthConfig, type TriggerEndpointOptions, type WithTriggerOptions, authorizeTrigger, createPayloadCipher, createTriggerEndpoint, defineQueue, drain, fromIORedis, fromUpstash, getSharedIORedis, newId, signTrigger, verifyTrigger, withTrigger };