Aan de slag

Events en wachtrijen: Valkey, NATS en RabbitMQ.

Achtergrondtaken, events en berichten tussen de diensten van een applicatie: wanneer je Valkey, NATS of RabbitMQ kiest, de verbindingsvariabelen, voorbeelden voor Laravel, Node.js en Python, resources, back-ups en grenzen.

10 MIN LEESTIJD

Geeft een site werk door aan een worker — een e-mail versturen, een afbeelding verkleinen, een bestelling afrekenen — of laat een dienst de andere weten dat er iets is gebeurd, dan gaat het bericht via een wachtrij of een message broker. Een project kan er drie hebben, elk toegevoegd als dienst: Overzicht → Diensten → Dienst toevoegen.

DienstKies deze voor
Valkeyeenvoudige takenwachtrijen (Laravel-queues en Horizon, BullMQ, Celery, RQ) en events in Streams — als je Valkey al gebruikt voor cache en sessies
NATSlichtgewicht berichtenverkeer tussen diensten: events, request en reply, en duurzame streams met JetStream
RabbitMQeen klassieke message broker: routering via exchanges, bevestigingen, nieuwe pogingen en dead-lettering, quorum queues

Twijfel je, begin dan met Valkey voor achtergrondtaken: de meeste frameworks ondersteunen het direct. Kies RabbitMQ als berichten over veel wachtrijen verdeeld moeten worden en er geen enkele verloren mag gaan, en NATS als diensten veel kleine berichten uitwisselen of elkaar om antwoorden vragen.

Valkey: takenwachtrijen en Streams

Valkey is een Redis-compatibele opslag — dezelfde beheerde dienst als bij Databases. De eerste Valkey van de applicatie geeft elke codedienst REDIS_URL, REDIS_HOST, REDIS_PORT en REDIS_PASSWORD; elke Valkey levert daarnaast zijn eigen RIVERVO_<NAME>_URL.

Drie manieren om er berichten mee te versturen:

  • Takenwachtrijen — Laravel-queues met de driver redis en Horizon, BullMQ, Celery, RQ. De bibliotheek bewaart de taken in Valkey; een worker pakt ze een voor een op en probeert mislukte taken opnieuw.
  • Streams met consumer groups — XADD voegt een event toe aan een stream, de consumers van een groep lezen het met XREADGROUP en bevestigen het met XACK. Events worden bewaard: een consumer die gestopt was, gaat verder waar hij was gebleven, een event dat niet is bevestigd kan opnieuw worden opgepakt, en een nieuwe groep kan de stream vanaf het begin lezen.
  • Pub/Sub — PUBLISH en SUBSCRIBE bezorgen een bericht alleen bij de abonnees die op dat moment verbonden zijn. Het bericht wordt niet bewaard: een abonnee die herstart of nog niet verbonden is, mist het. Gebruik Pub/Sub alleen waar een verloren bericht geen kwaad kan (bijvoorbeeld een «ververs»-signaal), en Streams of een wachtrij voor al het andere.

Van Valkey wordt elke dag een back-up gemaakt, net als van de andere databases; als je toegang openzet, is Valkey ook van buitenaf bereikbaar. Zie Databases.

NATS

NATS is een lichtgewicht, snel berichtensysteem, met JetStream ingeschakeld:

  • Publish en subscribe — een dienst publiceert naar een subject zoals orders.created en elke abonnee van dat subject krijgt het bericht. Zonder JetStream is dit fire-and-forget, net als Pub/Sub hierboven.
  • Request en reply — de ene dienst vraagt, een andere antwoordt. Antwoorden meerdere instances als queue group, dan verdeelt NATS de verzoeken over hen.
  • JetStream — duurzame streams: berichten worden op de schijf van de dienst opgeslagen, een consumer onthoudt wat hij heeft gelezen, en elk bericht wordt minstens één keer bezorgd tot het is bevestigd.
  • Key-value- en object-store op basis van JetStream — voor kleine gedeelde instellingen, locks of bestanden tussen diensten.

Variabelen. De eerste NATS van de applicatie geeft elke codedienst:

NATS_URL=nats://<user>:<password>@<service name>:4222

Elke NATS-dienst levert daarnaast RIVERVO_<NAME>_URL met een adres in dezelfde vorm — NAME is de naam van de dienst in hoofdletters, met streepjes omgezet in _: een dienst met de naam events levert RIVERVO_EVENTS_URL.

