cowmachine v1.12.1

View Source cowmachine_req (cowmachine v1.12.1)

Request functions for cowmachine.

Link to this section Summary

Types

context/0

The request context stores everything needed for the request handling.

context_map/0
halt/0
Used to stop a request with a specific HTTP status code
media_type/0
Media types for accepted and provided content types
outputfun/0
parts/0
ranges/0
resp_body/0
Response body, can be data, a file, device or streaming functions.
streamdata/0
streamfun/0
Streaming function, repeatedly called to fetch the next chunk
streamfun_next/0
writerfun/0
Writer function, calls output function till finished

Functions

base_uri(Context)
Return the base uri of the request.
controller(Context)
Return the current cowmachine controller.
controller_options(Context)
Return the current cowmachine controller options.
disp_path(Context)
Return the dispatch path of the request.
encode_content(Content, Context)
Encode the content according to the selected content encoding.
env(Context)
Fetch the cowboy middleware env from the context.
get_cookie_value(Name, Context)
Fetch the value of a cookie.
get_metadata(Key, Context)
get_req_header(Header, Context)
Fetch a request header, the header must be a lowercase binary.
get_req_headers(Context)
Fetch all request headers.
get_resp_cookies(Context)
Fetch all response cookies.
get_resp_header(Header, Context)
Fetch the response header, undefined if not set.
get_resp_headers(Context)
Fetch all response headers.
has_req_body(Context)
Check if the request has a body
has_resp_body(Context)
Check if a response body has been set.
host(Context)
Return the http host.
init_context(Req, Env, Options)
Initialize the context with the Req and Env.
init_env(Req, Env)
Set some intial metadata in the cowboy req.
is_proxy(Context)
Check if the request is forwarded by a proxy.
is_range_ok(Context)
Fetch the is_range_ok flag.
is_ssl(Context)
Check if the connection is secure (SSL).
method(Context)
Return the request Method.
path(Context)
Return the undecoded request path as-is.
path_info(Context)
Fetch all bindings from the dispatcher.
peer(Context)
Return the peer of this request, take x-forwarded-for into account if the peer is an ip4 LAN address.
peer_ip(Context)
Return the peer of this request, take x-forwarded-for into account if the peer is an ip4 LAN address.
port(Context)
Return the http port.
qs(Context)
Return the undecoded query string, <<>> when no query string.
raw_path(Context)
Return the undecoded request path as-is, including the query string.
remove_resp_header(Header, Context)
Remove the response header from the list for response headers.
req(Context)
Fetch the cowboy request from the context.
req_body(Context)

Equivalent to req_body(128 * 1024, Context).

req_body(MaxLength, Context)
req_cookie(Context)
Fetch all cookies.
req_qs(Context)
Return the decoded query string, [] when no query string.
resp_body(Context)
Return the response body, this must be converted to a response body that Cowboy can handle.
resp_chosen_charset(Context)
Get the chosen charset.
resp_content_encoding(Context)
Get the content encoding.
resp_content_type(Context)
Fetch the content type of the response.
resp_redirect(Context)
Return the redirect flag, used during POST processing to check if a 303 should be returned.
resp_transfer_encoding(Context)
Get the transfer encoding.
response_code(Context)
Fetch the preliminary HTTP response code for the request. This can be changed.
scheme(Context)
Return the scheme used (https or http).
set_disp_path(Path, Context)
Set the dispatch path of the request.
set_env(Env, Context)
Update the cowboy middleware env in the context.
set_metadata(Key, Value, Context)
set_range_ok(IsRangeOk, Context)
Set the is_range_ok flag.
set_req(Req, Context)
Update the cowboy request in the context.
set_resp_body(RespBody, Context)
Set the response body, this must be converted to a response body that Cowboy can handle.
set_resp_chosen_charset(CharSet, Context)
Set the chosen charset.
set_resp_content_encoding(Enc, Context)
Set the content encoding.
set_resp_content_type(CT, Context)
Set the content type of the response
set_resp_cookie(Key, Value, Options, Context)
Add a cookie to the response cookies.
set_resp_header(Header, Value, Context)
Add a response header, replacing an existing header with the same name.
The header must be a lowercased binary. If the value is a list of binaries then they are joined with a comma as separator.
set_resp_headers(Headers, Context)
Set multiple response headers.
set_resp_redirect(Location, Context)
Set the redirect flag, used during POST processing to check if a 303 should be returned.
set_resp_transfer_encoding(Enc, Context)
Set the transfer encoding.
set_response_code(Code, Context)
Set the preliminary HTTP response code for the request. This can be changed.
site(Context)
Return the cowmachine site.
stream_req_body(ChunkSize, Context)
version(Context)
Return the http version as a tuple {major, minor}.

