Queue throttling and controls

These are Core and are applied by the server when a worker claims a task, whatever language the worker is written in. They are not the same as rate limiting, which your own code calls (see Comparisons).

Pause, resume, clear, concurrency

From the console's Queues page or the API (operator):

Route	Effect
POST /api/v1/queues/:name/pause, .../resume	Workers stop taking the queue's jobs; the pause is shared by every process
PUT /api/v1/queues/:name/concurrency	Asks for a different concurrency on the queue. The SDK gateway enforces it at claim time: the queue's jobs and the workflow steps sent to it as a task queue share the limit
POST /api/v1/queues/:name/clear	Deletes every waiting job of the queue

The SDK gateway has no route for these: management happens in the console, and the gateway applies it when it hands out tasks.

The Queues page: pause, resume, clear and concurrency per queue (mock data).

Throttling

A JoobQ queue can carry a throttle, {limit, period}: at most limit jobs per period. In Crystal it is the fourth argument of the queue macro:

JoobQ.configure do
  queue "my_queue", 10, MyJob, {limit: 100, period: 1.minute}
end

For SDK workers, the gateway applies a queue's throttle when it hands out tasks: one claim per period / limit (in whole milliseconds, at least 1 ms), cluster-wide (a Redis key per queue), and one task per poll from a throttled queue. So limit: 100, period_ms: 60000 is one claim every 600 ms; a limit above period_ms gives one claim per millisecond. An empty queue spends no throttle slot. The throttle comes from one of two places, shown as the throttle's source on the queue:

• config: the queue is defined in the server's JoobQ configuration (JoobQ.config.queues) with a throttle. Change it there; the console and the API refuse to change it (409).

• console: a queue the configuration does not define, such as one that only SDK workers serve, gets its throttle from the console's Queues page or from the API (operator):

  curl -X PUT "$JOOBQUI_URL/api/v1/queues/emails/throttle" -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" -d '{"limit": 10, "period_ms": 60000}'

  limit is 1 to 100,000 and period_ms 1 s to a day. DELETE /api/v1/queues/:name/throttle removes it (also for a queue no worker serves any more). Both are audited (queue.throttle, queue.unthrottle) and take effect on the next claim, on every instance: a change also drops the slot the old rate was holding.

A console throttle is applied by the SDK gateway only: Crystal workers read their throttle from their own JoobQ configuration. For a rate your code controls, per key rather than per queue, use rate limiting (Pro).