# `MishkaCmsCore.ExtensionRouter`
[🔗](https://github.com/mishka-group/mishka_cms_core/blob/v0.0.5-alpha.13/lib/mishka_cms_core/extension_router.ex#L5)

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: []
    end

In 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
    end

## API 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)
    end

Every 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`, `/fonts` and `/images`, and the `/live`, `/ws` and `/phoenix` sockets;
  * 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: `/:lang` alone, `/:lang/:slug` and
    `/:lang/auth` are refused;
  * has the verb and path of another route in the list, of any extension; captures are compared by
    place, not name, so `/feed/:a` and `/feed/:b` are one route;
  * is a `:live` route, which is a page and belongs in `routes(: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
    ]

# `route`

```elixir
@type route() ::
  {:live, String.t(), module(), atom()}
  | {:live, String.t(), module(), atom(), keyword()}
  | {:get | :post | :put | :patch | :delete, String.t(), module(), atom()}
  | {:get | :post | :put | :patch | :delete, String.t(), module(), atom(),
     keyword()}
```

# `route_type`

```elixir
@type route_type() :: :admin | :admin_standalone | :public | :api
```

# `routes`

```elixir
@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.

# `extension_routes`
*macro* 

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.

# `host_prefixes`

```elixir
@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).

# `route_accepts`

```elixir
@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:

```elixir
import MishkaCmsCore.ExtensionRouter

pipeline :browser do
  plug :route_accepts, ["html"]
  # ...
end
```

A 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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
