Observer.Web.Router (Observer Web v0.1.5)

Provides mount points for the Web dashboard with customization.

Customizing with a Resolver Callback Module

Implementing a Observer.Web.Resolver callback module allows you to customize the dashboard per-user, i.e. setting access controls.

As a simple example, let's define a module that makes the dashboard read only:

defmodule MyApp.Resolver do
  @behaviour Observer.Web.Resolver

  @impl true
  def resolve_access(_user), do: :read_only
end

Then specify MyApp.Resolver as your resolver:

scope "/" do
  pipe_through :browser

  observer_dashboard "/observer", resolver: MyApp.Resolver
end

See the Observer.Web.Resolver docs for more details.

Running Multiple Dashboards

A single dashboard may connect to any number of running Observer instances. However, it's also possible to change the default instance via the :observer_name option. For example, given two configured Observer instances, Observer and MyAdmin.Observer, you can then mount both dashboards in your router:

scope "/" do
  pipe_through :browser

  observer_dashboard "/observer", observer_name: Observer, as: :observer_dashboard
  observer_dashboard "/admin/observer", observer_name: MyAdmin.Observer, as: :observer_admin_dashboard
end

Note that the default name is Observer or the first found instance, setting observer_name: Observer in the example above was purely for demonstration purposes.

On Mount Hooks

You can provide a list of hooks to attach to the dashboard's mount lifecycle. Additional hooks are prepended before Observer Web's own Authentication. For example, to run a user-fetching hook and an activation checking hook before mount:

scope "/" do
  pipe_through :browser

  observer_dashboard "/observer", on_mount: [MyApp.UserHook, MyApp.ActivatedHook]
end

Customizing the Socket Connection

Applications that use a live socket other than "/live" can override the default socket path in the router. For example, if your live socket is hosted at /observer_live:

socket "/observer_live", Phoenix.LiveView.Socket

scope "/" do
  pipe_through :browser

  observer_dashboard "/observer", socket_path: "/observer_live"
end

If your application is hosted in an environment that doesn't support websockets you can use longpolling as an alternate transport. To start, make sure that your live socket is configured for longpolling:

socket "/live", Phoenix.LiveView.Socket,
  longpoll: [connect_info: [session: @session_options], log: false]

Then specify "longpoll" as your transport:

scope "/" do
  pipe_through :browser

  observer_dashboard "/observer", transport: "longpoll"
end

Content Security Policy

To secure the dashboard, or comply with an existing CSP within your application, you can specify nonce keys for images, scripts and styles.

You'll configure the CSP nonce assign key in your router, where the dashboard is mounted. For example, to use a single nonce for all three asset types:

observer_dashboard("/observer", csp_nonce_assign_key: :my_csp_nonce)

That instructs the dashboard to extract a generated nonce from the assigns map on the plug connection, at the :my_csp_nonce key.

Instead, you can specify different keys for each asset type:

observer_dashboard("/observer",
  csp_nonce_assign_key: %{
    img: :img_csp_nonce,
    style: :style_csp_nonce,
    script: :script_csp_nonce
  }
)

Summary

Functions

observer_dashboard(path, opts \\ [])

Defines an observer dashboard route.

Functions

observer_dashboard(path, opts \\ [])

(macro)

Defines an observer dashboard route.

It requires a path where to mount the dashboard at and allows options to customize routing.

Options

  • :as — override the route name; otherwise defaults to :observer_dashboard

  • :on_mount — declares additional module callbacks to be invoked when the dashboard mounts

  • :observer_name — name of the Observer instance the dashboard will use for configuration and notifications, defaults to Observer or the first instance that can be found.

  • :resolver — an Observer.Web.Resolver implementation used to customize the dashboard's functionality.

  • :socket_path — a phoenix socket path for live communication, defaults to "/live".

  • :transport — a phoenix socket transport, either "websocket" or "longpoll", defaults to "websocket".

  • :csp_nonce_assign_key — CSP (Content Security Policy) keys used to authenticate image, style, and script assets by pulling a generated nonce out of the connection's assigns map. May be nil, a single atom, or a map of atoms. Defaults to nil.

Examples

Mount an observer dashboard at the path "/observer":

defmodule MyAppWeb.Router do
  use Phoenix.Router

  import Observer.Web.Router

  scope "/", MyAppWeb do
    pipe_through [:browser]

    observer_dashboard "/observer"
  end
end

References: