Skip to content

User's Guide

Consumption Models

Hooque supports two primary ways to consume messages: Pull and Streaming (SSE).

1. Pull (Request-Response)

The Pull model is the simplest way to consume messages. You make an HTTP GET request to the queue, and if a message is available, it is returned immediately.

  • Endpoint: GET /queues/:id/next (where :id is your Queue ID)
  • Behavior:
  • If a message is ready, returns 200 OK with the payload.
  • If the queue is empty, returns 204 No Content.
  • Concurrency: You can have multiple workers pulling simultaneously. Hooque ensures that a message is delivered to only one worker at a time (locked).

2. Streaming (Server-Sent Events)

For real-time applications or high-throughput scenarios, you can open a persistent connection using Server-Sent Events (SSE).

  • Endpoint: GET /queues/:id/stream
  • Behavior: The server keeps the connection open and pushes new messages as events as soon as they arrive.
  • Event Type: message
  • Data: A JSON object containing payload and meta.

Message Lifecycle

When a message is delivered to a consumer, it enters a Pending state. It is temporarily locked (invisible to other consumers) until one of the following happens:

  1. Ack (Acknowledge): The consumer successfully processed the message. Hooque deletes the message from the queue.
  2. Nack (Negative Acknowledge): The consumer failed to process the message temporarily (e.g., database glitch). Hooque releases the lock, and the message becomes available for redelivery (subject to retry policies).
  3. Reject: The consumer cannot process the message (e.g., invalid data). Hooque moves the message to a Dead Letter Queue (or discards it based on policy).
  4. Timeout: If the consumer doesn't Ack/Nack within the visibility timeout (default: 30s), Hooque automatically Nacks it, making it available for redelivery.

Auto-Ack

For simple use-cases where you don't need "at-least-once" guarantees or handle failures manually, you can use the autoAck=true query parameter.

GET /queues/:id/next?autoAck=true

In this mode, Hooque automatically acknowledges the message as soon as it is delivered to you. If your worker crashes after receiving the message but before processing it, the message is lost. Use with caution.

Control Headers and Metadata

Responses from the Pull API include headers to help you manage the flow.

X-Hooque-Meta

This header contains a JSON object with metadata about the message: - deliveryId: Unique ID for this specific delivery attempt. - attempts: How many times this message has been delivered. - ackUrl, nackUrl, rejectUrl: Complete URLs to perform the respective actions.

We follows standard hypermedia controls. You will find links with rel="ack", rel="nack", and rel="reject" in the Link header.

Link: <https://app.hooque.io/queues/cons_1/ack/del_2?leaseId=abc>; rel="ack", ...