Skip to main content

glean_core/flows/
mod.rs

1// This Source Code Form is subject to the terms of the Mozilla Public
2// License, v. 2.0. If a copy of the MPL was not distributed with this
3// file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
5//! Flows: declarative, session-scoped funnel instrumentation.
6//!
7//! A flow is a named task type declared in `flows.yaml`. glean_parser turns
8//! each declaration into a [`FlowDefinition`], which the language binding
9//! passes to Glean through its configuration. At init, core inverts those
10//! definitions into a [`FlowRegistry`], keyed by event, so the recording path
11//! resolves everything it needs about an event with a single lookup.
12
13use 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
27// Storage key for persisted flow state, alongside the `session#*` keys.
28const FLOW_STATE_METRIC_NAME: &str = "flows#state";
29
30/// The role an event plays in a flow.
31#[derive(Debug, Clone, Copy, PartialEq, Eq, MallocSizeOf)]
32pub enum FlowRole {
33    /// Recording the event opens an instance of the flow, if none is active.
34    Start,
35    /// Recording the event closes the active instance of the flow, if any.
36    End,
37    /// The event belongs to the flow but does not open or close it.
38    Member,
39}
40
41/// A flow definition, as generated by glean_parser from `flows.yaml`.
42#[derive(Debug, Clone, PartialEq, Eq, MallocSizeOf)]
43pub struct FlowDefinition {
44    /// The flow's name.
45    pub name: String,
46    /// Each member event's identifier (`category.name`), mapped to the role it
47    /// plays in this flow.
48    pub events: HashMap<String, FlowRole>,
49    /// How long an instance may stay open before it is closed with
50    /// `reason: timeout`, in milliseconds. `None` means it never times out.
51    pub auto_close_timeout_ms: Option<u64>,
52    /// Whether the flow ships disabled.
53    pub disabled: bool,
54}
55
56/// An active flow instance an event belongs to, as attached to the recorded event.
57#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize, MallocSizeOf)]
58pub struct FlowEntry {
59    /// The flow's name.
60    pub name: String,
61    /// The instance's sequence number within the session, starting at 0.
62    pub seq: u64,
63}
64
65/// Identifies a registered flow.
66///
67/// Flows are numbered in name order, so sorting by `FlowId` sorts by name.
68#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, MallocSizeOf)]
69pub(crate) struct FlowId(usize);
70
71/// A flow as held by the registry.
72#[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/// The flows a single event takes part in.
80///
81/// Each list is in name order.
82#[derive(Debug, Default, PartialEq, Eq, MallocSizeOf)]
83pub(crate) struct EventFlows {
84    /// Every flow the event belongs to, in any role.
85    pub(crate) member_of: Vec<FlowId>,
86    /// The flows the event opens.
87    pub(crate) starts: Vec<FlowId>,
88    /// The flows the event closes.
89    pub(crate) ends: Vec<FlowId>,
90}
91
92/// The registered flows and the event-to-flow index.
93///
94/// Built once at init and never modified afterwards.
95#[derive(Debug, Default, MallocSizeOf)]
96pub(crate) struct FlowRegistry {
97    /// Registered flows, sorted by name. A [`FlowId`] indexes into this.
98    flows: Vec<RegisteredFlow>,
99    /// Event identifier to the flows that event takes part in.
100    index: HashMap<String, EventFlows>,
101}
102
103impl FlowRegistry {
104    /// Builds the registry from the definitions passed in through the configuration.
105    ///
106    /// Definitions are walked in name order, so every list in the index comes
107    /// out in name order without sorting at record time. glean_parser rejects
108    /// duplicate flow names; if one gets through anyway, the first definition
109    /// wins and the rest are ignored.
110    ///
111    /// Takes a borrow because `Glean::new_for_subprocess()` only holds
112    /// `&InternalConfiguration`; taking ownership would just move the clone
113    /// to the caller. The sort below works on references, so the definitions
114    /// themselves are not copied, only the strings the registry keeps.
115    pub(crate) fn new(definitions: &[FlowDefinition]) -> Self {
116        let mut definitions: Vec<&FlowDefinition> = definitions.iter().collect();
117        // Stable, so among duplicates the first one passed in stays first.
118        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    /// Whether no flows are registered.
155    #[cfg(test)]
156    pub(crate) fn is_empty(&self) -> bool {
157        self.flows.is_empty()
158    }
159
160    /// Looks up the flows an event metric takes part in.
161    ///
162    /// When no flows are registered this is a single emptiness check, made before
163    /// building the metric's identifier, which is all the recording path pays in
164    /// a product that defines no flows.
165    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    /// Looks up the flows an event takes part in, by its base identifier.
173    #[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    /// Returns a registered flow.
182    pub(crate) fn flow(&self, id: FlowId) -> &RegisteredFlow {
183        &self.flows[id.0]
184    }
185
186    /// Finds a registered flow by name.
187    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/// An active flow instance.
196#[derive(Debug, Clone, Copy, PartialEq, Eq)]
197pub(crate) struct ActiveInstance {
198    /// The instance's sequence number within the session.
199    pub(crate) seq: u64,
200    /// When the instance opened, in wall-clock milliseconds since the epoch.
201    ///
202    /// Wall-clock time so that it stays meaningful across restarts.
203    pub(crate) opened_at_ms: i64,
204}
205
206/// The flow instances active in the current session.
207#[derive(Debug, Default)]
208pub(crate) struct FlowState {
209    /// Each active flow, mapped to its instance.
210    pub(crate) active: BTreeMap<FlowId, ActiveInstance>,
211    /// The `flow_seq` the next instance opened in this session will get.
212    pub(crate) next_seq: u64,
213}
214
215impl FlowState {
216    /// Opens an instance of `flow`, unless one is already active.
217    ///
218    /// Opening an already-open flow does nothing: the existing active
219    /// instance is kept, not replaced.
220    ///
221    /// Returns whether an instance was opened.
222    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    /// Removes and returns every active instance, among `candidates`, whose
235    /// flow's `auto_close_timeout` has elapsed since it opened. Returned in
236    /// reverse order of opening.
237    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/// Why a flow instance ended, as reported in `glean.flow_end`.
273#[derive(Debug, Clone, Copy)]
274pub(crate) enum FlowEndReason<'a> {
275    /// An event in the flow's `ends_on` was recorded.
276    Exit {
277        /// The closing event's identifier (`category.name`).
278        terminating_event: &'a str,
279    },
280    /// The flow's `auto_close_timeout` elapsed.
281    Timeout,
282    /// The session ended while the instance was active.
283    SessionEnd,
284    /// The app ended abnormally while the instance was active.
285    Abnormal {
286        /// The session that owned the instance.
287        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
302/// Looks up the flows an event metric's recording can affect.
303///
304/// Takes the `EventMetric` itself, rather than its metadata, because flows are
305/// built from events: `in_session` is not limited to event metrics, but only
306/// an event's recording may open, tag, or close an instance.
307///
308/// Returns `None` unless the metric is in-session and a session is active,
309/// since instances only exist within a session: an event recorded between
310/// sessions neither opens an instance nor is tagged.
311pub(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
319/// Opens an instance of every flow the event starts that has none active.
320///
321/// Nothing is recorded: the entry event itself is tagged with the new instance.
322pub(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    // Every flow must be opened, so this must not short-circuit.
329    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
338/// Closes, with `reason: timeout`, every expired instance of a flow the event
339/// belongs to.
340///
341/// Must be called before the event opens instances or is tagged, so the event
342/// that notices an expiry is not tagged with the expired instance, and an entry
343/// event for that flow opens a new one in the same recording.
344///
345/// Each `flow_end` takes the event's `timestamp`, that being when the expiry
346/// was noticed.
347///
348/// Returns `true` if any `flow_end` caused a ping to be submitted.
349pub(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
357/// Closes, with `reason: timeout`, every expired active instance.
358///
359/// Does nothing when no session is active: instances are only checked, and
360/// their `flow_end` only recorded, from within the session that owns them.
361///
362/// Returns `true` if any `flow_end` caused a ping to be submitted.
363pub(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
370/// Closes expired instances among `candidates`, or among all active instances
371/// when `candidates` is `None`.
372fn 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
406/// Returns a `flows` entry for every active instance of a flow the event belongs to.
407///
408/// Entries are in name order, which `member_of` already is.
409pub(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
423/// Closes the active instance of every flow the event ends, recording a
424/// `glean.flow_end` with `reason: exit` for each.
425///
426/// Must be called after the event itself is recorded, so each `flow_end` gets
427/// a higher `session.event_seq` than the event that closed it. Each takes the
428/// event's `timestamp`.
429///
430/// Returns `true` if any `flow_end` caused a ping to be submitted.
431pub(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
472/// Closes every active instance with `reason: session_end`, in reverse order of
473/// opening, after first closing any that have expired with `reason: timeout`.
474///
475/// Must be called while the ending session is still current, before its state
476/// is torn down and `glean.session_end` is recorded.
477pub(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    // `flow_seq` is assigned in order of opening.
488    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
500/// Resets in-memory flow state for a new session, and clears what was persisted.
501///
502/// Instances never span sessions, and `flow_seq` restarts at 0.
503pub(crate) fn reset_for_new_session(glean: &Glean) {
504    *glean.flow_state.lock().unwrap() = FlowState::default();
505    clear_persisted(glean);
506}
507
508/// Restores the persisted instances of the session being resumed at startup.
509///
510/// Only instances owned by `session_id` are restored, along with the flow
511/// counter, so the resumed session doesn't reuse sequence numbers. Instances
512/// of a flow that is no longer registered are discarded without a `flow_end`.
513/// Instances of a disabled flow are restored: restoring is not opening.
514pub(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    // A resumed session recomputes its sampling decision from the current
523    // sample rate. If that now samples it out, nothing in it is recorded, so
524    // its instances can neither be tagged nor closed.
525    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
562/// Closes every persisted instance with `reason: abnormal`, for a session that
563/// ended without closing them (a crash, or a session abandoned at startup).
564///
565/// Each `flow_end` is recorded out-of-session, since the owning session is no
566/// longer current, and carries that session's ID. Instances of a flow that is
567/// no longer registered are discarded without one. Must be called before the
568/// session's own synthetic `session_end` is recorded.
569pub(crate) fn recover_abnormal(glean: &Glean) {
570    if let Some(persisted) = read_persisted(glean) {
571        let mut instances = persisted.instances;
572        // Reverse order of opening, as at session end.
573        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
593/// Discards persisted flow state without recording anything, for instances
594/// whose session was not resumed and did not end abnormally.
595pub(crate) fn discard_persisted(glean: &Glean) {
596    *glean.flow_state.lock().unwrap() = FlowState::default();
597    clear_persisted(glean);
598}
599
600/// Flow state as persisted.
601#[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
602struct PersistedFlowState {
603    /// The session that owns the flow counter.
604    session_id: String,
605    next_seq: u64,
606    instances: Vec<PersistedInstance>,
607}
608
609/// An active instance as persisted.
610#[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
611struct PersistedInstance {
612    flow_name: String,
613    flow_seq: u64,
614    /// The session that owns the instance.
615    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
629/// Persists the active instances and the flow counter, in one write.
630///
631/// Called only when an instance opens or closes.
632fn persist(glean: &Glean, state: &FlowState) {
633    // Subprocesses have no storage, and never have an active session.
634    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    // Safe unwrap: these types always serialize.
656    let json = serde_json::to_string(&persisted).unwrap();
657    make_flow_state_metric().set_sync(glean, json);
658}
659
660/// Reads the persisted flow state, if any.
661fn 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
676/// Clears the persisted flow state.
677fn clear_persisted(glean: &Glean) {
678    if glean.data_store.is_none() {
679        return;
680    }
681    make_flow_state_metric().set_sync(glean, "");
682}
683
684/// The metadata `glean.flow_end` is recorded with, built once rather than on
685/// every call, since a session ending can close many instances at once.
686static 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
697/// Records a `glean.flow_end` event.
698///
699/// Like `glean.session_end`, this bypasses `EventMetric` and records directly,
700/// but in-session rather than out-of-session, so it is ordered against the
701/// instance's own events by `session.event_seq`. It is never flow-tagged. The
702/// exception is `reason: abnormal`, recorded at startup before any session
703/// exists, which carries the owning session's ID as an extra instead.
704///
705/// `timestamp` is on the same monotonic clock as every event's main timestamp:
706/// the triggering event's when one closed the instance, otherwise now.
707///
708/// Returns `true` if recording it caused a ping to be submitted.
709pub(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(&registry, &flows.member_of)
821        );
822        assert_eq!(vec!["mu", "zeta"], names(&registry, &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    // -----------------------------------------------------------------------
853    // Tagging recorded events
854    // -----------------------------------------------------------------------
855
856    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    /// Marks `flow` as having an active instance with the given `flow_seq`.
907    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    /// Records `metric` and returns the `flows` on the resulting event.
919    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        // checkout is active, but settings_toggled belongs only to onboarding.
971        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    // -----------------------------------------------------------------------
1055    // Lifecycle
1056    // -----------------------------------------------------------------------
1057
1058    /// The `onboarding` flow from the proposal's worked example.
1059    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    /// The worked example from the proposal, row by row.
1111    #[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        // The snapshot is ordered by timestamp, so use the same clock as the
1125        // session boundary events.
1126        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        // Tagged with both: the instance it closes and the one it opens.
1298        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        // session_start, started, dismissed, and then flow_end fills the store.
1377        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    // -----------------------------------------------------------------------
1389    // Session end
1390    // -----------------------------------------------------------------------
1391
1392    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    /// Returns `(category.name, session.session_id, session.event_seq)` for each
1424    /// event in the events store, in ping order.
1425    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        // zeta opens first (seq 0), alpha second (seq 1).
1463        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        // Comfortably outlast the 1ms inactivity timeout.
1526        std::thread::sleep(std::time::Duration::from_millis(5));
1527
1528        // The timeout is noticed here, ending the old session and starting a new one.
1529        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        // Only the exit's flow_end, none at session end.
1576        assert_eq!(
1577            vec![exit_extras("alpha", 0, "alpha.finished")],
1578            flow_ends(&glean)
1579        );
1580    }
1581
1582    // -----------------------------------------------------------------------
1583    // auto_close_timeout
1584    // -----------------------------------------------------------------------
1585
1586    const TIMEOUT_MS: u64 = 60_000;
1587
1588    /// `onboarding` with a one-minute `auto_close_timeout`, and `untimed`, with none.
1589    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    /// Moves an active instance's opening time `ms` into the past.
1603    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    /// Returns the events from every queued `events` ping.
1627    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        // The flow_end comes before the event that noticed the expiry.
1664        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    // -----------------------------------------------------------------------
1833    // Persistence
1834    // -----------------------------------------------------------------------
1835
1836    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    /// Drops `glean` and starts a new instance on the same data directory.
1844    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    /// Moves a persisted instance's opening time `ms` into the past.
1861    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        // The counter was restored, so the reopened flow doesn't reuse seq 1.
1939        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        // The new build no longer defines `alpha`.
1955        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        // Active, and never goes inactive: the dirty flag stays set.
2022        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        // A crash with `inactive_since` persisted (the session_end reason is
2064        // "abnormal_inactive"): the session is resumable, but the crash wins.
2065        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        // No inactive_since is recorded, so the session can't be resumed, but
2132        // the dirty flag is clear, so this isn't a crash either.
2133        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        // The new build samples every session out.
2152        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}