Link to this section Types

Link to this type

context/0

View Source 
-type context() :: context_map() | tuple().

The request context stores everything needed for the request handling.

Inside Zotonic all functions work with a site specific context, this context has optionally a request. That is why the context is wrapped around the cowboy request.

The cowmachine context must be the cowreq record, a tuple or a map. If it is a tuple then it is assumed to be a record then the cowreq is at position 2 and the cowenv at position 3.
Link to this type

context_map/0

View Source 
-type context_map() :: #{cowreq := cowboy_req:req(), cowenv := cowboy_middleware:env(), any() => any()}.
Link to this type

halt/0

View Source 
-type halt() :: {error, term()} | {halt, 200..599}.
Used to stop a request with a specific HTTP status code
Link to this type

media_type/0

View Source 
-type media_type() ::
    binary() |
    {binary(), binary(), [{binary(), binary()}]} |
    {binary(), binary()} |
    {binary(), [{binary(), binary()}]}.
Media types for accepted and provided content types
Link to this type

outputfun/0

View Source 
-type outputfun() :: fun((iodata(), IsFinal :: boolean(), context()) -> context()).
Link to this type

parts/0

View Source 
-type parts() ::
    all | {ranges(), Size :: non_neg_integer(), Boundary :: binary(), ContentType :: binary()}.
Link to this type

ranges/0

View Source 
-type ranges() :: [{Offset :: non_neg_integer(), Length :: non_neg_integer()}].
Link to this type

resp_body/0

View Source 
-type resp_body() ::
    iodata() |
    {device, Size :: non_neg_integer(), file:io_device()} |
    {device, file:io_device()} |
    {file, Size :: non_neg_integer(), file:filename_all()} |
    {file, file:filename_all()} |
    {stream, {streamdata(), streamfun()}} |
    {stream, Size :: non_neg_integer(), {streamdata(), streamfun()}} |
    {stream, streamfun()} |
    {stream, Size :: non_neg_integer(), streamfun()} |
    {writer, writerfun()} |
    undefined.
Response body, can be data, a file, device or streaming functions.
Link to this type

streamdata/0

View Source 
-type streamdata() ::
    iodata() | {file, non_neg_integer(), file:filename_all()} | {file, file:filename_all()}.
Link to this type

streamfun/0

View Source 
-type streamfun() ::
    fun((parts(), context()) -> {streamdata(), streamfun_next()}) |
    fun((context()) -> {streamdata(), streamfun_next()}) |
    fun(() -> {streamdata(), streamfun_next()}) |
    done.
Streaming function, repeatedly called to fetch the next chunk
Link to this type

streamfun_next/0

View Source 
-type streamfun_next() ::
    fun((context()) -> {streamdata(), streamfun_next()}) |
    fun(() -> {streamdata(), streamfun_next()}) |
    done.
Link to this type

writerfun/0

View Source 
-type writerfun() :: fun((outputfun(), context()) -> context()).
Writer function, calls output function till finished

Link to this section Functions

Link to this function

base_uri(Context)

View Source 
-spec base_uri(Context) -> Result when Context :: context(), Result :: binary().
Return the base uri of the request.
Link to this function

controller(Context)

View Source 
-spec controller(Context) -> Result when Context :: context(), Result :: module().
Return the current cowmachine controller.
Link to this function

controller_options(Context)

