DEV Community: Daniel Widgren

Adding auth to your application

Daniel Widgren — Thu, 22 Feb 2024 19:48:33 +0000

Adding auth

In earlier sections, we have talked about routings, plugins and views and touched controllers.

Now we will add security so we can try our login view.

Security is managed within our routing file, that will point to a security module and function. We have our routing file my_first_nova_router.erl looking like this:

-module(my_first_nova_router).
-behaviour(nova_router).

-export([
         routes/1
        ]).

%% The Environment-variable is defined in your sys.config in {nova, [{environment, Value}]}
routes(_Environment) ->
  [#{prefix => "",
      security => false,
      routes => [
                 {"/", fun my_first_nova_main_controller:index/1 , #{methods => [get]}},
                 {"/heartbeat", fun(_) -> {status, 200} end, #{methods => [get]}},
                 {"/login", fun my_first_nova_main_controller:login/1, #{methods => [get]}}
                ]
      }].

We will now re-arragne some of the routing so we can add the security, ususally we store things as auth tokens and use that to do next api call. But this is just an simple example so I will just add auth to our path and let our view make a post to it. We will show the Username in our homepage.

We will start with adding a new Route map into the list, and move the endpoint / this one will use a security module that we will create that will be called my_first_nova_auth.erl this module will have a function called username_password. The new route map will look like this:

    #{prefix => "",
      security => fun my_first_nova_auth:username_password/1,
      routes => [{"/", fun my_first_nova_main_controller:index/1, #{methods => [post]}}]
     }

Here we have added the security {my_first_nova_auth, username_password} so this will be called before the request hits the controller.

Lets create our security module, in src directory you can create my_first_nova_auth.erl, when we talked about plugins we configured our plugin to hand urlencoded body, this is what our form will give us.

-module(my_first_nova_auth).

-export([username_password/1]).

username_password(#{params := Params}) ->
    case Params of
        #{<<"username">> := Username,
          <<"password">> := <<"password">>} -> {true, #{authed => true,
                                                         username => Username}};
        _ -> false
    end.

What we will also do just to be sure that only authed user will see our page we will add a flag that we will set if someone passed the auth. Here we also change the message back to the view and add the Username that we get from our auth module. If you want only some username to be authed we could add a list of username that we could see if they are a member in.

index(#{auth_data := #{authed := true,
                       username := Username}}) ->
    {ok, [{message, <<"Hello ", Username/binary>>}]};
index(_Req) ->
    {status, 401}.

This will see if we have #{authed => true} in our request, this is set from the return of the security module that we will cre

-module(my_first_nova_router).
-behaviour(nova_router).

-export([
         routes/1
        ]).

