Caracola.Push (Caracola v0.1.0-rc.1)

Copy Markdown View Source

Push notifications for mobile clients (RFC 8599), on top of Caracola.Registrar: devices that cannot keep a connection open are woken up with a push notification (APNs, FCM...) when they have a request, and get it after they register again.

defmodule MyProxy do
  use Malla.Service,
    plugins: [Caracola.Push],
    sip: [listen: "sip:all:5060"],
    push: [providers: ["apns", "fcm"], timeout: 10_000]

  defcb sip_route(_scheme, _user, "example.com", req, call),
    do: Caracola.Push.route(req, call, [:record_route])

  defcb sip_push_send(push, _req, _service) do
    MyApp.Apns.send(push.prid, push.param, push.purr)
  end
end

Registration

Devices register Contacts with the pn-provider, pn-prid (the push token) and pn-param URI parameters. The registrar identifies them by their provider and token, instead of by address (which changes when the device wakes up), and answers with a Feature-Caps header with the +sip.pns (the provider) and +sip.pnspurr (an identifier of the registration) indicators. Providers not in :providers are rejected with 555 (Push Notification Service Not Supported).

Routing

route/3 routes a request to the registered contacts of its Request-URI. If some of them have push parameters, a push notification is sent to each of them (with sip_push_send/3, that the service implements to talk to the push services), and the request waits until they register again, or until the :timeout. Then it is proxied to the other contacts and to the refreshed ones; if there are none, it is answered with 480. The call process does not wait: the request is routed later (see Caracola.route/2), so it can be cancelled meanwhile.

Sending the notifications is up to the service: Caracola does not talk to APNs or FCM. sip_push_send/3 gets a map with the :provider, :prid, :param, :purr, the :aor and the registered :contact, and returns :ok or {:error, reason}.

Configuration

Under the :push key:

  • :providers - supported push providers (default ["apns", "fcm", "webpush"]).
  • :timeout - milliseconds to wait for the devices to register again (default 10000).

Summary

Types

The push parameters (RFC 8599) of a registered contact: provider, token (prid), purr, AOR and contact.

Functions

The push parameters of a Contact (RFC 8599 §4.1), or nil if it has none.

A sip_route/5 result for a request to a registered user: the contacts registered for its Request-URI, after waking up the devices with push notifications (see the module documentation). proxy_opts are the options for proxying.

Types

push()

@type push() :: %{
  provider: String.t(),
  prid: String.t(),
  param: String.t() | nil,
  purr: String.t(),
  aor: Caracola.Registrar.aor(),
  contact: Caracola.URI.t()
}

The push parameters (RFC 8599) of a registered contact: provider, token (prid), purr, AOR and contact.

Functions

push(contact, aor)

@spec push(Caracola.URI.t(), Caracola.Registrar.aor()) :: push() | nil

The push parameters of a Contact (RFC 8599 §4.1), or nil if it has none.

iex> {:ok, uri} = Caracola.URI.parse_one("<sip:a@10.0.0.1;pn-provider=apns;pn-prid=tok;pn-param=t.app>")
iex> push = Caracola.Push.push(uri, {:sip, "a", "example.com"})
iex> {push.provider, push.prid, push.param}
{"apns", "tok", "t.app"}

route(req, call, proxy_opts \\ [])

@spec route(Caracola.Message.t(), Caracola.Call.t(), list()) :: term()

A sip_route/5 result for a request to a registered user: the contacts registered for its Request-URI, after waking up the devices with push notifications (see the module documentation). proxy_opts are the options for proxying.