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"
};