Francis (Francis v0.1.22)

View Source

Module responsible for starting the Francis server and to wrap the Plug functionality

This module performs multiple tasks:

  • Uses the Application module to start the Francis server
  • Defines the Francis.Router which uses Francis.Plug.Router, :match and :dispatch
  • Defines the macros get, post, put, delete, patch and ws to define routes for each operation
  • Setups Plug.Static with the given options
  • Sets up Plug.Parsers with the default configuration of:
    • plug(Plug.Parsers,
        parsers: [:urlencoded, :multipart, :json],
        json_decoder: Jason
      )
  • Defines a default error handler that returns a 500 status code and a generic error message. You can override this by passing the function name on :error_handler option to the use Francis macro which will override the default error handler.

You can also set the following options:

  • :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

Summary

Functions

Defines a DELETE route

Defines a GET route

Defines a PATCH route

Defines a POST route

Defines a PUT route

Defines an action for umatched routes and returns 404

Defines a WebSocket route that sends text type responses.

Functions

delete(path, handler)

(macro)
@spec delete(String.t(), (Plug.Conn.t() -> binary() | map() | Plug.Conn.t())) ::
  Macro.t()

Defines a DELETE route

Examples

defmodule Example.Router do
  use Francis

  delete "/hello", fn conn ->
    "Hello World!"
  end
end

get(path, handler)

(macro)
@spec get(String.t(), (Plug.Conn.t() -> binary() | map() | Plug.Conn.t())) ::
  Macro.t()

Defines a GET route

Examples

defmodule Example.Router do
  use Francis

  get "/hello", fn conn ->
    "Hello World!"
  end
end

patch(path, handler)

(macro)
@spec patch(String.t(), (Plug.Conn.t() -> binary() | map() | Plug.Conn.t())) ::
  Macro.t()

Defines a PATCH route

Examples

defmodule Example.Router do
  use Francis

  patch "/hello", fn conn ->
    "Hello World!"
  end
end

post(path, handler)

(macro)
@spec post(String.t(), (Plug.Conn.t() -> binary() | map() | Plug.Conn.t())) ::
  Macro.t()

Defines a POST route

Examples

defmodule Example.Router do
  use Francis

  post "/hello", fn conn ->
    "Hello World!"
  end
end

put(path, handler)

(macro)
@spec put(String.t(), (Plug.Conn.t() -> binary() | map() | Plug.Conn.t())) ::
  Macro.t()

Defines a PUT route

Examples

defmodule Example.Router do
  use Francis

  put "/hello", fn conn ->
    "Hello World!"
  end
end

unmatched(handler)

(macro)
@spec unmatched((Plug.Conn.t() -> binary() | map() | Plug.Conn.t())) :: Macro.t()

Defines an action for umatched routes and returns 404

ws(path, handler, opts \\ [])

(macro)

Defines a WebSocket route that sends text type responses.

The handler function receives the message and the socket state, and it can return a binary or a map. The state includes:

  • :transport - The transport process that can be used to send messages back to the client using send/2
  • :id - A unique identifier for the WebSocket connection that can be used to track the connection
  • :path - The path of the WebSocket connection to identify the route that triggered the connection

Examples

defmodule Example.Router do
  use Francis

  ws "/hello", fn _, socket ->
    "Hello World!"
  end
end