bookclerk_plugin_abi::notifications

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

Last updated View as Markdown

The checks the host runs on notification requests and replies.

Three things cross a trust boundary here, and each is checked by sans-IO code that the fuzz targets and the host share:

  • A notifier's reply to Notifier.send (classify_send_reply): delivered, retry later or failed for good. The plugin's error text is cut to a short single line (sanitize_reason) before the delivery log stores it.
  • A destination address document (parse_address_document): the JSON object a patron typed (an email address, a Telegram chat id, a push subscription) and that a notifier's validateDestination normalised. Only a flat object of short string values is accepted. The address object of a patron's request body is first read as AddressFields, which refuses a key written twice.
  • A plugin's raise on the NOTIFY binding (check_raise_params): a declared type id, labelled fields, an optional patron and a path inside the library.

The host also checks every message it renders (check_message) before a notifier sees it, so a bug in a renderer cannot hand a plugin an oversized body or a link to somewhere other than the library.

Item Kind Summary
AddressFields struct The address object of a patron's POST /api/me/notifications/destinations body, as sent: a flat object of strings in which no key is written twice. JSON parsers keep the last of a repeated key, so a repeat is refused instead of silently dropping a value. The notifier's declared fields and parse_address_document check it further.
NotifyAddress struct A destination address document: a flat JSON object of string values, keyed by the [[notifier.address_fields]] keys. Values may be secrets (a push subscription's auth key); the type never prints them.
AddressFieldRule struct One address field a notifier declares in [[notifier.address_fields]].
NotificationError enum Why a notification request, message or reply was refused.
SendOutcome enum What the host does with one destination after a Notifier.send reply.
is_notification_type_id function Whether id is a local notification type id: a-z{0,63}.
is_qualified_notification_type function Whether id is a routed notification type id: a host type (job_failed) or a plugin type qualified by its plugin id (ntfy_relay:sync_failed, plugin ids being [a-z0-9_]{2,32}).
is_notify_id function Whether id is a usable id: 1 to MAX_NOTIFY_ID_BYTES bytes of printable ASCII with no space.
is_layout_char function Whether c breaks a line or reorders text without being a control character: the Unicode line and paragraph separators and the bidirectional marks, embeddings, overrides and isolates. A one-line value refuses them so it shows as written.
check_link function Checks an absolute link into the library: https://host[:port]/..., or http:// only to localhost, 127.0.0.1 or [::1]; no credentials, no whitespace or control characters, at most MAX_NOTIFICATION_FIELD_BYTES.
check_link_path function Checks a path inside the library that the host will prefix with its public origin: starts with one /, no // at the start, no backslash, whitespace or control characters, at most MAX_NOTIFICATION_FIELD_BYTES.
check_message function Checks a message the host rendered before any notifier sees it.
parse_address_document function Parses a destination address document.
check_address_against_fields function Checks an address document against the fields the notifier declares: every required field present and non-blank, no undeclared field.
check_send_params function Checks a Notifier.send request before it leaves the host.
check_validated function Checks a Notifier.validateDestination answer: a well-formed address document and an optional short single-line label.
scoped_patron_id function The sans-IO half of the host's patron-scope check on a raise: the library user a raise's patron_id names, which the host then looks up as a holder of the invocation's store account.
check_raise_params function Checks a raise a plugin sent on its NOTIFY binding. Whether the type is one the plugin declared, and whether the patron is inside the invocation's account scope, are the host's checks, since only it knows the manifest and the scope.
classify_send_reply function Turns a Notifier.send reply into what the host does next.
sanitize_reason function Cuts a notifier's error text to one line of at most MAX_NOTIFY_REASON_BYTES bytes: control characters become spaces and the cut falls on a character boundary.
severity_rank function Rank of a severity for comparing against a rule's minimum: info 0, warning 1, critical 2.
decode_notify_send_reply_bytes function Decodes a NotifySendReply from an unpacked Cap'n Proto message, the form a notifier's reply crosses the plugin boundary in.
encode_notify_send_reply_bytes function Encodes a NotifySendReply, the inverse of decode_notify_send_reply_bytes.
decode_notify_raise_params_bytes function Decodes NotifyRaiseParams from an unpacked Cap'n Proto message, the form a plugin's raise crosses the plugin boundary in.
encode_notify_raise_params_bytes function Encodes NotifyRaiseParams, the inverse of decode_notify_raise_params_bytes.
MAX_NOTIFY_ID_BYTES constant Longest notification id, destination id or patron id, in bytes. Ids are printable ASCII without spaces.
MAX_NOTIFICATION_TYPE_ID_BYTES constant Longest local notification type id (job_failed), in bytes; type ids follow the ABI identifier rule a-z{0,63}.
MAX_NOTIFY_ADDRESS_KEYS constant Most keys in one destination address document.
MAX_NOTIFY_REASON_BYTES constant Longest reason the delivery log keeps from a notifier's error, in bytes.
MAX_NOTIFY_RETRY_AFTER constant Longest wait the host honours from a notifier's retryAfterMs. A service asking for longer is retried after this long instead.

Structs

AddressFields

pub struct AddressFields(pub BTreeMap<String, String>);

The address object of a patron's POST /api/me/notifications/destinations body, as sent: a flat object of strings in which no key is written twice. JSON parsers keep the last of a repeated key, so a repeat is refused instead of silently dropping a value. The notifier's declared fields and parse_address_document check it further.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq

NotifyAddress

pub struct NotifyAddress {
    /* private fields */
}

A destination address document: a flat JSON object of string values, keyed by the [[notifier.address_fields]] keys. Values may be secrets (a push subscription's auth key); the type never prints them.

NotifyAddress::get

pub fn get(&self, key: &str) -> Option<&str>

The value of field key, if present.

NotifyAddress::keys

pub fn keys(&self) -> impl Iterator<Item = &str>

Field keys, sorted.

NotifyAddress::len

pub fn len(&self) -> usize

Number of fields.

NotifyAddress::is_empty

pub fn is_empty(&self) -> bool

Whether the document has no fields.

NotifyAddress::to_json

pub fn to_json(&self) -> String

The canonical JSON text of the document (keys sorted, no spaces), the form the host stores and sends.

Implements: Clone, Debug, Default, Eq, PartialEq

AddressFieldRule

pub struct AddressFieldRule {
    pub key: String,
    pub required: bool,
}

One address field a notifier declares in [[notifier.address_fields]].

Fields

  • key: Field key (email, chat_id).
  • required: Whether a personal destination must carry it.

Implements: Clone, Debug, Eq, PartialEq

Enums

NotificationError

pub enum NotificationError {
    BadTypeId,
    BadId(&'static str),
    BadText(&'static str),
    TooManyFields,
    BadLink,
    BadLinkPath,
    BadAlert,
    BadAddress(&'static str),
    MissingAddressField(String),
    UnknownAddressField(String),
    AddressKindMismatch,
}

Why a notification request, message or reply was refused.

Variants

  • BadTypeId: A notification type id is not [a-z][a-z0-9_]{0,63}, optionally prefixed by a plugin id and :.
  • BadId: An id (notification, destination, patron) is empty, too long, or holds a space or a non-printable byte.
  • BadText: A text value is empty where it may not be, over its cap, or holds a control character it may not.
  • TooManyFields: More than MAX_NOTIFICATION_FIELDS fields.
  • BadLink: A link is not an absolute https URL (or http to a loopback host), carries credentials, or is too long.
  • BadLinkPath: A link path is not an absolute path inside the library.
  • BadAlert: An alert action other than none came without an alert key, or an alert key came without an action.
  • BadAddress: An address document is not a flat JSON object of short strings, or is over MAX_NOTIFIER_ADDRESS_BYTES.
  • MissingAddressField: An address document lacks a field the notifier requires.
  • UnknownAddressField: An address document carries a field the notifier does not declare.
  • AddressKindMismatch: A channel destination carried an address, or a personal one none.

Implements: Clone, Debug, Display, Eq, Error, From<NotificationError>, PartialEq

SendOutcome

pub enum SendOutcome {
    Delivered { provider_id: Option<String> },
    Retry { after: Option<Duration>, reason: String },
    Failed { reason: String },
}

What the host does with one destination after a Notifier.send reply.

Variants

  • Delivered: Delivered; the service's id for the message, when it gave a usable one.
  • Retry: Try again later.
    • after: How long the service asked for, capped at MAX_NOTIFY_RETRY_AFTER; None uses the job's backoff.
    • reason: Short single-line reason for the delivery log.
  • Failed: Give up on this destination.
    • reason: Short single-line reason for the delivery log.

Implements: Clone, Debug, Eq, PartialEq

Functions

is_notification_type_id

pub fn is_notification_type_id(id: &str) -> bool

Whether id is a local notification type id: [a-z][a-z0-9_]{0,63}.

Arguments

  • id - The type id as a plugin declares it, without its plugin prefix.

Returns

True when the id is well formed.

is_qualified_notification_type

pub fn is_qualified_notification_type(id: &str) -> bool

Whether id is a routed notification type id: a host type (job_failed) or a plugin type qualified by its plugin id (ntfy_relay:sync_failed, plugin ids being [a-z0-9_]{2,32}).

Arguments

  • id - The type id as the router and the routing rules name it.

Returns

True when the id is well formed.

is_notify_id

pub fn is_notify_id(id: &str) -> bool

Whether id is a usable id: 1 to MAX_NOTIFY_ID_BYTES bytes of printable ASCII with no space.

Arguments

  • id - The id to check.

Returns

True when the id is well formed.

is_layout_char

pub fn is_layout_char(c: char) -> bool

Whether c breaks a line or reorders text without being a control character: the Unicode line and paragraph separators and the bidirectional marks, embeddings, overrides and isolates. A one-line value refuses them so it shows as written.

Arguments

  • c - The character to test.

Returns

True for U+2028, U+2029, U+061C, U+200E, U+200F, U+202A to U+202E and U+2066 to U+2069.

pub fn check_link(link: &str) -> Result<(), NotificationError>

Checks an absolute link into the library: https://host[:port]/..., or http:// only to localhost, 127.0.0.1 or [::1]; no credentials, no whitespace or control characters, at most MAX_NOTIFICATION_FIELD_BYTES.

Arguments

  • link - The link to check.

Errors

NotificationError::BadLink.

pub fn check_link_path(path: &str) -> Result<(), NotificationError>

Checks a path inside the library that the host will prefix with its public origin: starts with one /, no // at the start, no backslash, whitespace or control characters, at most MAX_NOTIFICATION_FIELD_BYTES.

Arguments

  • path - The path a raise names (/books/123).

Errors

NotificationError::BadLinkPath.

check_message

pub fn check_message(message: &NotificationMessage) -> Result<(), NotificationError>

Checks a message the host rendered before any notifier sees it.

Arguments

  • message - The rendered message.

Errors

The first NotificationError the message breaks: a bad id or type, a blank or oversized title, an oversized body, a link outside the rules, too many fields, or a mismatched alert.

parse_address_document

pub fn parse_address_document(text: &str) -> Result<NotifyAddress, NotificationError>

Parses a destination address document.

The document must be a JSON object of at most MAX_NOTIFY_ADDRESS_KEYS keys, each key an identifier ([a-z][a-z0-9_]{0,63}) appearing once, each value a string of at most MAX_NOTIFICATION_FIELD_BYTES bytes with no control characters; the whole text at most MAX_NOTIFIER_ADDRESS_BYTES.

Arguments

  • text - The document as a patron or a notifier gave it.

Returns

The parsed document.

Errors

NotificationError::BadAddress saying what is wrong.

check_address_against_fields

pub fn check_address_against_fields(
    address: &NotifyAddress,
    rules: &[AddressFieldRule],
) -> Result<(), NotificationError>

Checks an address document against the fields the notifier declares: every required field present and non-blank, no undeclared field.

Arguments

  • address - The parsed document.
  • rules - The notifier's declared address fields.

Errors

NotificationError::MissingAddressField or NotificationError::UnknownAddressField.

check_send_params

pub fn check_send_params(params: &NotifySendParams) -> Result<(), NotificationError>

Checks a Notifier.send request before it leaves the host.

Arguments

  • params - The message and destination.

Errors

The message's check_message error, a bad destination id, or an address that does not fit the destination kind.

check_validated

pub fn check_validated(
    validated: &NotifyValidated,
) -> Result<NotifyAddress, NotificationError>

Checks a Notifier.validateDestination answer: a well-formed address document and an optional short single-line label.

Arguments

  • validated - The notifier's answer.

Returns

The parsed, normalised document.

Errors

NotificationError::BadAddress or NotificationError::BadText.

scoped_patron_id

pub fn scoped_patron_id(invocation_account: &str, patron_id: &str) -> Option<i64>

The sans-IO half of the host's patron-scope check on a raise: the library user a raise's patron_id names, which the host then looks up as a holder of the invocation's store account.

A raise outside every account scope is refused here: an invocation with no account (an operator invocation) can name no patron, and a patron id must be a user id written canonically (a positive decimal with no sign, no leading zero and no other character) that fits an i64, so one user is never named two ways.

Arguments

  • invocation_account - Invocation.accountId; empty for an operator invocation.
  • patron_id - The raise's patron id.

Returns

The user id to look up, or None to refuse the raise.

check_raise_params

pub fn check_raise_params(params: &NotifyRaiseParams) -> Result<(), NotificationError>

Checks a raise a plugin sent on its NOTIFY binding. Whether the type is one the plugin declared, and whether the patron is inside the invocation's account scope, are the host's checks, since only it knows the manifest and the scope.

Arguments

  • params - The raise.

Errors

The first NotificationError the raise breaks.

classify_send_reply

pub fn classify_send_reply(reply: &Result<NotifySent, PluginError>) -> SendOutcome

Turns a Notifier.send reply into what the host does next.

rate_limited, unavailable, deadline_exceeded and cancelled are retried, rate_limited after the service's retryAfterMs when it gave one; every other error is a permanent failure for this destination. A delivered reply with a malformed provider id is still delivered, without the id.

Arguments

  • reply - The decoded reply.

Returns

The outcome, with any reason cut by sanitize_reason.

sanitize_reason

pub fn sanitize_reason(reason: &str) -> String

Cuts a notifier's error text to one line of at most MAX_NOTIFY_REASON_BYTES bytes: control characters become spaces and the cut falls on a character boundary.

Arguments

  • reason - The text to cut.

Returns

The cut text.

severity_rank

pub fn severity_rank(severity: NotificationSeverity) -> u8

Rank of a severity for comparing against a rule's minimum: info 0, warning 1, critical 2.

Arguments

  • severity - The severity to rank.

Returns

Its rank.

decode_notify_send_reply_bytes

pub fn decode_notify_send_reply_bytes(
    bytes: &[u8],
) -> Result<Result<NotifySent, PluginError>>

Decodes a NotifySendReply from an unpacked Cap'n Proto message, the form a notifier's reply crosses the plugin boundary in.

Arguments

  • bytes - The message bytes.

Returns

The reply: delivered, or the notifier's typed error.

Errors

Returns the Cap'n Proto error the reader reports.

encode_notify_send_reply_bytes

pub fn encode_notify_send_reply_bytes(
    reply: &Result<NotifySent, PluginError>,
) -> Result<Vec<u8>>

Encodes a NotifySendReply, the inverse of decode_notify_send_reply_bytes.

Arguments

  • reply - The reply to encode.

Returns

The message bytes.

Errors

Returns the Cap'n Proto error the builder reports.

decode_notify_raise_params_bytes

pub fn decode_notify_raise_params_bytes(bytes: &[u8]) -> Result<NotifyRaiseParams>

Decodes NotifyRaiseParams from an unpacked Cap'n Proto message, the form a plugin's raise crosses the plugin boundary in.

Arguments

  • bytes - The message bytes.

Returns

The raise.

Errors

Returns the Cap'n Proto error the reader reports.

encode_notify_raise_params_bytes

pub fn encode_notify_raise_params_bytes(params: &NotifyRaiseParams) -> Result<Vec<u8>>

Encodes NotifyRaiseParams, the inverse of decode_notify_raise_params_bytes.

Arguments

  • params - The raise to encode.

Returns

The message bytes.

Errors

Returns the Cap'n Proto error the builder reports.

Constants

MAX_NOTIFY_ID_BYTES

pub const MAX_NOTIFY_ID_BYTES: usize = 128;

Longest notification id, destination id or patron id, in bytes. Ids are printable ASCII without spaces.

MAX_NOTIFICATION_TYPE_ID_BYTES

pub const MAX_NOTIFICATION_TYPE_ID_BYTES: usize = 64;

Longest local notification type id (job_failed), in bytes; type ids follow the ABI identifier rule [a-z][a-z0-9_]{0,63}.

MAX_NOTIFY_ADDRESS_KEYS

pub const MAX_NOTIFY_ADDRESS_KEYS: usize = 16;

Most keys in one destination address document.

MAX_NOTIFY_REASON_BYTES

pub const MAX_NOTIFY_REASON_BYTES: usize = 512;

Longest reason the delivery log keeps from a notifier's error, in bytes.

MAX_NOTIFY_RETRY_AFTER

pub const MAX_NOTIFY_RETRY_AFTER: Duration = _;

Longest wait the host honours from a notifier's retryAfterMs. A service asking for longer is retried after this long instead.

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