@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/lib/app/services/jobs/defineJob.d.ts

@@ -0,0 +1,81 @@
+import type { Job, JobsOptions } from "bullmq";
+import type { LifecycleHookContext } from "../../services/hooks/LifecycleHooks.js";
+/**
+ * `defineJob({ queue, name, handler, options?, schedule? })` — declarative
+ * background-job definition that auto-registers into the framework
+ * `jobRegistry`.
+ *
+ * Replaces v3's ad-hoc job patterns. Each job lives in
+ * `modules/<name>/jobs/<jobName>.job.ts` (convention) and default-exports
+ * its definition. The framework's eventual InitJobs bootstrapper walks
+ * the module tree, registers every defined job, and starts BullMQ workers
+ * for each unique queue when `WORKER_MODE` includes worker.
+ *
+ * Type safety: the optional generic `TPayload` flows from `defineJob`
+ * through `enqueue(queue, name, payload)` to the handler — agents and
+ * humans alike get IDE feedback on payload shape.
+ *
+ * Schedule: `schedule: { cron: '0 * * * *' }` registers a BullMQ
+ * repeatable job at workers-startup time. The framework `defineCron(...)`
+ * helper (next batch) is a thin wrapper over this with cron-specific
+ * ergonomics.
+ */
+export interface JobHandlerContext {
+    /** The underlying BullMQ Job for advanced needs (logger, progress, etc.). */
+    job: Job;
+    /** Per-run framework context; mirrors the HTTP RequestContext shape so
+     *  lifecycle hooks behave the same in jobs as in requests. */
+    context: LifecycleHookContext;
+}
+export type JobHandler<TPayload = unknown, TResult = unknown> = (payload: TPayload, ctx: JobHandlerContext) => Promise<TResult> | TResult;
+export interface JobDefinitionOptions {
+    /** BullMQ JobsOptions (attempts, backoff, priority, etc.) applied at enqueue time. */
+    defaultJobOptions?: JobsOptions;
+    /**
+     * Repeatable schedule (cron expression). When set, the framework
+     * registers a BullMQ repeatable job alongside the handler at worker
+     * startup. Use `defineCron(...)` for the more ergonomic shortcut.
+     */
+    schedule?: {
+        cron: string;
+        tz?: string;
+    };
+    /** Worker-side concurrency for this queue. Default 1. */
+    concurrency?: number;
+}
+export interface JobDefinition<TPayload = unknown, TResult = unknown> {
+    /** Queue name. Multiple jobs can share a queue; the worker dispatches by `name`. */
+    readonly queue: string;
+    /** Job name within the queue. Unique per-queue. */
+    readonly name: string;
+    readonly handler: JobHandler<TPayload, TResult>;
+    readonly options?: JobDefinitionOptions;
+}
+/**
+ * Define a job. Auto-registers into the framework `jobRegistry` (via
+ * the `register` argument's default). For tests / standalone usage, pass
+ * a custom registry to keep state isolated.
+ */
+export declare function defineJob<TPayload = unknown, TResult = unknown>(def: JobDefinition<TPayload, TResult>, register?: {
+    add: (def: JobDefinition) => void;
+} | false): JobDefinition<TPayload, TResult>;
+/**
+ * In-memory registry of every `defineJob`-declared definition. Populated
+ * at module-load time when the framework imports the module's job files;
+ * read at worker startup to wire BullMQ Workers.
+ */
+export declare class JobRegistry {
+    private jobs;
+    add(def: JobDefinition): void;
+    list(): readonly JobDefinition[];
+    /** All job definitions for one queue. */
+    byQueue(queue: string): JobDefinition[];
+    /** Distinct queue names across all registered jobs. */
+    queues(): string[];
+    find(queue: string, name: string): JobDefinition | undefined;
+    size(): number;
+    clear(): void;
+}
+/** Framework-wide registry. */
+export declare const jobRegistry: JobRegistry;
+//# sourceMappingURL=defineJob.d.ts.map

