bookclerk_library::notifications

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Notifications: the router's rules and the shapes the library stores (docs/adr/notifications.md, docs/server/notifications.md).

The host decides what is worth a notification and who gets it; a notifier plugin only sends one message to one destination. This module is pure. The library database holds the destinations, the administrators' routes and offers, each patron's choices, every accepted notification, the delivery log and the inbox (LibraryStore::route_notification and its neighbours), and bookclerkd runs one notify_send job per delivery-log row.

Routing, for a notification of type T:

  • Operational (T is for administrators): every channel destination with a route for T whose minimum severity the notification reaches.
  • Patron (T is for one patron): the patron's inbox, always. Then, when the patron chose for T, the personal destinations they picked (when on); when they did not, every personal destination of theirs on an instance the administrators offer for T with default_on. Either way only instances the administrators offer for T are used.
  • Account is the host's own mail and is not routed here yet.

A paused destination is skipped.

Item Kind Summary
HostNotificationType struct A notification type the host itself raises.
NewNotification struct A notification for the router to accept: rendered once, copied to every destination.
PendingDelivery struct One accepted notification's delivery waiting for its send job.
StalledSend struct A send job that has been ready to run for a long time and that nothing claimed. It is stalled only when its notifier instance runs on no live node; otherwise it is waiting for a worker.
Routed struct What the router did with a notification.
Destination struct A destination as stored.
NewDestination struct A destination to create.
Route struct One operational route.
PatronOffer struct One instance offered to patrons for a patron type.
PatronChoice struct One patron's choice for one patron type.
StoredNotification struct A stored notification.
SendWork struct Everything one notify_send job needs.
DeliveryRecord struct One delivery-log row, joined with what a reader needs to show it.
InboxEntry struct One inbox entry.
DestinationKind enum Whether a destination is a library channel or one patron's address.
DeliveryState enum Where one delivery stands.
StallOutcome enum What failing one StalledSend did.
FailureEffect enum What a finished send attempt did to its destination.
FailedAttempt enum Whether recording a failed delivery spends one more attempt.
host_notification_type function The host type named id, if it is one.
qualified_plugin_type function The routed id of a plugin's type: <plugin id>:<type id>.
fields_text function A plain-text body from labelled fields: one name: value line each, cut at a character boundary (ending in …) when it would pass maxNotificationTextBytes, so a raise within the field limits is never refused for its rendered body; the fields themselves are kept whole.
link_for function The link a notifier is sent: the library's public origin and the path. None when either is missing, or when the result is not a link a notifier may be sent (an http:// origin that is not loopback, say), so the message goes without a link rather than not at all.
severity_reaches function Whether a route with minimum severity min takes a notification of severity.
PAUSE_AFTER_FAILURES constant Permanent send failures in a row after which a destination is paused. A delivery clears the count; an administrator or the patron resumes a paused destination by hand.
MAX_ADDRESS_BYTES constant Longest stored destination address, in bytes of its JSON text. A database whose cell limit is smaller lowers it further. 1 KiB keeps the insert inside the smallest statement payload any adapter advertises.
MAX_SEND_ATTEMPTS constant Send attempts one delivery may make, retries included. A delivery whose notifier still asks to retry after this many fails.
NOTIFICATION_RETENTION_DAYS constant Days a notification, its delivery log and its inbox rows are kept.
MAX_DESTINATION_LABEL_BYTES constant Longest destination label, in bytes.
MAX_ROUTES_PER_TYPE constant Most routes, offers or patron targets one notification type may have.
IN_APP_DESTINATION constant The reserved destination id of the built-in "In app" target: an operational route to it puts the notification in the inbox of every active Owner and Administrator, where the web app's bell, browser notifications and the desktop window's system notifications show it. It is not a stored destination and runs no plugin.
TEST_NOTIFICATION_TYPE constant The host's built-in test type: an administrator or a patron sends it to one destination to check that it works.
AUDIENCES constant Every audience, in the order of the audience column's CHECK list.
SEVERITIES constant Every severity, lowest first, in the order of the CHECK lists.
ALERT_ACTIONS constant Every alert action, in the order of the alert_action CHECK list.
HOST_NOTIFICATION_TYPES constant The host's own notification types. Producers of operational and patron events add theirs here as they land.

Structs

HostNotificationType

pub struct HostNotificationType {
    pub id: &'static str,
    pub audience: NotificationAudience,
    pub severity: NotificationSeverity,
    pub title: &'static str,
}

A notification type the host itself raises.

Fields

  • id: Type id; host types carry no plugin prefix.
  • audience: Who it is for.
  • severity: Default severity.
  • title: Title shown in the routing matrix and on each notification.

Implements: Clone, Copy, Debug, Eq, PartialEq

NewNotification

