# `FireMQ.Connection`
[🔗](https://github.com/FireMQ/firemq-elixir/blob/v0.1.0/lib/firemq/connection.ex#L1)

A connection to FireMQ: a process that owns one TCP or TLS socket.

The connection sends requests and matches replies by request id, tracks publisher
confirms, hands deliveries to subscribers, grants credit and exchanges heartbeats. Use
the functions in `FireMQ` to talk to it.

## Starting a connection

`FireMQ.connect/2` opens a connection that belongs to the calling process: it closes
when that process exits. Its exit does not affect the caller.

`start_link/1` opens a connection linked to the caller, which suits a supervisor:

    children = [
      {FireMQ.Connection, url: "fire://guest:guest@localhost:5673", name: MyApp.FireMQ}
    ]

    Supervisor.start_link(children, strategy: :one_for_one)

Then call `FireMQ.publish(MyApp.FireMQ, "", "jobs", "hello")`.

When the broker closes the connection or the socket fails, the process exits with
`{:shutdown, %FireMQ.Error{}}` and a supervisor starts a new one. The connection does
not reconnect on its own, and subscriptions do not survive a restart: subscribers
receive `{:firemq_cancelled, sub_ref, %FireMQ.Error{}}` and must subscribe again.

## Options

  * `:url` - the connection URL. Defaults to `"fire://localhost"`.
  * `:name` - registers the process under a name (`start_link/1` only).
  * `:heartbeat` - desired heartbeat interval in seconds; `0` disables heartbeats.
    Defaults to `30`.
  * `:connection_name` - a name shown in the management UI.
  * `:connect_timeout` - how long to wait for the TCP connection and the handshake, in
    milliseconds. Defaults to `10_000`.
  * `:ssl` - options for `:ssl.connect/3` on `fires://` URLs, merged over the defaults
    (`verify: :verify_peer` with the system CA store). For example
    `ssl: [cacertfile: "ca.pem"]` or, for local development only,
    `ssl: [verify: :verify_none]`.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `start_link`

```elixir
@spec start_link(keyword()) :: GenServer.on_start()
```

Starts a connection linked to the caller. See the module documentation for options.

Returns `{:error, %FireMQ.Error{}}` when the broker cannot be reached or refuses the
handshake.

---

*Consult [api-reference.md](api-reference.md) for complete listing*