Skip to main content

ChatMessageLifecycle

Trait ChatMessageLifecycle 

Source
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§

Source

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§

Source

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/get does not find it.
  • Bump the per-account Message state token and record the id in the change log so Message/changes sees it as destroyed.
  • Remove the id from its Chat’s pinnedMessageIds (§Chat pinnedMessageIds: “When a pinned Message is hard-deleted, the server MUST remove its id from this list.”). The same applies to destroy_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§

Source§

impl<C: MemoryCaller> ChatMessageLifecycle for MemoryBackend<C>

Available on crate feature memory only.
Source§

impl<T: DelegateChatMessageLifecycle> ChatMessageLifecycle for T