jj_lib/
fsmonitor.rs

1// Copyright 2023 The Jujutsu Authors
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// https://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Filesystem monitor tool interface.
16//!
17//! Interfaces with a filesystem monitor tool to efficiently query for
18//! filesystem updates, without having to crawl the entire working copy. This is
19//! particularly useful for large working copies, or for working copies for
20//! which it's expensive to materialize files, such those backed by a network or
21//! virtualized filesystem.
22
23#![warn(missing_docs)]
24
25use std::path::PathBuf;
26
27use crate::config::ConfigGetError;
28use crate::settings::UserSettings;
29
30/// Config for Watchman filesystem monitor (<https://facebook.github.io/watchman/>).
31#[derive(Eq, PartialEq, Clone, Debug)]
32pub struct WatchmanConfig {
33    /// Whether to use triggers to monitor for changes in the background.
34    pub register_trigger: bool,
35}
36
37/// The recognized kinds of filesystem monitors.
38#[derive(Eq, PartialEq, Clone, Debug)]
39pub enum FsmonitorSettings {
40    /// The Watchman filesystem monitor (<https://facebook.github.io/watchman/>).
41    Watchman(WatchmanConfig),
42
43    /// Only used in tests.
44    Test {
45        /// The set of changed files to pretend that the filesystem monitor is
46        /// reporting.
47        changed_files: Vec<PathBuf>,
48    },
49
50    /// No filesystem monitor. This is the default if nothing is configured, but
51    /// also makes it possible to turn off the monitor on a case-by-case basis
52    /// when the user gives an option like `--config=core.fsmonitor=none`;
53    /// useful when e.g. when doing analysis of snapshot performance.
54    None,
55}
56
57impl FsmonitorSettings {
58    /// Creates an `FsmonitorSettings` from a `config`.
59    pub fn from_settings(settings: &UserSettings) -> Result<FsmonitorSettings, ConfigGetError> {
60        let name = "core.fsmonitor";
61        match settings.get_string(name)?.as_ref() {
62            "watchman" => Ok(Self::Watchman(WatchmanConfig {
63                register_trigger: settings.get_bool("core.watchman.register-snapshot-trigger")?,
64            })),
65            "test" => Err(ConfigGetError::Type {
66                name: name.to_owned(),
67                error: "Cannot use test fsmonitor in real repository".into(),
68                source_path: None,
69            }),
70            "none" => Ok(Self::None),
71            other => Err(ConfigGetError::Type {
72                name: name.to_owned(),
73                error: format!("Unknown fsmonitor kind: {other}").into(),
74                source_path: None,
75            }),
76        }
77    }
78}
79
80/// Filesystem monitor integration using Watchman
81/// (<https://facebook.github.io/watchman/>). Requires `watchman` to already be
82/// installed on the system.
83#[cfg(feature = "watchman")]
84pub mod watchman {
85    use std::path::Path;
86    use std::path::PathBuf;
87
88    use itertools::Itertools as _;
89    use thiserror::Error;
90    use tracing::info;
91    use tracing::instrument;
92    use watchman_client::expr;
93    use watchman_client::prelude::Clock as InnerClock;
94    use watchman_client::prelude::ClockSpec;
95    use watchman_client::prelude::NameOnly;
96    use watchman_client::prelude::QueryRequestCommon;
97    use watchman_client::prelude::QueryResult;
98    use watchman_client::prelude::TriggerRequest;
99
100    /// Represents an instance in time from the perspective of the filesystem
101    /// monitor.
102    ///
103    /// This can be used to perform incremental queries. When making a query,
104    /// the result will include an associated "clock" representing the time
105    /// that the query was made.  By passing the same clock into a future
106    /// query, we inform the filesystem monitor that we only wish to get
107    /// changed files since the previous point in time.
108    #[derive(Clone, Debug)]
109    pub struct Clock(InnerClock);
110
111    impl From<crate::protos::working_copy::WatchmanClock> for Clock {
112        fn from(clock: crate::protos::working_copy::WatchmanClock) -> Self {
113            use crate::protos::working_copy::watchman_clock::WatchmanClock;
114            let watchman_clock = clock.watchman_clock.unwrap();
115            let clock = match watchman_clock {
116                WatchmanClock::StringClock(string_clock) => {
117                    InnerClock::Spec(ClockSpec::StringClock(string_clock))
118                }
119                WatchmanClock::UnixTimestamp(unix_timestamp) => {
120                    InnerClock::Spec(ClockSpec::UnixTimestamp(unix_timestamp))
121                }
122            };
123            Self(clock)
124        }
125    }
126
127    impl From<Clock> for crate::protos::working_copy::WatchmanClock {
128        fn from(clock: Clock) -> Self {
129            use crate::protos::working_copy::watchman_clock;
130            use crate::protos::working_copy::WatchmanClock;
131            let Clock(clock) = clock;
132            let watchman_clock = match clock {
133                InnerClock::Spec(ClockSpec::StringClock(string_clock)) => {
134                    watchman_clock::WatchmanClock::StringClock(string_clock)
135                }
136                InnerClock::Spec(ClockSpec::UnixTimestamp(unix_timestamp)) => {
137                    watchman_clock::WatchmanClock::UnixTimestamp(unix_timestamp)
138                }
139                InnerClock::ScmAware(_) => {
140                    unimplemented!("SCM-aware Watchman clocks not supported")
141                }
142            };
143            WatchmanClock {
144                watchman_clock: Some(watchman_clock),
145            }
146        }
147    }
148
149    #[expect(missing_docs)]
150    #[derive(Debug, Error)]
151    pub enum Error {
152        #[error("Could not connect to Watchman")]
153        WatchmanConnectError(#[source] watchman_client::Error),
154
155        #[error("Could not canonicalize working copy root path")]
156        CanonicalizeRootError(#[source] std::io::Error),
157
158        #[error("Watchman failed to resolve the working copy root path")]
159        ResolveRootError(#[source] watchman_client::Error),
160
161        #[error("Failed to query Watchman")]
162        WatchmanQueryError(#[source] watchman_client::Error),
163
164        #[error("Failed to register Watchman trigger")]
165        WatchmanTriggerError(#[source] watchman_client::Error),
166    }
167
168    /// Handle to the underlying Watchman instance.
169    pub struct Fsmonitor {
170        client: watchman_client::Client,
171        resolved_root: watchman_client::ResolvedRoot,
172    }
173
174    impl Fsmonitor {
175        /// Initialize the Watchman filesystem monitor. If it's not already
176        /// running, this will start it and have it crawl the working
177        /// copy to build up its in-memory representation of the
178        /// filesystem, which may take some time.
179        #[instrument]
180        pub async fn init(
181            working_copy_path: &Path,
182            config: &super::WatchmanConfig,
183        ) -> Result<Self, Error> {
184            info!("Initializing Watchman filesystem monitor...");
185            let connector = watchman_client::Connector::new();
186            let client = connector
187                .connect()
188                .await
189                .map_err(Error::WatchmanConnectError)?;
190            let working_copy_root = watchman_client::CanonicalPath::canonicalize(working_copy_path)
191                .map_err(Error::CanonicalizeRootError)?;
192            let resolved_root = client
193                .resolve_root(working_copy_root)
194                .await
195                .map_err(Error::ResolveRootError)?;
196
197            let monitor = Fsmonitor {
198                client,
199                resolved_root,
200            };
201
202            // Registering the trigger causes an unconditional evaluation of the query, so
203            // test if it is already registered first.
204            if !config.register_trigger {
205                monitor.unregister_trigger().await?;
206            } else if !monitor.is_trigger_registered().await? {
207                monitor.register_trigger().await?;
208            }
209            Ok(monitor)
210        }
211
212        /// Query for changed files since the previous point in time.
213        ///
214        /// The returned list of paths is relative to the `working_copy_path`.
215        /// If it is `None`, then the caller must crawl the entire working copy
216        /// themselves.
217        #[instrument(skip(self))]
218        pub async fn query_changed_files(
219            &self,
220            previous_clock: Option<Clock>,
221        ) -> Result<(Clock, Option<Vec<PathBuf>>), Error> {
222            // TODO: might be better to specify query options by caller, but we
223            // shouldn't expose the underlying watchman API too much.
224            info!("Querying Watchman for changed files...");
225            let QueryResult {
226                version: _,
227                is_fresh_instance,
228                files,
229                clock,
230                state_enter: _,
231                state_leave: _,
232                state_metadata: _,
233                saved_state_info: _,
234                debug: _,
235            }: QueryResult<NameOnly> = self
236                .client
237                .query(
238                    &self.resolved_root,
239                    QueryRequestCommon {
240                        since: previous_clock.map(|Clock(clock)| clock),
241                        expression: Some(self.build_exclude_expr()),
242                        ..Default::default()
243                    },
244                )
245                .await
246                .map_err(Error::WatchmanQueryError)?;
247
248            let clock = Clock(clock);
249            if is_fresh_instance {
250                // The Watchman documentation states that if it was a fresh
251                // instance, we need to delete any tree entries that didn't appear
252                // in the returned list of changed files. For now, the caller will
253                // handle this by manually crawling the working copy again.
254                Ok((clock, None))
255            } else {
256                let paths = files
257                    .unwrap_or_default()
258                    .into_iter()
259                    .map(|NameOnly { name }| name.into_inner())
260                    .collect_vec();
261                Ok((clock, Some(paths)))
262            }
263        }
264
265        /// Return whether or not a trigger has been registered already.
266        #[instrument(skip(self))]
267        pub async fn is_trigger_registered(&self) -> Result<bool, Error> {
268            info!("Checking for an existing Watchman trigger...");
269            Ok(self
270                .client
271                .list_triggers(&self.resolved_root)
272                .await
273                .map_err(Error::WatchmanTriggerError)?
274                .triggers
275                .iter()
276                .any(|t| t.name == "jj-background-monitor"))
277        }
278
279        /// Register trigger for changed files.
280        #[instrument(skip(self))]
281        async fn register_trigger(&self) -> Result<(), Error> {
282            info!("Registering Watchman trigger...");
283            self.client
284                .register_trigger(
285                    &self.resolved_root,
286                    TriggerRequest {
287                        name: "jj-background-monitor".to_string(),
288                        command: vec![
289                            "jj".to_string(),
290                            "debug".to_string(),
291                            "snapshot".to_string(),
292                        ],
293                        expression: Some(self.build_exclude_expr()),
294                        ..Default::default()
295                    },
296                )
297                .await
298                .map_err(Error::WatchmanTriggerError)?;
299            Ok(())
300        }
301
302        /// Register trigger for changed files.
303        #[instrument(skip(self))]
304        async fn unregister_trigger(&self) -> Result<(), Error> {
305            info!("Unregistering Watchman trigger...");
306            self.client
307                .remove_trigger(&self.resolved_root, "jj-background-monitor")
308                .await
309                .map_err(Error::WatchmanTriggerError)?;
310            Ok(())
311        }
312
313        /// Build an exclude expr for `working_copy_path`.
314        fn build_exclude_expr(&self) -> expr::Expr {
315            // TODO: consider parsing `.gitignore`.
316            let exclude_dirs = [Path::new(".git"), Path::new(".jj")];
317            let excludes = itertools::chain(
318                // the directories themselves
319                [expr::Expr::Name(expr::NameTerm {
320                    paths: exclude_dirs.iter().map(|&name| name.to_owned()).collect(),
321                    wholename: true,
322                })],
323                // and all files under the directories
324                exclude_dirs.iter().map(|&name| {
325                    expr::Expr::DirName(expr::DirNameTerm {
326                        path: name.to_owned(),
327                        depth: None,
328                    })
329                }),
330            )
331            .collect();
332            expr::Expr::Not(Box::new(expr::Expr::Any(excludes)))
333        }
334    }
335}
jj_lib/fsmonitor.rs

jj_lib/
fsmonitor.rs
