Skip to main content

folderbase_core/
workspace.rs

1//! Workspace navigation and optimistic text editing over an ordinary folderbase folder.
2
3use std::{
4    ffi::OsStr,
5    fs,
6    io::{self, Read},
7    path::{Component, Path, PathBuf},
8};
9
10use cap_std::{ambient_authority, fs::Dir};
11use serde::{Deserialize, Serialize};
12use sha2::{Digest, Sha256};
13use walkdir::WalkDir;
14
15use crate::{
16    ContentDigest, FolderbaseError, LocalVersionStore, ObjectId, Result, VersionId,
17    root_attestation::metadata_is_link_or_reparse,
18    traversal_policy::{
19        NestedFolderbaseBoundaryKind, classify_nested_folderbase_boundary,
20        is_reconstructable_directory, is_reserved_workspace_component as is_reserved_component,
21    },
22};
23
24pub const MAX_WORKSPACE_TEXT_BYTES: u64 = 2 * 1024 * 1024;
25const MAX_WORKSPACE_ENTRIES: usize = 50_000;
26const MAX_WORKSPACE_DEPTH: usize = 64;
27const ROOT_IGNORE_POLICY_PATH: &str = ".folderbaseignore";
28
29#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
30#[serde(rename_all = "lowercase")]
31pub enum WorkspaceEntryKind {
32    Folderbase,
33    Directory,
34    File,
35    Symlink,
36}
37
38#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
39pub struct WorkspaceEntry {
40    pub path: String,
41    pub name: String,
42    pub kind: WorkspaceEntryKind,
43    pub bytes: u64,
44    pub editable: bool,
45    pub reconstructable: bool,
46}
47
48#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
49pub struct WorkspaceListing {
50    pub root: PathBuf,
51    pub entries: Vec<WorkspaceEntry>,
52}
53
54#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
55pub struct WorkspaceTextDocument {
56    pub path: String,
57    pub content: String,
58    pub sha256: String,
59    pub bytes: u64,
60}
61
62#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
63pub struct WorkspaceSaveResult {
64    pub path: String,
65    pub previous_sha256: String,
66    pub document: WorkspaceDocumentState,
67    pub object_id: ObjectId,
68    pub version_id: VersionId,
69}
70
71#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
72pub struct WorkspaceDocumentState {
73    pub path: String,
74    pub sha256: String,
75    pub bytes: u64,
76}
77
78/// Return a deterministic flat projection of an ordinary folderbase folder.
79///
80/// Protocol and Git metadata are hidden. Default reconstructable directories
81/// remain visible as collapsed entries. Symbolic links are represented but
82/// never followed.
83pub fn list_workspace(root: impl AsRef<Path>) -> Result<WorkspaceListing> {
84    let root = canonical_folderbase_root(root.as_ref())?;
85    let mut entries = Vec::new();
86    let mut walker = WalkDir::new(&root)
87        .follow_links(false)
88        .sort_by_file_name()
89        .into_iter();
90
91    while let Some(next) = walker.next() {
92        let entry = next.map_err(|error| {
93            let path = error
94                .path()
95                .map(Path::to_path_buf)
96                .unwrap_or_else(|| root.clone());
97            FolderbaseError::io(
98                path,
99                error
100                    .into_io_error()
101                    .unwrap_or_else(|| io::Error::other("workspace traversal failed")),
102            )
103        })?;
104        if entry.depth() == 0 {
105            continue;
106        }
107        if entry.depth() > MAX_WORKSPACE_DEPTH {
108            return Err(invalid_workspace_record(
109                &root,
110                format!("workspace traversal exceeds the {MAX_WORKSPACE_DEPTH} level depth limit"),
111            ));
112        }
113
114        let file_type = entry.file_type();
115        let name = entry.file_name();
116        if is_reserved_workspace_component(name) {
117            if file_type.is_dir() {
118                walker.skip_current_dir();
119            }
120            continue;
121        }
122        let is_collapsed_reconstructable = file_type.is_dir() && is_reconstructable_directory(name);
123        let is_nested_folderbase_boundary =
124            file_type.is_dir() && has_nested_folderbase_marker(entry.path())?;
125
126        if entries.len() == MAX_WORKSPACE_ENTRIES {
127            return Err(invalid_workspace_record(
128                &root,
129                format!("workspace traversal exceeds {MAX_WORKSPACE_ENTRIES} entries"),
130            ));
131        }
132
133        let relative = entry
134            .path()
135            .strip_prefix(&root)
136            .map_err(|_| FolderbaseError::UnsafePath(entry.path().to_path_buf()))?;
137        let path = displayable_path(relative)?;
138        let name = name
139            .to_str()
140            .map(ToOwned::to_owned)
141            .ok_or_else(|| FolderbaseError::UnsafePath(relative.to_path_buf()))?;
142        let metadata = fs::symlink_metadata(entry.path())
143            .map_err(|source| FolderbaseError::io(entry.path(), source))?;
144
145        let (kind, bytes, editable) = if is_nested_folderbase_boundary {
146            (WorkspaceEntryKind::Folderbase, 0, false)
147        } else if file_type.is_symlink() {
148            (WorkspaceEntryKind::Symlink, 0, false)
149        } else if file_type.is_dir() {
150            (WorkspaceEntryKind::Directory, 0, false)
151        } else if file_type.is_file() {
152            let bytes = metadata.len();
153            (
154                WorkspaceEntryKind::File,
155                bytes,
156                refuse_generic_workspace_mutation_path(relative).is_ok()
157                    && file_is_editable(entry.path(), bytes)?,
158            )
159        } else {
160            continue;
161        };
162
163        entries.push(WorkspaceEntry {
164            path,
165            name,
166            kind,
167            bytes,
168            editable,
169            reconstructable: is_collapsed_reconstructable && !is_nested_folderbase_boundary,
170        });
171        if is_collapsed_reconstructable || is_nested_folderbase_boundary {
172            walker.skip_current_dir();
173        }
174    }
175
176    entries.sort_by(|left, right| left.path.cmp(&right.path));
177    Ok(WorkspaceListing { root, entries })
178}
179
180/// Read one existing, regular UTF-8 document without changing the folderbase.
181pub fn read_workspace_text(
182    root: impl AsRef<Path>,
183    relative_path: impl AsRef<Path>,
184) -> Result<WorkspaceTextDocument> {
185    let root = canonical_folderbase_root(root.as_ref())?;
186    let relative_path = safe_workspace_path(relative_path.as_ref())?;
187    let (file_path, relative_path) = resolve_existing_workspace_file(&root, &relative_path)?;
188    let metadata =
189        fs::metadata(&file_path).map_err(|source| FolderbaseError::io(&file_path, source))?;
190    if metadata.len() > MAX_WORKSPACE_TEXT_BYTES {
191        return Err(workspace_text_too_large(&relative_path));
192    }
193
194    let bytes = read_limited(&file_path)?;
195    if bytes.contains(&0) {
196        return Err(invalid_workspace_record(
197            &relative_path,
198            "workspace text contains a NUL byte",
199        ));
200    }
201    let content = String::from_utf8(bytes.clone())
202        .map_err(|_| invalid_workspace_record(&relative_path, "workspace file is not UTF-8"))?;
203
204    Ok(WorkspaceTextDocument {
205        path: displayable_path(&relative_path)?,
206        content,
207        sha256: format!("{:x}", Sha256::digest(&bytes)),
208        bytes: bytes.len() as u64,
209    })
210}
211
212/// Optimistically replace one existing UTF-8 file and durably version both
213/// sides of the accepted save.
214pub fn save_workspace_text(
215    root: impl AsRef<Path>,
216    relative_path: impl AsRef<Path>,
217    expected_sha256: &str,
218    content: &str,
219) -> Result<WorkspaceSaveResult> {
220    let root = canonical_folderbase_root(root.as_ref())?;
221    let relative_path = safe_workspace_path(relative_path.as_ref())?;
222    refuse_generic_workspace_mutation_path(&relative_path)?;
223    validate_sha256(expected_sha256, &relative_path)?;
224    if content.len() as u64 > MAX_WORKSPACE_TEXT_BYTES {
225        return Err(workspace_text_too_large(&relative_path));
226    }
227    if content.contains('\0') {
228        return Err(invalid_workspace_record(
229            &relative_path,
230            "workspace text contains a NUL byte",
231        ));
232    }
233
234    // Reject an already-stale editor before creating protocol storage. The
235    // version store checks the same precondition again immediately before
236    // accepting its durable transaction.
237    let (_, relative_path) = resolve_existing_workspace_file(&root, &relative_path)?;
238    refuse_generic_workspace_mutation_path(&relative_path)?;
239    let current = read_workspace_text(&root, &relative_path)?;
240    if current.sha256 != expected_sha256 {
241        return Err(FolderbaseError::WorkspaceContentChanged(relative_path));
242    }
243
244    let expected = ContentDigest {
245        algorithm: "sha256".to_owned(),
246        digest: expected_sha256.to_owned(),
247        bytes: current.bytes,
248    };
249    let versioned = LocalVersionStore::open(&root)?.replace_file_versioned(
250        &relative_path,
251        &expected,
252        content.as_bytes(),
253    )?;
254    let path = displayable_path(&relative_path)?;
255    let document = WorkspaceDocumentState {
256        path: path.clone(),
257        sha256: versioned.content.digest.clone(),
258        bytes: versioned.content.bytes,
259    };
260    Ok(WorkspaceSaveResult {
261        path,
262        previous_sha256: versioned.previous_content.digest,
263        document,
264        object_id: versioned.object_id,
265        version_id: versioned.version_id,
266    })
267}
268
269pub(crate) fn canonical_folderbase_root(root: &Path) -> Result<PathBuf> {
270    let metadata = fs::symlink_metadata(root).map_err(|source| match source.kind() {
271        io::ErrorKind::NotFound => FolderbaseError::InvalidRoot(root.to_path_buf()),
272        _ => FolderbaseError::io(root, source),
273    })?;
274    if metadata_is_link_or_reparse(&metadata) || !metadata.is_dir() {
275        return Err(FolderbaseError::InvalidRoot(root.to_path_buf()));
276    }
277    root.canonicalize()
278        .map_err(|source| FolderbaseError::io(root, source))
279}
280
281pub(crate) fn safe_workspace_path(path: &Path) -> Result<PathBuf> {
282    if path.as_os_str().is_empty() || path.is_absolute() || path.to_str().is_none() {
283        return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
284    }
285    let mut normalized = PathBuf::new();
286    for component in path.components() {
287        let Component::Normal(name) = component else {
288            return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
289        };
290        if is_reserved_workspace_component(name) {
291            return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
292        }
293        normalized.push(name);
294    }
295    if normalized.as_os_str().is_empty() {
296        return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
297    }
298    Ok(normalized)
299}
300
301pub(crate) fn resolve_existing_workspace_file(
302    root: &Path,
303    relative: &Path,
304) -> Result<(PathBuf, PathBuf)> {
305    let relative = safe_workspace_path(relative)?;
306    let mut resolved = root.to_path_buf();
307    for component in relative.components() {
308        let Component::Normal(name) = component else {
309            return Err(FolderbaseError::UnsafePath(relative));
310        };
311        resolved.push(name);
312        let metadata = fs::symlink_metadata(&resolved)
313            .map_err(|source| FolderbaseError::io(&resolved, source))?;
314        if metadata.file_type().is_symlink() {
315            return Err(FolderbaseError::UnsafePath(resolved));
316        }
317        if metadata.is_dir() && has_nested_folderbase_marker(&resolved)? {
318            return Err(FolderbaseError::UnsafePath(relative.to_path_buf()));
319        }
320    }
321    let metadata =
322        fs::symlink_metadata(&resolved).map_err(|source| FolderbaseError::io(&resolved, source))?;
323    if !metadata.is_file() || metadata.file_type().is_symlink() {
324        return Err(invalid_workspace_record(
325            resolved,
326            "workspace path is not a regular file",
327        ));
328    }
329    let resolved = resolved
330        .canonicalize()
331        .map_err(|source| FolderbaseError::io(&resolved, source))?;
332    let canonical_relative = resolved
333        .strip_prefix(root)
334        .map_err(|_| FolderbaseError::UnsafePath(resolved.clone()))?
335        .to_path_buf();
336    Ok((resolved, canonical_relative))
337}
338
339pub(crate) fn is_reserved_workspace_component(name: &OsStr) -> bool {
340    is_reserved_component(name)
341}
342
343pub(crate) fn refuse_generic_workspace_mutation_path(path: &Path) -> Result<()> {
344    let mut components = path.components();
345    let is_root_ignore_policy = matches!(
346        components.next(),
347        Some(Component::Normal(name))
348            if name
349                .to_str()
350                .is_some_and(|name| name.eq_ignore_ascii_case(ROOT_IGNORE_POLICY_PATH))
351    ) && components.next().is_none();
352    if is_root_ignore_policy {
353        return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
354    }
355    Ok(())
356}
357
358pub(crate) fn has_nested_folderbase_marker(path: &Path) -> Result<bool> {
359    let directory = Dir::open_ambient_dir(path, ambient_authority())
360        .map_err(|source| FolderbaseError::io(path, source))?;
361    match classify_nested_folderbase_boundary(&directory, path)? {
362        NestedFolderbaseBoundaryKind::ExactBoundary => Ok(true),
363        NestedFolderbaseBoundaryKind::None => Ok(false),
364        NestedFolderbaseBoundaryKind::UnsafeAliasShape => {
365            Err(FolderbaseError::UnsafePath(path.to_path_buf()))
366        }
367    }
368}
369
370fn displayable_path(path: &Path) -> Result<String> {
371    path.to_str()
372        .map(|value| value.replace(std::path::MAIN_SEPARATOR, "/"))
373        .ok_or_else(|| FolderbaseError::UnsafePath(path.to_path_buf()))
374}
375
376fn file_is_editable(path: &Path, bytes: u64) -> Result<bool> {
377    if bytes > MAX_WORKSPACE_TEXT_BYTES {
378        return Ok(false);
379    }
380    match read_limited(path) {
381        Ok(contents) => Ok(!contents.contains(&0) && std::str::from_utf8(&contents).is_ok()),
382        Err(FolderbaseError::InvalidRecord { message, .. })
383            if message.contains("workspace text exceeds") =>
384        {
385            Ok(false)
386        }
387        Err(error) => Err(error),
388    }
389}
390
391fn read_limited(path: &Path) -> Result<Vec<u8>> {
392    let file = fs::File::open(path).map_err(|source| FolderbaseError::io(path, source))?;
393    let mut contents = Vec::new();
394    file.take(MAX_WORKSPACE_TEXT_BYTES + 1)
395        .read_to_end(&mut contents)
396        .map_err(|source| FolderbaseError::io(path, source))?;
397    if contents.len() as u64 > MAX_WORKSPACE_TEXT_BYTES {
398        return Err(workspace_text_too_large(path));
399    }
400    Ok(contents)
401}
402
403fn workspace_text_too_large(path: &Path) -> FolderbaseError {
404    invalid_workspace_record(
405        path,
406        format!(
407            "workspace text exceeds the {} byte limit",
408            MAX_WORKSPACE_TEXT_BYTES
409        ),
410    )
411}
412
413fn validate_sha256(value: &str, path: &Path) -> Result<()> {
414    if value.len() != 64
415        || !value
416            .bytes()
417            .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
418    {
419        return Err(invalid_workspace_record(
420            path,
421            "expected SHA-256 must be 64 lowercase hexadecimal characters",
422        ));
423    }
424    Ok(())
425}
426
427fn invalid_workspace_record(
428    path: impl Into<PathBuf>,
429    message: impl Into<String>,
430) -> FolderbaseError {
431    FolderbaseError::InvalidRecord {
432        path: path.into(),
433        message: message.into(),
434    }
435}
436
437#[cfg(test)]
438mod tests {
439    use super::*;
440
441    #[test]
442    fn generic_mutation_classifier_reserves_ascii_case_variants_only_at_the_root() {
443        for root_policy in [
444            ".folderbaseignore",
445            ".FOLDERBASEIGNORE",
446            ".FolderBaseIgnore",
447        ] {
448            assert!(matches!(
449                refuse_generic_workspace_mutation_path(Path::new(root_policy)),
450                Err(FolderbaseError::UnsafePath(path)) if path == Path::new(root_policy)
451            ));
452        }
453
454        for ordinary_path in [
455            "docs/.folderbaseignore",
456            "docs/.FOLDERBASEIGNORE",
457            ".folderbaseignore.txt",
458        ] {
459            assert!(
460                refuse_generic_workspace_mutation_path(Path::new(ordinary_path)).is_ok(),
461                "{ordinary_path} is not the root capture policy"
462            );
463        }
464    }
465}