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
endRegistration
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
@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
@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"}
@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.