feat(crons): Add monitor check-in types to sentry-types (#577)

Adds types that define monitor check-in envelopes.

Includes a new EnvelopeItemType and implementations of `From` for
`EnvelopeItem` and `Envelope`

Author: evanpurkhiser

sentry-types/src/protocol/envelope.rs

@@ -4,9 +4,9 @@ use serde::Deserialize;
 use thiserror::Error;
 use uuid::Uuid;
 
-use super::{
-    attachment::AttachmentType,
-    v7::{Attachment, Event, SampleProfile, SessionAggregates, SessionUpdate, Transaction},
+use super::v7::{
+    Attachment, AttachmentType, Event, MonitorCheckIn, SampleProfile, SessionAggregates,
+    SessionUpdate, Transaction,
 };
 
 /// Raised if a envelope cannot be parsed from a given input.
@@ -61,6 +61,9 @@ enum EnvelopeItemType {
     /// A Profile Item Type
     #[serde(rename = "profile")]
     Profile,
+    /// A Monitor Check In Item Type
+    #[serde(rename = "check_in")]
+    MonitorCheckIn,
 }
 
 /// An Envelope Item Header.
@@ -109,6 +112,8 @@ pub enum EnvelopeItem {
     Attachment(Attachment),
     /// A Profile Item.
     Profile(SampleProfile),
+    /// A MonitorCheckIn item.
+    MonitorCheckIn(MonitorCheckIn),
     /// This is a sentinel item used to `filter` raw envelopes.
     Raw,
     // TODO:
@@ -151,6 +156,12 @@ impl From<SampleProfile> for EnvelopeItem {
     }
 }
 
+impl From<MonitorCheckIn> for EnvelopeItem {
+    fn from(check_in: MonitorCheckIn) -> Self {
+        EnvelopeItem::MonitorCheckIn(check_in)
+    }
+}
+
 /// An Iterator over the items of an Envelope.
 #[derive(Clone)]
 pub struct EnvelopeItemIter<'s> {
@@ -341,6 +352,9 @@ impl Envelope {
                     continue;
                 }
                 EnvelopeItem::Profile(profile) => serde_json::to_writer(&mut item_buf, profile)?,
+                EnvelopeItem::MonitorCheckIn(check_in) => {
+                    serde_json::to_writer(&mut item_buf, check_in)?
+                }
                 EnvelopeItem::Raw => {
                     continue;
                 }
@@ -352,6 +366,7 @@ impl Envelope {
                 EnvelopeItem::Transaction(_) => "transaction",
                 EnvelopeItem::Attachment(_) | EnvelopeItem::Raw => unreachable!(),
                 EnvelopeItem::Profile(_) => "profile",
+                EnvelopeItem::MonitorCheckIn(_) => "check_in",
             };
             writeln!(
                 writer,
@@ -493,6 +508,9 @@ impl Envelope {
                 ty: header.attachment_type,
             })),
             EnvelopeItemType::Profile => serde_json::from_slice(payload).map(EnvelopeItem::Profile),
+            EnvelopeItemType::MonitorCheckIn => {
+                serde_json::from_slice(payload).map(EnvelopeItem::MonitorCheckIn)
+            }
         }
         .map_err(EnvelopeError::InvalidItemPayload)?;
 
@@ -523,6 +541,14 @@ impl From<Transaction<'static>> for Envelope {
     }
 }
 