JetStream bewaart zijn streams op de schijf van de dienst; streams in het geheugen mogen ongeveer een kwart van het geheugen van de dienst gebruiken.

RabbitMQ

RabbitMQ 4.1 is een klassieke message broker: producers publiceren naar exchanges, exchanges routeren de berichten op basis van routing keys naar queues, consumers bevestigen elk bericht, en een bericht dat wordt geweigerd of verloopt kan naar een dead-letter-exchange gaan. Voor queues waarvan de berichten een herstart moeten overleven, gebruik je quorum queues (het argument x-queue-type: quorum) en publiceer je berichten als persistent.

Variabelen. De eerste RabbitMQ van de applicatie geeft elke codedienst:

VariabeleWaarde
AMQP_URLamqp://<user>:<password>@<service name>:5672/%2f
RABBITMQ_HOSTde naam van de dienst
RABBITMQ_PORT5672
RABBITMQ_USER, RABBITMQ_PASSWORDde gebruiker en het wachtwoord
RABBITMQ_VHOST/

%2f aan het eind van AMQP_URL is de standaard virtual host /, geschreven zoals verbindingsadressen dat vereisen. Elke RabbitMQ-dienst levert daarnaast zijn eigen RIVERVO_<NAME>_URL met een adres in dezelfde vorm.

Management-API. De HTTP-management-API luistert op poort 15672 binnen het privénetwerk van de applicatie: de diensten van de applicatie bereiken hem op http://<service name>:15672 met dezelfde gebruiker en hetzelfde wachtwoord, bijvoorbeeld:

curl -u "$RABBITMQ_USER:$RABBITMQ_PASSWORD" "http://$RABBITMQ_HOST:15672/api/queues"

Er is geen managementpagina op internet. De pagina van de dienst in het paneel toont een korte lijst van de queues, alleen om te lezen: klaarstaande en onbevestigde berichten en consumers.

Alleen intern

NATS en RabbitMQ hebben geen openbaar adres en zijn niet bereikbaar van buiten de applicatie — niet vanaf je computer, een andere server of een andere applicatie. Anders dan bij PostgreSQL, MySQL en Valkey is toegang van buitenaf voor deze diensten niet beschikbaar. De diensten die berichten publiceren en verwerken, draaien als diensten van dezelfde applicatie: webdiensten, achtergrondworkers en geplande taken.

Een tweede dienst van hetzelfde type

Alleen de eerste Valkey, NATS en RabbitMQ van de applicatie krijgen de gebruikelijke namen (REDIS_*, NATS_URL, AMQP_URL en RABBITMQ_*). De volgende van hetzelfde type voegt alleen zijn eigen RIVERVO_<NAME>_URL toe; lees die variabele in je code, of zet de gebruikelijke namen op het tabblad Variabelen op de waarden ervan. Variabelen komen bij de volgende deploy in een dienst terecht — zie Omgevingsvariabelen.

Laravel

Valkey. Stel op het tabblad Variabelen in:

QUEUE_CONNECTION=redis

Draai php artisan queue:work — of php artisan horizon met Horizon — als achtergrondworker. Zie Laravel.

RabbitMQ. Laravel heeft geen ingebouwde RabbitMQ-driver, en Rivervo past QUEUE_CONNECTION niet zelf aan. Zo gebruik je RabbitMQ voor Laravel-queues:

  1. Installeer het pakket: composer require vladimir-yuldashev/laravel-queue-rabbitmq.
  2. Voeg de verbinding rabbitmq toe aan config/queue.php zoals de README van het pakket voor jouw versie laat zien. Die leest RABBITMQ_HOST, RABBITMQ_PORT, RABBITMQ_USER, RABBITMQ_PASSWORD en RABBITMQ_VHOST, die de applicatie al heeft:
'rabbitmq' => [
    'driver' => 'rabbitmq',
    'hosts' => [
        [
            'host' => env('RABBITMQ_HOST', '127.0.0.1'),
            'port' => env('RABBITMQ_PORT', 5672),
            'user' => env('RABBITMQ_USER', 'guest'),
            'password' => env('RABBITMQ_PASSWORD', 'guest'),
            'vhost' => env('RABBITMQ_VHOST', '/'),
        ],
    ],
],
  1. Zet QUEUE_CONNECTION=rabbitmq op het tabblad Variabelen en deploy. De worker blijft php artisan queue:work.

