Behaviour and macro for extensions to define their routes.
Extensions implement this behaviour to register their admin, public, and API routes.
The main CMS router uses extension_routes/1 macro to load all extension routes.
Usage
In your extension:
defmodule MishkaBlogWeb.Routes do
@behaviour MishkaCmsCore.ExtensionRouter
@impl true
def routes(:admin) do
[
{:live, "/blog/posts", MishkaBlogWeb.Live.Admin.PostLive, :index}
]
end
def routes(_), do: []
endIn your main router:
import MishkaCmsCore.ExtensionRouter
scope "/admin/dashboard" do
pipe_through [:browser, :require_authenticated_user]
live_session :admin do
extension_routes(:admin)
end
live_session :admin_standalone do
extension_routes(:admin_standalone)
end
endAPI routes
routes(:api) is for what an extension answers that is not a page: a feed, a JSON endpoint, a
file it writes. The host mounts them before its catch-all, through a pipeline that resolves the
site and closes an offline one, with no CSRF check and no sign-in:
pipeline :extension_api do
plug :route_accepts, ["json"]
plug :fetch_session
plug :put_secure_browser_headers
plug MishkaCmsCore.Runtime.Plugs.SiteLookupPlug
# the host's offline gate
end
scope "/" do
pipe_through :extension_api
extension_routes(:api)
endEvery extension's API routes are put in a scope of their own behind
MishkaCmsCore.Runtime.Plugs.ExtensionGatePlug, so a site that switched the extension off answers
them with a 404 and no session cookie is ever written. A route that answers something other than
JSON names it under private: %{accepts: ...} (see route_accepts/2).
A POST, PUT, PATCH or DELETE to one reads an empty session: the pipeline has no CSRF check,
so the gate will not let a form on another site act as the visitor signed in here. A route that
takes those methods authenticates the request itself, as a webhook checks its signature.
What a route may claim
The :api routes are mounted before every host route but /admin/dashboard, /install and the
API's own, and the first route that matches answers, so a careless path takes addresses the host
owns. The router refuses to compile, naming the extension and the route, when a routes(:api)
route:
- starts with a segment the host answers itself, one of
host_prefixes/0:/admin,/api,/auth,/gql,/install,/_preview,/_health,/dev,/oban, the static/uploads,/assets,/fontsand/images, and the/live,/wsand/phoenixsockets; - is
/, or starts with a capture (/:slug,/*rest), which takes every address. The language capture is the exception (MishkaCmsCore.Runtime.Languages.capture/0,/:lang/feed) when a fixed segment that is not the host's follows it:/:langalone,/:lang/:slugand/:lang/authare refused; - has the verb and path of another route in the list, of any extension; captures are compared by
place, not name, so
/feed/:aand/feed/:bare one route; - is a
:liveroute, which is a page and belongs inroutes(:public).
routes(:public) is mounted in the host's page scope before its preview, sign-in and catch-all
routes, so the capture, / and duplicate checks hold for it too. It may start with a host segment
and list :live routes: that list is where an extension serves under the host's addresses on
purpose (/admin/language, /assets/css/:site/:hash, /_preview/doc-example/...).
In config.exs:
config :mishka_cms, :extensions, [
MishkaBlogWeb,
MishkaDocumentWeb
]
Summary
Callbacks
Returns the routes for the given type.
Functions
Macro to inject all extension routes into your router.
The top-level path segments the host answers itself, which no routes(:api) route may start with
(see "What a route may claim" in the moduledoc).
Phoenix.Controller.accepts/2 for a pipeline that pages and files share: the formats the matched
route names under its :accepts private, or formats for a route that names none.
Types
@type route_type() :: :admin | :admin_standalone | :public | :api
Callbacks
@callback routes(route_type()) :: [route()]
Returns the routes for the given type.
Types:
:admin- Admin dashboard routes:admin_standalone- Admin routes that need a document of their own (see below):public- Public-facing routes:api- API routes
When a route belongs in :admin_standalone
Only when the page needs something in <head> that the rest of the admin does not.
The root layout decides <head> from the LiveView's assigns, and it renders once per HTTP
response. A live navigation does not produce one: the destination LiveView runs inside the
document the SOURCE page built, with the source page's head. A page whose stylesheets, scripts or
meta tags differ from its neighbours' therefore arrives half-dressed, with no error anywhere —
the page builder reached this way lost its Tailwind JIT and the shim that nonces what it creates,
and its code editor opened unstyled.
:admin_standalone routes are emitted into a live_session of their own, and LiveView will not
live-navigate across a live_session boundary: arriving is a full page load, and so is leaving,
which also sheds whatever the page installed. Navigation BETWEEN two routes in this list stays
live, which is what makes it the right home for a group of pages that share a head.
So an admin page links INTO one with href (or redirect/2), not navigate (or
push_navigate/2). A navigate link still arrives, but only after LiveView has tried the live
navigation and refused it, logging "redirecting across live_sessions" on the server and
"unauthorized live_redirect" in the browser.
Everything else belongs in :admin. The boundary costs a page load in each direction, and a page
that is dressed like the rest of the admin has nothing to buy with it.
Functions
Macro to inject all extension routes into your router.
Extensions are configured in :mishka_cms, :extensions.
This macro is evaluated at compile time - no runtime overhead.
@spec host_prefixes() :: [String.t()]
The top-level path segments the host answers itself, which no routes(:api) route may start with
(see "What a route may claim" in the moduledoc).
@spec route_accepts(Plug.Conn.t(), [String.t()]) :: Plug.Conn.t()
Phoenix.Controller.accepts/2 for a pipeline that pages and files share: the formats the matched
route names under its :accepts private, or formats for a route that names none.
Plug it in place of plug :accepts, formats, imported from this module:
import MishkaCmsCore.ExtensionRouter
pipeline :browser do
plug :route_accepts, ["html"]
# ...
endA route answering a file of another kind names what it answers, and every other route keeps
formats — so /robots.txt answers Accept: text/plain while a page asked the same is still
refused with a 406:
{:get, "/robots.txt", MyExtWeb.RobotsController, :show,
private: %{accepts: ["html", "txt", "xml"]}}A route serving a stored file as it is names :any, and answers whatever Accept it is sent, as
Plug.Static does — a crawler asks for a gzipped sitemap as application/x-gzip, which no format
names:
{:get, "/sitemap-:file", MyExtWeb.SitemapController, :file, private: %{accepts: :any}}A route's private is on the conn before its pipeline runs, so this reads the route being served.