1use std::collections::btree_map::Entry;
14use std::collections::{BTreeMap, HashMap};
15
16use chrono::Utc;
17use malloc_size_of_derive::MallocSizeOf;
18use once_cell::sync::Lazy;
19use serde::{Deserialize, Serialize};
20
21use crate::common_metric_data::CommonMetricDataInternal;
22use crate::metrics::{EventMetric, MetricType, TextMetric};
23use crate::session::EventSessionContext;
24use crate::storage::INTERNAL_STORAGE;
25use crate::{CommonMetricData, Glean, Lifetime};
26
27const FLOW_STATE_METRIC_NAME: &str = "flows#state";
29
30#[derive(Debug, Clone, Copy, PartialEq, Eq, MallocSizeOf)]
32pub enum FlowRole {
33 Start,
35 End,
37 Member,
39}
40
41#[derive(Debug, Clone, PartialEq, Eq, MallocSizeOf)]
43pub struct FlowDefinition {
44 pub name: String,
46 pub events: HashMap<String, FlowRole>,
49 pub auto_close_timeout_ms: Option<u64>,
52 pub disabled: bool,
54}
55
56#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize, MallocSizeOf)]
58pub struct FlowEntry {
59 pub name: String,
61 pub seq: u64,
63}
64
65#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, MallocSizeOf)]
69pub(crate) struct FlowId(usize);
70
71#[derive(Debug, MallocSizeOf)]
73pub(crate) struct RegisteredFlow {
74 pub(crate) name: String,
75 pub(crate) auto_close_timeout_ms: Option<u64>,
76 pub(crate) disabled: bool,
77}
78
79#[derive(Debug, Default, PartialEq, Eq, MallocSizeOf)]
83pub(crate) struct EventFlows {
84 pub(crate) member_of: Vec<FlowId>,
86 pub(crate) starts: Vec<FlowId>,
88 pub(crate) ends: Vec<FlowId>,
90}
91
92#[derive(Debug, Default, MallocSizeOf)]
96pub(crate) struct FlowRegistry {
97 flows: Vec<RegisteredFlow>,
99 index: HashMap<String, EventFlows>,
101}
102
103impl FlowRegistry {
104 pub(crate) fn new(definitions: &[FlowDefinition]) -> Self {
116 let mut definitions: Vec<&FlowDefinition> = definitions.iter().collect();
117 definitions.sort_by(|a, b| a.name.cmp(&b.name));
119 definitions.dedup_by(|later, earlier| {
120 let duplicate = later.name == earlier.name;
121 if duplicate {
122 log::error!(
123 "Flow '{}' is defined more than once. Ignoring all but the first definition.",
124 later.name
125 );
126 }
127 duplicate
128 });
129
130 let mut flows = Vec::with_capacity(definitions.len());
131 let mut index: HashMap<String, EventFlows> = HashMap::new();
132 for (i, definition) in definitions.into_iter().enumerate() {
133 let id = FlowId(i);
134 flows.push(RegisteredFlow {
135 name: definition.name.clone(),
136 auto_close_timeout_ms: definition.auto_close_timeout_ms,
137 disabled: definition.disabled,
138 });
139
140 for (event, role) in &definition.events {
141 let entry = index.entry(event.clone()).or_default();
142 entry.member_of.push(id);
143 match role {
144 FlowRole::Start => entry.starts.push(id),
145 FlowRole::End => entry.ends.push(id),
146 FlowRole::Member => {}
147 }
148 }
149 }
150
151 Self { flows, index }
152 }
153
154 #[cfg(test)]
156 pub(crate) fn is_empty(&self) -> bool {
157 self.flows.is_empty()
158 }
159
160 pub(crate) fn lookup_metric(&self, meta: &CommonMetricDataInternal) -> Option<&EventFlows> {
166 if self.index.is_empty() {
167 return None;
168 }
169 self.index.get(&meta.base_identifier())
170 }
171
172 #[cfg(test)]
174 pub(crate) fn lookup(&self, identifier: &str) -> Option<&EventFlows> {
175 if self.index.is_empty() {
176 return None;
177 }
178 self.index.get(identifier)
179 }
180
181 pub(crate) fn flow(&self, id: FlowId) -> &RegisteredFlow {
183 &self.flows[id.0]
184 }
185
186 pub(crate) fn find(&self, name: &str) -> Option<FlowId> {
188 self.flows
189 .binary_search_by(|flow| flow.name.as_str().cmp(name))
190 .ok()
191 .map(FlowId)
192 }
193}
194
195#[derive(Debug, Clone, Copy, PartialEq, Eq)]
197pub(crate) struct ActiveInstance {
198 pub(crate) seq: u64,
200 pub(crate) opened_at_ms: i64,
204}
205
206#[derive(Debug, Default)]
208pub(crate) struct FlowState {
209 pub(crate) active: BTreeMap<FlowId, ActiveInstance>,
211 pub(crate) next_seq: u64,
213}
214
215impl FlowState {
216 fn open(&mut self, flow: FlowId, now_ms: i64) -> bool {
223 let Entry::Vacant(entry) = self.active.entry(flow) else {
224 return false;
225 };
226 entry.insert(ActiveInstance {
227 seq: self.next_seq,
228 opened_at_ms: now_ms,
229 });
230 self.next_seq += 1;
231 true
232 }
233
234 fn take_expired(
238 &mut self,
239 registry: &FlowRegistry,
240 candidates: &[FlowId],
241 now_ms: i64,
242 ) -> Vec<(FlowId, u64)> {
243 let expired_flows: Vec<FlowId> = candidates
244 .iter()
245 .copied()
246 .filter(|flow| {
247 let Some(instance) = self.active.get(flow) else {
248 return false;
249 };
250 registry
251 .flow(*flow)
252 .auto_close_timeout_ms
253 .is_some_and(|timeout| {
254 let timeout = i64::try_from(timeout).unwrap_or(i64::MAX);
255 now_ms.saturating_sub(instance.opened_at_ms) >= timeout
256 })
257 })
258 .collect();
259 let mut expired: Vec<(FlowId, u64)> = expired_flows
260 .into_iter()
261 .filter_map(|flow| self.active.remove(&flow).map(|i| (flow, i.seq)))
262 .collect();
263 expired.sort_by_key(|a| std::cmp::Reverse(a.1));
264 expired
265 }
266}
267
268fn now_ms() -> i64 {
269 Utc::now().timestamp_millis()
270}
271
272#[derive(Debug, Clone, Copy)]
274pub(crate) enum FlowEndReason<'a> {
275 Exit {
277 terminating_event: &'a str,
279 },
280 Timeout,
282 SessionEnd,
284 Abnormal {
286 session_id: &'a str,
288 },
289}
290
291impl FlowEndReason<'_> {
292 fn as_str(&self) -> &'static str {
293 match self {
294 FlowEndReason::Exit { .. } => "exit",
295 FlowEndReason::Timeout => "timeout",
296 FlowEndReason::SessionEnd => "session_end",
297 FlowEndReason::Abnormal { .. } => "abnormal",
298 }
299 }
300}
301
302pub(crate) fn lookup<'a>(glean: &'a Glean, metric: &EventMetric) -> Option<&'a EventFlows> {
312 let meta = metric.meta();
313 if !meta.inner.in_session || !glean.session_manager().is_active() {
314 return None;
315 }
316 glean.flow_registry.lookup_metric(meta)
317}
318
319pub(crate) fn open_instances(glean: &Glean, event_flows: &EventFlows) {
323 if event_flows.starts.is_empty() {
324 return;
325 }
326 let now = now_ms();
327 let mut state = glean.flow_state.lock().unwrap();
328 let mut opened = false;
330 for flow in &event_flows.starts {
331 opened |= state.open(*flow, now);
332 }
333 if opened {
334 persist(glean, &state);
335 }
336}
337
338pub(crate) fn close_expired_for_event(
350 glean: &Glean,
351 event_flows: &EventFlows,
352 timestamp: u64,
353) -> bool {
354 close_expired(glean, Some(&event_flows.member_of), timestamp)
355}
356
357pub(crate) fn close_all_expired(glean: &Glean) -> bool {
364 if !glean.session_manager().is_active() {
365 return false;
366 }
367 close_expired(glean, None, crate::get_timestamp_ms())
368}
369
370fn close_expired(glean: &Glean, candidates: Option<&[FlowId]>, timestamp: u64) -> bool {
373 let expired = {
374 let mut state = glean.flow_state.lock().unwrap();
375 if state.active.is_empty() {
376 return false;
377 }
378 let all: Vec<FlowId>;
379 let candidates = match candidates {
380 Some(candidates) => candidates,
381 None => {
382 all = state.active.keys().copied().collect();
383 &all
384 }
385 };
386 let expired = state.take_expired(&glean.flow_registry, candidates, now_ms());
387 if !expired.is_empty() {
388 persist(glean, &state);
389 }
390 expired
391 };
392
393 let mut submitted = false;
394 for (flow, seq) in expired {
395 submitted |= record_flow_end(
396 glean,
397 &glean.flow_registry.flow(flow).name,
398 seq,
399 FlowEndReason::Timeout,
400 timestamp,
401 );
402 }
403 submitted
404}
405
406pub(crate) fn active_entries(glean: &Glean, event_flows: &EventFlows) -> Vec<FlowEntry> {
410 let state = glean.flow_state.lock().unwrap();
411 event_flows
412 .member_of
413 .iter()
414 .filter_map(|id| {
415 state.active.get(id).map(|instance| FlowEntry {
416 name: glean.flow_registry.flow(*id).name.clone(),
417 seq: instance.seq,
418 })
419 })
420 .collect()
421}
422
423pub(crate) fn close_instances(
432 glean: &Glean,
433 event_flows: &EventFlows,
434 metric: &EventMetric,
435 timestamp: u64,
436) -> bool {
437 if event_flows.ends.is_empty() {
438 return false;
439 }
440 let closed: Vec<(FlowId, u64)> = {
441 let mut state = glean.flow_state.lock().unwrap();
442 let closed: Vec<(FlowId, u64)> = event_flows
443 .ends
444 .iter()
445 .filter_map(|flow| state.active.remove(flow).map(|i| (*flow, i.seq)))
446 .collect();
447 if !closed.is_empty() {
448 persist(glean, &state);
449 }
450 closed
451 };
452 if closed.is_empty() {
453 return false;
454 }
455
456 let terminating_event = metric.meta().base_identifier();
457 let mut submitted = false;
458 for (flow, seq) in closed {
459 submitted |= record_flow_end(
460 glean,
461 &glean.flow_registry.flow(flow).name,
462 seq,
463 FlowEndReason::Exit {
464 terminating_event: &terminating_event,
465 },
466 timestamp,
467 );
468 }
469 submitted
470}
471
472pub(crate) fn close_all_at_session_end(glean: &Glean) {
478 close_all_expired(glean);
479 let mut closed: Vec<(FlowId, u64)> = {
480 let mut state = glean.flow_state.lock().unwrap();
481 std::mem::take(&mut state.active)
482 .into_iter()
483 .map(|(flow, instance)| (flow, instance.seq))
484 .collect()
485 };
486 clear_persisted(glean);
487 closed.sort_by_key(|a| std::cmp::Reverse(a.1));
489 for (flow, seq) in closed {
490 record_flow_end(
491 glean,
492 &glean.flow_registry.flow(flow).name,
493 seq,
494 FlowEndReason::SessionEnd,
495 crate::get_timestamp_ms(),
496 );
497 }
498}
499
500pub(crate) fn reset_for_new_session(glean: &Glean) {
504 *glean.flow_state.lock().unwrap() = FlowState::default();
505 clear_persisted(glean);
506}
507
508pub(crate) fn restore(glean: &Glean, session_id: &str) {
515 let Some(persisted) = read_persisted(glean) else {
516 return;
517 };
518 if persisted.session_id != session_id {
519 clear_persisted(glean);
520 return;
521 }
522 if !glean.session_manager().sampled_in() {
526 log::info!("Discarding persisted flow instances of a now sampled-out session");
527 clear_persisted(glean);
528 return;
529 }
530
531 let persisted_count = persisted.instances.len();
532 let mut state = FlowState {
533 active: BTreeMap::new(),
534 next_seq: persisted.next_seq,
535 };
536 for instance in persisted.instances {
537 if instance.session_id != session_id {
538 continue;
539 }
540 match glean.flow_registry.find(&instance.flow_name) {
541 Some(flow) => {
542 state.active.insert(
543 flow,
544 ActiveInstance {
545 seq: instance.flow_seq,
546 opened_at_ms: instance.opened_at_ms,
547 },
548 );
549 }
550 None => log::info!(
551 "Discarding persisted instance of flow '{}', which is no longer registered",
552 instance.flow_name
553 ),
554 }
555 }
556 if state.active.len() != persisted_count {
557 persist(glean, &state);
558 }
559 *glean.flow_state.lock().unwrap() = state;
560}
561
562pub(crate) fn recover_abnormal(glean: &Glean) {
570 if let Some(persisted) = read_persisted(glean) {
571 let mut instances = persisted.instances;
572 instances.sort_by_key(|a| std::cmp::Reverse(a.flow_seq));
574 for instance in instances {
575 if glean.flow_registry.find(&instance.flow_name).is_none() {
576 continue;
577 }
578 record_flow_end(
579 glean,
580 &instance.flow_name,
581 instance.flow_seq,
582 FlowEndReason::Abnormal {
583 session_id: &instance.session_id,
584 },
585 crate::get_timestamp_ms(),
586 );
587 }
588 }
589 *glean.flow_state.lock().unwrap() = FlowState::default();
590 clear_persisted(glean);
591}
592
593pub(crate) fn discard_persisted(glean: &Glean) {
596 *glean.flow_state.lock().unwrap() = FlowState::default();
597 clear_persisted(glean);
598}
599
600#[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
602struct PersistedFlowState {
603 session_id: String,
605 next_seq: u64,
606 instances: Vec<PersistedInstance>,
607}
608
609#[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
611struct PersistedInstance {
612 flow_name: String,
613 flow_seq: u64,
614 session_id: String,
616 opened_at_ms: i64,
617}
618
619fn make_flow_state_metric() -> TextMetric {
620 TextMetric::new(CommonMetricData {
621 name: FLOW_STATE_METRIC_NAME.into(),
622 category: String::new(),
623 send_in_pings: vec![INTERNAL_STORAGE.into()],
624 lifetime: Lifetime::User,
625 ..Default::default()
626 })
627}
628
629fn persist(glean: &Glean, state: &FlowState) {
633 if glean.data_store.is_none() {
635 return;
636 }
637 let Some(session_id) = glean.session_manager().session_id() else {
638 return;
639 };
640 let session_id = session_id.to_string();
641 let persisted = PersistedFlowState {
642 session_id: session_id.clone(),
643 next_seq: state.next_seq,
644 instances: state
645 .active
646 .iter()
647 .map(|(flow, instance)| PersistedInstance {
648 flow_name: glean.flow_registry.flow(*flow).name.clone(),
649 flow_seq: instance.seq,
650 session_id: session_id.clone(),
651 opened_at_ms: instance.opened_at_ms,
652 })
653 .collect(),
654 };
655 let json = serde_json::to_string(&persisted).unwrap();
657 make_flow_state_metric().set_sync(glean, json);
658}
659
660fn read_persisted(glean: &Glean) -> Option<PersistedFlowState> {
662 glean.data_store.as_ref()?;
663 let json = make_flow_state_metric().get_value(glean, INTERNAL_STORAGE)?;
664 if json.is_empty() {
665 return None;
666 }
667 match serde_json::from_str(&json) {
668 Ok(persisted) => Some(persisted),
669 Err(e) => {
670 log::warn!("Discarding unreadable persisted flow state: {e}");
671 None
672 }
673 }
674}
675
676fn clear_persisted(glean: &Glean) {
678 if glean.data_store.is_none() {
679 return;
680 }
681 make_flow_state_metric().set_sync(glean, "");
682}
683
684static FLOW_END_META: Lazy<CommonMetricDataInternal> = Lazy::new(|| {
687 CommonMetricData {
688 name: "flow_end".into(),
689 category: "glean".into(),
690 send_in_pings: vec!["events".into()],
691 lifetime: Lifetime::Ping,
692 ..Default::default()
693 }
694 .into()
695});
696
697pub(crate) fn record_flow_end(
710 glean: &Glean,
711 flow_name: &str,
712 flow_seq: u64,
713 reason: FlowEndReason,
714 timestamp: u64,
715) -> bool {
716 let mut extra = HashMap::new();
717 extra.insert("flow_name".to_string(), flow_name.to_string());
718 extra.insert("flow_seq".to_string(), flow_seq.to_string());
719 extra.insert("reason".to_string(), reason.as_str().to_string());
720 let ctx = match reason {
721 FlowEndReason::Exit { terminating_event } => {
722 extra.insert(
723 "terminating_event".to_string(),
724 terminating_event.to_string(),
725 );
726 glean.session_manager().compute_event_context()
727 }
728 FlowEndReason::Abnormal { session_id } => {
729 extra.insert("session_id".to_string(), session_id.to_string());
730 EventSessionContext::OutOfSession
731 }
732 FlowEndReason::Timeout | FlowEndReason::SessionEnd => {
733 glean.session_manager().compute_event_context()
734 }
735 };
736 glean.maybe_inject_glean_timestamp(&mut extra);
737
738 glean.event_storage().record(
739 glean,
740 &FLOW_END_META,
741 timestamp,
742 Some(extra),
743 ctx,
744 Vec::new(),
745 )
746}
747
748#[cfg(test)]
749mod test {
750 use super::*;
751 use crate::session::SessionMode;
752 use crate::{CommonMetricData, InternalConfiguration, Lifetime};
753
754 fn definition(name: &str, events: &[(&str, FlowRole)]) -> FlowDefinition {
755 FlowDefinition {
756 name: name.into(),
757 events: events.iter().map(|(e, r)| (e.to_string(), *r)).collect(),
758 auto_close_timeout_ms: None,
759 disabled: false,
760 }
761 }
762
763 fn names(registry: &FlowRegistry, ids: &[FlowId]) -> Vec<String> {
764 ids.iter()
765 .map(|id| registry.flow(*id).name.clone())
766 .collect()
767 }
768
769 #[test]
770 fn no_definitions_gives_an_empty_registry() {
771 let registry = FlowRegistry::new(&[]);
772 assert!(registry.is_empty());
773 assert!(registry.index.is_empty());
774 assert!(registry.lookup("onboarding.started").is_none());
775 assert!(registry.find("onboarding").is_none());
776 }
777
778 #[test]
779 fn index_records_membership_and_boundary_roles() {
780 let registry = FlowRegistry::new(&[definition(
781 "onboarding",
782 &[
783 ("onboarding.started", FlowRole::Start),
784 ("onboarding.finished", FlowRole::End),
785 ("onboarding.card_shown", FlowRole::Member),
786 ],
787 )]);
788 let onboarding = registry.find("onboarding").unwrap();
789
790 let started = registry.lookup("onboarding.started").unwrap();
791 assert_eq!(vec![onboarding], started.member_of);
792 assert_eq!(vec![onboarding], started.starts);
793 assert!(started.ends.is_empty());
794
795 let finished = registry.lookup("onboarding.finished").unwrap();
796 assert_eq!(vec![onboarding], finished.member_of);
797 assert!(finished.starts.is_empty());
798 assert_eq!(vec![onboarding], finished.ends);
799
800 let card_shown = registry.lookup("onboarding.card_shown").unwrap();
801 assert_eq!(vec![onboarding], card_shown.member_of);
802 assert!(card_shown.starts.is_empty());
803 assert!(card_shown.ends.is_empty());
804
805 assert!(registry.lookup("settings.opened").is_none());
806 }
807
808 #[test]
809 fn index_lists_are_in_name_order_regardless_of_definition_order() {
810 let shared = "app.opened";
811 let registry = FlowRegistry::new(&[
812 definition("zeta", &[(shared, FlowRole::Start)]),
813 definition("alpha", &[(shared, FlowRole::Member)]),
814 definition("mu", &[(shared, FlowRole::Start)]),
815 ]);
816
817 let flows = registry.lookup(shared).unwrap();
818 assert_eq!(
819 vec!["alpha", "mu", "zeta"],
820 names(®istry, &flows.member_of)
821 );
822 assert_eq!(vec!["mu", "zeta"], names(®istry, &flows.starts));
823 assert!(flows.ends.is_empty());
824 }
825
826 #[test]
827 fn duplicate_flow_names_keep_the_first_definition() {
828 let mut first = definition("onboarding", &[("onboarding.started", FlowRole::Start)]);
829 first.auto_close_timeout_ms = Some(1000);
830 let second = definition("onboarding", &[("other.started", FlowRole::Start)]);
831
832 let registry = FlowRegistry::new(&[first, second]);
833 let id = registry.find("onboarding").unwrap();
834 assert_eq!(Some(1000), registry.flow(id).auto_close_timeout_ms);
835 assert!(registry.lookup("onboarding.started").is_some());
836 assert!(registry.lookup("other.started").is_none());
837 }
838
839 #[test]
840 fn registered_flow_carries_its_settings() {
841 let mut def = definition("onboarding", &[("onboarding.started", FlowRole::Start)]);
842 def.auto_close_timeout_ms = Some(45 * 60 * 1000);
843 def.disabled = true;
844
845 let registry = FlowRegistry::new(&[def]);
846 let flow = registry.flow(registry.find("onboarding").unwrap());
847 assert_eq!("onboarding", flow.name);
848 assert_eq!(Some(45 * 60 * 1000), flow.auto_close_timeout_ms);
849 assert!(flow.disabled);
850 }
851
852 fn glean_with_flows(flows: Vec<FlowDefinition>) -> (Glean, tempfile::TempDir) {
857 let dir = tempfile::tempdir().unwrap();
858 let cfg = test_cfg(&dir, flows);
859 (Glean::new(cfg).unwrap(), dir)
860 }
861
862 fn test_cfg(dir: &tempfile::TempDir, flows: Vec<FlowDefinition>) -> InternalConfiguration {
863 InternalConfiguration {
864 data_path: dir.path().display().to_string(),
865 application_id: "org.mozilla.glean.test.app".into(),
866 language_binding_name: "Rust".into(),
867 upload_enabled: true,
868 max_events: None,
869 delay_ping_lifetime_io: false,
870 app_build: "Unknown".into(),
871 use_core_mps: false,
872 trim_data_to_registered_pings: false,
873 log_level: None,
874 rate_limit: None,
875 enable_event_timestamps: false,
876 experimentation_id: None,
877 enable_internal_pings: true,
878 ping_schedule: Default::default(),
879 ping_lifetime_threshold: 0,
880 ping_lifetime_max_time: 0,
881 max_pending_pings_count: None,
882 max_pending_pings_directory_size: None,
883 session_mode: SessionMode::Manual,
884 session_sample_rate: 1.0,
885 session_inactivity_timeout_ms: 0,
886 events_ping_acceleration_factor: None,
887 enable_store_submitted_pings: false,
888 flows,
889 }
890 }
891
892 fn event(category: &str, name: &str, in_session: bool) -> EventMetric {
893 EventMetric::new(
894 CommonMetricData {
895 category: category.into(),
896 name: name.into(),
897 send_in_pings: vec!["events".into()],
898 lifetime: Lifetime::Ping,
899 in_session,
900 ..Default::default()
901 },
902 vec![],
903 )
904 }
905
906 fn activate(glean: &Glean, flow: &str, seq: u64) {
908 let id = glean.flow_registry.find(flow).unwrap();
909 glean.flow_state.lock().unwrap().active.insert(
910 id,
911 ActiveInstance {
912 seq,
913 opened_at_ms: now_ms(),
914 },
915 );
916 }
917
918 fn record_and_get_flows(glean: &Glean, metric: &EventMetric) -> Vec<FlowEntry> {
920 metric.record_sync(glean, 0, HashMap::new(), 0);
921 metric
922 .get_value(glean, "events")
923 .expect("event should be recorded")
924 .pop()
925 .unwrap()
926 .flows
927 }
928
929 fn entry(name: &str, seq: u64) -> FlowEntry {
930 FlowEntry {
931 name: name.into(),
932 seq,
933 }
934 }
935
936 fn onboarding_and_checkout() -> Vec<FlowDefinition> {
937 vec![
938 definition(
939 "onboarding",
940 &[
941 ("onboarding.started", FlowRole::Start),
942 ("app.card_shown", FlowRole::Member),
943 ("app.settings_toggled", FlowRole::Member),
944 ],
945 ),
946 definition(
947 "checkout",
948 &[
949 ("checkout.started", FlowRole::Start),
950 ("app.card_shown", FlowRole::Member),
951 ],
952 ),
953 ]
954 }
955
956 #[test]
957 fn member_event_is_tagged_with_its_active_flow() {
958 let (mut glean, _t) = glean_with_flows(onboarding_and_checkout());
959 glean.session_start();
960 activate(&glean, "onboarding", 0);
961
962 let flows = record_and_get_flows(&glean, &event("app", "settings_toggled", true));
963 assert_eq!(vec![entry("onboarding", 0)], flows);
964 }
965
966 #[test]
967 fn member_event_is_not_tagged_when_its_flow_is_not_active() {
968 let (mut glean, _t) = glean_with_flows(onboarding_and_checkout());
969 glean.session_start();
970 activate(&glean, "checkout", 0);
972
973 let flows = record_and_get_flows(&glean, &event("app", "settings_toggled", true));
974 assert!(flows.is_empty());
975 }
976
977 #[test]
978 fn event_in_several_active_flows_has_entries_in_name_order() {
979 let (mut glean, _t) = glean_with_flows(onboarding_and_checkout());
980 glean.session_start();
981 activate(&glean, "onboarding", 1);
982 activate(&glean, "checkout", 0);
983
984 let flows = record_and_get_flows(&glean, &event("app", "card_shown", true));
985 assert_eq!(vec![entry("checkout", 0), entry("onboarding", 1)], flows);
986 }
987
988 #[test]
989 fn event_named_by_no_flow_is_not_tagged() {
990 let (mut glean, _t) = glean_with_flows(onboarding_and_checkout());
991 glean.session_start();
992 activate(&glean, "onboarding", 0);
993 activate(&glean, "checkout", 0);
994
995 let flows = record_and_get_flows(&glean, &event("settings", "opened", true));
996 assert!(flows.is_empty());
997 }
998
999 #[test]
1000 fn out_of_session_event_is_not_tagged_even_if_a_flow_names_it() {
1001 let (mut glean, _t) = glean_with_flows(onboarding_and_checkout());
1002 glean.session_start();
1003 activate(&glean, "onboarding", 0);
1004
1005 let flows = record_and_get_flows(&glean, &event("app", "settings_toggled", false));
1006 assert!(flows.is_empty());
1007 }
1008
1009 #[test]
1010 fn event_is_not_tagged_between_sessions() {
1011 let (glean, _t) = glean_with_flows(onboarding_and_checkout());
1012 activate(&glean, "onboarding", 0);
1013
1014 let flows = record_and_get_flows(&glean, &event("app", "settings_toggled", true));
1015 assert!(flows.is_empty());
1016 }
1017
1018 #[test]
1019 fn flows_are_serialized_on_tagged_events_and_omitted_otherwise() {
1020 let (mut glean, _t) = glean_with_flows(onboarding_and_checkout());
1021 glean.session_start();
1022 activate(&glean, "onboarding", 3);
1023
1024 event("app", "settings_toggled", true).record_sync(&glean, 0, HashMap::new(), 0);
1025 event("settings", "opened", true).record_sync(&glean, 0, HashMap::new(), 0);
1026
1027 let json = glean
1028 .event_storage()
1029 .snapshot_as_json(&glean, "events", false)
1030 .unwrap();
1031 let events = json.as_array().unwrap();
1032 let find = |category: &str, name: &str| {
1033 events
1034 .iter()
1035 .find(|e| e["category"] == category && e["name"] == name)
1036 .unwrap()
1037 .clone()
1038 };
1039 assert_eq!(
1040 serde_json::json!([{"name": "onboarding", "seq": 3}]),
1041 find("app", "settings_toggled")["flows"]
1042 );
1043 assert!(find("settings", "opened").get("flows").is_none());
1044 }
1045
1046 #[test]
1047 fn stored_events_without_flows_deserialize_with_no_flows() {
1048 let event: crate::event_database::RecordedEvent =
1049 serde_json::from_str(r#"{"timestamp": 0, "category": "app", "name": "opened"}"#)
1050 .unwrap();
1051 assert!(event.flows.is_empty());
1052 }
1053
1054 fn onboarding() -> FlowDefinition {
1060 definition(
1061 "onboarding",
1062 &[
1063 ("onboarding.started", FlowRole::Start),
1064 ("onboarding.finished", FlowRole::End),
1065 ("onboarding.dismissed", FlowRole::End),
1066 ("onboarding.card_shown", FlowRole::Member),
1067 ("onboarding.permission_prompted", FlowRole::Member),
1068 ],
1069 )
1070 }
1071
1072 fn flow_end_metric() -> EventMetric {
1073 EventMetric::new(
1074 CommonMetricData {
1075 category: "glean".into(),
1076 name: "flow_end".into(),
1077 send_in_pings: vec!["events".into()],
1078 lifetime: Lifetime::Ping,
1079 ..Default::default()
1080 },
1081 vec![],
1082 )
1083 }
1084
1085 fn flow_ends(glean: &Glean) -> Vec<HashMap<String, String>> {
1086 flow_end_metric()
1087 .get_value(glean, "events")
1088 .unwrap_or_default()
1089 .into_iter()
1090 .map(|e| e.extra.unwrap())
1091 .collect()
1092 }
1093
1094 fn exit_extras(flow: &str, seq: u64, terminating_event: &str) -> HashMap<String, String> {
1095 [
1096 ("flow_name", flow.to_string()),
1097 ("flow_seq", seq.to_string()),
1098 ("reason", "exit".to_string()),
1099 ("terminating_event", terminating_event.to_string()),
1100 ]
1101 .into_iter()
1102 .map(|(k, v)| (k.to_string(), v))
1103 .collect()
1104 }
1105
1106 fn record(glean: &Glean, category: &str, name: &str) -> bool {
1107 event(category, name, true).record_sync(glean, 0, HashMap::new(), 0)
1108 }
1109
1110 #[test]
1112 fn worked_example() {
1113 let (mut glean, _t) = glean_with_flows(vec![onboarding()]);
1114
1115 glean.session_start();
1116 let steps = [
1117 ("onboarding", "started"),
1118 ("onboarding", "card_shown"),
1119 ("onboarding", "permission_prompted"),
1120 ("settings", "opened"),
1121 ("onboarding", "card_shown"),
1122 ("onboarding", "dismissed"),
1123 ];
1124 for (category, name) in steps {
1127 event(category, name, true).record_sync(
1128 &glean,
1129 crate::get_timestamp_ms(),
1130 HashMap::new(),
1131 0,
1132 );
1133 }
1134 glean.session_end(None);
1135
1136 let json = glean
1137 .event_storage()
1138 .snapshot_as_json(&glean, "events", false)
1139 .unwrap();
1140 let rows: Vec<(String, Option<u64>, serde_json::Value)> = json
1141 .as_array()
1142 .unwrap()
1143 .iter()
1144 .map(|e| {
1145 (
1146 format!(
1147 "{}.{}",
1148 e["category"].as_str().unwrap(),
1149 e["name"].as_str().unwrap()
1150 ),
1151 e["session"]["event_seq"].as_u64(),
1152 e.get("flows").cloned().unwrap_or(serde_json::Value::Null),
1153 )
1154 })
1155 .collect();
1156
1157 let tagged = serde_json::json!([{"name": "onboarding", "seq": 0}]);
1158 let none = serde_json::Value::Null;
1159 let expected = vec![
1160 ("glean.session_start", None, none.clone()),
1161 ("onboarding.started", Some(0), tagged.clone()),
1162 ("onboarding.card_shown", Some(1), tagged.clone()),
1163 ("onboarding.permission_prompted", Some(2), tagged.clone()),
1164 ("settings.opened", Some(3), none.clone()),
1165 ("onboarding.card_shown", Some(4), tagged.clone()),
1166 ("onboarding.dismissed", Some(5), tagged.clone()),
1167 ("glean.flow_end", Some(6), none.clone()),
1168 ("glean.session_end", None, none),
1169 ];
1170 let expected: Vec<(String, Option<u64>, serde_json::Value)> = expected
1171 .into_iter()
1172 .map(|(name, seq, flows)| (name.to_string(), seq, flows))
1173 .collect();
1174 assert_eq!(expected, rows);
1175
1176 assert_eq!(
1177 vec![exit_extras("onboarding", 0, "onboarding.dismissed")],
1178 flow_ends(&glean)
1179 );
1180 }
1181
1182 #[test]
1183 fn entry_event_while_active_keeps_the_existing_instance() {
1184 let (mut glean, _t) = glean_with_flows(vec![onboarding()]);
1185 glean.session_start();
1186
1187 record(&glean, "onboarding", "started");
1188 record(&glean, "onboarding", "started");
1189 record(&glean, "onboarding", "dismissed");
1190
1191 let starts = event("onboarding", "started", true)
1192 .get_value(&glean, "events")
1193 .unwrap();
1194 assert_eq!(vec![entry("onboarding", 0)], starts[0].flows);
1195 assert_eq!(vec![entry("onboarding", 0)], starts[1].flows);
1196 assert_eq!(
1197 vec![exit_extras("onboarding", 0, "onboarding.dismissed")],
1198 flow_ends(&glean)
1199 );
1200 }
1201
1202 #[test]
1203 fn exit_event_while_inactive_does_nothing() {
1204 let (mut glean, _t) = glean_with_flows(vec![onboarding()]);
1205 glean.session_start();
1206
1207 record(&glean, "onboarding", "dismissed");
1208
1209 let dismissed = event("onboarding", "dismissed", true)
1210 .get_value(&glean, "events")
1211 .unwrap();
1212 assert!(dismissed[0].flows.is_empty());
1213 assert!(flow_ends(&glean).is_empty());
1214 }
1215
1216 #[test]
1217 fn second_attempt_in_a_session_is_a_new_instance() {
1218 let (mut glean, _t) = glean_with_flows(vec![onboarding()]);
1219 glean.session_start();
1220
1221 record(&glean, "onboarding", "started");
1222 record(&glean, "onboarding", "dismissed");
1223 record(&glean, "onboarding", "started");
1224 record(&glean, "onboarding", "card_shown");
1225 record(&glean, "onboarding", "finished");
1226
1227 let shown = event("onboarding", "card_shown", true)
1228 .get_value(&glean, "events")
1229 .unwrap();
1230 assert_eq!(vec![entry("onboarding", 1)], shown[0].flows);
1231 assert_eq!(
1232 vec![
1233 exit_extras("onboarding", 0, "onboarding.dismissed"),
1234 exit_extras("onboarding", 1, "onboarding.finished"),
1235 ],
1236 flow_ends(&glean)
1237 );
1238 }
1239
1240 #[test]
1241 fn no_instance_opens_without_an_active_session() {
1242 let (glean, _t) = glean_with_flows(vec![onboarding()]);
1243
1244 record(&glean, "onboarding", "started");
1245
1246 assert!(glean.flow_state.lock().unwrap().active.is_empty());
1247 }
1248
1249 #[test]
1250 fn a_suppressed_entry_event_opens_nothing() {
1251 let (mut glean, _t) = glean_with_flows(vec![onboarding()]);
1252 glean.session_start();
1253
1254 let disabled = EventMetric::new(
1255 CommonMetricData {
1256 category: "onboarding".into(),
1257 name: "started".into(),
1258 send_in_pings: vec!["events".into()],
1259 lifetime: Lifetime::Ping,
1260 in_session: true,
1261 disabled: true,
1262 ..Default::default()
1263 },
1264 vec![],
1265 );
1266 disabled.record_sync(&glean, 0, HashMap::new(), 0);
1267
1268 assert!(glean.flow_state.lock().unwrap().active.is_empty());
1269 }
1270
1271 #[test]
1272 fn one_event_can_end_one_flow_and_start_another() {
1273 let (mut glean, _t) = glean_with_flows(vec![
1274 definition(
1275 "browse",
1276 &[
1277 ("browse.started", FlowRole::Start),
1278 ("checkout.started", FlowRole::End),
1279 ],
1280 ),
1281 definition(
1282 "checkout",
1283 &[
1284 ("checkout.started", FlowRole::Start),
1285 ("checkout.paid", FlowRole::End),
1286 ],
1287 ),
1288 ]);
1289 glean.session_start();
1290
1291 record(&glean, "browse", "started");
1292 record(&glean, "checkout", "started");
1293
1294 let started = event("checkout", "started", true)
1295 .get_value(&glean, "events")
1296 .unwrap();
1297 assert_eq!(
1299 vec![entry("browse", 0), entry("checkout", 1)],
1300 started[0].flows
1301 );
1302 assert_eq!(
1303 vec![exit_extras("browse", 0, "checkout.started")],
1304 flow_ends(&glean)
1305 );
1306 let checkout = glean.flow_registry.find("checkout").unwrap();
1307 assert_eq!(
1308 Some(1),
1309 glean
1310 .flow_state
1311 .lock()
1312 .unwrap()
1313 .active
1314 .get(&checkout)
1315 .map(|i| i.seq)
1316 );
1317 }
1318
1319 #[test]
1320 fn event_ending_two_flows_records_a_flow_end_for_each_in_name_order() {
1321 let shared_exit = ("app.closed", FlowRole::End);
1322 let (mut glean, _t) = glean_with_flows(vec![
1323 definition("zeta", &[("zeta.started", FlowRole::Start), shared_exit]),
1324 definition("alpha", &[("alpha.started", FlowRole::Start), shared_exit]),
1325 ]);
1326 glean.session_start();
1327
1328 record(&glean, "zeta", "started");
1329 record(&glean, "alpha", "started");
1330 record(&glean, "app", "closed");
1331
1332 assert_eq!(
1333 vec![
1334 exit_extras("alpha", 1, "app.closed"),
1335 exit_extras("zeta", 0, "app.closed"),
1336 ],
1337 flow_ends(&glean)
1338 );
1339 }
1340
1341 #[test]
1342 fn flow_end_carries_a_wall_clock_glean_timestamp() {
1343 let dir = tempfile::tempdir().unwrap();
1344 let mut cfg = test_cfg(&dir, vec![onboarding()]);
1345 cfg.enable_event_timestamps = true;
1346 let mut glean = Glean::new(cfg).unwrap();
1347 glean.session_start();
1348
1349 let before = Utc::now().timestamp_millis();
1350 record(&glean, "onboarding", "started");
1351 record(&glean, "onboarding", "dismissed");
1352 let after = Utc::now().timestamp_millis();
1353
1354 let json = glean
1355 .event_storage()
1356 .snapshot_as_json(&glean, "events", false)
1357 .unwrap();
1358 let flow_end = json
1359 .as_array()
1360 .unwrap()
1361 .iter()
1362 .find(|e| e["category"] == "glean" && e["name"] == "flow_end")
1363 .unwrap();
1364 let glean_timestamp: i64 = flow_end["extra"]["glean_timestamp"]
1365 .as_str()
1366 .unwrap()
1367 .parse()
1368 .unwrap();
1369 assert!((before..=after).contains(&glean_timestamp));
1370 }
1371
1372 #[test]
1373 fn ping_submitted_by_flow_end_is_reported_to_the_caller() {
1374 let dir = tempfile::tempdir().unwrap();
1375 let mut cfg = test_cfg(&dir, vec![onboarding()]);
1376 cfg.max_events = Some(4);
1378 let mut glean = Glean::new(cfg).unwrap();
1379 glean.session_start();
1380
1381 assert!(!record(&glean, "onboarding", "started"));
1382 assert!(
1383 record(&glean, "onboarding", "dismissed"),
1384 "the ping submitted by flow_end must be reported by the exit event's recording"
1385 );
1386 }
1387
1388 fn two_flows() -> Vec<FlowDefinition> {
1393 vec![
1394 definition(
1395 "alpha",
1396 &[
1397 ("alpha.started", FlowRole::Start),
1398 ("alpha.finished", FlowRole::End),
1399 ("app.card_shown", FlowRole::Member),
1400 ],
1401 ),
1402 definition(
1403 "zeta",
1404 &[
1405 ("zeta.started", FlowRole::Start),
1406 ("zeta.finished", FlowRole::End),
1407 ],
1408 ),
1409 ]
1410 }
1411
1412 fn session_end_extras(flow: &str, seq: u64) -> HashMap<String, String> {
1413 [
1414 ("flow_name", flow.to_string()),
1415 ("flow_seq", seq.to_string()),
1416 ("reason", "session_end".to_string()),
1417 ]
1418 .into_iter()
1419 .map(|(k, v)| (k.to_string(), v))
1420 .collect()
1421 }
1422
1423 fn ping_order(glean: &Glean) -> Vec<(String, Option<String>, Option<u64>)> {
1426 glean
1427 .event_storage()
1428 .snapshot_as_json(glean, "events", false)
1429 .unwrap()
1430 .as_array()
1431 .unwrap()
1432 .iter()
1433 .map(|e| {
1434 (
1435 format!(
1436 "{}.{}",
1437 e["category"].as_str().unwrap(),
1438 e["name"].as_str().unwrap()
1439 ),
1440 e["session"]["session_id"].as_str().map(str::to_string),
1441 e["session"]["event_seq"].as_u64(),
1442 )
1443 })
1444 .collect()
1445 }
1446
1447 fn record_now(glean: &Glean, category: &str, name: &str) {
1448 event(category, name, true).record_sync(
1449 glean,
1450 crate::get_timestamp_ms(),
1451 HashMap::new(),
1452 0,
1453 );
1454 }
1455
1456 #[test]
1457 fn session_end_closes_instances_in_reverse_order_of_opening_before_session_end() {
1458 let (mut glean, _t) = glean_with_flows(two_flows());
1459 glean.session_start();
1460 let session_id = glean.session_manager().session_id().unwrap().to_string();
1461
1462 record_now(&glean, "zeta", "started");
1464 record_now(&glean, "alpha", "started");
1465 record_now(&glean, "app", "card_shown");
1466 glean.session_end(None);
1467
1468 let id = Some(session_id);
1469 assert_eq!(
1470 vec![
1471 ("glean.session_start".to_string(), None, None),
1472 ("zeta.started".to_string(), id.clone(), Some(0)),
1473 ("alpha.started".to_string(), id.clone(), Some(1)),
1474 ("app.card_shown".to_string(), id.clone(), Some(2)),
1475 ("glean.flow_end".to_string(), id.clone(), Some(3)),
1476 ("glean.flow_end".to_string(), id, Some(4)),
1477 ("glean.session_end".to_string(), None, None),
1478 ],
1479 ping_order(&glean)
1480 );
1481 assert_eq!(
1482 vec![
1483 session_end_extras("alpha", 1),
1484 session_end_extras("zeta", 0)
1485 ],
1486 flow_ends(&glean)
1487 );
1488 assert!(glean.flow_state.lock().unwrap().active.is_empty());
1489 }
1490
1491 #[test]
1492 fn replaced_session_closes_instances_in_the_old_session() {
1493 let (mut glean, _t) = glean_with_flows(two_flows());
1494 glean.session_start();
1495 let old_session = glean.session_manager().session_id().unwrap().to_string();
1496 record_now(&glean, "alpha", "started");
1497
1498 glean.session_start();
1499
1500 let flow_end = flow_end_metric()
1501 .get_value(&glean, "events")
1502 .unwrap()
1503 .pop()
1504 .unwrap();
1505 assert_eq!(Some(session_end_extras("alpha", 0)), flow_end.extra);
1506 assert_eq!(
1507 old_session,
1508 flow_end.session.expect("flow_end is in-session").session_id
1509 );
1510 assert!(glean.flow_state.lock().unwrap().active.is_empty());
1511 }
1512
1513 #[test]
1514 fn auto_mode_timeout_closes_instances_in_the_timed_out_session() {
1515 let dir = tempfile::tempdir().unwrap();
1516 let mut cfg = test_cfg(&dir, two_flows());
1517 cfg.session_mode = SessionMode::Auto;
1518 cfg.session_inactivity_timeout_ms = 1;
1519 let mut glean = Glean::new(cfg).unwrap();
1520
1521 glean.handle_client_active();
1522 let old_session = glean.session_manager().session_id().unwrap().to_string();
1523 record_now(&glean, "alpha", "started");
1524 glean.handle_client_inactive();
1525 std::thread::sleep(std::time::Duration::from_millis(5));
1527
1528 glean.handle_client_active();
1530 assert_ne!(
1531 old_session,
1532 glean.session_manager().session_id().unwrap().to_string()
1533 );
1534
1535 let flow_end = flow_end_metric()
1536 .get_value(&glean, "events")
1537 .expect("flow_end should be recorded when the timeout is noticed")
1538 .pop()
1539 .unwrap();
1540 assert_eq!(Some(session_end_extras("alpha", 0)), flow_end.extra);
1541 assert_eq!(
1542 old_session,
1543 flow_end.session.expect("flow_end is in-session").session_id
1544 );
1545 }
1546
1547 #[test]
1548 fn flow_seq_restarts_at_zero_in_each_session() {
1549 let (mut glean, _t) = glean_with_flows(two_flows());
1550
1551 glean.session_start();
1552 record_now(&glean, "alpha", "started");
1553 record_now(&glean, "alpha", "finished");
1554 record_now(&glean, "zeta", "started");
1555 glean.session_end(None);
1556
1557 glean.session_start();
1558 record_now(&glean, "alpha", "started");
1559
1560 let starts = event("alpha", "started", true)
1561 .get_value(&glean, "events")
1562 .unwrap();
1563 assert_eq!(vec![entry("alpha", 0)], starts[0].flows);
1564 assert_eq!(vec![entry("alpha", 0)], starts[1].flows);
1565 }
1566
1567 #[test]
1568 fn session_end_with_no_active_instances_records_no_flow_end() {
1569 let (mut glean, _t) = glean_with_flows(two_flows());
1570 glean.session_start();
1571 record_now(&glean, "alpha", "started");
1572 record_now(&glean, "alpha", "finished");
1573 glean.session_end(None);
1574
1575 assert_eq!(
1577 vec![exit_extras("alpha", 0, "alpha.finished")],
1578 flow_ends(&glean)
1579 );
1580 }
1581
1582 const TIMEOUT_MS: u64 = 60_000;
1587
1588 fn timed_flows() -> Vec<FlowDefinition> {
1590 let mut timed = onboarding();
1591 timed.auto_close_timeout_ms = Some(TIMEOUT_MS);
1592 let untimed = definition(
1593 "untimed",
1594 &[
1595 ("untimed.started", FlowRole::Start),
1596 ("untimed.finished", FlowRole::End),
1597 ],
1598 );
1599 vec![timed, untimed]
1600 }
1601
1602 fn backdate(glean: &Glean, flow: &str, ms: u64) {
1604 let id = glean.flow_registry.find(flow).unwrap();
1605 let mut state = glean.flow_state.lock().unwrap();
1606 let instance = state.active.get_mut(&id).expect("flow should be active");
1607 instance.opened_at_ms -= ms as i64;
1608 }
1609
1610 fn is_active(glean: &Glean, flow: &str) -> bool {
1611 let id = glean.flow_registry.find(flow).unwrap();
1612 glean.flow_state.lock().unwrap().active.contains_key(&id)
1613 }
1614
1615 fn timeout_extras(flow: &str, seq: u64) -> HashMap<String, String> {
1616 [
1617 ("flow_name", flow.to_string()),
1618 ("flow_seq", seq.to_string()),
1619 ("reason", "timeout".to_string()),
1620 ]
1621 .into_iter()
1622 .map(|(k, v)| (k.to_string(), v))
1623 .collect()
1624 }
1625
1626 fn queued_events(dir: &tempfile::TempDir) -> Vec<serde_json::Value> {
1628 let Ok(entries) = std::fs::read_dir(dir.path().join("pending_pings")) else {
1629 return Vec::new();
1630 };
1631 entries
1632 .filter_map(|entry| std::fs::read_to_string(entry.ok()?.path()).ok())
1633 .filter_map(|contents| {
1634 let mut lines = contents.lines();
1635 let url = lines.next()?;
1636 if !url.contains("/events/") {
1637 return None;
1638 }
1639 serde_json::from_str::<serde_json::Value>(lines.next()?).ok()
1640 })
1641 .flat_map(|ping| ping["events"].as_array().cloned().unwrap_or_default())
1642 .collect()
1643 }
1644
1645 #[test]
1646 fn member_event_after_expiry_closes_the_instance_before_it_is_recorded() {
1647 let (mut glean, _t) = glean_with_flows(timed_flows());
1648 glean.session_start();
1649 record_now(&glean, "onboarding", "started");
1650 backdate(&glean, "onboarding", TIMEOUT_MS);
1651
1652 record_now(&glean, "onboarding", "card_shown");
1653
1654 let shown = event("onboarding", "card_shown", true)
1655 .get_value(&glean, "events")
1656 .unwrap();
1657 assert!(
1658 shown[0].flows.is_empty(),
1659 "noticing event must not be tagged"
1660 );
1661 assert_eq!(vec![timeout_extras("onboarding", 0)], flow_ends(&glean));
1662
1663 let order: Vec<(String, Option<u64>)> = ping_order(&glean)
1665 .into_iter()
1666 .map(|(name, _, seq)| (name, seq))
1667 .collect();
1668 assert_eq!(
1669 vec![
1670 ("glean.session_start".to_string(), None),
1671 ("onboarding.started".to_string(), Some(0)),
1672 ("glean.flow_end".to_string(), Some(1)),
1673 ("onboarding.card_shown".to_string(), Some(2)),
1674 ],
1675 order
1676 );
1677 }
1678
1679 #[test]
1680 fn entry_event_after_expiry_opens_a_new_instance_in_the_same_recording() {
1681 let (mut glean, _t) = glean_with_flows(timed_flows());
1682 glean.session_start();
1683 record_now(&glean, "onboarding", "started");
1684 backdate(&glean, "onboarding", TIMEOUT_MS);
1685
1686 record_now(&glean, "onboarding", "started");
1687
1688 let starts = event("onboarding", "started", true)
1689 .get_value(&glean, "events")
1690 .unwrap();
1691 assert_eq!(vec![entry("onboarding", 1)], starts[1].flows);
1692 assert_eq!(vec![timeout_extras("onboarding", 0)], flow_ends(&glean));
1693 assert!(is_active(&glean, "onboarding"));
1694 }
1695
1696 #[test]
1697 fn exit_event_after_expiry_records_only_the_timeout() {
1698 let (mut glean, _t) = glean_with_flows(timed_flows());
1699 glean.session_start();
1700 record_now(&glean, "onboarding", "started");
1701 backdate(&glean, "onboarding", TIMEOUT_MS);
1702
1703 record_now(&glean, "onboarding", "finished");
1704
1705 let finished = event("onboarding", "finished", true)
1706 .get_value(&glean, "events")
1707 .unwrap();
1708 assert!(finished[0].flows.is_empty());
1709 assert_eq!(vec![timeout_extras("onboarding", 0)], flow_ends(&glean));
1710 }
1711
1712 #[test]
1713 fn instance_within_its_timeout_is_untouched() {
1714 let (mut glean, _t) = glean_with_flows(timed_flows());
1715 glean.session_start();
1716 record_now(&glean, "onboarding", "started");
1717 backdate(&glean, "onboarding", TIMEOUT_MS - 1_000);
1718
1719 record_now(&glean, "onboarding", "card_shown");
1720
1721 let shown = event("onboarding", "card_shown", true)
1722 .get_value(&glean, "events")
1723 .unwrap();
1724 assert_eq!(vec![entry("onboarding", 0)], shown[0].flows);
1725 assert!(flow_ends(&glean).is_empty());
1726 }
1727
1728 #[test]
1729 fn flow_without_a_timeout_never_times_out() {
1730 let (mut glean, _t) = glean_with_flows(timed_flows());
1731 glean.session_start();
1732 record_now(&glean, "untimed", "started");
1733 backdate(&glean, "untimed", 365 * 24 * 60 * 60 * 1000);
1734
1735 record_now(&glean, "untimed", "started");
1736
1737 assert!(flow_ends(&glean).is_empty());
1738 assert!(is_active(&glean, "untimed"));
1739 }
1740
1741 #[test]
1742 fn an_unrelated_event_does_not_notice_an_expiry() {
1743 let (mut glean, _t) = glean_with_flows(timed_flows());
1744 glean.session_start();
1745 record_now(&glean, "onboarding", "started");
1746 backdate(&glean, "onboarding", TIMEOUT_MS);
1747
1748 record_now(&glean, "settings", "opened");
1749
1750 assert!(flow_ends(&glean).is_empty());
1751 assert!(is_active(&glean, "onboarding"));
1752 }
1753
1754 #[test]
1755 fn going_inactive_closes_expired_instances_into_that_events_ping() {
1756 let dir = tempfile::tempdir().unwrap();
1757 let mut cfg = test_cfg(&dir, timed_flows());
1758 cfg.session_mode = SessionMode::Auto;
1759 cfg.session_inactivity_timeout_ms = 30 * 60 * 1000;
1760 let mut glean = Glean::new(cfg).unwrap();
1761
1762 glean.handle_client_active();
1763 record_now(&glean, "onboarding", "started");
1764 record_now(&glean, "untimed", "started");
1765 backdate(&glean, "onboarding", TIMEOUT_MS);
1766
1767 glean.handle_client_inactive();
1768
1769 assert!(!is_active(&glean, "onboarding"));
1770 assert!(is_active(&glean, "untimed"));
1771 let flow_ends: Vec<serde_json::Value> = queued_events(&dir)
1772 .into_iter()
1773 .filter(|e| e["category"] == "glean" && e["name"] == "flow_end")
1774 .collect();
1775 assert_eq!(1, flow_ends.len());
1776 assert_eq!("timeout", flow_ends[0]["extra"]["reason"]);
1777 assert!(
1778 flow_ends[0]["session"]["event_seq"].is_u64(),
1779 "flow_end must be recorded in-session"
1780 );
1781 }
1782
1783 #[test]
1784 fn coming_back_to_a_resumed_session_closes_expired_instances() {
1785 let dir = tempfile::tempdir().unwrap();
1786 let mut cfg = test_cfg(&dir, timed_flows());
1787 cfg.session_mode = SessionMode::Auto;
1788 cfg.session_inactivity_timeout_ms = 30 * 60 * 1000;
1789 let mut glean = Glean::new(cfg).unwrap();
1790
1791 glean.handle_client_active();
1792 let session_id = glean.session_manager().session_id().unwrap().to_string();
1793 record_now(&glean, "onboarding", "started");
1794 glean.handle_client_inactive();
1795 backdate(&glean, "onboarding", TIMEOUT_MS);
1796
1797 glean.handle_client_active();
1798
1799 assert_eq!(
1800 session_id,
1801 glean.session_manager().session_id().unwrap().to_string(),
1802 "session should have resumed"
1803 );
1804 let flow_end = flow_end_metric()
1805 .get_value(&glean, "events")
1806 .expect("flow_end should be recorded on resume")
1807 .pop()
1808 .unwrap();
1809 assert_eq!(Some(timeout_extras("onboarding", 0)), flow_end.extra);
1810 assert_eq!(session_id, flow_end.session.unwrap().session_id);
1811 }
1812
1813 #[test]
1814 fn session_end_records_timeout_for_expired_instances_and_session_end_for_the_rest() {
1815 let (mut glean, _t) = glean_with_flows(timed_flows());
1816 glean.session_start();
1817 record_now(&glean, "onboarding", "started");
1818 record_now(&glean, "untimed", "started");
1819 backdate(&glean, "onboarding", TIMEOUT_MS);
1820
1821 glean.session_end(None);
1822
1823 assert_eq!(
1824 vec![
1825 timeout_extras("onboarding", 0),
1826 session_end_extras("untimed", 1)
1827 ],
1828 flow_ends(&glean)
1829 );
1830 }
1831
1832 fn auto_cfg(dir: &tempfile::TempDir, flows: Vec<FlowDefinition>) -> InternalConfiguration {
1837 let mut cfg = test_cfg(dir, flows);
1838 cfg.session_mode = SessionMode::Auto;
1839 cfg.session_inactivity_timeout_ms = 30 * 60 * 1000;
1840 cfg
1841 }
1842
1843 fn restart(glean: Glean, cfg: InternalConfiguration) -> Glean {
1845 drop(glean);
1846 Glean::new(cfg).unwrap()
1847 }
1848
1849 fn active_seqs(glean: &Glean) -> Vec<(String, u64)> {
1850 glean
1851 .flow_state
1852 .lock()
1853 .unwrap()
1854 .active
1855 .iter()
1856 .map(|(flow, i)| (glean.flow_registry.flow(*flow).name.clone(), i.seq))
1857 .collect()
1858 }
1859
1860 fn backdate_persisted(glean: &Glean, flow: &str, ms: u64) {
1862 let mut persisted = read_persisted(glean).expect("flow state should be persisted");
1863 let instance = persisted
1864 .instances
1865 .iter_mut()
1866 .find(|i| i.flow_name == flow)
1867 .expect("instance should be persisted");
1868 instance.opened_at_ms -= ms as i64;
1869 make_flow_state_metric().set_sync(glean, serde_json::to_string(&persisted).unwrap());
1870 }
1871
1872 fn abnormal_extras(flow: &str, seq: u64, session_id: &str) -> HashMap<String, String> {
1873 [
1874 ("flow_name", flow.to_string()),
1875 ("flow_seq", seq.to_string()),
1876 ("reason", "abnormal".to_string()),
1877 ("session_id", session_id.to_string()),
1878 ]
1879 .into_iter()
1880 .map(|(k, v)| (k.to_string(), v))
1881 .collect()
1882 }
1883
1884 #[test]
1885 fn opening_and_closing_persist_instances_and_the_counter() {
1886 let (mut glean, _t) = glean_with_flows(two_flows());
1887 glean.session_start();
1888 let session_id = glean.session_manager().session_id().unwrap().to_string();
1889
1890 record_now(&glean, "alpha", "started");
1891 record_now(&glean, "zeta", "started");
1892 record_now(&glean, "zeta", "finished");
1893
1894 assert_eq!(
1895 Some(PersistedFlowState {
1896 session_id: session_id.clone(),
1897 next_seq: 2,
1898 instances: vec![PersistedInstance {
1899 flow_name: "alpha".into(),
1900 flow_seq: 0,
1901 session_id,
1902 opened_at_ms: read_persisted(&glean).unwrap().instances[0].opened_at_ms,
1903 }],
1904 }),
1905 read_persisted(&glean)
1906 );
1907
1908 glean.session_end(None);
1909 assert!(read_persisted(&glean).is_none(), "cleared at session end");
1910 }
1911
1912 #[test]
1913 fn clean_restart_restores_instances_and_the_counter() {
1914 let dir = tempfile::tempdir().unwrap();
1915 let mut glean = Glean::new(auto_cfg(&dir, two_flows())).unwrap();
1916 glean.handle_client_active();
1917 let session_id = glean.session_manager().session_id().unwrap().to_string();
1918 record_now(&glean, "alpha", "started");
1919 record_now(&glean, "zeta", "started");
1920 record_now(&glean, "zeta", "finished");
1921 glean.handle_client_inactive();
1922
1923 let mut glean = restart(glean, auto_cfg(&dir, two_flows()));
1924 assert_eq!(vec![("alpha".to_string(), 0)], active_seqs(&glean));
1925
1926 glean.handle_client_active();
1927 assert_eq!(
1928 session_id,
1929 glean.session_manager().session_id().unwrap().to_string()
1930 );
1931 record_now(&glean, "app", "card_shown");
1932 record_now(&glean, "zeta", "started");
1933
1934 let shown = event("app", "card_shown", true)
1935 .get_value(&glean, "events")
1936 .unwrap();
1937 assert_eq!(vec![entry("alpha", 0)], shown[0].flows);
1938 assert_eq!(
1940 vec![("alpha".to_string(), 0), ("zeta".to_string(), 2)],
1941 active_seqs(&glean)
1942 );
1943 }
1944
1945 #[test]
1946 fn instance_of_an_unregistered_flow_is_discarded_on_restore_without_a_flow_end() {
1947 let dir = tempfile::tempdir().unwrap();
1948 let mut glean = Glean::new(auto_cfg(&dir, two_flows())).unwrap();
1949 glean.handle_client_active();
1950 record_now(&glean, "alpha", "started");
1951 record_now(&glean, "zeta", "started");
1952 glean.handle_client_inactive();
1953
1954 let zeta_only: Vec<FlowDefinition> = two_flows()
1956 .into_iter()
1957 .filter(|f| f.name == "zeta")
1958 .collect();
1959 let glean = restart(glean, auto_cfg(&dir, zeta_only));
1960
1961 assert_eq!(vec![("zeta".to_string(), 1)], active_seqs(&glean));
1962 assert!(flow_ends(&glean).is_empty());
1963 let persisted = read_persisted(&glean).unwrap();
1964 assert_eq!(
1965 vec!["zeta"],
1966 persisted
1967 .instances
1968 .iter()
1969 .map(|i| i.flow_name.as_str())
1970 .collect::<Vec<_>>()
1971 );
1972 }
1973
1974 #[test]
1975 fn instance_of_a_now_disabled_flow_is_restored() {
1976 let dir = tempfile::tempdir().unwrap();
1977 let mut glean = Glean::new(auto_cfg(&dir, two_flows())).unwrap();
1978 glean.handle_client_active();
1979 record_now(&glean, "alpha", "started");
1980 glean.handle_client_inactive();
1981
1982 let mut flows = two_flows();
1983 flows[0].disabled = true;
1984 let glean = restart(glean, auto_cfg(&dir, flows));
1985
1986 assert_eq!(vec![("alpha".to_string(), 0)], active_seqs(&glean));
1987 }
1988
1989 #[test]
1990 fn instance_that_expired_while_not_running_is_closed_on_restore() {
1991 let dir = tempfile::tempdir().unwrap();
1992 let mut glean = Glean::new(auto_cfg(&dir, timed_flows())).unwrap();
1993 glean.handle_client_active();
1994 let session_id = glean.session_manager().session_id().unwrap().to_string();
1995 record_now(&glean, "onboarding", "started");
1996 glean.handle_client_inactive();
1997 backdate_persisted(&glean, "onboarding", TIMEOUT_MS);
1998
1999 let glean = restart(glean, auto_cfg(&dir, timed_flows()));
2000
2001 assert!(active_seqs(&glean).is_empty());
2002 let flow_end = flow_end_metric()
2003 .get_value(&glean, "events")
2004 .expect("flow_end should be recorded at restore")
2005 .pop()
2006 .unwrap();
2007 assert_eq!(Some(timeout_extras("onboarding", 0)), flow_end.extra);
2008 let session = flow_end.session.expect("recorded in the resumed session");
2009 assert_eq!(session_id, session.session_id);
2010 assert!(
2011 !glean.session_manager().is_active(),
2012 "session stays inactive"
2013 );
2014 assert!(read_persisted(&glean).unwrap().instances.is_empty());
2015 }
2016
2017 #[test]
2018 fn dirty_restart_closes_persisted_instances_as_abnormal_before_session_end() {
2019 let dir = tempfile::tempdir().unwrap();
2020 let mut glean = Glean::new(auto_cfg(&dir, two_flows())).unwrap();
2021 glean.handle_client_active();
2023 let session_id = glean.session_manager().session_id().unwrap().to_string();
2024 record_now(&glean, "zeta", "started");
2025 record_now(&glean, "alpha", "started");
2026
2027 let mut glean = restart(glean, auto_cfg(&dir, two_flows()));
2028 assert!(active_seqs(&glean).is_empty(), "not restored after a crash");
2029 glean.recover_session_on_dirty_flag();
2030
2031 assert_eq!(
2032 vec![
2033 abnormal_extras("alpha", 1, &session_id),
2034 abnormal_extras("zeta", 0, &session_id),
2035 ],
2036 flow_ends(&glean)
2037 );
2038 let order: Vec<(String, Option<u64>)> = ping_order(&glean)
2039 .into_iter()
2040 .filter(|(name, _, _)| name.starts_with("glean."))
2041 .map(|(name, _, seq)| (name, seq))
2042 .collect();
2043 assert_eq!(
2044 vec![
2045 ("glean.flow_end".to_string(), None),
2046 ("glean.flow_end".to_string(), None),
2047 ("glean.session_end".to_string(), None),
2048 ],
2049 order,
2050 "abnormal flow_ends are out-of-session and precede the recovery session_end"
2051 );
2052 assert!(read_persisted(&glean).is_none());
2053 }
2054
2055 #[test]
2056 fn dirty_restart_of_an_inactive_session_closes_instances_as_abnormal() {
2057 let dir = tempfile::tempdir().unwrap();
2058 let mut glean = Glean::new(auto_cfg(&dir, two_flows())).unwrap();
2059 glean.handle_client_active();
2060 let session_id = glean.session_manager().session_id().unwrap().to_string();
2061 record_now(&glean, "alpha", "started");
2062 glean.handle_client_inactive();
2063 glean.set_dirty_flag(true);
2066
2067 let mut glean = restart(glean, auto_cfg(&dir, two_flows()));
2068 assert!(active_seqs(&glean).is_empty(), "not restored after a crash");
2069 glean.recover_session_on_dirty_flag();
2070
2071 assert_eq!(
2072 vec![abnormal_extras("alpha", 0, &session_id)],
2073 flow_ends(&glean)
2074 );
2075 }
2076
2077 #[test]
2078 fn dirty_restart_skips_instances_of_unregistered_flows() {
2079 let dir = tempfile::tempdir().unwrap();
2080 let mut glean = Glean::new(auto_cfg(&dir, two_flows())).unwrap();
2081 glean.handle_client_active();
2082 let session_id = glean.session_manager().session_id().unwrap().to_string();
2083 record_now(&glean, "alpha", "started");
2084 record_now(&glean, "zeta", "started");
2085
2086 let zeta_only: Vec<FlowDefinition> = two_flows()
2087 .into_iter()
2088 .filter(|f| f.name == "zeta")
2089 .collect();
2090 let mut glean = restart(glean, auto_cfg(&dir, zeta_only));
2091 glean.recover_session_on_dirty_flag();
2092
2093 assert_eq!(
2094 vec![abnormal_extras("zeta", 1, &session_id)],
2095 flow_ends(&glean)
2096 );
2097 }
2098
2099 #[test]
2100 fn session_abandoned_on_mode_change_closes_instances_as_abnormal() {
2101 let dir = tempfile::tempdir().unwrap();
2102 let mut glean = Glean::new(auto_cfg(&dir, two_flows())).unwrap();
2103 glean.handle_client_active();
2104 let session_id = glean.session_manager().session_id().unwrap().to_string();
2105 record_now(&glean, "alpha", "started");
2106 glean.handle_client_inactive();
2107
2108 let mut cfg = auto_cfg(&dir, two_flows());
2109 cfg.session_mode = SessionMode::Lifecycle;
2110 let glean = restart(glean, cfg);
2111
2112 assert_eq!(
2113 vec![abnormal_extras("alpha", 0, &session_id)],
2114 flow_ends(&glean)
2115 );
2116 let order: Vec<String> = ping_order(&glean)
2117 .into_iter()
2118 .map(|(name, _, _)| name)
2119 .collect();
2120 assert_eq!(vec!["glean.flow_end", "glean.session_end"], order);
2121 assert!(active_seqs(&glean).is_empty());
2122 assert!(read_persisted(&glean).is_none());
2123 }
2124
2125 #[test]
2126 fn instances_of_a_session_that_was_not_resumed_are_discarded() {
2127 let dir = tempfile::tempdir().unwrap();
2128 let mut glean = Glean::new(auto_cfg(&dir, two_flows())).unwrap();
2129 glean.handle_client_active();
2130 record_now(&glean, "alpha", "started");
2131 glean.set_dirty_flag(false);
2134
2135 let glean = restart(glean, auto_cfg(&dir, two_flows()));
2136
2137 assert!(active_seqs(&glean).is_empty());
2138 assert!(flow_ends(&glean).is_empty());
2139 assert!(read_persisted(&glean).is_none());
2140 }
2141
2142 #[test]
2143 fn instances_of_a_session_resumed_as_sampled_out_are_discarded() {
2144 let dir = tempfile::tempdir().unwrap();
2145 let mut glean = Glean::new(auto_cfg(&dir, timed_flows())).unwrap();
2146 glean.handle_client_active();
2147 record_now(&glean, "onboarding", "started");
2148 glean.handle_client_inactive();
2149 backdate_persisted(&glean, "onboarding", TIMEOUT_MS);
2150
2151 let mut cfg = auto_cfg(&dir, timed_flows());
2153 cfg.session_sample_rate = 0.0;
2154 let glean = restart(glean, cfg);
2155
2156 assert!(active_seqs(&glean).is_empty());
2157 assert!(flow_ends(&glean).is_empty());
2158 assert!(read_persisted(&glean).is_none());
2159 }
2160
2161 #[test]
2162 fn disabling_upload_resets_flow_state_without_a_flow_end() {
2163 let (mut glean, _t) = glean_with_flows(two_flows());
2164 glean.session_start();
2165 record_now(&glean, "alpha", "started");
2166
2167 glean.set_upload_enabled(false);
2168
2169 assert!(active_seqs(&glean).is_empty());
2170 assert!(read_persisted(&glean).is_none());
2171 assert!(flow_ends(&glean).is_empty());
2172 }
2173}