# Inch CI

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.

This function can be called in three ways:

  * with a list of options and a name
  * with an AMQP URI and a name
  * with an AMQP URI and a list of options (in this case, the options are merged with
    the AMQP URI, taking precedence on same keys)

## Options

  * `:username` - The name of a user registered with the broker (defaults to `"guest"`);
  * `:password` - The password of user (defaults to `"guest"`);
  * `:virtual_host` - The name of a virtual host in the broker (defaults to `"/"`);
  * `:host` - The hostname of the broker (defaults to `"localhost"`);
  * `:port` - The port the broker is listening on (defaults to `5672`);
  * `:channel_max` - The channel_max handshake parameter (defaults to `0`);
  * `:frame_max` - The frame_max handshake parameter (defaults to `0`);
  * `:heartbeat` - The hearbeat interval in seconds (defaults to `10`);
  * `:connection_timeout` - The connection timeout in milliseconds (defaults to `50000`);
  * `:ssl_options` - Enable SSL by setting the location to cert files (defaults to `:none`);
  * `:client_properties` - A list of extra client properties to be sent to the server, defaults to `[]`;
  * `: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.

## 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;

### Example

```
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,
                                   fail_if_no_peer_cert: true]
```

## Connection name

RabbitMQ supports user-specified connection names since version 3.6.2.

Connection names are human-readable strings that will be displayed in the management UI.
Connection names do not have to be unique and cannot be used as connection identifiers.

If the name is `:undefined`, the connection is not registered with any name.

## Examples

    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", port: 5673)
    {:ok, %AMQP.Connection{}}

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