package/lib/app/services/jobs/defineJob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineJob.d.ts","sourceRoot":"","sources":["../../../../src/app/services/jobs/defineJob.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC/C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AAEnF;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,iBAAiB;IAChC,6EAA6E;IAC7E,GAAG,EAAE,GAAG,CAAC;IACT;kEAC8D;IAC9D,OAAO,EAAE,oBAAoB,CAAC;CAC/B;AAED,MAAM,MAAM,UAAU,CAAC,QAAQ,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,CAC9D,OAAO,EAAE,QAAQ,EACjB,GAAG,EAAE,iBAAiB,KACnB,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;AAEhC,MAAM,WAAW,oBAAoB;IACnC,sFAAsF;IACtF,iBAAiB,CAAC,EAAE,WAAW,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa,CAAC,QAAQ,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAClE,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAChD,QAAQ,CAAC,OAAO,CAAC,EAAE,oBAAoB,CAAC;CACzC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,QAAQ,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAC7D,GAAG,EAAE,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC,EACrC,QAAQ,GAAE;IAAE,GAAG,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,CAAA;CAAE,GAAG,KAAmB,GACpE,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC,CAKlC;AAED;;;;GAIG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,IAAI,CAAuB;IAEnC,GAAG,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI;IAQ7B,IAAI,IAAI,SAAS,aAAa,EAAE;IAIhC,yCAAyC;IACzC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,EAAE;IAIvC,uDAAuD;IACvD,MAAM,IAAI,MAAM,EAAE;IAIlB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAI5D,IAAI,IAAI,MAAM;IAId,KAAK,IAAI,IAAI;CAGd;AAED,+BAA+B;AAC/B,eAAO,MAAM,WAAW,aAAoB,CAAC"}

package/lib/app/services/jobs/defineJob.js

@@ -0,0 +1,49 @@
+/**
+ * Define a job. Auto-registers into the framework `jobRegistry` (via
+ * the `register` argument's default). For tests / standalone usage, pass
+ * a custom registry to keep state isolated.
+ */
+export function defineJob(def, register = jobRegistry) {
+    if (register !== false) {
+        register.add(def);
+    }
+    return def;
+}
+/**
+ * In-memory registry of every `defineJob`-declared definition. Populated
+ * at module-load time when the framework imports the module's job files;
+ * read at worker startup to wire BullMQ Workers.
+ */
+export class JobRegistry {
+    jobs = [];
+    add(def) {
+        const dup = this.jobs.find((j) => j.queue === def.queue && j.name === def.name);
+        if (dup) {
+            throw new Error(`JobRegistry: duplicate job "${def.name}" in queue "${def.queue}"`);
+        }
+        this.jobs.push(def);
+    }
+    list() {
+        return [...this.jobs];
+    }
+    /** All job definitions for one queue. */
+    byQueue(queue) {
+        return this.jobs.filter((j) => j.queue === queue);
+    }
+    /** Distinct queue names across all registered jobs. */
+    queues() {
+        return [...new Set(this.jobs.map((j) => j.queue))];
+    }
+    find(queue, name) {
+        return this.jobs.find((j) => j.queue === queue && j.name === name);
+    }
+    size() {
+        return this.jobs.length;
+    }
+    clear() {
+        this.jobs = [];
+    }
+}
+/** Framework-wide registry. */
+export const jobRegistry = new JobRegistry();
+//# sourceMappingURL=defineJob.js.map

package/lib/app/services/jobs/defineJob.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineJob.js","sourceRoot":"","sources":["../../../../src/app/services/jobs/defineJob.ts"],"names":[],"mappings":"AA2DA;;;;GAIG;AACH,MAAM,UAAU,SAAS,CACvB,GAAqC,EACrC,WAA0D,WAAW;IAErE,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;QACvB,QAAQ,CAAC,GAAG,CAAC,GAA+B,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,WAAW;IACd,IAAI,GAAoB,EAAE,CAAC;IAEnC,GAAG,CAAC,GAAkB;QACpB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC;QAChF,IAAI,GAAG,EAAE,CAAC;YACR,MAAM,IAAI,KAAK,CAAC,+BAA+B,GAAG,CAAC,IAAI,eAAe,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC;QACtF,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtB,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAED,yCAAyC;IACzC,OAAO,CAAC,KAAa;QACnB,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;IACpD,CAAC;IAED,uDAAuD;IACvD,MAAM;QACJ,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,IAAI,CAAC,KAAa,EAAE,IAAY;QAC9B,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IACrE,CAAC;IAED,IAAI;QACF,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;IAC1B,CAAC;IAED,KAAK;QACH,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;IACjB,CAAC;CACF;AAED,+BAA+B;AAC/B,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC"}

package/lib/app/services/jobs/index.d.ts

