[Hexdocs](https://hexdocs.pm/bricks)
<!-- [Combidocs](https://hexdocs.pm/bricks_suite) -->

# bricks

The elixir sockets library of your dreams!

## Motivation

The OTP `:gen_tcp` and `:ssl` libraries have quite a few pain points:

- A different (albeit identical) API per socket type
- Different active mode message tags per socket type
- Risk of mailbox overflow-induced BEAM crash in active mode
- `ssl` ignores your intended socket state options on handshake
- `gen_tcp` sockets default to a different activity mode for a unix socket
- Confusing documentation
- Lack of useful examples

This library attempts to address these problems.

Goals:

- Intuitive high-level API for common tasks
- Simple low-level API for advanced purposes
- Fully embrace active and passive socket modes, avoiding active overflow
- Do not force a process model on the user
- Examples of common use cases

## Status: Beta

Bricks represents months of research and development. It is a
production quality library and well tested.

There is a possibility there will be small API tweaks in the run-up to 1.0

## Installation

Add to your deps:

```
{:bricks, "~> 0.1"}
```

## Overview

### Sockets

A Socket represents a *connected* Socket - that is it is
manufactured *after* a connection has been established.
  
As in Erlang/OTP, a Socket is owned by a single process, the owner. No
other process may interact with the Socket, but the owner can hand off
ownership to another process. If the owner process dies, the socket
will be closed.
  
A Socket is at any given time (as per OTP) in one of these modes:

- `passive` mode -  data can only be received when you call `recv`.

- `active` mode - the socket transforms packets into messages as
  they arrive and transmits them to the owner.

- `bounded active` mode - like `active` mode, but caps the number of
  packets that will be buffered in the owner mailbox before
  requiring a reset by the owner. See section later.

#### Picking a mode

If you are running a *service* process (such as a `GenServer`), you
generally do not want to use `passive` mode as it holds up the event
loop. Prefer `bounded active` mode (or `active` if you *must*).

Otherwise, all modes are available to you:

- `passive` mode: *a safe default* when you don't have aggressive
  performance requirements, but calling `recv` holds up responding to
  messages, so it's not generally suitable for a GenServer.

- `active` mode: the process mailbox becomes an effectively
  unlimited sized buffer. If you fail to keep up, you might buffer
  until the BEAM has eaten all of the memory and gets killed. But
  while it doesn't, it's low latency and high throughput.
  *WARNING: You almost certainly want bounded active. Active mode
  puts you at risk of BEAM crash. I hope you know what you're doing.*

- `bounded active` mode: like active mode, but caps the number of
  packets that will be buffered in the owner mailbox. Achieves
  better performance than `passive` mode but without the risks
  associated with `active` mode.

#### Bounded Active Mode

In addition to taking a boolean value, `set_active` can take an
integer, entering what I call `bounded active` mode (BAM).  BAM
provides most of the performance benefits of `active` mode with the
security of not having your BEAM get OOMkilled from overbuffering.
If passive mode doesn't meet your needs, use BAM - avoid OOM!

In BAM, the socket behaves as in `active` mode, sending messages
that are received to the owner. However, it also maintains an
internal `active window` counter of the number of packets that may
be received in active mode, after which the socket is placed into
passive mode and a notification message is sent to the owner who can
put the socket back into BAM with `set_active/2`.

The `bam_window` field in the `Socket` struct holds the intended active
window. It is used by `extend_active/1` to easily reset BAM.

##### Enabling and using BAM

`set_active/2` can take the following values:
  - `true`  - enable `active` mode
  - `false` - enable `passive` mode
  - `:once` - enable BAM for one packet
  - `integer()` - adjust the internal active window counter by this
                  many, send a message to notify the owner when the
                  socket is made passive.

Note that while the first three all set the value, providing an
integer can behave in two ways, depending on the current mode:

- You are not in BAM, the active counter is *set* to this
  value. If it is zero or lower, the socket is made passive.

- You are in BAM, the active counter is *adjusted by* this value
  (by addition). If you pass a negative number and cause the
  counter to go 0 or lower, the socket is made passive.

When providing an integer, when the socket is made passive by the
active counter hitting 0, a notification is sent. This is *only*
triggered by providing an integer, not by `:once`.

We recommend only using `set_active/2` with a positive integer and
when the socket is in passive mode (such as when you have been
informed the socket has just been made passive). This simplifies the
problem and you can pretend that it *does* set the internal counter.

If you ignore the last paragraph, you'll have to keep track of the
current active window to know what the new one will be after calling
`set_active/2`. The (undocumented) `decr_active/1` function may be
useful to call when you receive a packet. You could also use
`fetch_active/1`, but this will be slower.

This behaviour is inherited from OTP. We would not choose to implement
it this way ourselves.

#### Connectors

The simplest way to get a socket is to use a `Connector`. Connectors
are responsible for establishing a connection. There are `Tcp`, `Tls`
and `Unix` connectors at present.

You may use `Bricks.Connector.connect/1` to connect a connector:

```elixir
{:ok, conn} = Bricks.Connector.Tcp.new(%{host: "example.org", port: 80})
{:ok, socket} = Bricks.Connector.connect(conn)
```

Connectors perform validation and construction of underlying options
at construction time so you don't pay the penalty for each new
connection unless you change something.n

##### TCP Connector

```elixir
# Note: Optional arguments are shown with their default values
{:ok, tcp} = Bricks.Connector.Tcp.new(%{
  host: "example.org",   # required
  port: 80,              # required
  # common optional arguments
  bam_window: 10,        # bam_window on the created socket
  receive_timeout: 5000, # receive_timeout on the created socket in ms
  connect_timeout: 5000, # in ms
  send_timeout: 5000,    # in ms
  active: false,         # default activity mode
  ipv6?: true,           # ipv6 support
  # for full options, see moduledocs for `Bricks.Connector.Tcp`
})
```

The `Tcp` connector uses `gen_tcp` to establish a connection.

##### Unix Connector

```elixir
# Note: Optional arguments are shown with their default values
{:ok, unix} = Bricks.Connector.Unix.new("/var/run/example.sock", %{
  path: "/var/run/example.sock", # required
  # common optional arguments
  bam_window: 10,                # bam_window on the created socket
  connect_timeout: 3000,         # in ms
  receive_timeout: 3000,         # receive_timeout on the created socket in ms
  send_timeout:    3000,         # in ms
  active: false,                 # default activity mode
  # for full options, see moduledocs for `Bricks.Connector.Unix`
})
```

The `Unix` connector uses `:gen_tcp` to establish a connection.

## Usage Examples

### Passive Mode
  
#### Echo Service Client (Basic)

```elixir
alias Bricks.Connector.Unix
alias Bricks.{Connector, Socket}

def passive_echo() do

  # First we need to connect
  unix = Unix.new("/var/run/echo.sock")   # Configure
  {:ok, socket} = Connector.connect(unix) # Connect
  {:ok, "", socket} = Socket.passify(h)   # Set passive

  # Now we talk to the fictional echo service
  :ok = Socket.send_data(socket, "hello world\n")           # Send
  {:ok, "hello world\n", socket} = Socket.recv(socket, 0)   # Receive
  :ok = Socket.send_data(socket, "goodbye world\n")         # Send
  {:ok, "goodbye world\n", socket} = Socket.recv(socket, 0) # Receive

  :ok = Socket.close(socket) # Tidy up
end
```

### Active Mode

#### Echo Service Client (Basic)

```elixir
alias Bricks.Connector.Unix
alias Bricks.{Connector, Socket}
import Bricks.Sugar

def active_echo() do
  # First we need to connect
  unix = Unix.new("/var/run/echo.sock")           # Configure
  {:ok, socket} = Connector.connect(unix)         # Connect
  {:ok, socket} = Socket.set_active(socket, true) # Set active
  # Now we talk to the fictional echo service
  :ok = Socket.send_data(socket, "hello world\n") # Send
  binding socket do
    receive do
      match_data("hello world\n") -> :ok    # Receive
      match_closed()              -> {:error, :closed}
      match_error(reason)         -> {:error, reason}
    after 1000 -> throw :timeout
    end
  end
  :ok = Socket.close(socket) # Tidy up
end
```

#### Echo Service Client (Basic - No Sugar)

```elixir
alias Bricks.Connector.Unix
alias Bricks.{Connector, Socket}

def active_echo() do
  # First we need to connect
  unix = Unix.new("/var/run/echo.sock")           # Configure
  {:ok, socket} = Connector.connect(unix)         # Connect
  {:ok, socket} = Socket.set_active(socket, true) # Set active
  %Socket{                                        # Match out receive pins
    handle:     handle, # Internal socket handle
    data_tag:   data,   # Tag for data messages
    error_tag:  error,  # Tag for error messages
    closed_tag: closed, # Tag for closed messages
  }=socket

  # Now we talk to the fictional echo service
  :ok = Socket.send_data(socket, "hello world\n") # Send
  receive do
    {^data,   ^handle, "hello world\n"} -> :ok    # Receive
    {^closed, ^handle}         -> throw {:error, :closed}
    {^error,  ^handle, reason} -> throw {:error, reason}
  after 1000 -> throw :timeout
  end
  :ok = Socket.close(socket) # Tidy up
end
```

#### Slurp All (GenServer)

```elixir
defmodule GenServerExample do
  alias Bricks.{Connector, Socket}
  require Logger
  use GenServer
  import Bricks.Sugar

  def init([connector]) do
    {:ok, socket} = Connector.connect(connector)
    {:ok, socket} = Socket.set_active(socket, true)
    {:ok, socket}
  end

  defhandle_info data(SOCKET=socket, data) do
    Logger.info("Got data: " <> data)
    {:noreply, socket}
  end
 
  defhandle_info error(SOCKET=socket, data) do
    {:stop, reason, socket}
  end

  defhandle_info closed(SOCKET=socket) do
    {:stop, :closed, socket}
  end
end
```

#### Slurp All (GenServer - No Sugar)

```elixir
defmodule GenServerExample do
  use GenServer
  require Logger
  alias Bricks.{Connector, Socket}

  def init([connector]) do
    {:ok, socket} = Connector.connect(connector)
    {:ok, socket} = Socket.set_active(socket, true)
    {:ok, socket}
  end

  def handle_info({tag, handle, data}, socket=%Socket{handle: handle2, data_tag: tag2})
  when handle == handle2 and tag == tag2 do
    Logger.info("Got data: " <> data)
    {:noreply, socket}
  end

  def handle_info({tag, handle, reason}, socket=%Socket{handle: handle2, error_tag: tag2})
  when handle == handle2 and tag == tag2 do
    {:stop, reason, socket}
  end

  def handle_info({tag, handle}, socket=%Socket{handle: handle2, closed_tag: tag2})
  when handle == handle2 and tag == tag2 do
    {:stop, :closed, socket}
  end
end
```

### Bounded Active Mode

#### Echo Service Client (Basic)

```elixir
alias Bricks.Connector.Unix
alias Bricks.{Connector, Socket}

def bounded_active_echo() do

  # First we need to connect
  unix = Unix.new("/var/run/echo.sock")            # Configure
  {:ok, socket} = Connector.connect(unix)          # Connect
  {:ok, socket} = Socket.set_active(socket, false) # Set passive

  # Now we talk to the fictional echo service
  {:ok, socket} = Socket.set_active(socket, :once) # Set active for one packet
  :ok = Socket.send_data(socket, "hello world\n")  # Send
  binding socket do
    receive do
      match_data("hello world\n") -> :ok # Receive
      match_closed()      -> {:error, :closed}
      match_error(reason) -> {:error, reason}
    after 1000 -> throw :timeout
    end
  end
  :ok = Socket.close(socket) # Tidy up
end
```

#### Echo Service Client (Basic - No Sugar)

```elixir
alias Bricks.Connector.Unix
alias Bricks.{Connector, Socket}

def bounded_active_echo() do

  # First we need to connect
  unix = Unix.new("/var/run/echo.sock")            # Configure
  {:ok, socket} = Connector.connect(unix)          # Connect
  {:ok, socket} = Socket.set_active(socket, false) # Set passive
  %Socket{                                         # Match out receive pins
    handle: handle,     # Internal socket handle
    data_tag: data,     # Tag for data messages
    error_tag: error,   # Tag for error messages
    closed_tag: closed, # Tag for closed messages
  }=socket

  # Now we talk to the fictional echo service
  {:ok, socket} = Socket.set_active(socket, :once) # Set active for one packet
  :ok = Socket.send_data(socket, "hello world\n")  # Send
  receive do
    {^data,   ^handle, "hello world\n"} -> :ok       # Receive
    {^closed, ^handle}         -> throw {:error, :closed}
    {^error,  ^handle, reason} -> throw {:error, reason}
  after 1000 -> throw :timeout
  end
  {:ok, socket} = Socket.set_active(socket, :once)  # Set active for one packet
  :ok = Socket.send_data(socket, "goodbye world\n") # Send
  receive do
    {^data,   ^handle, "goodbye world\n"} -> :ok      # Receive
    {^closed, ^handle}         -> throw {:error, :closed}
    {^error,  ^handle, reason} -> throw {:error, reason}
  after 1000 -> throw :timeout
  end

  :ok = Socket.close(socket) # Tidy up
end
```

#### Slurp All (GenServer)

```elixir
defmodule GenServerExample do
  use GenServer
  require Logger
  alias Bricks.{Connector, Socket}

  def init([connector]) do
    {:ok, socket} = Connector.connect(connector)
    {:ok, socket} = Socket.extend_active(socket)
    {:ok, socket}
  end

  defhandle_info data(SOCKET=socket, data) do
    Logger.info("Got data: " <> data)
    {:noreply, socket}
  end

  defhandle_info error(SOCKET=socket, reason) do
    {:stop, reason, socket}
  end

  defhandle_info closed(SOCKET=socket) do
    {:stop, :closed, socket}
  end

  defhandle_info passive(SOCKET=socket) do
    {:ok, socket} = Socket.extend_active(socket)
    {:noreply, socket}
  end

end
```

#### Slurp All (GenServer - No Sugar)

```elixir
defmodule GenServerExample do
  use GenServer
  require Logger
  alias Bricks.{Connector, Socket}

  def init([connector]) do
    {:ok, socket} = Connector.connect(connector)
    {:ok, socket} = Socket.extend_active(socket)
    {:ok, socket}
  end

  def handle_info({tag, handle, data}, socket=%Socket{handle: handle2, data_tag: tag2})
  when handle == handle2 and tag == tag2 do
    Logger.info("Got data: " <> data)
    {:noreply, socket}
  end

  def handle_info({tag, handle, reason}, socket=%Socket{handle: handle2, error_tag: tag2})
  when handle == handle2 and tag == tag2 do
    {:stop, reason, socket}
  end

  def handle_info({tag, handle}, socket=%Socket{handle: handle2, closed_tag: tag2})
  when handle == handle2 and tag == tag2 do
    {:stop, :closed, socket}
  end

  def handle_info({tag, handle}, socket=%Socket{handle: handle2, passive_tag: tag2})
  when handle == handle2 and tag == tag2 do
    {:ok, socket} = Socket.extend_active(socket)
    {:noreply, socket}
  end

end
```

## Contributing

Contributions are welcome, even just doc fixes or suggestions.

This project has adopted a [Code of Conduct](CONDUCT.md) based on the
Contributor Covenant. Please be nice when interacting with the community.

## Copyright and License

Copyright (c) 2018 James Laver

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.