shawn-mcginty/naboris

Simple, fast, minimalist http server for OCaml/ReasonML

Simple, fast, minimalist web framework for OCaml/ReasonML built on httpaf and lwt.

https://naboris.dev

// ReasonML
let serverConfig: Naboris.ServerConfig.t(unit) = Naboris.ServerConfig.create()
  |> Naboris.ServerConfig.setRequestHandler((route, req, res) => switch(Naboris.Route.path(route)) {
    | ["hello"] =>
      res
        |> Naboris.Res.status(200)
        |> Naboris.Res.text(req, "Hello world!");
    | _ =>
      res
        |> Naboris.Res.status(404)
        |> Naboris.Res.text(req, "Resource not found.");
  });

Lwt_main.run(Naboris.listenAndWaitForever(3000, serverConfig));
/* In a browser navigate to http://localhost:3000/hello */

(* OCaml *)
let server_config: unit Naboris.ServerConfig.t = Naboris.ServerConfig.create ()
  |> Naboris.ServerConfig.setRequestHandler(fun route req res ->
    match (Naboris.Route.path route) with
      | ["hello"] ->
        res
          |> Naboris.Res.text req "Hello world!";
      | _ ->
        res
          |> Naboris.Res.status 404
          |> Naboris.Res.text req "Resource not found.";
  ) in