@@ -0,0 +1,4 @@
+export { type BullBoardHandle, type BullBoardOptions, createBullBoardApp } from "./bullBoard.js";
+export { defineJob, type JobDefinition, type JobDefinitionOptions, type JobHandler, type JobHandlerContext, JobRegistry, jobRegistry, } from "./defineJob.js";
+export { JobsManager, type JobsManagerOptions, type WorkerMode } from "./JobsManager.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/app/services/jobs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/app/services/jobs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACjG,OAAO,EACL,SAAS,EACT,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,WAAW,EACX,WAAW,GACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/lib/app/services/jobs/index.js

@@ -0,0 +1,4 @@
+export { createBullBoardApp } from "./bullBoard.js";
+export { defineJob, JobRegistry, jobRegistry, } from "./defineJob.js";
+export { JobsManager } from "./JobsManager.js";
+//# sourceMappingURL=index.js.map

package/lib/app/services/jobs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/app/services/jobs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+C,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACjG,OAAO,EACL,SAAS,EAKT,WAAW,EACX,WAAW,GACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,WAAW,EAA4C,MAAM,kBAAkB,CAAC"}

package/lib/app/services/rateLimit/InMemorySlidingWindowBackend.d.ts

@@ -0,0 +1,23 @@
+import type { RateLimitBackend, RateLimitCheckArgs, RateLimitCheckResult } from "./RateLimitBackend.js";
+/**
+ * In-process sliding-window-log limiter. Stores the timestamp of every
+ * counted request in a per-key array; on each `check()` it drops entries
+ * older than the window, counts the remainder, and either appends + allows
+ * or returns denied.
+ *
+ * Single-process only — does NOT coordinate across instances. Use Redis
+ * for multi-instance deployments. Suitable for tests, single-process dev,
+ * and as a documented `onRedisUnavailable: 'allow'` fallback if a consumer
+ * accepts the per-instance ceiling.
+ *
+ * Memory bound: each bucket holds at most `max` timestamps. A periodic
+ * cleanup-on-write removes empty buckets so abandoned keys (no traffic
+ * for > windowMs) don't leak memory.
+ */
+export declare class InMemorySlidingWindowBackend implements RateLimitBackend {
+    private buckets;
+    check(args: RateLimitCheckArgs): Promise<RateLimitCheckResult>;
+    /** Test helper: wipe everything. */
+    clear(): void;
+}
+//# sourceMappingURL=InMemorySlidingWindowBackend.d.ts.map

package/lib/app/services/rateLimit/InMemorySlidingWindowBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemorySlidingWindowBackend.d.ts","sourceRoot":"","sources":["../../../../src/app/services/rateLimit/InMemorySlidingWindowBackend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACrB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;;GAcG;AACH,qBAAa,4BAA6B,YAAW,gBAAgB;IACnE,OAAO,CAAC,OAAO,CAA+B;IAExC,KAAK,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAiCpE,oCAAoC;IACpC,KAAK,IAAI,IAAI;CAGd"}

package/lib/app/services/rateLimit/InMemorySlidingWindowBackend.js

@@ -0,0 +1,51 @@
+/**
+ * In-process sliding-window-log limiter. Stores the timestamp of every
+ * counted request in a per-key array; on each `check()` it drops entries
+ * older than the window, counts the remainder, and either appends + allows
+ * or returns denied.
+ *
+ * Single-process only — does NOT coordinate across instances. Use Redis
+ * for multi-instance deployments. Suitable for tests, single-process dev,
+ * and as a documented `onRedisUnavailable: 'allow'` fallback if a consumer
+ * accepts the per-instance ceiling.
+ *
+ * Memory bound: each bucket holds at most `max` timestamps. A periodic
+ * cleanup-on-write removes empty buckets so abandoned keys (no traffic
+ * for > windowMs) don't leak memory.
+ */
+export class InMemorySlidingWindowBackend {
+    buckets = new Map();
+    async check(args) {
+        const { key, windowMs, max, now } = args;
+        const cutoff = now - windowMs;
+        let timestamps = this.buckets.get(key) ?? [];
+        // Drop entries older than the window
+        timestamps = timestamps.filter((t) => t > cutoff);
+        if (timestamps.length >= max) {
+            // Reset = oldest counted timestamp + window
+            const resetAtMs = (timestamps[0] ?? now) + windowMs;
+            this.buckets.set(key, timestamps);
+            return {
+                allowed: false,
+                used: timestamps.length,
+                limit: max,
+                resetAtMs,
+            };
+        }
+        timestamps.push(now);
+        this.buckets.set(key, timestamps);
+        // Reset of the (now-non-empty) window — based on the oldest entry
+        const resetAtMs = timestamps[0] + windowMs;
+        return {
+            allowed: true,
+            used: timestamps.length,
+            limit: max,
+            resetAtMs,
+        };
+    }
+    /** Test helper: wipe everything. */
+    clear() {
+        this.buckets.clear();
+    }
+}
+//# sourceMappingURL=InMemorySlidingWindowBackend.js.map