pub struct NewNotification {
    pub notification_type: String,
    pub audience: NotificationAudience,
    pub severity: NotificationSeverity,
    pub title: String,
    pub text: String,
    pub link_path: Option<String>,
    pub fields: Vec<NotificationField>,
    pub group_key: Option<String>,
    pub alert_action: NotificationAlertAction,
    pub alert_key: Option<String>,
    pub source: String,
    pub patron: Option<i64>,
}

A notification for the router to accept: rendered once, copied to every destination.

Fields

  • notification_type: Qualified type (test, <plugin>:<type>).
  • audience: Who it is for; decides how it is routed.
  • severity: How urgent it is.
  • title: Short title.
  • text: Plain-text body.
  • link_path: Path inside the library to link to; the send job prefixes the public origin.
  • fields: Labelled values.
  • group_key: Grouping key.
  • alert_action: Alert lifecycle step.
  • alert_key: Alert key; required unless alert_action is none.
  • source: Empty for a host type, else the raising plugin's id.
  • patron: Patron a patron-audience notification is for; required for that audience and refused for the others.

NewNotification::check

pub fn check(&self, notification_id: &str) -> Result<(), NotificationError>

Checks the notification the way every send will be checked, so a bad one is refused before anything is stored.

Arguments
  • notification_id - The id it will be stored under.
Errors

The first NotificationError the rendered message or its link path breaks; NotificationError::BadId for a patron that does not match the audience.

NewNotification::message

pub fn message(&self, notification_id: &str, link: Option<String>) -> NotificationMessage

The message a notifier is sent, with link already built from the public origin.

Implements: Clone, Debug, Eq, PartialEq

PendingDelivery

pub struct PendingDelivery {
    pub id: String,
    pub plugin_instance_id: String,
}

One accepted notification's delivery waiting for its send job.

Fields

  • id: Delivery-log row id.
  • plugin_instance_id: Notifier instance that sends it.

Implements: Clone, Debug, Eq, PartialEq

StalledSend

pub struct StalledSend {
    pub job_id: String,
    pub run_after: String,
    pub lease_generation: i64,
    pub delivery_id: Option<String>,
    pub notifier: Option<String>,
}

A send job that has been ready to run for a long time and that nothing claimed. It is stalled only when its notifier instance runs on no live node; otherwise it is waiting for a worker.

Fields

  • job_id: The pending send job nothing claimed.
  • run_after: When the job became ready to run, as stored: the write that fails it matches this, so a job retried in the meantime is left alone.
  • lease_generation: The job's lease generation when it was read, matched the same way.
  • delivery_id: Its pending delivery, named by the job's dedup key; None when the delivery is gone, already finished or linked to another job, and the job only needs cancelling.
  • notifier: The notifier instance the delivery goes through; None exactly when delivery_id is.

Implements: Clone, Debug, Eq, PartialEq

Routed

pub struct Routed {
    pub notification_id: String,
    pub deliveries: Vec<PendingDelivery>,
    pub inboxed: bool,
}

What the router did with a notification.

Fields

  • notification_id: The id it was stored under.
  • deliveries: The deliveries it made, each with a send job enqueued (or left for the sweep when the enqueue failed).
  • inboxed: Whether it reached an inbox: its patron's, or the staff's through an "In app" route.

Implements: Clone, Debug, Eq, PartialEq

Destination

pub struct Destination {
    pub id: String,
    pub plugin_instance_id: String,
    pub kind: DestinationKind,
    pub user_id: Option<i64>,
    pub label: String,
    pub address_json: String,
    pub failure_count: i64,
    pub paused_at: Option<String>,
    pub paused_reason: Option<String>,
    pub created_at: String,
}

A destination as stored.

Fields

  • id: Destination id.
  • plugin_instance_id: Notifier instance that sends to it.
  • kind: Channel or personal.
  • user_id: Owner of a personal destination.
  • label: Name shown to people.
  • address_json: Canonical address document (empty for a channel). May hold secrets.
  • failure_count: Permanent failures since the last delivery.
  • paused_at: When it was paused; None while active.
  • paused_reason: Why it was paused.
  • created_at: RFC 3339 creation time.

Implements: Clone, Debug, Eq, PartialEq

NewDestination

pub struct NewDestination {
    pub plugin_instance_id: String,
    pub kind: DestinationKind,
    pub user_id: Option<i64>,
    pub label: String,
    pub address_json: String,
}

A destination to create.

Fields

  • plugin_instance_id: Notifier instance that will send to it.
  • kind: Channel or personal.
  • user_id: Owner; required for a personal destination, refused for a channel.
  • label: Name shown to people; one line, at most MAX_DESTINATION_LABEL_BYTES.
  • address_json: Canonical address document the notifier validated (empty for a channel).

Implements: Clone, Debug, Eq, PartialEq

Route

pub struct Route {
    pub destination_id: String,
    pub min_severity: NotificationSeverity,
}

