fake_riak

defmodule FakeRiak.Protocol do
  @moduledoc """
  Behaviour implemented by every wire-protocol handler (Riak, Redis, etcd,
  memcached).

  A handler is a pure request parser driven by `FakeRiak.Connection`:

    * `init/0` returns the initial per-connection parser state.

    * `parse/2` is handed the bytes received so far plus the current state and
      returns one of:

        - `{:reply, response, rest, state}` — a complete request was parsed;
          `response` (iodata) is sent back and parsing continues on `rest`.
        - `{:need_more, state}` — the buffer does not yet contain a full
          request; the loop reads more bytes and calls `parse/2` again.
        - `{:close, response}` — send the (possibly empty) `response` and close
          the connection.
        - `{:upgrade_tls, response, rest, state}` — send `response` over the
          current transport, then upgrade the socket to TLS (see Riak's
          `RpbStartTls`) and continue parsing with the same state. Only
          meaningful on a plain-TCP transport; an already-TLS connection is
          closed instead.
  """

  @type state :: term()
  @type result ::
          {:reply, iodata(), binary(), state()}
          | {:need_more, state()}
          | {:close, iodata()}
          | {:upgrade_tls, iodata(), binary(), state()}

  @callback init() :: state()
  @callback parse(buffer :: binary(), state()) :: result()
end