RabbitMQ tutorial - "Hello World!"

Introduction

info

Prerequisites

This tutorial assumes RabbitMQ is installed and running on localhost on the standard port (5672). In case you use a different host, port or credentials, connections settings would require adjusting.

Where to get help

If you're having trouble going through this tutorial you can contact us through GitHub Discussions or RabbitMQ community Discord.

RabbitMQ is a message broker: it accepts and forwards messages. You can think about it as a post office: when you put the mail that you want posting in a post box, you can be sure that the letter carrier will eventually deliver the mail to your recipient. In this analogy, RabbitMQ is a post box, a post office, and a letter carrier.

The major difference between RabbitMQ and the post office is that it doesn't deal with paper, instead it accepts, stores, and forwards binary blobs of data ‒ messages.

RabbitMQ, and messaging in general, uses some jargon.

Producing means nothing more than sending. A program that sends messages is a producer :
A queue is the name for the post box in RabbitMQ. Although messages flow through RabbitMQ and your applications, they can only be stored inside a queue. A queue is only bound by the host's memory & disk limits, it's essentially a large message buffer.

Many producers can send messages that go to one queue, and many consumers can try to receive data from one queue.

This is how we represent a queue:
Consuming has a similar meaning to receiving. A consumer is a program that mostly waits to receive messages:

Note that the producer, consumer, and broker do not have to reside on the same host; indeed in most applications they don't. An application can be both a producer and consumer, too.

"Hello World"

(using BunnySwift)

In this part of the tutorial we'll write two small programs in Swift: a producer that sends a single message, and a consumer that receives messages and prints them out. We'll gloss over some of the details in the BunnySwift API, concentrating on this very simple thing just to get started. It's the "Hello World" of messaging.

In the diagram below, "P" is our producer and "C" is our consumer. The box in the middle is a queue - a message buffer that RabbitMQ keeps on behalf of the consumer.

The BunnySwift client library

RabbitMQ speaks multiple protocols. This tutorial uses AMQP 0-9-1, which is an open, general-purpose protocol for messaging. There are a number of clients for RabbitMQ in many different languages. We'll use BunnySwift in this tutorial, a modern Swift client that leverages Swift concurrency with async/await.

Setup

First, make sure you have RabbitMQ installed and running.

BunnySwift requires Swift 6.0 or later. Create a new directory for your project and initialize it with Swift Package Manager:

mkdir rabbitmq-swift-tutorial
cd rabbitmq-swift-tutorial
swift package init --type executable --name Send

Edit Package.swift to add the BunnySwift dependency:

// swift-tools-version: 6.0
import PackageDescription

let package = Package(
    name: "RabbitMQTutorials",
    platforms: [.macOS(.v14)],
    dependencies: [
        .package(url: "https://github.com/rabbitmq/bunny-swift", from: "0.1.0")
    ],
    targets: [
        .executableTarget(
            name: "Send",
            dependencies: [.product(name: "BunnySwift", package: "bunny-swift")]
        ),
        .executableTarget(
            name: "Receive",
            dependencies: [.product(name: "BunnySwift", package: "bunny-swift")]
        )
    ]
)

Create the source directories:

mkdir -p Sources/Send Sources/Receive

Now we have Swift Package Manager set up with the BunnySwift dependency.

Sending

We'll call our message publisher (sender) Send and our message receiver Receive. The publisher will connect to RabbitMQ, send a single message, then exit.

In Sources/Send/main.swift, we need to import the library first:

import BunnySwift
import Foundation

then we can create a connection to the server:

@main
struct Send {
    static func main() async throws {
        let connection = try await Connection.open()

The connection abstracts the socket connection, and takes care of protocol version negotiation and authentication and so on for us. Here we connect to a RabbitMQ node on the local machine with all default settings.

If we wanted to connect to a node on a different machine or configure other connection parameters, we would use:

let connection = try await Connection.open(
    host: "some-host.example.com",
    port: 5672,
    username: "guest",
    password: "guest"
)

or specify a URI:

let connection = try await Connection.open(uri: "amqp://user:password@host:5672/vhost")

Next we create a channel, which is where most of the API for getting things done resides:

        let channel = try await connection.openChannel()

To send, we must declare a queue for us to send to; then we can publish a message to the queue:

        let queue = try await channel.queue("hello")

        try await channel.basicPublish(
            body: Data("Hello World!".utf8),
            routingKey: queue.name
        )
        print(" [x] Sent 'Hello World!'")

Declaring a queue is idempotent - it will only be created if it doesn't exist already. The message content is a byte array, so you can encode whatever you like there.

Lastly, we close the connection:

        try await connection.close()
    }
}

Here's the complete Send.swift file.

Sending doesn't work!

If this is your first time using RabbitMQ and you don't see the "Sent" message then you may be left scratching your head wondering what could be wrong. Maybe the broker was started without enough free disk space (by default it needs at least 50 MB free) and is therefore refusing to accept messages. Check the broker log file to see if there is a resource alarm logged and reduce the free disk space threshold if necessary. The Configuration guide will show you how to set disk_free_limit.

Receiving

That's it for our publisher. Our consumer listens for messages from RabbitMQ, so unlike the publisher which publishes a single message, we'll keep the consumer running to listen for messages and print them out.

The code in Sources/Receive/main.swift has the same imports as Send:

import BunnySwift

Setting up is the same as the publisher; we open a connection and a channel, and declare the queue from which we're going to consume. Note this matches up with the queue that Send publishes to.

@main
struct Receive {
    static func main() async throws {
        let connection = try await Connection.open()
        let channel = try await connection.openChannel()
        let queue = try await channel.queue("hello")

Note that we declare the queue here as well. Because we might start the consumer before the publisher, we want to make sure the queue exists before we try to consume messages from it.

We're about to tell the server to deliver us the messages from the queue. BunnySwift returns a consumer that we can iterate over using Swift concurrency. We call basicConsume and iterate over the messages:

        print(" [*] Waiting for messages. To exit press CTRL+C")

        let consumer = try await channel.basicConsume(
            queue: queue.name,
            acknowledgementMode: .automatic
        )
        for try await message in consumer {
            print(" [x] Received '\(message.bodyString ?? "")'")
        }
    }
}

The consumer will continue running, waiting for messages. Use Ctrl-C to stop it.

Here's the complete Receive.swift file.

Putting it all together

Build both programs:

swift build

In one terminal, run the consumer:

swift run Receive
# => [*] Waiting for messages. To exit press CTRL+C

Then, in another terminal, run the publisher:

swift run Send
# => [x] Sent 'Hello World!'

The consumer will print the message it gets from the publisher via RabbitMQ.

# => [x] Received 'Hello World!'

The consumer will keep running, waiting for messages, so try running the publisher again in another terminal.

Congrats! You were able to send and receive a message through RabbitMQ.

If you want to check on the queue, try using rabbitmqctl list_queues.

Time to move on to part 2 and build a simple work queue.

Introduction​

Prerequisites​

Where to get help​

"Hello World"​

(using BunnySwift)​

The BunnySwift client library​

Setup​

Sending​

Sending doesn't work!​

Receiving​

Putting it all together​