Revision control
Copy as Markdown
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
namespace push {};
/// Object representing the PushManager used to manage subscriptions
///
/// The `PushManager` object is the main interface provided by this crate
/// it allow consumers to manage push subscriptions. It exposes methods that
/// and persists state representing subscriptions.
interface PushManager {
/// Creates a new [`PushManager`] object, not subscribed to any
/// channels
///
/// # Arguments
///
/// - `config`: The PushConfiguration for the PushManager
///
/// # Errors
/// Returns an error in the following cases:
/// - PushManager is unable to open the `database_path` given
[Throws=PushApiError]
constructor(PushConfiguration config);
/// Subscribes to a new channel and gets the Subscription Info block
///
/// # Arguments
/// - `scope` - Site scope string
/// - `server_key` - optional VAPID public key to "lock" subscriptions (defaults to "" for no key)
///
/// # Returns
/// A Subscription response that includes the following:
/// - A URL that can be used to deliver push messages
/// - A cryptographic key that can be used to encrypt messages
/// that would then be decrypted using the [`PushManager::decrypt`] function
///
/// # Errors
/// Returns an error in the following cases:
/// - PushManager was unable to access its persisted storage
/// - An error occurred sending a subscription request to the autopush server
/// - An error occurred generating or deserializing the cryptographic keys
[Throws=PushApiError]
SubscriptionResponse subscribe([ByRef] string scope, [ByRef] optional string? app_server_sey = null);
/// Retrieves an existing push subscription
///
/// # Arguments
/// - `scope` - Site scope string
///
/// # Returns
/// A Subscription response that includes the following:
/// - A URL that can be used to deliver push messages
/// - A cryptographic key that can be used to encrypt messages
/// that would then be decrypted using the [`PushManager::decrypt`] function
///
/// # Errors
/// Returns an error in the following cases:
/// - PushManager was unable to access its persisted storage
/// - An error occurred generating or deserializing the cryptographic keys
[Throws=PushApiError]
SubscriptionResponse? get_subscription([ByRef] string scope);
/// Unsubscribe from given scope, ending that subscription for the user.
///
/// # Arguments
/// - `scope` - The scope for the channel to remove
///
/// # Returns
/// Returns a boolean. Boolean is False if the subscription was already
/// terminated in the past.
///
/// # Errors
/// Returns an error in the following cases:
/// - An error occurred sending an unsubscribe request to the autopush server
/// - An error occurred accessing the PushManager's persisted storage
[Throws=PushApiError]
boolean unsubscribe([ByRef] string scope);
/// Unsubscribe all channels for the user
///
/// # Errors
/// Returns an error in the following cases:
/// - The PushManager does not contain a valid UAID
/// - An error occurred sending an unsubscribe request to the autopush server
/// - An error occurred accessing the PushManager's persisted storage
[Throws=PushApiError]
void unsubscribe_all();
/// Updates the Native OS push registration ID.
///
/// # Arguments:
/// - `new_token` - the new Native OS push registration ID
///
/// # Errors
/// Return an error in the following cases:
/// - The PushManager does not contain a valid UAID
/// - An error occurred sending an update request to the autopush server
/// - An error occurred accessing the PushManager's persisted storage
[Throws=PushApiError]
void update([ByRef] string registration_token);
/// Verifies the connection state
///
/// **NOTE**: This does not resubscribe to any channels
/// it only returns the list of channels that the client should
/// re-subscribe to.
///
/// # Returns
/// Returns a list of [`PushSubscriptionChanged`]
/// indicating the channels the consumer the client should re-subscribe
/// to. If the list is empty, the client's connection was verified
/// successfully, and the client does not need to resubscribe
///
/// # Errors
/// Return an error in the following cases:
/// - The PushManager does not contain a valid UAID
/// - An error occurred sending an channel list retrieval request to the autopush server
/// - An error occurred accessing the PushManager's persisted storage
[Throws=PushApiError]
sequence<PushSubscriptionChanged> verify_connection(optional boolean force_verify = false);
/// Decrypts a raw push message.
///
/// This accepts the content of a Push Message (from websocket or via Native Push systems).
/// # Arguments:
/// - `payload`: The Push payload as received by the client from Push.
///
/// # Returns
/// Decrypted message body
///
/// # Errors
/// Returns an error in the following cases:
/// - The PushManager does not contain a valid UAID
/// - There are no records associated with the UAID the [`PushManager`] contains
/// - An error occurred while decrypting the message
/// - An error occurred accessing the PushManager's persisted storage
[Throws=PushApiError]
DecryptResponse decrypt(record<DOMString, string> payload);
};
/// Key Information that can be used to encrypt payloads
dictionary KeyInfo {
string auth;
string p256dh;
};
/// Subscription Information, the endpoint to send push messages to and
/// the key information that can be used to encrypt payloads
dictionary SubscriptionInfo {
string endpoint;
KeyInfo keys;
};
/// The subscription response object returned from [`PushManager::subscribe`]
dictionary SubscriptionResponse {
string channel_id;
SubscriptionInfo subscription_info;
};
/// An dictionary describing the push subscription that changed, the caller
/// will receive a list of [`PushSubscriptionChanged`] when calling
/// [`PushManager::verify_connection`], one entry for each channel that the
/// caller should resubscribe to
dictionary PushSubscriptionChanged {
string channel_id;
string scope;
};
dictionary DecryptResponse {
sequence<i8> result;
string scope;
};
/// The main Error returned from the Push component, each
/// variant describes a different error
[Error]
enum PushApiError {
"UAIDNotRecognizedError",
"RecordNotFoundError",
"InternalError"
};
/// The types of supported native bridges.
///
/// FCM = Google Android Firebase Cloud Messaging
/// ADM = Amazon Device Messaging for FireTV
/// APNS = Apple Push Notification System for iOS
///
/// Please contact services back-end for any additional bridge protocols.
///
enum BridgeType {
"Fcm",
"Adm",
"Apns",
};
dictionary PushConfiguration {
string server_host;
PushHttpProtocol http_protocol;
BridgeType bridge_type;
string sender_id;
string database_path;
u64? verify_connection_rate_limiter;
};
/// Supported protocols for push
/// "Https" is default, and "Http" is only
/// supported for tests
enum PushHttpProtocol {
"Https",
"Http"
};