AMQP 1.0 Client Module for Go

The amqp module is an AMQP 1.0 client implementation for Go.

AMQP 1.0 is not compatible with AMQP 0-9-1 or 0-10.

Getting Started

Prerequisites

Go 1.18 or later
An AMQP 1.0 compliant broker

Install the module

go get github.com/Azure/go-amqp

Connect to a broker

Call amqp.Dial() to connect to an AMQP broker. This creates an *amqp.Conn.

conn, err := amqp.Dial(context.TODO(), "amqp[s]://<host name of AMQP 1.0 broker>", nil)
if err != nil {
    // handle error
}

Sending and receiving messages

In order to send or receive messages, first create an *amqp.Session from the *amqp.Conn by calling Conn.NewSession().

session, err := conn.NewSession(context.TODO(), nil)
if err != nil {
    // handle error
}

Once the session has been created, create an *amqp.Sender to send messages and/or an *amqp.Receiver to receive messages by calling Session.NewSender() and/or Session.NewReceiver() respectively.

// create a new sender
sender, err := session.NewSender(context.TODO(), "<name of peer's receiving terminus>", nil)
if err != nil {
    // handle error
}

// send a message
err = sender.Send(context.TODO(), amqp.NewMessage([]byte("Hello!")), nil)
if err != nil {
    // handle error
}

// create a new receiver
receiver, err := session.NewReceiver(context.TODO(), "<name of peer's sending terminus>", nil)
if err != nil {
    // handle error
}

// receive the next message
msg, err := receiver.Receive(context.TODO(), nil)
if err != nil {
    // handle error
}

Key concepts

An *amqp.Conn connects a client to a broker (e.g. Azure Service Bus).
Once a connection has been established, create one or more *amqp.Session instances.
From an *amqp.Session instance, create one or more senders and/or receivers.
- An *amqp.Sender is used to send messages from the client to a broker.
- An *amqp.Receiver is used to receive messages from a broker to the client.

For a complete overview of AMQP's conceptual model, please consult section 2.1 Transport of the AMQP 1.0 specification.

Examples

The following examples cover common scenarios for sending and receiving messages:

Create a message
Send message
Receive messages

Create a message

A message can be created in two different ways. The first is to simply instantiate a new instance of the *amqp.Message type, populating the required fields.

msg := &amqp.Message{
    // populate fields (Data is the most common)
}

The second is the amqp.NewMessage constructor. It passes the provided []byte to the first entry in the *amqp.Message.Data slice.

msg := amqp.NewMessage(/* some []byte */)

This is purely a convenience constructor as many AMQP brokers expect a message's data in the Data field.

Send message

Once an *amqp.Session has been created, create an *amqp.Sender in order to send messages.

sender, err := session.NewSender(context.TODO(), "<name of peer's receiving terminus>", nil)

Once the *amqp.Sender has been created, call Sender.Send() to send an *amqp.Message.

err := sender.Send(context.TODO(), msg, nil)

Depending on the sender's configuration, the call to Sender.Send() will block until the peer has acknowledged the message was received. The amount of time the call will block is dependent upon network latency and the peer's load, but is usually in a few dozen milliseconds.

Receive messages

Once an *amqp.Session has been created, create an *amqp.Receiver in order to receive messages.

receiver, err := session.NewReceiver(context.TODO(), "<name of peer's sending terminus>", nil)

Once the *amqp.Receiver has been created, call Receiver.Receive() to wait for an incoming message.

msg, err := receiver.Receive(context.TODO(), nil)

Note that calls to Receiver.Receive() will block until either a message has been received or, if applicable, the provided context.Context has been cancelled and/or its deadline exceeded.

After an *amqp.Message message has been received and processed, as the final step it's imperative that the *amqp.Message is passed to one of the acknowledgement methods on the *amqp.Receiver.

Receiver.AcceptMessage - the client has accepted the message and no redelivery is required (most common)
Receiver.ModifyMessage - the client has modified the message and released it for redelivery with the specified modifications
Receiver.RejectMessage - the message is invalid and therefore cannot be processed
Receiver.ReleaseMessage - the client has released the message for redelivery without any modifications

err := receiver.AcceptMessage(context.TODO(), msg)

Next steps

See the examples for complete end-to-end examples on how to use this module.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Azure / go-amqp

readme