Francis

Simple boilerplate killer using Plug and Bandit inspired by Sinatra for Ruby.

Focused on reducing time to build as it offers automatic request parsing, automatic response parsing, easy DSL to build quickly new endpoints and websocket listeners.

Installation

If available in Hex, the package can be installed by adding francis to your list of dependencies in mix.exs:

def deps do
  [
    {:francis, "~> 0.1.0"}
  ]
end

You can also use the Francis generator to create all the initial project files. You need to install the francis tasks first.

mix archive.install hex francis

Then you can create a new project with:

mix francis.new my_app

Use mix help francis.new to see all the available options.

Usage

To start the server up you can run mix francis.server or if you need a iex console you can run with iex -S mix francis.server.

Deployment

To create the Dockerfile that can be used for deployment you can run:

mix francis.release

Configuration

You can configure Francis in your config/config.exs file. The following options are available:

dev - If set to true, it will enable the development mode which will automatically reload the server when you change your code. Defaults to false.
bandit_opts - Options to be passed to Bandit
static - Configure Plug.Static to serve static files
parser - Overrides the default configuration for Plug.Parsers
error_handler - Defines a custom error handler for the server
log_level - Sets the log level for Plug.Logger (default is :info)

import Config

config :francis,
  dev: false,
  bandit_opts: [port: 4000],
  static: [from: "priv/static", at: "/"],
  parser: [parsers: [:json, :urlencoded], pass: ["*/*"]],
  error_handler: &Example.error/2,
  log_level: :info

You can also set the values in use macro:

defmodule Example do
  use Francis,
    dev: true,
    bandit_opts: [port: 4000],
    static: [from: "priv/static", at: "/"],
    parser: [parsers: [:json, :urlencoded], pass: ["*/* "]],
    error_handler: &Example.error/2,
    log_level: :info
end

Error Handling

By default, Francis will return a 500 error with the message "Internal Server Error" if you return a tuple {:error, any()} or an exception is raised during the request handling.

Unmatched Routes

If a request does not match any defined route, you can use the unmatched/1 macro to define a custom response:

unmatched(fn _conn -> "not found" end)

Custom Error Responses

For more advanced error handling, you can setup a custom error handler by providing the function that will handle the errors of your application:

defmodule Example do
  use Francis, error_handler: &__MODULE__.error/2

  get("/", fn _ -> {:error, :potato} end)

  def error(conn,{:error, :failed}) do
    # Return a custom response
    Plug.Conn.send_resp(conn, 502, "Custom error response")
  end
end

If you do not handle errors explicitly, Francis will catch them and return a 500 response.

Example of a router

defmodule Example do
  use Francis

  get("/", fn _ -> "<html>world</html>" end)
end

If you do not handle errors explicitly, Francis will catch them and return a 500 response.

Example of a router

defmodule Example do
  use Francis

  get("/", fn _ -> "<html>world</html>" end)
  get("/:name", fn %{params: %{"name" => name}} -> "hello #{name}" end)
  post("/", fn conn -> conn.body_params end)

  ws("ws", fn "ping" -> "pong" end)

  unmatched(fn _ -> "not found" end)
end

And in your mix.exs file add that this module should be the one used for startup:

def application do
  [
    extra_applications: [:logger],
    mod: {Example, []}
  ]
end

This will ensure that Mix knows what module should be the entrypoint.

Example of a router with Static serving

With the static option, you are able to setup the options for Plug.Static to serve static assets easily.

defmodule Example do
  use Francis, static: [from: "priv/static", at: "/"]
end

Example of a router with Plugs

With the plugs option you are able to apply a list of plugs that happen between before dispatching the request.

In the following example we're adding the Plug.BasicAuth plug to setup basic authentication on all routes

defmodule Example do
  import Plug.BasicAuth

  use Francis

  plug(:basic_auth, username: "test", password: "test")

  get("/", fn _ -> "<html>world</html>" end)
  get("/:name", fn %{params: %{"name" => name}} -> "hello #{name}" end)

  ws("ws", fn "ping", _socket -> "pong" end)

  unmatched(fn _ -> "not found" end)
end

Example of multiple routers

You can also define multiple routers in your application by using the forward/2 function provided by Plug .

For example, you can have an authenticated router and a public router.

defmodule Public do
  use Francis
  get("/", fn _ -> "ok" end)
end

defmodule Private do
  use Francis
  import Plug.BasicAuth
  plug(:basic_auth, username: "test", password: "test")
  get("/", fn _ -> "hello" end)
end

defmodule TestApp do
  use Francis

  forward("/path1", to: Public)
  forward("/path2", to: Private)

  unmatched(fn _ -> "not found" end)
end

Check the folder examples to see examples of how to use Francis.