@spec close(t()) :: :ok | {:error, any()}

Closes an open Connection.

Please note that the closing will be performed asynchronously. To verify the actual closure, you must monitor the process.

@spec close(t(), non_neg_integer()) :: :ok | {:error, any()}

Closes a connection with a timeout in milliseconds.

After the timeout, the connection is abruptly terminated. Uses the default reply code 200 and text "Goodbye".

@spec close(t(), non_neg_integer(), String.t()) :: :ok | {:error, any()}

Closes a connection with a custom AMQP reply code and text. Uses the Erlang client's configured call timeout.

@spec close(t(), non_neg_integer(), String.t(), non_neg_integer()) ::
  :ok | {:error, any()}

Closes a connection with a custom AMQP reply code, text, and timeout in milliseconds.

After the timeout, the connection is abruptly terminated.

@spec connection_name(t()) :: String.t() | :undefined

Returns the user-specified connection name, or :undefined when unset.

@spec info(t(), [atom()]) :: keyword()

Returns a keyword list of the requested connection information.

Use info_keys/1 to discover available keys. These include :server_properties, :num_channels, :is_closing, and negotiated :channel_max, :frame_max, and :heartbeat values. Values are returned unchanged from the Erlang client, including records such as :amqp_params. Invalid keys raise ArgumentError without closing the connection.

@spec info_keys() :: [atom()]

Returns information keys available for any connection.

@spec info_keys(t()) :: [atom()]

Returns all information keys available for the given connection.

@spec open(keyword() | String.t()) :: {:ok, t()} | {:error, atom()} | {:error, any()}

Opens a new connection.

Behaves like open/2 but takes only either AMQP URI or options.

Examples

iex> options = [host: "localhost", port: 5672, virtual_host: "/", username: "guest", password: "guest"]
iex> AMQP.Connection.open(options)
{:ok, %AMQP.Connection{}}

iex> AMQP.Connection.open("amqp://guest:guest@localhost")
{:ok, %AMQP.Connection{}}

@spec open(String.t() | keyword(), keyword() | String.t() | :undefined) ::
  {:ok, t()} | {:error, atom()} | {:error, any()}

Opens an new Connection to an AMQP broker.

The connections created by this module are supervised under amqp_client's supervision tree. Please note that connections do not get restarted automatically by the supervision tree in case of a failure. If you need robust connections and channels, use monitors on the returned connection PID.

Options

• :username - The name of a user registered with the broker (default "guest")

• :password - The password of user (default to "guest")

• :virtual_host - The name of a virtual host in the broker (defaults "/")

• :host - The hostname of the broker (default "localhost")

• :port - The port the broker is listening on (default 5672)

• :channel_max - The channel_max handshake parameter (default 0)

• :frame_max - The frame_max handshake parameter (defaults 0)

• :heartbeat - The heartbeat interval in seconds (defaults 10)

• :connection_timeout - The connection timeout in milliseconds (efaults 50000)

• :ssl_options - Enable SSL by setting the location to cert files (default :none)

• :client_properties - A list of extra client properties to be sent to the server (default [])

• :socket_options - Extra socket options. These are appended to the default options. See http://www.erlang.org/doc/man/inet.html#setopts-2 and http://www.erlang.org/doc/man/gen_tcp.html#connect-4 for descriptions of the available options

• :auth_mechanisms - A list of authentication of SASL authentication mechanisms to use. See https://www.rabbitmq.com/access-control.html#mechanisms and https://github.com/rabbitmq/rabbitmq-auth-mechanism-ssl for descriptions of the available options

• :name - A human-readable string that will be displayed in the management UI. Connection names do not have to be unique and cannot be used as connection identifiers (default :undefined)

Examples

iex> options = [host: "localhost", port: 5672, virtual_host: "/", username: "guest", password: "guest", name: "my-conn"]
iex> AMQP.Connection.open(options)
{:ok, %AMQP.Connection{}}

iex> AMQP.Connection.open("amqp://guest:guest@localhost", port: 5673)
{:ok, %AMQP.Connection{}}

Enabling SSL

To enable SSL, supply the following in the ssl_options field:

• :cacertfile - Specifies the certificates of the root Certificate Authorities that we wish to implicitly trust

• :certfile - The client's own certificate in PEM format

• :keyfile - The client's private key in PEM format

Here is an example:

iex> AMQP.Connection.open(
  port: 5671,
  ssl_options: [
    cacertfile: '/path/to/testca/cacert.pem',
    certfile: '/path/to/client/cert.pem',
    keyfile: '/path/to/client/key.pem',
    # only necessary with intermediate CAs
    # depth: 2,
    verify: :verify_peer
  ]
)

Backward compatibility for connection name

RabbitMQ supports user-specified connection names since version 3.6.2.

Previously AMQP took a connection name as a separate parameter on open/2 and open/3 and it is still supported in this version.

iex> options = [host: "localhost", port: 5672, virtual_host: "/", username: "guest", password: "guest"]
iex> AMQP.Connection.open(options, :undefined)
{:ok, %AMQP.Connection{}}

iex> AMQP.Connection.open("amqp://guest:guest@localhost", "my-connection")
{:ok, %AMQP.Connection{}}

iex> AMQP.Connection.open("amqp://guest:guest@localhost", "my-connection", options)
{:ok, %AMQP.Connection{}}

However the connection name parameter is now deprecated and might not be supported in the future versions.

You are recommended to pass it with :name option instead:

iex> AMQP.Connection.open("amqp://guest:guest@localhost", name: "my-connection")
{:ok, %AMQP.Connection{}}

@spec register_blocked_handler(t(), pid()) :: :ok

Registers a process to receive connection blocked and unblocked notifications.

The process receives the Erlang record tuples {:"connection.blocked", reason} and {:"connection.unblocked"}. Registering another process replaces the handler. Registration is asynchronous and returns :ok.

The Erlang client retains monitors for replaced handlers. Keep those processes alive until the connection closes to avoid an unexpected connection exit.

@spec update_secret(t(), String.t(), String.t()) :: :ok | {:error, any()}

Updates the secret used to authenticate the given Connection.

This is useful when the credentials used to open the connection have a limited lifetime, such as an OAuth 2 token, and need to be renewed before they expire so the broker does not close the connection.

new_secret is the new secret and reason is a short human readable string explaining why the secret is being updated.

Examples

iex> {:ok, conn} = AMQP.Connection.open()
iex> AMQP.Connection.update_secret(conn, "new-token", "token refresh")
:ok