# `Dllb.Connection`
[🔗](https://github.com/Oeditus/dllb_ex/blob/v0.1.0/lib/dllb/connection.ex#L1)

Raw TCP socket operations for communicating with a dllb server.

This module is **not** a GenServer. It provides stateless functions
that operate on a `:gen_tcp` socket, suitable for use inside a
connection pool or standalone.

# `opts`

```elixir
@type opts() :: [
  host: String.t() | charlist(),
  port: :inet.port_number(),
  outcome: Dllb.Protocol.format(),
  timeout: timeout()
]
```

# `alive?`

```elixir
@spec alive?(:gen_tcp.socket()) :: boolean()
```

Checks whether the socket is still open.

Uses `:inet.peername/1` to determine connectivity without
consuming data from the socket.

# `close`

```elixir
@spec close(:gen_tcp.socket()) :: :ok
```

Closes the TCP socket.

# `connect`

```elixir
@spec connect(opts()) :: {:ok, :gen_tcp.socket()} | {:error, term()}
```

Opens a TCP connection to the dllb server and sends the `OUTCOME` command.

## Options

  * `:host` - server hostname (default `"127.0.0.1"`)
  * `:port` - server port (default `3009`)
  * `:outcome` - response format, one of `:json`, `:toon`, `:csv` (default `:json`)
  * `:timeout` - connection and recv timeout in ms (default `30_000`)

Returns `{:ok, socket}` or `{:error, reason}`.

# `query`

```elixir
@spec query(:gen_tcp.socket(), String.t(), Keyword.t()) ::
  {:ok, Dllb.Result.t()} | {:error, term()}
```

Sends a query over an established socket and returns the parsed result.

## Options

  * `:timeout` - recv timeout in ms (default `30_000`)
  * `:outcome` - response format (default `:json`)

Returns `{:ok, result}` or `{:error, reason}`.

---

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