NATS. Er is geen officiële Laravel-queuedriver voor NATS. Gebruik in je eigen code een NATS-client voor PHP — bijvoorbeeld basis-company/nats — en geef die de host, poort, gebruiker en het wachtwoord uit NATS_URL. Controleer of de client de functies ondersteunt die je nodig hebt (JetStream, key-value) voordat je erop bouwt.

Node.js

BullMQ (Valkey)

import { Queue, Worker } from 'bullmq'
import IORedis from 'ioredis'
 
const connection = new IORedis(process.env.REDIS_URL, { maxRetriesPerRequest: null })
 
// in the web service
const emails = new Queue('emails', { connection })
await emails.add('welcome', { userId: 42 }, { attempts: 3 })
 
// in the background worker
new Worker('emails', async (job) => {
  await sendWelcome(job.data.userId)
}, { connection })

BullMQ heeft maxRetriesPerRequest: null nodig op de verbinding die zijn workers gebruiken.

Valkey Streams

import IORedis from 'ioredis'
 
const redis = new IORedis(process.env.REDIS_URL)
 
// producer
await redis.xadd('orders', '*', 'id', '42')
 
// consumer of the group «billing»
await redis.xgroup('CREATE', 'orders', 'billing', '0', 'MKSTREAM').catch((err) => {
  if (!String(err).includes('BUSYGROUP')) throw err // the group already exists
})
const me = process.env.HOSTNAME ?? 'worker'
for (;;) {
  const res = await redis.xreadgroup('GROUP', 'billing', me, 'COUNT', 10, 'BLOCK', 5000, 'STREAMS', 'orders', '>')
  for (const [, entries] of res ?? []) {
    for (const [id, fields] of entries) {
      await handleOrder(fields)
      await redis.xack('orders', 'billing', id)
    }
  }
}

Een entry die gelezen maar niet bevestigd is, blijft openstaan in de groep; XAUTOCLAIM geeft hem aan een andere consumer.

NATS (nats.js)

import { connect, JSONCodec, AckPolicy } from 'nats'
 
const nc = await connect({ servers: process.env.NATS_URL })
const jc = JSONCodec()
 
// once: a stream for the subjects orders.* and a durable consumer
const jsm = await nc.jetstreamManager()
await jsm.streams.add({ name: 'ORDERS', subjects: ['orders.>'] })
await jsm.consumers.add('ORDERS', { durable_name: 'billing', ack_policy: AckPolicy.Explicit })
 
// producer
const js = nc.jetstream()
await js.publish('orders.created', jc.encode({ id: 42 }))
 
// consumer
const consumer = await js.consumers.get('ORDERS', 'billing')
for await (const m of await consumer.consume()) {
  await handleOrder(jc.decode(m.data))
  m.ack()
}

Request en reply: de ene dienst antwoordt met nc.subscribe('prices.get', { queue: 'prices', callback: (err, msg) => msg.respond(jc.encode(price)) }), een andere vraagt met await nc.request('prices.get', jc.encode({ sku: 'A1' }), { timeout: 2000 }).

RabbitMQ (amqplib)

import amqp from 'amqplib'
 
const conn = await amqp.connect(process.env.AMQP_URL)
const ch = await conn.createChannel()
await ch.assertQueue('emails', { durable: true, arguments: { 'x-queue-type': 'quorum' } })
 
// producer
ch.sendToQueue('emails', Buffer.from(JSON.stringify({ userId: 42 })), { persistent: true })
 
// consumer: at most 10 unacknowledged messages at a time
await ch.prefetch(10)
await ch.consume('emails', async (msg) => {
  try {
    await sendWelcome(JSON.parse(msg.content.toString()).userId)
    ch.ack(msg)
  } catch {
    ch.nack(msg, false, false) // to the dead-letter exchange, if the queue has one
  }
})

Elke dienst die de queue declareert, moet dat met dezelfde argumenten doen.

Python

Celery (Valkey of RabbitMQ)

import os
from celery import Celery
 
app = Celery("tasks", broker=os.environ["REDIS_URL"])  # or os.environ["AMQP_URL"]
 
@app.task(acks_late=True)
def send_welcome(user_id):
    ...