View Source 
-spec controller_options(Context) -> Result when Context :: context(), Result :: list().
Return the current cowmachine controller options.
Link to this function

disp_path(Context)

View Source 
-spec disp_path(Context) -> Result when Context :: context(), Result :: undefined | binary().
Return the dispatch path of the request.
Link to this function

encode_content(Content, Context)

View Source 
-spec encode_content(Content, Context) -> Result
                  when Content :: iodata(), Context :: context(), Result :: iodata().
Encode the content according to the selected content encoding.
Link to this function

env(Context)

View Source 
-spec env(Context) -> Result when Context :: context(), Result :: cowboy_middleware:env().
Fetch the cowboy middleware env from the context.
Link to this function

get_metadata(Key, Context)

View Source 
-spec get_metadata(Key, Context) -> Result
                when Key :: atom(), Context :: context(), Result :: undefined | term().
Link to this function

get_req_header(Header, Context)

View Source 
-spec get_req_header(Header, Context) -> Result
                  when Header :: binary(), Context :: context(), Result :: undefined | binary().
Fetch a request header, the header must be a lowercase binary.
Link to this function

get_req_headers(Context)

View Source 
-spec get_req_headers(Context) -> Result when Context :: context(), Result :: #{binary() => binary()}.
Fetch all request headers.
Link to this function

get_resp_cookies(Context)

View Source 
-spec get_resp_cookies(Context) -> Result when Context :: context(), Result :: [{binary(), binary()}].
Fetch all response cookies.
Link to this function

get_resp_header(Header, Context)

View Source 
-spec get_resp_header(Header, Context) -> Result
                   when Header :: binary(), Context :: context(), Result :: undefined | binary().
Fetch the response header, undefined if not set.
Link to this function

get_resp_headers(Context)

View Source 
-spec get_resp_headers(Context) -> Result when Context :: context(), Result :: map().
Fetch all response headers.
Link to this function

has_req_body(Context)

View Source 
-spec has_req_body(Context) -> Result when Context :: context(), Result :: boolean().
Check if the request has a body
Link to this function

has_resp_body(Context)

View Source 
-spec has_resp_body(Context) -> Result when Context :: context(), Result :: boolean().
Check if a response body has been set.
Link to this function

host(Context)

View Source 
-spec host(Context) -> Result when Context :: context(), Result :: binary().
Return the http host.
Link to this function

init_context(Req, Env, Options)

View Source 
-spec init_context(Req, Env, Options) -> Result
                when
                    Req :: cowboy_req:req(),
                    Env :: cowboy_middleware:env(),
                    Options :: undefined | map() | tuple(),
                    Result :: context().
Initialize the context with the Req and Env.
Link to this function

init_env(Req, Env)

View Source 
-spec init_env(Req, Env) -> Result
            when
                Req :: cowboy_req:req(),
                Env :: cowboy_middleware:env(),
                Result :: cowboy_middleware:env().
Set some intial metadata in the cowboy req.
Link to this function

is_proxy(Context)

View Source 
-spec is_proxy(Context) -> Result when Context :: context(), Result :: boolean().
Check if the request is forwarded by a proxy.
Link to this function

is_range_ok(Context)

View Source 
-spec is_range_ok(context()) -> boolean().
Fetch the is_range_ok flag.
Link to this function

is_ssl(Context)

View Source 
-spec is_ssl(Context) -> Result when Context :: context(), Result :: boolean().
Check if the connection is secure (SSL).
Link to this function

method(Context)

View Source 
-spec method(Context) -> Result when Context :: context(), Result :: binary().
Return the request Method.
Link to this function

path(Context)

View Source 
-spec path(Context) -> Result when Context :: context(), Result :: binary().
Return the undecoded request path as-is.
Link to this function

path_info(Context)

View Source 
-spec path_info(Context) -> Result when Context :: context(), Result :: cowboy_router:bindings().
Fetch all bindings from the dispatcher.
Link to this function

peer(Context)

View Source 
-spec peer(Context) -> Result when Context :: context(), Result :: binary().
Return the peer of this request, take x-forwarded-for into account if the peer is an ip4 LAN address.
Link to this function

