Dynamo.Connection behaviour

This modules defines the connection API.

By default, Elixir ships with two implementations of this API: Dynamo.Cowboy.Connection (used by Cowboy web server) and Dynamo.Connection.Test.

Notice that this module documentation uses the record notation. So although the documentation says params(conn), the function should be invoked as conn.params() and Elixir automatically moves the conn to the last argument.

It is also important to remind that, as in all Elixir structures, a connection is immutable. So if you are using conn.put_resp_header("X-API", "123456") to set a response header, a new connection will be returned with the new header set. The original conn is not going to be modified.

Source

Functions summary

default_before_send()

Default values for before send callbacks. It contains callbacks to set content type, configure cookies and session.

Callbacks summary

already_sent?(conn)	Returns a boolean if the connection was already sent or not. This must return the correct result regardless if we have an updated copy of the connection or not.
assign(key, value, conn)	Puts a new assign with the given key and value.
assigns(conn)	Returns a keywords list with assigns set so far.
chunk(body, conn)	Send the given data through the socket. `send_chunked/2` needs to be called before `chunk/2`.
delete_resp_header(key, conn)	Deletes a response header. The header key must be downcased.
fetch(fetch_aspect, conn)	Responsible for fetching and caching aspects of the response. The default "fetchable" aspects are: headers, params, cookies and body.
fetchable(atom, list2, conn)	Register an aspect as fetchable in the connection.
forward_to(segments, module, conn)	Mounts the request by setting the new path information to the given segments. Both scriptname/1 and pathsegments/1 are updated. The segments given must be a suffix of the current path segments.
host(conn)	Returns the request host.
host_url(conn)	Returns the host_url (i.e. containing the scheme, hort and port).
main(conn)	Returns the main module that started the connection the request.
method(conn)	Returns the HTTP method as a binary.
method(method, conn)	Changes the request method to the given `method`, storing the previous value in original_method.
original_method(conn)	Returns the original HTTP method as a binary. Sometimes a filter may change the method from HEAD to GET or from POST to PUT, this function returns the original method.
params(conn)	Returns the params retrieved from the query string and the request body as a `Binary.Dict`. The parameters need to be explicitly fetched with `conn.fetch(:params)` before using this function.
path(conn)	Returns the full path as a binary, as received by the web server.
path_info(conn)	Returns the request path relative to the forwarding endpoint as a binary.
path_info_segments(conn)	Return the path as a list of binaries split on "/". If the request was forwarded request, `path_info_segments` returns only the segments related to the current forwarded endpoint.
path_segments(conn)	Returns the full path segments, as received by the web server.
peer(conn)	The remote host ip address.
port(conn)	Returns the request port.
private(conn)	Returns a keywords list with private assigns set so far.
put_assign(key, value, conn)	The same as `assign/3`.
put_private(key, value, conn)	Sets a new private assign with the given key and value. We recommended private keys to follow the format:
put_resp_cookie(key, value, opts, conn)	Puts the response cookie with the given key, value and list of options.
put_resp_header(key, value, conn)	Puts a response header, overriding any previous value. Both `key` and `value` are converted to binary. The header key must be downcased.
query_string(conn)	Returns the query string as a binary.
req_body(conn)	Returns the request body as a binary.
req_cookies(conn)	Returns the cookies sent in the request as a `Binary.Dict`. Cookies need to be explicitly fetched with `conn.fetch(:cookies)` before using this function.
req_headers(conn)	Returns the request headers as `Binary.Dict`. Note that duplicated entries are removed. The headers need to be explicitly fetched with `conn.fetch(:headers)` before using this function. Headers keys are all downcased.
resp(status, body, conn)	Sets a response to the given status and body. The response will only be sent when `send` is called.
resp_body(conn)	Returns the response body if one was set.
resp_body(body, conn)	Sets the response body and changes the state to `:set`.
resp_charset(conn)	Gets the response charset. Defaults to "utf-8".
resp_charset(charset, conn)	Sets the response charset. The charset is just added to the response if `resp_content_type` is also set.
resp_content_type(conn)	Gets the response content-type.
resp_content_type(content_type, conn)	Sets the response content-type. This is sent as a header when the response is sent.
resp_cookies(conn)	Returns the response cookies as a list of three element tuples containing the key, value and given options.
resp_headers(conn)	Returns the response headers as `Binary.Dict`. Header names are all downcased.
route_params(conn)	Returns the parameters that were set as part of the route matching. This is used internally by Dynamo and a developer likely does not need to invoke it manually.
route_params(t, conn)	Updates the route parameters. This is used internally by Dynamo and a developer does not need to invoke it manually.
scheme(conn)	Returns the request scheme.
script_name(conn)	As in CGI environment, returns the current forwarded endpoint as binary.
script_name_segments(conn)	As in CGI environment, returns the current forwarded endpoint as segments.
send(conn)	A shortcut to `conn.send(conn.status, conn.resp_body)`.
send(status, body, conn)	Sends to the client the given status and body. An updated connection is returned with `:sent` state, the given status and response body set to nil.
send_chunked(status, conn)	Starts to send a chunked response to the client. An updated connection is returned with `:chunked` state, the given status and response body set to nil. Use `chunk/2` to chunk each part of the response.
sendfile(status, path, conn)	Sends the file at the given path. It is expected that the given path exists and it points to a regular file. The file is sent straight away.
state(conn)	Returns the response state. It can be:
status(conn)	Returns the response status if one was set.
status(status, conn)	Sets the response status and changes the state to `:set`.
version(conn)	Returns the HTTP version.

