bunqueue 2.8.34 → 2.8.35

package/dist/application/backgroundTasks.js

@@ -342,8 +342,15 @@ export function recover(ctx) {
         const shard = ctx.shards[shardIndex(qs.name)];
         if (qs.paused)
             shard.pause(qs.name);
-        if (qs.rateLimit !== null)
-            shard.setRateLimit(qs.name, qs.rateLimit);
+        if (qs.rateLimit !== null) {
+            // TTL'd limits are temporary by definition: an already-expired one must
+            // not resurrect as permanent. A still-live one is restored with its
+            // remaining TTL so it keeps expiring broker-side.
+            const remainingTtl = qs.rateLimitExpiresAt === null ? undefined : qs.rateLimitExpiresAt - Date.now();
+            if (remainingTtl === undefined || remainingTtl > 0) {
+                shard.setRateLimit(qs.name, qs.rateLimit, qs.rateLimitDuration ?? undefined, remainingTtl);
+            }
+        }
         if (qs.concurrencyLimit !== null)
             shard.setConcurrency(qs.name, qs.concurrencyLimit);
         ctx.registerQueueName(qs.name);

package/dist/application/queueManager.d.ts

@@ -196,7 +196,7 @@ export declare class QueueManager {
     retryDlq(queue: string, jobId?: JobId, limit?: number): number;
     purgeDlq(queue: string): number;
     retryCompleted(queue: string, jobId?: JobId): number;
-    setRateLimit(queue: string, limit: number): void;
+    setRateLimit(queue: string, limit: number, durationMs?: number, ttlMs?: number): void;
     clearRateLimit(queue: string): void;
     setConcurrency(queue: string, limit: number): void;
     clearConcurrency(queue: string): void;

package/dist/application/queueManager.js

@@ -860,8 +860,8 @@ export class QueueManager {
         return dlqOps.retryCompletedJobs(queue, this.contextFactory.getRetryCompletedContext(), jobId);
     }
     // ============ Rate Limiting ============
-    setRateLimit(queue, limit) {
-        this.shards[shardIndex(queue)].setRateLimit(queue, limit);
+    setRateLimit(queue, limit, durationMs, ttlMs) {
+        this.shards[shardIndex(queue)].setRateLimit(queue, limit, durationMs, ttlMs);
         this.persistQueueState(queue);
     }
     clearRateLimit(queue) {
@@ -893,11 +893,20 @@ export class QueueManager {
             this.storage.deleteQueueState(queue);
             return;
         }
-        this.storage.saveQueueState(queue, state.paused, state.rateLimit, state.concurrencyLimit);
+        this.storage.saveQueueState(queue, {
+            paused: state.paused,
+            rateLimit: state.rateLimit,
+            concurrencyLimit: state.concurrencyLimit,
+            rateLimitDuration: state.rateLimitDuration,
+            rateLimitExpiresAt: state.rateLimitExpiresAt,
+        });
     }
     /** Get rate limit and concurrency limit for a queue */
     getQueueLimits(queue) {
-        const state = this.shards[shardIndex(queue)].getState(queue);
+        const shard = this.shards[shardIndex(queue)];
+        // Lazy TTL expiry so reads never report a limit that no longer throttles.
+        shard.expireRateLimitIfNeeded(queue);
+        const state = shard.getState(queue);
         return { rateLimit: state.rateLimit, concurrencyLimit: state.concurrencyLimit };
     }
     /** Get all job results (for cloud telemetry) */

package/dist/client/queue/dlq.d.ts

@@ -3,7 +3,8 @@
  * Wraps dlqOps for Queue class usage
  */
 import type { TcpConnectionPool } from '../tcpPool';
-import type { DlqConfig, DlqEntry, DlqStats, DlqFilter } from '../types';
+import type { Job, DlqConfig, DlqEntry, DlqStats, DlqFilter } from '../types';
+import { type SimpleJobContext } from './jobProxy';
 interface DlqContext {
     name: string;
     embedded: boolean;
@@ -11,20 +12,41 @@ interface DlqContext {
 }
 /** Set DLQ configuration */
 export declare function setDlqConfig(ctx: DlqContext, config: Partial<DlqConfig>): void;
+/** Set DLQ configuration and resolve once the server has applied it. */
+export declare function setDlqConfigAsync(ctx: DlqContext, config: Partial<DlqConfig>): Promise<void>;
 /** Get DLQ configuration */
 export declare function getDlqConfig(ctx: DlqContext): DlqConfig;
 /** Get DLQ configuration (async, works in TCP mode) */
 export declare function getDlqConfigAsync(ctx: DlqContext): Promise<DlqConfig>;
 /** Get DLQ entries */
 export declare function getDlq<T>(ctx: DlqContext, filter?: DlqFilter): DlqEntry<T>[];
+type DlqQueryContext = DlqContext & Pick<SimpleJobContext, 'getJobState' | 'removeAsync' | 'retryJob' | 'getChildrenValues'>;
+/**
+ * Get the dead jobs in the DLQ, working over TCP too (wire command `Dlq`).
+ * Returns public Job objects; the wire does not carry DlqEntry metadata
+ * (reason, enteredAt, attempts) — that stays embedded-only via getDlq().
+ */
+export declare function getDlqJobsAsync<T>(ctx: DlqQueryContext, count?: number): Promise<Job<T>[]>;
 /** Get DLQ stats */
 export declare function getDlqStats(ctx: DlqContext): DlqStats;
 /** Retry DLQ entries */
 export declare function retryDlq(ctx: DlqContext, id?: string): number;
+/**
+ * Retry DLQ entries and resolve with the retried count once the server has
+ * processed it. The fire-and-forget retryDlq() always returns 0 over TCP and
+ * discards the server's count.
+ */
+export declare function retryDlqAsync(ctx: DlqContext, id?: string): Promise<number>;
 /** Retry DLQ entries by filter */
 export declare function retryDlqByFilter(ctx: DlqContext, filter: DlqFilter): number;
 /** Purge DLQ */
 export declare function purgeDlq(ctx: DlqContext): number;
+/**
+ * Purge the DLQ and resolve with the purged count once the server has
+ * processed it. The fire-and-forget purgeDlq() always returns 0 over TCP;
+ * purge-then-assert-empty patterns need this variant.
+ */
+export declare function purgeDlqAsync(ctx: DlqContext): Promise<number>;
 /** Retry completed job */
 export declare function retryCompleted(ctx: DlqContext, id?: string): number;
 /** Retry completed job (async) */

package/dist/client/queue/dlq.js

@@ -4,6 +4,7 @@
  */
 import { getSharedManager } from '../manager';
 import { jobId } from '../../domain/types/job';
+import { createSimpleJob } from './jobProxy';
 import * as dlqOps from './dlqOps';
 /** Client-side cache for TCP mode */
 const tcpDlqConfigCache = new Map();
@@ -18,6 +19,18 @@ export function setDlqConfig(ctx, config) {
         void ctx.tcp.send({ cmd: 'SetDlqConfig', queue: ctx.name, config });
     }
 }
+/** Set DLQ configuration and resolve once the server has applied it. */
+export async function setDlqConfigAsync(ctx, config) {
+    if (ctx.embedded) {
+        dlqOps.setDlqConfig(ctx.name, config);
+        return;
+    }
+    if (!ctx.tcp)
+        return;
+    const current = tcpDlqConfigCache.get(ctx.name) ?? {};
+    tcpDlqConfigCache.set(ctx.name, { ...current, ...config });
+    await ctx.tcp.send({ cmd: 'SetDlqConfig', queue: ctx.name, config });
+}
 /** Get DLQ configuration */
 export function getDlqConfig(ctx) {
     if (ctx.embedded)
@@ -45,6 +58,38 @@ export function getDlq(ctx, filter) {
         return [];
     return dlqOps.getDlqEntries(ctx.name, filter);
 }
+/**
+ * Get the dead jobs in the DLQ, working over TCP too (wire command `Dlq`).
+ * Returns public Job objects; the wire does not carry DlqEntry metadata
+ * (reason, enteredAt, attempts) — that stays embedded-only via getDlq().
+ */
+export async function getDlqJobsAsync(ctx, count) {
+    let raw;
+    if (ctx.embedded) {
+        raw = getSharedManager().getDlq(ctx.name, count);
+    }
+    else if (ctx.tcp) {
+        const response = await ctx.tcp.send({ cmd: 'Dlq', queue: ctx.name, count });
+        if (!response.ok)
+            return [];
+        raw = (response.jobs ?? []);
+    }
+    else {
+        return [];
+    }
+    return raw.map((job) => {
+        const name = job.data?.name ?? 'unknown';
+        return createSimpleJob(String(job.id), name, job.data, job.createdAt ?? Date.now(), {
+            queueName: ctx.name,
+            embedded: ctx.embedded,
+            tcp: ctx.tcp,
+            getJobState: ctx.getJobState,
+            removeAsync: ctx.removeAsync,
+            retryJob: ctx.retryJob,
+            getChildrenValues: ctx.getChildrenValues,
+        });
+    });
+}
 /** Get DLQ stats */
 export function getDlqStats(ctx) {
     if (!ctx.embedded) {
@@ -67,6 +112,21 @@ export function retryDlq(ctx, id) {
         void ctx.tcp.send({ cmd: 'RetryDlq', queue: ctx.name, jobId: id });
     return 0;
 }
+/**
+ * Retry DLQ entries and resolve with the retried count once the server has
+ * processed it. The fire-and-forget retryDlq() always returns 0 over TCP and
+ * discards the server's count.
+ */
+export async function retryDlqAsync(ctx, id) {
+    if (ctx.embedded)
+        return dlqOps.retryDlqEmbedded(ctx.name, id);
+    if (!ctx.tcp)
+        return 0;
+    const response = await ctx.tcp.send({ cmd: 'RetryDlq', queue: ctx.name, jobId: id });
+    if (!response.ok)
+        return 0;
+    return (response.count ?? 0);
+}
 /** Retry DLQ entries by filter */
 export function retryDlqByFilter(ctx, filter) {
     if (!ctx.embedded)
@@ -81,6 +141,21 @@ export function purgeDlq(ctx) {
         void ctx.tcp.send({ cmd: 'PurgeDlq', queue: ctx.name });
     return 0;
 }
+/**
+ * Purge the DLQ and resolve with the purged count once the server has
+ * processed it. The fire-and-forget purgeDlq() always returns 0 over TCP;
+ * purge-then-assert-empty patterns need this variant.
+ */
+export async function purgeDlqAsync(ctx) {
+    if (ctx.embedded)
+        return dlqOps.purgeDlqEmbedded(ctx.name);
+    if (!ctx.tcp)
+        return 0;
+    const response = await ctx.tcp.send({ cmd: 'PurgeDlq', queue: ctx.name });
+    if (!response.ok)
+        return 0;
+    return (response.count ?? 0);
+}
 /** Retry completed job */
 export function retryCompleted(ctx, id) {
     if (ctx.embedded) {

package/dist/client/queue/jobProxy.d.ts

@@ -29,7 +29,7 @@ export interface JobReflectionMeta {
 }
 /** Create a full Job proxy with TCP methods */
 export declare function createJobProxy<T>(id: string, name: string, data: T, ctx: JobProxyContext, meta?: JobReflectionMeta): Job<T>;
-interface SimpleJobContext {
+export interface SimpleJobContext {
     queueName: string;
     /** Execution mode — determines whether to use embedded manager or TCP */
     embedded?: boolean;

package/dist/client/queue/operations/control.d.ts

@@ -10,12 +10,29 @@ interface ControlContext {
 }
 /** Pause the queue */
 export declare function pause(ctx: ControlContext): void;
+/** Pause the queue and resolve once the server has processed it. */
+export declare function pauseAsync(ctx: ControlContext): Promise<void>;
 /** Resume the queue */
 export declare function resume(ctx: ControlContext): void;
+/** Resume the queue and resolve once the server has processed it. */
+export declare function resumeAsync(ctx: ControlContext): Promise<void>;
 /** Drain the queue (remove all waiting jobs) */
 export declare function drain(ctx: ControlContext): void;
+/**
+ * Drain the queue and resolve with the number of removed jobs once the
+ * server has processed it. Same ordering guarantee as obliterateAsync():
+ * jobs added after resolution cannot be caught by a late-arriving drain.
+ */
+export declare function drainAsync(ctx: ControlContext): Promise<number>;
 /** Obliterate the queue (remove all jobs and data) */
 export declare function obliterate(ctx: ControlContext): void;
+/**
+ * Obliterate the queue and resolve once the server has processed it.
+ * The fire-and-forget obliterate() gives no ordering guarantee over a
+ * multi-connection pool: a PUSH sent right after it can be processed first
+ * and then wiped. Await this variant before enqueuing follow-up jobs.
+ */
+export declare function obliterateAsync(ctx: ControlContext): Promise<void>;
 /** Check if queue is paused (sync, embedded only) */
 export declare function isPaused(ctx: ControlContext): boolean;
 /** Check if queue is paused (async, works with TCP) */

package/dist/client/queue/operations/control.js

@@ -10,6 +10,13 @@ export function pause(ctx) {
     else if (ctx.tcp)
         void ctx.tcp.send({ cmd: 'Pause', queue: ctx.name });
 }
+/** Pause the queue and resolve once the server has processed it. */
+export async function pauseAsync(ctx) {
+    if (ctx.embedded)
+        getSharedManager().pause(ctx.name);
+    else if (ctx.tcp)
+        await ctx.tcp.send({ cmd: 'Pause', queue: ctx.name });
+}
 /** Resume the queue */
 export function resume(ctx) {
     if (ctx.embedded)
@@ -17,6 +24,13 @@ export function resume(ctx) {
     else if (ctx.tcp)
         void ctx.tcp.send({ cmd: 'Resume', queue: ctx.name });
 }
+/** Resume the queue and resolve once the server has processed it. */
+export async function resumeAsync(ctx) {
+    if (ctx.embedded)
+        getSharedManager().resume(ctx.name);
+    else if (ctx.tcp)
+        await ctx.tcp.send({ cmd: 'Resume', queue: ctx.name });
+}
 /** Drain the queue (remove all waiting jobs) */
 export function drain(ctx) {
     if (ctx.embedded)
@@ -24,6 +38,21 @@ export function drain(ctx) {
     else if (ctx.tcp)
         void ctx.tcp.send({ cmd: 'Drain', queue: ctx.name });
 }
+/**
+ * Drain the queue and resolve with the number of removed jobs once the
+ * server has processed it. Same ordering guarantee as obliterateAsync():
+ * jobs added after resolution cannot be caught by a late-arriving drain.
+ */
+export async function drainAsync(ctx) {
+    if (ctx.embedded)
+        return getSharedManager().drain(ctx.name);
+    if (!ctx.tcp)
+        return 0;
+    const response = await ctx.tcp.send({ cmd: 'Drain', queue: ctx.name });
+    if (!response.ok)
+        return 0;
+    return (response.count ?? 0);
+}
 /** Obliterate the queue (remove all jobs and data) */
 export function obliterate(ctx) {
     if (ctx.embedded)
@@ -31,6 +60,18 @@ export function obliterate(ctx) {
     else if (ctx.tcp)
         void ctx.tcp.send({ cmd: 'Obliterate', queue: ctx.name });
 }
+/**
+ * Obliterate the queue and resolve once the server has processed it.
+ * The fire-and-forget obliterate() gives no ordering guarantee over a
+ * multi-connection pool: a PUSH sent right after it can be processed first
+ * and then wiped. Await this variant before enqueuing follow-up jobs.
+ */
+export async function obliterateAsync(ctx) {
+    if (ctx.embedded)
+        getSharedManager().obliterate(ctx.name);
+    else if (ctx.tcp)
+        await ctx.tcp.send({ cmd: 'Obliterate', queue: ctx.name });
+}
 /** Check if queue is paused (sync, embedded only) */
 export function isPaused(ctx) {
     if (!ctx.embedded)

package/dist/client/queue/queue.d.ts

@@ -74,9 +74,13 @@ export declare class Queue<T = unknown> {
     getCountsPerPriority(): Record<number, number>;
     getCountsPerPriorityAsync(): Promise<Record<number, number>>;
     pause(): void;
+    pauseAsync(): Promise<void>;
     resume(): void;
+    resumeAsync(): Promise<void>;
     drain(): void;
+    drainAsync(): Promise<number>;
     obliterate(): void;
+    obliterateAsync(): Promise<void>;
     isPaused(): boolean;
     isPausedAsync(): Promise<boolean>;
     waitUntilReady(): Promise<void>;
@@ -106,23 +110,32 @@ export declare class Queue<T = unknown> {
     changeJobPriority(id: string, opts: ChangePriorityOpts): Promise<void>;
     extendJobLock(id: string, token: string, duration: number): Promise<number>;
     setStallConfig(config: Partial<StallConfig>): void;
+    setStallConfigAsync(config: Partial<StallConfig>): Promise<void>;
     getStallConfig(): StallConfig;
     getStallConfigAsync(): Promise<StallConfig>;
     setDlqConfig(config: Partial<DlqConfig>): void;
+    setDlqConfigAsync(config: Partial<DlqConfig>): Promise<void>;
     getDlqConfig(): DlqConfig;
     getDlqConfigAsync(): Promise<DlqConfig>;
     getDlq(filter?: DlqFilter): DlqEntry<T>[];
+    getDlqJobsAsync(count?: number): Promise<Job<T>[]>;
     getDlqStats(): DlqStats;
     retryDlq(id?: string): number;
+    retryDlqAsync(id?: string): Promise<number>;
     retryDlqByFilter(filter: DlqFilter): number;
     purgeDlq(): number;
+    purgeDlqAsync(): Promise<number>;
     retryCompleted(id?: string): number;
     retryCompletedAsync(id?: string): Promise<number>;
     setGlobalConcurrency(concurrency: number): void;
+    setGlobalConcurrencyAsync(concurrency: number): Promise<void>;
     removeGlobalConcurrency(): void;
+    removeGlobalConcurrencyAsync(): Promise<void>;
     getGlobalConcurrency(): Promise<number | null>;
     setGlobalRateLimit(max: number, duration?: number): void;
+    setGlobalRateLimitAsync(max: number, duration?: number): Promise<void>;
     removeGlobalRateLimit(): void;
+    removeGlobalRateLimitAsync(): Promise<void>;
     getGlobalRateLimit(): Promise<{
         max: number;
         duration: number;

package/dist/client/queue/queue.js

@@ -262,15 +262,27 @@ export class Queue {
     pause() {
         controlOps.pause(this.ctx);
     }
+    pauseAsync() {
+        return controlOps.pauseAsync(this.ctx);
+    }
     resume() {
         controlOps.resume(this.ctx);
     }
+    resumeAsync() {
+        return controlOps.resumeAsync(this.ctx);
+    }
     drain() {
         controlOps.drain(this.ctx);
     }
+    drainAsync() {
+        return controlOps.drainAsync(this.ctx);
+    }
     obliterate() {
         controlOps.obliterate(this.ctx);
     }
+    obliterateAsync() {
+        return controlOps.obliterateAsync(this.ctx);
+    }
     isPaused() {
         return controlOps.isPaused(this.ctx);
     }
@@ -333,6 +345,9 @@ export class Queue {
     setStallConfig(config) {
         stallOps.setStallConfig(this.ctx, config);
     }
+    setStallConfigAsync(config) {
+        return stallOps.setStallConfigAsync(this.ctx, config);
+    }
     getStallConfig() {
         return stallOps.getStallConfig(this.ctx);
     }
@@ -343,6 +358,9 @@ export class Queue {
     setDlqConfig(config) {
         dlqOps.setDlqConfig(this.ctx, config);
     }
+    setDlqConfigAsync(config) {
+        return dlqOps.setDlqConfigAsync(this.ctx, config);
+    }
     getDlqConfig() {
         return dlqOps.getDlqConfig(this.ctx);
     }
@@ -352,18 +370,27 @@ export class Queue {
     getDlq(filter) {
         return dlqOps.getDlq(this.ctx, filter);
     }
+    getDlqJobsAsync(count) {
+        return dlqOps.getDlqJobsAsync(this.queryCtx, count);
+    }
     getDlqStats() {
         return dlqOps.getDlqStats(this.ctx);
     }
     retryDlq(id) {
         return dlqOps.retryDlq(this.ctx, id);
     }
+    retryDlqAsync(id) {
+        return dlqOps.retryDlqAsync(this.ctx, id);
+    }
     retryDlqByFilter(filter) {
         return dlqOps.retryDlqByFilter(this.ctx, filter);
     }
     purgeDlq() {
         return dlqOps.purgeDlq(this.ctx);
     }
+    purgeDlqAsync() {
+        return dlqOps.purgeDlqAsync(this.ctx);
+    }
     retryCompleted(id) {
         return dlqOps.retryCompleted(this.ctx, id);
     }
@@ -374,18 +401,30 @@ export class Queue {
     setGlobalConcurrency(concurrency) {
         rateLimitOps.setGlobalConcurrency(this.ctx, concurrency);
     }
+    setGlobalConcurrencyAsync(concurrency) {
+        return rateLimitOps.setGlobalConcurrencyAsync(this.ctx, concurrency);
+    }
     removeGlobalConcurrency() {
         rateLimitOps.removeGlobalConcurrency(this.ctx);
     }
+    removeGlobalConcurrencyAsync() {
+        return rateLimitOps.removeGlobalConcurrencyAsync(this.ctx);
+    }
     getGlobalConcurrency() {
         return rateLimitOps.getGlobalConcurrency(this.ctx);
     }
     setGlobalRateLimit(max, duration) {
         rateLimitOps.setGlobalRateLimit(this.ctx, max, duration);
     }
+    setGlobalRateLimitAsync(max, duration) {
+        return rateLimitOps.setGlobalRateLimitAsync(this.ctx, max, duration);
+    }
     removeGlobalRateLimit() {
         rateLimitOps.removeGlobalRateLimit(this.ctx);
     }
+    removeGlobalRateLimitAsync() {
+        return rateLimitOps.removeGlobalRateLimitAsync(this.ctx);
+    }
     getGlobalRateLimit() {
         return rateLimitOps.getGlobalRateLimit(this.ctx);
     }

package/dist/client/queue/rateLimit.d.ts

@@ -9,20 +9,35 @@ interface RateLimitContext {
 }
 /** Set global concurrency limit */
 export declare function setGlobalConcurrency(ctx: RateLimitContext, concurrency: number): void;
+/** Set global concurrency limit and resolve once the server has applied it. */
+export declare function setGlobalConcurrencyAsync(ctx: RateLimitContext, concurrency: number): Promise<void>;
 /** Remove global concurrency limit */
 export declare function removeGlobalConcurrency(ctx: RateLimitContext): void;
+/** Remove global concurrency limit and resolve once the server has applied it. */
+export declare function removeGlobalConcurrencyAsync(ctx: RateLimitContext): Promise<void>;
 /** Get global concurrency limit */
 export declare function getGlobalConcurrency(_ctx: RateLimitContext): Promise<number | null>;
-/** Set global rate limit */
-export declare function setGlobalRateLimit(ctx: RateLimitContext, max: number, _duration?: number): void;
+/**
+ * Set global rate limit: `max` jobs per `duration` ms (default 1000ms).
+ * The window is honored in both embedded and TCP modes.
+ */
+export declare function setGlobalRateLimit(ctx: RateLimitContext, max: number, duration?: number): void;
+/** Set global rate limit and resolve once the server has applied it. */
+export declare function setGlobalRateLimitAsync(ctx: RateLimitContext, max: number, duration?: number): Promise<void>;
 /** Remove global rate limit */
 export declare function removeGlobalRateLimit(ctx: RateLimitContext): void;
+/** Remove global rate limit and resolve once the server has applied it. */
+export declare function removeGlobalRateLimitAsync(ctx: RateLimitContext): Promise<void>;
 /** Get global rate limit */
 export declare function getGlobalRateLimit(_ctx: RateLimitContext): Promise<{
     max: number;
     duration: number;
 } | null>;
-/** Set temporary rate limit with expiration */
+/**
+ * Set temporary rate limit with expiration. The expiry lives broker-side
+ * (RateLimit `ttl`), so it survives client exit and works identically in
+ * embedded and TCP modes — no client timer involved.
+ */
 export declare function rateLimit(ctx: RateLimitContext, expireTimeMs: number): Promise<void>;
 /** Get rate limit TTL */
 export declare function getRateLimitTtl(_ctx: RateLimitContext, _maxJobs?: number): Promise<number>;

package/dist/client/queue/rateLimit.js

@@ -11,6 +11,13 @@ export function setGlobalConcurrency(ctx, concurrency) {
         void ctx.tcp.send({ cmd: 'SetConcurrency', queue: ctx.name, limit: concurrency });
     }
 }
+/** Set global concurrency limit and resolve once the server has applied it. */
+export async function setGlobalConcurrencyAsync(ctx, concurrency) {
+    if (ctx.embedded)
+        getSharedManager().setConcurrency(ctx.name, concurrency);
+    else if (ctx.tcp)
+        await ctx.tcp.send({ cmd: 'SetConcurrency', queue: ctx.name, limit: concurrency });
+}
 /** Remove global concurrency limit */
 export function removeGlobalConcurrency(ctx) {
     if (ctx.embedded) {
@@ -20,19 +27,36 @@ export function removeGlobalConcurrency(ctx) {
         void ctx.tcp.send({ cmd: 'ClearConcurrency', queue: ctx.name });
     }
 }
+/** Remove global concurrency limit and resolve once the server has applied it. */
+export async function removeGlobalConcurrencyAsync(ctx) {
+    if (ctx.embedded)
+        getSharedManager().clearConcurrency(ctx.name);
+    else if (ctx.tcp)
+        await ctx.tcp.send({ cmd: 'ClearConcurrency', queue: ctx.name });
+}
 /** Get global concurrency limit */
 export function getGlobalConcurrency(_ctx) {
     return Promise.resolve(null);
 }
-/** Set global rate limit */
-export function setGlobalRateLimit(ctx, max, _duration) {
+/**
+ * Set global rate limit: `max` jobs per `duration` ms (default 1000ms).
+ * The window is honored in both embedded and TCP modes.
+ */
+export function setGlobalRateLimit(ctx, max, duration) {
     if (ctx.embedded) {
-        getSharedManager().setRateLimit(ctx.name, max);
+        getSharedManager().setRateLimit(ctx.name, max, duration);
     }
     else if (ctx.tcp) {
-        void ctx.tcp.send({ cmd: 'RateLimit', queue: ctx.name, limit: max });
+        void ctx.tcp.send({ cmd: 'RateLimit', queue: ctx.name, limit: max, duration });
     }
 }
+/** Set global rate limit and resolve once the server has applied it. */
+export async function setGlobalRateLimitAsync(ctx, max, duration) {
+    if (ctx.embedded)
+        getSharedManager().setRateLimit(ctx.name, max, duration);
+    else if (ctx.tcp)
+        await ctx.tcp.send({ cmd: 'RateLimit', queue: ctx.name, limit: max, duration });
+}
 /** Remove global rate limit */
 export function removeGlobalRateLimit(ctx) {
     if (ctx.embedded) {
@@ -42,20 +66,31 @@ export function removeGlobalRateLimit(ctx) {
         void ctx.tcp.send({ cmd: 'RateLimitClear', queue: ctx.name });
     }
 }
+/** Remove global rate limit and resolve once the server has applied it. */
+export async function removeGlobalRateLimitAsync(ctx) {
+    if (ctx.embedded)
+        getSharedManager().clearRateLimit(ctx.name);
+    else if (ctx.tcp)
+        await ctx.tcp.send({ cmd: 'RateLimitClear', queue: ctx.name });
+}
 /** Get global rate limit */
 export function getGlobalRateLimit(_ctx) {
     return Promise.resolve(null);
 }
-/** Set temporary rate limit with expiration */
+/**
+ * Set temporary rate limit with expiration. The expiry lives broker-side
+ * (RateLimit `ttl`), so it survives client exit and works identically in
+ * embedded and TCP modes — no client timer involved.
+ */
 export async function rateLimit(ctx, expireTimeMs) {
+    if (!Number.isFinite(expireTimeMs) || expireTimeMs <= 0) {
+        throw new Error(`rateLimit: expireTimeMs must be a positive finite number, got ${expireTimeMs}`);
+    }
     if (ctx.embedded) {
-        getSharedManager().setRateLimit(ctx.name, 1);
-        setTimeout(() => {
-            getSharedManager().clearRateLimit(ctx.name);
-        }, expireTimeMs);
+        getSharedManager().setRateLimit(ctx.name, 1, undefined, expireTimeMs);
     }
     else if (ctx.tcp) {
-        await ctx.tcp.send({ cmd: 'RateLimit', queue: ctx.name, limit: 1 });
+        await ctx.tcp.send({ cmd: 'RateLimit', queue: ctx.name, limit: 1, ttl: expireTimeMs });
     }
 }
 /** Get rate limit TTL */

package/dist/client/queue/stall.d.ts

@@ -11,6 +11,8 @@ interface StallContext {
 }
 /** Set stall detection configuration */
 export declare function setStallConfig(ctx: StallContext, config: Partial<StallConfig>): void;
+/** Set stall detection configuration and resolve once the server has applied it. */
+export declare function setStallConfigAsync(ctx: StallContext, config: Partial<StallConfig>): Promise<void>;
 /** Get stall detection configuration */
 export declare function getStallConfig(ctx: StallContext): StallConfig;
 /** Get stall detection configuration (async, works in TCP mode) */

package/dist/client/queue/stall.js

@@ -23,6 +23,18 @@ export function setStallConfig(ctx, config) {
         void ctx.tcp.send({ cmd: 'SetStallConfig', queue: ctx.name, config });
     }
 }
+/** Set stall detection configuration and resolve once the server has applied it. */
+export async function setStallConfigAsync(ctx, config) {
+    if (ctx.embedded) {
+        dlqOps.setStallConfigEmbedded(ctx.name, config);
+        return;
+    }
+    if (!ctx.tcp)
+        return;
+    const current = tcpConfigCache.get(ctx.name) ?? { ...DEFAULT_STALL_CONFIG };
+    tcpConfigCache.set(ctx.name, { ...current, ...config });
+    await ctx.tcp.send({ cmd: 'SetStallConfig', queue: ctx.name, config });
+}
 /** Get stall detection configuration */
 export function getStallConfig(ctx) {
     if (ctx.embedded) {

package/dist/domain/queue/limiterManager.d.ts

@@ -20,10 +20,22 @@ export declare class LimiterManager {
     pause(name: string): void;
     /** Resume queue */
     resume(name: string): void;
-    /** Set rate limit for queue */
-    setRateLimit(queue: string, limit: number): void;
+    /**
+     * Set rate limit for queue.
+     * @param durationMs window the limit applies to (default 1000ms): `limit`
+     *   tokens refill over `durationMs`. Non-finite or non-positive → default.
+     * @param ttlMs auto-expiry: the limit clears itself after this many ms
+     *   (lazy, checked on acquire/read). Non-finite or non-positive → permanent.
+     */
+    setRateLimit(queue: string, limit: number, durationMs?: number, ttlMs?: number): void;
     /** Clear rate limit */
     clearRateLimit(queue: string): void;
+    /**
+     * Drop the rate limit if its TTL has elapsed. Lazy expiry: called from the
+     * acquire path and from limit reads, so no timer is needed and an expired
+     * limit can never throttle a pull.
+     */
+    expireRateLimitIfNeeded(queue: string): void;
     /** Try to acquire rate limit token */
     tryAcquireRateLimit(queue: string): boolean;
     /** Set concurrency limit for queue */

package/dist/domain/queue/limiterManager.js

@@ -34,20 +34,47 @@ export class LimiterManager {
         this.getState(name).paused = false;
     }
     // ============ Rate Limiting ============
-    /** Set rate limit for queue */
-    setRateLimit(queue, limit) {
-        this.rateLimiters.set(queue, new RateLimiter(limit));
-        this.getState(queue).rateLimit = limit;
+    /**
+     * Set rate limit for queue.
+     * @param durationMs window the limit applies to (default 1000ms): `limit`
+     *   tokens refill over `durationMs`. Non-finite or non-positive → default.
+     * @param ttlMs auto-expiry: the limit clears itself after this many ms
+     *   (lazy, checked on acquire/read). Non-finite or non-positive → permanent.
+     */
+    setRateLimit(queue, limit, durationMs, ttlMs) {
+        const duration = Number.isFinite(durationMs) && durationMs > 0 ? durationMs : null;
+        const ttl = Number.isFinite(ttlMs) && ttlMs > 0 ? ttlMs : null;
+        const windowSeconds = (duration ?? 1000) / 1000;
+        this.rateLimiters.set(queue, new RateLimiter(limit, limit / windowSeconds));
+        const state = this.getState(queue);
+        state.rateLimit = limit;
+        state.rateLimitDuration = duration;
+        state.rateLimitExpiresAt = ttl === null ? null : Date.now() + ttl;
     }
     /** Clear rate limit */
     clearRateLimit(queue) {
         this.rateLimiters.delete(queue);
         const state = this.queueState.get(queue);
-        if (state)
+        if (state) {
             state.rateLimit = null;
+            state.rateLimitDuration = null;
+            state.rateLimitExpiresAt = null;
+        }
+    }
+    /**
+     * Drop the rate limit if its TTL has elapsed. Lazy expiry: called from the
+     * acquire path and from limit reads, so no timer is needed and an expired
+     * limit can never throttle a pull.
+     */
+    expireRateLimitIfNeeded(queue) {
+        const expiresAt = this.queueState.get(queue)?.rateLimitExpiresAt;
+        if (expiresAt !== null && expiresAt !== undefined && Date.now() >= expiresAt) {
+            this.clearRateLimit(queue);
+        }
     }
     /** Try to acquire rate limit token */
     tryAcquireRateLimit(queue) {
+        this.expireRateLimitIfNeeded(queue);
         const limiter = this.rateLimiters.get(queue);
         return !limiter || limiter.tryAcquire();
     }

package/dist/domain/queue/shard.d.ts

@@ -69,8 +69,9 @@ export declare class Shard {
     isGroupActive(queue: string, groupId: string): boolean;
     activateGroup(queue: string, groupId: string): void;
     releaseGroup(queue: string, groupId: string): void;
-    setRateLimit(queue: string, limit: number): void;
+    setRateLimit(queue: string, limit: number, durationMs?: number, ttlMs?: number): void;
     clearRateLimit(queue: string): void;
+    expireRateLimitIfNeeded(queue: string): void;
     tryAcquireRateLimit(queue: string): boolean;
     setConcurrency(queue: string, limit: number): void;
     clearConcurrency(queue: string): void;

package/dist/domain/queue/shard.js

@@ -138,12 +138,15 @@ export class Shard {
         this.activeGroups.get(queue)?.delete(groupId);
     }
     // ============ Rate & Concurrency Limiting (delegated) ============
-    setRateLimit(queue, limit) {
-        this.limiterManager.setRateLimit(queue, limit);
+    setRateLimit(queue, limit, durationMs, ttlMs) {
+        this.limiterManager.setRateLimit(queue, limit, durationMs, ttlMs);
     }
     clearRateLimit(queue) {
         this.limiterManager.clearRateLimit(queue);
     }
+    expireRateLimitIfNeeded(queue) {
+        this.limiterManager.expireRateLimitIfNeeded(queue);
+    }
     tryAcquireRateLimit(queue) {
         return this.limiterManager.tryAcquireRateLimit(queue);
     }

package/dist/domain/types/command.d.ts

@@ -253,6 +253,10 @@ export interface RateLimitCommand extends BaseCommand {
     readonly cmd: 'RateLimit';
     readonly queue: string;
     readonly limit: number;
+    /** Window in ms the limit applies to (default 1000: `limit` per second). */
+    readonly duration?: number;
+    /** Auto-expiry in ms: the limit clears itself broker-side after this long. */
+    readonly ttl?: number;
 }
 export interface SetConcurrencyCommand extends BaseCommand {
     readonly cmd: 'SetConcurrency';

package/dist/domain/types/queue.d.ts

@@ -7,6 +7,10 @@ export interface QueueState {
     readonly name: string;
     paused: boolean;
     rateLimit: number | null;
+    /** Rate-limit window in ms (null = default 1000ms bucket). */
+    rateLimitDuration: number | null;
+    /** Epoch ms after which the rate limit self-expires (null = permanent). */
+    rateLimitExpiresAt: number | null;
     concurrencyLimit: number | null;
     activeCount: number;
 }

package/dist/domain/types/queue.js

@@ -8,6 +8,8 @@ export function createQueueState(name) {
         name,
         paused: false,
         rateLimit: null,
+        rateLimitDuration: null,
+        rateLimitExpiresAt: null,
         concurrencyLimit: null,
         activeCount: 0,
     };

package/dist/infrastructure/persistence/schema.d.ts

@@ -4,10 +4,10 @@
 /** SQLite PRAGMA settings for optimal performance */
 export declare const PRAGMA_SETTINGS = "\nPRAGMA journal_mode = WAL;\nPRAGMA synchronous = NORMAL;\nPRAGMA cache_size = -64000;\nPRAGMA temp_store = MEMORY;\nPRAGMA mmap_size = 268435456;\nPRAGMA page_size = 4096;\nPRAGMA busy_timeout = 5000;\n";
 /** Main schema creation */
-export declare const SCHEMA = "\n-- Jobs table (using UUIDv7 for job IDs)\n-- Uses BLOB for data fields (MessagePack serialization for ~2-3x faster than JSON)\nCREATE TABLE IF NOT EXISTS jobs (\n    id TEXT PRIMARY KEY,\n    queue TEXT NOT NULL,\n    data BLOB NOT NULL,\n    priority INTEGER NOT NULL DEFAULT 0,\n    created_at INTEGER NOT NULL,\n    run_at INTEGER NOT NULL,\n    started_at INTEGER,\n    completed_at INTEGER,\n    attempts INTEGER NOT NULL DEFAULT 0,\n    max_attempts INTEGER NOT NULL DEFAULT 3,\n    backoff INTEGER NOT NULL DEFAULT 1000,\n    ttl INTEGER,\n    timeout INTEGER,\n    unique_key TEXT,\n    custom_id TEXT,\n    depends_on BLOB,\n    parent_id TEXT,\n    children_ids BLOB,\n    tags BLOB,\n    state TEXT NOT NULL DEFAULT 'waiting',\n    lifo INTEGER NOT NULL DEFAULT 0,\n    group_id TEXT,\n    progress INTEGER DEFAULT 0,\n    progress_msg TEXT,\n    remove_on_complete INTEGER DEFAULT 0,\n    remove_on_fail INTEGER DEFAULT 0,\n    stall_timeout INTEGER,\n    last_heartbeat INTEGER,\n    timeline BLOB,\n    stacktrace BLOB\n);\n\n-- Indexes for common queries\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_state\n    ON jobs(queue, state);\n-- Stable createdAt/id pagination for unfiltered and logical-state queue views\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_created\n    ON jobs(queue, created_at, id);\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_state_created\n    ON jobs(queue, state, created_at, id);\nCREATE INDEX IF NOT EXISTS idx_jobs_run_at\n    ON jobs(run_at) WHERE state IN ('waiting', 'delayed');\nCREATE INDEX IF NOT EXISTS idx_jobs_unique\n    ON jobs(queue, unique_key) WHERE unique_key IS NOT NULL;\nCREATE INDEX IF NOT EXISTS idx_jobs_custom_id\n    ON jobs(custom_id) WHERE custom_id IS NOT NULL;\nCREATE INDEX IF NOT EXISTS idx_jobs_parent\n    ON jobs(parent_id) WHERE parent_id IS NOT NULL;\n\n-- Job results storage (BLOB for MessagePack)\nCREATE TABLE IF NOT EXISTS job_results (\n    job_id TEXT PRIMARY KEY,\n    result BLOB,\n    completed_at INTEGER NOT NULL\n);\n\n-- Dead letter queue (BLOB for MessagePack - stores full DlqEntry)\nCREATE TABLE IF NOT EXISTS dlq (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    job_id TEXT NOT NULL,\n    queue TEXT NOT NULL,\n    entry BLOB NOT NULL,\n    entered_at INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_dlq_queue ON dlq(queue);\nCREATE INDEX IF NOT EXISTS idx_dlq_job_id ON dlq(job_id);\nCREATE INDEX IF NOT EXISTS idx_dlq_entered_at ON dlq(entered_at);\n\n-- Performance indexes for high-throughput operations\n-- Stall detection: runs every 5s, needs fast lookup of active jobs by started_at\nCREATE INDEX IF NOT EXISTS idx_jobs_state_started\n    ON jobs(state, started_at) WHERE state = 'active';\n\n-- Group operations: fast lookup by group_id\nCREATE INDEX IF NOT EXISTS idx_jobs_group_id\n    ON jobs(group_id) WHERE group_id IS NOT NULL;\n\n-- Pending jobs: compound index for priority-ordered retrieval\nCREATE INDEX IF NOT EXISTS idx_jobs_pending_priority\n    ON jobs(queue, state, priority DESC, run_at ASC) WHERE state IN ('waiting', 'delayed');\n\n-- Completed jobs: index for recovery ordering (issue #84)\nCREATE INDEX IF NOT EXISTS idx_jobs_completed_order\n    ON jobs(completed_at DESC) WHERE state = 'completed';\n\n-- Cron jobs (BLOB for MessagePack)\nCREATE TABLE IF NOT EXISTS cron_jobs (\n    name TEXT PRIMARY KEY,\n    queue TEXT NOT NULL,\n    data BLOB NOT NULL,\n    schedule TEXT,\n    repeat_every INTEGER,\n    priority INTEGER NOT NULL DEFAULT 0,\n    next_run INTEGER NOT NULL,\n    executions INTEGER NOT NULL DEFAULT 0,\n    max_limit INTEGER,\n    timezone TEXT,\n    unique_key TEXT,\n    dedup BLOB,\n    skip_missed_on_restart INTEGER NOT NULL DEFAULT 0,\n    skip_if_no_worker INTEGER NOT NULL DEFAULT 0,\n    prevent_overlap INTEGER NOT NULL DEFAULT 1,\n    job_options BLOB\n);\n\n-- Queue state persistence (optional)\nCREATE TABLE IF NOT EXISTS queue_state (\n    name TEXT PRIMARY KEY,\n    paused INTEGER NOT NULL DEFAULT 0,\n    rate_limit INTEGER,\n    concurrency_limit INTEGER\n);\n";
+export declare const SCHEMA = "\n-- Jobs table (using UUIDv7 for job IDs)\n-- Uses BLOB for data fields (MessagePack serialization for ~2-3x faster than JSON)\nCREATE TABLE IF NOT EXISTS jobs (\n    id TEXT PRIMARY KEY,\n    queue TEXT NOT NULL,\n    data BLOB NOT NULL,\n    priority INTEGER NOT NULL DEFAULT 0,\n    created_at INTEGER NOT NULL,\n    run_at INTEGER NOT NULL,\n    started_at INTEGER,\n    completed_at INTEGER,\n    attempts INTEGER NOT NULL DEFAULT 0,\n    max_attempts INTEGER NOT NULL DEFAULT 3,\n    backoff INTEGER NOT NULL DEFAULT 1000,\n    ttl INTEGER,\n    timeout INTEGER,\n    unique_key TEXT,\n    custom_id TEXT,\n    depends_on BLOB,\n    parent_id TEXT,\n    children_ids BLOB,\n    tags BLOB,\n    state TEXT NOT NULL DEFAULT 'waiting',\n    lifo INTEGER NOT NULL DEFAULT 0,\n    group_id TEXT,\n    progress INTEGER DEFAULT 0,\n    progress_msg TEXT,\n    remove_on_complete INTEGER DEFAULT 0,\n    remove_on_fail INTEGER DEFAULT 0,\n    stall_timeout INTEGER,\n    last_heartbeat INTEGER,\n    timeline BLOB,\n    stacktrace BLOB\n);\n\n-- Indexes for common queries\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_state\n    ON jobs(queue, state);\n-- Stable createdAt/id pagination for unfiltered and logical-state queue views\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_created\n    ON jobs(queue, created_at, id);\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_state_created\n    ON jobs(queue, state, created_at, id);\nCREATE INDEX IF NOT EXISTS idx_jobs_run_at\n    ON jobs(run_at) WHERE state IN ('waiting', 'delayed');\nCREATE INDEX IF NOT EXISTS idx_jobs_unique\n    ON jobs(queue, unique_key) WHERE unique_key IS NOT NULL;\nCREATE INDEX IF NOT EXISTS idx_jobs_custom_id\n    ON jobs(custom_id) WHERE custom_id IS NOT NULL;\nCREATE INDEX IF NOT EXISTS idx_jobs_parent\n    ON jobs(parent_id) WHERE parent_id IS NOT NULL;\n\n-- Job results storage (BLOB for MessagePack)\nCREATE TABLE IF NOT EXISTS job_results (\n    job_id TEXT PRIMARY KEY,\n    result BLOB,\n    completed_at INTEGER NOT NULL\n);\n\n-- Dead letter queue (BLOB for MessagePack - stores full DlqEntry)\nCREATE TABLE IF NOT EXISTS dlq (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    job_id TEXT NOT NULL,\n    queue TEXT NOT NULL,\n    entry BLOB NOT NULL,\n    entered_at INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_dlq_queue ON dlq(queue);\nCREATE INDEX IF NOT EXISTS idx_dlq_job_id ON dlq(job_id);\nCREATE INDEX IF NOT EXISTS idx_dlq_entered_at ON dlq(entered_at);\n\n-- Performance indexes for high-throughput operations\n-- Stall detection: runs every 5s, needs fast lookup of active jobs by started_at\nCREATE INDEX IF NOT EXISTS idx_jobs_state_started\n    ON jobs(state, started_at) WHERE state = 'active';\n\n-- Group operations: fast lookup by group_id\nCREATE INDEX IF NOT EXISTS idx_jobs_group_id\n    ON jobs(group_id) WHERE group_id IS NOT NULL;\n\n-- Pending jobs: compound index for priority-ordered retrieval\nCREATE INDEX IF NOT EXISTS idx_jobs_pending_priority\n    ON jobs(queue, state, priority DESC, run_at ASC) WHERE state IN ('waiting', 'delayed');\n\n-- Completed jobs: index for recovery ordering (issue #84)\nCREATE INDEX IF NOT EXISTS idx_jobs_completed_order\n    ON jobs(completed_at DESC) WHERE state = 'completed';\n\n-- Cron jobs (BLOB for MessagePack)\nCREATE TABLE IF NOT EXISTS cron_jobs (\n    name TEXT PRIMARY KEY,\n    queue TEXT NOT NULL,\n    data BLOB NOT NULL,\n    schedule TEXT,\n    repeat_every INTEGER,\n    priority INTEGER NOT NULL DEFAULT 0,\n    next_run INTEGER NOT NULL,\n    executions INTEGER NOT NULL DEFAULT 0,\n    max_limit INTEGER,\n    timezone TEXT,\n    unique_key TEXT,\n    dedup BLOB,\n    skip_missed_on_restart INTEGER NOT NULL DEFAULT 0,\n    skip_if_no_worker INTEGER NOT NULL DEFAULT 0,\n    prevent_overlap INTEGER NOT NULL DEFAULT 1,\n    job_options BLOB\n);\n\n-- Queue state persistence (optional)\nCREATE TABLE IF NOT EXISTS queue_state (\n    name TEXT PRIMARY KEY,\n    paused INTEGER NOT NULL DEFAULT 0,\n    rate_limit INTEGER,\n    concurrency_limit INTEGER,\n    rate_limit_duration INTEGER,\n    rate_limit_expires_at INTEGER\n);\n";
 /** Migration version table */
 export declare const MIGRATION_TABLE = "\nCREATE TABLE IF NOT EXISTS migrations (\n    version INTEGER PRIMARY KEY,\n    applied_at INTEGER NOT NULL\n);\n";
 /** Current schema version */
-export declare const SCHEMA_VERSION = 14;
+export declare const SCHEMA_VERSION = 16;
 /** All migrations in order */
 export declare const MIGRATIONS: Record<number, string>;

package/dist/infrastructure/persistence/schema.js

@@ -127,7 +127,9 @@ CREATE TABLE IF NOT EXISTS queue_state (
     name TEXT PRIMARY KEY,
     paused INTEGER NOT NULL DEFAULT 0,
     rate_limit INTEGER,
-    concurrency_limit INTEGER
+    concurrency_limit INTEGER,
+    rate_limit_duration INTEGER,
+    rate_limit_expires_at INTEGER
 );
 `;
 /** Migration version table */
@@ -138,7 +140,7 @@ CREATE TABLE IF NOT EXISTS migrations (
 );
 `;
 /** Current schema version */
-export const SCHEMA_VERSION = 14;
+export const SCHEMA_VERSION = 16;
 /** All migrations in order */
 export const MIGRATIONS = {
     1: SCHEMA,
@@ -199,5 +201,16 @@ CREATE INDEX IF NOT EXISTS idx_jobs_queue_created
     ON jobs(queue, created_at, id);
 CREATE INDEX IF NOT EXISTS idx_jobs_queue_state_created
     ON jobs(queue, state, created_at, id);
+`,
+    // Migrations 15-16: Rate-limit window (duration) + TTL auto-expiry on
+    // queue_state. One ALTER per migration ON PURPOSE: each runs in its own
+    // db.run with its own error-swallow, so a crash between the two leaves a
+    // retryable state (a two-ALTER string would abort at the first "duplicate
+    // column" on re-run and never execute the second statement).
+    15: `
+ALTER TABLE queue_state ADD COLUMN rate_limit_duration INTEGER;
+`,
+    16: `
+ALTER TABLE queue_state ADD COLUMN rate_limit_expires_at INTEGER;
 `,
 };

package/dist/infrastructure/persistence/sqlite.d.ts

@@ -204,13 +204,21 @@ export declare class SqliteStorage {
      * Persist a queue's control-state (paused / rate-limit / concurrency) so it
      * survives a server restart. Write-through on every pause/resume/limit change.
      */
-    saveQueueState(name: string, paused: boolean, rateLimit: number | null, concurrencyLimit: number | null): void;
+    saveQueueState(name: string, state: {
+        paused: boolean;
+        rateLimit: number | null;
+        concurrencyLimit: number | null;
+        rateLimitDuration?: number | null;
+        rateLimitExpiresAt?: number | null;
+    }): void;
     /** Load all persisted queue control-state rows (used by recover() on boot). */
     loadQueueState(): Array<{
         name: string;
         paused: boolean;
         rateLimit: number | null;
         concurrencyLimit: number | null;
+        rateLimitDuration: number | null;
+        rateLimitExpiresAt: number | null;
     }>;
     /** Drop a queue's persisted control-state (e.g. on obliterate). */
     deleteQueueState(name: string): void;

package/dist/infrastructure/persistence/sqlite.js

@@ -650,11 +650,11 @@ export class SqliteStorage {
      * Persist a queue's control-state (paused / rate-limit / concurrency) so it
      * survives a server restart. Write-through on every pause/resume/limit change.
      */
-    saveQueueState(name, paused, rateLimit, concurrencyLimit) {
+    saveQueueState(name, state) {
         this.safeWrite(() => {
             this.statements
                 .get('upsertQueueState')
-                .run(name, paused ? 1 : 0, rateLimit, concurrencyLimit);
+                .run(name, state.paused ? 1 : 0, state.rateLimit, state.concurrencyLimit, state.rateLimitDuration ?? null, state.rateLimitExpiresAt ?? null);
         });
     }
     /** Load all persisted queue control-state rows (used by recover() on boot). */
@@ -665,6 +665,8 @@ export class SqliteStorage {
             paused: row.paused === 1,
             rateLimit: row.rate_limit,
             concurrencyLimit: row.concurrency_limit,
+            rateLimitDuration: row.rate_limit_duration ?? null,
+            rateLimitExpiresAt: row.rate_limit_expires_at ?? null,
         }));
     }
     /** Drop a queue's persisted control-state (e.g. on obliterate). */

package/dist/infrastructure/persistence/statements.d.ts

@@ -67,4 +67,6 @@ export interface DbQueueState {
     paused: number;
     rate_limit: number | null;
     concurrency_limit: number | null;
+    rate_limit_duration: number | null;
+    rate_limit_expires_at: number | null;
 }

package/dist/infrastructure/persistence/statements.js

@@ -57,8 +57,8 @@ export const SQL_STATEMENTS = {
   `,
     updateCron: 'UPDATE cron_jobs SET executions = ?, next_run = ? WHERE name = ?',
     // Queue control-state persistence (#100): paused / rate-limit / concurrency.
-    upsertQueueState: 'INSERT OR REPLACE INTO queue_state (name, paused, rate_limit, concurrency_limit) VALUES (?, ?, ?, ?)',
-    loadQueueState: 'SELECT name, paused, rate_limit, concurrency_limit FROM queue_state',
+    upsertQueueState: 'INSERT OR REPLACE INTO queue_state (name, paused, rate_limit, concurrency_limit, rate_limit_duration, rate_limit_expires_at) VALUES (?, ?, ?, ?, ?, ?)',
+    loadQueueState: 'SELECT name, paused, rate_limit, concurrency_limit, rate_limit_duration, rate_limit_expires_at FROM queue_state',
     deleteQueueState: 'DELETE FROM queue_state WHERE name = ?',
 };
 /** Prepare all statements */

package/dist/infrastructure/scheduler/cronScheduler.d.ts

@@ -100,6 +100,11 @@ export declare class CronScheduler {
      */
     private tick;
     /** Fire a cron job with overlap and worker detection */
+    /**
+     * Reasons a due cron must not push right now. Evaluated BEFORE the
+     * executions increment in tick(), so skips never consume maxLimit budget.
+     */
+    private getSkipReason;
     private fireCronJob;
     /**
      * Get scheduler stats

package/dist/infrastructure/scheduler/cronScheduler.js

@@ -283,6 +283,35 @@ export class CronScheduler {
                 else {
                     newNextRun = executionTime;
                 }
+                // Skip decision comes BEFORE the executions increment: a skipped fire
+                // pushes no job, so it must not consume the maxLimit budget (a cron
+                // with maxLimit=N must deliver N jobs, not N-minus-skips — worst case
+                // skipIfNoWorker used to burn the whole budget with zero deliveries).
+                // The schedule still advances so the heap doesn't hot-loop on it.
+                const skipReason = this.getSkipReason(cron, now);
+                if (skipReason) {
+                    if (this.persistCron) {
+                        try {
+                            this.persistCron(cron.name, cron.executions, newNextRun);
+                        }
+                        catch (persistErr) {
+                            // Benign here: nothing was pushed, in-memory advance is enough;
+                            // the next successful persist catches the row up.
+                            cronLog.error('Failed to persist cron nextRun on skip', {
+                                name: cron.name,
+                                error: String(persistErr),
+                            });
+                        }
+                    }
+                    cron.nextRun = newNextRun;
+                    this.dashboardEmit?.('cron:skipped', {
+                        name: cron.name,
+                        queue: cron.queue,
+                        reason: skipReason,
+                    });
+                    toReinsert.push(entry);
+                    continue;
+                }
                 // PERSIST STATE FIRST (before pushing job to prevent duplicates)
                 if (this.persistCron) {
                     try {
@@ -339,27 +368,24 @@ export class CronScheduler {
         this.scheduleNext();
     }
     /** Fire a cron job with overlap and worker detection */
-    async fireCronJob(cron, now) {
+    /**
+     * Reasons a due cron must not push right now. Evaluated BEFORE the
+     * executions increment in tick(), so skips never consume maxLimit budget.
+     */
+    getSkipReason(cron, now) {
         // skipIfNoWorker: skip if no workers registered for this queue
         if (cron.skipIfNoWorker && this.hasWorkers && !this.hasWorkers(cron.queue)) {
-            this.dashboardEmit?.('cron:skipped', {
-                name: cron.name,
-                queue: cron.queue,
-                reason: 'no-worker',
-            });
-            return;
+            return 'no-worker';
         }
         // Overlap detection: skip if last fire was within repeatEvery window
         const lastFire = this.lastFiredAt.get(cron.name);
         const interval = cron.repeatEvery ?? 60000;
         if (lastFire && now - lastFire < interval * 0.8) {
-            this.dashboardEmit?.('cron:skipped', {
-                name: cron.name,
-                queue: cron.queue,
-                reason: 'overlap',
-            });
-            return;
+            return 'overlap';
         }
+        return null;
+    }
+    async fireCronJob(cron, now) {
         // preventOverlap: auto-set uniqueKey to block pushes while previous job is active
         const effectiveUniqueKey = cron.uniqueKey ?? (cron.preventOverlap ? `cron:${cron.name}` : undefined);
         const opts = cron.jobOptions;

package/dist/infrastructure/server/handlers/advanced.js

@@ -172,8 +172,17 @@ export function handleRateLimit(cmd, ctx, reqId) {
     const limit = toFiniteNumber(cmd.limit);
     if (limit === undefined)
         return resp.error('limit must be a finite number', reqId);
-    ctx.queueManager.setRateLimit(cmd.queue, limit);
-    ctx.queueManager.emitDashboardEvent('ratelimit:set', { queue: cmd.queue, max: limit });
+    // Optional window/TTL: invalid values degrade to the defaults (1s window,
+    // permanent limit) inside the limiter rather than failing the command.
+    const duration = toFiniteNumber(cmd.duration);
+    const ttl = toFiniteNumber(cmd.ttl);
+    ctx.queueManager.setRateLimit(cmd.queue, limit, duration, ttl);
+    ctx.queueManager.emitDashboardEvent('ratelimit:set', {
+        queue: cmd.queue,
+        max: limit,
+        ...(duration !== undefined && { duration }),
+        ...(ttl !== undefined && { ttl }),
+    });
     return resp.ok(undefined, reqId);
 }
 /** Handle RateLimitClear command */

package/dist/infrastructure/server/httpRouteQueueConfig.js

@@ -76,6 +76,8 @@ export async function routeQueueConfigRoutes(req, path, method, ctx, cors) {
             cmd: 'RateLimit',
             queue,
             limit: body['limit'],
+            duration: body['duration'],
+            ttl: body['ttl'],
         }, ctx);
         return jsonResponse(r, 200, cors);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunqueue",
-  "version": "2.8.34",
+  "version": "2.8.35",
   "description": "High-performance job queue for Bun & AI agents. SQLite persistence, cron scheduling, priorities, retries, DLQ, webhooks, native MCP server. Zero external infrastructure.",
   "type": "module",
   "main": "dist/main.js",