OKMQ - Queues Guide

What are Queues?

Queues are the core of OKMQ. They store messages in order and deliver them to consumers reliably. Each queue has its own configuration for retry strategies, TTL, acknowledgment modes, and more.

FIFO Ordering

Messages are delivered in first-in, first-out order

Persistent Storage

Messages survive server restarts and crashes

Configurable Retries

Multiple retry strategies for failed deliveries

Auto-cleanup

TTL support removes expired messages automatically

Creating Queues

Create a queue by sending a POST request to /queues/ with the queue configuration.


const createQueue = async () => {
  const response = await fetch('https://api.okmq.net/queues/', {
    method: 'POST',
    headers: {
      authorization: `Bearer ${token}`,
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      name: 'order-processing',
      auto_ack: false,           // Manual acknowledgment
      ttl: 3600,                // 1 hour TTL
      max_delivery_attempts: 5,  // Try up to 5 times
      lock_duration: 60,        // Lock messages for 60 seconds
      topics: ['orders', 'payments'], // Subscribe to these topics
      retry_strategy: {
        type: 'exponential',
        base_delay: 5,          // Start with 5 second delay
        max_delay: 300,         // Cap at 5 minutes
        multiplier: 2.0         // Double delay each retry
      }
    }),
  })
}

Parameter	Type	Description	Default
`name`	string	Unique queue name (max 50 characters)	Required
`auto_ack`	boolean	Automatically acknowledge messages	false
`ttl`	number	Message time-to-live in seconds	300
`retry_strategy`	object	Retry configuration (see examples below)	exponential
`max_delivery_attempts`	number	Maximum delivery attempts	1
`lock_duration`	number	Message lock duration in seconds	30
`topics`	array	Topics to subscribe to for fan-out messaging	[]

Retry Strategies

When message processing fails, OKMQ can automatically retry delivery using different strategies.

Exponential Backoff

Delays increase exponentially: 5s, 10s, 20s, 40s, 80s...


{
  "type": "exponential",
  "base_delay": 5,      // Initial delay (seconds)
  "max_delay": 300,     // Cap at 5 minutes
  "multiplier": 2.0     // Double each time
}

Linear Backoff

Delays increase linearly: 10s, 20s, 30s, 40s...


{
  "type": "linear",
  "base_delay": 10,     // Starting delay (seconds)
  "max_delay": 120      // Cap at 2 minutes
}

Fixed Delay

Constant retry delay: 30s, 30s, 30s...


{
  "type": "fixed",
  "base_delay": 30      // Fixed delay (seconds)
}

No Retries

Failed messages are immediately discarded


{
  "type": "none"
}

TTL and Cleanup

Set time-to-live (TTL) values to automatically clean up expired messages and prevent queue bloat. TTL is evaluated and expired messages are deleted every minute.

Getting Queue Information

Retrieve queue configuration and statistics using GET requests. This provides both the queue settings and real-time message counts.


const getQueueInfo = async (queueName) => {
  const response = await fetch(`https://api.okmq.net/queues/${queueName}`, {
    headers: {
      authorization: `Bearer ${token}`,
      'content-type': 'application/json'
    }
  })
  
  if (response.ok) {
    const queueInfo = await response.json()
    console.log('Queue configuration:', queueInfo)
    return queueInfo
  }
}

// Example response
{
  "name": "order-processing",
  "auto_ack": false,
  "lock_duration": 60,
  "max_delivery_attempts": 3,
  "ttl": 3600,
  "retry_strategy": {
    "type": "exponential",
    "base_delay": 5,
    "max_delay": 300,
    "multiplier": 2.0
  },
  "topics": ["orders", "payments"],
  "acked": 1250,
  "enqueued": 45,
  "failed": 12,
  "scheduled": 8
}

Configuration Fields

name - Queue name
auto_ack - Auto acknowledgment setting
lock_duration - Message lock time (seconds)
max_delivery_attempts - Retry limit
ttl - Message TTL (seconds)
retry_strategy - Retry configuration
topics - Subscribed topics

Statistics Fields

acked - Successfully processed messages
enqueued - Messages ready for processing
failed - Messages that exceeded retry limit
scheduled - Messages scheduled for future delivery

Statistics are updated in real-time and can be used for monitoring queue health and performance.

Deleting Queues

Delete a queue and all its messages by sending a DELETE request to the queue endpoint.


const deleteQueue = async (queueName) => {
  const response = await fetch(`https://api.okmq.net/queues/${queueName}`, {
    method: 'DELETE',
    headers: {
      authorization: `Bearer ${token}`,
      'content-type': 'application/json',
    }
  })
  
  if (response.ok) {
    console.log(`Queue ${queueName} deleted successfully`)
  }
}

Warning: Deleting a queue permanently removes the queue and all its messages. This action cannot be undone.