Axiom is a micro-framework for building web applications in Erlang. It is inspired by Sinatra and built on top of Cowboy.
Axiom is built to make creating web applications fast and easy. A minimal application would look like this:
-module(my_app).
-export([start/0, handle/3]).
start() ->
axiom:start(?MODULE).
handle(<<"GET">>, [<<"hi">>], _Request) ->
<<"Hello world!">>.
This handles requests for GET /hi and returns "Hello world!".
The third argument given to the handler is of type cowboy_req:req(). Use the
cowboy_req module, if you need anything out of the request.
The return value can be a binary string or iolist. So, this also works:
handle(<<"GET">>, [<<"hello">>, Who], _Request) ->
[<<"Hello ">>, Who, <<"!">>].If you want to specify a response status code and/or headers, use a tuple with either the status code and body or status code, headers and body, in these respective orders.
Examples:
{418, <<"<h1>I'm a teapot!</h1>">>}or
{418, [{<<"X-Foo">>, <<"bar">>}], <<"<h1>I'm a teapot!</h1>">>}As a third option a cowboy_req:req() can be returned. In this case, to set the
response headers and body, use the cowboy_req:set_resp_header/3 and
cowboy_req:set_resp_body/2 functions. To set the status code, use
axiom:set_resp_status/2. These functions return a new cowboy_req:req() to be
used further and to be returned from YourHandler:handle/3.
The full spec of YourHandler:handle/3 is expected to look like this:
handle(Method, Path, Req) -> Body | Req | {Status, Body} | {Status, Headers, Body}.
Types:
Method = binary(),
Path = [PathSegment]
PathSegment = binary()
Req = cowboy_req:req()
Body = iodata()
Status = non_neg_integer()
Headers = [Header]
Header = {binary(), binary()}To get the request parameters out of the request, you can use the two
handy functions axiom:params(Req) and axiom:param(Name, Req).
The first returns a proplist of all parameters, the second one returns
the named parameter's value. Keys and values are binary strings.
axiom:start/1 has a bigger brother called axiom:start/2, taking a
proplist as the second argument. Possible properties and their defaults
are as follows:
[
{nb_acceptors: 100}, % acceptor pool size
{host, '_'}, % host IP
{port, 7654}, % host port
{public, "public"} % custom path for static files
]Static files are served via the cowboy_static handler. By default, every file
in the ./public directory and all its subdirectories will be made accessible via
URL path the same as file's relative path. E.g. the file ./public/about.html
can be accessed via GET /about.html. Note: Currently, if the contents of
the ./public subtree change, Axiom needs to be restarted to reflect the change.
You can specify a custom directory via the public option.
When you use this feature, it is advisable to start Erlang with the
+A n flag. This will start n async threads.
Rule of thumb is to use your machine's number of CPU cores.
You can redirect requests with redirect/2:
handle(<<"GET">>, [<<"foo">>], Req) ->
Req1 = axiom:redirect("/bar", Req),
Req;
handle(<<"GET">>, [<<"bar">>], Request) ->
<<"<h1>Welcome back!</h1>">>.Axiom comes with Django template
support via erlydtl. To make
use of it in your application, create a directory named templates and
in it, create a template, e.g. my_template.dtl:
<h1>Hello {{who}}</h1>
In your handler, specify the template to be rendered:
handle(<<"GET">>, [<<"hello">>], _Request) ->
axiom:dtl(my_template, [{who, "you"}]).For convenience, the second argument, a proplist of parameters, can have atoms, lists or binaries as keys. That way request parameters can be put in there, without you having to convert them first.
The templates are compiled into modules when rebar compile is
called.
To see what else erlydtl can do for you, take a look at its project page.
Axiom comes with a basic session handler and ets based session store. To use it, add this tuple to the configuration proplist:
{sessions, []}In your handler you can then use
axiom_session:set(Key, Value, Request) and
axiom_session:get(Key, Request).
To set attributes for the cookie, storing the session ID, add some
parameters to the session configuration in a tuple with the key
cookies:
{sessions, [{cookies, [param()]}]}Possible parameters are:
param() = {max_age, integer()} |
{local_time, calendar:datetime()} |
{domain, binary()} |
{path, binary()} |
{secure, true | false} |
{http_only, true | false}The default session store is the axiom_session_ets module. You can use
your own by adding a store tuple to the sessions tuple:
{sessions, [{store, my_session_store, []}]}For implementation details take a look into the axiom_session_ets
module.
The functions before_filter/1 and after_filter/1 can be implemented
to deal with the cowboy_req:req() before and after YourHandler:handle/3.
When implemented, these are called no matter which handle function matches the
request.
In your handler module:
before_filter(Req) ->
% do stuff
Req.
after_filter(Req) ->
% do more stuff
Req.To overwrite Axiom's response to 404 errors, just create a catch-all handler:
handle(_Method, _Path, _Req) ->
{404, <<"nope.">>}.Note that you have to take care of the status code yourself, as otherwise the default of 200 is sent back to the client.
To handle these yourself, you can implement a function named error/1.
The argument is the cowboy_req:req() object, otherwise it works like your
Handler:handle/3 function.
To send a chunked reply, call axiom:chunk/2 for each chunk:
chunk(Data::iodata(), Req::cowboy_req:req()) -> {ok, Req1::cowboy_req:req()}.The returned cowboy_req:req() object has to be given as an argument to
subsequent calls to chunk and as the return value of your
Handler:handle/3 function.
To stream data with a Content-Type other than text/html, use
chunk/3, which has an additional parameter, to be set to the type you
want:
chunk(Data::iodata(), Req::cowboy_req:req(), Type::binary()) -> {ok, Req1::cowboy_req:req()}.handle(<<"GET">>, [<<"stream">>], Req) ->
{ok, Req1} = axiom:chunk(<<"Hello">>, Req, <<"text/plain">>),
{ok, Req2} = axiom:chunk(<<" world">>, Req1),
{ok, Req3} = axiom:chunk(<<"!">>, Req2),
Req3.To use it in your OTP application, add this to your rebar.config:
{lib_dirs, ["deps"]}.
{deps, [
{'axiom', "0.1.0", {git, "git://github.com/tsujigiri/axiom.git", {tag, "v0.1.0"}}}
]}.then, as usual:
rebar get-deps
rebar compile
Please take a look at the LICENSE file! (tl;dr: it's the MIT License)
To express your appreciation you are welcome to
