Announce through PostgreSQL, so that pages open on any server hear about their user’s notifications, whether or not the servers are connected as an Erlang cluster. Add it to the app’s supervisor on every server, after the database pool and before the server:

supervisor.new(supervisor.OneForOne)
|> supervisor.add(pool)
|> supervisor.add(notifications.across_servers(notifier))
|> supervisor.add(jobs.supervised(runner))
|> supervisor.add(howdy.supervised(app(notifier)))

It listens on a connection of its own, opened with the pool’s settings; see across_servers_via for a pool howdy/database/postgres did not open. One runs per node. On SQLite, which only one server can use, it changes nothing. While it is not running, such as when it restarts, announcements go through the cluster as they do without it. What is announced while a server’s listening connection is lost does not reach that server’s open pages, but the inbox has it: the bell reads it when its panel next opens.

across_servers, listening with these settings, such as pog.url_config(name, url): the same the app’s pool uses. The pool name in them is not used.

Tell a user’s subscribers something, from any node. send does this itself; this is for events of the app’s own making, such as an unread count changed by a bulk update.

Those older than the notification with this ID, for the next page.

More detail, shown under the title.

Forget a user’s choice for kind, so the default applies again.

Values to keep with the notification, such as the IDs the app needs to act on it. They are sent to the browser with it.

What happens to a kind nobody chose for: shown in the inbox and pushed to browsers that asked for it, and not emailed.

Remove a notification from a user’s inbox for good.

Remove everything kept for a user: notifications, preferences and push subscriptions. conn may be a transaction, such as the one auth.with_account_deletion gives, so it all goes with the account.

A notification of kind with title, its one line summary.

Wait this long before emailing a notification, and skip the email if it is read in the inbox meanwhile. Someone who is already looking at the app does not need an email too. Defaults to zero.

The kind a preference applies to when it is set for every kind.

One of a user’s notifications.

Teach the app’s jobs runner to send notifications’ email, digests and push. They run on the notifications queue, ten at a time unless the runner says otherwise with jobs.queue. Every node running the runner shares the work.

let runner =
  jobs.runner(db)
  |> notifications.handle_jobs(notifier)

supervisor.new(supervisor.OneForOne)
|> supervisor.add(jobs.supervised(runner))
|> supervisor.add(howdy.supervised(app(notifier)))

In tests, jobs.drain(runner) sends whatever is due.

At most limit notifications, between 1 and 100.

Where opening the notification goes, as a path such as /posts/42. Email and push need a full URL; see with_base_url.

A user’s inbox, newest first.

Mark every notification in a user’s inbox read.

Mark one notification read. Reading one already read changes nothing.

Mark one notification unread again.

Nothing at all: the notification is not even saved.

Notifications kept in repo, which must have had schema applied.

The newest twenty notifications.

How kind reaches recipient: their choice for the kind, else their choice for every_kind, else the app’s default.

The choices a user has made, by kind, every_kind included.

Delete notifications that were read before before, in unix milliseconds, so the table does not grow for ever. Unread ones are kept. Call it now and then, such as daily.

The queue the delivery jobs go to.

The inbox over HTTP, for howdy/ui/bell or a page of your own. identify names the signed-in user, or refuses the request:

notifications.routes(notifier, at: "/notifications", identify: fn(ctx) {
  auth.required(auth)(ctx) |> result.map(fn(principal) { principal.user.id })
})

Writes come from the user’s own browser with their cookie, so identify must refuse cross-site requests, as auth.required does, or the app must use howdy/csrf.

• GET / lists the inbox as {"notifications": [...], "unread": 3}. It takes limit, before (an ID, for the next page) and unread=true in the query.
• GET /events is the stream of the inbox.
• POST /read marks every notification read.
• POST /:id/read and POST /:id/unread mark one.
• DELETE /:id deletes one.

Writes answer {"unread": 2} with the new count. A plain HTML form can post to them too: give the action a next query parameter, a path such as ?next=/inbox, and the answer is a redirect there instead.

The migrations for the package’s tables, all named howdy_notifications_.

Save a notification for recipient, announce it to their open pages, and queue whatever email and push their preferences ask for. Gives None when they have muted the kind.

Call it after the change it is about has been committed, not inside the transaction making it: the announcement cannot be taken back.

Send the same notification to each recipient, one at a time, stopping at the first error.

Choose how kind, or every_kind, reaches a user. Use muted to stop it altogether.

A server-sent event stream of recipient’s inbox. It opens with an unread event giving the count, then sends a notification event for each that arrives and an unread event whenever the count changes:

event: notification
data: {"id": "…", "title": "Ana commented on your post", …}

event: unread
data: {"count": 3}

recipient must be the signed-in user; take it from the session, never from the request.

Hear about recipient’s inbox on subject, from any node in the cluster, or any server at all with across_servers, until the process that owns the subject exits or unsubscribe is called. Nothing announced after this returns is missed.

In a live view, subscribe from an effect:

server_component.select(fn(_dispatch, subject) {
  notifications.subscribe(user_id, subject)
  process.new_selector() |> process.select_map(subject, Notified)
})

How many subscriptions a user has, across the cluster. Servers that are not clustered, even with across_servers, only count their own.

How many notifications in the inbox are unread.

Only unread notifications.

The full URL of a notification’s link, using with_base_url; the base URL itself when it has none. A link that is already a full URL is kept.

The address the app is served from, such as https://example.com, so email and push can link to it. See url.

How each kind is delivered when the user has not chosen. Kinds the function does not know should get default_delivery.

notifications.with_defaults(notifier, fn(kind) {
  case kind {
    "security." <> _ -> Delivery(..default_delivery, email: EmailNow)
    "comment.created" -> Delivery(..default_delivery, email: EmailDigest)
    _ -> default_delivery
  }
})

Gather EmailDigest notifications into one email per user at most every every_seconds, such as 86_400 for a daily digest. render writes it from the user’s unread notifications, oldest first; those read in the meantime are left out. Needs with_email.

Without a digest, EmailDigest notifications are emailed one by one.

Send email for the kinds whose delivery asks for it. address finds a user’s address, and render writes the email for one notification: its subject and body, but not its recipient, which is filled in.

notifications.with_email(notifier, mailer,
  address: fn(user_id) { users.email_address(user_id) },
  render: fn(n) {
    mail.message()
    |> mail.subject(n.title)
    |> mail.text(n.body <> "\n\n" <> notifications.url(notifier, n))
  },
)

Deliver push notifications with deliver, such as the one web_push.deliver makes. It is the push service named "default": calling with_push again replaces it. Add more with with_push_service.

Deliver push notifications with deliver too, as the push service called name, such as one sending to phones. A notification the user wants pushed goes to every service, each in a job of its own: one that fails or is retried does not hold up or repeat the others. Adding a name that is already there replaces its service.

notifier
|> notifications.with_push_service("web", web_push.deliver(push))
|> notifications.with_push_service("phones", my_app.send_to_phones)

deliver is given the notification and finds the user’s devices itself. Keep a name once notifications have been sent with it: jobs waiting for a service that is gone fail.