pub trait ChatMessageLifecycle: JmapBackend {
// Required method
fn read_and_burn_message(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
message_id: &Id,
patch: PatchObject,
) -> impl Future<Output = Result<(), BackendSetError<Self::Error>>> + Send;
// Provided method
fn expire_message(
&self,
_caller: &Self::CallerCtx,
_account_id: &Id,
_message_id: &Id,
) -> impl Future<Output = Result<(), Self::Error>> + Send { ... }
}Expand description
Message expiry and read-and-burn.
Part of ChatBackend (docs/design/chat-backend-split.md).
Required Methods§
Sourcefn read_and_burn_message(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
message_id: &Id,
patch: PatchObject,
) -> impl Future<Output = Result<(), BackendSetError<Self::Error>>> + Send
fn read_and_burn_message( &self, caller: &Self::CallerCtx, account_id: &Id, message_id: &Id, patch: PatchObject, ) -> impl Future<Output = Result<(), BackendSetError<Self::Error>>> + Send
Apply a readAt-setting patch to the burnOnRead Message
message_id and hard-delete it, as one atomic operation.
Per draft-atwood-jmap-chat-00 §Message burnOnRead (jmap-chat-spec
77c3474 L750): “the receiving server SHOULD permanently hard-delete
this message (row removal, not tombstone) immediately after setting
readAt.” This crate performs the recommended deletion by choice.
§Authorisation contract
Implementors MUST verify that caller may act as the owner of
account_id before setting readAt and deleting the Message and MUST return BackendSetError::SetError
with SetErrorType::Forbidden otherwise. See ChatStore::create_object
for the workspace-canonical rationale; the same rule applies here.
§Atomicity contract
Validate patch against the stored Message exactly as
ChatStore::update_object would, then remove the row, record the id
in the destroyed set of the Message change log (bumping the
Message state once), and unpin it from its Chat (§Chat
pinnedMessageIds). All of it takes effect or none: on any error
nothing is committed, so a retried readAt patch burns again.
Composing this from update_object and Self::expire_message
loses that guarantee: a failed delete leaves readAt stored, and
a retry finds nothing left to set.
§When the handler calls this
Message/set update calls this instead of update_object when
the patch sets a non-null readAt and the stored Message has
burnOnRead: true. Return SetError notFound if the Message
does not exist and the update_object SetError for an invalid
patch. There is no default: a non-atomic default would reinstate
the gap.
Provided Methods§
Sourcefn expire_message(
&self,
_caller: &Self::CallerCtx,
_account_id: &Id,
_message_id: &Id,
) -> impl Future<Output = Result<(), Self::Error>> + Send
fn expire_message( &self, _caller: &Self::CallerCtx, _account_id: &Id, _message_id: &Id, ) -> impl Future<Output = Result<(), Self::Error>> + Send
Hard-delete a message (“expire” it) due to a per-message expiry event.
Called by crate::expiry::sweep_expired for each message whose
senderExpiresAt, Chat messageExpirySeconds or
expiresAfterReadSeconds deadline has passed
(draft-atwood-jmap-chat-00 §Message, §Chat). The kit does NOT run a
scheduler; consumers call the sweep, or this method directly, when
a timer fires.
§Contract
Per draft-atwood-jmap-chat-00 §Message (jmap-chat-spec 77c3474 L747,
L753), the senderExpiresAt and expiresAfterReadSeconds deletions
are SHOULD; this crate performs them by choice. The deletion removes
the row (not a tombstone), and the message appears in the
destroyed set of subsequent Message/changes results.
Implementations therefore SHOULD:
- Remove the underlying record so a subsequent
Message/getdoes not find it. - Bump the per-account
Messagestate token and record the id in the change log soMessage/changessees it as destroyed. - Remove the id from its Chat’s
pinnedMessageIds(§ChatpinnedMessageIds: “When a pinned Message is hard-deleted, the server MUST remove its id from this list.”). The same applies todestroy_object::<Message>.
§Idempotency
If the message no longer exists — because a previous
expire_message call or Self::read_and_burn_message has
already deleted it — this method MUST
return Ok(()), AND MUST NOT bump the per-account Message
state token in that case. The no-op case must be
observationally indistinguishable from “the scheduler never
fired” for Message/changes subscribers; a state bump on the
retry path would surface a spurious empty change set on every
re-fire and induce a poll storm. Expiry events are
inherently retry-friendly (a scheduler may re-fire if it
crashed mid-batch). The
return type is Result<(), Self::Error> (not
BackendSetError) precisely to prevent a NotFound
SetError construction on this path: expiry is an internal
scheduler hook, not a /set-shaped call, and there is no
JMAP wire surface for per-message expiry rejection.
A Message/set read of a burnOnRead Message does not use this
hook; it calls Self::read_and_burn_message so the readAt
write and the hard-delete are atomic. The expiry sweep
(crate::sweep_expired) does call it for a read
burnOnRead Message that reached the store another way.
§Default implementation
The default returns Ok(()) without doing anything, so expired
messages stay in the store and remain visible to Message/get.
It is correct only for a backend on which no message ever
expires. Backends whose messages can carry senderExpiresAt,
expiresAfterReadSeconds or a Chat messageExpirySeconds MUST
override this method: for senderExpiresAt,
draft-atwood-jmap-chat-00 §Message (jmap-chat-spec 77c3474 L747)
says “servers SHOULD permanently delete this message — removing the
row entirely, not leaving a tombstone — at or before this time”,
which this crate performs by choice.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".
Implementors§
impl<C: MemoryCaller> ChatMessageLifecycle for MemoryBackend<C>
memory only.