package/lib/app/services/rateLimit/InMemorySlidingWindowBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemorySlidingWindowBackend.js","sourceRoot":"","sources":["../../../../src/app/services/rateLimit/InMemorySlidingWindowBackend.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,4BAA4B;IAC/B,OAAO,GAAG,IAAI,GAAG,EAAoB,CAAC;IAE9C,KAAK,CAAC,KAAK,CAAC,IAAwB;QAClC,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QACzC,MAAM,MAAM,GAAG,GAAG,GAAG,QAAQ,CAAC;QAE9B,IAAI,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QAC7C,qCAAqC;QACrC,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;QAElD,IAAI,UAAU,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;YAC7B,4CAA4C;YAC5C,MAAM,SAAS,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,QAAQ,CAAC;YACpD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;YAClC,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,IAAI,EAAE,UAAU,CAAC,MAAM;gBACvB,KAAK,EAAE,GAAG;gBACV,SAAS;aACV,CAAC;QACJ,CAAC;QAED,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QAElC,kEAAkE;QAClE,MAAM,SAAS,GAAG,UAAU,CAAC,CAAC,CAAE,GAAG,QAAQ,CAAC;QAC5C,OAAO;YACL,OAAO,EAAE,IAAI;YACb,IAAI,EAAE,UAAU,CAAC,MAAM;YACvB,KAAK,EAAE,GAAG;YACV,SAAS;SACV,CAAC;IACJ,CAAC;IAED,oCAAoC;IACpC,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;CACF"}

package/lib/app/services/rateLimit/RateLimitBackend.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Storage abstraction for the rate-limit middleware.
+ *
+ * Two implementations ship in v4.0:
+ *   - `RedisSlidingWindowBackend` — production default. Atomic Lua-script
+ *     sliding-window log over a Redis sorted set (ZADD/ZRANGE/ZCARD).
+ *     Supports horizontal scaling.
+ *   - `InMemorySlidingWindowBackend` — test fixture. Single-process only;
+ *     useful for unit tests and as a documented fallback when running
+ *     a single-instance dev / staging service.
+ *
+ * The interface deliberately exposes the algorithm-agnostic shape: a
+ * single `check()` that atomically counts + records the request and
+ * returns the verdict + bookkeeping. Future v4.x implementations
+ * (Cloudflare Durable Objects, Upstash REST, Memcached CAS) plug in
+ * without changing the middleware.
+ */
+export interface RateLimitCheckArgs {
+    /** Composed bucket key (caller has already applied scope + key generator). */
+    key: string;
+    /** Window length in milliseconds. */
+    windowMs: number;
+    /** Maximum requests per window. */
+    max: number;
+    /** Current time in epoch milliseconds. Injected for deterministic tests. */
+    now: number;
+}
+export interface RateLimitCheckResult {
+    /** `true` → request is permitted; `false` → over the ceiling. */
+    allowed: boolean;
+    /** Number of requests counted toward this window so far (post-this-call). */
+    used: number;
+    /** Configured ceiling (returned for header convenience). */
+    limit: number;
+    /** Window-reset time in epoch ms. Used to compute `Retry-After`. */
+    resetAtMs: number;
+}
+export interface RateLimitBackend {
+    check(args: RateLimitCheckArgs): Promise<RateLimitCheckResult>;
+}
+//# sourceMappingURL=RateLimitBackend.d.ts.map

package/lib/app/services/rateLimit/RateLimitBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RateLimitBackend.d.ts","sourceRoot":"","sources":["../../../../src/app/services/rateLimit/RateLimitBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;IACZ,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,oBAAoB;IACnC,iEAAiE;IACjE,OAAO,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAChE"}

package/lib/app/services/rateLimit/RateLimitBackend.js