One operational route.

Fields

  • destination_id: Channel destination, or IN_APP_DESTINATION for the staff inbox.
  • min_severity: Lowest severity sent.

Implements: Clone, Debug, Eq, PartialEq

PatronOffer

pub struct PatronOffer {
    pub plugin_instance_id: String,
    pub default_on: bool,
}

One instance offered to patrons for a patron type.

Fields

  • plugin_instance_id: Notifier instance.
  • default_on: Whether a patron who has not chosen gets the type there.

Implements: Clone, Debug, Eq, PartialEq

PatronChoice

pub struct PatronChoice {
    pub notification_type: String,
    pub enabled: bool,
    pub destination_ids: Vec<String>,
}

One patron's choice for one patron type.

Fields

  • notification_type: Qualified patron type.
  • enabled: Whether the patron wants it outside the inbox.
  • destination_ids: The patron's personal destinations it goes to.

Implements: Clone, Debug, Eq, PartialEq

StoredNotification

pub struct StoredNotification {
    pub id: String,
    pub notification: NewNotification,
    pub created_at: String,
}

A stored notification.

Fields

  • id: Notification id.
  • notification: The notification as accepted.
  • created_at: RFC 3339 creation time.

Implements: Clone, Debug, Eq, PartialEq

SendWork

pub struct SendWork {
    pub delivery_id: String,
    pub state: DeliveryState,
    pub attempts: i64,
    pub plugin_instance_id: String,
    pub notification: StoredNotification,
    pub destination: Option<Destination>,
}

Everything one notify_send job needs.

Fields

  • delivery_id: Delivery-log row id.
  • state: Where the delivery stands.
  • attempts: Attempts made so far.
  • plugin_instance_id: Notifier instance that sends it.
  • notification: The notification.
  • destination: The destination; None when it was removed.

Implements: Clone, Debug, Eq, PartialEq

DeliveryRecord

pub struct DeliveryRecord {
    pub id: String,
    pub notification_id: String,
    pub notification_type: String,
    pub title: String,
    pub destination_id: String,
    pub plugin_instance_id: String,
    pub state: DeliveryState,
    pub attempts: i64,
    pub provider_id: Option<String>,
    pub reason: Option<String>,
    pub created_at: String,
    pub updated_at: String,
}

One delivery-log row, joined with what a reader needs to show it.

Fields

  • id: Delivery-log row id.
  • notification_id: Notification id.
  • notification_type: Qualified type.
  • title: Notification title.
  • destination_id: Destination id.
  • plugin_instance_id: Notifier instance.
  • state: Where it stands.
  • attempts: Attempts made.
  • provider_id: The service's id for the delivered message.
  • reason: Last failure or retry reason.
  • created_at: RFC 3339 creation time.
  • updated_at: RFC 3339 time of the last change.

Implements: Clone, Debug, Eq, PartialEq

InboxEntry

pub struct InboxEntry {
    pub notification: StoredNotification,
    pub read_at: Option<String>,
}

One inbox entry.

Fields

  • notification: The notification.
  • read_at: When the patron read it; None while unread.

Implements: Clone, Debug, Eq, PartialEq

Enums

DestinationKind

pub enum DestinationKind {
    Channel,
    Personal,
}

Whether a destination is a library channel or one patron's address.

Variants

  • Channel: A library channel; the notifier instance's own settings say where.
  • Personal: One patron's personal address.

DestinationKind::ALL

pub const ALL: [Self; 2] = _

Every kind, in the order of the kind column's CHECK list.

DestinationKind::as_str

pub fn as_str(self) -> &'static str

The stored spelling.

DestinationKind::parse

pub fn parse(s: &str) -> Option<Self>

Parses the stored spelling; None when unknown.

DestinationKind::wire

pub fn wire(self) -> NotifyDestinationKind

The kind the notifier sees.

Implements: Clone, ComposeSchema, Copy, Debug, Deserialize<'de>, Eq, Hash, PartialEq, Serialize, ToSchema

DeliveryState

pub enum DeliveryState {
    Pending,
    Delivered,
    Failed,
    Dropped,
}

Where one delivery stands.

Variants

  • Pending: Waiting for its send job, or between retries.
  • Delivered: The notifier delivered it.
  • Failed: The notifier refused it for good, or it ran out of attempts.
  • Dropped: Not sent: its destination was paused or removed, or its notifier instance is gone.

DeliveryState::ALL

pub const ALL: [Self; 4] = _

Every state, in the order of the state column's CHECK list.

DeliveryState::as_str

pub fn as_str(self) -> &'static str

The stored spelling.

DeliveryState::parse

pub fn parse(s: &str) -> Option<Self>

Parses the stored spelling; None when unknown.

Implements: Clone, ComposeSchema, Copy, Debug, Deserialize<'de>, Eq, Hash, PartialEq, Serialize, ToSchema