Types

conn :: Dynamo.Connection.t

body :: binary

status :: non_neg_integer

headers :: Binary.Dict.t

method :: binary

segments :: [binary]

charset :: binary

content_type :: binary

fetch_aspect :: :headers | :params | :cookies | :body | atom

main :: module

assigns :: Keyword.t

private :: Keyword.t

scheme :: :http | :https

host :: binary

port_number :: :inet.port_number

host_url :: binary

state :: :unset | :set | :chunked | :sendfile | :sent

Functions

default_before_send()

Default values for before send callbacks. It contains callbacks to set content type, configure cookies and session.

Source

Callbacks

already_sent?(conn)

Specs:

already_sent?(conn) :: boolean

Returns a boolean if the connection was already sent or not. This must return the correct result regardless if we have an updated copy of the connection or not.

Source

assign(key, value, conn)

Specs:

assign(key :: atom, value :: term, conn) :: conn

Puts a new assign with the given key and value.

Source

assigns(conn)

Specs:

assigns(conn) :: assigns

Returns a keywords list with assigns set so far.

Source

chunk(body, conn)

Specs:

chunk(body, conn) :: {:ok, conn} | {:error, atom}

Send the given data through the socket. send_chunked/2 needs to be called before chunk/2.

Source

delete_resp_header(key, conn)

Specs:

delete_resp_header(key :: String.Chars.t, conn) :: conn

Deletes a response header. The header key must be downcased.

Source

fetch(fetch_aspect, conn)

Specs:

fetch(fetch_aspect | [fetch_aspect], conn) :: conn

Responsible for fetching and caching aspects of the response. The default "fetchable" aspects are: headers, params, cookies and body.

Source

fetchable(atom, list2, conn)

Specs:

fetchable(atom, (conn -> conn), conn) :: conn

Source

forward_to(segments, module, conn)

Specs:

forward_to(segments, module, conn) :: conn

Mounts the request by setting the new path information to the given segments. Both scriptname/1 and pathsegments/1 are updated. The segments given must be a suffix of the current path segments.

Source

host(conn)

Specs:

host(conn) :: host

Returns the request host.

Source

host_url(conn)

Specs:

host_url(conn) :: host_url

Returns the host_url (i.e. containing the scheme, hort and port).

Source

main(conn)

Specs:

main(conn) :: main

Returns the main module that started the connection the request.

Source

method(conn)

Specs:

method(conn) :: method

Returns the HTTP method as a binary.

Examples

conn.method #=> "GET"

Source

method(method, conn)

Specs:

method(method, conn) :: conn

Changes the request method to the given method, storing the previous value in original_method.

Source

original_method(conn)

Specs:

original_method(conn) :: method

Returns the original HTTP method as a binary. Sometimes a filter may change the method from HEAD to GET or from POST to PUT, this function returns the original method.

Examples

conn.original_method #=> "GET"

Source

params(conn)

Specs:

params(conn) :: Binary.Dict.t | no_return

Returns the params retrieved from the query string and the request body as a Binary.Dict. The parameters need to be explicitly fetched with conn.fetch(:params) before using this function.

Source

path(conn)

Specs:

path(conn) :: binary

Returns the full path as a binary, as received by the web server.

Source

path_info(conn)

Specs:

path_info(conn) :: binary

Returns the request path relative to the forwarding endpoint as a binary.

Source

path_info_segments(conn)

Specs:

path_info_segments(conn) :: segments

Return the path as a list of binaries split on "/". If the request was forwarded request, path_info_segments returns only the segments related to the current forwarded endpoint.

Source

path_segments(conn)

Specs:

path_segments(conn) :: [binary]

Returns the full path segments, as received by the web server.

Source

peer(conn)

Specs:

peer(conn) :: tuple

The remote host ip address.

Source

port(conn)

Specs:

port(conn) :: port_number

Returns the request port.

Source

private(conn)

Specs:

private(conn) :: assigns

Returns a keywords list with private assigns set so far.

Source

put_assign(key, value, conn)

Specs:

put_assign(key :: atom, value :: term, conn) :: conn

The same as assign/3.

Source

put_private(key, value, conn)

Specs:

