So I’m on page 34.
I have a question regarding that quote:
We know that the last plug in the endpoint is the router, and we know we
can find that file in lib/hello_web/router.ex .
A plug is essentially a function that comes from the plug module. If that so why router is being called a plug?
And if plugs are functions why call them plugs(my answer for convenient reasons because they come from plug module)?
A plug is essentially a function that comes from the plug module.
So, basically you’re right, a plug is a function. But it’s not any function, it is a 2 arity function where the first argument is a Plug.Conn and the second is a list of options, and also, the return must be always a Plug.Conn. If the function doesn’t follow those rules, it can’t be used as a Plug, because that’s the way the plug lib handle’s them.
And if plugs are functions why call them plugs(my answer for convenient reasons because they come from plug module)?
As answered before, not all functions can be used as plugs, just functions that follow a predefined set of rules. But you are actually kind of right, it’s for convenience, but not because they come from a specific module, actually because it is convenient to have names that classify specific types of functions, “operators” for example, they are mostly functions (some are macros, but ok), but we call operators functions that can be used in the pattern first_arg X second_arg (like 1 + 2), but deep inside, they are just functions that follow a set of rules, just like plugs.
In the case of plugs, a behaviour can be used to make sure you implement the correct functions.
From what I can tell the 2nd parameter on (Plug.Conn.t, Plug.opts) :: Plug.Conn.t is useless (***) with a function plug - it exists only for compatibility with the module plug.
The documentation’s examplemodule plug looks like this:
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
There are two functions call/2 and init/1. Again in this particular case the 2nd parameter _opts for call/2 is unused. While init/1 and call/2 exist in the same module there is a difference that is easy to miss:
i.e.
init/1 is called during compile time to generate a “compile time configuration” for the Plug
call/2 is called during run time (while the request is being processed) and is passed the options that were generated by init/1during compilation.
The compilation/runtime split is sometimes used for testing but init/1 gives a module plug a standardized method for compile time configuration (or think of it as server configuration rather than request configuration).
Plug.Cowboy makes use of the Plug specification.
init/1 is used when the dispatch is created during compile time (or more accurately when the server is starting - but not yet processing any requests):
call/2 is used at runtime in the Plug.Cowboy.Handler:
defmodule HelloWeb.Router do
use HelloWeb, :router
pipeline :browser do
plug :accepts, ["html"]
plug :fetch_session
plug :fetch_flash
plug :protect_from_forgery
plug :put_secure_browser_headers
end
pipeline :api do
plug :accepts, ["json"]
end
scope "/", HelloWeb do
pipe_through :browser # Use the default browser stack
get "/", PageController, :index
end
end
First of all use HelloWeb, :router injects a lot of code into HelloWeb.Router. Looking into HelloWeb.ex there is
defmacro __using__(which) when is_atom(which) do
apply(__MODULE__, which, [])
end
So use HelloWeb, :router turns into Kernel.apply(HelloWeb, :router) (see apply/3) at compile time which is equivalent to HelloWeb.router(). Looking up into the HelloWeb module you’ll find that router function:
def router do
quote do
use Phoenix.Router
import Plug.Conn
import Phoenix.Controller
end
end
So use HelloWeb, :router turns into:
use Phoenix.Router
import Plug.Conn
import Phoenix.Controller
The same type of thing happens recursively with use Phoenix.Router - in deps/phoenix/lib/phoenix/router.ex:
defmacro __using__(_) do
quote do
unquote(prelude())
unquote(defs())
unquote(match_dispatch())
end
end
The interesting one is match_dispatch():
defp match_dispatch() do
quote location: :keep do
@behaviour Plug
@doc """
Callback required by Plug that initializes the router
for serving web requests.
"""
def init(opts) do
opts
end
@doc """
Callback invoked by Plug on every request.
"""
def call(conn, _opts) do
%{method: method, path_info: path_info, host: host} = conn = prepare(conn)
case __match_route__(method, Enum.map(path_info, &URI.decode/1), host) do
:error -> raise NoRouteError, conn: conn, router: __MODULE__
match -> Phoenix.Router.__call__(conn, match)
end
end
defoverridable [init: 1, call: 2]
end
end
This is the function that turns your hello_web/router.ex into a module plug as it provides the compile time init/1 function and the runtime call/2 function.
Edit: *** Correction - not entirely useless. For example with Plug.Builder.plug/2 you can supply the options to be passed to a function plug.