foundry_common/
fs.rs

1//! Contains various `std::fs` wrapper functions that also contain the target path in their errors.
2
3use crate::errors::FsPathError;
4use flate2::{Compression, read::GzDecoder, write::GzEncoder};
5use serde::{Serialize, de::DeserializeOwned};
6use std::{
7    fs::{self, File},
8    io::{BufReader, BufWriter, Read, Write},
9    path::{Component, Path, PathBuf},
10};
11
12/// The [`fs`](self) result type.
13pub type Result<T> = std::result::Result<T, FsPathError>;
14
15/// Wrapper for [`File::create`].
16pub fn create_file(path: impl AsRef<Path>) -> Result<fs::File> {
17    let path = path.as_ref();
18    File::create(path).map_err(|err| FsPathError::create_file(err, path))
19}
20
21/// Wrapper for [`std::fs::remove_file`].
22pub fn remove_file(path: impl AsRef<Path>) -> Result<()> {
23    let path = path.as_ref();
24    fs::remove_file(path).map_err(|err| FsPathError::remove_file(err, path))
25}
26
27/// Wrapper for [`std::fs::read`].
28pub fn read(path: impl AsRef<Path>) -> Result<Vec<u8>> {
29    let path = path.as_ref();
30    fs::read(path).map_err(|err| FsPathError::read(err, path))
31}
32
33/// Wrapper for [`std::fs::read_link`].
34pub fn read_link(path: impl AsRef<Path>) -> Result<PathBuf> {
35    let path = path.as_ref();
36    fs::read_link(path).map_err(|err| FsPathError::read_link(err, path))
37}
38
39/// Wrapper for [`std::fs::read_to_string`].
40pub fn read_to_string(path: impl AsRef<Path>) -> Result<String> {
41    let path = path.as_ref();
42    fs::read_to_string(path).map_err(|err| FsPathError::read(err, path))
43}
44
45/// Reads the JSON file and deserialize it into the provided type.
46pub fn read_json_file<T: DeserializeOwned>(path: &Path) -> Result<T> {
47    // read the file into a byte array first
48    // https://github.com/serde-rs/json/issues/160
49    let s = read_to_string(path)?;
50    serde_json::from_str(&s).map_err(|source| FsPathError::ReadJson { source, path: path.into() })
51}
52
53/// Reads and decodes the json gzip file, then deserialize it into the provided type.
54pub fn read_json_gzip_file<T: DeserializeOwned>(path: &Path) -> Result<T> {
55    let file = open(path)?;
56    let reader = BufReader::new(file);
57    let decoder = GzDecoder::new(reader);
58    serde_json::from_reader(decoder)
59        .map_err(|source| FsPathError::ReadJson { source, path: path.into() })
60}
61
62/// Reads the entire contents of a locked shared file into a string.
63pub fn locked_read_to_string(path: impl AsRef<Path>) -> Result<String> {
64    let path = path.as_ref();
65    let file =
66        fs::OpenOptions::new().read(true).open(path).map_err(|err| FsPathError::open(err, path))?;
67    file.lock_shared().map_err(|err| FsPathError::lock(err, path))?;
68    let mut contents = String::new();
69    (&file).read_to_string(&mut contents).map_err(|err| FsPathError::read(err, path))?;
70    file.unlock().map_err(|err| FsPathError::unlock(err, path))?;
71    Ok(contents)
72}
73
74/// Reads the entire contents of a locked shared file into a bytes vector.
75pub fn locked_read(path: impl AsRef<Path>) -> Result<Vec<u8>> {
76    let path = path.as_ref();
77    let file =
78        fs::OpenOptions::new().read(true).open(path).map_err(|err| FsPathError::open(err, path))?;
79    file.lock_shared().map_err(|err| FsPathError::lock(err, path))?;
80    let file_len = file.metadata().map_err(|err| FsPathError::open(err, path))?.len() as usize;
81    let mut buffer = Vec::with_capacity(file_len);
82    (&file).read_to_end(&mut buffer).map_err(|err| FsPathError::read(err, path))?;
83    file.unlock().map_err(|err| FsPathError::unlock(err, path))?;
84    Ok(buffer)
85}
86
87/// Writes the object as a JSON object.
88pub fn write_json_file<T: Serialize>(path: &Path, obj: &T) -> Result<()> {
89    let file = create_file(path)?;
90    let mut writer = BufWriter::new(file);
91    serde_json::to_writer(&mut writer, obj)
92        .map_err(|source| FsPathError::WriteJson { source, path: path.into() })?;
93    writer.flush().map_err(|e| FsPathError::write(e, path))
94}
95
96/// Writes the object as a pretty JSON object.
97pub fn write_pretty_json_file<T: Serialize>(path: &Path, obj: &T) -> Result<()> {
98    let file = create_file(path)?;
99    let mut writer = BufWriter::new(file);
100    serde_json::to_writer_pretty(&mut writer, obj)
101        .map_err(|source| FsPathError::WriteJson { source, path: path.into() })?;
102    writer.flush().map_err(|e| FsPathError::write(e, path))
103}
104
105/// Writes the object as a gzip compressed file.
106pub fn write_json_gzip_file<T: Serialize>(path: &Path, obj: &T) -> Result<()> {
107    let file = create_file(path)?;
108    let writer = BufWriter::new(file);
109    let mut encoder = GzEncoder::new(writer, Compression::default());
110    serde_json::to_writer(&mut encoder, obj)
111        .map_err(|source| FsPathError::WriteJson { source, path: path.into() })?;
112    encoder
113        .finish()
114        .map_err(serde_json::Error::io)
115        .map_err(|source| FsPathError::WriteJson { source, path: path.into() })?;
116    Ok(())
117}
118
119/// Wrapper for `std::fs::write`
120pub fn write(path: impl AsRef<Path>, contents: impl AsRef<[u8]>) -> Result<()> {
121    let path = path.as_ref();
122    fs::write(path, contents).map_err(|err| FsPathError::write(err, path))
123}
124
125/// Writes all content in an exclusive locked file.
126pub fn locked_write(path: impl AsRef<Path>, contents: impl AsRef<[u8]>) -> Result<()> {
127    let path = path.as_ref();
128    let mut file = fs::OpenOptions::new()
129        .write(true)
130        .create(true)
131        .truncate(true)
132        .open(path)
133        .map_err(|err| FsPathError::open(err, path))?;
134    file.lock().map_err(|err| FsPathError::lock(err, path))?;
135    file.write_all(contents.as_ref()).map_err(|err| FsPathError::write(err, path))?;
136    file.unlock().map_err(|err| FsPathError::unlock(err, path))
137}
138
139/// Writes a line in an exclusive locked file.
140pub fn locked_write_line(path: impl AsRef<Path>, line: &String) -> Result<()> {
141    let path = path.as_ref();
142    let mut file = std::fs::OpenOptions::new()
143        .append(true)
144        .create(true)
145        .open(path)
146        .map_err(|err| FsPathError::open(err, path))?;
147    file.lock().map_err(|err| FsPathError::lock(err, path))?;
148    writeln!(file, "{line}").map_err(|err| FsPathError::write(err, path))?;
149    file.unlock().map_err(|err| FsPathError::unlock(err, path))
150}
151
152/// Wrapper for `std::fs::copy`
153pub fn copy(from: impl AsRef<Path>, to: impl AsRef<Path>) -> Result<u64> {
154    let from = from.as_ref();
155    let to = to.as_ref();
156    fs::copy(from, to).map_err(|err| FsPathError::copy(err, from, to))
157}
158
159/// Wrapper for `std::fs::create_dir`
160pub fn create_dir(path: impl AsRef<Path>) -> Result<()> {
161    let path = path.as_ref();
162    fs::create_dir(path).map_err(|err| FsPathError::create_dir(err, path))
163}
164
165/// Wrapper for `std::fs::create_dir_all`
166pub fn create_dir_all(path: impl AsRef<Path>) -> Result<()> {
167    let path = path.as_ref();
168    fs::create_dir_all(path).map_err(|err| FsPathError::create_dir(err, path))
169}
170
171/// Wrapper for `std::fs::remove_dir`
172pub fn remove_dir(path: impl AsRef<Path>) -> Result<()> {
173    let path = path.as_ref();
174    fs::remove_dir(path).map_err(|err| FsPathError::remove_dir(err, path))
175}
176
177/// Wrapper for `std::fs::remove_dir_all`
178pub fn remove_dir_all(path: impl AsRef<Path>) -> Result<()> {
179    let path = path.as_ref();
180    fs::remove_dir_all(path).map_err(|err| FsPathError::remove_dir(err, path))
181}
182
183/// Wrapper for `std::fs::File::open`
184pub fn open(path: impl AsRef<Path>) -> Result<fs::File> {
185    let path = path.as_ref();
186    fs::File::open(path).map_err(|err| FsPathError::open(err, path))
187}
188
189/// Normalize a path, removing things like `.` and `..`.
190///
191/// NOTE: This does not return symlinks and does not touch the filesystem at all (unlike
192/// [`std::fs::canonicalize`])
193///
194/// ref: <https://github.com/rust-lang/cargo/blob/9ded34a558a900563b0acf3730e223c649cf859d/crates/cargo-util/src/paths.rs#L81>
195pub fn normalize_path(path: &Path) -> PathBuf {
196    let mut components = path.components().peekable();
197    let mut ret = if let Some(c @ Component::Prefix(..)) = components.peek().copied() {
198        components.next();
199        PathBuf::from(c.as_os_str())
200    } else {
201        PathBuf::new()
202    };
203
204    for component in components {
205        match component {
206            Component::Prefix(..) => unreachable!(),
207            Component::RootDir => {
208                ret.push(component.as_os_str());
209            }
210            Component::CurDir => {}
211            Component::ParentDir => {
212                ret.pop();
213            }
214            Component::Normal(c) => {
215                ret.push(c);
216            }
217        }
218    }
219    ret
220}
221
222/// Returns an iterator over all files with the given extension under the `root` dir.
223pub fn files_with_ext<'a>(root: &Path, ext: &'a str) -> impl Iterator<Item = PathBuf> + 'a {
224    walkdir::WalkDir::new(root)
225        .sort_by_file_name()
226        .into_iter()
227        .filter_map(walkdir::Result::ok)
228        .filter(|e| e.file_type().is_file() && e.path().extension() == Some(ext.as_ref()))
229        .map(walkdir::DirEntry::into_path)
230}
231
232/// Returns an iterator over all JSON files under the `root` dir.
233pub fn json_files(root: &Path) -> impl Iterator<Item = PathBuf> {
234    files_with_ext(root, "json")
235}
236
237/// Canonicalize a path, returning an error if the path does not exist.
238///
239/// Mainly useful to apply canonicalization to paths obtained from project files but still error
240/// properly instead of flattening the errors.
241pub fn canonicalize_path(path: impl AsRef<Path>) -> std::io::Result<PathBuf> {
242    dunce::canonicalize(path)
243}
244
245#[cfg(test)]
246mod tests {
247    use super::*;
248
249    #[test]
250    fn test_normalize_path() {
251        let p = Path::new("/a/../file.txt");
252        let normalized = normalize_path(p);
253        assert_eq!(normalized, PathBuf::from("/file.txt"));
254    }
255}