@@ -0,0 +1,19 @@
+/**
+ * Storage abstraction for the rate-limit middleware.
+ *
+ * Two implementations ship in v4.0:
+ *   - `RedisSlidingWindowBackend` — production default. Atomic Lua-script
+ *     sliding-window log over a Redis sorted set (ZADD/ZRANGE/ZCARD).
+ *     Supports horizontal scaling.
+ *   - `InMemorySlidingWindowBackend` — test fixture. Single-process only;
+ *     useful for unit tests and as a documented fallback when running
+ *     a single-instance dev / staging service.
+ *
+ * The interface deliberately exposes the algorithm-agnostic shape: a
+ * single `check()` that atomically counts + records the request and
+ * returns the verdict + bookkeeping. Future v4.x implementations
+ * (Cloudflare Durable Objects, Upstash REST, Memcached CAS) plug in
+ * without changing the middleware.
+ */
+export {};
+//# sourceMappingURL=RateLimitBackend.js.map

package/lib/app/services/rateLimit/RateLimitBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RateLimitBackend.js","sourceRoot":"","sources":["../../../../src/app/services/rateLimit/RateLimitBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}

package/lib/app/services/rateLimit/RedisSlidingWindowBackend.d.ts

@@ -0,0 +1,16 @@
+import type { RateLimitBackend, RateLimitCheckArgs, RateLimitCheckResult } from "./RateLimitBackend.js";
+export interface RedisEvalClient {
+    eval(script: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
+}
+export interface RedisSlidingWindowBackendOptions {
+    client: RedisEvalClient;
+    /** Optional namespace prepended to every bucket key. */
+    keyPrefix?: string;
+}
+export declare class RedisSlidingWindowBackend implements RateLimitBackend {
+    private client;
+    private keyPrefix;
+    constructor(opts: RedisSlidingWindowBackendOptions);
+    check(args: RateLimitCheckArgs): Promise<RateLimitCheckResult>;
+}
+//# sourceMappingURL=RedisSlidingWindowBackend.d.ts.map

package/lib/app/services/rateLimit/RedisSlidingWindowBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedisSlidingWindowBackend.d.ts","sourceRoot":"","sources":["../../../../src/app/services/rateLimit/RedisSlidingWindowBackend.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACrB,MAAM,uBAAuB,CAAC;AAoD/B,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACvF;AAED,MAAM,WAAW,gCAAgC;IAC/C,MAAM,EAAE,eAAe,CAAC;IACxB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAcD,qBAAa,yBAA0B,YAAW,gBAAgB;IAChE,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,SAAS,CAAS;gBAEd,IAAI,EAAE,gCAAgC;IAK5C,KAAK,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAoBrE"}

package/lib/app/services/rateLimit/RedisSlidingWindowBackend.js

@@ -0,0 +1,80 @@
+import { randomBytes } from "node:crypto";
+/**
+ * Atomic sliding-window-log rate limiter on Redis.
+ *
+ * Algorithm: each key is a sorted set keyed by timestamp. Each request
+ * goes through a single Lua script that:
+ *   1. ZREMRANGEBYSCORE removes entries outside the current window.
+ *   2. ZCARD reads the current count.
+ *   3. If >= max, returns denied (looks up the oldest entry to compute
+ *      the reset time).
+ *   4. Otherwise, ZADD adds this request and PEXPIRE bumps the bucket TTL.
+ *
+ * Single Lua script means atomicity per key — no race between concurrent
+ * requests sharing a bucket. Cluster mode: hash-tag the bucket key to
+ * keep it on one shard.
+ *
+ * Returns `{ allowed (0|1), used, limit, resetAtMs }` from the script;
+ * the wrapper translates to the `RateLimitCheckResult` shape.
+ *
+ * Designed to accept any Redis-like client that supports `eval`. ioredis
+ * and node-redis both qualify.
+ */
+const LUA_SLIDING_WINDOW = `
+local now = tonumber(ARGV[1])
+local windowMs = tonumber(ARGV[2])
+local max = tonumber(ARGV[3])
+local entryId = ARGV[4]
+
+-- Drop expired entries
+redis.call('ZREMRANGEBYSCORE', KEYS[1], 0, now - windowMs)
+
+local count = redis.call('ZCARD', KEYS[1])
+
+if count >= max then
+  -- Get oldest entry's score to compute when the window resets
+  local oldest = redis.call('ZRANGE', KEYS[1], 0, 0, 'WITHSCORES')
+  local resetAt = oldest[2] and (tonumber(oldest[2]) + windowMs) or (now + windowMs)
+  return { 0, count, max, resetAt }
+end
+
+-- Allowed — record this request
+redis.call('ZADD', KEYS[1], now, entryId)
+redis.call('PEXPIRE', KEYS[1], windowMs)
+
+local newCount = count + 1
+local oldest = redis.call('ZRANGE', KEYS[1], 0, 0, 'WITHSCORES')
+local resetAt = oldest[2] and (tonumber(oldest[2]) + windowMs) or (now + windowMs)
+return { 1, newCount, max, resetAt }
+`;
+function nextEntryId(now) {
+    // Unique-enough per-process token: now-ms suffixed with crypto-quality
+    // random bytes. F26 replaced the prior monotonic counter — that leaked
+    // process uptime / request-count info to anyone who could observe two
+    // consecutive entry IDs (admittedly a low-impact info leak, but
+    // `crypto.randomBytes` is free).
+    //
+    // 8 bytes → 16 hex chars → 64 bits of entropy per entry. Far above the
+    // collision threshold for a millisecond window even under heavy load.
+    return `${now}-${randomBytes(8).toString("hex")}`;
+}
+export class RedisSlidingWindowBackend {
+    client;
+    keyPrefix;
+    constructor(opts) {
+        this.client = opts.client;
+        this.keyPrefix = opts.keyPrefix ?? "ratelimit:";
+    }
+    async check(args) {
+        const namespacedKey = this.keyPrefix + args.key;
+        const result = (await this.client.eval(LUA_SLIDING_WINDOW, 1, namespacedKey, args.now, args.windowMs, args.max, nextEntryId(args.now)));
+        const [allowedFlag, used, limit, resetAtMs] = result;
+        return {
+            allowed: allowedFlag === 1,
+            used,
+            limit,
+            resetAtMs,
+        };
+    }
+}
+//# sourceMappingURL=RedisSlidingWindowBackend.js.map

package/lib/app/services/rateLimit/RedisSlidingWindowBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedisSlidingWindowBackend.js","sourceRoot":"","sources":["../../../../src/app/services/rateLimit/RedisSlidingWindowBackend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAO1C;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;CA0B1B,CAAC;AAYF,SAAS,WAAW,CAAC,GAAW;IAC9B,uEAAuE;IACvE,uEAAuE;IACvE,sEAAsE;IACtE,gEAAgE;IAChE,iCAAiC;IACjC,EAAE;IACF,uEAAuE;IACvE,sEAAsE;IACtE,OAAO,GAAG,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;AACpD,CAAC;AAED,MAAM,OAAO,yBAAyB;IAC5B,MAAM,CAAkB;IACxB,SAAS,CAAS;IAE1B,YAAY,IAAsC;QAChD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,YAAY,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAwB;QAClC,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC;QAChD,MAAM,MAAM,GAAG,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CACpC,kBAAkB,EAClB,CAAC,EACD,aAAa,EACb,IAAI,CAAC,GAAG,EACR,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,GAAG,EACR,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CACtB,CAAqC,CAAC;QAEvC,MAAM,CAAC,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,CAAC,GAAG,MAAM,CAAC;QACrD,OAAO;YACL,OAAO,EAAE,WAAW,KAAK,CAAC;YAC1B,IAAI;YACJ,KAAK;YACL,SAAS;SACV,CAAC;IACJ,CAAC;CACF"}

package/lib/app/services/rateLimit/index.d.ts

@@ -0,0 +1,4 @@
+export { InMemorySlidingWindowBackend } from "./InMemorySlidingWindowBackend.js";
+export type { RateLimitBackend, RateLimitCheckArgs, RateLimitCheckResult, } from "./RateLimitBackend.js";
+export { type RedisEvalClient, RedisSlidingWindowBackend, type RedisSlidingWindowBackendOptions, } from "./RedisSlidingWindowBackend.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/app/services/rateLimit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/app/services/rateLimit/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,mCAAmC,CAAC;AACjF,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,eAAe,EACpB,yBAAyB,EACzB,KAAK,gCAAgC,GACtC,MAAM,gCAAgC,CAAC"}

