novaframework / nova

Web framework for Erlang.

Simple. Fault-tolerant. Distributed.

• Create a basic webpage in minutes
• Using Erlang OTP to achieve both fault-tolerance and distribution

http://www.novaframework.org

Getting started

Start by adding the rebar3 template for Nova. This can be done by running the installation script;

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

Manually with rebar.config

Add rebar3_nova to ~/.config/rebar3/rebar.config

{project_plugins, [rebar3_nova]}

After this is done use rebar3 to generate a new project with Nova.

rebar3 new nova my_first_nova

Supported Erlang versions

Nova is supported with OTP 23 and above.

Documentation

Hex docs: https://hexdocs.pm/nova/

More on how things work can be read in the docs Getting Started.

Articles

• Building an Erlang Web Api using Nova Framework and Redis

Contributing

Contribution is welcome to Nova. Check our CODE OF CONDUCT for more information. We will add features and bugs to the issues list.

Generating a Nova project

Start a new project with:

rebar3 new nova my_first_nova

That will generate a Nova project for you.

rebar3 nova serve

This will fetch all dependencies and compile. After the compilation it will start a shell that says which port it is running on and a few debug lines.

When the shell is started, open a browser and go to localhost:8080 which will point to the my_first_nova server running Nova.

Important links

• Erlang Slack channel
• Issue tracker
• Nova Forum (questions)
• Visit Nova's sponsors for expert Nova consulting:
  • Burbas Consulting
  • Widgrens IT

nova's Issues

Read and complement README

Add a logo, and also read so basic things are in place.

Run tests on Travis CI

Rebar3 template to generate only nova rest

It would be good if we had a template that only generated a rest project without the view handling.

Make sure we can use Erlang 24

We have some dependencies that need to solve otp 24 for functions that will be deprecated. We should look into this before 24 is released.

Add opentelematey

We should add so we use opentelematry to collect data. That can be used by others to view data and logs.

Replace the Req object with a Nova-state instead for controllers

The cowboy_req-object will be moved into a nova-state datastructure instead. This is so we have more freedom to include more information to the controller without having to add more arguments. Modules like the security-handler will be using this to make a better experience for the devs.

Add -specs and function documentation on public functions

Support for registering external handlers

Today we have a special {external_handler, Module, Payload}. It would be nice if this could be automatically and the user then can specify an external handler in the same way as the others eg. {send_pong, Payload}

Include web_port in the templated config

CORS

Is this something we should handle in Nova or should we create a plugin for it so users can decide by them self how it should be used in their applications?

Example is that OPTIONS should not have auth on it and return data on what methods is allowed and headers. Is it possible to solve today, but it need some boilerplate code in all controllers to work.

Create a step-by-step guide on creating a simple site

Maybe use the nova_blog as an example

Create a admin interface (seperate repo)

can't install nova framework

sh -c "$(curl -fsSL https://raw.githubusercontent.com/novaframework/nova/master/tools/install.sh)"
sh -c "$(wget -O- https://raw.githubusercontent.com/novaframework/nova/master/tools/install.sh)"
executing the above commands results in 404 not found

Remove copyright headers in source-files

Nova does not support prefix and security parameters for sub nova-applications

Prefix and security parameters should be part of the nova_applications-list in application-config

Validate JSON schemas

Perhaps it would be a nice thing (if the user chooses it) to validate incoming JSON data with a schema if such exist.

rebar3 error

Reading rebar3 configuration failed. Check your file (and if it does not exist - create it). The file is:
escript: exception error: bad argument
in function io:format/3
called as io:format(<0.62.0>,"sn","/")

More route validation

This is a quality of life improvement that I wanted to take note of before I forgot.

Today I ran into an issue where the routes file I made compiled fine but led to 404 errors.

I had this:

