bookclerk_plugin_abi::notifications
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'svalidateDestinationnormalised. Only a flat object of short string values is accepted. Theaddressobject of a patron's request body is first read asAddressFields, which refuses a key written twice. - A plugin's raise on the
NOTIFYbinding (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. |
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
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.
pub fn get(&self, key: &str) -> Option<&str>
The value of field key, if present.
pub fn keys(&self) -> impl Iterator<Item = &str>
Field keys, sorted.
pub fn len(&self) -> usize
Number of fields.
pub fn is_empty(&self) -> bool
Whether the document has no fields.
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
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
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 thanMAX_NOTIFICATION_FIELDSfields.BadLink: A link is not an absolutehttpsURL (orhttpto 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 thannonecame 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 overMAX_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
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.provider_id: Service message id, at mostMAX_NOTIFICATION_FIELD_BYTESof printable text; dropped when malformed.
Retry: Try again later.after: How long the service asked for, capped atMAX_NOTIFY_RETRY_AFTER;Noneuses 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
pub fn is_notification_type_id(id: &str) -> bool
Whether id is a local notification type id: [a-z][a-z0-9_]{0,63}.
id- The type id as a plugin declares it, without its plugin prefix.
True when the id is well formed.
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}).
id- The type id as the router and the routing rules name it.
True when the id is well formed.
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.
id- The id to check.
True when the id is well formed.
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.
c- The character to test.
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.
link- The link to check.
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.
path- The path a raise names (/books/123).
NotificationError::BadLinkPath.
pub fn check_message(message: &NotificationMessage) -> Result<(), NotificationError>
Checks a message the host rendered before any notifier sees it.
message- The rendered message.
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.
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.
text- The document as a patron or a notifier gave it.
The parsed document.
NotificationError::BadAddress saying what is wrong.
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.
address- The parsed document.rules- The notifier's declared address fields.
NotificationError::MissingAddressField or
NotificationError::UnknownAddressField.
pub fn check_send_params(params: &NotifySendParams) -> Result<(), NotificationError>
Checks a Notifier.send request before it leaves the host.
params- The message and destination.
The message's check_message error, a bad destination id, or an
address that does not fit the destination kind.
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.
validated- The notifier's answer.
The parsed, normalised document.
NotificationError::BadAddress or NotificationError::BadText.
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.
invocation_account-Invocation.accountId; empty for an operator invocation.patron_id- The raise's patron id.
The user id to look up, or None to refuse the raise.
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.
params- The raise.
The first NotificationError the raise breaks.
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.
reply- The decoded reply.
The outcome, with any reason cut by 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.
reason- The text to cut.
The cut text.
pub fn severity_rank(severity: NotificationSeverity) -> u8
Rank of a severity for comparing against a rule's minimum: info 0, warning 1, critical 2.
severity- The severity to rank.
Its rank.
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.
bytes- The message bytes.
The reply: delivered, or the notifier's typed error.
Returns the Cap'n Proto error the reader reports.
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.
reply- The reply to encode.
The message bytes.
Returns the Cap'n Proto error the builder reports.
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.
bytes- The message bytes.
The raise.
Returns the Cap'n Proto error the reader reports.
pub fn encode_notify_raise_params_bytes(params: &NotifyRaiseParams) -> Result<Vec<u8>>
Encodes NotifyRaiseParams, the inverse of
decode_notify_raise_params_bytes.
params- The raise to encode.
The message bytes.
Returns the Cap'n Proto error the builder reports.
pub const MAX_NOTIFY_ID_BYTES: usize = 128;
Longest notification id, destination id or patron id, in bytes. Ids are printable ASCII without spaces.
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}.
pub const MAX_NOTIFY_ADDRESS_KEYS: usize = 16;
Most keys in one destination address document.
pub const MAX_NOTIFY_REASON_BYTES: usize = 512;
Longest reason the delivery log keeps from a notifier's error, in bytes.
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