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
PushVerificationto a subscription untilis_deliverableis true, and filter eachStateChangewithstate_change_for.
Provided Associated Constants§
Sourceconst PUSH_SUBSCRIPTION_EXTENSION_PROPERTIES: &'static [&'static str] = _
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.
Sourceconst PUSH_SUBSCRIPTION_EXTENSION_CAPABILITIES: &'static [(&'static str, &'static str)] = _
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§
Sourcefn list_push_subscriptions(
&self,
caller: &Self::CallerCtx,
) -> impl Future<Output = Result<Vec<StoredPushSubscription>, Self::Error>> + Send
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.
Sourcefn create_push_subscription(
&self,
caller: &Self::CallerCtx,
new: PushSubscription,
) -> impl Future<Output = Result<StoredPushSubscription, BackendSetError<Self::Error>>> + Send
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_codeas 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
overQuotawhen it is reached. “The server MUST limit the number of push subscriptions any one user may have” (rfc8620.txt:4172-4175); - hand a
PushVerificationwith 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.
Sourcefn update_push_subscription(
&self,
caller: &Self::CallerCtx,
sub: PushSubscription,
) -> impl Future<Output = Result<PushSubscription, BackendSetError<Self::Error>>> + Send
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.
Sourcefn destroy_push_subscription(
&self,
caller: &Self::CallerCtx,
id: &Id,
) -> impl Future<Output = Result<(), BackendSetError<Self::Error>>> + Send
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".