ruma_client_api/
delayed_events.rs

1//! Endpoints for sending and interacting with delayed events.
2//!
3//! Delayed events are an unstable feature added by [MSC4140](https://github.com/matrix-org/matrix-spec-proposals/pull/4140)
4
5pub mod get_all_delayed_events;
6pub mod get_delayed_event;
7pub mod send_delayed_event;
8pub mod update_delayed_event;
9
10// deprecated endpoints
11pub mod delayed_message_event;
12pub mod delayed_state_event;
13
14use std::time::Duration;
15
16use ruma_common::{
17    MilliSecondsSinceUnixEpoch, OwnedEventId, OwnedRoomId,
18    api::error::StandardErrorBody,
19    serde::{Raw, StringEnum},
20};
21use ruma_events::{AnyTimelineEventContent, TimelineEventType};
22use serde::{Deserialize, Serialize};
23
24use crate::PrivOwnedStr;
25
26/// The structure of the data for returning a delayed event from a GET endpoint
27#[derive(Clone, Debug, Serialize, Deserialize)]
28#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
29pub struct DelayedEventData {
30    /// The ID of the delayed event.
31    pub delay_id: String,
32
33    /// The ID of the room that the delayed event was scheduled to be sent in.
34    pub room_id: OwnedRoomId,
35
36    /// The event type of the delayed event.
37    #[serde(rename = "type")]
38    pub event_type: TimelineEventType,
39
40    /// The State Key if the event is a state event, nothing otherwise
41    #[serde(skip_serializing_if = "Option::is_none")]
42    pub state_key: Option<String>,
43
44    /// The event content to send.
45    ///
46    /// This is the content that was submitted to the send endpoint, not the content of the final
47    /// event
48    pub content: Raw<AnyTimelineEventContent>,
49
50    /// The duration that the server should wait before sending this event
51    #[serde(with = "ruma_common::serde::duration::ms")]
52    pub delay: Duration,
53
54    /// The timestamp when the delayed event was scheduled or last restarted.
55    pub running_since: MilliSecondsSinceUnixEpoch,
56
57    /// The error that prevented the delayed event from being sent.
58    /// Present only for finalized events that were cancelled due to an error.
59    #[serde(skip_serializing_if = "Option::is_none")]
60    pub error: Option<StandardErrorBody>,
61
62    /// The event_id this event got when it was sent.
63    /// Present only for events that were sent successfully.
64    #[serde(skip_serializing_if = "Option::is_none")]
65    pub event_id: Option<OwnedEventId>,
66
67    /// The timestamp when the event was finalized.
68    /// Present only for events that were finalized (sent, failed to send, or cancelled).
69    #[serde(skip_serializing_if = "Option::is_none")]
70    #[serde(rename = "finalised_ts")]
71    pub finalized_ts: Option<MilliSecondsSinceUnixEpoch>,
72}
73
74impl DelayedEventData {
75    /// Create a new delayed event data object with the given parameters
76    pub fn new(
77        delay_id: String,
78        room_id: OwnedRoomId,
79        event_type: TimelineEventType,
80        state_key: Option<String>,
81        content: Raw<AnyTimelineEventContent>,
82        delay: Duration,
83        running_since: MilliSecondsSinceUnixEpoch,
84    ) -> Self {
85        Self {
86            delay_id,
87            room_id,
88            event_type,
89            state_key,
90            delay,
91            running_since,
92            content,
93            error: None,
94            event_id: None,
95            finalized_ts: None,
96        }
97    }
98
99    /// Returns the status indicated by this delayed event data.
100    pub fn status(&self) -> DelayedEventStatus {
101        if self.finalized_ts.is_none() {
102            DelayedEventStatus::Scheduled
103        } else if self.event_id.is_some() {
104            DelayedEventStatus::Send
105        } else if self.error.is_some() {
106            DelayedEventStatus::Error
107        } else {
108            DelayedEventStatus::Cancel
109        }
110    }
111}
112
113/// The status that a delayed event stored on the server can have.
114#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
115#[derive(Clone, StringEnum)]
116#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
117#[ruma_enum(rename_all = "snake_case")]
118pub enum DelayedEventStatus {
119    /// The event is currently scheduled to be submitted at a later date.
120    /// It may be restarted, sent or cancelled via the management endpoint.
121    Scheduled,
122
123    /// The event has been sent successfully.
124    Send,
125
126    /// The event has been cancelled.
127    Cancel,
128
129    /// The event has encountered an error when trying to send.
130    Error,
131
132    #[doc(hidden)]
133    _Custom(PrivOwnedStr),
134}
135
136/// The query parameters for a delayed event request.
137/// It contains the `timeout` configuration for a delayed event.
138///
139/// This enum is no longer used except by deprecated endpoints.
140#[derive(Clone, Debug, Serialize, Deserialize)]
141#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
142#[serde(untagged)]
143pub enum DelayParameters {
144    /// Sending a delayed event with a timeout. The response will contain a (server
145    /// generated) `delay_id` instead of an `event_id`.
146    Timeout {
147        /// The timeout duration for this delayed event.
148        #[serde(with = "ruma_common::serde::duration::ms")]
149        #[serde(rename = "org.matrix.msc4140.delay")]
150        timeout: Duration,
151    },
152}
ruma_client_api/delayed_events.rs

ruma_client_api/
delayed_events.rs