%% The Environment-variable is defined in your sys.config in {nova, [{environment, Value}]}
routes(_Environment) ->
  [#{prefix => "",
      security => false,
      routes => [
                 {"/login", fun my_first_nova_main_controller:login/1, #{methods => [get]}},
                 {"/heartbeat", fun(_) -> {status, 200} end, #{methods => [get]}}
                ]
      },
    #{prefix => "",
      security => fun my_first_nova_auth:username_password/1,
      routes => [{"/", fun my_first_nova_main_controller:index/1, #{methods => [post]}}]
     }
   ].

Now we can try this out, start the node rebar3 nova serve then we can go to localhost:8080/login this will show us our view with username and password form. Try any username and the password is password. If everything works you will see the start page with starts and Nova loggo saying Hello USERNAME.

Adding a new view and present it

Daniel Widgren — Thu, 22 Feb 2024 19:24:40 +0000

Views

Nova is using ErlyDTL to tempalte the views, that is an Erlang version of Django templating.

You can read more about Django templating here.

New view

We want to create a simple view that have to input fields that will send in username and password to our service. In our directory src/views we will create a new file called login.dtl. In that file we will add this html code.

<html>
<body>
  <div>
    <form action="/" method="post" id="nameform">
      <label for="username">userame:</label>
      <input type="text" id="username" name="username"><br>
      <label for="password">Password:</label>
      <input type="password" id="password" name="password"><br>
      <input type="submit" value="submit">
    </form>
  </div>
</body>
</html>

As you can see in this html we will send a post to the endpoint /login.

Controller

We will now modify our controller so we can view this html.

In our application we have a controller that is in src/controllers the file is called my_first_nova_contrller.erl.

It looks like this:

-module(my_first_nova_main_controller).
-export([
         index/1
        ]).

index(_Req) ->
    {ok, [{message, "Hello world!"}]}.

What this does is send "Hello world!" to the view that we did see when we went to localhost:8080. Now we want to add the function that we added in the routing section.

The function we want to add is login/1.

-module(my_first_nova_main_controller).
-export([
         index/1,
         login/1
        ]).

index(_Req) ->
    {ok, [{message, "Hello world!"}]}.

login(_Req) ->
    {ok, [], #{view => login}}.

What this return tuple will tell Nova is that we want a view and it is named login, Nova will check after the view and show it if we go to localhost:8080/login. And because we added the route before in the routing file we will now connect the view.

Plugins and the pipeline

Daniel Widgren — Sat, 13 Mar 2021 08:24:05 +0000

Plugins

Plugins in Nova are modules that have a behaviour, these behaviours will be a part of the pipeline flow of a request.

-module(nova_correlation_plugin).

-behaviour(nova_plugin).

-export([pre_request/2,
         post_request/2,
         plugin_info/0]).

-include_lib("kernel/include/logger.hrl").

%%--------------------------------------------------------------------
%% @doc
%% Pre-request callback to either pick up correlation ID from request headers
%% or generate a new uuid correlation ID.
%% @end
%%--------------------------------------------------------------------

pre_request(Req0, Opts) ->
    CorrId = get_correlation_id(Req0, Opts),
    %% Update the logger's metadata with correlation-id
    ok = update_logger_metadata(CorrId, Opts),
    Req1 = cowboy_req:set_resp_header(<<"X-Correlation-ID">>, CorrId, Req0),
    Req = Req1#{correlation_id => CorrId},
    {ok, Req}.

post_request(Req, _) ->
    {ok, Req}.

plugin_info() ->
   {
     <<"nova_correlation_plugin">>,
     <<"0.2.0">>,
     <<"Nova team <info@novaframework.org">>,
     <<"Add X-Correlation-ID headers to response">>,
     []
    }.

get_correlation_id(Req, #{ request_correlation_header := CorrelationHeader }) ->
    case cowboy_req:header(CorrelationHeader, Req) of
        undefined ->
            uuid();
        CorrId ->
            CorrId
    end;

get_correlation_id(_Req, _Opts) ->
    uuid().

uuid() ->
    uuid:uuid_to_string(uuid:get_v4()).

update_logger_metadata(CorrId, Opts) ->
    LoggerKey = maps:get(logger_metadata_key, Opts, <<"correlation-id">>),
    logger:update_process_metadata(#{LoggerKey => CorrId}).

This is an example plugin that will add a correlation ID to all your requests.

Pipeline

We can look at the flow of a request as a pipeline that will go into different plugins before and after it has done the controller code.

Plugins can be used for HTTP requests. The example above shows two functions, such as pre_request (That will happen before the controller) and post_request (That will happen after the controller).

Prioritization & Configuration

We want to say in what order we want plugins to be run. We do this in sys.config where we also can set extra options for the plugins.

{nova, [
         {use_stacktrace, true},
         {environment, dev},
         {cowboy_configuration, #{
                                  port => 8080
                                 }},
         {dev_mode, true},
         {bootstrap_application, my_first_nova}, %% Bootstraps the application
         %% Plugins is written on form {RequestType, Module, Options, Priority}
         %% Priority is that the lowest number is executed first
         {plugins, [
                    {pre_request, nova_request_plugin, #{decode_json_body => true}}
                   ]}
        ]}
  %% Please change your app.src-file instead if you intend to add app-specific configurations

In this scenario:
nova_request_plugin is a plugin that is included with Nova, it can handle some decoding of incomming bodies.

To read more about what plugins are included in Nova you can read it here.

What we want to do in our application is that we are later going to create a view that will send in an urlencoded body from a form submit. An easy login page.

If we want Nova to decode this urlencoded body we will need to change our plugin setting to:

    {plugins, [
            {pre_request, nova_request_plugin, #{read_urlencoded_body => true}}
            ]}

How does routing work?

Daniel Widgren — Fri, 12 Mar 2021 18:20:39 +0000

Routing

Here I will write about routing in Nova and how it works.

When we generate a new Nova app we will have a routing file within our src directory.

The file is named in our example my_first_nova_router.erl in that file we have a function that has a list of Erlang maps that will specify and configure what rules are for an endpoint.

-module(my_first_nova_router).
-behaviour(nova_router).

-export([
         routes/1
        ]).

%% The Environment-variable is defined in your sys.config in {nova, [{environment, Value}]}
routes(_Environment) ->
    [#{prefix => "",
      security => false,
      routes => [
                 {"/", fun my_first_nova_main_controller:index/1 , #{methods => [get]}},
                 {"/heartbeat", fun(_) -> {status, 200} end, #{methods => [get]}}
                ]
      }].

What does this routing configuration indicate?

If we run this we will see the routing tree in your shell:

$ rebar3 nova routes
Host: '_'
     ├─  /assets
        └─  _ /[...] (my_first_nova, cowboy_static:init/1)
     └─  GET / (my_first_nova, my_first_nova_main_controller:index/1)

_Environement is a variable that is set in the config file, in dev_sys.config.src we can find {environment, dev} and for prod_sys.config.src we have {environment, prod}. In this file that we got from the start we don't care if the environment is dev or prod we will start the routes here for all environments. It could be so when we develop that we want to have some extra routes for dev environment that we don't want to have in production. Then we can add a new function for dev and add the routes.

Example:

-module(my_first_nova_router).
-behaviour(nova_router).

-export([
         routes/1
        ]).

%% The Environment-variable is defined in your sys.config in {nova, [{environment, Value}]}
routes(prod) ->
  prod();
routes(dev) ->
  prod() ++ dev().

prod() ->
  [#{prefix => "",
      security => false,
      routes => [
                 {"/", fun my_first_nova_main_controller:index/1, #{methods => [get]}},       
                 {"/heartbeat", fun(_) -> {status, 200} end, #{methods => [get]}}
                ]
      }].

dev() ->
  [#{prefix => "",
  security => false,
  routes => [
             {"/dev-tools", fun my_first_nova_dev_controller:index/1, #{methods => [get]}}
            ]
  }].

If you run rebar3 nova routes you will see that you get same result before we added the dev routes. This is because we only show what is in production and not in your development routes.

Back to the structure of the routing:

#{prefix => "",
  security => false,
  routes => [
             {"/", fun my_first_nova_main_controller:index/1 , #{methods => [get]}},
             {"/heartbeat", fun(_) -> {status, 200} end, #{methods => [get]}}
            ]
  }

prefix is if you want to group your routes, example if you are going to make a lot of routes for users v1/user, v1/user/USERKEY, v1/user/USERKEY/... then you can use a prefix with prefix => "/v1/user" and every route in routes field will have it as a prefix.
security here is if we want to have any security for the routes specified in this map. security takes a Erlang function, fun Module:Function/1.
routes this is a list that takes an Erlang tuple {PATH, fun Module:Function/1, #{}}. Path is the endpoint, the function with Moduleand Function will tell you what controller is used for this endpoint.

What we want to do is to add a new route to our application:

-module(my_first_nova_router).
-behaviour(nova_router).

-export([
         routes/1
        ]).

%% The Environment-variable is defined in your sys.config in {nova, [{environment, Value}]}
routes(_Environment) ->
  [#{prefix => "",
      security => false,
      routes => [
                 {"/", fun my_first_nova_main_controller:index/1 , #{methods => [get]}},
                 {"/heartbeat", fun(_) -> {status, 200} end, #{methods => [get]}},
                 {"/login", fun my_first_nova_main_controller:login/1, #{methods => [get]}}
                ]
      }].

In the example above we have added a new route for login.

Pattern matching

Daniel Widgren — Thu, 22 Oct 2020 12:06:05 +0000

In last section we did some recursive functions. Now we will try to do some pattern matching and later combine it with recursive functions.

When it comes to Erlang we execute from right to left that makes it easier to understand the error message.

2> Variable = 1.
1
3> Variable = 1.
1
4> 1 = Variable.
1
5> a = Variable.
** exception error: no match of right hand side value 1

This is a Erlang shell that we bind Variable to 1 and then pattern match.

At 3>, we try to pattern match 1 to Variable, if Variable haven't been set before it will be 1. But now it is set at 2>. At 4>, we try to match Variable to 1, and if it is ok the value is returned. At 5> we have a mismatch, this is where we match things from right to left. So on the right hand side we try to match 1 to a. That fails because of a no match.

One other example we can do is fibonacci. Fibonacci works that it do addition on the last number and the number before. 1, 1, 2, 3, 5, 8, 13.

We implement this in Erlang using recursion and pattern matching.

-module(fibonacci).

-export([fib/1]).

fib(0) ->
    0;
fib(1) ->
    1;
fib(N) ->
    fib(N-1) + fib(N-2).

What does our code do?

We have two base case here, if N is 0 and if N is 1. In the last function clause we call fib function with N-1 and N-2.

maps, records, tuples

Say that we want to do different things depending on a value in a map.

We get a list with maps that looks something like:

[#{type => sms, text => <<"hi">>}, #{type => <<"email">>, text => <<"hi">>}]

We want to sum the amount of each type in our list.

-module(pattern).

-export([sum_by_type/1,
         generate_list/0]).

sum_by_type(List) ->
    sum_by_type_aux(List, []).

sum_by_type_aux([], Acc) ->
    Acc;
sum_by_type_aux([#{type := Type} | Tail], Acc) ->
    case get_value(Acc, Type) of
        undefined ->
            sum_by_type_aux(Tail, [{Type, 1} | Acc]);
        Value ->
            NewAcc = remove_value(Acc, Type),
            sum_by_type_aux(Tail, [{Type, Value + 1} | NewAcc])
    end.

get_value([], _) ->
    undefined;
get_value([{Type, Value}|_], Type) ->
    Value;
get_value([_ | Tail], Type) ->
    get_value(Tail, Type).

remove_value(List, Type) ->
    remove_value_aux(List, Type, []).

remove_value_aux([], _, Acc) ->
    Acc;
remove_value_aux([{Type, _} | Tail], Type, Acc) ->
    remove_value_aux(Tail, Type, Acc);
remove_value_aux([Head | Tail], Type, Acc) ->
    remove_value_aux(Tail, Type, [Head | Acc]).

generate_list() ->
    [#{type => sms, text => <<"hi">>},
     #{type => email, text => <<"hi">>},
     #{type => sms, text => <<"hi">>},
     #{type => email, text => <<"hi">>},
     #{type => sms, text => <<"hi">>},
     #{type => sms, text => <<"hi">>},
     #{type => sms, text => <<"hi">>}].

Here is the code that will handle the sum and sort things. We create one function that will be the exported and that function will call a helper function with two arguments. First is the input we get, the other argument is the accumulator that we will return.

Helper function will match first element in the list and then check if we have already summed it. I have created my own functions now to get values and remove values to more show how pattern matching and recursion works. OTP library have proplists module or other modules to do this.

4> List = pattern:generate_list().
[#{text => <<"hi">>,type => sms},
 #{text => <<"hi">>,type => email},
 #{text => <<"hi">>,type => sms},
 #{text => <<"hi">>,type => email},
 #{text => <<"hi">>,type => sms},
 #{text => <<"hi">>,type => sms},
 #{text => <<"hi">>,type => sms}]
5> pattern:sum_by_type(List).
[{sms,5},{email,2}]

Small examples on how to use lists, tuples and maps.

Recursive functions

Daniel Widgren — Wed, 21 Oct 2020 04:42:38 +0000

This is me trying to describe recursive functions in Erlang. How you can write them and how it works.

Erlang uses recursive functions often because in other languages you have for, while and other loops. In Erlang we do it with recursive functions.

Example:

-module(recursive).

-export([sum/1]).

sum([]) ->
    0;
sum([Head | Tail]) ->
   Head + sum(Tail).

Here we do a sum function that will take a list of integers and summarize them.

15> recursive:sum([1,2,3]).
6

What happen when we call our function?

Thing in Erlang works that we go from the top to the bottom of our code.

recursive:sum([1,2,3]). When we call this function with argument [1,2,3] this will happen.

sum([]) ->
   0;
sum([1 | [2,3]]) ->
   1 + sum([2,3]).

First we will hit the first function clause and because our list contain three elements it will go on to the next function clause. Here the head of the list will be 1 and the tail will be list with two elements [2,3].

The recursive call that we call our function sum again but now with the tail will give us.

sum([]) ->
   0;
sum([2 | [3]]) ->
   2 + sum([3]).

We also do that with the last element in the list.

sum([]) ->
   0;
sum([3 | []]) ->
   3 + sum([]).

Last call here will hit the base case and return a 0.

This will calculate 3 + 2 + 1 + 0 (base case) = 6.

You can also do this with tail recursive so you pass the result of the recursive to the next.

sum([], Sum) ->
    Sum;
sum([Head | Tail], Sum) ->
    sum(Tail, Sum + Head).

This is our function with tail recursive. What will happen here is very similar to what we did above. Different now is that we to the addition in the recursive step and send the result to the next recursive. When we hit base case we will return the result.

16> c(recursive).          
{ok,recursive}
17> recursive:sum([1,2,3], 0).
6

We have now created a function called sum that now have aritry 2. It will take the list with integers and the start value.

sum([], Sum) ->
   Sum;
sum([1 | [2,3]], 0) ->
   sum([2,3], 0 + 1).

sum([], Sum) ->
   Sum;
sum([2 | [3]], 1) ->
   sum([3], 1 + 2).

sum([], Sum) ->
   Sum;
sum([3 | []], 3) ->
   sum([], 3 + 3).

sum([], 6) ->
   6;
sum([Head | Tail], Sum) ->
   sum(Tail, Sum + Head).

When we hit the base case and the list is empty we will return the variable Sum that is in this case 6.

Getting started with Nova

Daniel Widgren — Wed, 05 Aug 2020 11:38:55 +0000

Create a new Nova application

We mentioned before that we wanted to get away from the hazzle of starting new things. To make it easier to install we have made this script. This one will check for rebar3 and if you don't have it install. Also it will add rebar3_nova, with that you will have some templates that will help you create your first Nova app.

$ sh -c "$(curl -fsSL https://raw.githubusercontent.com/novaframework/rebar3_nova/master/install.sh)"

When the rebar3 plugin is installed, you can template a new Nova app with the command.

Rebar3 new command that we will use can generate from start either and Erlang application or library.

$ rebar3 new app this_is_an_application
$ rebar3 new lib this_is_a_lib

But we want to create a Nova application, with rebar3_nova we will have a Nova template so we can write nova and the application name.

$ rebar3 new nova my_first_nova

This command will create a directory with the same name as your application, then it will add all the files needed to have a running Nova application.

===> Writing my_first_nova/config/dev_sys.config.src
===> Writing my_first_nova/config/prod_sys.config.src
===> Writing my_first_nova/src/my_first_nova.app.src
===> Writing my_first_nova/src/my_first_nova_app.erl
===> Writing my_first_nova/src/my_first_nova_sup.erl
===> Writing my_first_nova/src/my_first_nova_router.erl
===> Writing my_first_nova/src/controllers/my_first_nova_main_controller.erl
===> Writing my_first_nova/rebar.config
===> Writing my_first_nova/config/vm.args.src
===> Writing my_first_nova/priv/assets/favicon.ico
===> Writing my_first_nova/src/views/my_first_nova_main.dtl
===> Writing my_first_nova/.tool-versions
===> Writing my_first_nova/.gitignore

.tool-versions is used by asdf to know what versions of different packages that we can use here.

erlang 26.2.2
rebar 3.22.1

If we now use asdf it will install Erlang with version 26.2.2 and rebar3 version 3.22.1.

asdf install

asdf will now start downloading and installing both Erlang and Rebar3.

In src/ is our source code, in this library you will have two other libraries. One is src/controllers here are the modules that we call controllers, they contain the logic of your application. src/views contains the django templates.

rebar.config is for telling rebar3 how to build our application and also if we want to add dependencies or how we do releases. I will dig into this deeper later.

In the config/ directory you have two configuration files for your application, dev_sys.config.src and prod_sys.config.src. When we develop we use two commands in rebar3, first one is:

rebar3 shell

This will compile your code and start an Erlang shell, this is what we call development mode, so it will help you with dependencies and load all code. With the rebar3_nova plugin we have created a new command that is called:

rebar3 nova serve

This command will do the same as rebar3 shell but with the addition that it will get notification if a file was changed and compile it for you and re-load it. While you develop and save your file the node will compile and re-load so you don't need to restart everything.

Both of these commands when started will use the dev_sys.config.src configuration.

Run our example

$ rebar3 nova serve

When the node is up you can start a browser and go to localhost:8080 this will show a homepage telling you that the system is up. The other way to see if your system is up is to curlheartbeat endpoint.

curl -v localhost:8080/heartbeat
*   Trying 127.0.0.1:8080...
* TCP_NODELAY set
* Connected to localhost (127.0.0.1) port 8080 (#0)
> GET /heartbeat HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.68.0
> Accept: */*
> 
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< content-length: 0
< date: Fri, 26 Jul 2024 08:39:45 GMT
< server: Cowboy/Nova
< vary: accept-encoding
< set-cookie: session_id=60dl0UW8dnaUPU7DZ24GfF99+yTO2KAPzrWwUo0B0Zg=
< 
* Connection #0 to host localhost left intact

To list our routes, we can use rebar3 nova routes

Host: '_'
     ├─  /assets
        └─  _ /[...] (my_first_nova, cowboy_static:init/1)
     └─  GET / (my_first_nova, my_first_nova_main_controller:index/1)

What is Nova?

Daniel Widgren — Sun, 02 Aug 2020 15:18:18 +0000

Nova

What is Nova?

One of our goals is that it should be easy to start a web project in Erlang and to maintain and operate it. With that, we have created rebar3_nova, which not only templates modules for you but also bootstraps applications, so you can get something up and running fast.

Nova is a View-Controller right now. We are working on integrating models and databases into it but have yet to do so. As for views, we currently use erlydtl.

Why should I use Nova?

Nova is the solution for rapid application development. Born from the frustrations of repetitive setup tasks in Cowboy, it offers quick application bootstrapping, eliminates code redundancy, and provides clear visibility into your application's flow. With Nova, you'll slash time-to-market, enhance code reusability, and troubleshoot with ease. Streamline your workflow and conquer modern development challenges with Nova.

Pre-requirements for this series

Nova is using Erlang as a language and Rebar3 as a tool to compile. I will use asdf in this tutorial for how to install Erlang and Rebar3, if you want to install them using other ways you can read at Adopting Erlang on how to install them.

Rebar3

Rebar3 is the tool we will use for building our application and creating releases and even documentation. Rebar3 has something called plugins, which is code that helps us with some functionality. We will next article introduce you to rebar3_nova a Rebar3 plugin that makes developing and working with Nova much smoother.

asdf

asdf is a version manager system that helps you use the correct tools when developing an application. This is not only for Erlang, it can be used for many areas you can read more about asdf here.

When we bootstrap our application we will get a .tool-versions file that includes Erlang and Rebar3 versions that you can install with asdf.

How to install asdf, you can read here for more details.

git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0

This will install the asdf system, and then you will need to add it to your shell, I will show bash but if you are using other shell you can read here.

Bash & Git
Add the following to ~/.bashrc:

. "$HOME/.asdf/asdf.sh"

Completions must be confgured by adding the following to your .bashrc:

. "$HOME/.asdf/completions/asdf.bash"

After that asdf is installed we need to add the Rebar plugin to asdf.

asdf plugin-add rebar https://github.com/Stratus3D/asdf-rebar.git

And also the Erlang plugin.

asdf plugin add erlang https://github.com/asdf-vm/asdf-erlang.git

We will need these plugins later when we start Nova.

enotify

In the rebar3 nova plugin, we also use enotify.

Depending on your system you will need to install the dependency that is listed below.

Backends
Mac fsevent
Linux inotify
Windows inotify-win
NOTE: On Linux, you need to install inotify-tools.

When enotify is installed and working, we can use the rebar3 nova serve command. That will work as rebar3 shell but it will look for files that have been changed and recompile them. It is very nice when you develop, that you don't need to recompile your node each time you want to change something or develop something new.

In this serie

In this serie I will write about how you create a Nova application with a web login that also can include other Nova applications.