@devmoods/express-extras 0.76.1 → 0.77.0

package/dist/context.js

@@ -7,7 +7,7 @@ export const JOB_ID_CONTEXT_KEY = 'jobId';
 /**
  * Middleware for setting a `requestId` on the request context.
  */
-export function withRequestContext({ getRequestId = (req) => req.headers['X-Request-ID'], } = {}) {
+export function withRequestContext({ getRequestId = (req) => req.get('X-Request-ID'), } = {}) {
     return (req, res, next) => {
         const requestId = getRequestId(req) || randomUUID();
         requestContext.run(new Map(), () => {
@@ -20,6 +20,9 @@ export function withRequestContext({ getRequestId = (req) => req.headers['X-Requ
  * Return a value from the request context
  */
 export function useRequestContext(key) {
+    return getRequestContextValue(key);
+}
+function getRequestContextValue(key) {
     const store = requestContext.getStore();
     if (store) {
         return store.get(key);
@@ -36,8 +39,8 @@ export function setRequestContext(key, value) {
     }
 }
 export function useRequestCounter(key) {
-    const value = useRequestContext(key) || 0;
-    const increase = () => setRequestContext(key, value + 1);
+    const value = getRequestContextValue(key) || 0;
+    const increase = () => setRequestContext(key, (getRequestContextValue(key) || 0) + 1);
     return {
         value,
         increase,

package/dist/email.d.ts

@@ -13,5 +13,5 @@ export interface SendEmailOptions extends nodemailer.SendMailOptions {
 }
 export declare function createEmail({ host, port, user, pass, senderName, senderAddress, onEmailSent, }?: EmailOptions): {
     send: ({ to, subject, message, ...rest }: SendEmailOptions) => Promise<void>;
-    transporter: nodemailer.Transporter<import("nodemailer/lib/smtp-transport/index.js").SentMessageInfo, import("nodemailer/lib/smtp-transport/index.js").Options>;
+    transporter: nodemailer.Mail<nodemailer.SMTPSentMessageInfo, nodemailer.SMTPTransportOptions>;
 };

package/dist/faktory.d.ts

@@ -1,34 +1,21 @@
 import { create, type WorkerOptions } from 'faktory-worker';
-export interface JobsOptions<QueueName extends string> {
-    queues: QueueName[];
+import { type JobBackend, type JobSubmission, type JobWorkerOptions } from './jobs.js';
+export { createJobs, createJobWorker, type AnyJobContext, type Job, type JobBackend, type JobOptions, type JobSubmission, type JobWorker, type JobWorkerOptions, type JobsOptions, } from './jobs.js';
+export interface FaktoryJobBackendOptions {
     faktory?: typeof create;
 }
-export type AnyJobContext = Record<string, any>;
-export interface JobOptions<QueueName extends string> {
-    retry?: number;
-    priority?: number;
-    at?: Date | string;
-    queue?: QueueName;
+export declare class FaktoryJobBackend implements JobBackend {
+    private createFactory;
+    constructor({ faktory }?: FaktoryJobBackendOptions);
+    enqueue({ jid, jobName, args, queue, ...options }: JobSubmission): Promise<void>;
+    createWorker(options: JobWorkerOptions<any>): Promise<{
+        start(workerOptions?: WorkerOptions): Promise<void>;
+        stop(): Promise<void>;
+    }>;
 }
-type JobFn<Arguments, Context extends AnyJobContext> = (input: Arguments, ctx: Context) => undefined | Promise<any>;
-export declare function createJobs<QueueName extends string, GlobalContext extends AnyJobContext>({ queues, faktory: createFactory }: JobsOptions<QueueName>): {
-    job: <Arguments>(optionsOrFn: JobOptions<QueueName> | JobFn<Arguments, GlobalContext>, fnOrUndefined?: JobFn<Arguments, GlobalContext>) => {
-        $job: boolean;
-        jobName: string;
-        options: JobOptions<QueueName>;
-        delay(args?: Parameters<JobFn<Arguments, GlobalContext>>[0]): Promise<`${string}-${string}-${string}-${string}-${string}`>;
-        execute(args: Parameters<JobFn<Arguments, GlobalContext>>[0], context: GlobalContext): Promise<any>;
-    };
-    queues: QueueName[];
-};
-export type Job = ReturnType<ReturnType<typeof createJobs>['job']>;
-export interface FaktoryWorkerOptions<GlobalContext> {
-    jobs: unknown[];
-    queues: string[];
+export interface FaktoryWorkerOptions<GlobalContext> extends JobWorkerOptions<GlobalContext> {
     faktory?: typeof create;
-    jobContext?: GlobalContext;
 }
-export { createFaktoryWorker as createJobWorker };
 export declare function createFaktoryWorker<GlobalContext>({ queues, jobs, faktory: createFactory, jobContext, }: FaktoryWorkerOptions<GlobalContext>): Promise<{
     start(workerOptions?: WorkerOptions): Promise<void>;
     stop(): Promise<void>;

package/dist/faktory.js

@@ -1,61 +1,56 @@
-import { randomUUID } from 'node:crypto';
 import { startTimer } from '@devmoods/observability';
 import { create } from 'faktory-worker';
 import { JOB_ID_CONTEXT_KEY, requestContext, setRequestContext, } from './context.js';
+import {} from './jobs.js';
 import { getLogger } from './logger.js';
+export { createJobs, createJobWorker, } from './jobs.js';
 const logger = getLogger('faktory');
-export function createJobs({ queues, faktory: createFactory = create }) {
-    const faktory = createFactory();
-    function job(optionsOrFn, fnOrUndefined) {
-        const fn = typeof optionsOrFn === 'function' ? optionsOrFn : fnOrUndefined;
-        const options = typeof optionsOrFn === 'function' ? {} : optionsOrFn;
-        if (!fn) {
-            throw new Error('job() must get a function as the first or second argument');
+export class FaktoryJobBackend {
+    createFactory;
+    constructor({ faktory = create } = {}) {
+        this.createFactory = faktory;
+    }
+    async enqueue({ jid, jobName, args, queue, ...options }) {
+        const faktory = this.createFactory();
+        let client;
+        let enqueueError;
+        let closeError;
+        try {
+            client = await faktory.connect();
+            const job = client.job(jobName, args);
+            job.jid = jid;
+            job.queue = queue;
+            Object.assign(job, options);
+            await job.push();
         }
-        const jobName = fn.name;
-        if (!jobName) {
-            throw new Error('Can not create job without a name');
+        catch (error) {
+            enqueueError = error;
         }
-        return {
-            $job: true,
-            jobName,
-            options,
-            async delay(args) {
-                const jid = randomUUID();
+        finally {
+            if (client) {
                 try {
-                    const client = await faktory.connect();
-                    const j = client.job(jobName, args);
-                    j.jid = jid;
-                    j.queue = options.queue || queues[0];
-                    Object.assign(j, options);
-                    await j.push();
                     await client.close();
                 }
                 catch (error) {
-                    logger.error(error, 'failed to create job', {
+                    closeError = error;
+                    logger.error(error, 'failed to close faktory client', {
                         jobId: jid,
                         jobName,
-                        args: JSON.stringify(args),
                     });
-                    throw error;
-                }
-                return jid;
-            },
-            async execute(args, context) {
-                try {
-                    const result = await fn(args, context);
-                    return result;
                 }
-                catch (error) {
-                    logger.error(error);
-                    throw error;
-                }
-            },
-        };
+            }
+        }
+        if (enqueueError) {
+            throw enqueueError;
+        }
+        if (closeError) {
+            throw closeError;
+        }
+    }
+    createWorker(options) {
+        return createFaktoryWorker({ ...options, faktory: this.createFactory });
     }
-    return { job, queues };
 }
-export { createFaktoryWorker as createJobWorker };
 export async function createFaktoryWorker({ queues, jobs, faktory: createFactory = create, jobContext, }) {
     const faktory = createFactory();
     const filter = (j) => !!Object.prototype.hasOwnProperty.call(j, '$job');
@@ -83,25 +78,18 @@ export async function createFaktoryWorker({ queues, jobs, faktory: createFactory
                 faktory.use(async (ctx, next) => {
                     const jobId = ctx.job.jid;
                     const timer = startTimer();
-                    logger.info('job started', {
-                        jobName: ctx.job.jobtype,
-                        jobId,
-                    });
+                    logger.info('job started', { jobName: ctx.job.jobtype, jobId });
                     await requestContext.run(new Map(), async () => {
                         setRequestContext(JOB_ID_CONTEXT_KEY, jobId);
                         await next();
                     });
-                    const duration = timer.getDuration();
                     logger.info('job succeeded', {
                         jobName: ctx.job.jobtype,
                         jobId,
-                        duration,
+                        duration: timer.getDuration(),
                     });
                 });
-                await faktory.work({
-                    queues,
-                    ...workerOptions,
-                });
+                await faktory.work({ queues, ...workerOptions });
             }
             catch (error) {
                 logger.error(error);

package/dist/index.d.ts

@@ -17,6 +17,7 @@ export * from './manage.js';
 export * from './middleware.js';
 export * from './rate-limit.js';
 export * from './redis.js';
+export * from './redis-jobs.js';
 export * from './router.js';
 export * from './routes.js';
 export * from './slack.js';

package/dist/index.js

@@ -18,6 +18,7 @@ export * from './manage.js';
 export * from './middleware.js';
 export * from './rate-limit.js';
 export * from './redis.js';
+export * from './redis-jobs.js';
 export * from './router.js';
 export * from './routes.js';
 export * from './slack.js';

package/dist/jobs.d.ts

@@ -0,0 +1,52 @@
+import { type create } from 'faktory-worker';
+export type AnyJobContext = Record<string, any>;
+export interface JobOptions<QueueName extends string> {
+    retry?: number;
+    priority?: number;
+    at?: Date | string;
+    queue?: QueueName;
+}
+export interface JobSubmission {
+    jid: string;
+    jobName: string;
+    args: unknown;
+    queue: string;
+    retry?: number;
+    priority?: number;
+    at?: Date | string;
+}
+export interface JobWorker {
+    start(options?: any): Promise<void>;
+    stop(): Promise<void>;
+}
+export interface JobBackend {
+    enqueue(job: JobSubmission): Promise<void>;
+    createWorker(options: JobWorkerOptions<any>): Promise<JobWorker> | JobWorker;
+}
+export interface JobWorkerOptions<GlobalContext> {
+    jobs: unknown[];
+    queues: string[];
+    jobContext?: GlobalContext;
+    backend?: JobBackend;
+}
+export interface JobsOptions<QueueName extends string> {
+    queues: QueueName[];
+    backend?: JobBackend;
+    /** @deprecated Pass `new FaktoryJobBackend({ faktory })` as backend. */
+    faktory?: typeof create;
+}
+type JobFn<Arguments, Context extends AnyJobContext> = (input: Arguments, ctx: Context) => undefined | Promise<any>;
+export declare function createJobs<QueueName extends string, GlobalContext extends AnyJobContext>({ queues, backend, faktory }: JobsOptions<QueueName>): {
+    job: <Arguments>(optionsOrFn: JobOptions<QueueName> | JobFn<Arguments, GlobalContext>, fnOrUndefined?: JobFn<Arguments, GlobalContext>) => {
+        $job: boolean;
+        jobName: string;
+        options: JobOptions<QueueName>;
+        delay(args?: Arguments): Promise<`${string}-${string}-${string}-${string}-${string}`>;
+        execute(args: Arguments, context: GlobalContext): Promise<any>;
+    };
+    queues: QueueName[];
+    backend: JobBackend;
+};
+export type Job = ReturnType<ReturnType<typeof createJobs>['job']>;
+export declare function createJobWorker<GlobalContext>({ backend, ...options }: JobWorkerOptions<GlobalContext>): JobWorker | Promise<JobWorker>;
+export {};

package/dist/jobs.js

@@ -0,0 +1,58 @@
+import { randomUUID } from 'node:crypto';
+import {} from 'faktory-worker';
+import { FaktoryJobBackend } from './faktory.js';
+import { getLogger } from './logger.js';
+const logger = getLogger('jobs');
+export function createJobs({ queues, backend, faktory }) {
+    const jobBackend = backend ?? new FaktoryJobBackend({ faktory });
+    function job(optionsOrFn, fnOrUndefined) {
+        const fn = typeof optionsOrFn === 'function' ? optionsOrFn : fnOrUndefined;
+        const options = typeof optionsOrFn === 'function' ? {} : optionsOrFn;
+        if (!fn) {
+            throw new Error('job() must get a function as the first or second argument');
+        }
+        const jobName = fn.name;
+        if (!jobName) {
+            throw new Error('Can not create job without a name');
+        }
+        return {
+            $job: true,
+            jobName,
+            options,
+            async delay(args) {
+                const jid = randomUUID();
+                try {
+                    await jobBackend.enqueue({
+                        jid,
+                        jobName,
+                        args,
+                        queue: options.queue ?? queues[0],
+                        ...options,
+                    });
+                }
+                catch (error) {
+                    logger.error(error, 'failed to create job', {
+                        jobId: jid,
+                        jobName,
+                        args: JSON.stringify(args),
+                    });
+                    throw error;
+                }
+                return jid;
+            },
+            async execute(args, context) {
+                try {
+                    return await fn(args, context);
+                }
+                catch (error) {
+                    logger.error(error);
+                    throw error;
+                }
+            },
+        };
+    }
+    return { job, queues, backend: jobBackend };
+}
+export function createJobWorker({ backend = new FaktoryJobBackend(), ...options }) {
+    return backend.createWorker(options);
+}

package/dist/listen.js

@@ -77,10 +77,28 @@ export function stoppable(server, gracePeriodMs = Infinity) {
         return address.port;
     };
     const start = (port = 0) => {
-        return new Promise((resolve) => {
-            server.listen(port, () => {
+        return new Promise((resolve, reject) => {
+            const cleanup = () => {
+                server.off('listening', onListening);
+                server.off('error', onError);
+            };
+            const onListening = () => {
+                cleanup();
                 resolve();
-            });
+            };
+            const onError = (error) => {
+                cleanup();
+                reject(error);
+            };
+            server.once('listening', onListening);
+            server.once('error', onError);
+            try {
+                server.listen(port);
+            }
+            catch (error) {
+                cleanup();
+                reject(error);
+            }
         });
     };
     const inspect = () => {
@@ -109,6 +127,12 @@ export function createExpressServer(app, options = {}) {
         app.set('trust proxy', trustProxy);
     }
     let stopping = false;
+    const signals = ['SIGTERM', 'SIGINT'];
+    function removeSignalHandlers() {
+        for (const signal of signals) {
+            process.off(signal, onSignal);
+        }
+    }
     async function onSignal(signal) {
         if (stopping) {
             return;
@@ -126,16 +150,18 @@ export function createExpressServer(app, options = {}) {
                 gracefully,
             });
             await options.afterShutdown?.();
+            removeSignalHandlers();
             process.exit(0);
         }
         catch (error) {
             logger.error(error, 'error during shutdown', {
                 duration: timer.getDuration(),
             });
+            removeSignalHandlers();
             process.exit(1);
         }
     }
-    for (const signal of ['SIGTERM', 'SIGINT']) {
+    for (const signal of signals) {
         process.on(signal, onSignal);
     }
     const healthTypes = ['live', 'ready'];
@@ -182,8 +208,13 @@ export function createExpressServer(app, options = {}) {
             duration: appTimer.getDuration(),
         });
     };
-    enhanced.stop = () => {
-        return ctl.stop();
+    enhanced.stop = async () => {
+        try {
+            return await ctl.stop();
+        }
+        finally {
+            removeSignalHandlers();
+        }
     };
     enhanced.terminate = function terminate() {
         return onSignal('SIGTERM');

package/dist/rate-limit.d.ts

@@ -6,11 +6,17 @@ export interface RateLimitMiddleware extends RequestHandler {
      */
     clear: (key: string) => Promise<void>;
     /**
-     * Clear all rate limits
+     * Clear this namespace's rate limits and return the number actually deleted.
+     * Not atomic with concurrent requests: quiesce traffic for a complete reset.
      */
     clearAll: () => Promise<number>;
 }
 export interface RateLimitOptions {
+    /**
+     * Stable, nonempty policy name. Use the same namespace and options on all
+     * workers sharing a quota, and different namespaces for independent policies.
+     */
+    namespace: string;
     /**
      * Maximum number of requests allowed within the window
      * @default 100
@@ -28,6 +34,8 @@ export interface RateLimitOptions {
     getKey?: (req: Request) => string;
 }
 /**
- * Returns a middleware for rate limiting requests.
+ * Fixed-window rate limiting shared across workers through Redis.
+ * The window starts on the first accepted request. Redis errors go to next(error)
+ * without admitting the request. Requires permission to execute Redis scripts.
  */
-export declare function rateLimit(redis: RedisClient, { max, windowSizeInSeconds, getKey, }?: RateLimitOptions): RateLimitMiddleware;
+export declare function rateLimit(redis: RedisClient, { namespace, max, windowSizeInSeconds, getKey, }: RateLimitOptions): RateLimitMiddleware;

package/dist/rate-limit.js

@@ -2,33 +2,64 @@ import { config } from '@devmoods/config';
 import {} from 'express';
 import { makeError } from './errors.js';
 import {} from './redis.js';
+// Redis executes this entire decision atomically, including key expiration.
+// Rejected requests neither increment the counter nor extend the window.
+const consumeScript = `
+local count = tonumber(redis.call('GET', KEYS[1]) or '0')
+local ttl = redis.call('PTTL', KEYS[1])
+local window = tonumber(ARGV[2])
+
+if ttl == -2 then
+  redis.call('SET', KEYS[1], '1', 'PX', ARGV[2])
+  return {1, 1, window}
+end
+
+-- Repair counters that have lost their expiry without resetting their usage.
+if ttl == -1 then
+  redis.call('PEXPIRE', KEYS[1], ARGV[2])
+  ttl = window
+end
+
+if count >= tonumber(ARGV[1]) then
+  return {0, count, ttl}
+end
+
+count = redis.call('INCR', KEYS[1])
+return {1, count, ttl}
+`;
 /**
- * Returns a middleware for rate limiting requests.
+ * Fixed-window rate limiting shared across workers through Redis.
+ * The window starts on the first accepted request. Redis errors go to next(error)
+ * without admitting the request. Requires permission to execute Redis scripts.
  */
-export function rateLimit(redis, { max = 100, windowSizeInSeconds = 60, 
-/* v8 ignore start -- @preserve */
-getKey = (req) => req.ip || 'unknown',
-/* v8 ignore end -- @preserve */
- } = {}) {
-    const keyPrefix = `${config.REDIS_KEY_PREFIX}rate-limit:`;
+export function rateLimit(redis, { namespace, max = 100, windowSizeInSeconds = 60, getKey = (req) => req.ip || 'unknown', }) {
+    if (typeof namespace !== 'string' || namespace.trim().length === 0) {
+        throw new TypeError('namespace must be a nonempty string');
+    }
+    if (!Number.isSafeInteger(max) || max <= 0) {
+        throw new RangeError('max must be a positive safe integer');
+    }
+    const windowMs = windowSizeInSeconds * 1000;
+    if (!Number.isSafeInteger(windowSizeInSeconds) ||
+        windowSizeInSeconds <= 0 ||
+        !Number.isSafeInteger(windowMs)) {
+        throw new RangeError('windowSizeInSeconds must be a positive integer representable safely in milliseconds');
+    }
+    const keyPrefix = `${config.REDIS_KEY_PREFIX}rate-limit:v2:${encodeURIComponent(namespace)}:`;
     const middleware = async (req, res, next) => {
         try {
             const key = `${keyPrefix}${getKey(req)}`;
-            // Use Redis to track requests
-            const currentCount = await redis.get(key);
-            const count = currentCount ? parseInt(currentCount, 10) : 0;
+            const [allowed, count, ttlMs] = (await redis.eval(consumeScript, {
+                keys: [key],
+                arguments: [String(max), String(windowMs)],
+            }));
             // Set headers for rate limiting info
             res.setHeader('X-RateLimit-Limit', max.toString());
-            res.setHeader('X-RateLimit-Remaining', Math.max(0, max - count - 1).toString());
-            if (count >= max) {
+            res.setHeader('X-RateLimit-Remaining', Math.max(0, max - count).toString());
+            if (!allowed) {
+                res.setHeader('Retry-After', Math.max(1, Math.ceil(ttlMs / 1000)).toString());
                 throw makeError(429, 'Rate limit exceeded');
             }
-            if (count === 0) {
-                await redis.set(key, '1', { EX: windowSizeInSeconds });
-            }
-            else {
-                await redis.incr(key);
-            }
             next();
         }
         catch (error) {
@@ -41,7 +72,8 @@ getKey = (req) => req.ip || 'unknown',
     const clearAll = async () => {
         let cursor = '0';
         let deletedCount = 0;
-        const pattern = `${config.REDIS_KEY_PREFIX}rate-limit:*`;
+        // Escape Redis glob metacharacters in both the app prefix and namespace.
+        const pattern = `${keyPrefix.replace(/[\\*?[\]]/g, '\\$&')}*`;
         do {
             // Use SCAN instead of KEYS - non-blocking iteration
             const result = await redis.scan(cursor, {
@@ -50,11 +82,9 @@ getKey = (req) => req.ip || 'unknown',
             });
             cursor = result.cursor;
             const keys = result.keys;
-            /* v8 ignore next -- @preserve */
             if (keys.length > 0) {
                 // Use UNLINK instead of DEL - asynchronous deletion
-                await redis.unlink(keys);
-                deletedCount += keys.length;
+                deletedCount += await redis.unlink(keys);
             }
         } while (cursor !== '0');
         return deletedCount;

package/dist/redis-jobs.d.ts

@@ -0,0 +1,23 @@
+import { type JobBackend, type JobSubmission, type JobWorkerOptions } from './jobs.js';
+import { type RedisClient } from './redis.js';
+export interface RedisJobBackendOptions {
+    /** Defaults to the configured Redis prefix followed by `jobs:`. */
+    keyPrefix?: string;
+    /** Reservation lifetime in milliseconds. Defaults to 30 seconds. */
+    leaseMs?: number;
+}
+/** Persistent, at least once job processing using Redis sorted sets. */
+export declare class RedisJobBackend implements JobBackend {
+    private redis;
+    private options;
+    constructor(redis: RedisClient, options?: RedisJobBackendOptions);
+    private key;
+    private get leaseMs();
+    enqueue(job: JobSubmission): Promise<void>;
+    private claim;
+    private finish;
+    createWorker<GlobalContext>({ jobs, queues, jobContext, }: JobWorkerOptions<GlobalContext>): {
+        start(): Promise<void>;
+        stop(): Promise<void>;
+    };
+}