bookclerk_library::notifications
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 (
Tis for administrators): every channel destination with a route forTwhose minimum severity the notification reaches. - Patron (
Tis for one patron): the patron's inbox, always. Then, when the patron chose forT, the personal destinations they picked (when on); when they did not, every personal destination of theirs on an instance the administrators offer forTwithdefault_on. Either way only instances the administrators offer forTare 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. |
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
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 unlessalert_actionisnone.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.
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.
notification_id- The id it will be stored under.
The first NotificationError the rendered message or its link path
breaks; NotificationError::BadId for a patron that does not match
the audience.
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
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
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;Nonewhen 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;Noneexactly whendelivery_idis.
Implements: Clone, Debug, Eq, PartialEq
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
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;Nonewhile active.paused_reason: Why it was paused.created_at: RFC 3339 creation time.
Implements: Clone, Debug, Eq, PartialEq
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 mostMAX_DESTINATION_LABEL_BYTES.address_json: Canonical address document the notifier validated (empty for a channel).
Implements: Clone, Debug, Eq, PartialEq
pub struct Route {
pub destination_id: String,
pub min_severity: NotificationSeverity,
}
One operational route.
Fields
destination_id: Channel destination, orIN_APP_DESTINATIONfor the staff inbox.min_severity: Lowest severity sent.
Implements: Clone, Debug, Eq, PartialEq
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
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
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
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;Nonewhen it was removed.
Implements: Clone, Debug, Eq, PartialEq
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
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;Nonewhile unread.
Implements: Clone, Debug, Eq, PartialEq
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.
pub const ALL: [Self; 2] = _
Every kind, in the order of the kind column's CHECK list.
pub fn as_str(self) -> &'static str
The stored spelling.
pub fn parse(s: &str) -> Option<Self>
Parses the stored spelling; None when unknown.
pub fn wire(self) -> NotifyDestinationKind
The kind the notifier sees.
Implements: Clone, ComposeSchema, Copy, Debug, Deserialize<'de>, Eq, Hash, PartialEq, Serialize, ToSchema
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.
pub const ALL: [Self; 4] = _
Every state, in the order of the state column's CHECK list.
pub fn as_str(self) -> &'static str
The stored spelling.
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
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
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
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
pub fn host_notification_type(id: &str) -> Option<&'static HostNotificationType>
The host type named id, if it is one.
pub fn qualified_plugin_type(plugin_id: &str, type_id: &str) -> String
The routed id of a plugin's type: <plugin id>:<type id>.
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.
pub fn severity_reaches(severity: NotificationSeverity, min: NotificationSeverity) -> bool
Whether a route with minimum severity min takes a notification of
severity.
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.
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.
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.
pub const NOTIFICATION_RETENTION_DAYS: i64 = 30;
Days a notification, its delivery log and its inbox rows are kept.
pub const MAX_DESTINATION_LABEL_BYTES: usize = 128;
Longest destination label, in bytes.
pub const MAX_ROUTES_PER_TYPE: usize = 32;
Most routes, offers or patron targets one notification type may have.
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.
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.
pub const AUDIENCES: [NotificationAudience; 3] = _;
Every audience, in the order of the audience column's CHECK list.
pub const SEVERITIES: [NotificationSeverity; 3] = _;
Every severity, lowest first, in the order of the CHECK lists.
pub const ALERT_ACTIONS: [NotificationAlertAction; 3] = _;
Every alert action, in the order of the alert_action CHECK list.
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