Skip to content

Connect to a broker

backend, err := amqp.New(ctx, amqp.Settings{
    URL:      "amqps://broker.example.com:5671",
    Username: user,
    Password: pass,
    Logger:   logger,
}, amqp.Artemis{})
if err != nil {
    return err
}

bus, err := messaging.New(backend, messaging.Settings{Subscriptions: specs})

Every Settings field and its default is in Settings.

Where a connection failure shows up

amqp.New connects. It dials once, reads the broker's configuration through the Management, and closes that connection. So, unlike the core's own construction, which does not connect, the failures below arrive at amqp.New and not at bus.Start or Ready():

Problem Error
nothing listening messaging-amqp: dialling: dial tcp 127.0.0.1:5999: connect: connection refused
wrong credentials messaging-amqp: dialling: SASL PLAIN auth failed with code 0x1:
no Management messaging-amqp: a Management is required; nothing under at-least-once can be verified without one
the broker would not answer the management requests messaging-amqp: reading the broker's features

Retry amqp.New yourself if the broker may start after the service. The core's handling of an unreachable backend applies once you have a backend, not before.

Capabilities are decided at this call and do not change afterwards. A broker reconfigured later is noticed by the next amqp.New, not by a running backend.

Credentials and TLS

If Username or Password is set, the connection uses SASL PLAIN with both. If both are empty no SASL mechanism is set, which is anonymous access. Settings has no field for a TLS configuration, a container ID, or any other connection option: the adapter passes only the SASL mechanism to Azure/go-amqp.

What a running backend holds

Open dials its own connection and opens one session on it. Each subscription then opens a session of its own on that connection, so ending a subscription lets its link go without unsubscribing it. A publisher opens one sender link per address, lazily, and keeps it.

Close retires every source concurrently, closes the sender links, then the session and the connection, in reverse of Open. Publishing after Close returns ErrClosed.

A message that cannot be sent is an error from Publish, with the broker's disposition in it. The disposition is waited for, so a returned nil means the broker accepted the message. See Wire format for what that does and does not guarantee.