+impl From<MonitorCheckIn> for Envelope {
+    fn from(check_in: MonitorCheckIn) -> Self {
+        let mut envelope = Self::default();
+        envelope.add_item(check_in);
+        envelope
+    }
+}
+
 #[cfg(test)]
 mod test {
     use std::str::FromStr;
@@ -532,7 +558,10 @@ mod test {
     use time::OffsetDateTime;
 
     use super::*;
-    use crate::protocol::v7::{Level, SessionAttributes, SessionStatus, Span};
+    use crate::protocol::v7::{
+        Level, MonitorCheckInStatus, MonitorConfig, MonitorSchedule, SessionAttributes,
+        SessionStatus, Span,
+    };
 
     fn to_str(envelope: Envelope) -> String {
         let mut vec = Vec::new();
@@ -649,6 +678,35 @@ mod test {
         )
     }
 
+    #[test]
+    fn test_monitor_checkin() {
+        let check_in_id = Uuid::parse_str("22d00b3f-d1b1-4b5d-8d20-49d138cd8a9c").unwrap();
+
+        let check_in = MonitorCheckIn {
+            check_in_id,
+            monitor_slug: "my-monitor".into(),
+            status: MonitorCheckInStatus::Ok,
+            duration: Some(123.4),
+            environment: Some("production".into()),
+            monitor_config: Some(MonitorConfig {
+                schedule: MonitorSchedule::Crontab {
+                    value: "12 0 * * *".into(),
+                },
+                checkin_margin: Some(5),
+                max_runtime: Some(30),
+                timezone: Some("UTC".into()),
+            }),
+        };
+        let envelope: Envelope = check_in.into();
+        assert_eq!(
+            to_str(envelope),
+            r#"{}
+{"type":"check_in","length":259}
+{"check_in_id":"22d00b3fd1b14b5d8d2049d138cd8a9c","monitor_slug":"my-monitor","status":"ok","environment":"production","duration":123.4,"monitor_config":{"schedule":{"type":"crontab","value":"12 0 * * *"},"checkin_margin":5,"max_runtime":30,"timezone":"UTC"}}
+"#
+        )
+    }
+
     #[test]
     fn test_event_with_attachment() {
         let event_id = Uuid::parse_str("22d00b3f-d1b1-4b5d-8d20-49d138cd8a9c").unwrap();

sentry-types/src/protocol/mod.rs

@@ -15,5 +15,6 @@ pub use v7 as latest;
 
 mod attachment;
 mod envelope;
+mod monitor;
 mod profile;
 mod session;

sentry-types/src/protocol/monitor.rs

@@ -0,0 +1,113 @@
+use serde::{Deserialize, Serialize, Serializer};
+use uuid::Uuid;
+
+/// Represents the status of the monitor check-in
+#[derive(Clone, Copy, Debug, PartialEq, Deserialize, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum MonitorCheckInStatus {
+    /// Check-in had no issues during execution.
+    Ok,
+    /// Check-in failed or otherwise had some issues.
+    Error,
+    /// Check-in is expectred to complete.
+    InProgress,
+    /// Monitor did not check in on time.
+    Missed,
+    /// No status was passed.
+    #[serde(other)]
+    Unknown,
+}
+
+/// Configuration object of the monitor schedule.
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+#[serde(rename_all = "snake_case")]
+#[serde(tag = "type")]
+pub enum MonitorSchedule {
+    /// A Crontab schedule allows you to use a standard UNIX crontab style schedule string to
+    /// configure when a monitor check-in will be expected on Sentry.
+    Crontab {
+        /// The crontab syntax string defining the schedule.
+        value: String,
+    },
+    /// A Interval schedule allows you to configure a periodic check-in, that will occur at an
+    /// interval after the most recent check-in.
+    Interval {
+        /// The interval value.
+        value: u64,
+        /// The interval unit of the value.
+        unit: MonitorIntervalUnit,
+    },
+}
+
+/// The unit for the interval schedule type
+#[derive(Clone, Copy, Debug, PartialEq, Deserialize, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum MonitorIntervalUnit {
+    /// Year Interval.
+    Year,
+    /// Month Interval.
+    Month,
+    /// Week Interval.
+    Week,
+    /// Day Interval.
+    Day,
+    /// Hour Interval.
+    Hour,
+    /// Minute Interval.
+    Minute,
+}
+
+/// The monitor configuration playload for upserting monitors during check-in
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+pub struct MonitorConfig {
+    /// The monitor schedule configuration.
+    pub schedule: MonitorSchedule,
+
+    /// How long (in minutes) after the expected check-in time will we wait until we consider the
+    /// check-in to have been missed.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub checkin_margin: Option<u64>,
+
+    /// How long (in minutes) is the check-in allowed to run for in
+    /// [`MonitorCheckInStatus::InProgress`] before it is considered failed.in_rogress
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_runtime: Option<u64>,
+
+    /// tz database style timezone string
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub timezone: Option<String>,
+}
+
+fn serialize_id<S: Serializer>(uuid: &Uuid, serializer: S) -> Result<S::Ok, S::Error> {
+    serializer.serialize_some(&uuid.as_simple())
+}
+
+/// The monitor check-in payload.
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+pub struct MonitorCheckIn {
+    /// Unique identifier of this check-in.
+    #[serde(serialize_with = "serialize_id")]
+    pub check_in_id: Uuid,
+
+    /// Identifier of the monitor for this check-in.
+    pub monitor_slug: String,
+
+    /// Status of this check-in. Defaults to `"unknown"`.
+    pub status: MonitorCheckInStatus,
+
+    /// The environment to associate the check-in with.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub environment: Option<String>,
+
+    /// Duration of this check-in since it has started in seconds.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub duration: Option<f64>,
+
+    /// Monitor configuration to support upserts. When provided a monitor will be created on Sentry
+    /// upon receiving the first check-in.
+    ///
+    /// If the monitor already exists the configuration will be updated with the values provided in
+    /// this object.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub monitor_config: Option<MonitorConfig>,
+}

sentry-types/src/protocol/v7.rs

@@ -26,6 +26,7 @@ use crate::utils::{ts_rfc3339_opt, ts_seconds_float};
 
 pub use super::attachment::*;
 pub use super::envelope::*;
+pub use super::monitor::*;
 pub use super::profile::*;
 pub use super::session::*;