Francis Thinking

<EXTREMELY-IMPORTANT>
Invoke this skill BEFORE doing ANYTHING else on a Francis task — including exploring the codebase.

Francis macros generate hidden modules at compile time. Exploring first means you won't know what to look for, and you'll miss critical safety rules (HTML escaping, SSE directionality, redirect safety). </EXTREMELY-IMPORTANT>

The Rule

Francis task → Read this skill FIRST → Then explore → Then write code

Even "where is the route defined?" needs this skill first — get/ws/sse macros generate hidden modules; grepping for the handler won't find them.

STOP: The One Footgun That Causes XSS

# WRONG — html/2 does NOT escape. XSS vulnerability:
html(conn, "<p>Hello #{user_input}</p>")

# WRONG — safe_html/2 escapes the ENTIRE string, including your <p> tags:
safe_html(conn, "<p>Hello #{user_input}</p>")
# renders: &lt;p&gt;Hello user input&lt;/p&gt;  — raw text, not HTML

# RIGHT — escape only the interpolation, keep your trusted markup:
html(conn, "<p>Hello #{Francis.HTML.escape(user_input)}</p>")

# RIGHT — safe_html/2 is for rendering untrusted content as escaped plain text:
safe_html(conn, user_input)

The Unified Event Model

All three transports share the same shape:

HTTP:   fn conn         -> response
WS/SSE: fn event, socket -> reply

Return value dispatch (HTTP handlers):

Status is 200 for route macros, 404 for unmatched/1. Return Plug.Conn to override either.

Reply value dispatch (WS/SSE handlers):

{:reply, {:binary, bytes}} is the only way to send binary WebSocket frames.

HTTP Routes

defmodule MyApp do
  use Francis

  get("/", fn _conn -> "hello" end)
  get("/users/:id", fn conn -> "user #{conn.params["id"]}" end)
  post("/users", fn conn -> conn.body_params end)
  put("/users/:id", fn conn -> %{updated: conn.params["id"]} end)
  delete("/users/:id", fn conn -> %{deleted: conn.params["id"]} end)
  patch("/users/:id", fn conn -> conn.body_params end)

  unmatched(fn _conn -> "not found" end)
end

unmatched/1 must be declared last — it shadows any routes declared after it.

Accessing data:

• Path params + query string: conn.params["id"]
• Request body: conn.body_params — requires a matching content-type header (application/json, application/x-www-form-urlencoded, multipart/form-data). Without it, body_params is %{}. Body params are also merged into conn.params after parsing.

Response helpers (auto-imported via Francis.ResponseHandlers):

json(conn, %{ok: true})
json(conn, 201, %{id: 1})
text(conn, "hello")
html(conn, "<h1>Trusted static HTML only</h1>")
safe_html(conn, user_input)         # escapes the whole string as plain text
safe_html(conn, 201, user_input)
redirect(conn, "/new")              # relative paths only
redirect(conn, 301, "/new")

HEAD requests — no head/2 macro. Plug.Head (installed by default) converts HEAD requests to GET automatically.

WebSockets

ws("/chat/:room", fn
  :join, socket ->
    {:reply, %{type: "welcome", room: socket.params["room"]}}

  {:received, msg}, socket ->
    {:reply, "[#{socket.params["room"]}] #{msg}"}

  {:close, _reason}, _socket ->
    :ok
end)

ws("/live", handler_fn, heartbeat_interval: 10_000, timeout: 120_000)

Events:

• :join — client connected
• {:received, message} — client sent a text message over the wire
• {:close, reason} — connection closed

:join and {:close, _} are optional — succeed silently if unmatched. Easy to lose cleanup logic on close.

Socket state:

%{
  id: "64-character hex string (32 random bytes)",
  transport: pid,
  path: "/chat/general",
  params: %{"room" => "general"}
}

send(socket.transport, msg) for WS bypasses the handler entirely. Messages are forwarded directly to the client. They do NOT pass through your {:received, _} clause. Store socket.transport to broadcast from other processes.

Options:

• :heartbeat_interval (default: 30_000 ms) — ping frames; nil to disable
• :timeout (default: 60_000 ms) — idle connection timeout
• :max_frame_size (default: 65_536 bytes) — memory protection

Module name collision: each ws/3 call generates a module named from the route path. Two routes with structurally identical paths generate the same module name and silently overwrite each other.

Server-Sent Events (SSE)

SSE is server→client only. The SSE client has no upstream channel. All events the handler receives come from other processes via send(socket.transport, msg).

sse("/events", fn
  :join, socket ->
    {:reply, %{event: "connected", data: %{id: socket.id}}}

  {:received, msg}, socket ->
    {:reply, msg}

  {:close, _reason}, _socket ->
    :ok
end)

sse("/stream", handler_fn, keepalive_interval: 30_000)

send(socket.transport, msg) for SSE routes through the handler's {:received, msg} clause — unlike WS where it bypasses the handler. You can transform or filter messages before they reach the client.

Real close reasons include :chunk_failed (client disconnected) and :keepalive_failed. Use {:close, _} to clean up subscriptions.

SSE event formats:

{:reply, "plain text"}
# => data: plain text\n\n

{:reply, %{status: "ok"}}
# => data: {"status":"ok"}\n\n

{:reply, %{event: "user_joined", data: %{name: "Alice"}, id: "42", retry: 5000}}
# => event: user_joined\ndata: {...}\nid: 42\nretry: 5000\n\n

Options:

• :keepalive_interval (default: 15_000 ms) — comment line to keep connection alive; nil to disable

WS vs SSE — critical difference: