View Source Spaceboy.Conn (Spaceboy v0.3.2)

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

Fetchable fields

These fields are not populated until they are fetched manually.

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 because they would look like: %{"my_username" => ""}

Response fields

You are supposed to set those values during request lifetime with the functions in this module:

  • :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
  • :halted - the boolean status on whether the pipeline was halted
  • :state - the connection state
  • :owner - process which owns the connection

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.

Summary

Types

t()

Connection struct which holds all the data related to Gemini connection

Functions

Assigns a value to a key in the connection

Fetch query params - decode :query_string to t:map()

Set file as response.

Assigns multiple values to keys in the connection.

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

Set response header and potentially body to the function.

Types

state()

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

t()

@type t() :: %Spaceboy.Conn{
  assigns: Keyword.t(),
  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,
  peer_name: {:inet.ip_address(), :inet.port_number()} | nil,
  port: :inet.port_number(),
  query_params: map() | Spaceboy.Conn.Unfetched.t(),
  query_string: String.t() | nil,
  request_id: binary() | nil,
  request_path: String.t(),
  scheme: :gemini,
  state: state()
}

Connection struct which holds all the data related to Gemini connection

Functions

assign(conn, key, value)

@spec assign(conn :: t(), key :: atom(), value :: term()) :: t()

Assigns a value to a key in the connection

fetch_query_params(conn)

@spec fetch_query_params(conn :: t()) :: t()

Fetch query params - decode :query_string to t:map()

file(conn, file_path, mime \\ nil)

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

Set 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.

merge_assigns(conn, assigns)

@spec merge_assigns(conn :: t(), assigns :: Keyword.t()) :: t()

Assigns multiple values to keys in the connection.

Equivalent to multiple calls to assign/3

register_before_send(conn, callback)

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

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

Multiple functions will get executed in LIFO order.

resp(conn, header, body \\ nil)

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

Set response header and potentially body to the function.