Skip to main content

PushSubscriptionBackend

Trait PushSubscriptionBackend 

Source
pub trait PushSubscriptionBackend: JmapBackend {
    // Required methods
    fn list_push_subscriptions(
        &self,
        caller: &Self::CallerCtx,
    ) -> impl Future<Output = Result<Vec<StoredPushSubscription>, Self::Error>> + Send;
    fn create_push_subscription(
        &self,
        caller: &Self::CallerCtx,
        new: PushSubscription,
    ) -> impl Future<Output = Result<StoredPushSubscription, BackendSetError<Self::Error>>> + Send;
    fn update_push_subscription(
        &self,
        caller: &Self::CallerCtx,
        sub: PushSubscription,
    ) -> impl Future<Output = Result<PushSubscription, BackendSetError<Self::Error>>> + Send;
    fn destroy_push_subscription(
        &self,
        caller: &Self::CallerCtx,
        id: &Id,
    ) -> impl Future<Output = Result<(), BackendSetError<Self::Error>>> + Send;
}
Expand description

Storage for RFC 8620 §7.2 push subscriptions, scoped to the caller’s credentials rather than to an account.

The PushSubscription/set handler validates the request before it calls the create and update methods: url begins with "https://", a create carries no id or verificationCode, an update changes no immutable property, a new verificationCode matches StoredPushSubscription::expected_code, and expires is at most MAX_PUSH_EXPIRY_SECS in the future. A backend may reject a request for its own policy reasons by returning BackendSetError::SetError, which the handler places in the response verbatim.

§Consumer MUSTs

These RFC 8620 requirements need I/O, clocks or credential state that this crate does not have. The consumer that implements this trait and sends the pushes MUST meet them:

  • “The server MUST ensure the URL is externally resolvable to avoid server-side request forgery” (rfc8620.txt:4151-4153).
  • “The rate of creation MUST also be limited” (rfc8620.txt:4175-4177).
  • “Should these credentials expire or be revoked, the push subscription MUST be destroyed by the JMAP server” (rfc8620.txt:3691-3693).
  • “When a push subscription is destroyed, the server MUST securely erase the URL and encryption keys from memory and storage as soon as possible” (rfc8620.txt:3725-3727).
  • Send nothing but the PushVerification to a subscription until is_deliverable is true, and filter each StateChange with state_change_for.

Required Methods§

Source

fn list_push_subscriptions( &self, caller: &Self::CallerCtx, ) -> impl Future<Output = Result<Vec<StoredPushSubscription>, Self::Error>> + Send

Return every push subscription created with the credentials that caller identifies, and no others.

RFC 8620 §7.2.1: “The server MUST only return push subscriptions that were created using the same authentication credentials as for this “PushSubscription/get” request.“ The handler cannot tell credentials apart, so it relies on this method for that MUST.

Source

fn create_push_subscription( &self, caller: &Self::CallerCtx, new: PushSubscription, ) -> impl Future<Output = Result<StoredPushSubscription, BackendSetError<Self::Error>>> + Send

Store new as a subscription owned by the credentials that caller identifies, and return what was stored.

new has no id and no verificationCode, and its expires is already limited to MAX_PUSH_EXPIRY_SECS from now. The backend MUST:

  • assign id;
  • generate StoredPushSubscription::expected_code as a fixed-length code carrying at least 128 bits from a CSPRNG. The code “MUST contain sufficient entropy to avoid the client being able to guess the code via brute force” (rfc8620.txt:3784-3786);
  • check its per-user subscription cap atomically with the insert and return overQuota when it is reached. “The server MUST limit the number of push subscriptions any one user may have” (rfc8620.txt:4172-4175);
  • hand a PushVerification with the new id and code to the consumer’s delivery path.

The backend may shorten expires. In created the handler echoes the returned id and expires, plus every property the client did not send.

Source

fn update_push_subscription( &self, caller: &Self::CallerCtx, sub: PushSubscription, ) -> impl Future<Output = Result<PushSubscription, BackendSetError<Self::Error>>> + Send

Replace the caller’s subscription whose id is sub.id with sub, and return what was stored.

sub is the stored subscription with the client’s patch applied and validated. Return notFound if no subscription of the caller has that id. The backend may shorten expires. The handler reports a returned expires that differs from the one the client asked for in updated.

Source

fn destroy_push_subscription( &self, caller: &Self::CallerCtx, id: &Id, ) -> impl Future<Output = Result<(), BackendSetError<Self::Error>>> + Send

Delete the caller’s subscription with this id, or return notFound if the caller has none.

See the secure-erase MUST in the trait docs.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§