amqp091-go Documentation

The amqp091-go library is a Go AMQP 0.9.1 client maintained by the RabbitMQ core team. It is designed to provide a functional interface that closely represents the AMQP 0.9.1 model specifically for use with RabbitMQ.

Key Characteristics:

• Compatibility: Supports RabbitMQ versions starting from 2.0.
• Authentication: Supports PLAIN and EXTERNAL authentication mechanisms.
• API Evolution: Unlike the original client, this library allows for reasonable breaking public API changes to improve the client over time.
• Limitations:
  • Does not support AMQP 1.0 (which is a different protocol).
  • Does not support AMQP Protocol negotiation for forward/backward compatibility.
  • Does not guarantee ordering between basic.return and basic.ack frames sent over different channels due to the use of Go channels for protocol events.

To learn how to implement producers and consumers, refer to the following resources:

1. Code Examples: Check the _examples subdirectory in the repository for executable examples of simple producers and consumers.
2. Official Tutorials: Follow the RabbitMQ tutorials in Go for structured learning.
3. API Reference: For detailed technical documentation of all exported symbols, use the Godoc API reference.

If you are migrating an existing project from the original streadway/amqp client to this maintained version, you can minimize code changes by using a package alias. This allows you to keep using the amqp identifier in your code while importing the new repository path.

amqp "github.com/rabbitmq/amqp091-go"

A DeferredConfirmation is a handle to a specific message's acknowledgement status. It is created during the publishing process and is tied to a unique DeliveryTag.

It uses an internal done channel to signal when the server has responded. This allows for both blocking (Wait) and non-blocking (Acked) patterns. If the underlying connection or confirms object is closed, pending DeferredConfirmation objects are NACKed (set to false) to prevent goroutines from blocking indefinitely.

The library provides a two-phase recovery mechanism to handle network interruptions:

1. Connection Recovery: Re-establishes the TCP socket, performs the AMQP handshake (including SASL and tuning), and re-opens all previously active channels. It also re-applies QoS settings and channel-level confirms.
2. Topology Recovery: Once channels are re-opened, the library re-declares the AMQP entities (exchanges, queues, and bindings) that were active before the drop.

Transient vs. Durable Topology: When using TopologyRecoveryOnlyTransient, the client only re-declares 'transient' entities (e.g., auto-delete exchanges or exclusive/auto-delete queues) and their associated bindings. Durable, non-auto-delete entities are assumed to be retained by the broker and are not re-declared.

The amqp091 library uses LifeCycleState to represent the current status of a connection or channel. You can monitor these states to understand if a connection is active, recovering, or shutting down.

Available states:

• StateOpen: The connection or channel is active and open.
• StateReconnecting: The connection or channel is actively undergoing automatic recovery.
• StateClosing: The connection or channel is in the process of closing down.
• StateClosed: The connection or channel is fully closed and shut down (terminal state).

When a connection or channel changes state, a StateChanged event is emitted. This event provides details about the transition, including the previous state, the new state, and potential errors or skipped entities.

Key fields in StateChanged:

• From: The LifeCycleState before the transition.
• To: The LifeCycleState after the transition.
• Err: Set only during a transition to StateClosed. It contains the fatal error that ended the recovery process (e.g., exhausted retries).
• SkippedTopologyEntities: Set only during a StateReconnecting $\rightarrow$ StateOpen transition. It contains a list of TopologyRecoveryEntity objects that were skipped due to errors during recovery.

The TopologyRecoveryMode determines which AMQP entities are automatically redeclared by the client after a reconnection. There are three modes:

1. TopologyRecoveryAllEnabled (Default): Recovers everything tracked by the client, including exchanges, queues, bindings, and active consumers. Use this for standard client behavior.
2. TopologyRecoveryOnlyTransient: Recovers only connection-scoped (transient) entities, such as exclusive or auto-delete queues/exchanges and their bindings. It skips durable entities, assuming they are managed externally. Note: Active consumers are always re-subscribed regardless of this mode.
3. TopologyRecoveryDisabled: Disables topology and consumer recovery entirely. Connection and channel recovery will still occur if enabled, but the state (queues, exchanges, etc.) will not be restored.

The library automatically restores the state of the broker's topology upon reconnection. The recovery process follows these steps in order:

1. Recover Exchanges: Re-declares all exchanges across all channels.
2. Recover Queues: Re-declares all queues. If a server-generated queue (where DeclaredName was empty) receives a new name from the broker, the library automatically updates all subsequent bindings and consumer configurations to use this new name.
3. Recover Queue-to-Exchange Bindings: Re-establishes bindings between queues and exchanges.
4. Recover Exchange-to-Exchange Bindings: Re-establishes bindings between exchanges.
5. Re-subscribe Consumers: Re-establishes consumers on the queues. This is done using basic.consume directly to ensure that existing delivery channels and goroutines are reused, meaning the application's consumer logic remains uninterrupted.

The Channel type is the primary context for performing AMQP operations. It represents an AMQP channel.

Important: If any method on a Channel returns an error, that channel should be considered invalid and discarded. You must establish a new channel to continue operations.

The amqp091.Config.Recovery field enables experimental automatic reconnection and topology recovery. When enabled, the connection and its channels will attempt to reconnect and recover topology (exchanges, queues, bindings, and consumers) after a network failure.

Topology recovery scope is controlled by Recovery.TopologyRecoveryMode:

• TopologyRecoveryAllEnabled (default): Recovers all tracked topology.
• TopologyRecoveryOnlyTransient: Recovers only transient entities (exclusive/auto-delete queues/exchanges).
• TopologyRecoveryDisabled: Skips topology and consumer recovery.

Applications can monitor recovery state via Connection.NotifyStateChange and Channel.NotifyStateChange.