# README
Go RabbitMQ Client Library
This is a Go AMQP 0.9.1 client maintained by the RabbitMQ core team. It was originally developed by Sean Treadway.
Differences from streadway/amqp
Some things are different compared to the original client, others haven't changed.
Package Name
This library uses a different package name. If moving from streadway/amqp,
using an alias may reduce the number of changes needed:
amqp "github.com/rabbitmq/amqp091-go"
License
This client uses the same 2-clause BSD license as the original project.
Public API Evolution
This client retains key API elements as practically possible. It is, however, open to reasonable breaking public API changes suggested by the community. We don't have the "no breaking public API changes ever" rule and fully recognize that a good client API evolves over time.
Project Maturity
This project is based on a mature Go client that's been around for over a decade.
Supported Go Versions
This client supports two most recent Go release series.
Supported RabbitMQ Versions
This project supports RabbitMQ versions starting with 2.0 but primarily tested
against currently supported RabbitMQ release series.
Some features and behaviours may be server version-specific.
Goals
Provide a functional interface that closely represents the AMQP 0.9.1 model targeted to RabbitMQ as a server. This includes the minimum necessary to interact the semantics of the protocol.
Non-goals
Things not intended to be supported.
- Auto reconnect and re-synchronization of client and server topologies.
- Reconnection would require understanding the error paths when the topology cannot be declared on reconnect. This would require a new set of types and code paths that are best suited at the call-site of this package. AMQP has a dynamic topology that needs all peers to agree. If this doesn't happen, the behavior is undefined. Instead of producing a possible interface with undefined behavior, this package is designed to be simple for the caller to implement the necessary connection-time topology declaration so that reconnection is trivial and encapsulated in the caller's application code.
- AMQP Protocol negotiation for forward or backward compatibility.
- 0.9.1 is stable and widely deployed. AMQP 1.0 is a divergent specification (a different protocol) and belongs to a different library.
- Anything other than PLAIN and EXTERNAL authentication mechanisms.
- Keeping the mechanisms interface modular makes it possible to extend outside of this package. If other mechanisms prove to be popular, then we would accept patches to include them in this package.
- Support for
basic.returnandbasic.ackframe ordering. This client uses Go channels for certain protocol events and ordering between events sent to two different channels generally cannot be guaranteed.
Usage
See the _examples subdirectory for simple producers and consumers executables. If you have a use-case in mind which isn't well-represented by the examples, please file an issue.
Documentation
Contributing
Pull requests are very much welcomed. Create your pull request on a non-main branch, make sure a test or example is included that covers your change, and your commits represent coherent changes that include a reason for the change.
See CONTRIBUTING.md for more information.
License
BSD 2 clause, see LICENSE for more details.
# Functions
DefaultDial establishes a connection when config.Dial is not provided.
Dial accepts a string in the AMQP URI format and returns a new Connection over TCP using PlainAuth.
DialConfig accepts a string in the AMQP URI format and a configuration for the transport and connection setup, returning a new Connection.
DialTLS accepts a string in the AMQP URI format and returns a new Connection over TCP using PlainAuth.
DialTLS_ExternalAuth accepts a string in the AMQP URI format and returns a new Connection over TCP using EXTERNAL auth.
NewConnectionProperties creates an amqp.Table to be used as amqp.Config.Properties.
Open accepts an already established connection, or other io.ReadWriteCloser as
a transport.
ParseURI attempts to parse the given AMQP URI according to the spec.
Enables logging using a custom Logging instance.
# Constants
Error codes that can be sent from the server during a connection or channel exception or used by the client to indicate a class of error like ErrCredentials.
Error codes that can be sent from the server during a connection or channel exception or used by the client to indicate a class of error like ErrCredentials.
Error codes that can be sent from the server during a connection or channel exception or used by the client to indicate a class of error like ErrCredentials.
Error codes that can be sent from the server during a connection or channel exception or used by the client to indicate a class of error like ErrCredentials.
ConsumerTimeoutArg is available in RabbitMQ 3.12+ as a queue argument.
Error codes that can be sent from the server during a connection or channel exception or used by the client to indicate a class of error like ErrCredentials.
DefaultExchange is the default direct exchange that binds every queue by its name.
Constants for standard AMQP 0-9-1 exchange types.
Constants for standard AMQP 0-9-1 exchange types.
Constants for standard AMQP 0-9-1 exchange types.
Constants for standard AMQP 0-9-1 exchange types.
Error codes that can be sent from the server during a connection or channel exception or used by the client to indicate a class of error like ErrCredentials.
0 means immediately expire.
Error codes that can be sent from the server during a connection or channel exception or used by the client to indicate a class of error like ErrCredentials.
Error codes that can be sent from the server during a connection or channel exception or used by the client to indicate a class of error like ErrCredentials.
empty value means never expire.
Error codes that can be sent from the server during a connection or channel exception or used by the client to indicate a class of error like ErrCredentials.
Error codes that can be sent from the server during a connection or channel exception or used by the client to indicate a class of error like ErrCredentials.
Error codes that can be sent from the server during a connection or channel exception or used by the client to indicate a class of error like ErrCredentials.
Error codes that can be sent from the server during a connection or channel exception or used by the client to indicate a class of error like ErrCredentials.
Error codes that can be sent from the server during a connection or channel exception or used by the client to indicate a class of error like ErrCredentials.
DeliveryMode.
Error codes that can be sent from the server during a connection or channel exception or used by the client to indicate a class of error like ErrCredentials.
Most common queue argument keys in queue declaration.
Most common queue argument keys in queue declaration.
Most common queue argument keys in queue declaration.
Most common queue argument keys in queue declaration.
Values for queue arguments.
Values for queue arguments.
Values for queue arguments.
Most common queue argument keys in queue declaration.
Most common queue argument keys in queue declaration.
Values for queue arguments.
Values for queue arguments.
Values for queue arguments.
QueueVersionArg declares the Classic Queue version to use.
Error codes that can be sent from the server during a connection or channel exception or used by the client to indicate a class of error like ErrCredentials.
Error codes that can be sent from the server during a connection or channel exception or used by the client to indicate a class of error like ErrCredentials.
Most common queue argument keys in queue declaration.
Most common queue argument keys in queue declaration.
Most common queue argument keys in queue declaration.
Most common queue argument keys in queue declaration.
Error codes that can be sent from the server during a connection or channel exception or used by the client to indicate a class of error like ErrCredentials.
DeliveryMode.
Error codes that can be sent from the server during a connection or channel exception or used by the client to indicate a class of error like ErrCredentials.
# Variables
ErrChannelMax is returned when Connection.Channel has been called enough times that all channel IDs have been exhausted in the client or the server.
ErrClosed is returned when the channel or connection is not open.
ErrCommandInvalid is returned when the server sends an unexpected response to this requested message type.
ErrCredentials is returned when the authenticated client is not authorized to any vhost.
ErrFieldType is returned when writing a message containing a Go type unsupported by AMQP.
ErrFrame is returned when the protocol frame cannot be read from the server, indicating an unsupported protocol or unsupported frame type.
ErrSASL is returned from Dial when the authentication mechanism could not be negotiated.
ErrSyntax is hard protocol error, indicating an unsupported protocol, implementation or encoding.
ErrUnexpectedFrame is returned when something other than a method or heartbeat frame is delivered to the Connection, indicating a bug in the client.
ErrVhost is returned when the authenticated user is not permitted to access the requested Vhost.
No description provided by the author
# Structs
AMQPlainAuth is similar to PlainAuth.
Blocking notifies the server's TCP flow control of the Connection.
Channel represents an AMQP channel.
Config is used in DialConfig and Open to specify the desired tuning parameters used during a connection open handshake.
Confirmation notifies the acknowledgment or negative acknowledgement of a publishing identified by its delivery tag.
Connection manages the serialization and deserialization of frames from IO and dispatches the frames to the appropriate channel.
Decimal matches the AMQP decimal type.
DeferredConfirmation represents a future publisher confirm for a message.
Delivery captures the fields for a previously delivered message resident in a queue to be delivered by the server to a consumer from Channel.Consume or Channel.Get.
Error captures the code and reason a channel or connection has been closed by the server.
ExternalAuth for RabbitMQ-auth-mechanism-ssl.
No description provided by the author
PlainAuth is a similar to Basic Auth in HTTP.
Publishing captures the client message sent to the server.
Queue captures the current server state of the queue on the server returned from Channel.QueueDeclare or Channel.QueueInspect.
Return captures a flattened struct of fields returned by the server when a Publishing is unable to be delivered either due to the `mandatory` flag set and no route found, or `immediate` flag set and no free consumer.
URI represents a parsed AMQP URI string.
# Interfaces
Acknowledger notifies the server of successful or failed consumption of deliveries via identifier found in the Delivery.DeliveryTag field.
Authentication interface provides a means for different SASL authentication mechanisms to be used during connection tuning.
No description provided by the author
# Type aliases
Table stores user supplied fields of the following types:
bool byte int8 float32 float64 int int16 int32 int64 nil string time.Time amqp.Decimal amqp.Table []byte []interface{} - containing above types
Functions taking a table will immediately fail when the table contains a value of an unsupported type.