mbr_core/
change_event.rs

1//! File change events: what the watcher broadcasts and what the in-process
2//! writers (task toggles, edits, uploads, renames) announce.
3//!
4//! Kept apart from the watcher (`mbr_server::watcher`) so the repository index,
5//! the task index and the server can consume and produce events without
6//! depending on the `notify` crate. Only the watcher itself needs that.
7
8use serde::{Deserialize, Serialize};
9
10/// Capacity of the broadcast channel that carries [`FileChangeEvent`]s.
11/// If clients don't keep up, the oldest messages will be dropped.
12///
13/// Lives here rather than in the watcher because the server creates the
14/// channel whether or not a watcher feeds it: in-process writers announce
15/// their own edits on it, and a build without the `watcher` feature still
16/// has live reload for those.
17pub const BROADCAST_CAPACITY: usize = 100;
18
19/// Represents a file system change event.
20///
21/// Only `relative_path` and `event` cross the wire: this struct is broadcast to
22/// every live-reload WebSocket client, and an absolute path would leak the OS
23/// username, the home directory layout, and private note filenames.
24#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
25pub struct FileChangeEvent {
26    /// The absolute path to the changed file.
27    ///
28    /// **Server-side only** (`#[serde(skip)]`): consumed in-process by the
29    /// template hot-reload and repo-invalidation tasks. It is never serialized
30    /// to WebSocket clients — see the struct docs.
31    #[serde(skip)]
32    pub path: String,
33    /// The path relative to the repository root.
34    pub relative_path: String,
35    /// The type of change event.
36    pub event: ChangeEventType,
37}
38
39/// Type of file system change event.
40#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
41#[serde(rename_all = "lowercase")]
42pub enum ChangeEventType {
43    Modified,
44    Created,
45    Deleted,
46}
47
48#[cfg(test)]
49mod tests {
50    use super::*;
51
52    #[test]
53    fn test_serialized_event_omits_absolute_path() {
54        // The live-reload WebSocket broadcasts this struct to any client that
55        // completes a handshake, so the absolute path must never be on the
56        // wire: it leaks the OS username, home layout, and private filenames.
57        let event = FileChangeEvent {
58            path: "/Users/someone/private notes/secret.md".to_string(),
59            relative_path: "private notes/secret.md".to_string(),
60            event: ChangeEventType::Modified,
61        };
62        let json = serde_json::to_string(&event).unwrap();
63        assert!(
64            !json.contains("/Users/someone"),
65            "absolute path leaked into the broadcast payload: {json}"
66        );
67        let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
68        assert!(
69            parsed.get("path").is_none(),
70            "`path` must not be serialized: {json}"
71        );
72        assert_eq!(parsed["relative_path"], "private notes/secret.md");
73        assert_eq!(parsed["event"], "modified");
74    }
75}
mbr_core/change_event.rs

mbr_core/
change_event.rs
