Plug is:
- A specification for composable modules in between web applications
- Connection adapters for different web servers in the Erlang VM
Documentation for Plug is available online.
defmodule MyPlug do
import Plug.Conn
def init(options) do
# initialize options
options
end
def call(conn, _opts) do
conn
|> put_resp_content_type("text/plain")
|> send_resp(200, "Hello world")
end
end
IO.puts "Running MyPlug with Cowboy on http://localhost:4000"
Plug.Adapters.Cowboy.http MyPlug, []
The snippet above shows a very simple example on how to use Plug. Save that snippet to a file and run it inside the plug application with:
mix run --no-halt path/to/file.exs
Access "http://localhost:4000" and we are done!
You can use plug in your projects in two steps:
-
Add plug and your webserver of choice (currently cowboy) to your
mix.exs
dependencies:def deps do [{:cowboy, "~> 1.0.0"}, {:plug, "~> 0.6.0"}] end
-
List both
:cowboy
and:plug
as your application dependencies:def application do [applications: [:cowboy, :plug]] end
Note: if you are using Elixir master, please use Plug master (from git) as well.
In the hello world example, we defined our first plug. What is a plug after all?
A plug takes two shapes. It is a function that receives a connection and a set of options as arguments and returns the connection or it is a module that provides an init/1
function to initialize options and implement the call/2
function, receiving the connection and the initialized options, and returning the connection.
As per the specification above, a connection is represented by the Plug.Conn
record (docs):
%Plug.Conn{host: "www.example.com",
path_info: ["bar", "baz"],
...}
Data can be read directly from the record and also pattern matched on. However, whenever you need to manipulate the record, you must use the functions defined in the Plug.Conn
module (docs). In our example, both put_resp_content_type/2
and send_resp/3
are defined in Plug.Conn
.
Remember that, as everything else in Elixir, a connection is immutable, so every manipulation returns a new copy of the connection:
conn = put_resp_content_type(conn, "text/plain")
conn = send_resp(conn, 200, "ok")
conn
Finally, keep in mind that a connection is a direct interface to the underlying web server. When you call send_resp/3
above, it will immediately send the given status and body back to the client. This makes features like streaming a breeze to work with.
Plug ships with a Plug.Test
module (docs) that makes testing your plugs easy. Here is how we can test our hello world example:
defmodule MyPlugTest do
use ExUnit.Case, async: true
use Plug.Test
@opts MyPlug.init([])
test "returns hello world" do
# Create a test connection
conn = conn(:get, "/")
# Invoke the plug
conn = MyPlug.call(conn, @opts)
# Assert the response and status
assert conn.state == :sent
assert conn.status == 200
assert conn.resp_body == "Hello world"
end
end
The Plug router allows developers to quickly match on incoming requests and perform some action:
defmodule AppRouter do
import Plug.Conn
use Plug.Router
plug :match
plug :dispatch
get "/hello" do
send_resp(conn, 200, "world")
end
match _ do
send_resp(conn, 404, "oops")
end
end
The router is a plug, which means it can be invoked as:
AppRouter.call(conn, AppRouter.init([]))
Each route needs to return the connection as per the Plug specification.
Note Plug.Router
compiles all of your routes into a single function and relies on the Erlang VM to optimize the underlying routes into a tree lookup, instead of a linear lookup that would instead match route-per-route. This means route lookups are extremely fast in Plug!
This also means that a catch all match
is recommended to be defined, as in the example above, otherwise routing fails with a function clause error (as it would in any regular Elixir function).
This project aims to ship with different plugs that can be re-used accross applications:
Plug.Head
(docs) - converts HEAD requests to GET requests;Plug.MethodOverride
(docs) - overrides a request method with one specified in headers;Plug.Parsers
(docs) - responsible for parsing the request body given its content-type;Plug.Session
(docs) - handles session management and storage;Plug.Static
(docs) - serves static files;
Plug source code is released under Apache 2 License. Check LICENSE file for more information.