raxx

v0.14.9

raxx v0.14.9 Raxx

Tooling to work with HTTP.

Several data structures are defined to model parts of the communication between client and server.

  • Raxx.Request: metadata sent by a client before sending content.
  • Raxx.Response: metadata sent by a server before sending content.
  • Raxx.Data: A part of a messages content.
  • Raxx.Tail: metadata set by client or server to conclude communication.

This module contains functions to create and manipulate these structures.

See Raxx.Server for implementing a web application.

Link to this section Summary

Types

body()

The body of a Raxx message

header()

Attribute value pair that can be serialized to an HTTP request or response

headers()

List of HTTP headers

message()

Either a Raxx.Request.t or a Raxx.Response.t

Functions

complete?(map)

Does the message struct contain all the data to be sent

data(data)

Construct a Raxx.Data

html_escape(data)

Escapes the given HTML to string

html_escape_to_iodata(data)

Escapes the given HTML to iodata

is_application?(arg)

Can application be run by compatable server?

normalized_path(request)
reason_phrase(int)

The RFC7231 specified reason phrase for each known HTTP status code. Extra reason phrases can be defined in raxx config under extra_status

request(method, url)

Construct a Raxx.Request

response(status_code)

Construct a Raxx.Response

set_body(message, body)

Add a complete body to a message

set_header(message, name, value)

Set the value of a header field

set_query(request, query)

Add a query value to a request

split_path(path_string)

Split a path on forward slashes

tail(headers \\ [])

Construct a Raxx.Tail

verify_application(arg)

Verify application can be run by compatable server?

Link to this section Types

Link to this type body() 
body() :: boolean() | String.t()

The body of a Raxx message.

The body can be:

  • part of the message (String.t()).
  • empty (false).
  • present but unknown (true).
Link to this type header() 
header() :: {String.t(), String.t()}

Attribute value pair that can be serialized to an HTTP request or response

Link to this type headers() 
headers() :: [header()]

List of HTTP headers.

Link to this type message() 
message() :: Raxx.Request.t() | Raxx.Response.t()

Either a Raxx.Request.t or a Raxx.Response.t

Link to this section Functions

Link to this function complete?(map) 
complete?(message()) :: boolean()

Does the message struct contain all the data to be sent.

Examples 

iex> request(:GET, "/")
...> |> complete?()
true

iex> response(:ok)
...> |> set_body("Hello, World!")
...> |> complete?()
true

iex> response(:ok)
...> |> set_body(true)
...> |> complete?()
false
Link to this function data(data) 
data(String.t()) :: Raxx.Data.t()

Construct a Raxx.Data

Wrap a piece of data as being part of a message’s body.

Examples 

iex> data("Hi").data
"Hi"
Link to this function html_escape(data) 
html_escape(String.t()) :: String.t()

Escapes the given HTML to string.

iex> html_escape("foo")
"foo"

iex> html_escape("<foo>")
"&lt;foo&gt;"

iex> html_escape("quotes: \" & \'")
"quotes: &quot; &amp; &#39;"
Link to this function html_escape_to_iodata(data) 
html_escape_to_iodata(String.t()) :: iodata()

Escapes the given HTML to iodata.

iex> html_escape_to_iodata("foo")
"foo"

iex> html_escape_to_iodata("<foo>")
[[[] | "&lt;"], "foo" | "&gt;"]

iex> html_escape_to_iodata("quotes: \" & \'")
[[[[], "quotes: " | "&quot;"], " " | "&amp;"], " " | "&#39;"]
Link to this function is_application?(arg) 
is_application?({module(), any()}) :: boolean()

Can application be run by compatable server?

Examples 

iex> is_application?({Raxx.ServerTest.DefaultServer, %{}})
true

iex> is_application?({GenServer, %{}})
false

iex> is_application?({NotAModule, %{}})
false
Link to this function normalized_path(request)
Link to this function reason_phrase(int) 
reason_phrase(integer()) :: String.t()

The RFC7231 specified reason phrase for each known HTTP status code. Extra reason phrases can be defined in raxx config under extra_status.

For example.

