# `Caracola.Push`
[🔗](https://github.com/netkubes/caracola/blob/v0.1.0-rc.1/lib/caracola/push.ex#L1)

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

# `push`

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

# `push`

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

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

---

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