Skip to main content

PushSubscriptionBackend

Trait PushSubscriptionBackend 

Source
pub trait PushSubscriptionBackend: JmapBackend {
    const PUSH_SUBSCRIPTION_EXTENSION_PROPERTIES: &'static [&'static str] = _;
    const PUSH_SUBSCRIPTION_EXTENSION_CAPABILITIES: &'static [(&'static str, &'static str)] = _;

    // 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.

Provided Associated Constants§

Source

const PUSH_SUBSCRIPTION_EXTENSION_PROPERTIES: &'static [&'static str] = _

The extension property names, beyond those of RFC 8620 §7.2, that PushSubscription/get accepts in its properties argument (e.g. chatPush, draft-atwood-jmap-chat-push-00).

RFC 8620 §5.1 (rfc8620.txt:1609-1611): “If an invalid property is requested, the call MUST be rejected with an “invalidArguments” error.“ The handler rejects any name that is neither an RFC 8620 §7.2 property nor listed here.

Source

const PUSH_SUBSCRIPTION_EXTENSION_CAPABILITIES: &'static [(&'static str, &'static str)] = _

Extension properties that exist only for a request whose using holds a capability, as (property, capability URI) pairs (e.g. ("emailPush", "urn:ietf:params:jmap:emailpush"), draft-ietf-jmap-emailpush-05 §4: “To get or set the emailPush property, the client MUST include” the capability in using).

A gated property is a valid PushSubscription/get property name; it need not also be in PUSH_SUBSCRIPTION_EXTENSION_PROPERTIES. Without its capability in using, /get leaves it out of every object and rejects it in properties with invalidArguments, and /set rejects a create that sends it, or a patch whose first path segment names it, with invalidProperties. With the capability, an absent gated property reads as null in /get and in created.

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.

Extension properties tied to accounts are returned as they stand for the caller now. An EmailPush backend runs jmap_mail_server::emailpush::prune_email_push on each subscription it returns, so an account the caller has lost is not listed (draft-ietf-jmap-emailpush-05 §4); /set patches the listed object, so the next update persists the pruned map.

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, every property the client did not send, and every extension property stored with a value other than the one sent.

§Extension properties

The backend validates and normalizes the extension properties in new.extra before storing them, and returns a SetError (BackendSetError::SetError) to reject the create; the handler checks only the using gate (PUSH_SUBSCRIPTION_EXTENSION_CAPABILITIES). An EmailPush backend MUST call jmap_mail_server::emailpush::check_email_push_change; a chatPush backend calls validate_chat_push. Validating here, in the same call as the store, keeps it inside a conditional-02 scope.

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, in updated, a returned expires that differs from the one the client asked for and every extension property stored with a value other than the patched one.

Validate and normalize extension properties as for create_push_subscription.

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§