QUEUE

Filas FIFO

Filas simples por cliente: empilha mensagens, puxa a mais antiga primeiro, com espera curta opcional em vez de polling.

FIFO queues

Simple per-client queues: push messages, pull the oldest first, with an optional short wait instead of polling.

SYNC resposta na mesma chamada answers in the same call

Endpoints

POST /api/v1/queue/{name}/push empilha uma mensagem no fim da fila pushes a message to the end of the queue

POST /api/v1/queue/{name}/pull puxa a mensagem mais antiga pulls the oldest message

GET /api/v1/queue/{name}/stats profundidade atual da fila current queue depth

DELETE /api/v1/queue/{name} remove a fila inteira removes the entire queue

Fora de escopo v1: visibility timeout, ack/nack, dead-letter queue, garantia de entrega. É uma fila FIFO simples de push/pop: se uma mensagem é puxada e o cliente cai antes de processá-la, ela se foi, não existe "devolver pra fila" automático.

Out of scope for v1: visibility timeout, ack/nack, dead-letter queue, delivery guarantees. It's a plain FIFO push/pop queue: if a message is pulled and the client dies before processing it, it's gone, there's no automatic "return to queue".

Parâmetros

Parameters

Nome	Name	Onde	In
`name`	path	nome da fila, isolado por cliente: filas de nomes iguais de clientes diferentes não se enxergam	queue name, isolated per client: same-named queues from different clients never see each other
`message`	body	`/push`: texto da mensagem, dentro do limite de tamanho tunável (padrão 256KB)	`/push`: message text, within the tunable size limit (default 256KB)
`wait`	query	`/pull`: 0 a 5 segundos; sem ele, checagem imediata. Com ele, espera curta (long-poll) até chegar mensagem ou o tempo esgotar, em vez do cliente ficar repetindo a chamada	`/pull`: 0 to 5 seconds; without it, an immediate check. With it, a short wait (long-poll) until a message arrives or time runs out, instead of the client repeatedly polling

Exemplo

Example

curl -X POST "https://api.alicercelabs.com.br/api/v1/queue/pedidos/push" \
          -H "Authorization: Bearer <token>" \
          -H "Content-Type: application/json" \
          -d '{"message":"pedido-4231"}'

{
          "success": true,
          "data": { "message": "enfileirado" },
          "meta": { "elapsed_ms": 4, "request_id": "..." }
        }

curl -X POST "https://api.alicercelabs.com.br/api/v1/queue/pedidos/pull?wait=3" \
          -H "Authorization: Bearer <token>"

{
          "success": true,
          "data": { "message": "pedido-4231" },
          "meta": { "elapsed_ms": 812, "request_id": "..." }
        }

Erros possíveis

Possible errors

Status	Motivo	Reason
400	nome de fila inválido, corpo inválido, mensagem vazia, maior que o limite, ou profundidade máxima da fila atingida	invalid queue name, invalid body, empty message, over the size limit, or the queue's max depth reached
401	token ausente ou inválido	missing or invalid token
404	fila vazia: imediatamente, ou depois do `wait=` sem achar nada	empty queue: immediately, or after `wait=` found nothing
429	limite de taxa excedido	rate limit exceeded

Usando o SDK

Using the SDK

FIFO simples: pull faz long-poll (espera até wait segundos por uma mensagem antes de devolver vazio).

Simple FIFO: pull long-polls (waits up to wait seconds for a message before returning empty).

SDKs oficiais: Go · Python · JavaScript.

Official SDKs: Go · Python · JavaScript.

Empilhar / consumir uma mensagem

Push / pull a message

import (
	"context"
	"fmt"

	alicercelabs "github.com/alicercelabs/alicercesdk-go"
)

client := alicercelabs.New("alk_...")
ctx := context.Background()

err := client.Queue.Push(ctx, "pedidos", "pedido-123")

msg, ok, err := client.Queue.Pull(ctx, "pedidos", 3) // long-poll de até 3s
if ok {
	fmt.Println(msg)
}

from alicercelabs import AlicerceLabs

client = AlicerceLabs(api_key="alk_...")

client.queue.push("pedidos", "pedido-123")

msg = client.queue.pull("pedidos", wait=3)  # long-poll de até 3s, None se vazio
if msg is not None:
    print(msg)

import { AlicerceLabs } from "alicercesdk-javascript";

const client = new AlicerceLabs("alk_...");

await client.queue.push("pedidos", "pedido-123");

const msg = await client.queue.pull("pedidos", 3); // long-poll de até 3s, null se vazio
if (msg !== null) console.log(msg);

Ver profundidade da fila

Check queue depth

stats, err := client.Queue.Stats(ctx, "pedidos")
fmt.Println(stats.Depth)

stats = client.queue.stats("pedidos")
print(stats["depth"])

const stats = await client.queue.stats("pedidos");
console.log(stats.depth);

Remover uma fila

Delete a queue

err := client.Queue.Delete(ctx, "pedidos")

client.queue.delete("pedidos")

await client.queue.delete("pedidos");

Limites

Limits

1.000/dia · 41/hora por operação (push e pull têm cotas separadas, escrita é o que pode esgotar a profundidade de uma fila). Profundidade máxima: 10.000 mensagens por fila. Tamanho máximo de mensagem: 256KB. Ambos tunáveis por cliente via admin.

1,000/day · 41/hour per operation (push and pull have separate quotas, writes are what can exhaust a queue's depth). Max depth: 10,000 messages per queue. Max message size: 256KB. Both tunable per client via admin.