StallOutcome

pub enum StallOutcome {
    NotStalled,
    Cancelled,
    Dropped,
    Failed(FailureEffect),
}

What failing one StalledSend did.

Variants

  • NotStalled: The job was claimed, retried or ended meanwhile; nothing changed.
  • Cancelled: The job was cancelled; it had no pending delivery to fail.
  • Dropped: The job was cancelled and its delivery dropped, because the destination was already paused; nothing was counted.
  • Failed: The job was cancelled and its delivery failed, in one write.

Implements: Clone, Copy, Debug, Eq, PartialEq

FailureEffect

pub enum FailureEffect {
    Counted,
    Paused,
}

What a finished send attempt did to its destination.

Variants

  • Counted: The destination stays active.
  • Paused: This failure paused the destination.

Implements: Clone, Copy, Debug, Eq, PartialEq

FailedAttempt

pub enum FailedAttempt {
    New,
    AlreadyCounted,
}

Whether recording a failed delivery spends one more attempt.

Variants

  • New: A send the notifier refused for good: this answer is a new attempt.
  • AlreadyCounted: A delivery that ran out of attempts: its last answer (a retry) was already counted when it was recorded.

Implements: Clone, Copy, Debug, Eq, PartialEq

Functions

host_notification_type

pub fn host_notification_type(id: &str) -> Option<&'static HostNotificationType>

The host type named id, if it is one.

qualified_plugin_type

pub fn qualified_plugin_type(plugin_id: &str, type_id: &str) -> String

The routed id of a plugin's type: <plugin id>:<type id>.

fields_text

pub fn fields_text(fields: &[NotificationField]) -> String

A plain-text body from labelled fields: one name: value line each, cut at a character boundary (ending in …) when it would pass maxNotificationTextBytes, so a raise within the field limits is never refused for its rendered body; the fields themselves are kept whole.

pub fn link_for(public_origin: Option<&str>, path: Option<&str>) -> Option<String>

The link a notifier is sent: the library's public origin and the path. None when either is missing, or when the result is not a link a notifier may be sent (an http:// origin that is not loopback, say), so the message goes without a link rather than not at all.

severity_reaches

pub fn severity_reaches(severity: NotificationSeverity, min: NotificationSeverity) -> bool

Whether a route with minimum severity min takes a notification of severity.

Constants

PAUSE_AFTER_FAILURES

pub const PAUSE_AFTER_FAILURES: i64 = 5;

Permanent send failures in a row after which a destination is paused. A delivery clears the count; an administrator or the patron resumes a paused destination by hand.

MAX_ADDRESS_BYTES

pub const MAX_ADDRESS_BYTES: usize = 1024;

Longest stored destination address, in bytes of its JSON text. A database whose cell limit is smaller lowers it further. 1 KiB keeps the insert inside the smallest statement payload any adapter advertises.

MAX_SEND_ATTEMPTS

pub const MAX_SEND_ATTEMPTS: i64 = 10;

Send attempts one delivery may make, retries included. A delivery whose notifier still asks to retry after this many fails.

NOTIFICATION_RETENTION_DAYS

pub const NOTIFICATION_RETENTION_DAYS: i64 = 30;

Days a notification, its delivery log and its inbox rows are kept.

MAX_DESTINATION_LABEL_BYTES

pub const MAX_DESTINATION_LABEL_BYTES: usize = 128;

Longest destination label, in bytes.

MAX_ROUTES_PER_TYPE

pub const MAX_ROUTES_PER_TYPE: usize = 32;

Most routes, offers or patron targets one notification type may have.

IN_APP_DESTINATION

pub const IN_APP_DESTINATION: &str = "in-app";

The reserved destination id of the built-in "In app" target: an operational route to it puts the notification in the inbox of every active Owner and Administrator, where the web app's bell, browser notifications and the desktop window's system notifications show it. It is not a stored destination and runs no plugin.

TEST_NOTIFICATION_TYPE

pub const TEST_NOTIFICATION_TYPE: &str = "test";

The host's built-in test type: an administrator or a patron sends it to one destination to check that it works.

AUDIENCES

pub const AUDIENCES: [NotificationAudience; 3] = _;

Every audience, in the order of the audience column's CHECK list.

SEVERITIES

pub const SEVERITIES: [NotificationSeverity; 3] = _;

Every severity, lowest first, in the order of the CHECK lists.

ALERT_ACTIONS

pub const ALERT_ACTIONS: [NotificationAlertAction; 3] = _;

Every alert action, in the order of the alert_action CHECK list.

HOST_NOTIFICATION_TYPES

pub const HOST_NOTIFICATION_TYPES: &[HostNotificationType] = _;

The host's own notification types. Producers of operational and patron events add theirs here as they land.

Generated from crates/bookclerk-library at main · View as Markdown