config :raxx,
  :extra_statuses, ["422", "Unprocessable Entity"]

Examples 

iex> reason_phrase(200)
"OK"

iex> reason_phrase(500)
"Internal Server Error"

iex> reason_phrase(422)
"Unprocessable Entity"
Link to this function request(method, url) 
request(Raxx.Request.method(), String.t() | URI.t()) :: Raxx.Request.t()

Construct a Raxx.Request.

An HTTP request must have a method and path.

If the location argument is a relative path the scheme and authority values will be unset. When these values can be inferred from the location they will be set.

The method must be an atom for one of the HTTP methods

[:GET, :POST, :PUT, :PATCH, :DELETE, :HEAD, :OPTIONS]

The request will have no body or headers. These can be added with set_header/3 and set_body/2.

Examples 

iex> request(:HEAD, "/").method
:HEAD

iex> request(:GET, "/").path
[]

iex> request(:GET, "/foo/bar").path
["foo", "bar"]

iex> request(:GET, "https:///").scheme
:https

iex> request(:GET, "https://example.com").authority
"example.com"

iex> request(:GET, "/?foo=bar").query
%{"foo" => "bar"}

iex> request(:GET, "/?foo[bob]=bar").query
%{"foo" => %{"bob" => "bar"}}

iex> request(:GET, "/").headers
[]

iex> request(:GET, "/").body
false
Link to this function response(status_code) 
response(Raxx.Response.status_code() | atom()) :: Raxx.Response.t()

Construct a Raxx.Response.

The responses HTTP status code can be provided as an integer, or will be translated from a known atom.

The response will have no body or headers. These can be added with set_header/3 and set_body/2.

Examples 

iex> response(200).status
200

iex> response(:no_content).status
204

iex> response(200).headers
[]

iex> response(200).body
false
Link to this function set_body(message, body) 
set_body(Raxx.Request.t(), body()) :: Raxx.Request.t()
set_body(Raxx.Response.t(), body()) :: Raxx.Response.t()

Add a complete body to a message.

Examples 

iex> request(:GET, "/")
...> |> set_body("Hello")
...> |> Map.get(:body)
"Hello"
Link to this function set_header(message, name, value) 
set_header(Raxx.Request.t(), String.t(), String.t()) :: Raxx.Request.t()
set_header(Raxx.Response.t(), String.t(), String.t()) :: Raxx.Response.t()

Set the value of a header field.

Examples 

iex> request(:GET, "/")
...> |> set_header("referer", "example.com")
...> |> set_header("accept", "text/html")
...> |> Map.get(:headers)
[{"referer", "example.com"}, {"accept", "text/html"}]
Link to this function set_query(request, query) 
set_query(Raxx.Request.t(), %{optional(binary()) => binary()}) :: Raxx.Request.t()

Add a query value to a request

Examples 

iex> request(:GET, "/")
...> |> set_query(%{"value" => "1"})
...> |> Map.get(:query)
%{"value" => "1"}
Link to this function split_path(path_string) 
split_path(String.t()) :: [String.t()]

Split a path on forward slashes.

Examples 

iex> split_path("/foo/bar")
["foo", "bar"]
Link to this function tail(headers \\ []) 
tail([{String.t(), String.t()}]) :: Raxx.Tail.t()

Construct a Raxx.Tail

Examples 

iex> tail([{"digest", "opaque-data"}]).headers
[{"digest", "opaque-data"}]

iex> tail().headers
[]
Link to this function verify_application(arg) 
verify_application({module(), any()}) ::
  {:ok, {module(), any()}} |
  {:error, String.t()}

Verify application can be run by compatable server?

Examples 

iex> verify_application({Raxx.ServerTest.DefaultServer, %{}})
{:ok, {Raxx.ServerTest.DefaultServer, %{}}}

iex> verify_application({GenServer, %{}})
{:error, "module [`GenServer`](https://hexdocs.pm/elixir/GenServer.html) does not implement [`Raxx.Server`](Raxx.Server.html) behaviour."}

iex> verify_application({NotAModule, %{}})
{:error, "module `NotAModule` is not available."}