put_private(key :: atom, value :: term, conn) :: conn

Sets a new private assign with the given key and value. We recommended private keys to follow the format:

:"#{plugin}_#{key}"

For example, a Dynamo key to store timeout values would be set as: :dynamo_timeout.

Source

put_resp_cookie(key, value, opts, conn)

Specs:

put_resp_cookie(key :: binary, value :: binary | nil, opts :: [], conn) :: conn

Puts the response cookie with the given key, value and list of options.

Source

put_resp_header(key, value, conn)

Specs:

put_resp_header(key :: String.Chars.t, value :: String.Chars.t, conn) :: conn

Puts a response header, overriding any previous value. Both key and value are converted to binary. The header key must be downcased.

Source

query_string(conn)

Specs:

query_string(conn) :: binary

Returns the query string as a binary.

Source

req_body(conn)

Specs:

req_body(conn) :: body | no_return

Returns the request body as a binary.

Source

req_cookies(conn)

Specs:

req_cookies(conn) :: Binary.Dict.t | no_return

Returns the cookies sent in the request as a Binary.Dict. Cookies need to be explicitly fetched with conn.fetch(:cookies) before using this function.

Source

req_headers(conn)

Specs:

req_headers(conn) :: headers | no_return

Returns the request headers as Binary.Dict. Note that duplicated entries are removed. The headers need to be explicitly fetched with conn.fetch(:headers) before using this function. Headers keys are all downcased.

Source

resp(status, body, conn)

Specs:

resp(status, body, conn) :: conn

Sets a response to the given status and body. The response will only be sent when send is called.

After calling this function, the state changes to :set, both status and resp_body are set.

Source

resp_body(conn)

Specs:

resp_body(conn) :: body | nil

Returns the response body if one was set.

Source

resp_body(body, conn)

Specs:

resp_body(body, conn) :: conn

Sets the response body and changes the state to :set.

Source

resp_charset(conn)

Specs:

resp_charset(conn) :: binary

Gets the response charset. Defaults to "utf-8".

Source

resp_charset(charset, conn)

Specs:

resp_charset(charset, conn) :: conn

Sets the response charset. The charset is just added to the response if resp_content_type is also set.

Source

resp_content_type(conn)

Specs:

resp_content_type(conn) :: binary | nil

Gets the response content-type.

Source

resp_content_type(content_type, conn)

Specs:

resp_content_type(content_type, conn) :: conn

Sets the response content-type. This is sent as a header when the response is sent.

Source

resp_cookies(conn)

Specs:

resp_cookies(conn) :: [{binary, binary, []}]

Returns the response cookies as a list of three element tuples containing the key, value and given options.

Source

resp_headers(conn)

Specs:

resp_headers(conn) :: Binary.Dict.t

Returns the response headers as Binary.Dict. Header names are all downcased.

Source

route_params(conn)

Specs:

route_params(conn) :: Keyword.t

Returns the parameters that were set as part of the route matching. This is used internally by Dynamo and a developer likely does not need to invoke it manually.

Source

route_params(t, conn)

Specs:

route_params(Keyword.t, conn) :: conn

Updates the route parameters. This is used internally by Dynamo and a developer does not need to invoke it manually.

Source

scheme(conn)

Specs:

scheme(conn) :: scheme

Returns the request scheme.

Source

script_name(conn)

Specs:

script_name(conn) :: binary

As in CGI environment, returns the current forwarded endpoint as binary.

Source

script_name_segments(conn)

Specs:

script_name_segments(conn) :: segments

As in CGI environment, returns the current forwarded endpoint as segments.

Source

send(conn)

Specs:

send(conn) :: conn

A shortcut to conn.send(conn.status, conn.resp_body).

Source

send(status, body, conn)

Specs:

send(status, body :: term, conn) :: conn

Sends to the client the given status and body. An updated connection is returned with :sent state, the given status and response body set to nil.

Source

send_chunked(status, conn)

Specs:

send_chunked(status, conn) :: conn

Starts to send a chunked response to the client. An updated connection is returned with :chunked state, the given status and response body set to nil. Use chunk/2 to chunk each part of the response.

Source

sendfile(status, path, conn)

Specs:

sendfile(status, path :: binary, conn) :: conn

Sends the file at the given path. It is expected that the given path exists and it points to a regular file. The file is sent straight away.

Source

state(conn)

Specs:

state(conn) :: state

Returns the response state. It can be:

:unset - the response was not configured yet
:set - the response was set via conn.resp_body or conn.status
:chunked - the response is being sent in chunks
:sent - the response was sent

Source

status(conn)

Specs:

status(conn) :: status

Returns the response status if one was set.

Source

status(status, conn)

Specs:

status(status, conn) :: conn

Sets the response status and changes the state to :set.

Source

version(conn)

Specs:

version(conn) :: binary

Returns the HTTP version.

Source