Skip to content

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

  1. Asks the management API for /api/overview. A failure is ErrManagement, wrapping the path and the cause.
  2. Dials URL with amqp.Dial. A failure is wrapped as messaging-rabbitmq: dialling.
  3. Passively declares Exchange as a topic exchange on a disposable channel. A failure is ErrNoExchange, naming the exchange.
  4. 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.