View Source cowmachine_req (cowmachine v1.10.3)

Request functions for cowmachine.

Link to this section Summary

Types

The request context stores everything needed for the request handling.

Used to stop a request with a specific HTTP status code
Media types for accepted and provided content types
Response body, can be data, a file, device or streaming functions.
Streaming function, repeatedly called to fetch the next chunk
Writer function, calls output function till finished

Functions

Return the base uri of the request.
Return the current cowmachine controller.
Return the current cowmachine controller options.
Return the dispatch path of the request.
Encode the content according to the selected content encoding.
Fetch the cowboy middleware env from the context.
Fetch the value of a cookie.
Fetch a request header, the header must be a lowercase binary.
Fetch all request headers.
Fetch all response cookies.
Fetch the response header, undefined if not set.
Fetch all response headers.
Check if the request has a body
Check if a response body has been set.
Return the http host.
Initialize the context with the Req and Env.
Set some intial metadata in the cowboy req.
Check if the request is forwarded by a proxy.
Fetch the is_range_ok flag.
Check if the connection is secure (SSL).
Return the request Method.
Return the undecoded request path as-is.
Fetch all bindings from the dispatcher.
Return the peer of this request, take x-forwarded-for into account if the peer is an ip4 LAN address.
Return the peer of this request, take x-forwarded-for into account if the peer is an ip4 LAN address.
Return the http port.
Return the undecoded query string, <<>> when no query string.
Return the undecoded request path as-is, including the query string.
Remove the response header from the list for response headers.
Fetch the cowboy request from the context.
Fetch all cookies.
Return the decoded query string, [] when no query string.
Return the response body, this must be converted to a response body that Cowboy can handle.
Get the chosen charset.
Get the content encoding.
Fetch the content type of the response.
Return the redirect flag, used during POST processing to check if a 303 should be returned.
Get the transfer encoding.
Fetch the preliminary HTTP response code for the request. This can be changed.
Return the scheme used (https or http).
Set the dispatch path of the request.
Update the cowboy middleware env in the context.
Set the is_range_ok flag.
Update the cowboy request in the context.
Set the response body, this must be converted to a response body that Cowboy can handle.
Set the content encoding.
Set the content type of the response
Add a cookie to the response cookies.
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 multiple response headers.
Set the redirect flag, used during POST processing to check if a 303 should be returned.
Set the transfer encoding.
Set the preliminary HTTP response code for the request. This can be changed.
Return the cowmachine site.
Return the http version as a tuple {major, minor}.

Link to this section Types

-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.
-type context_map() :: #{cowreq := cowboy_req:req(), cowenv := cowboy_middleware:env(), any() => any()}.
-type halt() :: {error, term()} | {halt, 200..599}.
Used to stop a request with a specific HTTP status code
-type media_type() ::
    binary() |
    {binary(), binary(), [{binary(), binary()}]} |
    {binary(), binary()} |
    {binary(), [{binary(), binary()}]}.
Media types for accepted and provided content types
-type outputfun() :: fun((iodata(), IsFinal :: boolean(), context()) -> context()).
-type parts() ::
    all | {ranges(), Size :: non_neg_integer(), Boundary :: binary(), ContentType :: binary()}.
-type ranges() :: [{Offset :: non_neg_integer(), Length :: non_neg_integer()}].
-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.
-type streamdata() ::
    iodata() | {file, non_neg_integer(), file:filename_all()} | {file, file:filename_all()}.
-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
-type streamfun_next() ::
    fun((context()) -> {streamdata(), streamfun_next()}) |
    fun(() -> {streamdata(), streamfun_next()}) |
    done.
-type writerfun() :: fun((outputfun(), context()) -> context()).
Writer function, calls output function till finished

Link to this section Functions

-spec base_uri(Context) -> Result when Context :: context(), Result :: binary().
Return the base uri of the request.
-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.
-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.
-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.
-spec has_req_body(Context) -> Result when Context :: context(), Result :: boolean().
Check if the request has a body
-spec has_resp_body(Context) -> Result when Context :: context(), Result :: boolean().
Check if a response body has been set.
-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.
-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.
-spec is_proxy(Context) -> Result when Context :: context(), Result :: boolean().
Check if the request is forwarded by a proxy.
-spec is_range_ok(context()) -> boolean().
Fetch the is_range_ok flag.
-spec is_ssl(Context) -> Result when Context :: context(), Result :: boolean().
Check if the connection is secure (SSL).
-spec method(Context) -> Result when Context :: context(), Result :: binary().
Return the request Method.
-spec path(Context) -> Result when Context :: context(), Result :: binary().
Return the undecoded request path as-is.
-spec path_info(Context) -> Result when Context :: context(), Result :: cowboy_router:bindings().
Fetch all bindings from the dispatcher.
-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.
-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.
-spec port(Context) -> Result when Context :: context(), Result :: integer().
Return the http port.
-spec qs(Context) -> Result when Context :: context(), Result :: binary().
Return the undecoded query string, <<>> when no query string.
-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.
-spec req(Context) -> Result when Context :: context(), Result :: cowboy_req:req().
Fetch the cowboy request from the context.
-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()}.
-spec req_cookie(Context) -> Result when Context :: context(), Result :: list().
Fetch all cookies.
-spec req_qs(Context) -> Result when Context :: context(), Result :: [{binary(), binary()}].
Return the decoded query string, [] when no query string.
-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.
-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.
-spec response_code(Context) -> Result when Context :: context(), Result :: integer().
Fetch the preliminary HTTP response code for the request. This can be changed.
-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.
-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.
-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.
-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()}.
-spec version(Context) -> Result
           when
               Context :: context(),
               Result :: {Major, Minor},
               Major :: integer(),
               Minor :: integer().
Return the http version as a tuple {major, minor}.