Understanding Acknowledgements in Kyo͞o

What Are Acknowledgements?

In queue-based systems like Kyo͞o, an acknowledgement (commonly referred to as ack) is a confirmation sent by a worker to the queue broker, indicating that a job has been successfully processed. Acknowledging a job signals to the broker that it can safely remove the job from the queue, preventing the job from being redelivered.

Negative Acknowledgements

A negative acknowledgement (commonly referred to as nack) is the opposite of an ack. It informs the broker that a job has failed or could not be processed correctly. When a worker issues a negative acknowledgement, it indicates that the job should either be discarded or re-enqueued, depending on the specified parameters.

Using Acknowledgements and Negative Acknowledgements in Kyo͞o

In Kyo͞o, acknowledgements and negative acknowledgements are managed using the following interfaces:

Acknowledgement (Ack)

export interface KyooJobAck {
  (): Promise<void>;
}

Ack Usage Examples

await ack();

Calling ack() confirms the successful processing of the job, and the job is then permanently removed from the queue.

Negative Acknowledgement (Nack)

export interface KyooJobNack {
  (requeue?: "start" | "end" | boolean): Promise<void>;
}

Nack Usage Examples

await nack();           // Discard job (no requeue)
await nack(true);       // Requeue job at start (next to process)
await nack("start");    // Requeue job at start (next to process)
await nack("end");      // Requeue job at end (last to process)

Understanding the "Requeue" Options in Negative Acknowledgements

The requeue parameter in nack() determines if and how a job should be returned to the queue after being negatively acknowledged:

• true or "start":

  • The job is immediately requeued and placed at the front of the queue.
  • The job will be the next one processed by available workers.

• "end":

  • The job is requeued at the end of the queue.
  • It will be processed only after all currently enqueued jobs.

• false or omitted:

  • The job is discarded.
  • It will not be requeued or reprocessed.

Broker-specific Behavior

Due to broker-specific constraints, Kyo͞o handles negative acknowledgements slightly differently for each supported queue broker:

Broker	nack("start")	nack("end")
AMQP	Job placed at start unless honoring maxAttempts, in which case job is placed at the end.	Job explicitly placed at end.
BullMQ (Redis)	Job placed at start (using lifo).	Job explicitly placed at end.
Amazon SQS	Job is deleted and re-enqueued immediately (new message added at front is not supported, thus job is effectively placed at end).	Job explicitly placed at end.

Important:

• Due to AMQP limitations, if a job must respect the maxAttempts constraint, it cannot reliably be placed at the start. Instead, the job is requeued at the end of the queue in such cases.

Practical Recommendations

• Use ack (ack()) to finalize job processing and prevent redelivery.
• Use nack (nack()) without requeue to discard permanently failing jobs.
• Use nack with requeue (nack("start"), nack("end")) for retrying failed jobs based on your desired processing order.