Flow control

Three rules get mistaken for each other. Throttling bounds how fast jobs dispatch — every call still runs, just later. Coalescing drops a call that is identical to one already queued — the first job wins and never moves. Debouncing keeps one job per key and slides its deadline forward on every call — the burst runs once, after it stops. A throttle is about rate, a coalesce is about duplicates, a debounce is about quiet.

Throttle: every call runs, at a bounded rate

A token bucket per task name, enforced at the scheduler, so "10/s" means ten per second across the whole deployment. A hundred calls become a hundred jobs; the tenth second is when the hundredth runs.

@queue.task(rate_limit="10/s")
def call_api(endpoint: str) -> dict:
    return requests.get(endpoint).json()

queue.task("callApi", callApi, { rateLimit: "10/s" });

Task<String> CALL_API = Task.of("call-api", String.class).rateLimit("10/s");

Coalesce: identical calls become one job

A dedup key pins the first job. A second enqueue carrying the same key while that job is pending or running resolves to its id instead of inserting a row — same job, same deadline, nothing moves.

@queue.task(idempotent=True)          # key = hash(task name + arguments)
def charge(customer_id: int, cents: int) -> str: ...

first = charge.delay(42, 1000)
second = charge.delay(42, 1000)
assert second.id == first.id          # coalesced onto the first job

const first = queue.enqueue("charge", [42, 1000], { uniqueKey: "charge:42:1000" });
const second = queue.enqueue("charge", [42, 1000], { uniqueKey: "charge:42:1000" });
// second === first — coalesced onto the first job

Task<Order> CHARGE = Task.of("charge", Order.class).idempotent(true);

String first = flexiq.enqueue(CHARGE, order);
String second = flexiq.enqueue(CHARGE, order);  // same id — coalesced

Debounce: the burst runs once, after it stops

A window keyed on the payload. While a job with the same resolved key is pending and unclaimed, the enqueue slides that job's deadline instead of inserting a second one.

@queue.task(
    debounce="5m",                    # slide the run 5 minutes out per call
    debounce_key="report:{user_id}",  # one window per user
    debounce_max_wait="30m",          # but never delay past 30 minutes
)
def build_report(user_id: str) -> None: ...

build_report.delay("u1")              # creates the job
build_report.delay("u1")              # same job id — deadline moves

queue.task("buildReport", buildReport, {
  debounce: "5m", // slide the run 5 minutes out per call
  debounceKey: "report:{userId}", // one window per user
  debounceMaxWait: "30m", // but never delay past 30 minutes
});

queue.enqueue("buildReport", [{ userId: "u1" }]); // creates the job
queue.enqueue("buildReport", [{ userId: "u1" }]); // same job id — deadline moves

Task<Report> BUILD_REPORT = Task.of("build-report", Report.class)
        .debounce(
                Duration.ofMinutes(5),    // slide the run 5 minutes out per call
                "report:{userId}",        // one window per user
                Duration.ofMinutes(30));  // but never delay past 30 minutes

flexiq.enqueue(BUILD_REPORT, new Report("u1", 1));  // creates the job
flexiq.enqueue(BUILD_REPORT, new Report("u1", 2));  // same id — deadline moves

Which one you want follows from the question you are answering:

A dedup key and a debounce window cannot be combined — one pins the job, the other moves it — and setting both is an error rather than a precedence rule.

What already ships

The whole flow-control family, in one place:

See Rate limiting, Concurrency, and Circuit breakers for each in depth, and Debouncing for the full debounce surface.

Max wait is mandatory

A window with no ceiling is an unbounded delay. A caller who never stops enqueuing slides the deadline forever and the job never runs — the classic debounce footgun, and the reason a window without a max wait is refused up front rather than accepted and regretted:

@queue.task(debounce="5m", debounce_key="report:{user_id}")
def build_report(user_id: str) -> None: ...
# ValueError: debounce=... requires debounce_max_wait=... — an unbounded
# debounce starves the job while enqueues keep arriving

queue.task("buildReport", buildReport, {
  debounce: "5m",
  debounceKey: "report:{userId}",
});
// QueueError at registration: debounce requires debounceMaxWait — without a
// ceiling a caller who keeps enqueuing starves the job forever

EnqueueOptions.builder()
        .debounce(Duration.ofMinutes(5))
        .debounceKey("report:{userId}")
        .build();
// IllegalArgumentException at build(): a window requires a max wait