{"/update/did/subject", {did_repo_admin_controller, update_did_subject, #{methods => [post]}}}

But I needed this:

{"/update/did/subject", {did_repo_admin_controller, update_did_subject}, #{methods => [post]}}

Obviously, this is user error. However, it is such a subtle difference that it would be helpful if the tooling could identify these types of issues too.

Fix CI/CD pipelines

Move templates back into the master branch

Use a ORM for models

For a long time we said no to integrating an ORM into Nova but now might be the time.

We found a really fancy library called erldb (That myself and @Taure wrote a couple of years ago) that will fullfil most of our need. There's not a whole lot of backends to it (yet), but it has potential of growing into something really valuable.

https://github.com/erldb/erldb

static routing is not working in 0.7.1

With new routing in place static routing is not working.

https://github.com/Taure/trylfe

this repo have static routing that returns 404 instead of correct html file. Old version it works.

Refactor nova_router

Today the router is structured as a gen-server with lots of handle_cast-cases. This works okay, but gets a bit complex. One suggestion is to refactor the router and move most of the parsing-actions to separate methods instead and use the gen-server as a orcestrator for routes - handling the communications with cowboy and provide an API that one clients can query to modify/remove/add routes.

Also include the suggestions from #50 when refactoring this

Missing plugins in config make nova_ws_handle crash

1> =ERROR REPORT==== 16-Sep-2020::19:27:52.996492 ===
Websocket failed with error:{case_clause,
                                  {ok,
                                   #{app => nova_chat,
                                     controller_data => #{user => <<"user1">>},
                                     mod => nova_chat_ws,
                                     nova_handler => nova_ws_handler,
                                     secure => false,subprotocols => []}}}.
Stacktrace:
[{nova_ws_handler,run_post_plugin,1,
                  [{file,"/home/daniel/projects/nova_chat/_build/default/lib/nova/src/nova_ws_handler.erl"},
                   {line,147}]},
 {nova_ws_handler,invoke_controller,4,
                  [{file,"/home/daniel/projects/nova_chat/_build/default/lib/nova/src/nova_ws_handler.erl"},
                   {line,113}]},
 {cowboy_websocket,handler_call,6,
                   [{file,"/home/daniel/projects/nova_chat/_build/default/lib/cowboy/src/cowboy_websocket.erl"},
                    {line,527}]},
 {cowboy_http,loop,1,
              [{file,"/home/daniel/projects/nova_chat/_build/default/lib/cowboy/src/cowboy_http.erl"},
               {line,254}]},
 {proc_lib,init_p_do_apply,3,[{file,"proc_lib.erl"},{line,226}]}]

Routing and Module:Function

Today we can specify routing like this:

{"/v1/user", { my_controller, create_user}, #{methods => [post]}},
{"/v1/user/:userid", {my_controller, manage_user}, #{methods => [put, get, delete]}}

Each endpoint can only handle one function. It would be nice to be able to point different methods to different functions.

Example:

{"/v1/user", post, { my_controller, create_user}, ...},
{"/v1/user/:userid", get, { my_user_controller, get_user} ... },
{"/v1/user/:userid", put, { my_user_controller, change_user}, ... },
{"/v1/user/:userid", delete, { my_controller, remove_user}, ... }

In this way we can get explicit functions from routing and methods. And it is also easy to see what endpoint points against Module:Function.

Create a erlydtl custom tag for handling dynamic urls to internal routes

If we include an application and sets its prefix to something like "/prefix" we need some way to address this route somehow. One suggestion is a filter to erlydtl that tells us what application. Something like {{ "/my_route"|app:my_app}}

Problem with session object

Today we don't support to return the cowboy_req-object from a controller. This makes it hard for nova_session that sets the session_id as a cookie-value in the cowboy_req-object.

So either we change the return-values to include an optional cowboy_req object or have some kind of central storage where we can keep track of all the req-objects in the system (Will be very short-lived data).

I think the second idea makes it easier for the user, but will increase the complexity of Nova.

The first idea, having a optional cowboy_req object in the return could be solved with something like {{ok, Variables}, Req}. The downside with this is that the user needs to be aware of this when handling things like sessions.

Erlydtl gives warning because of get_stacktrace()

Erlydtl is using functions that will be depricated.

We should raise this to Erlydtl but also manage it until they have a fix.

Refactor the router in order to get more flexibility against other BEAM-languages

Today one can set route_parse_mf option to have a custom parsing of routes. This requires the user to implement the whole parsing of routes themselves which was not the original idea.

Refactor the router so that the parsing of routes is exposed (And can therefore be utilized by others).

Auto reload does not work with view changes

I've built the my_first_nova app and I noticed that with rebar3 auto it does not rebuild the page when any changes were made to src/views/my_first_nova_main.dtl file. I would expect the paged to be reloaded with the new content.
Also, it recompiles the whole project when changes are made in a controller eg. src/controllers/my_first_nova_main_controller.erl which takes a lot of time (~10 s) even for a small project instead of just recompiling and reading only this one module, for unknown to me reason dependencies are also recompiled.

Investigate how we could utilize the middleware option in cowboy

Right now we are wrapping cowboy but with the middleware option we could actually tap into cowboy making things like routing a bit easier.

nova_router render status page and lookup fails we call module that does not exist

2021-11-04T19:26:04.868209+01:00 error: [nova_handler] Controller crashed (error, undef), Stacktrace: [{nova_controller,status_code,[#{body_length => 0,cert => undefined,has_body => false,headers => #{<<"accept">> => <<"image/avif,image/webp,image/apng,image/svg+xml,image/*,*/*;q=0.8">>,<<"accept-encoding">> => <<"gzip, deflate, br">>,<<"accept-language">> => <<"en-US,en;q=0.9">>,<<"cache-control">> => <<"no-cache">>,<<"connection">> => <<"keep-alive">>,<<"cookie">> => <<"session_id=s1EvOn/1DuLA/XVHsA6BicDVszRPjlsYinkLPYIRgCw=; server=Cowboy/Nova">>,<<"host">> => <<"localhost:8080">>,<<"pragma">> => <<"no-cache">>,<<"referer">> => <<"http://localhost:8080/">>,<<"sec-ch-ua">> => <<"\"Chromium\";v=\"94\", \" Not A;Brand\";v=\"99\", \"Opera GX\";v=\"80\"">>,<<"sec-ch-ua-mobile">> => <<"?0">>,<<"sec-ch-ua-platform">> => <<"\"Windows\"">>,<<"sec-fetch-dest">> => <<"image">>,<<"sec-fetch-mode">> => <<"no-cors">>,<<"sec-fetch-site">> => <<"same-origin">>,<<"user-agent">> => <<"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36 OPR/80.0.4170.86">>},host => <<"localhost">>,method => <<"GET">>,path => <<"/favicon.ico">>,peer => {{127,0,0,1},48562},pid => <0.2025.0>,port => 8080,qs => <<>>,ref => nova_listener,resp_cookies => #{<<"server">> => [<<"server">>,<<"=">>,<<"Cowboy/Nova">>,<<"; Version=1">>,[]]},scheme => <<"http">>,sock => {{127,0,0,1},8080},streamid => 2,version => 'HTTP/1.1'}],[]},{nova_handler,execute,2,[{file,"/home/daniel/project/nova_project/my_first_app/_build/default/lib/nova/src/nova_handler.erl"},{line,40}]},{cowboy_stream_h,execute,3,[{file,"/home/daniel/project/nova_project/my_first_app/_build/default/lib/cowboy/src/cowboy_stream_h.erl"},{line,306}]},{cowboy_stream_h,request_process,3,[{file,"/home/daniel/project/nova_project/my_first_app/_build/default/lib/cowboy/src/cowboy_stream_h.erl"},{line,295}]},{proc_lib,init_p_do_apply,3,[{file,"proc_lib.erl"},{line,226}]}]

We try to call on a module nova_controller that does not exist anymore.

https://github.com/novaframework/nova/blob/master/src/nova_router.erl#L299

Investigate if we could have something similar to Phoenix 'Watchers'

In Phoenix they have an option called watchers which enables things like running node compilation during runtime. We could look into this and see if it's plausable to have in nova.

Proper session handling

The current session handling is based on ETS. The nova_session should be an abstract interface so that contributors can implement a session backend in an easy and modular way.

Reloader needs to compile dtl-files with options

We don't want to have options in several places. Right now we need to have one for sync and another for rebar3. It would be nice if we could fix a reloader that reads from the rebar.config instead.

Distributed session management

Make it possible to create endpoints that use websockets

We should be able to set what routes use websocket.

Create test suite for the framework itself

This is a really important issue since it allows us to ensure that a release is working before tagging it. My suggestion is that we introduce unit-tests for early catches and have a dockerized environment which we can define a workflow in - eg. create a nova application, start it and make a couple of curl calls to ensure it works.

Easier handling of nova applications

Today we have a map inside our config that specifies which nova applications should be included into the release. Each application is structured as a map and contains the name of the application and it's route-file. One suggestion is to simplify this into using atoms and derive the route-file from that.

Routing is not working in master

We removed a piece of code that were used for routing the main application. This needs to be fixed

Make plugins configurable with priority

It would be nice to have some sort of order for which plugins are executed. This can be implemented with a priority-value. Perhaps we can utilize https://github.com/okeuday/pqueue for this.

Add a better CSS to edocs

Would be great if we could have a better CSS that looks better than standard edocs.

Improve the "Quickstart" documentation

We need better guides on how to use Nova. Look at other frameworks and see what kind of example-app they build in their quickstart.

Include a Dockerfile with the templates

It would be nice to include a Dockerfile with the nova-templates so the user can build a docker image for the project.

Name of the rebar3 templated view is incorrect

Should be $project_main.dtl instead of $project_main_view.dtl

Investigate how we could ease testing of projects created with Nova

Return additional headers in returns

It might be nice to have ability to return additional headers and/or body for {status, ...}

Better handling of routes

We should refactor nova_router and aim to fix the following points:

• Easier code
• Support for status codes
• Proper support for inheritance of status codes
• Better docs

Install script

New install script should:
Idea is to have a script that install the plugins and check if some of the pre-reqs are installed.

• check if rebar3 is installed
• if rebar3 is not installed ask if latest version should be downloaded
• check if erlang is installed
• If erlang is not installed give a warning
• Add rebar3_nova to plugins in ~/.cache/rebar3/rebar.config

Can't view the default nova page.

"This page isn’t workinglocalhost is currently unable to handle this request.
HTTP ERROR 500"