# `Decree.Store.Notifications.Connection`
[🔗](https://github.com/sparkle-space/decree/blob/v0.1.0/lib/decree/store/notifications/connection.ex#L1)

**Temporary.** This module stands in for `Postgrex.Notifications` because Postgrex
0.22.4, the newest release on Hex, drops a notification that arrives while its idle ping
runs. The fix, elixir-ecto/postgrex#795 (commit `bd402a5310`), is in no release yet.
Remove this module, and go back to `Postgrex.Notifications`, at the first Hex Postgrex
release that contains `bd402a5310` (expected to be 0.23). sparkle-space/sparklespace#8532
tracks that clean-up. Before removing it, check that the release's
`Postgrex.Notifications` also covers what 0.22.4's lacks besides the ping:
  * it answers a failed `LISTEN` `{:ok, ref}` and never listens on that channel;
  * a `LISTEN` it issues on a reconnect that loses its connection strands it: 0.22.4's
    `SimpleConnection` drops the reconnect after a query issued from `handle_connect/1`
    disconnects;
  * a query waits for its answer with no timeout.

The event store's `LISTEN` connection, a `Postgrex.SimpleConnection` that listens on one
channel and sends each notification to the `Decree.Store.Notifications.Listener` as
`{:notification, pid, nil, channel, payload}`.

On every connect it listens by itself once the Listener is registered; until then the
Listener's `listen/2` call issues the `LISTEN`. `listen/2` answers `:ok` once the
connection listens, and `:eventually` while it is disconnected, or when the `LISTEN` it
issued fails or is lost to a disconnect.

The connection sends no idle ping. While it listens it runs `SELECT 1` every
`:idle_interval` milliseconds (default 5000), and a notification that arrives during
that query is delivered. Every query it issues is bounded by `:timeout` (default
15000): a query still unanswered then kills the process. `:infinity` bounds none, as for
the store's other queries. A query that fails ends the
process with a `{:shutdown, reason}` exit. The process that started it (the store's
`MonitoredServer`) starts it again.

# `listen`

```elixir
@spec listen(GenServer.server(), timeout()) :: :ok | :eventually
```

Asks the connection to listen. `:ok` once it listens, `:eventually` when it will listen
after it reconnects.

# `start_link`

---

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