Connect to RabbitMQ¶
rabbitmq.New returns a messaging.Backend. It connects nothing: the bus calls Open when it
starts, so a broker that is briefly down does not stop an application booting
(the backend contract).
Build it¶
backend := rabbitmq.New(rabbitmq.Settings{
URL: "amqps://rabbit.internal:5671/",
Management: rabbitmq.Management{
URL: "https://rabbit.internal:15671",
Username: "app",
Password: "secret",
VHost: "/",
},
Exchange: "events",
Logger: logger,
})
bus, err := messaging.New(backend, messaging.Settings{Subscriptions: specs})
Credentials go in the URL's userinfo, before the host. amqp.Dial uses guest and guest when the
URL has none. Both endpoints are required. The management API is a dependency, not a fallback: every claim the
backend makes about a queue comes from it. Settings lists every field and
its default.
Management.VHost is only the management API's path. The AMQP virtual host is the one in URL, so
set both when you do not use /.
What Open does, in order¶
- Asks the management API for
/api/overview. A failure isErrManagement, wrapping the path and the cause. - Dials
URLwithamqp.Dial. A failure is wrapped asmessaging-rabbitmq: dialling. - Passively declares
Exchangeas a topic exchange on a disposable channel. A failure isErrNoExchange, naming the exchange. - Opens the publish channel and puts it in confirm mode.
Anything that fails after the dial closes the connection before returning. Open dials once. The
adapter has no reconnection of its own; see Limits.
Tell the failures apart¶
switch {
case errors.Is(err, rabbitmq.ErrManagement):
// the management plugin is off, the URL or credentials are wrong, or it is unreachable
case errors.Is(err, rabbitmq.ErrNoExchange):
// the operator has not created the exchange; the adapter will not
}
Open is called by the bus at start, so these errors come back through bus.Start's path rather than from rabbitmq.New.
Errors lists every sentinel.
Check it before the first subscription¶
Open proves the exchange and the management API. It proves nothing about a queue: that happens at
Subscribe, per subscription. See Prepare the exchange and queues.