peer_ip(Context)

View Source 
-spec peer_ip(Context) -> Result when Context :: context(), Result :: tuple().
Return the peer of this request, take x-forwarded-for into account if the peer is an ip4 LAN address.
Link to this function

port(Context)

View Source 
-spec port(Context) -> Result when Context :: context(), Result :: integer().
Return the http port.
Link to this function

qs(Context)

View Source 
-spec qs(Context) -> Result when Context :: context(), Result :: binary().
Return the undecoded query string, <<>> when no query string.
Link to this function

raw_path(Context)

View Source 
-spec raw_path(Context) -> Result when Context :: context(), Result :: binary().
Return the undecoded request path as-is, including the query string.
Link to this function

remove_resp_header(Header, Context)

View Source 
-spec remove_resp_header(Header, Context) -> Result
                      when Header :: binary(), Context :: context(), Result :: context().
Remove the response header from the list for response headers.
Link to this function

req(Context)

View Source 
-spec req(Context) -> Result when Context :: context(), Result :: cowboy_req:req().
Fetch the cowboy request from the context.
Link to this function

req_body(Context)

View Source 
-spec req_body(Context) -> Result when Context :: context(), Result :: {undefined | binary(), context()}.

Equivalent to req_body(128 * 1024, Context).

Fetch the request body as a single binary.
Per default we don't receive more than ~128K bytes.
Link to this function

req_body(MaxLength, Context)

View Source 
-spec req_body(MaxLength, Context) -> Result
            when
                MaxLength :: non_neg_integer(),
                Context :: context(),
                Result :: {undefined | binary(), context()}.
Link to this function

req_cookie(Context)

View Source 
-spec req_cookie(Context) -> Result when Context :: context(), Result :: list().
Fetch all cookies.
Link to this function

req_qs(Context)

View Source 
-spec req_qs(Context) -> Result when Context :: context(), Result :: [{binary(), binary()}].
Return the decoded query string, [] when no query string.
Link to this function

resp_body(Context)

View Source 
-spec resp_body(Context) -> Result when Context :: context(), Result :: resp_body().
Return the response body, this must be converted to a response body that Cowboy can handle.
Link to this function

resp_chosen_charset(Context)

View Source 
-spec resp_chosen_charset(Context) -> Result when Context :: context(), Result :: undefined | binary().
Get the chosen charset.
Link to this function

resp_content_encoding(Context)

View Source 
-spec resp_content_encoding(Context) -> Result when Context :: context(), Result :: binary().
Get the content encoding.
Link to this function

resp_content_type(Context)

View Source 
-spec resp_content_type(Context) -> Result when Context :: context(), Result :: cow_http_hd:media_type().
Fetch the content type of the response.
Link to this function

resp_redirect(Context)

View Source 
-spec resp_redirect(Context) -> Result when Context :: context(), Result :: boolean().
Return the redirect flag, used during POST processing to check if a 303 should be returned.
Link to this function

resp_transfer_encoding(Context)

View Source 
-spec resp_transfer_encoding(Context) -> Result
                          when Context :: context(), Result :: undefined | {binary(), function()}.
Get the transfer encoding.
Link to this function

response_code(Context)

View Source 
-spec response_code(Context) -> Result when Context :: context(), Result :: integer().
Fetch the preliminary HTTP response code for the request. This can be changed.
Link to this function

scheme(Context)

View Source 
-spec scheme(Context) -> Result when Context :: context(), Result :: http | https.
Return the scheme used (https or http).
Link to this function

set_disp_path(Path, Context)

View Source 
-spec set_disp_path(Path, Context) -> Result
                 when Path :: binary(), Context :: context(), Result :: context().
Set the dispatch path of the request.
Link to this function

set_env(Env, Context)

View Source 
-spec set_env(Env, Context) -> Result
           when Env :: cowboy_middleware:env(), Context :: context(), Result :: context().
Update the cowboy middleware env in the context.
Link to this function

set_metadata(Key, Value, Context)

