Spaceboy.Conn (Spaceboy v0.1.1) View Source

Struct representing Spaceboy connection (request) roughly equivalent to Plug.Conn

This is main struct that will go through the whole request lifetime.

Request fields

These values are set by the framework and you are supposed to treat them as read-only

:scheme - is always :gemini (no other schemes are supported)
:host - will be set to host from request
:port - listening port (default 1965)
:remote_ip - IP address of the client (or closest proxy)
:path_info - path segments
:request_path - default path as received from client
:query_string - query string as received from client
:peer_cert - client certificate

Fetchabel fields

These fields are not populated until they are fetched manually.

:path_params - fetched by Spaceboy.Router
:query_params - fetched by fetch_query_params/1
:params - combined field of :path_params and :query_params

Those fields requires manual fetching because you don't always want to format e.g. query. If you are using query for simple user input (e.g. username) and the query looks like &my_username you actually don't want to fetch it and create params from it.

Response fields

You are supposed to set those values during request lifetime

:header - header struct for the response
:body - response body or file path

Furthermore, the before_send field stores callbacks that are invoked before the connection is sent.

Connection fields

:assigns - user data (currently unused)
:owner - process which owns the connection
:halted - the boolean status on whether the pipeline was halted
:state - the connection state

The connection state is used to track the connection lifecycle. It starts as :unset but is changed to :set or :set_file when response is set. Its final result is :sent.

Link to this section Summary

Types

state()

t()

Functions

auth_required(conn, prompt \\ "Certificate is missing")

Set client certificate required response

fetch_query_params(conn)

Fetch query params - decode query_string to map()

file(conn, file_path, mime \\ nil)

Add file as response.

gemini(conn, content)

Add text/gemini string as response

input(conn, prompt)

Set input response

json(conn, content)

Add map as JSON response

not_found(conn, prompt \\ "Page not found")

Set not found response

redirect(conn, path)

Set redirect response

register_before_send(conn, callback)

Add function to be run righ before the response is actually send.

resp(conn, header, body \\ nil)

Add response header and potentially body to the function.

Link to this section Types

state()

Specs

state() :: :unset | :set | :set_file | :sent

t()

Specs

t() :: %Spaceboy.Conn{
  assigns: map(),
  before_send: [(t() -> t())],
  body: String.t() | nil,
  halted: boolean(),
  header: Spaceboy.Header.t() | nil,
  host: String.t(),
  owner: pid() | nil,
  params: map() | Spaceboy.Conn.Unfetched.t(),
  path_info: [String.t()],
  path_params: map() | Spaceboy.Conn.Unfetched.t(),
  peer_cert: binary() | :no_peercert,
  port: :inet.port_number(),
  query_params: map() | Spaceboy.Conn.Unfetched.t(),
  query_string: String.t() | nil,
  remote_ip: :inet.ip_address() | nil,
  request_path: String.t(),
  scheme: :gemini,
  state: state()
}

Link to this section Functions

auth_required(conn, prompt \\ "Certificate is missing")

Specs

auth_required(conn :: t(), prompt :: String.t()) :: t()

Set client certificate required response

fetch_query_params(conn)

Specs

fetch_query_params(conn :: t()) :: t()

Fetch query params - decode query_string to map()

file(conn, file_path, mime \\ nil)

Specs

file(conn :: t(), file_path :: Path.t(), mime :: String.t() | nil) :: t()

Add file as response.

Third argument is MIME type of the file. If it is not set the function will use MIME.from_path/1 function to guess its type.

gemini(conn, content)

Specs

gemini(conn :: t(), content :: String.t()) :: t()

Add text/gemini string as response

input(conn, prompt)

Specs

input(conn :: t(), promt :: String.t()) :: t()

Set input response

json(conn, content)

Specs

json(conn :: t(), content :: map()) :: t()

Add map as JSON response

not_found(conn, prompt \\ "Page not found")

Specs

not_found(conn :: t(), prompt :: String.t()) :: t()

Set not found response

redirect(conn, path)

Specs

redirect(conn :: t(), path :: String.t()) :: t()

Set redirect response

register_before_send(conn, callback)

Specs

register_before_send(conn :: t(), callback :: (t() -> t())) :: t()

Add function to be run righ before the response is actually send.

Multiple functions will get executed in FIFO order.

Examples

iex> conn = Spaceboy.Conn.register_before_send(%Spaceboy.Conn{}, fn conn -> conn end)
iex> length(conn.before_send)
1
iex> is_function(hd(conn.before_send), 1)
true

resp(conn, header, body \\ nil)

Specs

resp(conn :: t(), header :: Spaceboy.Header.t(), body :: String.t() | nil) ::
  t()

Add response header and potentially body to the function.