Web Development with Webmachine

If for any reason you are interested in developing a web application on Erlang, then you will naturally have a question as to which of the available technologies to use for this: take one of the existing web servers, such as YAWS, Mochiweb, Misultin (I’ll call them so , although some of them call themselves a framework for building web servers) or use something ready-made, for example, Zotonic CMS or Nitrogen.
Asking this question, you will surely find this post on Stackoverflow, in which all the pros and cons of various approaches are discussed in some detail.

In this article, the author tried to reveal the topic of using Webmachine to create web resources.

So what is a webmachine? According to the developers themselves, there is no definite answer: whether it is a web framework, or a toolkit for creating REST-like web resources. The author is of the opinion that this is a way of describing the state of a web service using the provided toolkit.
What is interesting Webmachine?

dispatch.conf

An important feature of the Webmachine is how the request reaches the destination. There is a dispatch.conf file, which defines the rules for matching the request address to its processing module. This module in terms of the Webmachine is called a resource.
')
An example of spherical dispatch.conf :

%%-*- mode: erlang -*-
{["page1", "subpage11"], page11_resource, []}.
{["page1", "subpage12"], page12_resource, [{is_protected, true}]}.
{["page2", '*'], page2_resource, []}.
{['*'], default_resource, []}.

From the example it is clear that each line of this file consists of three parts. The first part is the rule by which the current request is processed. As soon as the request satisfies one of these rules, it is sent to the resource described in the second part of the current line. The last part is the input parameters for the init function of this resource.

For example, if the Webmachine is running on localhost:8000 , then the request localhost:8000/page1/subpage12 falls under the second rule, and the request localhost:8000/unknown_url/subpage42 processed last.

Flow diagram

Another important difference of Webmachine from most other technologies is the division of the processing of a request within a resource into levels according to the following diagram :



For each node of this diagram, there is a handler function that decides whether to go further or stop. For most nodes, reasonable default handlers are provided, so the task comes down to identifying the nodes that are essential to your goal and implementing their logic.

Example of a spherical resource:

-module(page12_resource).
-export([init/1, is_authorized/2, content_types_provided/2, allowed_methods/2, to_html/2, to_text/2]).

-include_lib("webmachine/include/webmachine.hrl").

init(InitArgsFromDispatchConf) -> {ok, InitArgsFromDispatchConf}.

content_types_provided(Request, Context) ->
{[{"text/html", to_html},{"text/plain",to_text}], Request, Context}.

allowed_methods(Request, Context) ->
{['GET', 'POST'], Request, Context}.

is_authorized(Request, Context) ->
case wrq:get_req_header("Authorization", ReqData) of
"Basic "++Base64 ->
Str = base64:mime_decode_to_string(Base64),
case string:tokens(Str, ":") of
["authdemo", "demo1"] ->
{true, Request, Context};
_ ->
{"Basic realm=webmachine", Request, Context}
end;
_ ->
case proplists:get_value(is_protected, Context, false) of
false -> {true, Request, Context};
_ -> {"Basic realm=webmachine", Request, Context}
end
end.

to_html(Request, Context) -> {"Hello, html world", Request, Context}.

to_text(Request, Context) -> {"Hello, text world", Request, Context}.

This example shows that our resource can output data in both text / plain and text / html. If you set “Accept: text / xml” in the request header, then when accessing this resource, you will receive “HTTP / 1.1 406 Not Acceptable” from the server in response. Similarly with the request method, if you try to do a “PUT” or “DELETE”, you will receive “HTTP / 1.1 405 Method Not Allowed” in response. A simple example of basic authorization is also given.

Built-in web debugger

Quite useful is the debugging mechanism of the application. It is a web resource running on the same Webmachine, when accessed, it displays on the diagram the entire path of your request and all intermediate states. An example of the debugger can be found here .

Templates

Fans of patterns and templating can take advantage of the very functional port of Django Templates Language - ErlyDtl .

Where to get?

Getting started using the webmachine is pretty simple:

git clone github.com/basho/webmachine.git
cd webmachine && ./scripts/new_webmachine.sh mydemo ~/webmachine_applications
cd ~/webmachine_applications/mydemo && make && ./start.sh

More documentation on the Wiki or on Github .

Included with the source code comes a utility to build rebar and start.sh startup script.
The priv folder contains dispatch.conf , and the src folder contains the source codes of the resources.

Conclusion

Webmachine is a flexible and powerful platform for building web applications on Erlang. It is fairly simple, but not primitive, universal, but not comprehensive. This is an interesting technology that deserves the attention of REST-like service developers and web developers.

PS If something is missing in the functionality of the Webmachine, then you can go down to the level below and pick the whale on which it stands (Mochiweb).

Drink tea, write Erlang.