let _ = Lwt_main.run(Naboris.listenAndWaitForever 3000 server_config)
(* In a browser navigate to http://localhost:3000/hello *)

Pre 1.0.0 the API may be changing a bit. A list of these changes will be kept below.

Contents

• Installation
• Scaffolding
• naboris.dev
• Development
• Breaking Changes

Installation

Note

Naboris makes heavy use of Lwt. For better performance it is highly recommended (however optional) to also install conf-libev which will configure Lwt to run with the libev scheduler. If you are using esy you will have to install conf-libev using a special package.

conf-libev also requires that the libev be installed. This can usually be done via your package manager.

brew install libev

or

apt install libev-dev

opam

opam install naboris

esy

"@opam/naboris": "^0.1.3"

dune

(libraries naboris)

Scaffolding

For a basic Reason project

git clone [email protected]:shawn-mcginty/naboris-re-scaffold.git
cd naboris-re-scaffold
npm run install
npm run build
npm run start

For a basic OCaml project

git clone [email protected]:shawn-mcginty/naboris-ml-scaffold.git
cd naboris-ml-scaffold
npm run install
npm run build
npm run start

Development

Any help would be greatly appreciated! 👍

To run tests

esy install
npm run test

Breaking Changes

From	To	Breaking Change
0.1.2	0.1.3	secret argument added to all session configuration APIs.
0.1.0	0.1.1	ServerConfig.setSessionGetter changed to ServerConfig.setSessionConfig which also allows ~maxAge and ~sidKey to be passed in optionally.
0.1.0	0.1.1	All RequestHandler.t and Middleware.t now return Lwt.t(Res.t) instead of Lwt.t(unit)
0.1.0	0.1.1	Res.reportError now taxes exn as the first argument to match more closely the rest of the Res API.

naboris's Issues

Remove all public records

Use module data types and functions instead. Keeping everything consistent.

Add support for sessions

Fix issues in code examples on README

Some of the code examples in the README don't work or have typos, they need to be fixed and verified to work.

Related to #33

Add OCaml syntax to docs

Unify Res API

Change Res redirect API to take req res as first arguments like most of the Res API

Add WebSocket feature

Refactor to use lwt ppx

The code could be made much more readable with the lwt ppx

Naboris.Res.static returns plain/text with .html files

Naboris.Res.static uses plain/text content type header instead of matching html file

Add support for CSRF tokens

Should look at other highly used HTTP frameworks and implement csrf tokens in a similar way.

add redirect

Should be easy to redirect a request to another uri

OCaml example from readme

Hi!
I was trying to execute OCaml example from readme

(* OCaml *)
let server_config: unit Naboris.ServerConfig.t = Naboris.ServerConfig.create ()
  |> Naboris.ServerConfig.setRequestHandler(fun route req res ->
    match (Naboris.Route.path route) with
      | ["hello"] ->
        res
          |> Naboris.Res.text req "Hello world!";
      | _ ->
        res
          |> Naboris.Res.status 404
          |> Naboris.Res.text req "Resource not found.";
  ) in

Naboris.listenAndWaitForever 3000 server_config
(* In a browser navigate to http://localhost:3000/hello *)

but I didn't get success.

Here are the steps:

opam switch create . ocaml-base-compiler.4.09.0
eval $(opam env)
opam install merlin ocp-indent dune utop naboris
touch main.ml #paste OCaml example
touch dune #paste dune config

(executable
    (name main)
    (libraries naboris)
)

dune build main.exe

No errors.
Execute

dune exec ./main.exe 
# or
_build/default/main.exe 

nothing happens.
I'm beginner in OCaml, so maybe I did something wrong. I would appreciate any advice. Thanks.

Middlewares should return Naboris.Res.t Lwt.t

Middlewares should return something that would be useful for examining how a request was responded to.

Add api for streaming response

Should be implemented by default on Res.static

Better documentation

A real frontend web app for documentation, something like expressjs.com. Probably find a free host or a cheap one, and a domain.

Encrypt session IDs

weirdness w/ chrome

Sometimes requests from chrome will lock the entire Naboris server up. If using cURL or incognito chrome everything works fine. Or even after clearing cookies/cache from chrome it will work again. Something with the state of chrome after a while causes it to spin forever. Need to track this down.

Custom error_handler

Let a user provide a custom error_handler for Httpaf

Add support for caching

Add cache response headers

1. Add (weak) ETag header to all GET responses (make this configurable)
2. Add Date header to all GET responses (make this configurable)
3. Add Last-Modified header to static responses (make this configurable)
4. Add Cache-Control: public, max-age=0 to static responses (make this configurable)

Support conditional requests
https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests
(except for If-Range)

Make session id and max age configurable

Add middleware hooks and unify API

add hooks for middleware

maybe beforeRouteRequest?

beforeRouteRequest could be a fn that takes something like Route.t -> Req.t -> Res.t -> (Route.t -> Req.t -> Res.t -> (Route.t * Req.t * Res.t) Lwt.t) -> (Route.t * Req.t * Res.t) Lwt.t) meaning it's last arg is the routeRequest function, which should be called to continue the lifecycle of the request.

maybe afterRouteRequest? I'm not as sure about that one

Naboris.Res.static hangs when file not found

Naboris.Res.static never responds if a file is not found

Static files OCaml example in readme

There are some typos in readme for OCaml static files example, but I was able to make it work like this:

let server_config: unit Naboris.ServerConfig.t = Naboris.ServerConfig.create ()
  |> Naboris.ServerConfig.setRequestHandler(fun route req res ->
    match ((Naboris.Route.meth route), (Naboris.Route.path route)) with
      | (Naboris.Method.GET, "static" :: static_path) ->
        Naboris.Res.static (Sys.getcwd() ^ "/static") static_path req res 
      | (Naboris.Method.GET, "/" :: []) ->
        Naboris.Res.static (Sys.getcwd() ^ "/static") ["/index.html"] req res
      | (Naboris.Method.GET, "" :: []) ->
        Naboris.Res.static (Sys.getcwd() ^ "/static") ["/index.html"] req res
      | _ ->
        res
          |> Naboris.Res.status 404
          |> Naboris.Res.text req "Resource not found.";
  )

let _ = Lwt_main.run begin
    Naboris.listenAndWaitForever 3000 server_config
end

By this index.html file from static folder is opened when gethttp://localhost:3000/ or http://localhost:3000.
Would be nice to have static folder by default or via parameter in ServerConfig for serving up static files. It can be useful for SPA.

Add delete session API

Add api for setting headers to remove a session cookie.

Clean up file descriptors in Res.static

Relates to #34

fds need to be closed in Res.static, there may be other perf benefits we can get there as well, some testing should be done.

Expose main lwt promise

Naboris.listen encapsulates the Lwt_main.runing of the promise. There should be a function to get the raw promise allowing the user to manage his own top level Lwt_main.run

Something like Naboris.listen_promise: int serverConfig -> 'a Lwt

typo in docs

git clone [email protected]:shawn-mcginty/naboris-ocaml-scaffold.git
should be
git clone [email protected]:shawn-mcginty/naboris-ml-scaffold.git

in the scaffolding section of "Quick Start"

Unix.EINVAL when serving static under load test

Fatal error: exception Unix.Unix_error(Unix.EINVAL, "select", "")

App code

let server_config: unit Naboris.ServerConfig.t = Naboris.ServerConfig.create ()
  |> Naboris.ServerConfig.setRequestHandler(fun route req res ->
    match ((Naboris.Route.meth route), (Naboris.Route.path route)) with
      | (Naboris.Method.GET, "static" :: static_path) ->
        Naboris.Res.static (Sys.getcwd() ^ "/static") static_path req res 
      | (Naboris.Method.GET, "/" :: []) ->
        Naboris.Res.static (Sys.getcwd() ^ "/static") ["/index.html"] req res
      | (Naboris.Method.GET, "" :: []) ->
        Naboris.Res.static (Sys.getcwd() ^ "/static") ["/index.html"] req res
      | _ ->
        res
          |> Naboris.Res.status 404
          |> Naboris.Res.text req "Resource not found.";
  )

let _ = Lwt_main.run begin
    Naboris.listenAndWaitForever 3000 server_config
end

vegeta targets file content
veg.txt
Request all files from static folder

GET http://localhost:3000/static/main-1f6385083dfd82fb9d36.css
GET http://localhost:3000/static/1.1f6385083dfd82fb9d36-build.js
GET http://localhost:3000/static/1f6385083dfd82fb9d36-build.js
GET http://localhost:3000/static/logo.png
GET http://localhost:3000

First test execution:

vegeta -cpus 1 attack -duration=20s -targets veg.txt | tee results.bin | vegeta report
Requests      [total, rate, throughput]  1000, 50.06, 50.05
Duration      [total, attack, wait]      19.979108875s, 19.976830593s, 2.278282ms
Latencies     [mean, 50, 95, 99, max]    4.25599ms, 2.605914ms, 6.75315ms, 12.32878ms, 160.517914ms
Bytes In      [total, mean]              134701400, 134701.40
Bytes Out     [total, mean]              0, 0.00
Success       [ratio]                    100.00%
Status Codes  [code:count]               200:1000  

Second one:

vegeta -cpus 1 attack -duration=20s -targets veg.txt | tee results.bin | vegeta report
Requests      [total, rate, throughput]  1000, 50.05, 23.13
Duration      [total, attack, wait]      21.837638678s, 19.979902873s, 1.857735805s
Latencies     [mean, 50, 95, 99, max]    278.843405ms, 2.774347ms, 1.122188958s, 3.228599022s, 4.313448889s
Bytes In      [total, mean]              68024207, 68024.21
Bytes Out     [total, mean]              0, 0.00
Success       [ratio]                    50.50%
Status Codes  [code:count]               0:495  200:505  
Error Set:
Get http://localhost:3000/static/1.1f6385083dfd82fb9d36-build.js: read tcp 127.0.0.1:62836->127.0.0.1:3000: read: connection reset by peer
Get http://localhost:3000/static/1f6385083dfd82fb9d36-build.js: read tcp 127.0.0.1:62838->127.0.0.1:3000: read: connection reset by peer
Get http://localhost:3000/static/main-1f6385083dfd82fb9d36.css: read tcp 127.0.0.1:62834->127.0.0.1:3000: read: connection reset by peer
Get http://localhost:3000/static/logo.png: dial tcp 0.0.0.0:0->[::1]:3000: connect: connection refused
Get http://localhost:3000: dial tcp 0.0.0.0:0->[::1]:3000: connect: connection refused
Get http://localhost:3000/static/main-1f6385083dfd82fb9d36.css: dial tcp 0.0.0.0:0->[::1]:3000: connect: connection refused
Get http://localhost:3000/static/1.1f6385083dfd82fb9d36-build.js: dial tcp 0.0.0.0:0->[::1]:3000: connect: connection refused
Get http://localhost:3000/static/1f6385083dfd82fb9d36-build.js: dial tcp 0.0.0.0:0->[::1]:3000: connect: connection refused

When -cpus more than 1 it always fails.

Seems like it is known issue of Lwt/OCaml ocsigen/lwt#529

Add support for partial requests

Blocked by #44

Implement these:
https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests

Implement:
If-Range - https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests

Add easy to use static config

Should add an easy to use config option for a static directory.

Related to #33

Any performance numbers to share?

Naboris looks great, definitely much more user-friendly than other options out there.

Would be interested to see how Naboris performs on the techempower benchmark or even a simple hello world.

thanks

Better error handling

Need unit tests for error handling and better config options for error handling.

Support newer versions of OCaml

I think some minor refactoring may be required but nothing is really in the way of supporting OCaml 4.10+

Hotfix - use content length headers

Use content length headers instead of connection close.