docs: idiomatic Elixir and Phoenix patterns with source citations
Extracted patterns, conventions, and code smells directly from the Elixir and Phoenix source code with file path and line number citations. Covers: GenServer, error handling, data transforms, process design, testing, documentation, typespecs, macros, behaviours, module organization, Phoenix-specific patterns, framework deviations, and anti-patterns.
This commit is contained in:
Aaron Weiker
@@ -0,0 +1,235 @@
|
||||
# Phoenix Patterns
|
||||
|
||||
Patterns specific to Phoenix extracted from the framework source code.
|
||||
|
||||
## 1. Endpoint as Supervision Tree Root + Plug Pipeline
|
||||
|
||||
**Source:** `lib/phoenix/endpoint.ex:1-40` (moduledoc)
|
||||
|
||||
> The endpoint is the boundary where all requests to your web application start.
|
||||
> It is also the interface your application provides to the underlying web servers.
|
||||
>
|
||||
> Overall, an endpoint has three responsibilities:
|
||||
> - to provide a wrapper for starting and stopping the endpoint as part of a supervision tree
|
||||
> - to define an initial plug pipeline for requests to pass through
|
||||
> - to host web specific configuration for your application
|
||||
|
||||
**Source:** `lib/phoenix/endpoint.ex:408-418` (`__using__` macro)
|
||||
|
||||
```elixir
|
||||
defmacro __using__(opts) do
|
||||
quote do
|
||||
@behaviour Phoenix.Endpoint
|
||||
unquote(config(opts))
|
||||
unquote(pubsub())
|
||||
unquote(plug())
|
||||
unquote(server())
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
The endpoint is four things composed together:
|
||||
1. **Config** — compile-time and runtime configuration
|
||||
2. **PubSub** — subscribe/broadcast interface
|
||||
3. **Plug** — request pipeline (via `Plug.Builder`)
|
||||
4. **Server** — supervision and HTTP server management
|
||||
|
||||
**Why:** The Endpoint is a supervisor, a plug pipeline, AND a configuration host — all in one module. This unification means one place to configure and start the entire web layer.
|
||||
|
||||
**Anti-pattern:** Splitting endpoint responsibilities across multiple unrelated modules — Phoenix deliberately consolidates the "boundary" concept.
|
||||
|
||||
---
|
||||
|
||||
## 2. Router: Compile-Time Route Optimization
|
||||
|
||||
**Source:** `lib/phoenix/router.ex:109-123` (Why the macros? info block)
|
||||
|
||||
> We use macros for two purposes:
|
||||
>
|
||||
> * They define the routing engine, used on every request, to choose which
|
||||
> controller to dispatch the request to. Thanks to macros, Phoenix compiles
|
||||
> all of your routes to a single case-statement with pattern matching rules,
|
||||
> which is heavily optimized by the Erlang VM
|
||||
>
|
||||
> * For each route you define, we also define metadata to implement `Phoenix.VerifiedRoutes`.
|
||||
|
||||
**Source:** `lib/phoenix/router.ex:280` (route accumulation)
|
||||
|
||||
```elixir
|
||||
Module.register_attribute(__MODULE__, :phoenix_routes, accumulate: true)
|
||||
```
|
||||
|
||||
**Why:** Routes are defined with macros that accumulate route data at compile time. At `@before_compile`, all routes are compiled into a single pattern-match dispatch function. This is O(1) routing, not O(n) list scanning.
|
||||
|
||||
**Anti-pattern:** Runtime route tables (like maps or lists that are scanned per-request) — compile-time pattern matching is orders of magnitude faster.
|
||||
|
||||
---
|
||||
|
||||
## 3. Pipeline and `pipe_through` for Request Processing
|
||||
|
||||
**Source:** `lib/phoenix/router.ex:230-260` (Pipelines and plugs section)
|
||||
|
||||
```elixir
|
||||
pipeline :browser do
|
||||
plug :fetch_session
|
||||
plug :accepts, ["html"]
|
||||
end
|
||||
|
||||
scope "/" do
|
||||
pipe_through :browser
|
||||
# routes
|
||||
end
|
||||
```
|
||||
|
||||
**Why:** Pipelines are named, composable groups of plugs. Routes declare which pipelines they pass through. This separates concerns:
|
||||
- Pipeline definition (what transformations exist)
|
||||
- Route definition (which routes use which pipelines)
|
||||
|
||||
**Anti-pattern:** Putting plug logic directly in controllers or duplicating plug chains across routes.
|
||||
|
||||
---
|
||||
|
||||
## 4. Controller as Thin Dispatch Layer
|
||||
|
||||
**Source:** `lib/phoenix/controller.ex:28-45` (moduledoc examples)
|
||||
|
||||
```elixir
|
||||
defmodule MyAppWeb.UserController do
|
||||
use MyAppWeb, :controller
|
||||
|
||||
def show(conn, %{"id" => id}) do
|
||||
user = Repo.get(User, id)
|
||||
render(conn, :show, user: user)
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
Controllers:
|
||||
- Pattern match on params (destructure what you need)
|
||||
- Call domain logic (the Repo/context layer)
|
||||
- Render the result
|
||||
|
||||
**Source:** `lib/phoenix/controller.ex:1-3` (imports)
|
||||
|
||||
```elixir
|
||||
defmodule Phoenix.Controller do
|
||||
import Plug.Conn
|
||||
alias Plug.Conn.AlreadySentError
|
||||
require Logger
|
||||
```
|
||||
|
||||
**Why:** Controllers import `Plug.Conn` for connection manipulation. They're pluggable themselves — a controller IS a plug. The action is just the last step in the plug pipeline.
|
||||
|
||||
**Anti-pattern:** Fat controllers with business logic — controllers should delegate to context modules.
|
||||
|
||||
---
|
||||
|
||||
## 5. Channel as GenServer with Topic-Based Routing
|
||||
|
||||
**Source:** `lib/phoenix/channel.ex:1-20` (topic pattern)
|
||||
|
||||
```elixir
|
||||
channel "room:*", MyAppWeb.RoomChannel
|
||||
```
|
||||
|
||||
Then in the channel:
|
||||
```elixir
|
||||
def join("room:lobby", _payload, socket) do
|
||||
{:ok, socket}
|
||||
end
|
||||
|
||||
def join("room:" <> room_id, _payload, socket) do
|
||||
{:ok, socket}
|
||||
end
|
||||
```
|
||||
|
||||
**Source:** `lib/phoenix/channel.ex:476-479` (channels are GenServers)
|
||||
|
||||
```elixir
|
||||
def start_link(triplet) do
|
||||
GenServer.start_link(Phoenix.Channel.Server, triplet,
|
||||
hibernate_after: @phoenix_hibernate_after
|
||||
)
|
||||
end
|
||||
```
|
||||
|
||||
**Why:** Each channel join creates a process. Pattern matching on the topic string provides natural routing. The GenServer backing means channels get supervision, hibernation, and all OTP semantics.
|
||||
|
||||
**Anti-pattern:** Managing channel state in shared ETS or external state — each channel IS its own process with its own state.
|
||||
|
||||
---
|
||||
|
||||
## 6. PubSub Integration via Endpoint
|
||||
|
||||
**Source:** `lib/phoenix/endpoint.ex:440-475` (pubsub macro)
|
||||
|
||||
```elixir
|
||||
def subscribe(topic, opts \\ []) when is_binary(topic) do
|
||||
Phoenix.PubSub.subscribe(pubsub_server!(), topic, opts)
|
||||
end
|
||||
|
||||
def broadcast(topic, event, msg) do
|
||||
Phoenix.Channel.Server.broadcast(pubsub_server!(), topic, event, msg)
|
||||
end
|
||||
|
||||
defp pubsub_server! do
|
||||
config(:pubsub_server) ||
|
||||
raise ArgumentError, "no :pubsub_server configured for #{inspect(__MODULE__)}"
|
||||
end
|
||||
```
|
||||
|
||||
**Why:** PubSub is wired through the endpoint — `MyAppWeb.Endpoint.broadcast!("topic", "event", payload)`. The endpoint knows its pubsub server from config; channels broadcast through it transparently.
|
||||
|
||||
**Anti-pattern:** Passing PubSub server names around manually — the endpoint already knows and exposes the interface.
|
||||
|
||||
---
|
||||
|
||||
## 7. Socket as Authentication Boundary
|
||||
|
||||
**Source:** `lib/phoenix/socket.ex` (connect callback pattern)
|
||||
|
||||
```elixir
|
||||
defmodule MyAppWeb.UserSocket do
|
||||
use Phoenix.Socket
|
||||
|
||||
channel "room:*", MyAppWeb.RoomChannel
|
||||
|
||||
def connect(params, socket, _connect_info) do
|
||||
{:ok, assign(socket, :user_id, params["user_id"])}
|
||||
end
|
||||
|
||||
def id(socket), do: "users_socket:#{socket.assigns.user_id}"
|
||||
end
|
||||
```
|
||||
|
||||
**Why:** Authentication happens ONCE at socket connection. All channels on that socket inherit the authenticated identity. `id/1` enables targeted disconnection — `Endpoint.broadcast("users_socket:123", "disconnect", %{})`.
|
||||
|
||||
**Anti-pattern:** Authenticating in every `join/3` callback instead of at the socket level.
|
||||
|
||||
---
|
||||
|
||||
## 8. Plug Pattern: `init/1` + `call/2`
|
||||
|
||||
**Source:** `lib/phoenix/router/route.ex:51-58`
|
||||
|
||||
```elixir
|
||||
@doc "Used as a plug on forwarding"
|
||||
def init(opts), do: opts
|
||||
|
||||
@doc "Used as a plug on forwarding"
|
||||
def call(%{path_info: path, script_name: script} = conn, {fwd_segments, plug, opts}) do
|
||||
new_path = path -- fwd_segments
|
||||
{base, ^new_path} = Enum.split(path, length(path) - length(new_path))
|
||||
conn = %{conn | path_info: new_path, script_name: script ++ base}
|
||||
conn = plug.call(conn, plug.init(opts))
|
||||
%{conn | path_info: path, script_name: script}
|
||||
end
|
||||
```
|
||||
|
||||
**Why:** The Plug specification splits work into:
|
||||
- `init/1` — compile-time setup (called once, result cached)
|
||||
- `call/2` — runtime execution (called per-request, must be fast)
|
||||
|
||||
This is Phoenix's fundamental composition pattern. Everything is a plug.
|
||||
|
||||
**Anti-pattern:** Doing expensive setup work in `call/2` instead of `init/1` — it runs on every request.
|
||||
Reference in New Issue
Block a user