The ceiling is measured from when the window opened, not from the latest call, so the deadline is min(now + window, first_seen + max_wait). A user who edits for two hours straight still gets a report every thirty minutes. It may never be shorter than the window itself — that would cap the very first insert and make the window meaningless.

The key must come from the payload

Write the key without a placeholder and every caller shares one window. Under steady traffic from many users, that means one report every max_wait — for whichever user happened to open the window, while everyone else's edits go unrebuilt:

# Wrong: one window for every user on the platform.
@queue.task(debounce="5m", debounce_key="report", debounce_max_wait="30m")
def build_report(user_id: str) -> None: ...

// Wrong: one window for every user on the platform.
queue.task("buildReport", buildReport, {
  debounce: "5m",
  debounceKey: "report",
  debounceMaxWait: "30m",
});

// Wrong: one window for every user on the platform.
Task<Report> BUILD_REPORT = Task.of("build-report", Report.class)
        .debounce(Duration.ofMinutes(5), "report", Duration.ofMinutes(30));

The key is a template resolved against each call's arguments, so the unit of collapsing is whatever the placeholder names:

@queue.task(debounce="5m", debounce_key="report:{user_id}", debounce_max_wait="30m")
def build_report(user_id: str) -> None: ...

queue.task("buildReport", buildReport, {
  debounce: "5m",
  debounceKey: "report:{userId}",
  debounceMaxWait: "30m",
});

Task<Report> BUILD_REPORT = Task.of("build-report", Report.class)
        .debounce(Duration.ofMinutes(5), "report:{userId}", Duration.ofMinutes(30));

A placeholder the call cannot fill throws at enqueue and inserts nothing. Falling back to the literal template would silently produce the global window above, which is the failure debouncing exists to avoid. A key with no placeholder is still legal — it just has to be a deliberate choice, spelled out.

Dropping instead of deferring

A saturated rate limit defers: the job keeps its place and dispatches once tokens are available. That is the right default, but some work is worth less than the backlog it would build — a metrics sample, a cache warm, a presence ping. For those, drop the excess:

@queue.task(rate_limit="10/s", on_excess="drop")
def record_sample(metric: str, value: float) -> None: ...

queue.task("recordSample", recordSample, {
  rateLimit: "10/s",
  onExcess: "drop",
});

Task<Sample> RECORD_SAMPLE = Task.of("record-sample", Sample.class)
        .rateLimit("10/s")
        .onExcess(OnExcess.DROP);

Dropped is not deleted. The job is dead-lettered on the spot, so shedding is something an operator can see rather than something they have to infer from a missing run.

How a dropped job looks in the dashboard

It appears in Dead letters, newest first, alongside genuine failures — with three things that tell it apart:

A CoDel shed looks the same shape with a codel: reason and {"codel":true} metadata. The reserved prefix is what the scheduler itself reads: the dead-letter auto-retry sweep skips any entry wearing one, because resurrecting a job the scheduler deliberately dropped would undo the shed. The dashboard's own Retry button is not gated — a manual retry re-enqueues a shed entry like any other, which is what you want when you shed by mistake.

Three more things worth knowing before turning it on:

• The DLQ row's metadata is the shed marker, so it replaces the job's own metadata there. The archived job row keeps the original.
• Dropping fires no middleware and no events. The job never ran, so there is no outcome to report — the dead-letter row is the record. Dependents of a shed job cascade-cancel, exactly as they would after a failure.
• A tripped circuit breaker always defers regardless of on_excess. That is a downstream failure, not excess load: the job is fine, its dependency is not.

CoDel is the other shed path, and it is deliberately harder to trigger — a queue's jobs have to sit past target_ms for a full interval_ms before anything is dropped, so a transient spike is absorbed rather than shed.

Backend notes

The debounce decision — slide the pending job or insert a new one — has to be atomic. A job claimed a microsecond ago must never be pulled back to a later deadline once a worker holds it, so the read, the status guard, and the write are one operation. Each backend gets that differently:

Redis has no transaction to lean on, so the slide-or-insert decision is made inside the script, and a slide commits as a compare-and-swap on the job document. Contended enough to lose that swap repeatedly, the call errors rather than inserting a second job: failing an enqueue is recoverable, quietly double-running the work is not. Everything else about the semantics — the min(now + window, first_seen + max_wait) deadline, the claimed-row guard, the key's independence — is identical on all three. See Debouncing for the surface those guarantees back.