DD_Plug.md

Plug lives at the heart of Phoenix's HTTP layer, and Phoenix puts Plug front and center. We interact with plugs at every step of the connection lifecycle, and the core Phoenix components like Endpoints, Routers, and Controllers are all just Plugs internally. Let's jump in and find out just what makes Plug so special.

Plug is a specification for composable modules in between web applications. It is also an abstraction layer for connection adapters of different web servers. The basic idea of Plug is to unify the concept of a "connection" that we operate on. This differs from other HTTP middleware layers such as Rack, where the request and response are separated in the middleware stack.

The Plug Specification

At the simplest level, the Plug specification comes in two flavors, function plugs and module plugs

Function Plugs

In order to act as a plug, a function simply needs to accept a connection struct (%Plug.Conn{}) and options. It also needs to return the connection struct. Any function that meets those criteria will do. Here's an example.

def put_headers(conn, key_values) do
  Enum.reduce key_values, conn, fn {k, v}, conn ->
    Plug.Conn.put_resp_header(conn, k, v)
  end
end

Pretty simple, right?

This is how we use them to compose a series of transformations on our connection in Phoenix:

defmodule HelloPhoenix.MessageController do
  use HelloPhoenix.Web, :controller

  plug :put_headers, %{content_encoding: "gzip", cache_control: "max-age=3600"}
  plug :put_layout, "bare.html"
  plug :action

  ...
end

By abiding by the plug contract, put_headers/2, put_layout/2, and even action/2 turn an application request into a series of explicit transformations. It doesn't stop there. To really see how effective Plug's design is, let's imagine a scenario where we need to check a series of conditions and then either redirect or halt if a condition fails. Without plug, we would end up with something like this:

defmodule HelloPhoenix.MessageController do
  use HelloPhoenix.Web, :controller

  def show(conn, params) do
    case authenticate(conn) do
      {:ok, user} ->
        case find_message(params["id"]) do
          nil ->
            conn |> put_flash("That message wasn't found") |> redirect(to: "/")
          message ->
            case authorize_message(conn, params["id"])
              :ok ->
                render conn, :show, page: find_page(params["id"])
              :error ->
                conn |> put_flash("You must be logged in") |> redirect(to: "/")
            end
        end
      :error ->
        conn |> put_flash("You can't access that page") |> redirect(to: "/")
    end
  end
end

Notice how just a few steps of authentication and authorization require complicated nesting and duplication? Let's improve this with a couple of plugs.

defmodule HelloPhoenix.MessageController do
  use HelloPhoenix.Web, :controller

  plug :authenticate
  plug :find_message
  plug :authorize_message
  plug :action

  def show(conn, params) do
    render conn, :show, page: find_page(params["id"])
  end

  defp authenticate(conn, _) do
    case Authenticator.find_user(conn) do
      {:ok, user} ->
        assign(conn, :user, user)
      :error ->
        conn |> put_flash("You must be logged in") |> redirect(to: "/") |> halt
    end
  end

  defp find_message(conn, _) do  
    case find_message(params["id"]) do
      nil ->
        conn |> put_flash("That message wasn't found") |> redirect(to: "/") |> halt
      message ->
        assign(conn, :message, message)
    end
  end

  defp authorize_message(conn, _) do
    if Authorizer.can_access?(conn.assigns[:user], conn.assigns[:message]) do
      conn
    else
      conn |> put_flash("You can't access that page") |> redirect(to: "/") |> halt
    end
  end
end

By replacing the nested blocks of code with a flattened series of plug transformations, we are able to achieve the same functionality in a much more composable, clear, and reusable way.

Now let's look at the other flavor plugs come in, module plugs.

Module Plugs

Module plugs are another type of Plug that let us define a connection transformation in a module. The module only needs to implement two functions:

• init/1 which initializes any arguments or options to be passed to call/2
• call/2 which carries out the connection transformation. call/2 is just a function plug that we saw earlier

To see this in action, lets write a module plug that puts the :locale key and value into the connection assign for downstream use in other plugs, controller actions, and our views.

defmodule HelloPhoenix.Plugs.Locale
  import Plug.Conn

  @locales ["en", "fr", "de"]

  def init(default), do: default

  def call(%Plug.Conn{params: %{"locale" => loc}}, _default) when loc in @locales do
    assign(conn, :locale, loc)
  end
  def call(conn, default), do: assign(conn, :locale, default)
end

defmodule HelloPhoenix.Router do
  use HelloPhoenix.Web, :router

  pipeline :browser do
    plug :accepts, ["html"]
    plug :fetch_session
    plug :fetch_flash
    plug :protect_from_forgery
    plug HelloPhoenix.Plugs.Locale, "en"
  end
  ...

We are able to add this module plug to our browser pipeline via plug HelloPhoenix.Plugs.Locale, "en". In the init/1 callback, we pass a default locale to use if none is present in the params. We also use pattern matching to define multiple call/2 function heads to validate the locale in the params, and fall back to "en" if there is no match.

That's all there is to Plug. Phoenix embraces the plug design of composable transformations all the way up and down the stack. This is just the first taste. If we ask ourselves, "Could I put this in a plug?" The answer is usually, "Yes!"