[![ version][hexpm version]][hexpm]
[![ Downloads][hexpm downloads]][hexpm]
[![ Documentation][hexdocs documentation]][hexdocs]
[![Erlang Versions][erlang version badge]][gh]

# Cowmachine

Webmachine for Zotonic and Cowboy

This is an adaptation of for the Cowboy web server.

Cowmachine is a request handler for Cowboy.

Main differences with Basho’s Webmachine are:

 * Use cowboy instead of mochiweb for the http server
 * Separate dispatching
 * Simplified callbacks
 * Single `process/4` callback for all http methods
 * Caching of some callbacks (like `modified`)
 * More streaming options for returned data
 * Better support for range requests

## Installation

Cowmachine is at Hex, in your `rebar.config` file use:

{deps, [

You can also use the direct Git url and use the development version:

{deps, [
    {cowmachine, {git, "", {branch, "master"}}}

## Calling Cowmachine

Cowmachine can be called from your Cowboy middleware:

-spec execute(Req, Env) -> {ok, Req, Env} | {stop, Req}
    when Req::cowboy_req:req(), Env::cowboy_middleware:env().
execute(Req, Env) ->
    % Replace below with your own controller module and optionally wrap
    % the request in your own request-context record or map.
    EnvController = Env#{
        cowmachine_controller => mycontroller
    RequestContext = cowmachine_req:init_context(Req, EnvController, #{}),
    % Set options for the cowmachine
    Options = #{
        on_request =>
            fun(Ctx) ->
                % Perform anything after initialization of your request
                % Examples are checking special cookies, changing headers, etc.
        on_welformed =>
            fun(Ctx) ->
                % Perform anything after well-formedness check of your request
                % Examples are parsing the query args, or authentication
        on_handled =>
            fun(Ctx) ->
                % Perform anything after processing, before sending the result.
    % Handle the request, returns updated Req and Env for next Cowboy middleware
    cowmachine:request(RequestContext, Options).

Or just use the default Cowmachine middleware:

        middlewares => [
            % ... add your dispatcher middlware
        request_timeout => 60000,
        env => #{
            % If no dispatcher, default to `mycontroller` as the cowmachine
            % controller.
            cowmachine_controller => mycontroller

## Dispatching

You can use the [Zotonic Dispatch Compiler]( to match your controller paths against the request.

## Controller

The controller provides the callbacks to handle the request.

The controller is an Erlang module implementing callback functions, only functions that return some non-default value need to be implemented.

For the controller callbacks and more documentation, check the [wiki pages](

## Documentation generation

### Edoc

#### Generate public API
`rebar3 edoc`

#### Generate private API
`rebar3 as edoc_private edoc`

### ExDoc

`rebar3 ex_doc --logo doc/img/logo.png --output edoc -f html`

<!-- Badges -->
[hexpm version]: "Hex version"
[hexpm downloads]:
[hexdocs documentation]:
[gh badge]:
[erlang version badge]:
[license]: "Apache 2.0"