View Source 
-spec set_metadata(Key, Value, Context) -> Result
                when Key :: atom(), Value :: term(), Context :: context(), Result :: context().
Link to this function

set_range_ok(IsRangeOk, Context)

View Source 
-spec set_range_ok(IsRangeOk, Context) -> Result
                when IsRangeOk :: boolean(), Context :: context(), Result :: context().
Set the is_range_ok flag.
Link to this function

set_req(Req, Context)

View Source 
-spec set_req(Req, Context) -> Result
           when Req :: cowboy_req:req(), Context :: context(), Result :: context().
Update the cowboy request in the context.
Link to this function

set_resp_body(RespBody, Context)

View Source 
-spec set_resp_body(RespBody, Context) -> Result
                 when RespBody :: resp_body(), Context :: context(), Result :: context().
Set the response body, this must be converted to a response body that Cowboy can handle.
Link to this function

set_resp_chosen_charset(CharSet, Context)

View Source 
-spec set_resp_chosen_charset(CharSet, Context) -> Result
                           when
                               CharSet :: undefined | binary(),
                               Context :: context(),
                               Result :: context().
Set the chosen charset.
Link to this function

set_resp_content_encoding(Enc, Context)

View Source 
-spec set_resp_content_encoding(Enc, Context) -> Result
                             when Enc :: binary(), Context :: context(), Result :: context().
Set the content encoding.
Link to this function

set_resp_content_type(CT, Context)

View Source 
-spec set_resp_content_type(cow_http_hd:media_type() | binary(), context()) -> context().
Set the content type of the response
Link to this function

set_resp_cookie(Key, Value, Options, Context)

View Source 
-spec set_resp_cookie(Key, Value, Options, Context) -> Result
                   when
                       Key :: binary(),
                       Value :: binary(),
                       Options :: list(),
                       Context :: context(),
                       Result :: context().
Add a cookie to the response cookies.
Link to this function

set_resp_header(Header, Value, Context)

View Source 
-spec set_resp_header(Header, Value, Context) -> Result
                   when
                       Header :: binary(),
                       Value :: binary() | [binary()] | string(),
                       Context :: context(),
                       Result :: context().
Add a response header, replacing an existing header with the same name.
The header must be a lowercased binary. If the value is a list of binaries then they are joined with a comma as separator.
Link to this function

set_resp_headers(Headers, Context)

View Source 
-spec set_resp_headers(Headers, Context) -> Result
                    when
                        Headers :: [{binary(), binary()}],
                        Context :: context(),
                        Result :: context().
Set multiple response headers.
Link to this function

set_resp_redirect(Location, Context)

View Source 
-spec set_resp_redirect(Location, Context) -> Result
                     when
                         Location :: boolean() | binary(),
                         Context :: context(),
                         Result :: context().
Set the redirect flag, used during POST processing to check if a 303 should be returned.
Link to this function

set_resp_transfer_encoding(Enc, Context)

View Source 
-spec set_resp_transfer_encoding(Enc, Context) -> Result
                              when
                                  Enc :: {binary(), function()},
                                  Context :: context(),
                                  Result :: context().
Set the transfer encoding.
Link to this function

set_response_code(Code, Context)

View Source 
-spec set_response_code(Code, Context) -> Result
                     when Code :: integer(), Context :: context(), Result :: context().
Set the preliminary HTTP response code for the request. This can be changed.
Link to this function

site(Context)

View Source 
-spec site(Context) -> Site when Context :: context(), Site :: atom().
Return the cowmachine site.
Link to this function

stream_req_body(ChunkSize, Context)

View Source 
-spec stream_req_body(ChunkSize, Context) -> Result
                   when
                       ChunkSize :: non_neg_integer(),
                       Context :: context(),
                       Result :: {ok | more, binary(), context()}.
Link to this function

version(Context)

View Source 
-spec version(Context) -> Result
           when
               Context :: context(),
               Result :: {Major, Minor},
               Major :: integer(),
               Minor :: integer().
Return the http version as a tuple {major, minor}.