rust: simplify intercept execution event

Author: rizsotto

rust/intercept/src/bin/wrapper.rs

@@ -58,7 +58,7 @@ fn report_execution(path_buf: &PathBuf) {
         .expect("Cannot create reporter");
 
     // Report the execution
-    let execution = intercept::Event::Started {
+    let execution = intercept::Event {
         pid: intercept::ProcessId(std::process::id() as u32),
         execution: intercept::Execution {
             executable: path_buf.clone(),

rust/intercept/src/lib.rs

@@ -26,17 +26,23 @@ use serde::{Deserialize, Serialize};
 pub mod collector;
 pub mod reporter;
 
-// Reporter id is a unique identifier for a reporter.
-//
-// It is used to identify the process that sends the execution report.
-// Because the OS PID is not unique across a single build (PIDs are
-// recycled), we need to use a new unique identifier to identify the process.
+/// Reporter id is a unique identifier for a reporter.
+///
+/// It is used to identify the process that sends the execution report.
+/// Because the OS PID is not unique across a single build (PIDs are
+/// recycled), we need to use a new unique identifier to identify the process.
 #[derive(Serialize, Deserialize, Debug, PartialEq, Clone)]
 pub struct ReporterId(pub u64);
 
+/// Process id is a OS identifier for a process.
 #[derive(Serialize, Deserialize, Debug, PartialEq, Clone)]
 pub struct ProcessId(pub u32);
 
+/// Execution is a representation of a process execution.
+///
+/// It does not contain information about the outcome of the execution,
+/// like the exit code or the duration of the execution. It only contains
+/// the information that is necessary to reproduce the execution.
 #[derive(Serialize, Deserialize, Debug, PartialEq, Clone)]
 pub struct Execution {
     pub executable: PathBuf,
@@ -45,26 +51,20 @@ pub struct Execution {
     pub environment: HashMap<String, String>,
 }
 
-// Represent a relevant life cycle event of a process.
-//
-// Currently, it's only the process life cycle events (start, signal,
-// terminate), but can be extended later with performance related
-// events like monitoring the CPU usage or the memory allocation if
-// this information is available.
+/// Represent a relevant life cycle event of a process.
+///
+/// In the current implementation, we only have one event, the `Started` event.
+/// This event is sent when a process is started. It contains the process id
+/// and the execution information.
 #[derive(Serialize, Deserialize, Debug, PartialEq, Clone)]
-pub enum Event {
-    Started {
-        pid: ProcessId,
-        execution: Execution,
-    },
-    Terminated {
-        status: i64,
-    },
-    Signaled {
-        signal: i32,
-    },
+pub struct Event {
+    pub pid: ProcessId,
+    pub execution: Execution,
 }
 
+/// Envelope is a wrapper around the event.
+///
+/// It contains the reporter id, the timestamp of the event and the event itself.
 #[derive(Serialize, Deserialize, Debug, PartialEq, Clone)]
 pub struct Envelope {
     pub rid: ReporterId,
@@ -82,6 +82,10 @@ impl Envelope {
         }
     }
 
+    /// Read an envelope from a reader using TLV format.
+    ///
+    /// The envelope is serialized using JSON and the length of the JSON
+    /// is written as a 4 byte big-endian integer before the JSON.
     pub fn read_from(reader: &mut impl Read) -> Result<Self, anyhow::Error> {
         let mut length_bytes = [0; 4];
         reader.read_exact(&mut length_bytes)?;
@@ -94,6 +98,10 @@ impl Envelope {
         Ok(envelope)
     }
 
+    /// Write an envelope to a writer using TLV format.
+    ///
+    /// The envelope is serialized using JSON and the length of the JSON
+    /// is written as a 4 byte big-endian integer before the JSON.
     pub fn write_into(&self, writer: &mut impl Write) -> Result<u32, anyhow::Error> {
         let serialized_envelope = serde_json::to_string(&self)?;
         let bytes = serialized_envelope.into_bytes();

rust/intercept/tests/test.rs

@@ -78,29 +78,75 @@ mod test {
     lazy_static! {
         static ref ENVELOPES: Vec<Envelope> = vec![
             Envelope {
-                rid: ReporterId(1),
-                timestamp: 0,
-                event: Event::Started {
-                    pid: ProcessId(1),
+                rid: ReporterId::new(),
+                timestamp: fixtures::timestamp(),
+                event: Event {
+                    pid: fixtures::pid(),
                     execution: Execution {
                         executable: PathBuf::from("/usr/bin/ls"),
-                        arguments: vec!["ls".to_string(), "-l".to_string()],
+                        arguments: vec_of_strings!["ls", "-l"],
                         working_dir: PathBuf::from("/tmp"),
                         environment: HashMap::new(),
                     },
                 },
             },
             Envelope {
-                rid: ReporterId(1),
-                timestamp: 0,
-                event: Event::Terminated { status: 0 },
+                rid: ReporterId::new(),
+                timestamp: fixtures::timestamp(),
+                event: Event {
+                    pid: fixtures::pid(),
+                    execution: Execution {
+                        executable: PathBuf::from("/usr/bin/cc"),
+                        arguments: vec_of_strings!["cc", "-c", "./file_a.c", "-o", "./file_a.o"],
+                        working_dir: PathBuf::from("/home/user"),
+                        environment: map_of_strings! {
+                            "PATH" => "/usr/bin:/bin",
+                            "HOME" => "/home/user",
+                        },
+                    },
+                },
             },
             Envelope {
-                rid: ReporterId(1),
-                timestamp: 0,
-                event: Event::Signaled { signal: 15 },
+                rid: ReporterId::new(),
+                timestamp: fixtures::timestamp(),
+                event: Event {
+                    pid: fixtures::pid(),
+                    execution: Execution {
+                        executable: PathBuf::from("/usr/bin/ld"),
+                        arguments: vec_of_strings!["ld", "-o", "./file_a", "./file_a.o"],
+                        working_dir: PathBuf::from("/opt/project"),
+                        environment: map_of_strings! {
+                            "PATH" => "/usr/bin:/bin",
+                            "LD_LIBRARY_PATH" => "/usr/lib:/lib",
+                        },
+                    },
+                },
             },
         ];
         static ref EVENTS: Vec<Event> = ENVELOPES.iter().map(|e| e.event.clone()).collect();
     }
 }
+
+mod fixtures {
+    use intercept::ProcessId;
+
+    pub fn timestamp() -> u64 {
+        rand::random::<u64>()
+    }
+
+    pub fn pid() -> ProcessId {
+        ProcessId(rand::random::<u32>())
+    }
+
+    #[macro_export]
+    macro_rules! vec_of_strings {
+        ($($x:expr),*) => (vec![$($x.to_string()),*]);
+    }
+
+    #[macro_export]
+    macro_rules! map_of_strings {
+        ($($k:expr => $v:expr),* $(,)?) => {{
+            core::convert::From::from([$(($k.to_string(), $v.to_string()),)*])
+        }};
+    }
+}