Draai celery -A tasks worker --loglevel=info als achtergrondworker. Celery accepteert amqp://-adressen zoals ze zijn. Met RabbitMQ kunnen recente Celery-versies quorum queues declareren (task_default_queue_type = "quorum") — zie de documentatie van Celery voor jouw versie.

RQ (Valkey)

import os
from redis import Redis
from rq import Queue
 
queue = Queue("emails", connection=Redis.from_url(os.environ["REDIS_URL"]))
queue.enqueue(send_welcome, 42)

De worker: rq worker emails --url "$REDIS_URL".

NATS (nats-py)

import asyncio, json, os
import nats
from nats.errors import TimeoutError
 
async def main():
    nc = await nats.connect(os.environ["NATS_URL"])
    js = nc.jetstream()
    await js.add_stream(name="ORDERS", subjects=["orders.>"])
 
    await js.publish("orders.created", json.dumps({"id": 42}).encode())
 
    sub = await js.pull_subscribe("orders.>", durable="billing")
    while True:
        try:
            msgs = await sub.fetch(10, timeout=5)
        except TimeoutError:
            continue
        for msg in msgs:
            await handle_order(json.loads(msg.data))
            await msg.ack()
 
asyncio.run(main())

RabbitMQ (pika)

import json, os
import pika
 
conn = pika.BlockingConnection(pika.URLParameters(os.environ["AMQP_URL"]))
ch = conn.channel()
ch.queue_declare(queue="emails", durable=True, arguments={"x-queue-type": "quorum"})
 
# producer
ch.basic_publish(exchange="", routing_key="emails",
                 body=json.dumps({"user_id": 42}),
                 properties=pika.BasicProperties(delivery_mode=2))
 
# consumer
def on_message(ch, method, properties, body):
    send_welcome(json.loads(body)["user_id"])
    ch.basic_ack(delivery_tag=method.delivery_tag)
 
ch.basic_qos(prefetch_count=10)
ch.basic_consume(queue="emails", on_message_callback=on_message)
ch.start_consuming()

Meer dan één keer bezorgd

Wachtrijen en brokers bezorgen een bericht opnieuw als een worker stopt voordat hij het heeft bevestigd — tijdens een deploy, een herstart of een herstel. Schrijf consumers zo dat het geen kwaad kan als hetzelfde bericht twee keer wordt verwerkt: bewaar de ID van elk verwerkt bericht, of maak de actie zelf herhaalbaar (bijvoorbeeld «zet de status op betaald» in plaats van «voeg een betaling toe»).

Resources en prijs

DienstBegint metMinimaal geheugen
NATS256 MB geheugen · 1 CPU-core · 5 GB schijf256 MB
RabbitMQ1 GB geheugen · 1 CPU-core · 10 GB schijf512 MB

Elk wordt geprijsd op basis van geheugen, CPU en schijf, zoals elke dienst — zie Diensten van een project. De resources kun je later aanpassen in de Instellingen van de dienst.

Back-ups en herstellen

Van NATS en RabbitMQ wordt elke dag een back-up gemaakt; we bewaren de laatste 7 dagen en 4 weken, net als bij de andere diensten.

  • De back-up kopieert de databestanden van de dienst terwijl die draait. Voor RabbitMQ bevat dezelfde back-up ook een export van de definities: gebruikers, virtual hosts, queues, exchanges, bindings en policies.
  • Er is geen herstel naar een exact moment — dat is er alleen voor PostgreSQL en MySQL. Je zet een van de dagelijkse kopieën terug.
  • Bij een herstel stopt de dienst even, worden de bestanden teruggezet en start de dienst weer. Berichten die rond het moment van de back-up binnenkwamen of bevestigd werden, kunnen ontbreken of opnieuw bezorgd worden — nog een reden om consumers veilig herhaalbaar te maken.
  • Kan RabbitMQ niet starten met de gekopieerde bestanden, dan start de dienst alleen met de definities: de queues, exchanges en gebruikers zijn er, maar de berichten uit de back-up zijn verloren.

Onderhoud en verhuizingen

Voor NATS en RabbitMQ stel je geen onderhoudstijd in. Ze worden niet automatisch naar een andere server verhuisd; is dat ooit nodig, dan regelt support het met je.

Kom je er niet uit?

Chat met ons — de AI antwoordt meteen en een technicus komt erbij als dat nodig is, op elk moment van de dag.

Contact met support