Message Handling Semantics

Lets survey a few scenarios. Given a message, what can you do with it?

Anyway, given a message:

• If it leads to a job well done, you can acknowledge it so that the broker can know it can safely remove it from the queue.
• If the job errored, you can reject it. The broker can then either discard it or direct it to a dead-letter box; with RabbitMQ this is called a Dead-Letter-Exchange, or a DLX. You can configure what happens when you reject and where it goes - read more here.
• If the job timeouted (perhaps the resource you are trying to work with isn't available, e.g. 3rd party web service), you can reject it. requeue (reject with requeue=true) doesn't make much sense because client pushes requeued message to the front of the queue so there is almost no delay before re-processing. Instead consider to use Maxretry handler based on DLX.

Sneakers supports these directly, and you can use the matching methods in your worker

• ack!
• reject!
• requeue!

Internally, sneakers will also report a couple more events

• error for unexpected errors
• timeout for non-fitted in time frame jobs
• noop when all went well, but no ack! was given

These semantics are translated into AMQP constructs by Sneakers. And the best thing is - you can change them! (it can be a bad thing if someone else changed them without you knowing, though :)

Here's how the Oneshot handler looks like today:

      def initialize(channel)
        @channel = channel
      end

      def acknowledge(tag)
        @channel.acknowledge(tag, false)
      end

      def reject(tag, requeue=false)
        @channel.reject(tag, requeue)
      end

      def error(tag, err)
        reject(tag)
      end

      def timeout(tag)
        reject(tag)
      end

      def noop(tag)

      end

If you implement your own handler, you can inject it globally in your configuration block:

Sneakers.configure(handler: YourHandlerClass )

Please check out Messaging Pitfalls to understand better the issues may arise on message handling.