Interface to handle server side communication in an HTTP message exchange.

If simple request -> response transformation is possible, try Raxx.SimpleServer

A module implementing Raxx.Server is run by an HTTP server. For example Ace can run such a module for both HTTP/1.x and HTTP/2 exchanges

Getting Started

Send complete response as soon as request headers are received.

defmodule HelloServer do
  use Raxx.Server

  def handle_head(%Raxx.Request{method: :GET, path: []}, _state) do
    response(:ok)
    |> set_header("content-type", "text/plain")
    |> set_body("Hello, World!")
  end
end

Store data as it is available from a clients request

defmodule StreamingRequest do
  use Raxx.Server

  def handle_head(%Raxx.Request{method: :PUT, body: true}, _state) do
    {:ok, io_device} = File.open("my/path")
    {[], {:file, device}}
  end

  def handle_data(body_chunk, state = {:file, device}) do
    IO.write(device, body_chunk)
    {[], state}
  end

  def handle_tail(_trailers, state) do
    response(:see_other)
    |> set_header("location", "/")
  end
end

Subscribe server to event source and forward notifications to client.

defmodule SubscribeToMessages do
  use Raxx.Server

  def handle_head(_request, _state) do
    {:ok, _} = ChatRoom.join()
    response(:ok)
    |> set_header("content-type", "text/event-stream")
    |> set_body(true)
  end

  def handle_info({ChatRoom, data}, state) do
    {[body(data)], state}
  end
end

Notes

• handle_head/2 will always be called with a request that has body as a boolean. For small requests where buffering the whole request is acceptable a simple middleware can be used.
• Acceptable return values are the same for all callbacks; either a Raxx.Response, which must be complete or a list of message parts and a new state.

Streaming

Raxx.Server defines an interface to stream the body of request and responses.

This has several advantages:

• Large payloads do not need to be help in memory
• Server can push information as it becomes available, using Server Sent Events.
• If a request has invalid headers then a reply can be set without handling the body.
• Content can be generated as requested using HTTP/2 flow control

The body of a Raxx message (Raxx.Request or Raxx.Response) may be one of three types:

• iodata - This is the complete body for the message.
• :false - There is no body, for example :GET requests never have a body.
• :true - There is a body, it can be processed as it is received

Server Isolation

To start an exchange a client sends a request. The server, upon receiving this message, sends a reply. A logical HTTP exchange consists of a single request and response.

Methods such as pipelining and multiplexing combine multiple logical exchanges onto a single connection. This is done to improve performance and is a detail not exposed a server.

A Raxx server handles a single HTTP exchange. Therefore a single connection my have multiple servers each isolated in their own process.

Termination

An exchange can be stopped early by terminating the server process. Support for early termination is not consistent between versions of HTTP.

• HTTP/2: server exit with reason :normal, stream reset with error CANCEL.
• HTTP/2: server exit any other reason, stream reset with error INTERNAL_ERROR.
• HTTP/1.x: server exit with any reason, connection is closed.

Raxx.Server does not provide a terminate callback. Any cleanup that needs to be done from an aborted exchange should be handled by monitoring the server process.