Provides an configuration endpoint for use in your Phoenix applications.

Rather than configuring your Electric Typescript client directly, you instead configure a route in your application with a pre-configured Electric.Client.ShapeDefinition and then retreive the URL and other configuration for that shape from your client via a request to your Phoenix application.

In your Phoenix application, add a route to Electric.Phoenix.Plug specifying a particular shape:

defmodule MyAppWeb.Router do
  scope "/shapes" do
    pipe_through :browser

    get "/todos", Electric.Phoenix.Plug,
      shape: Electric.Client.shape!("todos", where: "visible = true")
  end
end

Then in your client code, you retrieve the shape configuration directly from the Phoenix endpoint:

import { ShapeStream } from '@electric-sql/client'

const endpoint = `https://localhost:4000/shapes/todos`
const response = await fetch(endpoint)
const config = await response.json()

// The returned `config` has all the information you need to subscribe to
// your shape
const stream = new ShapeStream(config)

stream.subscribe(messages => {
  // ...
})

You can add additional authentication/authorization for shapes using Phoenix's pipelines or other plug calls.

Plug.Router

For pure Plug-based applications, you can use Plug.Router.forward/2:

defmodule MyRouter do
  use Plug.Router

  plug :match
  plug :dispatch

  forward "/shapes/items",
    to: Electric.Phoenix.Plug,
    shape: Electric.Client.shape!("items")

  match _ do
    send_resp(conn, 404, "oops")
  end
end

Parameter-based shapes

As well as defining fixed-shapes for a particular url, you can request shape configuration using parameters in your request:

defmodule MyAppWeb.Router do
  scope "/" do
    pipe_through :browser

    get "/shape", Electric.Phoenix.Plug, []
  end
end

import { ShapeStream } from '@electric-sql/client'

const endpoint = `https://localhost:4000/shape?table=items&namespace=public&where=visible%20%3D%20true`
const response = await fetch(endpoint)
const config = await response.json()

// as before

The parameters are:

• table - The Postgres table name (required).
• namespace - The Postgres schema if not specified defaults to public.
• where - The where clause to filter items from the shape.

Custom Authentication

The Electric.Client allows for generating authentication headers via it's authenticator configuration but if you want to include parameters from the request in the authentication tokens, for example including the currently logged in user id, then you can set an authenticator directly in the Electric.Phoenix.Plug configuration.

First you must define a function that accepts the %Plug.Conn{} of the request, the %Electric.Client.ShapeDefinition{} of the endpoint and some (optional) config and returns a map of additional request headers:

defmodule MyAuthModule do
  def shape_auth_headers(conn, shape, _opts \\ []) do
    user_id = conn.assigns.user_id
    signer = Joken.Signer.create("HS256", "my-deep-secret")
    claims = %{
      user_id: user_id,
      table: [shape.namespace, shape.table],
      where: shape.where
    }
    token = Joken.generate_and_sign!(Joken.Config.default_claims(), claims, signer)
    %{"authorization" => "Bearer #{token}"}
  end
end

Now configure the Shape configuration endpoint to use your authentication function:

forward "/shapes/tasks/:project_id",
  to: Electric.Plug,
  authenticator: {MyAuthModule, :shape_auth_headers, _opts = []},
  shape: [
    from(t in Task, where: t.active == true),
    project_id: :project_id
  ]

Or you can use a capture:

forward "/shapes/tasks/:project_id",
  to: Electric.Plug,
  authenticator: &MyAuthModule.shape_auth_headers/2,
  shape: [
    from(t in Task, where: t.active == true),
    project_id: :project_id
  ]