Elixir Plugs - question about Plug Modules

Phoenix actually never performs the “call” itself as far as I can tell. Phoenix is nothing more than a set of plugs and supporting libraries.

You are right about the init function, it gets called only when app stars. The call function, on the other hand, will be called on each request.

When a HTTP request comes in, Cowboy server is the first that starts handling such request. plug library adds hooks, builds up the chain of plug middlewares, and calls it, I believe here: plug/lib/plug/adapters/cowboy/handler.ex at 2df667389dbaebb0e2102343c8d7a6ed4de6e280 · elixir-plug/plug · GitHub

So, calling “call” happens on each and every request. Moreover, those calls get nested so a pipeline of plugs get processed by some macro (plug/lib/plug/builder.ex at main · elixir-plug/plug · GitHub) and when one call finishes, another call is executed, until some plug returns a valid response, in such case it is halted, response returned to the browser by cowboy. You don’t have to manually call upstream plugs because of smart macros that do it for us.

Basically, a request comes in → cowboy handler executed → plug1.call() → plug2.call() → plug3.call() etc.

You can think of this:

pipeline :browser do
  plug :accepts, ["html"]
  plug :fetch_session
  plug :fetch_flash
  plug :protect_from_forgery
  plug :put_secure_browser_headers
  plug Rumbl.Auth, repo: Rumbl.Repo
end

will generate this:

conn # the initial conn handled by cowboy, passed on to Phoenix
|> accepts(["html"])
|> fetch_session
|> fetch_flash
|> protect_from_forgery
|> put_secure_browser_headers
|> Rumbl.Auth.call(repo: Rumbl.Repo)

Any request that goes to your app will be run through that pipeline first. You don’t have to explicitly call call/2.

Edit: actually my explanation is missing some details. Before going through the pipeline, the connection from first arrives at the Endpoint and went through a series of Plugs before going to the Router and, subsequently, the pipeline.

Does that make sense?

Actually closer to this (still not perfectly accurate, but keeps the init in this idea):

conn # the initial conn handled by cowboy, passed on to Phoenix
|> accepts(["html"]))
|> fetch_session()
|> fetch_flash()
|> protect_from_forgery()
|> put_secure_browser_headers()
|> Rumbl.Auth.call(Rumbl.Auth.init(repo: Rumbl.Repo))

But yeah, it is the ‘pipeline’ call that does the plugs there. In something like Endpoint the plugs are run via the plug builder that builds the ‘state’.

And to answer this:

Those other functions are pure functions. They don’t depend on call/2 whatsoever and, as you said, are isolated from one another.

It might be nice to remember that even though Rumbl.Auth is a module plug, it is also a module. In Elixir (and many other FP languages), a module is usually just a collection of functions.

The login/2, login_by_username_and_pass/4, etc. are plain functions. Although login/2 fulfils the contract of a function plug, it is not used as such. They are called with Rumbl.Auth.login(user), and so on.

The reason that those functions are in the Rumbl.Auth module is most likely because as the name implies, they deal with user authentication, therefore it makes sense to group them under an Auth module.

Lots of great info guys - thank you so much. It makes a lot more sense to me - modules plugs are still Elixir modules - so any other functions within them are isolated from init/1 and call/2 (correct?), but they’re still used to contain like functionality, such as authentication.

Along with that, the plug will get executed (call/2 init/1 on startup) on each and every request since I plugged it into the Browser Pipeline. That happens when Cowboy handles it as @hubertlepicki pointed out.

It’s all becoming a little clearer. Thanks guys, still learning as I read through your posts.

A small correction: init is called when the app compiles.

Thanks Jose! Great book, much appreciated. Where do I go to submit any errors / suggestions I find?

I believe it is here: https://pragprog.com/titles/phoenix/errata