Idempotency

@queue.task(idempotent=True)
def charge_customer(customer_id: int, amount_cents: int) -> str:
    return payment_provider.charge(customer_id, amount_cents)

job1 = charge_customer.delay(42, 1000)
job2 = charge_customer.delay(42, 1000)

assert job1.id == job2.id  # second call coalesced into the first

idempotent=True also works as a per-call override on apply_async() for a task that wasn't registered idempotent by default.

public static final Task<Order> CHARGE_CUSTOMER =
        Task.of("charge_customer", Order.class).idempotent(true);

String first = queue.enqueue(CHARGE_CUSTOMER, order);
String second = queue.enqueue(CHARGE_CUSTOMER, order); // same id — coalesced into the first

EnqueueOptions.Builder.idempotent(boolean) is the same toggle as a per-call override on a task that isn't idempotent by default.

.idempotent() on the call derives the key, and #[flexiq::task(idempotent)] makes it the default for every call of that task:

#[flexiq::task(idempotent)]
fn charge_customer(customer_id: i64, amount_cents: i64) -> flexiq::Outcome<()> {
    Ok(())
}

let first = queue.enqueue(charge_customer::call(42, 1_000))?;
let second = queue.enqueue(charge_customer::call(42, 1_000))?;

assert_eq!(first.id, second.id); // second call coalesced into the first

An explicit .unique_key(..) on the same call beats .idempotent().

There's no idempotent flag to auto-derive this key for you (see above), but the recipe itself is public — build the same string yourself if you need a Node producer's key to collide with a Python or Java producer's.

The crate pins the digest rather than merely asserting it is stable against itself: a test asserts that one known call derives auto:c3abb8ce58c62cb737c17b92beb816be, the exact string a producer in another language computes for the same (task_name, payload) pair. Getting the NUL separator or the 32-character truncation wrong still enqueues — it only stops deduping across the boundary — so the expected value is written out where a change to it fails the build.

apply_async() and enqueue_many() accept three overlapping inputs; the first one set wins:

Precedence, high to low: unique_key → idempotency_key → auto-derivation (when idempotent is True, or the task default is, and no explicit key was given).

EnqueueOptions accepts the same three overlapping inputs, resolved with identical precedence before the enqueue call reaches native code — idempotent/idempotencyKey never cross the JNI boundary themselves, only the resolved uniqueKey does:

Precedence, high to low: uniqueKey → idempotencyKey → auto-derivation (when idempotent is true, or the task default is, and no explicit key was given).

There's only one input — uniqueKey — so there's no precedence to resolve. Omit the option to skip dedup for that call.

Two inputs, on EnqueueOptions and on TaskCall alike:

There is no idempotency_key alias, and no way to turn derivation off for one call — .idempotent() takes no argument and only ever sets the flag. A task declared #[flexiq::task(idempotent)] therefore dedupes on every call unless that call names its own .unique_key(..).

enqueueMany routes any job carrying a key through the same check-then-insert path as a single enqueue — a duplicate inside the batch, or one that collides with an already-active job, resolves to the existing job's id instead of failing the batch:

List<String> ids = queue.enqueueMany(CHARGE_CUSTOMER, orders, once);
// duplicates map to the already-enqueued job's id, in input order

enqueue_many() still accepts unique_keys, idempotency_keys, and a uniform idempotent=True to resolve a key per row — just make sure the resulting keys are distinct, or don't rely on dedup for that call:

queue.enqueue_many(
    task_name="myapp.charge_customer",
    args_list=[(42, 1000), (43, 2000)],  # pre-deduplicated by the caller
    idempotent=True,
)

When collision resilience matters more than throughput, loop apply_async() calls instead — each one goes through the coalescing check-then-insert path.

enqueueMany routes any entry carrying a uniqueKey through the same check-then-insert path as a single enqueue — a duplicate inside the batch, or one that collides with an already-active job, resolves to the existing job's id instead of failing the batch:

const ids = queue.enqueueMany("chargeCustomer", [
  { args: [42, 1000], options: { uniqueKey: "charge:42" } },
  { args: [42, 1000], options: { uniqueKey: "charge:42" } },
]);
// ids[0] === ids[1] — one job, the duplicate maps to it, in input order

A batch carrying no uniqueKey at all keeps the plain bulk insert, so it costs exactly what it did before; a single keyed entry switches the whole batch to the check-then-insert path — still one storage call either way.

enqueue_batch switches the whole batch onto the unique check-then-insert path as soon as one call in it carries a key, explicit or derived. A duplicate inside the batch, or one colliding with an already-active job, resolves to the existing job instead of failing the call:

let jobs = queue.enqueue_batch(vec![
    charge_customer::call(42, 1_000).idempotent(),
    charge_customer::call(42, 1_000).idempotent(),
])?;
// the duplicate resolves onto the already-active job rather than failing

A batch where no call carries a key keeps the plain bulk insert — one transaction either way. A call carrying a debounce window is the one thing a batch refuses outright, because storage has no batched debounce to hand it to; enqueue that call on its own.

• Don't derive a key from a moving value. datetime.now(), uuid4(), and similar produce a different hash on every call, so auto-derived dedup never triggers. Move them inside the task body or pass a stable identifier instead.
• Argument order affects the hash. charge(42, 1000) and charge(amount=1000, customer_id=42) serialize differently and therefore hash differently. Be consistent at the call site, or use an explicit idempotency_key.
• Changing the serializer changes the hash. The hash survives a codec change (it's taken pre-codec) but not a serializer change between releases — in-flight jobs from the old release won't dedupe against new submissions. Use an explicit idempotency_key for keys that must survive a deploy.
• queue.test_mode() skips dedup. Tasks run synchronously without storage in test mode, so idempotency is a no-op there.

• Don't derive a key from a moving value. A timestamp, a random UUID, or similar produces a different hash on every call, so auto-derived dedup never triggers. Move it inside the handler or pass a stable identifier instead.
• Argument order affects the hash. The auto-key hashes the serialized payload, so two payloads that are semantically equal but serialize differently (field order in a hand-built JSON payload, for example) hash differently. Use an explicit .idempotencyKey(...) when that risk exists.
• Changing the serializer changes the hash. The hash survives a codec change (it's taken pre-codec) but not a serializer change between releases — in-flight jobs from the old release won't dedupe against new submissions. Use an explicit .idempotencyKey(...) for keys that must survive a deploy.

Whatever you build uniqueKey from, keep it stable for the equality you want — a timestamp or a random id defeats dedup entirely, since every call then gets its own key.

• Don't derive a key from a moving value. An argument holding a timestamp or a freshly generated id hashes differently on every call, so .idempotent() never dedupes. Generate it inside the body, or pass a stable identifier.
• Argument order is part of the hash, and so is struct field order. The digest runs over the encoded payload, and the encoder keeps map keys in insertion order on purpose — sorting them behind the caller's back would change an identity. Reordering a task's parameters, or the fields of a type it takes, changes what dedupes against what.
• There is no serializer to swap. The payload codec is the wire CBOR and it is fixed, so the hash cannot drift from a codec change between releases. Use an explicit .unique_key(..) for a key that has to survive a change to the arguments themselves.
• A debounce window silently beats a key. enqueue matches on the window before it looks at the dedup key, so a call carrying both never derives the auto: key and never runs a dedup lookup at all.