package/lib/app/services/rateLimit/index.js

@@ -0,0 +1,3 @@
+export { InMemorySlidingWindowBackend } from "./InMemorySlidingWindowBackend.js";
+export { RedisSlidingWindowBackend, } from "./RedisSlidingWindowBackend.js";
+//# sourceMappingURL=index.js.map

package/lib/app/services/rateLimit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/app/services/rateLimit/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,mCAAmC,CAAC;AAMjF,OAAO,EAEL,yBAAyB,GAE1B,MAAM,gCAAgC,CAAC"}

package/lib/app/services/storage/DiskStorageAdapter.d.ts

@@ -0,0 +1,62 @@
+import type { GetResult, ListOptions, ListResult, PutOptions, StorageBody, StorageObjectMeta, StorageService } from "./StorageService.js";
+export interface DiskStorageAdapterOptions {
+    /** Absolute path to the root directory. Created on first `put` if absent. */
+    rootDir: string;
+}
+export declare class DiskStorageAdapter implements StorageService {
+    private rootDir;
+    /**
+     * Lazily-resolved real path of `rootDir`. Cached because the root
+     * doesn't move at runtime — and recomputing it per I/O call would
+     * stat the entire root-prefix chain every time.
+     */
+    private realRootCache?;
+    constructor(opts: DiskStorageAdapterOptions);
+    /**
+     * Resolve a key to an absolute filesystem path, refusing path traversal.
+     * String-based check only — see `resolveKeySafe` for the realpath-based
+     * defense against symlink escapes.
+     */
+    private resolveKey;
+    /**
+     * `resolveKey` after a realpath-pass that defeats symlink escapes —
+     * critical for multi-tenant deployments on shared filesystems (NFS,
+     * shared k8s volumes) where one tenant's upload directory could
+     * contain a symlink pointing at another tenant's prefix. The pure
+     * string check in `resolveKey` is sound against `..` patterns but
+     * doesn't notice symlinks.
+     *
+     * Strategy: find the deepest existing ancestor of the target path,
+     * `realpath` it (resolving any symlinks along the way), then
+     * re-check that the canonical absolute path is still inside
+     * `realRootDir`. New-key writes work because the "deepest existing
+     * ancestor" is usually the parent directory of the new file.
+     *
+     * `lstat` (not `stat`) is the gate so a symlink whose target is
+     * missing is still detected — we want the symlink itself to count
+     * as "exists" for the walk, then realpath resolves it.
+     */
+    private resolveKeySafe;
+    private getRealRoot;
+    /** Convert any StorageBody into a Buffer (DiskStorageAdapter buffers fully). */
+    private bodyToBuffer;
+    put(key: string, body: StorageBody, opts?: PutOptions): Promise<StorageObjectMeta>;
+    get(key: string): Promise<GetResult | null>;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    /**
+     * Recursive listing of `rootDir`. `prefix` is matched against the
+     * key (not the absolute path); `continuationToken` is an opaque numeric
+     * cursor of how many entries have been emitted so far.
+     *
+     * For local-disk semantics this is fine; production cloud adapters
+     * carry stronger pagination guarantees.
+     */
+    list(prefix?: string, opts?: ListOptions): Promise<ListResult>;
+    /**
+     * Yields all keys (relative paths) under `dir`. Skips `.meta.json`
+     * sidecars so they don't appear as separate objects.
+     */
+    private walkKeys;
+}
+//# sourceMappingURL=DiskStorageAdapter.d.ts.map

package/lib/app/services/storage/DiskStorageAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DiskStorageAdapter.d.ts","sourceRoot":"","sources":["../../../../src/app/services/storage/DiskStorageAdapter.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,SAAS,EACT,WAAW,EACX,UAAU,EACV,UAAU,EACV,WAAW,EACX,iBAAiB,EACjB,cAAc,EACf,MAAM,qBAAqB,CAAC;AAwB7B,MAAM,WAAW,yBAAyB;IACxC,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,kBAAmB,YAAW,cAAc;IACvD,OAAO,CAAC,OAAO,CAAS;IACxB;;;;OAIG;IACH,OAAO,CAAC,aAAa,CAAC,CAAS;gBAEnB,IAAI,EAAE,yBAAyB;IAM3C;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAelB;;;;;;;;;;;;;;;;;OAiBG;YACW,cAAc;YA+Dd,WAAW;IAgBzB,gFAAgF;YAClE,YAAY;IAsBpB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA2BtF,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IA8B3C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWrC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxC;;;;;;;OAOG;IACG,IAAI,CAAC,MAAM,SAAK,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAmCpE;;;OAGG;YACW,QAAQ;CAqBvB"}