Queues

A queue holds messages until your code processes them, so slow or unreliable work moves out of the request that triggered it. Use one to send email after a sign-up, process an upload, fan out webhooks, or run something every weekday at 08:00.

Push and pull

Every queue belongs to one environment, and how its messages reach your code depends on one setting, the consumer path.

Push suits most apps: there is no worker to run, and deliveries scale with your Functions. Pull suits a worker that lives somewhere else, or work you want to drain on your own schedule.

Send and consume a message

The queue does not need to exist before the first send: sending to a new name creates a pull queue with default settings. The push consumer in this example is a Next.js route handler.

// lib/queues.ts
import { queue } from '@gigadrive/sdk';

export const emails = queue<{ to: string; template: string }>('emails');

// app/signup/actions.ts: send from anywhere in your app
import { emails } from '@/lib/queues';

await emails.send({ to: 'jane@example.com', template: 'welcome' });
await emails.send({ to: 'jane@example.com', template: 'nudge' }, { delay: '3d' });

// app/api/queues/emails/route.ts: the push consumer
import { emails } from '@/lib/queues';

export const POST = emails.handler(async (email) => {
  await sendEmail(email.to, email.template);
});

Inside a deployed Function the client needs no configuration: it authenticates with the Function's own credential, described in OIDC federation, and verifies push deliveries with a signing secret the platform injects.

To make emails a push queue, declare its consumer in gigadrive.yaml:

services:
  queues:
    emails:
      consumer: /api/queues/emails

What a queue guarantees

• At least once. A message is delivered until your code acknowledges it or it runs out of attempts. A delivery can repeat after a timeout or a crash, so make processing idempotent.
• No global order. Messages are delivered roughly in the order they became due. When order matters, give related messages the same ordering group key and they are delivered one at a time, in send order.
• Retries, then dead letters. A failed delivery is retried with exponential backoff, up to 10 attempts by default. A message that exhausts them moves to the queue's dead-letter list, where you can inspect it and send it back.

In the console

Open an environment and select Queues to see every queue with its live depth: Ready, Scheduled, In flight and Dead letters. The Last 24 hours column shows how many messages each queue received and how many deliveries failed. A queue's page also shows Waiting, the messages held behind an earlier message of their ordering group, and how much data the queue stores.

The Activity card on a queue's page charts the last hour, 24 hours or 7 days, each compared with the period before it:

• Sent and Delivered: messages the queue accepted and messages your code acknowledged. When Sent stays above Delivered, a backlog is building.
• Failed deliveries: deliveries that returned an error, timed out or were not acknowledged before their lease ended. Dead-lettered counts the messages that ran out of attempts.
• Average delivery lag: the time from when a message was due until your code acknowledged it.

From a queue's page you can:

• Send a test message with Send message.
• Browse messages without taking them, cancel a scheduled message, or delete any other message.
• Retry one dead letter, or every dead letter with Retry all.
• Pause deliveries, change settings and manage schedules.
• Delete the dead letters, every message, or the queue itself from More actions.