From b90d428c3897fd0a08672a85d219c578fa7baa6b Mon Sep 17 00:00:00 2001 From: rain Date: Mon, 16 Nov 2026 00:37:54 +0000 Subject: [PATCH] feat(gc): compact report and API/MCP calls (#50, #51) --- .../references/methods/project.md | 47 +- api/README.md | 2 +- api/crates/layerfs-api/src/calls/mod.rs | 2 +- api/crates/layerfs-api/src/lib.rs | 2 +- api/crates/layerfs-api/src/project/mod.rs | 4 +- api/crates/layerfs-api/src/project/remove.rs | 24 - api/crates/layerfs-api/tests/calls_scope.rs | 1 - api/crates/layerfs-api/tests/calls_table.rs | 21 +- api/crates/layerfs-api/tests/gc_calls.rs | 27 + .../layerfs-api/tests/project_export.rs | 25 +- .../layerfs-api/tests/project_family.rs | 183 +++++- .../layerfs-api/tests/project_init_worker.rs | 11 +- .../layerfs-api/tests/store_projects.rs | 13 +- api/crates/layerfs-api/tests/store_stats.rs | 60 +- api/crates/layerfs-cli/tests/gc.rs | 11 + api/mcp/src/profiles.js | 18 +- api/mcp/src/tools.js | 5 + api/mcp/test/profiles.test.mjs | 14 +- api/mcp/test/workflow.test.mjs | 7 +- api/node/README.md | 2 +- api/node/test/branch-file/inventory.mjs | 4 +- api/node/test/calls.mjs | 4 +- api/python/test/test_calls.py | 2 +- .../crates/layerfs-control/src/inventory.rs | 12 - control/crates/layerfs-control/src/project.rs | 15 +- control/crates/layerfs-control/src/store.rs | 1 - .../layerfs-control/src/worker_server.rs | 14 +- .../layerfs-control/tests/in_use_detail.rs | 38 +- .../crates/layerfs-control/tests/inventory.rs | 7 - .../tests/project_delete_worker.rs | 2 +- .../tests/store_transfer_recovery.rs | 1 - .../layerfs-sandbox/src/daemon/channel.rs | 13 + .../layerfs-sandbox/src/daemon/internal.rs | 11 +- .../src/daemon/workspace/mount.rs | 14 +- .../src/daemon/workspace/recovery.rs | 27 +- .../crates/layerfs-sandbox/src/registry.rs | 4 +- .../layerfs-sandbox/src/workspace/serve.rs | 13 +- control/crates/layerfs-store/src/compact.rs | 41 +- .../crates/layerfs-store/src/project/add.rs | 28 +- .../layerfs-store/src/project/delete.rs | 2 +- .../layerfs-store/src/project/family.rs | 63 +- .../crates/layerfs-store/src/project/frame.rs | 38 +- .../crates/layerfs-store/src/project/mod.rs | 1 - .../layerfs-store/src/project/remove.rs | 68 --- control/crates/layerfs-store/src/related.rs | 4 +- control/crates/layerfs-store/src/status.rs | 10 + .../tests/compact_report_status.rs | 26 + .../tests/project_delete_store.rs | 2 +- .../layerfs-store/tests/project_frames.rs | 31 +- .../layerfs-store/tests/restore_install.rs | 1 - .../layerfs-history/src/contract/catalog.rs | 20 + .../src/encoding/delta/select.rs | 179 +++++- .../crates/layerfs-storage/src/save/pooled.rs | 13 +- .../issues/project-41/gc-t10-report-status.md | 45 +- docs/architecture/api/README.md | 4 +- docs/architecture/api/calls/README.md | 4 +- docs/architecture/api/front-ends/mcp.md | 17 +- docs/architecture/api/sdk/README.md | 16 +- docs/architecture/api/sdk/branch.md | 28 +- docs/architecture/api/sdk/project.md | 78 ++- docs/architecture/api/sdk/store.md | 37 +- docs/architecture/engine/README.md | 2 +- docs/architecture/engine/store/README.md | 8 +- docs/architecture/engine/store/testing.md | 162 +++++ docs/architecture/flows/call.md | 2 +- docs/architecture/glossary.md | 2 +- engine/crates/layerfs-bridge/src/control.rs | 2 +- .../layerfs-bridge/src/control_request.rs | 67 ++- .../layerfs-bridge/src/control_types.rs | 53 ++ .../layerfs-bridge/tests/control_records.rs | 13 + .../src/application/diagnostics.rs | 2 + .../src/application/retained.rs | 2 + .../layerfs-daemon/src/control/operations.rs | 38 +- .../layerfs-daemon/tests/mount_holders.rs | 127 ++++ .../queries/history/gc_intent_all_branch.sql | 2 +- .../queries/history/gc_intent_all_project.sql | 2 +- .../queries/history/gc_intent_ops_branch.sql | 2 +- .../queries/history/gc_intent_ops_project.sql | 2 +- .../src/backend/sqlite/compact.rs | 131 +++- .../src/compact_metrics.rs | 559 ++++++++++++++++++ .../src/history/catalog.rs | 13 + engine/crates/layerfs-persistence/src/lib.rs | 1 + .../tests/compact_metrics.rs | 448 ++++++++++++++ .../tests/concurrent_first_installs.rs | 7 + .../tests/postgresql_commit_round_trips.rs | 5 +- .../tests/postgresql_gc_fence.rs | 532 +++++++++++++++++ .../tests/postgresql_gc_mark.rs | 387 ++++++++++++ .../tests/postgresql_narrow_locations.rs | 21 +- .../layerfs-persistence/tests/support/mod.rs | 3 + .../layerfs-persistence/tests/support/pg.rs | 281 +++++++++ .../crates/layerfs-project/src/store/init.rs | 11 +- .../crates/layerfs-project/src/store/live.rs | 20 +- .../layerfs-project/tests/init_postgresql.rs | 19 +- .../src/history/admission.rs | 11 +- .../src/history/branch.rs | 2 +- .../src/history/lookup.rs | 3 +- .../src/history/saved.rs | 4 +- .../src/operator/files.rs | 2 +- .../src/operator/inspect.rs | 14 +- .../layerfs-store-service/src/store/bind.rs | 49 +- .../layerfs-store-service/tests/admission.rs | 3 + .../tests/golden/sdk_methods.txt | 6 +- .../tests/sdk_path_whiteouts.rs | 56 +- tools/ci/test_store_ext4.sh | 327 ++++++++++ 104 files changed, 4254 insertions(+), 566 deletions(-) delete mode 100644 api/crates/layerfs-api/src/project/remove.rs delete mode 100644 control/crates/layerfs-store/src/project/remove.rs create mode 100644 docs/architecture/engine/store/testing.md create mode 100644 engine/crates/layerfs-daemon/tests/mount_holders.rs create mode 100644 engine/crates/layerfs-persistence/src/compact_metrics.rs create mode 100644 engine/crates/layerfs-persistence/tests/compact_metrics.rs create mode 100644 engine/crates/layerfs-persistence/tests/postgresql_gc_fence.rs create mode 100644 engine/crates/layerfs-persistence/tests/postgresql_gc_mark.rs create mode 100644 engine/crates/layerfs-persistence/tests/support/pg.rs create mode 100755 tools/ci/test_store_ext4.sh diff --git a/.agents/skills/layerfs-js-sdk/references/methods/project.md b/.agents/skills/layerfs-js-sdk/references/methods/project.md index bbd29a11b0..59e6ea6a6c 100644 --- a/.agents/skills/layerfs-js-sdk/references/methods/project.md +++ b/.agents/skills/layerfs-js-sdk/references/methods/project.md @@ -13,7 +13,8 @@ project.init(project, folder, { timeout, on_progress }) project.list(store?, { page_size, page_pos }) project.get(project) project.export(project, destination, { branch, on_progress }) -project.remove(project) +project.delete(project) +project.remove_file(project, path) ``` ## `project.init` @@ -119,23 +120,41 @@ The project's record: its Store, the Store's kind and machine. {"project":"shop/api","store":"shop","name":"api","kind":"sqlite","machine":"native","created":1793574061265} ``` -## `project.remove` +## `project.delete` -`project.remove(project)` +`project.delete(project)` -Removes one project from its Store. Its Branches, Commits and `main` go with -it; there is no undo. The live result: +Retires one project in its Store and removes its home entry (spec §4). The +project disappears from `project.list` and `project.get`; its Layers, +Branches, Commits and stored content stay until a later `store.compact`, and +the Store stays addressable. The live result: ```json -{"stack":"3104401f11fb…","packs_kept":true,"project":"shop/api"} +{"kind":"Removed","project":"shop/api","deleted_ms":1793574061265,"home_entry_removed":true} ``` -`packs_kept: true`: the project's records are gone, but its stored content -stays in the Store file. Removing a project from a PostgreSQL Store is -`Unsupported` in this build. While a Sandbox of the project is recorded it is -refused `InUse`; `detail.related` lists each as `{ kind: "sandbox", name }` -(close them first). To delete a whole Store with every project in it, use -`store.remove`. +The Store marker is the commit point. If the home entry cannot be removed the +call still succeeds with `home_entry_removed: false` and keeps a durable +intent, so the same call retried from the same home reuses `deleted_ms` and +finishes the entry. A mount of the project is refused `MountsActive`, another +user or operation `Busy`/`Unresolved`. -An agent working on a project never needs `remove`; it is for whoever owns the -home. +## `project.remove_file` + +`project.remove_file(project, path)` + +Hides one absolute project path from every node at or below its marker +frontier (spec §4.3). It writes a marker only; no bytes are freed. The path is +normalized (one leading `/` stripped) and must be a canonical absolute POSIX +path. The live result: + +```json +{"kind":"Removed","project":"shop/api","path":"docs/old.md","frontier_serial":42,"removed_ms":1793574061265} +``` + +`kind` is `UpToDate` when no project node is above this path's marker +frontier. Later reads and stats of the path are refused `Removed`; a Commit +after the frontier that writes the path again is visible. + +An agent working on a project never needs `delete` or `remove_file`; they are +for whoever owns the home. diff --git a/api/README.md b/api/README.md index c7329db066..ae3d5d2bc8 100644 --- a/api/README.md +++ b/api/README.md @@ -10,7 +10,7 @@ CLI package `@layerfs/cli` (in [`cli/`](cli)), the Python package (in the private stdio MCP server [`mcp/`](mcp) (`@layerfs/mcp`: one generated tool per call, `work` and `admin` profiles). The design is in [docs/architecture/api](../docs/architecture/api/README.md). The package is the -library's call table as ten families of functions, 73 calls in all: +library's call table as ten families of functions, 76 calls in all: | Family | Calls | | --- | --- | diff --git a/api/crates/layerfs-api/src/calls/mod.rs b/api/crates/layerfs-api/src/calls/mod.rs index ef74ed4009..e90eae9b74 100644 --- a/api/crates/layerfs-api/src/calls/mod.rs +++ b/api/crates/layerfs-api/src/calls/mod.rs @@ -2,7 +2,7 @@ //! table's shape, argument checks, folder scope, result keys and the one //! dispatcher with its call log line (`render`, #659); moved back from //! `layerfs-control` by layerfs-project#107. -//! The 70 entries in ten families live beside it, one folder per family and +//! The 76 entries in ten families live beside it, one folder per family and //! one file per call; each function here that needs them takes that list. mod check; mod context; diff --git a/api/crates/layerfs-api/src/lib.rs b/api/crates/layerfs-api/src/lib.rs index 0f67fadce2..83c1d4676b 100644 --- a/api/crates/layerfs-api/src/lib.rs +++ b/api/crates/layerfs-api/src/lib.rs @@ -71,7 +71,7 @@ pub use layerfs_sandbox::{ BoundWorkspace, MountFailure, MountedWorkspace, Unmounted, WorkspaceApi, }; -/// The ten families, in the order help lists them: 77 calls, the same +/// The ten families, in the order help lists them: 76 calls, the same /// from the `layerfs` binary, Node and Python. pub fn families() -> Families { &[ diff --git a/api/crates/layerfs-api/src/project/mod.rs b/api/crates/layerfs-api/src/project/mod.rs index 7a65fd924f..caee164cb7 100644 --- a/api/crates/layerfs-api/src/project/mod.rs +++ b/api/crates/layerfs-api/src/project/mod.rs @@ -1,10 +1,9 @@ -//! The `project` family: 8 calls, one file each. +//! The `project` family: 7 calls, one file each. mod delete; mod export; mod get; mod init; mod list; -mod remove; mod remove_file; mod stats; @@ -20,6 +19,5 @@ pub(crate) fn calls() -> Calls { export::CALL, delete::CALL, remove_file::CALL, - remove::CALL, ] } diff --git a/api/crates/layerfs-api/src/project/remove.rs b/api/crates/layerfs-api/src/project/remove.rs deleted file mode 100644 index c464f1a441..0000000000 --- a/api/crates/layerfs-api/src/project/remove.rs +++ /dev/null @@ -1,24 +0,0 @@ -//! `project.remove`: remove one project from its Store. -use crate::calls::table::Kind::Project; -use crate::calls::table::{a, call, Call}; -use crate::calls::Context; -use layerfs_bridge::control::SdkValue; -use layerfs_home::names::ProjectRef; -use layerfs_home::outcome::Outcome; - -/// Its table entry. -pub(crate) const CALL: Call = call( - "project", - "remove", - &[a("project", Project)], - &[], - "remove one project from its Store", - run, -); - -/// Runs `project.remove`. -fn run(context: &mut Context<'_>, args: &SdkValue) -> Outcome { - let project = ProjectRef::parse(args.get_text("project").unwrap_or(""))?; - let (home, events) = context.parts(); - layerfs_control::project::remove(home, events, &project) -} diff --git a/api/crates/layerfs-api/tests/calls_scope.rs b/api/crates/layerfs-api/tests/calls_scope.rs index 5b324435e0..28d19e6e6d 100644 --- a/api/crates/layerfs-api/tests/calls_scope.rs +++ b/api/crates/layerfs-api/tests/calls_scope.rs @@ -114,7 +114,6 @@ fn a_scope_refuses_every_call_it_does_not_cover() { let uncovered: &[(&str, &[(&str, SdkValue)])] = &[ ("store.remove", &[("name", t("shop"))]), ("store.list", &[]), - ("project.remove", &[("project", t("shop/api"))]), ( "branch.remove", &[("project", t("shop/api")), ("branch", t("main"))], diff --git a/api/crates/layerfs-api/tests/calls_table.rs b/api/crates/layerfs-api/tests/calls_table.rs index 2ba77897cd..0f329039b2 100644 --- a/api/crates/layerfs-api/tests/calls_table.rs +++ b/api/crates/layerfs-api/tests/calls_table.rs @@ -1,4 +1,4 @@ -//! The call table and its dispatcher (#533 step 2): 77 calls in ten +//! The call table and its dispatcher (#533 step 2): 76 calls in ten //! families, arguments checked before any effect, one test per family that //! a valid call reaches its family function and a wrong one is refused. use layerfs_api::{families, json, keys, size, Call, Kind}; @@ -51,9 +51,9 @@ fn code(name: &str, args: SdkValue) -> String { } #[test] -fn the_table_has_ten_families_and_77_calls() { +fn the_table_has_ten_families_and_76_calls() { let all: Vec<&Call> = layerfs_api::calls(); - assert_eq!(all.len(), 77); + assert_eq!(all.len(), 76); // each family holds only its own calls, and has at least one for family in families() { assert!(!family.calls().is_empty(), "{}", family.name); @@ -66,7 +66,7 @@ fn the_table_has_ten_families_and_77_calls() { let mut names: Vec<_> = all.iter().map(|c| c.name()).collect(); names.sort(); names.dedup(); - assert_eq!(names.len(), 77, "call names are unique"); + assert_eq!(names.len(), 76, "call names are unique"); // an optional positional is only ever followed by optional ones (D7) for c in &all { let first_optional = c.args.iter().position(|a| a.optional); @@ -75,7 +75,7 @@ fn the_table_has_ten_families_and_77_calls() { } } let counts: Vec = families().iter().map(|f| f.calls().len()).collect(); - assert_eq!(counts, [8, 9, 3, 15, 4, 6, 12, 13, 5, 2]); + assert_eq!(counts, [7, 9, 3, 15, 4, 6, 12, 13, 5, 2]); } #[test] @@ -98,6 +98,17 @@ fn unknown_calls_and_arguments_are_refused_before_any_effect() { .starts_with("InvalidInput")); } +#[test] +fn project_remove_is_retired() { + // spec 4: the hard delete leaves the table; a caller gets `InvalidInput` + // naming it, never a silent hard delete + assert!(layerfs_api::find("project.remove").is_none()); + assert_eq!( + code("project.remove", map(&[("project", t("shop/api"))])), + "InvalidInput: no call named `project.remove`" + ); +} + #[test] fn project_family() { assert!(code("project.get", map(&[("project", t("api"))])) diff --git a/api/crates/layerfs-api/tests/gc_calls.rs b/api/crates/layerfs-api/tests/gc_calls.rs index c7d37f5d24..ad390c8eab 100644 --- a/api/crates/layerfs-api/tests/gc_calls.rs +++ b/api/crates/layerfs-api/tests/gc_calls.rs @@ -246,6 +246,33 @@ fn project_delete_reports_removal_and_retires_the_entry() { let _ = std::fs::remove_dir_all(folder); } +/// A project name a `project.delete` retired is still held: a second +/// `project.init` is `NameTaken` with the `deleted` holder, refused before +/// the folder is scanned. +#[test] +fn project_init_after_delete_is_nametaken_deleted() { + let (home, folder) = project(); + ok(&home, "project.delete", &[p()]); + let refusal = layerfs_api::call( + Some(&home), + "project.init", + map(&[ + ("project", t("shop/api")), + ("folder", t(&folder.display().to_string())), + ]), + &mut |_| {}, + ) + .unwrap_err(); + assert_eq!(refusal.code, "NameTaken", "{}", refusal.message); + let holder = refusal.detail.get("holder").expect("holder detail"); + assert_eq!(holder.get_text("kind"), Some("project"), "{refusal:?}"); + assert_eq!(holder.get_text("name"), Some("api")); + assert_eq!(holder.get_text("state"), Some("deleted")); + assert_eq!(refusal.detail.get_text("source"), Some("store")); + std::fs::remove_dir_all(home).unwrap(); + let _ = std::fs::remove_dir_all(folder); +} + #[test] fn store_compact_refuses_an_unknown_store_and_reports_a_run() { let home = tempdir("compact-none"); diff --git a/api/crates/layerfs-api/tests/project_export.rs b/api/crates/layerfs-api/tests/project_export.rs index 0db2299303..07a79b982c 100644 --- a/api/crates/layerfs-api/tests/project_export.rs +++ b/api/crates/layerfs-api/tests/project_export.rs @@ -1283,7 +1283,7 @@ fn shared_store_lease_and_concurrent_remove_admission() { // 2. During an in-flight `project.export`: // - same-Store `file.read` and a second concurrent `project.export` succeed; // - exclusive Store operations (`store.remove`, `store.push`) are refused `InUse`; - // - `project.remove` drops the catalog stack while packs stay (`packs_kept: true`), + // - `project.delete` retires the Stack (its marker keeps packs/objects), // leaving the in-flight pinned export intact while refusing later exports. let first_dest = area.join("first"); let second_dest = area.join("second"); @@ -1336,10 +1336,14 @@ fn shared_store_lease_and_concurrent_remove_admission() { .unwrap_err(); assert_eq!(push_code, "InUse", "{push_msg}"); - // `project.remove` drops the LayerStack while keeping packs/objects; - // the already-pinned export continues without corruption. - let removed = ok(&home, "project.remove", &[("project", t("shop/app"))]); - assert_eq!(removed.get("packs_kept"), Some(&SdkValue::Bool(true))); + // `project.delete` retires the LayerStack and removes the home + // entry; the already-pinned export continues without corruption. + let removed = ok(&home, "project.delete", &[("project", t("shop/app"))]); + assert_eq!(removed.get_text("kind"), Some("Removed")); + assert_eq!( + removed.get("home_entry_removed"), + Some(&SdkValue::Bool(true)) + ); } }, ) @@ -1350,7 +1354,7 @@ fn shared_store_lease_and_concurrent_remove_admission() { assert_same_tree(&source, &second_dest); let _ = std::fs::remove_file(&other_lease); - // After `project.remove`, a new export is refused `NoSuchProject` + // After `project.delete`, a new export is refused `NoSuchProject` let after_rm_dest = area.join("after-rm"); let (code, _) = call( &home, @@ -1364,12 +1368,13 @@ fn shared_store_lease_and_concurrent_remove_admission() { assert_eq!(code, "NoSuchProject"); assert!(!after_rm_dest.exists()); - // Re-init `shop/app` and verify Store-level `Busy` and `Unresolved` admission + // Re-init a new project (`shop/app` stays a retired name) and verify + // Store-level `Busy` and `Unresolved` admission. ok( &home, "project.init", &[ - ("project", t("shop/app")), + ("project", t("shop/app2")), ("folder", t(&source.display().to_string())), ], ); @@ -1394,7 +1399,7 @@ fn shared_store_lease_and_concurrent_remove_admission() { &home, "project.export", &[ - ("project", t("shop/app")), + ("project", t("shop/app2")), ("destination", t(&busy_dest.display().to_string())), ], ) @@ -1419,7 +1424,7 @@ fn shared_store_lease_and_concurrent_remove_admission() { &home, "project.export", &[ - ("project", t("shop/app")), + ("project", t("shop/app2")), ("destination", t(&busy_dest.display().to_string())), ], ) diff --git a/api/crates/layerfs-api/tests/project_family.rs b/api/crates/layerfs-api/tests/project_family.rs index fc4ba41bc0..3039230e5a 100644 --- a/api/crates/layerfs-api/tests/project_family.rs +++ b/api/crates/layerfs-api/tests/project_family.rs @@ -3,7 +3,7 @@ //! it, the Store pushed to a worker machine and read there, then the project //! removed. use layerfs_api::home::{self, paths, write_record}; -use layerfs_bridge::control::SdkValue; +use layerfs_bridge::control::{SdkRefusal, SdkValue}; use std::net::TcpListener; use std::path::{Path, PathBuf}; @@ -335,7 +335,15 @@ fn init_files_branches_move_and_remove() { ); assert_eq!(content(&read), "newer\n", "read through the worker"); - ok(&home, "project.remove", &[p()]); + // `project.delete` retires the project in the Store under `box` and + // removes both entries; its history stays until a compaction. + let deleted = ok(&home, "project.delete", &[p()]); + assert_eq!(deleted.get_text("kind"), Some("Removed")); + assert_eq!(deleted.get_text("project"), Some("shop/api")); + assert_eq!( + deleted.get("home_entry_removed"), + Some(&SdkValue::Bool(true)) + ); assert_eq!( call(&home, "project.get", &[p()]).unwrap_err().0, "NoSuchProject" @@ -389,3 +397,174 @@ fn a_private_home_may_be_passable_and_nothing_more() { std::fs::remove_dir_all(home).unwrap(); let _ = std::fs::remove_dir_all(folder); } + +fn refused(home: &Path, name: &str, args: &[(&str, SdkValue)]) -> SdkRefusal { + let args = SdkValue::Map( + args.iter() + .map(|(n, v)| ((*n).to_owned(), v.clone())) + .collect(), + ); + layerfs_api::call(Some(home), name, args, &mut |_| {}).expect_err("the call is refused") +} + +fn private_home(tag: &str) -> PathBuf { + let home = tempdir(tag); + use std::os::unix::fs::PermissionsExt; + std::fs::set_permissions(&home, std::fs::Permissions::from_mode(0o700)).unwrap(); + home::open(&home).unwrap(); + home +} + +/// A `project.init` name collision is the typed `NameTaken`: the home record +/// first, and the Store's own holder when the home has no record for it. +#[test] +fn project_init_name_collision_reports_holder_and_source() { + let home = private_home("name-taken"); + let folder = tempdir("name-taken-folder"); + std::fs::write(folder.join("README"), b"held\n").unwrap(); + ok(&home, "store.create", &[("name", t("shop"))]); + ok( + &home, + "project.init", + &[ + ("project", t("shop/api")), + ("folder", t(&folder.display().to_string())), + ], + ); + + let home_taken = refused( + &home, + "project.init", + &[ + ("project", t("shop/api")), + ("folder", t(&folder.display().to_string())), + ], + ); + assert_eq!(home_taken.code, "NameTaken", "{}", home_taken.message); + let holder = home_taken.detail.get("holder").expect("holder detail"); + assert_eq!(holder.get_text("kind"), Some("project")); + assert_eq!(holder.get_text("name"), Some("api")); + assert_eq!(holder.get_text("state"), Some("live")); + assert_eq!(home_taken.detail.get_text("source"), Some("home")); + + // A home that no longer records the project meets the Store's own holder. + std::fs::remove_dir_all(paths::project_dir(&home, "shop", "api")).unwrap(); + let store_taken = refused( + &home, + "project.init", + &[ + ("project", t("shop/api")), + ("folder", t(&folder.display().to_string())), + ], + ); + assert_eq!(store_taken.code, "NameTaken", "{}", store_taken.message); + let holder = store_taken.detail.get("holder").expect("holder detail"); + assert_eq!(holder.get_text("kind"), Some("project")); + assert_eq!(holder.get_text("name"), Some("api")); + assert_eq!(holder.get_text("state"), Some("live")); + assert_eq!(store_taken.detail.get_text("source"), Some("store")); + + std::fs::remove_dir_all(home).unwrap(); + let _ = std::fs::remove_dir_all(folder); +} + +/// A Layer keeps the name of the Branch it was published from after that +/// Branch is retired: provenance rendering is not a caller-facing lookup. +#[test] +fn a_retired_source_branch_still_renders_on_its_layers() { + let home = private_home("retired-source"); + let folder = tempdir("retired-source-folder"); + std::fs::write(folder.join("base.txt"), b"base\n").unwrap(); + ok(&home, "store.create", &[("name", t("shop"))]); + ok( + &home, + "project.init", + &[ + ("project", t("shop/api")), + ("folder", t(&folder.display().to_string())), + ], + ); + ok( + &home, + "branch.fork", + &[ + ("project", t("shop/api")), + ("name", t("work")), + ("from_branch", t("main")), + ], + ); + ok( + &home, + "file.write", + &[ + ("project", t("shop/api")), + ("branch", t("work")), + ("path", t("/new.txt")), + ("content", t("new\n")), + ("message", t("new")), + ], + ); + ok( + &home, + "branch.publish", + &[("project", t("shop/api")), ("branch", t("work"))], + ); + + let main = ok( + &home, + "commit.list", + &[("project", t("shop/api")), ("branch", t("main"))], + ); + let SdkValue::List(layers) = main.get("items").expect("items") else { + panic!("{main:?}") + }; + let id = layers[0].get_text("id").expect("layer id").to_owned(); + assert_eq!(layers[0].get_text("source_branch"), Some("work"), "{main:?}"); + + ok( + &home, + "branch.remove", + &[("project", t("shop/api")), ("branch", t("work"))], + ); + + // `layer.list` still renders the provenance ... + let main = ok( + &home, + "commit.list", + &[("project", t("shop/api")), ("branch", t("main"))], + ); + let SdkValue::List(layers) = main.get("items").expect("items") else { + panic!("{main:?}") + }; + assert_eq!( + layers[0].get_text("source_branch"), + Some("work"), + "layer.list: {main:?}" + ); + // ... and so does `layer.get` ... + let got = ok( + &home, + "commit.get", + &[ + ("project", t("shop/api")), + ("branch", t("main")), + ("commit", t(&id)), + ], + ); + assert_eq!( + got.get_text("source_branch"), + Some("work"), + "layer.get: {got:?}" + ); + // ... while a caller-facing lookup of the retired Branch stays refused. + let (code, message) = call( + &home, + "branch.get", + &[("project", t("shop/api")), ("branch", t("work"))], + ) + .unwrap_err(); + assert_eq!(code, "NoSuchBranch", "{message}"); + + std::fs::remove_dir_all(home).unwrap(); + let _ = std::fs::remove_dir_all(folder); +} diff --git a/api/crates/layerfs-api/tests/project_init_worker.rs b/api/crates/layerfs-api/tests/project_init_worker.rs index d0f3900c4b..07b805b32d 100644 --- a/api/crates/layerfs-api/tests/project_init_worker.rs +++ b/api/crates/layerfs-api/tests/project_init_worker.rs @@ -231,14 +231,19 @@ fn init_into_a_worker_s_store_copies_the_caller_s_folder() { let stat = store_call(&home, "file.stat", "shop/web", "/link"); assert_eq!(stat.get_text("type"), Some("symlink"), "{stat:?}"); - let again = call( - &home, + let again = layerfs_api::call( + Some(&home), "project.init", init_args("shop/web", &folder), &mut |_| {}, ) .unwrap_err(); - assert_eq!(again.0, "Exists", "{}", again.1); + assert_eq!(again.code, "NameTaken", "{}", again.message); + let holder = again.detail.get("holder").expect("holder detail"); + assert_eq!(holder.get_text("kind"), Some("project"), "{again:?}"); + assert_eq!(holder.get_text("name"), Some("web")); + assert_eq!(holder.get_text("state"), Some("live")); + assert_eq!(again.detail.get_text("source"), Some("home")); open_up(&folder); let (missing, plain) = (missing.parent().unwrap(), plain.parent().unwrap()); diff --git a/api/crates/layerfs-api/tests/store_projects.rs b/api/crates/layerfs-api/tests/store_projects.rs index 8961aaf5f8..9f3875af36 100644 --- a/api/crates/layerfs-api/tests/store_projects.rs +++ b/api/crates/layerfs-api/tests/store_projects.rs @@ -7,7 +7,10 @@ use layerfs_content::{ file::FileView, filesystem::{FilesystemRead, FilesystemRootId, LogicalPath}, }; -use layerfs_history::{BranchId, HistoryCatalog, HistoryCatalogConfig, HistoryName, LayerStackId}; +use layerfs_history::{ + error::{HolderKind, HolderState, NameSource}, + BranchId, HistoryCatalog, HistoryCatalogConfig, HistoryName, LayerStackId, +}; use layerfs_persistence::{PersistenceConfig, SqliteHandles, SqlitePersistenceProfile}; use layerfs_storage::StoragePolicy; use layerfs_telemetry::timer::Timing; @@ -124,7 +127,13 @@ fn an_empty_store_holds_two_projects_and_refuses_a_taken_name() { assert_ne!(shop.initialized.root, api.initialized.root); assert_eq!(shop.branch.effective_root, shop.initialized.root); let taken = add(&path, source(&directory, "again", b"x"), "shop", 30); - assert!(matches!(taken, Err(InitError::Exists)), "{taken:?}"); + let Err(InitError::NameTaken(state)) = taken else { + panic!("a held project name is NameTaken: {taken:?}"); + }; + assert_eq!(state.holder.kind, HolderKind::Project); + assert_eq!(state.holder.name, "shop"); + assert_eq!(state.holder.state, HolderState::Live); + assert_eq!(state.source, NameSource::Store); let handles = SqliteHandles::open_writable(store(&path), BINDING, CURSOR).unwrap(); let names: Vec<_> = projects(&handles.history) diff --git a/api/crates/layerfs-api/tests/store_stats.rs b/api/crates/layerfs-api/tests/store_stats.rs index dcb2fceded..54cfc0f3a5 100644 --- a/api/crates/layerfs-api/tests/store_stats.rs +++ b/api/crates/layerfs-api/tests/store_stats.rs @@ -26,28 +26,31 @@ fn call(home: &Path, method: &str, fields: &[(&str, SdkValue)]) -> SdkValue { layerfs_api::call(Some(home), method, args, &mut |_| {}) .unwrap_or_else(|r| panic!("{method}: {r:?}")) } -fn check(home: &Path, kind: &str) { +fn check(home: &Path, kind: &str, test: &str) { let stats = || call(home, "store.stats", &[("name", t("stats"))]); let empty = stats(); assert_eq!(empty.get_text("kind"), Some(kind)); - assert_eq!(empty.get_int("history_logical"), Some(0)); + // a previous project's bytes stay after its soft delete, so later runs + // measure from the Store's current history + let base = empty.get_int("history_logical").unwrap(); assert_eq!( empty.get("free") == Some(&SdkValue::Null), kind == "postgresql" ); assert!(empty.get("dedupe").is_none()); - let source = folder(&format!("input-{kind}")); + let name = format!("stats/{test}"); + let source = folder(&format!("input-{kind}-{test}")); std::fs::write(source.join("file"), "hello").unwrap(); call( home, "project.init", &[ - ("project", t("stats/p")), + ("project", t(&name)), ("folder", t(source.to_str().unwrap())), ], ); let initial = stats(); - assert_eq!(initial.get_int("history_logical"), Some(5)); + assert_eq!(initial.get_int("history_logical"), Some(base + 5)); assert!(initial.get_int("canonical").unwrap() > 0); assert!(initial.get_int("stored").unwrap() > 0); assert!(initial.get_int("file").unwrap() > 0); @@ -55,7 +58,7 @@ fn check(home: &Path, kind: &str) { home, "branch.fork", &[ - ("project", t("stats/p")), + ("project", t(&name)), ("name", t("dev")), ("from_branch", t("main")), ], @@ -64,7 +67,7 @@ fn check(home: &Path, kind: &str) { home, "file.write", &[ - ("project", t("stats/p")), + ("project", t(&name)), ("branch", t("dev")), ("path", t("/file")), ("content", t("abcdef")), @@ -73,30 +76,31 @@ fn check(home: &Path, kind: &str) { call( home, "branch.publish", - &[("project", t("stats/p")), ("branch", t("dev"))], + &[("project", t(&name)), ("branch", t("dev"))], ); let published = stats(); assert_eq!( published.get_int("history_logical"), - Some(17), + Some(base + 17), "Commit and Layer count their snapshots" ); - if kind == "postgresql" { - let refused = layerfs_api::call( - Some(home), - "project.remove", - SdkValue::map([("project", t("stats/p"))]), - &mut |_| {}, - ) - .unwrap_err(); - assert_eq!(refused.code, "Unsupported"); - } else { - call(home, "project.remove", &[("project", t("stats/p"))]); - let removed = stats(); - assert_eq!(removed.get_int("history_logical"), Some(0)); - assert_eq!(removed.get("canonical"), published.get("canonical")); - assert_eq!(removed.get("stored"), published.get("stored")); - } + // `project.delete` retires the Stack and removes the home entry; the + // marker is the commit point, so the history bytes stay until a + // `store.compact` collects them and the counters do not drop. + call(home, "project.delete", &[("project", t(&name))]); + let removed = stats(); + assert_eq!(removed.get_int("history_logical"), Some(base + 17)); + assert_eq!(removed.get("canonical"), published.get("canonical")); + assert_eq!(removed.get("stored"), published.get("stored")); + let gone = layerfs_api::call( + Some(home), + "project.get", + SdkValue::map([("project", t(&name))]), + &mut |_| {}, + ) + .unwrap_err(); + assert_eq!(gone.code, "NoSuchProject"); + assert!(!paths::project_record(home, "stats", test).exists()); layerfs_api::close_idle(std::time::Duration::ZERO); std::fs::remove_dir_all(source).unwrap(); } @@ -105,7 +109,7 @@ fn check(home: &Path, kind: &str) { fn native_sqlite_and_worker_statistics_use_the_same_counters() { let home = folder("sqlite-home"); call(&home, "store.create", &[("name", t("stats"))]); - check(&home, "sqlite"); + check(&home, "sqlite", "p"); let root = folder("worker-root"); let listener = TcpListener::bind("127.0.0.1:0").unwrap(); let address = listener.local_addr().unwrap().to_string(); @@ -126,7 +130,7 @@ fn native_sqlite_and_worker_statistics_use_the_same_counters() { "store.push", &[("name", t("stats")), ("machine", t("box"))], ); - check(&home, "sqlite"); + check(&home, "sqlite", "w"); // A stopped worker refuses rather than starting anything. layerfs_api::close_idle(std::time::Duration::ZERO); std::fs::remove_file(paths::worker_record(&home, "box")).unwrap(); @@ -159,6 +163,6 @@ fn postgresql_statistics_have_null_free_and_count_publications() { ("synchronous_commit", t("off")), ], ); - check(&home, "postgresql"); + check(&home, "postgresql", "p"); std::fs::remove_dir_all(home).unwrap(); } diff --git a/api/crates/layerfs-cli/tests/gc.rs b/api/crates/layerfs-cli/tests/gc.rs index 36d04aeb68..0b2096f0d6 100644 --- a/api/crates/layerfs-cli/tests/gc.rs +++ b/api/crates/layerfs-cli/tests/gc.rs @@ -36,6 +36,17 @@ const CALLS: &[(&[&str], &str, &str)] = &[ ), ]; +#[test] +fn project_remove_is_a_usage_error() { + let home = tempdir("gc-remove"); + let (code, out, err) = run_code(&home, &["project", "remove", "shop/api"]); + assert_eq!(code, Some(2), "{out} {err}"); + assert!(err.contains("no call `project remove`"), "{err}"); + assert!(out.is_empty(), "{out}"); + assert!(!home.join("store").exists(), "no call reached a home"); + std::fs::remove_dir_all(home).unwrap(); +} + #[test] fn help_lists_each_gc_call_with_its_usage() { let home = tempdir("gc-help"); diff --git a/api/mcp/src/profiles.js b/api/mcp/src/profiles.js index 495a83bff4..cec2810f13 100644 --- a/api/mcp/src/profiles.js +++ b/api/mcp/src/profiles.js @@ -6,7 +6,8 @@ // Assignment rule (each call lands in exactly one bucket, none excluded): // work the families an agent works in (branch, commit, file, workspace) // plus the read-only project and Sandbox calls named below -// admin every other call: project create/remove, Sandbox create/close, +// admin every other call: project create/delete/remove_file, Branch +// remove, Sandbox create/close, // and the machine, store, backup and logs families // The `admin` launch profile exposes the union, so `admin` adds the // administrative calls to the `work` set. @@ -20,15 +21,15 @@ const WORK_FAMILIES = new Set(["branch", "commit", "file", "workspace"]); /** Read-only calls of families that are otherwise administration. */ const WORK_CALLS = new Set(["project.list", "project.get", "project.stats", "project.export", "sandbox.list", "sandbox.get"]); -/** Administrative calls of the project and sandbox families. */ -const ADMIN_CALLS = new Set(["project.init", "project.remove", "sandbox.create", "sandbox.close"]); +/** Administrative calls outside the admin families. */ +const ADMIN_CALLS = new Set(["project.init", "project.delete", "project.remove_file", "branch.remove", "sandbox.create", "sandbox.close"]); /** Families whose every call belongs to the `admin` profile. */ const ADMIN_FAMILIES = new Set(["machine", "store", "backup", "logs"]); /** Why a family's calls sit where they do; one line per family, in the doc. */ const WHY = { - project: "read a project's record or its entry counts, or export one (work); importing and removing a project are administration", + project: "read a project's record or its entry counts, or export one (work); importing, deleting or hiding a path in a project is administration", branch: "work on Branches: list, read, fork, merge, publish and diff", commit: "read a Branch's Commit history", file: "read and change files in a Branch; each write is one explicit Commit", @@ -48,9 +49,11 @@ const nameOf = (spec) => `${spec.family}.${spec.call}`; */ export function bucketOf(spec) { const name = nameOf(spec); + // The admin exception list is checked before the work families: a retired + // entity in a work family (`branch.remove`) is still administration (§10). + if (ADMIN_CALLS.has(name)) return "admin"; if (WORK_CALLS.has(name)) return "work"; if (WORK_FAMILIES.has(spec.family)) return "work"; - if (ADMIN_CALLS.has(name)) return "admin"; if (ADMIN_FAMILIES.has(spec.family)) return "admin"; return null; } @@ -58,7 +61,10 @@ export function bucketOf(spec) { /** Why this call is in its bucket: a line for the generated documentation table. */ export function whyOf(spec) { if (spec.family === "project" && spec.call === "init") return "import a host folder into a Store; administration"; - if (spec.family === "project" && spec.call === "remove") return "remove a project from its Store; administration"; + if (spec.family === "project" && spec.call === "delete") return "retire a project in its Store and remove its home entry; administration; a folder scope refuses it"; + if (spec.family === "project" && spec.call === "remove_file") return "hide one absolute path from every node at or below its marker frontier; administration; a folder scope refuses it"; + if (spec.family === "branch" && spec.call === "remove") return "retire one Branch in its Store; administration; a folder scope refuses it"; + if (spec.family === "store" && spec.call === "compact") return "reclaim one sqlite Store's dead bytes; administration; a folder scope refuses it"; if (spec.family === "sandbox" && spec.call === "create") return "start a Sandbox process; administration"; if (spec.family === "sandbox" && spec.call === "close") return "stop a Sandbox; administration"; if (spec.family === "project" && spec.call === "export") return "export a Branch snapshot to a local folder under a launch-time --export-root; a folder scope refuses it"; diff --git a/api/mcp/src/tools.js b/api/mcp/src/tools.js index c8fc065b52..8f7635a9b0 100644 --- a/api/mcp/src/tools.js +++ b/api/mcp/src/tools.js @@ -31,6 +31,11 @@ const COMMON = { description: "a whole number; send a decimal string to keep one beyond ±(2^53-1) exact", }, bool: { type: "boolean" }, + image: { + type: "string", + minLength: 1, + description: "a sha256: image digest, a Docker image id, or a Docker reference such as postgres:17-bookworm", + }, size: { oneOf: [{ type: "integer" }, { type: "string", minLength: 1 }], description: "a size in bytes, or text such as \"512M\" or \"8G\"", diff --git a/api/mcp/test/profiles.test.mjs b/api/mcp/test/profiles.test.mjs index 39752837d6..fce4272a92 100644 --- a/api/mcp/test/profiles.test.mjs +++ b/api/mcp/test/profiles.test.mjs @@ -13,20 +13,28 @@ const nameOf = (spec) => `${spec.family}.${spec.call}`; test("every call is in exactly one bucket, and admin adds the work bucket", () => { assert.deepEqual(check(table), []); - assert.equal(table.length, 73); + assert.equal(table.length, 76); const buckets = table.map(bucketOf); assert.equal(buckets.filter((bucket) => bucket === "work").length, 38); - assert.equal(buckets.filter((bucket) => bucket === "admin").length, 35); + assert.equal(buckets.filter((bucket) => bucket === "admin").length, 38); assert.ok(buckets.every((bucket) => bucket === "work" || bucket === "admin")); const work = tools(table, "work").map(nameOf); const admin = tools(table, "admin").map(nameOf); assert.equal(work.length, 38); - assert.equal(admin.length, 73); + assert.equal(admin.length, 76); for (const name of work) assert.ok(admin.includes(name), `${name} is in work but not admin`); assert.throws(() => tools(table, "root"), /unknown profile/); }); +test("the admin exception list is checked before the work families", () => { + // `branch` is a work family, but retiring one is administration (§10) + const retire = { family: "branch", call: "remove" }; + assert.equal(bucketOf(retire), "admin"); + assert.ok(!tools([...table, retire], "work").includes(retire)); + assert.ok(tools([...table, retire], "admin").includes(retire)); +}); + test("every generated tool is a valid MCP tool with the table's arguments and options", () => { const generated = toolsOf(table); assert.equal(generated.length, table.length); diff --git a/api/mcp/test/workflow.test.mjs b/api/mcp/test/workflow.test.mjs index 6c26d40b46..9b5f2f8b28 100644 --- a/api/mcp/test/workflow.test.mjs +++ b/api/mcp/test/workflow.test.mjs @@ -92,6 +92,11 @@ test("a real workflow, refusals, progress, scope and the two profiles", async () server.client.callTool({ name: "not_a_tool", arguments: {} }), (error) => error.code === -32602 && /unknown tool/.test(error.message), ); + // retired in 2.0 (spec 4): the old tool name does not exist + await assert.rejects( + server.client.callTool({ name: "project_remove", arguments: { project: "shop/api" } }), + (error) => error.code === -32602 && /unknown tool/.test(error.message), + ); await assert.rejects( server.client.callTool({ name: "store_create", arguments: { name: 5 } }), (error) => error.code === -32602 && /name.*must be text/.test(error.message), @@ -122,7 +127,7 @@ test("a real workflow, refusals, progress, scope and the two profiles", async () for (const name of names("admin").filter((name) => !names("work").includes(name))) { assert.ok(!workNames.has(name), `${name} is an admin tool in the work profile`); } - for (const prefix of ["store_", "machine_", "backup_", "project_init", "project_remove", "sandbox_create", "sandbox_close"]) { + for (const prefix of ["store_", "machine_", "backup_", "project_init", "project_delete", "project_remove_file", "branch_remove", "sandbox_create", "sandbox_close"]) { assert.ok(![...workNames].some((name) => name.startsWith(prefix)), `${prefix} in the work profile`); } const scopedRead = await call(work.client, "file_read", { project: "shop/api", branch: "feat", path: "/sub/b.txt" }); diff --git a/api/node/README.md b/api/node/README.md index 44af7efcda..6a9d49edc9 100644 --- a/api/node/README.md +++ b/api/node/README.md @@ -2,7 +2,7 @@ The LayerFS SDK for Node: ten families — `project`, `branch`, `commit`, `file`, `sandbox`, `workspace`, `machine`, `store`, `backup`, `logs` — over one call -table of 73 calls into one native library. Each function makes one call; it +table of 76 calls into one native library. Each function makes one call; it does not retry, replay or commit on its own. Results are plain objects with snake_case keys, whole numbers are exact (`bigint` beyond `Number.MAX_SAFE_INTEGER`), bytes are `Buffer`s, and the TypeScript typings diff --git a/api/node/test/branch-file/inventory.mjs b/api/node/test/branch-file/inventory.mjs index 39debc4c41..a16f8d05c3 100644 --- a/api/node/test/branch-file/inventory.mjs +++ b/api/node/test/branch-file/inventory.mjs @@ -11,8 +11,8 @@ const root = fileURLToPath(new URL("../../../../", import.meta.url)); const command = process.env.LAYERFS_CLI ?? join(root, "target/debug/layerfs"); const docs = join(root, "docs/architecture/api/sdk"); -test("the SDK pages name all 73 current calls, one `### family.call` heading each", () => { - assert.equal(table.length, 73); +test("the SDK pages name all 76 current calls, one `### family.call` heading each", () => { + assert.equal(table.length, 76); const families = [...new Set(table.map((spec) => spec.family))]; assert.equal(families.length, 10); const index = readFileSync(join(docs, "README.md"), "utf8"); diff --git a/api/node/test/calls.mjs b/api/node/test/calls.mjs index f417bcab15..5eb15f49a5 100644 --- a/api/node/test/calls.mjs +++ b/api/node/test/calls.mjs @@ -14,9 +14,9 @@ const temp = (tag) => { return dir; }; -test("the table: ten families, 73 calls, each a function", () => { +test("the table: ten families, 76 calls, each a function", () => { assert.deepEqual(families, ["project", "branch", "commit", "file", "sandbox", "workspace", "machine", "store", "backup", "logs"]); - assert.equal(table.length, 73); + assert.equal(table.length, 76); for (const spec of table) assert.equal(typeof layerfs[spec.family][spec.call], "function", `${spec.family}.${spec.call}`); }); diff --git a/api/python/test/test_calls.py b/api/python/test/test_calls.py index adeabfb50e..e8fc9793a3 100644 --- a/api/python/test/test_calls.py +++ b/api/python/test/test_calls.py @@ -340,7 +340,7 @@ def test_the_table(self): layerfs.FAMILIES, ["project", "branch", "commit", "file", "sandbox", "workspace", "machine", "store", "backup", "logs"], ) - self.assertEqual(len(layerfs.TABLE), 73) + self.assertEqual(len(layerfs.TABLE), 76) for spec in layerfs.TABLE: self.assertTrue(callable(getattr(getattr(layerfs, spec["family"]), spec["call"]))) with self.assertRaises(layerfs.LayerFSError) as caught: diff --git a/control/crates/layerfs-control/src/inventory.rs b/control/crates/layerfs-control/src/inventory.rs index d84ff2afdb..38256c129c 100644 --- a/control/crates/layerfs-control/src/inventory.rs +++ b/control/crates/layerfs-control/src/inventory.rs @@ -216,15 +216,3 @@ pub fn store_idle(home: &Path, store: &str) -> Result<()> { held.extend(related("sandbox", &sandboxes)); Err(in_use(why.join("; "), held)) } - -/// `project.remove`: refused `InUse` while a Sandbox of `project` is -/// recorded; `detail.related` lists them as `{kind: "sandbox", name}`. -pub fn can_remove_project(home: &Path, project: &str) -> Result<()> { - let sandboxes = sandboxes_of_project(home, project)?; - let message = match sandboxes.as_slice() { - [] => return Ok(()), - [sandbox] => format!("Sandbox {sandbox} of {project} is running"), - many => format!("Sandboxes {} of {project} are running", many.join(", ")), - }; - Err(in_use(message, related("sandbox", &sandboxes))) -} diff --git a/control/crates/layerfs-control/src/project.rs b/control/crates/layerfs-control/src/project.rs index baee69b1eb..af30e384f6 100644 --- a/control/crates/layerfs-control/src/project.rs +++ b/control/crates/layerfs-control/src/project.rs @@ -1,20 +1,13 @@ -//! The `project` call that checks who uses a project, `project.remove` -//! (layerfs-project#105); the other `project` calls are `layerfs-store`'s -//! own. +//! The `project` call that retires a project in its Store and removes the +//! caller's home entry (`project.delete`, spec §4); the other `project` +//! calls are `layerfs-store`'s own. use layerfs_home::events::Events; use layerfs_home::names::ProjectRef; use layerfs_home::outcome::Outcome; use std::path::Path; -/// `project.remove`: a project's history dropped from its Store, once its -/// Sandboxes are closed. -pub fn remove(home: &Path, events: &mut Events<'_>, project: &ProjectRef) -> Outcome { - layerfs_store::project::family::remove(home, events, project, crate::store::RELATED) -} - /// `project.delete(project)`: retires the project in its Store and removes -/// the caller home entry (spec §4). Add the API and MCP call-table entry in -/// T11; this is the service/control layer behind that dispatch. +/// the caller home entry (spec §4). pub fn delete(home: &Path, events: &mut Events<'_>, project: &ProjectRef) -> Outcome { layerfs_store::project::delete::delete(home, events, project) } diff --git a/control/crates/layerfs-control/src/store.rs b/control/crates/layerfs-control/src/store.rs index 8b7dc2334f..4dd9903e85 100644 --- a/control/crates/layerfs-control/src/store.rs +++ b/control/crates/layerfs-control/src/store.rs @@ -27,7 +27,6 @@ pub fn compact(home: &Path, events: &mut Events<'_>, name: &StoreName) -> Outcom /// Who uses a Store or a project, read from the Sandbox records. pub const RELATED: Related = Related { store_idle: inventory::store_idle, - can_remove_project: inventory::can_remove_project, }; /// `store.remove`: a sqlite Store no Sandbox uses, with its file. diff --git a/control/crates/layerfs-control/src/worker_server.rs b/control/crates/layerfs-control/src/worker_server.rs index 3e7d2cf8bd..b768955acb 100644 --- a/control/crates/layerfs-control/src/worker_server.rs +++ b/control/crates/layerfs-control/src/worker_server.rs @@ -10,8 +10,8 @@ //! build sends nothing more and closes. Then a request `{ op, args }`, read with at most //! [`REQUEST_WAIT`] between bytes. `worker.ping` answers who it is; //! `store.call`, `store.file`, `store.reach`, `sandbox.host`, `project.stage`, -//! `project.init`, `project.export`, `project.remove`, `project.delete` and -//! `project.list` run one operation on this machine, +//! `project.init`, `project.export`, `project.delete` and `project.list` run +//! one operation on this machine, //! with `home` set to the worker's own root (the machine's data disk), //! never a path the caller sends. Answers are //! `{ value }` or `{ refused }`, after any `{ event }` frames. @@ -33,10 +33,10 @@ use layerfs_store::project::discovery::home_of; use layerfs_store::project::export::in_worker as export_in_worker; use layerfs_store::project::frame::{ DeleteAdmitFrame, DeleteFrame, DeleteReleaseFrame, ExportFrame, InitFrame, ListingFrame, - RemoveFrame, StageFrame, + StageFrame, }; use layerfs_store::project::listing::list_projects; -use layerfs_store::project::{init::in_worker, remove::remove_project, staged}; +use layerfs_store::project::{init::in_worker, staged}; use std::net::{TcpListener, TcpStream}; use std::path::{Path, PathBuf}; use std::sync::atomic::{AtomicU64, Ordering}; @@ -273,12 +273,6 @@ fn run( }, layerfs_sandbox::workspace::dispatch::call, ), - // drops one project from the Store under this worker's root (2.0): - // `{ store, project, store_record }` - "project.remove" => { - let root = home_of(Some(root))?; - remove_project(&root, &RemoveFrame::decode(&args)?) - } // retires one project in the Store under this worker root and // removes the worker own entry (2.0, T4.5b): `{ store, stack_id, // deleted_ms?, project?, op_id?, store_record? }` diff --git a/control/crates/layerfs-control/tests/in_use_detail.rs b/control/crates/layerfs-control/tests/in_use_detail.rs index e83e63c43c..be250e38ae 100644 --- a/control/crates/layerfs-control/tests/in_use_detail.rs +++ b/control/crates/layerfs-control/tests/in_use_detail.rs @@ -1,9 +1,9 @@ -//! `InUse` from `project.remove` and `store.disconnect` fills -//! `detail.related` with `{kind, name}` entries (#536 §10b refusal detail): -//! the project's Sandboxes, and another process's lease on the Store. +//! `InUse` from `store.disconnect` fills `detail.related` with +//! `{kind, name}` entries (#536 §10b refusal detail): another process's +//! lease on the Store. use layerfs_bridge::control::{SdkRefusal, SdkValue}; use layerfs_home::events::Events; -use layerfs_home::home::{paths, private_dir, write_entity, write_record}; +use layerfs_home::home::{paths, private_dir, write_entity}; use std::path::PathBuf; fn t(s: &str) -> SdkValue { @@ -34,36 +34,6 @@ fn refused(run: impl FnOnce(&mut Events<'_>) -> layerfs_home::outcome::Outcome) run(&mut Events::new(&mut sink)).unwrap_err() } -#[test] -fn project_remove_names_the_project_s_sandboxes() { - let home = home("project"); - let store = SdkValue::map([ - ("name", t("shop")), - ("kind", t("sqlite")), - ("machine", t("native")), - ]); - write_entity(&paths::store_record(&home, "shop"), &store).unwrap(); - let project = SdkValue::map([("name", t("api"))]); - write_entity(&paths::project_record(&home, "shop", "api"), &project).unwrap(); - for name in ["sa", "sb"] { - let sandbox = SdkValue::map([ - ("v", SdkValue::Int(1)), - ("name", t(name)), - ("project", t("shop/api")), - ("machine", t("native")), - ]); - write_record(&paths::sandbox_record(&home, name), &sandbox).unwrap(); - } - let project = layerfs_home::names::ProjectRef::parse("shop/api").unwrap(); - let refusal = refused(|events| layerfs_control::project::remove(&home, events, &project)); - assert_eq!(refusal.code, "InUse", "{refusal:?}"); - let sandbox = |n: &str| ("sandbox".to_owned(), n.to_owned()); - assert_eq!(related(&refusal), [sandbox("sa"), sandbox("sb")]); - // nothing was removed - assert!(paths::project_record(&home, "shop", "api").is_file()); - let _ = std::fs::remove_dir_all(&home); -} - #[test] fn store_disconnect_names_another_process_s_lease() { let home = home("disconnect"); diff --git a/control/crates/layerfs-control/tests/inventory.rs b/control/crates/layerfs-control/tests/inventory.rs index d72f18ba2a..a2d8d91c4a 100644 --- a/control/crates/layerfs-control/tests/inventory.rs +++ b/control/crates/layerfs-control/tests/inventory.rs @@ -216,13 +216,6 @@ fn the_checks_refuse_in_use_with_the_same_texts() { }; assert_eq!(names(refusal.detail.get("related").unwrap()), ["a", "c"]); assert!(inventory::store_idle(&home, "pg").is_ok()); - let refusal = inventory::can_remove_project(&home, "docs/web").unwrap_err(); - assert_eq!(refusal.message, "Sandbox b of docs/web is running"); - assert_eq!(names(refusal.detail.get("related").unwrap()), ["b"]); - let refusal = inventory::can_remove_project(&home, "shop/api").unwrap_err(); - assert_eq!(refusal.message, "Sandboxes a, c of shop/api are running"); - assert_eq!(names(refusal.detail.get("related").unwrap()), ["a", "c"]); - assert!(inventory::can_remove_project(&home, "shop/web").is_ok()); let _ = std::fs::remove_dir_all(&home); } diff --git a/control/crates/layerfs-control/tests/project_delete_worker.rs b/control/crates/layerfs-control/tests/project_delete_worker.rs index c1ab487c20..1138ae2e63 100644 --- a/control/crates/layerfs-control/tests/project_delete_worker.rs +++ b/control/crates/layerfs-control/tests/project_delete_worker.rs @@ -153,7 +153,7 @@ fn the_worker_path_admits_before_the_sidecar_and_releases_after_the_marker() { store: StoreName::parse("shop").unwrap(), name: "app".to_owned(), source, - timeout_ms: None, + timeout_ms: Some(60_000), store_record: None, }) .unwrap(); diff --git a/control/crates/layerfs-control/tests/store_transfer_recovery.rs b/control/crates/layerfs-control/tests/store_transfer_recovery.rs index c122aa6b8e..0dea8ba5d7 100644 --- a/control/crates/layerfs-control/tests/store_transfer_recovery.rs +++ b/control/crates/layerfs-control/tests/store_transfer_recovery.rs @@ -41,7 +41,6 @@ fn idle(_home: &Path, _name: &str) -> Result<(), SdkRefusal> { fn related() -> Related { Related { store_idle: idle, - can_remove_project: idle, } } diff --git a/control/crates/layerfs-sandbox/src/daemon/channel.rs b/control/crates/layerfs-sandbox/src/daemon/channel.rs index 49c161ef81..4aad4a659e 100644 --- a/control/crates/layerfs-sandbox/src/daemon/channel.rs +++ b/control/crates/layerfs-sandbox/src/daemon/channel.rs @@ -291,6 +291,19 @@ fn matches_reply(request: &Request, reply: &Reply) -> bool { Reply::Bound { token, binding }, ) => token.workspace == *workspace && binding.branch.name.as_str() == branch, (Request::MountNamed { .. }, Reply::SdkRefused(_)) => true, + ( + Request::MountPlaced { + workspace, branch, .. + }, + Reply::Bound { token, binding }, + ) => token.workspace == *workspace && binding.branch.id == *branch, + ( + Request::MountNamedPlaced { + workspace, branch, .. + }, + Reply::Bound { token, binding }, + ) => token.workspace == *workspace && binding.branch.name.as_str() == branch, + (Request::MountNamedPlaced { .. }, Reply::SdkRefused(_)) => true, ( Request::Commit(_), Reply::Committed(_) | Reply::MergeCommitted(_) | Reply::Conflict(_), diff --git a/control/crates/layerfs-sandbox/src/daemon/internal.rs b/control/crates/layerfs-sandbox/src/daemon/internal.rs index 3188e6d448..58b6a0ace2 100644 --- a/control/crates/layerfs-sandbox/src/daemon/internal.rs +++ b/control/crates/layerfs-sandbox/src/daemon/internal.rs @@ -2,7 +2,7 @@ pub use super::channel::{Control, ControlCause, ControlFailure, ControlPhase}; use crate::{BoundWorkspace, OperationFailure, WorkspaceApi}; use layerfs_bridge::{ - control::{CleanupObservation, ReadyMount, WorkspaceStatus, WorkspaceToken}, + control::{CleanupObservation, MountPlace, ReadyMount, WorkspaceStatus, WorkspaceToken}, duplex::Connection, }; use layerfs_history::{BranchId, WorkspaceId}; @@ -16,6 +16,7 @@ pub fn workspace(control: &mut Control) -> InternalWorkspaceApi<'_> { InternalWorkspaceApi(WorkspaceApi { control, observation_scope: None, + place: MountPlace::default(), }) } /// Applies explicit observation scope only to this borrow's filesystem calls. @@ -26,6 +27,7 @@ pub fn with_observations<'a>( InternalWorkspaceApi(WorkspaceApi { control, observation_scope: Some(scope), + place: MountPlace::default(), }) } impl<'a> Deref for InternalWorkspaceApi<'a> { @@ -40,6 +42,13 @@ impl DerefMut for InternalWorkspaceApi<'_> { } } impl InternalWorkspaceApi<'_> { + /// Names the Sandbox and machine a mount through this channel belongs + /// to; a mount then registers them beside its Workspace. + #[must_use] + pub fn placed(mut self, sandbox: Option<&str>, machine: Option<&str>) -> Self { + self.0.place = MountPlace::new(sandbox, machine); + self + } /// Original logical bind for component proofs; kernel mount still uses both steps. pub fn bind( &mut self, diff --git a/control/crates/layerfs-sandbox/src/daemon/workspace/mount.rs b/control/crates/layerfs-sandbox/src/daemon/workspace/mount.rs index 038cf2245f..9c5e86e90f 100644 --- a/control/crates/layerfs-sandbox/src/daemon/workspace/mount.rs +++ b/control/crates/layerfs-sandbox/src/daemon/workspace/mount.rs @@ -1,6 +1,6 @@ //! Logical binding and kernel mount acknowledgements. use crate::{internal::Control, OperationFailure}; -use layerfs_bridge::control::{ReadyMount, Reply, Request, WorkspaceToken}; +use layerfs_bridge::control::{MountPlace, ReadyMount, Reply, Request, WorkspaceToken}; use layerfs_history::{BranchId, BranchSnapshot, WorkspaceId}; /// Explicit filesystem operations on one caller-owned sequential control channel. @@ -8,6 +8,10 @@ use layerfs_history::{BranchId, BranchSnapshot, WorkspaceId}; pub struct WorkspaceApi<'a> { pub control: &'a mut Control, pub observation_scope: Option<&'a [u8; 32]>, + /// The Sandbox and machine a mount through this channel belongs to, + /// when its caller knows them: the daemon registers the holder with + /// them. Both absent when the caller knows neither. + pub place: MountPlace, } impl<'a> WorkspaceApi<'a> { /// Borrows this Sandbox's original authenticated filesystem control owner. @@ -21,8 +25,16 @@ impl<'a> WorkspaceApi<'a> { Self { control, observation_scope: None, + place: MountPlace::default(), } } + /// Names the Sandbox and machine a mount through this channel belongs + /// to; a mount then registers them beside its Workspace. + #[must_use] + pub fn placed(mut self, sandbox: Option<&str>, machine: Option<&str>) -> Self { + self.place = MountPlace::new(sandbox, machine); + self + } pub fn exchange(&mut self, request: Request) -> Result> { let request = match self.observation_scope { Some(scope) => Request::Observed { diff --git a/control/crates/layerfs-sandbox/src/daemon/workspace/recovery.rs b/control/crates/layerfs-sandbox/src/daemon/workspace/recovery.rs index 1c6836649b..25ab47ebce 100644 --- a/control/crates/layerfs-sandbox/src/daemon/workspace/recovery.rs +++ b/control/crates/layerfs-sandbox/src/daemon/workspace/recovery.rs @@ -12,7 +12,15 @@ impl WorkspaceApi<'_> { workspace: WorkspaceId, branch: BranchId, ) -> Result> { - let request = Request::Mount { workspace, branch }; + let request = if self.place.known() { + Request::MountPlaced { + workspace, + branch, + place: self.place.clone(), + } + } else { + Request::Mount { workspace, branch } + }; match self.exchange(request.clone())? { Reply::Bound { token, binding } => Ok(BoundWorkspace { token, binding }), reply => Err(OperationFailure::unexpected(request, reply)), @@ -27,10 +35,19 @@ impl WorkspaceApi<'_> { project: &str, branch: &str, ) -> Result> { - let request = Request::MountNamed { - workspace, - project: project.to_owned(), - branch: branch.to_owned(), + let request = if self.place.known() { + Request::MountNamedPlaced { + workspace, + project: project.to_owned(), + branch: branch.to_owned(), + place: self.place.clone(), + } + } else { + Request::MountNamed { + workspace, + project: project.to_owned(), + branch: branch.to_owned(), + } }; match self.exchange(request.clone())? { Reply::Bound { token, binding } => Ok(BoundWorkspace { token, binding }), diff --git a/control/crates/layerfs-sandbox/src/registry.rs b/control/crates/layerfs-sandbox/src/registry.rs index 6864944940..91d407a8d7 100644 --- a/control/crates/layerfs-sandbox/src/registry.rs +++ b/control/crates/layerfs-sandbox/src/registry.rs @@ -1,6 +1,6 @@ //! What this process owns: its running Inits and its live Sandboxes. A -//! project itself is only its home entry, so a project removed there can be -//! initialized again without a restart. +//! project itself is only its home entry, so a project deleted there can be +//! initialized again (under another name, until a compaction frees the name). //! //! A Sandbox is one daemon process (`runtime`: native, or namespaces with //! its init stage), known by its name. Its runtime runs diff --git a/control/crates/layerfs-sandbox/src/workspace/serve.rs b/control/crates/layerfs-sandbox/src/workspace/serve.rs index 457cfb1356..c878cde8c0 100644 --- a/control/crates/layerfs-sandbox/src/workspace/serve.rs +++ b/control/crates/layerfs-sandbox/src/workspace/serve.rs @@ -13,11 +13,11 @@ use crate::daemon::values; use crate::host::Host; use crate::internal::workspace; use crate::lifecycle::{operation, WORKSPACES}; -use crate::record::{DaemonRecord, WorkspaceRecord}; +use crate::record::{DaemonRecord, SandboxRecord, WorkspaceRecord}; use crate::registry::{sandbox, sandbox_live, Mount}; use crate::OperationCause; use crate::Unmounted; -use layerfs_bridge::control::{CommitControl, Reply, SdkRefusal, SdkValue}; +use layerfs_bridge::control::{CommitControl, MountPlace, Reply, SdkRefusal, SdkValue}; use layerfs_history::{BranchId, CommitId, WorkspaceId}; use layerfs_home::helpers::{lock, random, required}; use layerfs_home::names::WorkspaceName; @@ -102,7 +102,14 @@ pub fn mount(host: &Host, branch: Option<&str>, name: Option<&str>) -> Outcome { let id = WorkspaceId::from_authority(random()?).map_err(failed)?; let mounted = { let mut control = crate::daemon::trace::control(&state.controls)?; - workspace(&mut control).mount_named(id, (project, branch)) + // This Sandbox's record names the machine it runs on; the daemon + // that binds the mount registers both names beside its Workspace. + let machine = + SandboxRecord::read_in(&directory, sandbox)?.map(|record| record.machine().to_owned()); + let place = MountPlace::new(Some(state.id.as_str()), machine.as_deref()); + workspace(&mut control) + .placed(place.sandbox.as_deref(), place.machine.as_deref()) + .mount_named(id, (project, branch)) }; let mounted = mounted.map_err(|failure| match (&failure.bound, &failure.failure.cause) { // the daemon's lookup refusal, nothing bound: the call's answer diff --git a/control/crates/layerfs-store/src/compact.rs b/control/crates/layerfs-store/src/compact.rs index dab93bac77..3a7514b54f 100644 --- a/control/crates/layerfs-store/src/compact.rs +++ b/control/crates/layerfs-store/src/compact.rs @@ -15,17 +15,17 @@ use crate::open_args::OpenArgs; use crate::place::{self, Executor}; #[cfg(feature = "postgresql")] use crate::postgresql; -use crate::record::{self, StoreRecord, StoreRef}; +use crate::record::{StoreRecord, StoreRef}; use layerfs_bridge::control::SdkRefusal; use layerfs_home::events::Events; use layerfs_home::home::paths; use layerfs_home::outcome::{failed, refused, Outcome}; -#[cfg(feature = "postgresql")] -use layerfs_persistence::PostgresHandles; +use layerfs_persistence::compact_metrics::{self, CompactRefusal}; use layerfs_persistence::{ - CompactReport, CompactRequest, PersistenceConfig, SqliteHandles, - SqlitePersistenceProfile, + CompactReport, CompactRequest, PersistenceConfig, SqliteHandles, SqlitePersistenceProfile, }; +#[cfg(feature = "postgresql")] +use layerfs_persistence::PostgresHandles; use layerfs_store_service::history::{admission, lookup}; use std::path::Path; @@ -33,7 +33,15 @@ use std::path::Path; /// the §11 report. pub fn compact(home: &Path, _events: &mut Events<'_>, store: &str) -> Outcome { let home = home.to_path_buf(); - let (_lease, record) = lease::claim(&home, store)?; + // A live operation is `Busy`, a dead owner's record `Unresolved`; the + // refusal is a bounded metric label and never changes what is returned. + let (_lease, record) = match lease::claim(&home, store) { + Ok(claimed) => claimed, + Err(refusal) => { + note_refusal(&refusal); + return Err(refusal); + } + }; let store_ref = record.store_ref()?.clone(); if matches!(store_ref, StoreRef::Postgres { .. }) { return compact_postgresql(&record, &home, store); @@ -85,7 +93,7 @@ pub fn compact(home: &Path, _events: &mut Events<'_>, store: &str) -> Outcome { } /// `store.compact` of a PostgreSQL Store in a build without the `postgresql` -/// feature is `Unsupported`. +/// feature: no engine is linked, so the call is `Unsupported`. #[cfg(not(feature = "postgresql"))] fn compact_postgresql(_record: &StoreRecord, _home: &Path, _store: &str) -> Outcome { Err(refused( @@ -97,9 +105,12 @@ fn compact_postgresql(_record: &StoreRecord, _home: &Path, _store: &str) -> Outc /// The §8 PostgreSQL path: dial the Store's recorded URL, open its schema as /// this home's authority, and run Phase M/A/B/C. The Store is usable at /// G + 1 from the swap on; a lost reply is judged by the next call (§9). +/// +/// Only built with the `postgresql` feature; the stub above answers +/// `Unsupported` without it. #[cfg(feature = "postgresql")] fn compact_postgresql(record: &StoreRecord, home: &Path, store: &str) -> Outcome { - let url = record::url(record)?; + let url = crate::record::url(record)?; let id = identity::identity(&OpenArgs { home: Some(home.to_path_buf()), store: Some(store.to_owned()), @@ -139,12 +150,24 @@ fn compact_postgresql(record: &StoreRecord, home: &Path, store: &str) -> Outcome /// failure with its own text. fn open_refusal(error: layerfs_storage::port::PersistenceError) -> SdkRefusal { use layerfs_storage::port::PersistenceError; - match error { + let refusal = match error { PersistenceError::Busy => refused("Busy", "the Store is held by another writer"), PersistenceError::Refused { status } => refused( "Busy", format!("the Store refused the compaction: {status}"), ), other => failed(other), + }; + note_refusal(&refusal); + refusal +} + +/// Counts a Busy/Unresolved refusal of a call that never reached a run; the +/// measured SQLite run records the refusals it produces itself. +fn note_refusal(refusal: &SdkRefusal) { + match refusal.code.as_str() { + "Busy" => compact_metrics::record_refusal(CompactRefusal::Busy), + "Unresolved" => compact_metrics::record_refusal(CompactRefusal::Unresolved), + _ => {} } } diff --git a/control/crates/layerfs-store/src/project/add.rs b/control/crates/layerfs-store/src/project/add.rs index af7e24516f..5e4236eaf0 100644 --- a/control/crates/layerfs-store/src/project/add.rs +++ b/control/crates/layerfs-store/src/project/add.rs @@ -7,6 +7,7 @@ use crate::project::discovery::Project; use layerfs_bridge::control::{SdkRefusal, SdkValue}; use layerfs_bridge::provision::{ProviderKind, StoreManifest, StoreProfile}; use layerfs_bridge::sdk_values::hex; +use layerfs_history::error::{HolderKind, HolderState, NameHolder, NameSource, NameTakenState}; use layerfs_history::{BranchId, HistoryName, LayerStackId}; use layerfs_home::helpers::random; use layerfs_home::home::paths; @@ -14,6 +15,7 @@ use layerfs_home::names::StoreName; use layerfs_home::outcome::{failed, refused, Outcome}; use layerfs_persistence::{PersistenceConfig, SealedStore, SqlitePersistenceProfile}; use layerfs_project::store::{AddRequest, InitError, ProjectApi}; +use layerfs_store_service::history::lookup; use layerfs_project::{InitCounters, ProjectError}; use std::path::{Path, PathBuf}; use std::sync::Arc; @@ -75,7 +77,7 @@ pub fn make_entry(home: &Path, store: &str, name: &str) -> Result { let entry = layerfs_home::home::paths::project_dir(home, store, name); std::fs::create_dir(&entry).map_err(|error| { if error.kind() == std::io::ErrorKind::AlreadyExists { - refused("Exists", format!("project {name} exists in Store {store}")) + home_name_taken(store, name) } else { failed(error) } @@ -85,6 +87,20 @@ pub fn make_entry(home: &Path, store: &str, name: &str) -> Result { Ok(entry) } +/// A project name the caller's home already records: `NameTaken` with its +/// `home` source, decided before the Store is asked anything. +pub(crate) fn home_name_taken(store: &str, name: &str) -> SdkRefusal { + let state = NameTakenState::new( + NameHolder::new(HolderKind::Project, name, HolderState::Live), + NameSource::Home, + ); + lookup::refuse( + "NameTaken", + format!("project {name} exists in Store {store}"), + lookup::name_taken_detail(&state), + ) +} + /// `project.init`'s add of folder `source` as the new project `name` of /// Store `store` in `home` (the caller's, or a worker's root), whose file is /// `/store//store.sqlite`. @@ -143,10 +159,7 @@ pub fn add_project(request: &ProjectAdd) -> Outcome { } let home = discovery::home_of(Some(&request.home))?; if name == store && legacy(&home, store)? { - return Err(refused( - "Exists", - format!("Store {store} already has a project named {name}"), - )); + return Err(home_name_taken(store, name)); } let entry = make_entry(&home, store, name)?; let _guard = discovery::guard(&entry)?; @@ -213,9 +226,10 @@ pub fn add_project(request: &ProjectAdd) -> Outcome { /// diagnosis. pub fn add_failure(error: InitError, entry: Option<&Path>, name: &str, store: &str) -> SdkRefusal { let refusal = match &error { - InitError::Exists => refused( - "Exists", + InitError::NameTaken(state) => lookup::refuse( + "NameTaken", format!("Store {store} already has a project named {name}"), + lookup::name_taken_detail(state), ), InitError::NoAcquisition => refused( "Unsupported", diff --git a/control/crates/layerfs-store/src/project/delete.rs b/control/crates/layerfs-store/src/project/delete.rs index 12fb89b68b..b780d22e9b 100644 --- a/control/crates/layerfs-store/src/project/delete.rs +++ b/control/crates/layerfs-store/src/project/delete.rs @@ -18,7 +18,7 @@ //! //! The worker op is `project.delete`; its frame is //! `{store, stack_id, deleted_ms?, project?, op_id?, store_record?}`. The two -//! optional context fields are the same ones `project.remove` sends: the +//! optional context fields are the ones the retired `project.remove` call sent: the //! worker opens the Store under its own root with the caller's `store_record`, //! and the project name lets its reply and its own home entry name the //! project. The worker saves the legacy own-project identity, writes the diff --git a/control/crates/layerfs-store/src/project/family.rs b/control/crates/layerfs-store/src/project/family.rs index af8d81619d..6b1cf8985b 100644 --- a/control/crates/layerfs-store/src/project/family.rs +++ b/control/crates/layerfs-store/src/project/family.rs @@ -5,22 +5,19 @@ //! `native` or a PostgreSQL Store, in the machine's worker for a sqlite //! Store on any other machine (#536 H11). The folder is always on the //! caller's host: for a worker this process copies it to the machine -//! first (H11a). Records in the home list projects; `remove` drops one -//! project's history from its Store. +//! first (H11a). Records in the home list projects. use crate::calls::Page; use crate::lease; use crate::open_args::OpenArgs; use crate::place::{self, Executor, Worker}; use crate::project::add::{add_project, ProjectAdd}; -use crate::project::discovery::home_of; -use crate::project::frame::{InitFrame, ListingFrame, ListingReply, RemoveFrame}; +use crate::project::frame::{InitFrame, ListingFrame, ListingReply}; use crate::project::postgres_init::PgProjectAdd; use crate::project::record::ProjectRecord; use crate::record::{StoreRecord, StoreRef}; use crate::resolve; use crate::service; use crate::sqlite::family::progress; -use crate::Related; use layerfs_bridge::control::{SdkRefusal, SdkValue}; use layerfs_home::events::Events; use layerfs_home::home::paths; @@ -331,10 +328,7 @@ fn init_on_worker( timeout, } = call; if paths::project_record(&home, store, name).exists() { - return Err(refused( - "Exists", - format!("Store {store} already has a project named {name}"), - )); + return Err(crate::project::add::home_name_taken(store.as_str(), name)); } let total = send::measure(Path::new(folder), name)?; let copy = send::Copy { @@ -399,10 +393,7 @@ fn init_postgresql( let home = home.to_path_buf(); let path = paths::project_record(&home, store, name); if path.exists() { - return Err(refused( - "Exists", - format!("Store {store} already has a project named {name}"), - )); + return Err(crate::project::add::home_name_taken(store.as_str(), name)); } let add = PgProjectAdd { add: ProjectAdd { @@ -426,49 +417,3 @@ fn init_postgresql( } Ok(out) } - -/// `project.remove(project)`: drops the project's Layers, Branches and -/// Commits from its Store in one write, then its record. Its Sandboxes must -/// be closed first; the other projects stay. -pub fn remove( - home: &Path, - events: &mut Events<'_>, - project: &ProjectRef, - related: Related, -) -> Outcome { - let text = project.to_string(); - let home = home.to_path_buf(); - let target = resolve::target(&home, &text)?; - target.record.unblocked()?; - (related.can_remove_project)(&home, &text)?; - let request = RemoveFrame { - store: project.store.clone(), - project: target.project.clone(), - store_record: Some(target.record.to_record().clone()), - }; - if let StoreRef::Postgres { .. } = target.store_ref { - return Err(refused( - "Unsupported", - "removing a project from a PostgreSQL Store is not built", - )); - } - let removed = match place::plan(&home, &target.store_ref)? { - Executor::Local => { - let _lease = lease::hold(&home, &target.store)?; - crate::project::remove::remove_project(&home_of(Some(&home))?, &request)? - } - Executor::Worker(mut worker) => { - let _lease = lease::hold(&home, &target.store)?; - worker.call("project.remove", request.encode(), &mut |e| events.event(e))? - } - }; - let entry = paths::project_dir(&home, &target.store, &target.project); - if entry.exists() { - std::fs::remove_dir_all(&entry).map_err(failed)?; - } - Ok(layerfs_home::home::with_field( - removed, - "project", - SdkValue::text(text), - )) -} diff --git a/control/crates/layerfs-store/src/project/frame.rs b/control/crates/layerfs-store/src/project/frame.rs index 808fbd46e4..bcdfa67405 100644 --- a/control/crates/layerfs-store/src/project/frame.rs +++ b/control/crates/layerfs-store/src/project/frame.rs @@ -1,5 +1,5 @@ //! The `project` worker frames (layerfs-project#109): `project.init`, -//! `project.remove`, `project.list` (T4.5c), `project.stage`, +//! `project.list` (T4.5c), `project.stage`, //! `project.export`, `project.delete` (T4.5b) and its admission ops, each //! encoded by the caller and //! decoded once in the worker, in the order the worker always refused them. @@ -30,18 +30,6 @@ pub struct InitFrame { pub store_record: Option, } -/// `project.remove`: drop project `project` from Store `store` (here, or in -/// its worker). -#[derive(Clone, Debug)] -pub struct RemoveFrame { - /// The Store. - pub store: StoreName, - /// The project's name in it. - pub project: String, - /// The Store's record. - pub store_record: Option, -} - /// `project.export` in a worker: stream Branch `branch` of project /// `project` of Store `store` back to the caller. #[derive(Clone, Debug)] @@ -146,30 +134,6 @@ impl InitFrame { } } -impl RemoveFrame { - /// The `project.remove` frame: `{ store, project, store_record }`. - pub fn encode(&self) -> SdkValue { - let mut fields = vec![ - ("store", SdkValue::text(self.store.as_str())), - ("project", SdkValue::text(&self.project)), - ]; - fields.extend(self.store_record.clone().map(|r| ("store_record", r))); - map(fields) - } - - /// A `project.remove` frame: no Store, no project, then a bad Store - /// name are refused. - pub fn decode(frame: &SdkValue) -> Result { - let store = required(frame.get_text("store"), "store")?; - let project = required(frame.get_text("project"), "project")?.to_owned(); - Ok(Self { - store: StoreName::parse(store)?, - project, - store_record: frame.get("store_record").cloned(), - }) - } -} - impl StageFrame { /// The `project.stage` frame: `{ store, name, staged, step, part? }`. pub fn encode(self) -> SdkValue { diff --git a/control/crates/layerfs-store/src/project/mod.rs b/control/crates/layerfs-store/src/project/mod.rs index 65597449ed..1b35d9d8ca 100644 --- a/control/crates/layerfs-store/src/project/mod.rs +++ b/control/crates/layerfs-store/src/project/mod.rs @@ -13,7 +13,6 @@ pub mod parts; pub mod postgres_init; #[doc(hidden)] pub mod record; -pub mod remove; pub mod send; pub mod staged; pub mod tree; diff --git a/control/crates/layerfs-store/src/project/remove.rs b/control/crates/layerfs-store/src/project/remove.rs deleted file mode 100644 index 4e5200e347..0000000000 --- a/control/crates/layerfs-store/src/project/remove.rs +++ /dev/null @@ -1,68 +0,0 @@ -//! A project removed from its Store (`project.remove`, here or in the -//! Store's worker). -use crate::identity::{identity, legacy, save_record, store_dir}; -use crate::open_args::OpenArgs; -use crate::project::frame::RemoveFrame; -use layerfs_bridge::control::SdkValue; -use layerfs_bridge::sdk_values::hex; -use layerfs_home::home::paths; -use layerfs_home::outcome::{failed, refused, Outcome}; -use std::path::Path; - -/// `project.remove`'s work on the Store's machine (here, or in its worker -/// as the worker op `project.remove`), in `home` (the caller's, or the -/// worker's root; checked by the caller with [`home_of`](super::discovery::home_of)): -/// drops the project's stack (its Layers, Branches and Commits) from the -/// Store in one write, then its entry from the home. The other projects -/// stay. The entry of the project a Store was made by (its own Init) holds -/// the Store's identity, so a Store record is saved before that entry goes. -/// Its packs and objects stay in the Store; reclaiming them is A8 (#411). -/// The caller stops the project's Sandboxes and clients first. -pub fn remove_project(home: &Path, request: &RemoveFrame) -> Outcome { - let (store, name) = (request.store.as_str(), request.project.as_str()); - let open = OpenArgs { - home: Some(home.to_path_buf()), - store: Some(store.to_owned()), - project: Some(name.to_owned()), - store_path: Some(paths::store_file(home, store).display().to_string()), - store_record: request.store_record.clone(), - postgresql: None, - }; - let identity = identity(&open)?; - let own = name == store && legacy(home, store)?; - let entry = layerfs_home::home::paths::project_dir(home, store, name); - let stack = crate::service::with_service(&open, |service| { - let stacks = service - .store - .published(layerfs_project::store::projects) - .map_err(failed)?; - let Some(stack) = stacks.into_iter().find(|stack| stack.name.as_str() == name) else { - return Err(refused( - "NoSuchProject", - format!("Store {store} holds no project named {name}"), - )); - }; - service - .store - .history() - .remove_layerstack(stack.id) - .map_err(|error| { - failed(format!( - "removing project {name} from Store {store}: {error:?}" - )) - })?; - Ok(stack.id) - })?; - // the own project's entry carried the Store's identity until now - if own { - layerfs_home::home::private_dir(&store_dir(home, store)?)?; - save_record(home, store, &identity)?; - } - if entry.exists() { - std::fs::remove_dir_all(&entry).map_err(failed)?; - } - Ok(SdkValue::map([ - ("stack", SdkValue::text(hex(&stack.to_bytes()))), - ("packsKept", SdkValue::Bool(true)), - ])) -} diff --git a/control/crates/layerfs-store/src/related.rs b/control/crates/layerfs-store/src/related.rs index 56b471049a..06e2bc9fcb 100644 --- a/control/crates/layerfs-store/src/related.rs +++ b/control/crates/layerfs-store/src/related.rs @@ -8,13 +8,11 @@ use std::path::Path; /// An `InUse` check on the Store or project `name` in home `home`. type Check = fn(home: &Path, name: &str) -> Result<(), SdkRefusal>; -/// The `InUse` checks over a Store's and a project's users. +/// The `InUse` checks over a Store's users. #[derive(Clone, Copy)] pub struct Related { /// `store.push`, `store.pull`, `store.remove`, `store.disconnect` and /// `backup.restore`: refused while another live process holds the Store /// or a Sandbox of one of its projects is recorded. pub store_idle: Check, - /// `project.remove`: refused while a Sandbox of the project is recorded. - pub can_remove_project: Check, } diff --git a/control/crates/layerfs-store/src/status.rs b/control/crates/layerfs-store/src/status.rs index 5656f73eb7..72e277bc7b 100644 --- a/control/crates/layerfs-store/src/status.rs +++ b/control/crates/layerfs-store/src/status.rs @@ -6,6 +6,7 @@ use crate::sqlite::family::{fields_map, record_of, step_on}; use crate::sqlite::transfer::step::StoreStep; use layerfs_bridge::control::SdkValue; use layerfs_home::outcome::Outcome; +use layerfs_persistence::compact_metrics::{self, CompactStatusState}; use std::path::Path; /// `store.status`: who holds it, the operation on it (`op`, as H6 shows it), @@ -67,6 +68,15 @@ pub fn status(home: &Path, name: &str) -> Outcome { let state = compaction .get_text("state") .unwrap_or_else(|| record.state(down.is_some(), &holders).as_str()); + // The status path observes an unsettled run by its bounded state label, + // never by a Store name or phase path. + if compaction.get("id").is_some() { + match state { + "busy" => compact_metrics::record_status(CompactStatusState::Busy), + "unresolved" => compact_metrics::record_status(CompactStatusState::Unresolved), + _ => {} + } + } let mut fields = vec![ ("name", SdkValue::text(name)), ("kind", SdkValue::text(store_ref.kind().as_str())), diff --git a/control/crates/layerfs-store/tests/compact_report_status.rs b/control/crates/layerfs-store/tests/compact_report_status.rs index 88aa9e03da..56a7a28068 100644 --- a/control/crates/layerfs-store/tests/compact_report_status.rs +++ b/control/crates/layerfs-store/tests/compact_report_status.rs @@ -159,6 +159,32 @@ fn the_report_wire_is_the_snake_case_contract_shape() { assert!(wire.get("zeroReason").is_none(), "no camelCase key"); } +#[test] +fn status_emits_bounded_busy_and_unresolved_metrics() { + let home = store_home(); + let name = StoreName::parse("s").unwrap(); + let capture = layerfs_persistence::compact_metrics::CompactMetricsCapture::start(); + // Idle: no compaction record, so no `compact.status` sample. + let _ = layerfs_store::sqlite::family::status(&home, &name).unwrap(); + // A live owner is `busy`; a gone one is `unresolved`. + sidecar(&home, "build", std::process::id()); + let _ = layerfs_store::sqlite::family::status(&home, &name).unwrap(); + sidecar(&home, "build", 99_999_999); + let _ = layerfs_store::sqlite::family::status(&home, &name).unwrap(); + let metrics = capture.finish(); + let value = |state: &str| { + metrics + .samples() + .iter() + .find(|sample| sample.name == "compact.status" && sample.label("state") == Some(state)) + .map_or(0, |sample| sample.value) + }; + assert_eq!(value("busy"), 1); + assert_eq!(value("unresolved"), 1); + assert_eq!(value("idle"), 0, "an idle status is not a compaction op"); + std::fs::remove_dir_all(home).unwrap(); +} + #[test] fn status_projects_the_sidecar_phase_and_state() { let home = store_home(); diff --git a/control/crates/layerfs-store/tests/project_delete_store.rs b/control/crates/layerfs-store/tests/project_delete_store.rs index 1d0e945a70..fec3091bbb 100644 --- a/control/crates/layerfs-store/tests/project_delete_store.rs +++ b/control/crates/layerfs-store/tests/project_delete_store.rs @@ -72,7 +72,7 @@ fn shop(tag: &str) -> Option<(PathBuf, OpenArgs, LayerStackId)> { store: StoreName::parse("shop").unwrap(), name: "app".to_owned(), source, - timeout_ms: None, + timeout_ms: Some(60_000), store_record: None, }) .unwrap(); diff --git a/control/crates/layerfs-store/tests/project_frames.rs b/control/crates/layerfs-store/tests/project_frames.rs index e200d7f041..2afe04cff9 100644 --- a/control/crates/layerfs-store/tests/project_frames.rs +++ b/control/crates/layerfs-store/tests/project_frames.rs @@ -3,7 +3,7 @@ //! refuses in the order it always did. use layerfs_bridge::control::SdkValue; use layerfs_home::names::StoreName; -use layerfs_store::project::frame::{InitFrame, RemoveFrame, StageFrame, StageStep}; +use layerfs_store::project::frame::{InitFrame, StageFrame, StageStep}; fn t(text: &str) -> SdkValue { SdkValue::text(text) @@ -45,26 +45,6 @@ fn each_frame_encodes_the_map_its_caller_built() { assert_eq!((decoded.name, decoded.timeout_ms), (init.name, Some(5))); assert_eq!(decoded.store_record, init.store_record); - let remove = RemoveFrame { - store: store(), - project: "web".to_owned(), - store_record: Some(record.clone()), - }; - let encoded = remove.encode(); - assert_eq!( - encoded, - map(vec![ - ("store", t("shop")), - ("project", t("web")), - ("store_record", record), - ]) - ); - let decoded = RemoveFrame::decode(&encoded).unwrap(); - assert_eq!( - (decoded.store, decoded.project), - (store(), "web".to_owned()) - ); - let stage = |step| StageFrame { store: "shop".to_owned(), name: "web".to_owned(), @@ -98,15 +78,6 @@ fn the_worker_refuses_a_frame_in_its_old_order() { let bare = InitFrame::decode(&map(vec![("store", t("shop")), ("staged", t(ID))])).unwrap(); assert_eq!((bare.name, bare.timeout_ms), (None, None)); - let remove = |fields| RemoveFrame::decode(&map(fields)).unwrap_err().message; - assert_eq!(remove(vec![]), "missing text argument `store`"); - // no project before a bad Store name - assert_eq!( - remove(vec![("store", t("../x"))]), - "missing text argument `project`" - ); - assert!(remove(vec![("store", t("../x")), ("project", t("web"))]).starts_with("store name")); - let stage = |fields| StageFrame::decode(map(fields)).unwrap_err().message; // a bad id before an unknown step assert_eq!( diff --git a/control/crates/layerfs-store/tests/restore_install.rs b/control/crates/layerfs-store/tests/restore_install.rs index 2364f2e8c3..688d62cd02 100644 --- a/control/crates/layerfs-store/tests/restore_install.rs +++ b/control/crates/layerfs-store/tests/restore_install.rs @@ -45,7 +45,6 @@ fn unused(home: &Path, name: &str) -> Result<(), SdkRefusal> { fn related() -> Related { Related { store_idle: unused, - can_remove_project: unused, } } diff --git a/core/crates/layerfs-history/src/contract/catalog.rs b/core/crates/layerfs-history/src/contract/catalog.rs index b543464d0f..da2364410c 100644 --- a/core/crates/layerfs-history/src/contract/catalog.rs +++ b/core/crates/layerfs-history/src/contract/catalog.rs @@ -92,6 +92,17 @@ pub trait HistoryCatalog: Send + Sync { /// Stacks in name order. fn layer_stacks(&self, page: &Page) -> HistoryResult>; + /// The typed `NameTaken` state for a LayerStack (project) name, live or + /// deleted, read without resolving the Stack (spec 4.4). The default + /// reports none; a provider that keeps the collision query overrides it, + /// so `project.init` refuses a held name before it scans anything. + fn layer_stack_name_taken( + &self, + _name: &HistoryName, + ) -> HistoryResult> { + Ok(None) + } + /// The stack named `name`, if any. A provider answers through its name /// index; this default pages through the stacks in name order. fn layer_stack_named(&self, name: &HistoryName) -> HistoryResult> { @@ -114,6 +125,15 @@ pub trait HistoryCatalog: Send + Sync { /// One Branch by identity. fn branch(&self, id: BranchId) -> HistoryResult>; + /// One Branch by identity without the visibility filter (spec 4.2). Only + /// rendering and identity keep a retired Branch's name this way; every + /// caller-facing lookup resolves through [`HistoryCatalog::branch`]. A + /// provider that keeps retired rows overrides this; the default reads the + /// filtered row. + fn branch_any(&self, id: BranchId) -> HistoryResult> { + self.branch(id) + } + /// One Branch by its name in a stack, through the name index: the /// stack's other Branches are not read. fn branch_named( diff --git a/core/crates/layerfs-storage/src/encoding/delta/select.rs b/core/crates/layerfs-storage/src/encoding/delta/select.rs index c293559691..65cadeb583 100644 --- a/core/crates/layerfs-storage/src/encoding/delta/select.rs +++ b/core/crates/layerfs-storage/src/encoding/delta/select.rs @@ -60,6 +60,9 @@ pub struct DeltaCounters { pub absent_candidates: u64, /// Candidates present but ineligible under the depth or role policy. pub ineligible_candidates: u64, + /// Candidates whose stored chain names the object being stored: a + /// concurrent writer's copy depends on it. Stored FULL by policy. + pub cyclic_candidates: u64, /// Candidates refused because the resulting chain would exceed its budget. pub work_exceeded: u64, /// Candidates whose chain already reached the role's depth cap. Their chain @@ -101,6 +104,7 @@ impl DeltaCounters { (&mut self.no_candidate, other.no_candidate), (&mut self.absent_candidates, other.absent_candidates), (&mut self.ineligible_candidates, other.ineligible_candidates), + (&mut self.cyclic_candidates, other.cyclic_candidates), (&mut self.work_exceeded, other.work_exceeded), (&mut self.depth_capped, other.depth_capped), (&mut self.rebased, other.rebased), @@ -154,6 +158,18 @@ pub struct ChainCost { pub encoded: u64, } +/// How a walk of one stored dependency chain ended. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum ChainWalk { + /// The object is stored and its chain costs this. + Cost(ChainCost), + /// The object, or a base it names, is not stored. + Absent, + /// The chain names the object the caller is storing: that object cannot be + /// its base without closing a dependency cycle. + Cycle, +} + /// Bounded per-save cache of dependency depths and chain costs. #[derive(Debug, Default)] pub struct DepthCache { @@ -205,8 +221,59 @@ impl DepthCache { connection: &dyn Source, workspace: &mut DecompressionWorkspace, id: ObjectId, - mut base_of: F, + base_of: F, ) -> StorageResult> + where + F: FnMut( + &dyn Source, + &mut DecompressionWorkspace, + &ObjectLocation, + ) -> StorageResult, + { + match self.walk(connection, workspace, id, None, base_of)? { + ChainWalk::Cost(cost) => Ok(Some(cost)), + ChainWalk::Absent => Ok(None), + // Without an object to avoid, a walk that names its own start is a + // cycle already stored. + ChainWalk::Cycle => Err(StorageError::Integrity("dependency cycle")), + } + } + + /// `id`'s chain cost, or [`ChainWalk::Cycle`] when the chain names `avoid` + /// (the object the caller is about to store against it). + /// + /// Two writers can store the same new object at once. One writer's copy can + /// name the other writer's object as its base, so the candidate a selection + /// is about to use can name the object that selection is storing. Storing + /// that candidate as the new object's base would close a dependency cycle, + /// so the caller stores the object whole instead. + pub fn cost_avoiding( + &mut self, + connection: &dyn Source, + workspace: &mut DecompressionWorkspace, + id: ObjectId, + avoid: ObjectId, + base_of: F, + ) -> StorageResult + where + F: FnMut( + &dyn Source, + &mut DecompressionWorkspace, + &ObjectLocation, + ) -> StorageResult, + { + self.walk(connection, workspace, id, Some(avoid), base_of) + } + + /// One iterative, bounded walk from `id` to the root of its stored chain. + fn walk( + &mut self, + connection: &dyn Source, + workspace: &mut DecompressionWorkspace, + id: ObjectId, + avoid: Option, + mut base_of: F, + ) -> StorageResult where F: FnMut( &dyn Source, @@ -226,9 +293,18 @@ impl DepthCache { if path.iter().any(|(id, _, _)| *id == current) { return Err(StorageError::Integrity("dependency cycle")); } - if let Some(cost) = self.costs.get(¤t).copied() { - cached_edge = 1; - break cost; + if Some(current) == avoid { + return Ok(ChainWalk::Cycle); + } + // An avoid walk reads the chain from storage: a cost cached + // earlier in this Save can come from a plan the first-wins + // registration later replaced, and only the stored edges decide + // whether this candidate names the object being stored. + if avoid.is_none() { + if let Some(cost) = self.costs.get(¤t).copied() { + cached_edge = 1; + break cost; + } } // Past the first element `current` is a base a stored record names. let location = if path.is_empty() { @@ -237,7 +313,7 @@ impl DepthCache { connection.base_location(current, i64::MAX)? }; let Some(location) = location else { - return Ok(None); + return Ok(ChainWalk::Absent); }; path.push((current, location.canonical_length as u64, 0)); // A chain of depth `d` has `d + 1` records, and the deepest supported @@ -252,6 +328,9 @@ impl DepthCache { last.2 = edge.width; } match edge.base { + // The record names the object being stored: its own copy may not + // be published yet, but the edge is already a cycle-to-be. + Some(base) if Some(base) == avoid => return Ok(ChainWalk::Cycle), Some(base) => current = base, None => { break ChainCost { @@ -291,7 +370,7 @@ impl DepthCache { self.record(*id, level); result = level; } - Ok(Some(result)) + Ok(ChainWalk::Cost(result)) } /// Records the depth and chain cost of one identity. @@ -542,13 +621,13 @@ pub fn select( input.counters.note_depth(role, 0); return Ok(full); } - Some(id) => match probe(input, id, role)? { - true => Some(id), + Some(candidate) => match probe(input, candidate, role, id)? { + true => Some(candidate), false => None, }, None => None, }, - _ => match acquisition(input, role, advisory)? { + _ => match acquisition(input, role, advisory, id)? { Some(id) => Some(id), // A payload no PREFIX record can beat asks the ring nothing: the // answer is FULL, as a trial would find (`prefix_cannot_win`). @@ -558,10 +637,10 @@ pub fn select( input.candidates.ensure_loaded(input.connection)?; let found = input.candidates.propose(id, &sig); match found { - Some(id) => match probe(input, id, role)? { + Some(proposal) => match probe(input, proposal, role, id)? { true => { - from_ring = Some((id, sig)); - Some(id) + from_ring = Some((proposal, sig)); + Some(proposal) } false => None, }, @@ -589,9 +668,21 @@ pub fn select( // A chunk's trial outcome is noted against the base it was offered, which // re-basing may replace (`LosingBases`). let offered = (role == ObjectRole::Chunk).then_some(base_id); - let base_cost = chain_cost(input, base_id)?; + let Some(base_cost) = chain_cost(input, base_id, id)? else { + // The candidate's chain names this object: a concurrent writer already + // stored a copy that depends on it, so using it as a base would close a + // cycle. Store FULL by policy (the concurrent copy keeps the object). + input.counters.cyclic_candidates = input.counters.cyclic_candidates.saturating_add(1); + if lane == PackLane::WholeFile { + let sig = prehashed.unwrap_or_else(|| signature(raw)); + input.candidates.ensure_loaded(input.connection)?; + input.candidates.insert(id, sig); + } + input.counters.note_depth(role, 0); + return Ok(full); + }; let Some((base_id, base_cost)) = - trial_base(input, base_id, base_cost, canonical.len() as u64, depth_cap)? + trial_base(input, base_id, base_cost, canonical.len() as u64, depth_cap, id)? else { return refused_by_budget(input, id, role, raw, prehashed, full); }; @@ -705,18 +796,29 @@ fn refused_by_budget( Ok(full) } -/// Depth and work cost of a stored candidate's chain, from its records' sizes. -fn chain_cost(input: &mut SelectInput<'_>, id: ObjectId) -> StorageResult { +/// Depth and work cost of a stored candidate's chain, from its records' sizes; +/// `None` when the chain names `avoid`, the object being stored. +fn chain_cost( + input: &mut SelectInput<'_>, + id: ObjectId, + avoid: ObjectId, +) -> StorageResult> { let mut bases = ChainBases::new(input.packs); let started = Instant::now(); - let cost = input.depths.cost_of( + let cost = input.depths.cost_avoiding( input.connection, input.decode, id, + avoid, |connection, workspace, location| bases.edge(connection, workspace, location), ); SaveProfile::charge(&mut input.profile.resolve.cost_ns, started); - cost?.ok_or(StorageError::Integrity("selected base is not stored")) + match cost? { + ChainWalk::Cost(cost) => Ok(Some(cost)), + // `probe` admitted the candidate as stored; a dangling base is corrupt. + ChainWalk::Absent => Err(StorageError::Integrity("selected base is not stored")), + ChainWalk::Cycle => Ok(None), + } } /// The base the one trial runs against, and its chain cost (#89). @@ -734,6 +836,7 @@ fn trial_base( cost: ChainCost, target: u64, depth_cap: u8, + avoid: ObjectId, ) -> StorageResult> { let capped = cost.depth >= depth_cap; if capped { @@ -748,7 +851,9 @@ fn trial_base( let root = chain_root(input.connection, input.packs, input.decode, id); SaveProfile::charge(&mut input.profile.resolve.cost_ns, started); let root = root?.object_id; - let root_cost = chain_cost(input, root)?; + let Some(root_cost) = chain_cost(input, root, avoid)? else { + return Ok(None); + }; if root_cost.depth >= depth_cap { return Ok(None); } @@ -804,8 +909,13 @@ fn note_stored(profile: &mut SaveProfile, record: &EncodedRecord) { /// Every rejected candidate is counted, whether it was absent or present but /// ineligible; neither ever becomes a failure of the operation. A candidate at /// the depth cap is eligible: selection re-bases it onto its chain root (#89). -fn probe(input: &mut SelectInput<'_>, id: ObjectId, role: ObjectRole) -> StorageResult { - if eligible(input, id, role)? { +fn probe( + input: &mut SelectInput<'_>, + id: ObjectId, + role: ObjectRole, + avoid: ObjectId, +) -> StorageResult { + if eligible(input, id, role, avoid)? { return Ok(true); } input.counters.ineligible_candidates = input.counters.ineligible_candidates.saturating_add(1); @@ -816,16 +926,22 @@ fn acquisition( input: &mut SelectInput<'_>, role: ObjectRole, advisory: &[ObjectId], + avoid: ObjectId, ) -> StorageResult> { for id in advisory { - if probe(input, *id, role)? { + if probe(input, *id, role, avoid)? { return Ok(Some(*id)); } } Ok(None) } -fn eligible(input: &mut SelectInput<'_>, id: ObjectId, role: ObjectRole) -> StorageResult { +fn eligible( + input: &mut SelectInput<'_>, + id: ObjectId, + role: ObjectRole, + avoid: ObjectId, +) -> StorageResult { let Some(location) = input.connection.location(id, i64::MAX)? else { input.counters.absent_candidates = input.counters.absent_candidates.saturating_add(1); return Ok(false); @@ -835,18 +951,25 @@ fn eligible(input: &mut SelectInput<'_>, id: ObjectId, role: ObjectRole) -> Stor } let mut bases = ChainBases::new(input.packs); let started = Instant::now(); - let depth = input.depths.depth_of( + let walk = input.depths.cost_avoiding( input.connection, input.decode, id, + avoid, |connection, workspace, location| bases.edge(connection, workspace, location), ); SaveProfile::charge(&mut input.profile.resolve.eligible_ns, started); - if depth?.is_none() { - input.counters.absent_candidates = input.counters.absent_candidates.saturating_add(1); - return Ok(false); + match walk? { + ChainWalk::Cost(_) => Ok(true), + ChainWalk::Absent => { + input.counters.absent_candidates = input.counters.absent_candidates.saturating_add(1); + Ok(false) + } + ChainWalk::Cycle => { + input.counters.cyclic_candidates = input.counters.cyclic_candidates.saturating_add(1); + Ok(false) + } } - Ok(true) } fn acquire(input: &mut SelectInput<'_>, id: ObjectId) -> StorageResult> { diff --git a/core/crates/layerfs-storage/src/save/pooled.rs b/core/crates/layerfs-storage/src/save/pooled.rs index f5b01ec28a..36a86ae156 100644 --- a/core/crates/layerfs-storage/src/save/pooled.rs +++ b/core/crates/layerfs-storage/src/save/pooled.rs @@ -9,6 +9,7 @@ use super::{source::WaveSource, state::State}; use crate::{ encoding::{ + delta::select::ChainWalk, pool::{delta, leaf}, EncodedRecord, }, @@ -57,7 +58,7 @@ impl State<'_> { ) -> StorageResult { let input = PoolingLeaf::decode(object.canonical())?; let mut known = BTreeMap::<[u8; INODE_VALUE_BYTES], u32>::new(); - let bases = self.pooled_bases(advisory, &mut known)?; + let bases = self.pooled_bases(object.id(), advisory, &mut known)?; // Values no base holds may still be ones this Save already assigned, // which is the common case while a whole tree is first saved. let mut candidates = BTreeSet::new(); @@ -180,6 +181,7 @@ impl State<'_> { /// another delta still gives its rows their ordinals. fn pooled_bases( &mut self, + target: ObjectId, advisory: &[ObjectId], known: &mut BTreeMap<[u8; INODE_VALUE_BYTES], u32>, ) -> StorageResult> { @@ -201,10 +203,11 @@ impl State<'_> { let reader = &mut self.pool; let groups = &mut self.groups; let packs = &mut self.packs; - let Some(cost) = self.depths.cost_of( + let walk = self.depths.cost_avoiding( &source, &mut self.decode, *id, + target, |source, workspace, location| { // The pool reader keeps the encoded account of a pooled chain // (`chain_encoded` below), so the walk measures no width. @@ -220,8 +223,10 @@ impl State<'_> { ) .map(|base| crate::encoding::delta::read::ChainEdge { base, width: 0 }) }, - )? - else { + )?; + let ChainWalk::Cost(cost) = walk else { + // A base whose chain names this leaf would close a cycle; an + // absent or dangling one cannot carry it. continue; }; let (body, canonical) = self.pool.leaf_parts_with_caches( diff --git a/core/docs/issues/project-41/gc-t10-report-status.md b/core/docs/issues/project-41/gc-t10-report-status.md index 48df05d38d..5125a0e9d9 100644 --- a/core/docs/issues/project-41/gc-t10-report-status.md +++ b/core/docs/issues/project-41/gc-t10-report-status.md @@ -74,8 +74,47 @@ backend-only field, so PostgreSQL reports its zeros through the same keys wire change. `store.status` reads the Store-side `gc_op` at the same point in `status.rs`; nothing is read from a file there. +## Metrics and SLO signals (T10.3) + +`engine/crates/layerfs-persistence/src/compact_metrics.rs` publishes the +compaction observations from the real `store.compact` and `store.status` +paths: + +- counters: `compact.runs`, `compact.operations{outcome}`, + `compact.refusals{code}`, `compact.settles{kind}`, + `compact.retries{reason}`, `compact.status{state}` and + `compact.slo{objective,result}` (`residue_free`, `generation`); +- duration aggregates: `compact.phase.duration_ns{phase,statistic}` for + `mark`/`build`/`verify`/`install` and `compact.duration_ns{statistic}`, each + with `count`, `sum` and `max`; +- the last successful run's §11 gauges: `compact.dead_bytes{kind}`, + `compact.kept_waste{part}`, `compact.kept_waste_bytes`, + `compact.residue_bytes` and `compact.generation{which}`. + +Labels come only from closed enums: outcome, phase, refusal code, settle kind, +retry reason, status state, SLO objective/result, statistic and report key. A +Store name, path, operation id or artifact name is never a label, so metric +cardinality is fixed. A `none` run times only `mark`; a rebuild times all four +phases; a failure or unknown run records its outcome and total but publishes +no report gauge; a run that settles an earlier leftover adds `leftover` to +`compact.settles` and `compact.retries`. A `Busy`/`Unresolved` refusal that +stops the call before a run is counted once by the control path, and a refusal +the measured run itself produces is counted by that run. + +The registry follows the telemetry crate's rules (fixed low-cardinality +labels, recording never changes a result). `store.compact` has no new public +metrics call: `snapshot()` reads the process totals and +`CompactMetricsCapture` captures one thread, which the tests use. + ## Tests +- `engine/crates/layerfs-persistence/tests/compact_metrics.rs`: a successful + rebuild (all four phase durations, outcome, dead/kept-waste/residue/generation + gauges and both SLO checks), the `none` path (only `mark` timed, generation + kept), a stopped `AfterBuild` run followed by the leftover settle + (`uncertain` outcome, then `rebuild` + `retries{leftover}` + + `settles{leftover}`), and a definite failure with no report gauge. Every + capture also asserts closed label keys and values. - `engine/crates/layerfs-persistence/tests/sqlite_compact.rs`: `the_report_projects_every_section_11_field`, `the_empty_store_report_explains_its_zeros`, @@ -86,10 +125,14 @@ wire change. `store.status` reads the Store-side `gc_op` at the same point in - `control/crates/layerfs-store/tests/compact_report_status.rs`: the report wire is the snake_case contract shape (including `zero_reasons` and the `delta_bases.references` hex), and `store.status` projects an idle Store, - a live owner's record and a leftover one (`op`, `state`, `phases`). + a live owner's record and a leftover one (`op`, `state`, `phases`), and the + `compact.status{state}` metric of each read. ## Gaps +- The compaction metrics are emitted into the process registry only; no SDK + call or CLI command renders `snapshot()` yet. +- T9's PostgreSQL rebuild has no metrics of its own yet. - T9's PostgreSQL rebuild and its `gc_op` status read are not implemented; the trait and the status comment are the only PostgreSQL pieces. - The `{value, cap}` capped-field shape is not produced: the SQLite receipt diff --git a/docs/architecture/api/README.md b/docs/architecture/api/README.md index 467bbcc365..c85436b1fc 100644 --- a/docs/architecture/api/README.md +++ b/docs/architecture/api/README.md @@ -2,7 +2,7 @@ > **Status:** Current architecture guide for LayerFS 2.0.0; maintained with the source. -The public surface: the `layerfs-api` call table with its one dispatcher, and the front ends (the `layerfs` command, Node, Python and a local MCP server) that expose its **73 calls in 10 families** with the same names and arguments. +The public surface: the `layerfs-api` call table with its one dispatcher, and the front ends (the `layerfs` command, Node, Python and a local MCP server) that expose its **76 calls in 10 families** with the same names and arguments. | | | | --- | --- | @@ -85,7 +85,7 @@ give each call's own arguments, answer and errors. | Test or example | Command | Platform | Shows | | --- | --- | --- | --- | -| [`calls_table.rs`](../../../api/crates/layerfs-api/tests/calls_table.rs) | `cargo +1.85.1 test --locked -p layerfs-api --test calls_table` | any Unix host | 73 calls in ten families; one source file per call; refusals before any effect | +| [`calls_table.rs`](../../../api/crates/layerfs-api/tests/calls_table.rs) | `cargo +1.85.1 test --locked -p layerfs-api --test calls_table` | any Unix host | 76 calls in ten families; one source file per call; refusals before any effect | | [`coverage.mjs`](../../../api/node/test/coverage.mjs) | `node --test api/node/test/coverage.mjs` | macOS or Linux, with the built addon, Python module and CLI | every front end matches the table | | [`file-history.mjs`](../../../api/node/examples/file-history.mjs) | `node api/node/examples/file-history.mjs` | macOS or Linux, with the built addon | a Store, Init, file writes and history reads | diff --git a/docs/architecture/api/calls/README.md b/docs/architecture/api/calls/README.md index d17fa5cc97..2744390222 100644 --- a/docs/architecture/api/calls/README.md +++ b/docs/architecture/api/calls/README.md @@ -41,7 +41,7 @@ The call table and the one dispatcher every front end goes through: what a call | Behaviour | Detail | Source | | --- | --- | --- | -| Table | ten `Family { name, list }`; a `Call` is `{ family, call, args, options, help, run }`, an `Arg` `{ name, kind, optional }`; 73 calls, help order | [`table.rs`](../../../../api/crates/layerfs-api/src/calls/table.rs), [`lib.rs`](../../../../api/crates/layerfs-api/src/lib.rs) `families` | +| Table | ten `Family { name, list }`; a `Call` is `{ family, call, args, options, help, run }`, an `Arg` `{ name, kind, optional }`; 76 calls, help order | [`table.rs`](../../../../api/crates/layerfs-api/src/calls/table.rs), [`lib.rs`](../../../../api/crates/layerfs-api/src/lib.rs) `families` | | JSON form | `table_json()`: `[{ family, call, args: [{ name, kind, optional }], options, help }]`; Node's `table`, Python's `TABLE`; the CLI parser and help read the same `Call` values | `table.rs` `table_json` | | Shared options | `PAGE` (`page_size`, `page_pos`), `DIFF` (`paths_only`, `page_size`, `page_pos`, `cursor`), `MESSAGE` (`message`), `PROGRESS` (`on_progress`) | `table.rs` | | Kinds | below | `table.rs` `Kind` | @@ -160,7 +160,7 @@ changes it. Reading and clearing it are the [`logs`](../sdk/logs.md) calls. | Test or example | Command | Platform | Shows | | --- | --- | --- | --- | -| [`calls_table.rs`](../../../../api/crates/layerfs-api/tests/calls_table.rs) | `cargo +1.85.1 test --locked -p layerfs-api --test calls_table` | any Unix host, temporary folders | ten families and 73 calls; unknown calls and arguments refused before any effect; each family reached; JSON round trips; sizes and keys; a relative home refused; one source file per call | +| [`calls_table.rs`](../../../../api/crates/layerfs-api/tests/calls_table.rs) | `cargo +1.85.1 test --locked -p layerfs-api --test calls_table` | any Unix host, temporary folders | ten families and 76 calls; unknown calls and arguments refused before any effect; each family reached; JSON round trips; sizes and keys; a relative home refused; one source file per call | | [`calls_scope.rs`](../../../../api/crates/layerfs-api/tests/calls_scope.rs) | `cargo +1.85.1 test --locked -p layerfs-api --test calls_scope` | any Unix host | a scope names its project, refuses every call it does not cover, needs a Sandbox of its project, and a scoped `branch.list` reads every page | | [`scope_references.rs`](../../../../api/crates/layerfs-api/tests/scope_references.rs) | `cargo +1.85.1 test --locked -p layerfs-api --test scope_references` | any Unix host | fork and publish references outside the namespace refused before any effect; the JSON form refuses the same | | [`logs.rs`](../../../../api/crates/layerfs-api/tests/logs.rs) | `cargo +1.85.1 test --locked -p layerfs-api --test logs` | any Unix host | one line per call, rendering and redaction, `logs.list` and `logs.reset` | diff --git a/docs/architecture/api/front-ends/mcp.md b/docs/architecture/api/front-ends/mcp.md index 4f4fd02c3e..1a91f60383 100644 --- a/docs/architecture/api/front-ends/mcp.md +++ b/docs/architecture/api/front-ends/mcp.md @@ -98,12 +98,12 @@ Each call belongs to exactly one bucket, `work` (listed by both profiles) or | Bucket | Calls | | --- | --- | | `work` | the `branch`, `commit`, `file` and `workspace` families; `project.list`, `project.get`, `project.export`, `sandbox.list`, `sandbox.get` | -| `admin` | `project.init`, `project.remove`, `sandbox.create`, `sandbox.close`; the `machine`, `store`, `backup` and `logs` families | +| `admin` | `project.init`, `project.delete`, `project.remove_file`, `branch.remove`, `store.compact`, `sandbox.create`, `sandbox.close`; the `machine`, `store`, `backup` and `logs` families | `work` lets an agent read a project, work on Branches and files (each write is one explicit Commit), run in a mounted Workspace and export a snapshot. `admin` adds the calls that start workers, move whole Stores, hold -credentials, delete records or change the shape of the home. A new call with +credentials, retire or compact records, or change the shape of the home. A new call with no bucket fails `tools()`, generation and the test rather than appearing silently. Regenerate the table below with `node api/mcp/scripts/gen-profiles.mjs` (`--check` compares; both need the @@ -111,16 +111,17 @@ built addon). -73 calls: 38 in `work`, 35 in `admin` only; `--profile admin` lists all 73. +76 calls: 38 in `work`, 38 in `admin` only; `--profile admin` lists all 76. | Call | Bucket | Profiles that list it | Why | | --- | --- | --- | --- | | `project.init` | admin | admin | import a host folder into a Store; administration | -| `project.list` | work | work, admin | read a project's record or its entry counts, or export one (work); importing and removing a project are administration | -| `project.get` | work | work, admin | read a project's record or its entry counts, or export one (work); importing and removing a project are administration | -| `project.stats` | work | work, admin | read a project's record or its entry counts, or export one (work); importing and removing a project are administration | +| `project.list` | work | work, admin | read a project's record or its entry counts, or export one (work); importing, deleting or hiding a path in a project is administration | +| `project.get` | work | work, admin | read a project's record or its entry counts, or export one (work); importing, deleting or hiding a path in a project is administration | +| `project.stats` | work | work, admin | read a project's record or its entry counts, or export one (work); importing, deleting or hiding a path in a project is administration | | `project.export` | work | work, admin | export a Branch snapshot to a local folder under a launch-time --export-root; a folder scope refuses it | -| `project.remove` | admin | admin | remove a project from its Store; administration | +| `project.delete` | admin | admin | retire a project in its Store and remove its home entry; administration; a folder scope refuses it | +| `project.remove_file` | admin | admin | hide one absolute path from every node at or below its marker frontier; administration; a folder scope refuses it | | `branch.list` | work | work, admin | work on Branches: list, read, fork, merge, publish and diff | | `branch.get` | work | work, admin | work on Branches: list, read, fork, merge, publish and diff | | `branch.commits` | work | work, admin | work on Branches: list, read, fork, merge, publish and diff | @@ -129,6 +130,7 @@ built addon). | `branch.merge` | work | work, admin | work on Branches: list, read, fork, merge, publish and diff | | `branch.publish` | work | work, admin | work on Branches: list, read, fork, merge, publish and diff | | `branch.diff` | work | work, admin | work on Branches: list, read, fork, merge, publish and diff | +| `branch.remove` | admin | admin | retire one Branch in its Store; administration; a folder scope refuses it | | `commit.list` | work | work, admin | read a Branch's Commit history | | `commit.get` | work | work, admin | read a Branch's Commit history | | `commit.diff` | work | work, admin | read a Branch's Commit history | @@ -180,6 +182,7 @@ built addon). | `store.push` | admin | admin | create, connect, transfer and remove Stores; administration | | `store.pull` | admin | admin | create, connect, transfer and remove Stores; administration | | `store.remove` | admin | admin | create, connect, transfer and remove Stores; administration | +| `store.compact` | admin | admin | reclaim one sqlite Store's dead bytes; administration; a folder scope refuses it | | `store.disconnect` | admin | admin | create, connect, transfer and remove Stores; administration | | `backup.connect` | admin | admin | upload and restore a Store on a bucket; administration | | `backup.disconnect` | admin | admin | upload and restore a Store on a bucket; administration | diff --git a/docs/architecture/api/sdk/README.md b/docs/architecture/api/sdk/README.md index a1b2ff608b..c994cdfa8f 100644 --- a/docs/architecture/api/sdk/README.md +++ b/docs/architecture/api/sdk/README.md @@ -2,7 +2,7 @@ > **Status:** Current architecture guide for LayerFS 2.0.0; maintained with the source. -Every call a program can make: **73 calls in 10 families**, the same names and arguments in JavaScript, Python and the `layerfs` command, one page per family. +Every call a program can make: **76 calls in 10 families**, the same names and arguments in JavaScript, Python and the `layerfs` command, one page per family. | | | | --- | --- | @@ -49,14 +49,14 @@ built table. | Family | Calls, in help order | Runs by default | Source | | --- | --- | --- | --- | -| [`project`](project.md) | [`init`](project.md#projectinit), [`list`](project.md#projectlist), [`get`](project.md#projectget), [`stats`](project.md#projectstats), [`export`](project.md#projectexport), [`remove`](project.md#projectremove) | `list`, `get`: home records; the rest where the Store's calls run | [`project/`](../../../../api/crates/layerfs-api/src/project) | -| [`branch`](branch.md) | [`list`](branch.md#branchlist), [`get`](branch.md#branchget), [`commits`](branch.md#branchcommits), [`get_commit`](branch.md#branchget_commit), [`fork`](branch.md#branchfork), [`merge`](branch.md#branchmerge), [`publish`](branch.md#branchpublish), [`diff`](branch.md#branchdiff) | where the Store's calls run | [`branch/`](../../../../api/crates/layerfs-api/src/branch) | +| [`project`](project.md) | [`init`](project.md#projectinit), [`list`](project.md#projectlist), [`get`](project.md#projectget), [`stats`](project.md#projectstats), [`export`](project.md#projectexport), [`delete`](project.md#projectdelete), [`remove_file`](project.md#projectremove_file) | `list`, `get`: home records; the rest where the Store's calls run | [`project/`](../../../../api/crates/layerfs-api/src/project) | +| [`branch`](branch.md) | [`list`](branch.md#branchlist), [`get`](branch.md#branchget), [`commits`](branch.md#branchcommits), [`get_commit`](branch.md#branchget_commit), [`fork`](branch.md#branchfork), [`merge`](branch.md#branchmerge), [`publish`](branch.md#branchpublish), [`diff`](branch.md#branchdiff), [`remove`](branch.md#branchremove) | where the Store's calls run | [`branch/`](../../../../api/crates/layerfs-api/src/branch) | | [`commit`](commit.md) | [`list`](commit.md#commitlist), [`get`](commit.md#commitget), [`diff`](commit.md#commitdiff) | where the Store's calls run | [`commit/`](../../../../api/crates/layerfs-api/src/commit) | | [`file`](file.md) | [`read`](file.md#fileread), [`stat`](file.md#filestat), [`list`](file.md#filelist), [`glob`](file.md#fileglob), [`grep`](file.md#filegrep), [`revision`](file.md#filerevision), [`blame`](file.md#fileblame), [`diff`](file.md#filediff), [`write`](file.md#filewrite), [`edit`](file.md#fileedit), [`rm`](file.md#filerm), [`mkdir`](file.md#filemkdir), [`mv`](file.md#filemv), [`cp`](file.md#filecp), [`apply`](file.md#fileapply) | where the Store's calls run | [`file/`](../../../../api/crates/layerfs-api/src/file) | | [`sandbox`](sandbox.md) | [`create`](sandbox.md#sandboxcreate), [`list`](sandbox.md#sandboxlist), [`get`](sandbox.md#sandboxget), [`close`](sandbox.md#sandboxclose) | records here; start and stop on the Sandbox's machine | [`sandbox/`](../../../../api/crates/layerfs-api/src/sandbox) | | [`workspace`](workspace.md) | [`mount`](workspace.md#workspacemount), [`exec`](workspace.md#workspaceexec), [`exec_cancel`](workspace.md#workspaceexec_cancel), [`commit`](workspace.md#workspacecommit), [`unmount`](workspace.md#workspaceunmount), [`status`](workspace.md#workspacestatus) | the Sandbox's daemon; `exec` and `exec_cancel` in the Sandbox's runtime | [`workspace/`](../../../../api/crates/layerfs-api/src/workspace) | | [`machine`](machine.md) | [`list`](machine.md#machinelist), [`platforms`](machine.md#machineplatforms), [`get`](machine.md#machineget), [`images`](machine.md#machineimages), [`load`](machine.md#machineload), [`prune`](machine.md#machineprune), [`status`](machine.md#machinestatus), [`start`](machine.md#machinestart), [`stop`](machine.md#machinestop), [`create`](machine.md#machinecreate), [`remove`](machine.md#machineremove), [`update`](machine.md#machineupdate) | the caller's process, through the platform adapter | [`machine/`](../../../../api/crates/layerfs-api/src/machine) | -| [`store`](store.md) | [`list`](store.md#storelist), [`get`](store.md#storeget), [`status`](store.md#storestatus), [`stats`](store.md#storestats), [`create`](store.md#storecreate), [`connect`](store.md#storeconnect), [`attach`](store.md#storeattach), [`detach`](store.md#storedetach), [`push`](store.md#storepush), [`pull`](store.md#storepull), [`remove`](store.md#storeremove), [`disconnect`](store.md#storedisconnect) | the caller's process; sqlite file steps in the Store machine's worker | [`store/`](../../../../api/crates/layerfs-api/src/store) | +| [`store`](store.md) | [`list`](store.md#storelist), [`get`](store.md#storeget), [`status`](store.md#storestatus), [`stats`](store.md#storestats), [`create`](store.md#storecreate), [`connect`](store.md#storeconnect), [`attach`](store.md#storeattach), [`detach`](store.md#storedetach), [`push`](store.md#storepush), [`pull`](store.md#storepull), [`remove`](store.md#storeremove), [`compact`](store.md#storecompact), [`disconnect`](store.md#storedisconnect) | the caller's process; sqlite file steps in the Store machine's worker | [`store/`](../../../../api/crates/layerfs-api/src/store) | | [`backup`](backup.md) | [`connect`](backup.md#backupconnect), [`disconnect`](backup.md#backupdisconnect), [`list`](backup.md#backuplist), [`create`](backup.md#backupcreate), [`restore`](backup.md#backuprestore) | the caller's process; `create` stages on the Store's machine | [`backup/`](../../../../api/crates/layerfs-api/src/backup) | | [`logs`](logs.md) | [`list`](logs.md#logslist), [`reset`](logs.md#logsreset) | the caller's process, home files only | [`logs/`](../../../../api/crates/layerfs-api/src/logs) | @@ -103,20 +103,20 @@ in the [API layer page](../README.md#calling-conventions). | Test or example | Command | Platform | Shows | | --- | --- | --- | --- | | [`inventory.mjs`](../../../../api/node/test/branch-file/inventory.mjs) | `perl -e 'alarm 120; exec @ARGV' node --test api/node/test/branch-file/inventory.mjs` | macOS or Linux, with the built addon (`npm --prefix api run build:native`) and `target/debug/layerfs` | the count line and one heading per call match the built table; branch and file CLI help exposes every option | -| [`calls_table.rs`](../../../../api/crates/layerfs-api/tests/calls_table.rs) | `cargo +1.85.1 test --locked -p layerfs-api --test calls_table` | any Unix host | 73 calls in ten families; one source file per call; unknown calls and arguments refused before any effect | +| [`calls_table.rs`](../../../../api/crates/layerfs-api/tests/calls_table.rs) | `cargo +1.85.1 test --locked -p layerfs-api --test calls_table` | any Unix host | 76 calls in ten families; one source file per call; unknown calls and arguments refused before any effect | | [`file-history.mjs`](../../../../api/node/examples/file-history.mjs) | `node api/node/examples/file-history.mjs` | macOS or Linux, with the built addon | a Store, Init, file writes and history reads | ## Pages | Page | What it covers | | --- | --- | -| [project](project.md) | Init, project records, stats, export, remove | -| [branch](branch.md) | Branches, saved history, fork, merge, publish, diff; the saved-query rules | +| [project](project.md) | Init, project records, stats, export, delete, path removal | +| [branch](branch.md) | Branches, saved history, fork, merge, publish, diff, retire; the saved-query rules | | [commit](commit.md) | a Branch's Commits and saved comparisons | | [file](file.md) | reads at a saved version; one-Commit writes | | [sandbox](sandbox.md) | Sandboxes: create, list, get, close | | [workspace](workspace.md) | mount, exec, cancel, commit, status, unmount | | [machine](machine.md) | built-in and VM machines | -| [store](store.md) | sqlite and PostgreSQL Stores | +| [store](store.md) | sqlite and PostgreSQL Stores; compaction | | [backup](backup.md) | buckets and Store backups | | [logs](logs.md) | the home's call log | diff --git a/docs/architecture/api/sdk/branch.md b/docs/architecture/api/sdk/branch.md index 480c6faae1..85933cdfd9 100644 --- a/docs/architecture/api/sdk/branch.md +++ b/docs/architecture/api/sdk/branch.md @@ -2,7 +2,7 @@ > **Status:** Current architecture guide for LayerFS 2.0.0; maintained with the source. -The `branch` calls: list and read a project's Branches and their saved history, fork, merge, publish to `main`, and compare two Branches, within the [SDK](README.md). +The `branch` calls: list and read a project's Branches and their saved history, fork, merge, publish to `main`, compare two Branches and retire one, within the [SDK](README.md). | | | | --- | --- | @@ -35,6 +35,7 @@ The `branch` calls: list and read a project's Branches and their saved history, | [`branch.merge`](#branchmerge) | `branch.merge` | write | | [`branch.publish`](#branchpublish) | `branch.publish` | write | | [`branch.diff`](#branchdiff) | `branch.diff_branches` | saved read | +| [`branch.remove`](#branchremove) | `branch.remove` | write | Each entry forwards a typed request to `layerfs_store::calls::branch`, which renames the table's snake_case fields to the Store method's @@ -287,6 +288,31 @@ comparison and attribution are each bounded to 64 MiB per request ([`read/branch_compare.rs`](../../../../engine/crates/layerfs-store-service/src/read/branch_compare.rs), [`read/compare.rs`](../../../../engine/crates/layerfs-store-service/src/read/compare.rs)). +### branch.remove + +Retires one Branch in its Store (spec §4). Its row is hidden from listings and +name resolution; fork, merge, publish and mount of it are refused, its Commits +and objects stay until a later [`store.compact`](store.md#storecompact), and +`main` is `ReservedName`. + +```text +JS await layerfs.branch.remove(project, branch) +Python layerfs.branch.remove(project, branch) +CLI layerfs branch remove +``` + +Returns `{ kind: "Removed", project, branch, removed_ms }`. A repeat is +`NoSuchBranch` (only `project.delete` is retry-idempotent); a concurrent +remove is `Busy` with phase `"retire"`. + +| Error | When | Source | +| --- | --- | --- | +| `ReservedName` | the Branch is `main` | [`methods/branch/remove.rs`](../../../../engine/crates/layerfs-store-service/src/methods/branch/remove.rs) | +| `NoSuchStore`, `NoSuchBranch` | the Store or Branch is missing (or already retired) | same | +| `MountsActive` | a mount of the Branch is live | [`history/admission.rs`](../../../../engine/crates/layerfs-store-service/src/history/admission.rs) | +| `Busy`, `Unresolved` | another user or operation holds the Branch, or a dead owner left an uncertain one | spec §5.1 | +| `Unknown` | worker route: the answer was lost | [`worker/client.rs`](../../../../control/crates/layerfs-machine/src/worker/client.rs) | + ## Saved queries Shared by `branch.commits`, `branch.get_commit`, `branch.diff` and the diff --git a/docs/architecture/api/sdk/project.md b/docs/architecture/api/sdk/project.md index e300021835..597349806f 100644 --- a/docs/architecture/api/sdk/project.md +++ b/docs/architecture/api/sdk/project.md @@ -2,12 +2,12 @@ > **Status:** Current architecture guide for LayerFS 2.0.0; maintained with the source. -The `project` calls: import a host folder into a Store as `/`, read the home's project records, count or export a saved tree, and remove a project, within the [SDK](README.md). +The `project` calls: import a host folder into a Store as `/`, read the home's project records, count or export a saved tree, retire a project, and hide one path from every node at or below a frontier, within the [SDK](README.md). | | | | --- | --- | | Source | [`api/crates/layerfs-api/src/project`](../../../../api/crates/layerfs-api/src/project), [`layerfs-store/src/project`](../../../../control/crates/layerfs-store/src/project), [`layerfs-control/src/project.rs`](../../../../control/crates/layerfs-control/src/project.rs) | -| Runs by default | `list`, `get`: the caller's process, home records only. `init`, `stats`, `export`, `remove`: where the Store's calls run (the caller's process for PostgreSQL and a sqlite Store on a locally executing machine, else that machine's worker) | +| Runs by default | `list`, `get`: the caller's process, home records only. `init`, `stats`, `export`, `delete`, `remove_file`: where the Store's calls run (the caller's process for PostgreSQL and a sqlite Store on a locally executing machine, else that machine's worker) | | Design | [Stores and projects](../../control/stores-and-projects/README.md), [projects](../../control/stores-and-projects/projects.md), [Project Init](../../engine/project-init/README.md) | ## Calls @@ -22,7 +22,7 @@ The `project` calls: import a host folder into a Store as `/`, r +--> stats export (one pinned saved tree) +--> branch.*, commit.*, file.*, sandbox.create ... v - remove / (no Sandbox of it may be recorded) + delete / remove_file / ``` | Call | Returns | @@ -32,7 +32,8 @@ The `project` calls: import a host folder into a Store as `/`, r | [`project.get`](#projectget) | the project summary | | [`project.stats`](#projectstats) | entry counts of one pinned tree | | [`project.export`](#projectexport) | pinned identity and local output counts | -| [`project.remove`](#projectremove) | `{ stack, packs_kept: true, project }` | +| [`project.delete`](#projectdelete) | `{ kind: "Removed", project, deleted_ms, home_entry_removed }` | +| [`project.remove_file`](#projectremove_file) | `{ kind: "Removed" \| "UpToDate", project, path, frontier_serial, removed_ms }` | The **project summary** is `ProjectRecord::to_sdk` ([`project/record.rs`](../../../../control/crates/layerfs-store/src/project/record.rs)): @@ -231,36 +232,63 @@ per 200 ms besides the first and last Export only reads history: a lost reply creates no source mutation and no uncertain intent. -### project.remove +### project.delete -Drops one project's LayerStack (Layers, Branches, Commits) from its Store in -one write, then the project's home entry; other projects stay. +Retires one project in its Store and removes its home entry (spec §4). The +project's Layers, Branches, Commits, packs and objects stay until a later +[`store.compact`](store.md#storecompact) collects them: the project is hidden +from listings and name resolution, and the Store stays addressable. No mount +or operation of the project may be live. ```text -JS await layerfs.project.remove(project) -Python layerfs.project.remove(project) -CLI layerfs project remove +JS await layerfs.project.delete(project) +Python layerfs.project.delete(project) +CLI layerfs project delete ``` -Returns `{ stack, packs_kept: true, project }`: `stack` is the removed -LayerStack's id; `packs_kept` is always true because the project's packs and -objects stay in the Store -([`project/remove.rs`](../../../../control/crates/layerfs-store/src/project/remove.rs)). -It runs through `layerfs_control::project::remove` -([`project.rs`](../../../../control/crates/layerfs-control/src/project.rs)), -under the Store's lease, locally or as the worker operation `project.remove`. +Returns `{ kind: "Removed", project, deleted_ms, home_entry_removed }`. The +Store marker is the commit point: if the home entry cannot be removed the +call still succeeds with `home_entry_removed: false` and keeps its durable +intent `store//delete/.json`, so a repeat from the same home +reuses `deleted_ms` and finishes the entry. The call is idempotent only +through that intent; it never resolves the name again. A lost worker reply +is `Unknown` and keeps the intent. | Error | When | Source | | --- | --- | --- | -| `NoSuchProject` | also when the Store holds no LayerStack of that name | [`identity.rs`](../../../../control/crates/layerfs-store/src/identity.rs) | -| `InUse` | a Sandbox of the project is recorded; `detail.related` lists `{ kind: "sandbox", name }` | [`inventory.rs`](../../../../control/crates/layerfs-control/src/inventory.rs) | -| `Unsupported` | a PostgreSQL Store ("removing a project from a PostgreSQL Store is not built"); the kernel guard refuses the Store's directory when opened (non-private mode/owner/type — another user's directory or group/other access instead of `0700` — or unsupported filesystem) | [`project/family.rs`](../../../../control/crates/layerfs-store/src/project/family.rs) | -| `Failed` | the Store write failed, its outcome included | `identity.rs` `remove_project` | -| `Unknown` | worker route: the answer was lost | [`worker/client.rs`](../../../../control/crates/layerfs-machine/src/worker/client.rs) | +| `NoSuchStore`, `NoSuchProject` | the Store or project is missing (or already retired) | [`project/delete.rs`](../../../../control/crates/layerfs-store/src/project/delete.rs) | +| `MountsActive` | a mount of the project is live; its holders are named | [`history/admission.rs`](../../../../engine/crates/layerfs-store-service/src/history/admission.rs) | +| `Busy`, `Unresolved` | another user or operation holds the project, or a dead owner left an uncertain one | spec §5.1 | +| `Unsupported` | the Store is on another machine and the project record names no LayerStack id | [`project/delete.rs`](../../../../control/crates/layerfs-store/src/project/delete.rs) | +| `Unknown` | worker route: the answer was lost; the intent stays | [`worker/client.rs`](../../../../control/crates/layerfs-machine/src/worker/client.rs) | + +### project.remove_file + +Hides one absolute project path from every node at or below its marker +frontier (spec §4.3). It writes one `path_removed` marker and changes no +pack, object, Commit or Layer; reads and stats of the path afterwards are +refused `Removed`. + +```text +JS await layerfs.project.remove_file(project, path) +Python layerfs.project.remove_file(project, path) +CLI layerfs project remove-file +``` + +The path is normalized (one leading `/` stripped) and must be an absolute +POSIX path of at most 4096 bytes and 256 components, with no empty, `.` or +`..` component and no `\` or NUL +([`path.rs`](../../../../core/crates/layerfs-history/src/contract/path.rs)). +Returns `{ kind: "Removed" | "UpToDate", project, path, frontier_serial, +removed_ms }`: the marker's stored values, `UpToDate` when no project node is +above this path's marker frontier. -After `Failed` or `Unknown` the home entry is kept (it is removed only after -success). `branch.list` answering `NoSuchProject` from the Store means the -stack is gone. +| Error | When | Source | +| --- | --- | --- | +| `InvalidInput` | the path is not a normalized absolute POSIX path | [`path.rs`](../../../../core/crates/layerfs-history/src/contract/path.rs) | +| `NoSuchStore`, `NoSuchProject` | the Store or project is missing (or retired) | [`methods/project.rs`](../../../../engine/crates/layerfs-store-service/src/methods/project.rs) | +| `MountsActive`, `Busy`, `Unresolved` | project-scope admission, as `project.delete` | spec §5.1 | +| `Unknown` | worker route: the answer was lost | [`worker/client.rs`](../../../../control/crates/layerfs-machine/src/worker/client.rs) | ## Family errors diff --git a/docs/architecture/api/sdk/store.md b/docs/architecture/api/sdk/store.md index 9ecdbe155b..d2a45bb3fc 100644 --- a/docs/architecture/api/sdk/store.md +++ b/docs/architecture/api/sdk/store.md @@ -2,7 +2,7 @@ > **Status:** Current architecture guide for LayerFS 2.0.0; maintained with the source. -The `store` calls: create, connect, inspect, move and remove the databases that hold every project's history, within the [SDK](README.md). +The `store` calls: create, connect, inspect, move, remove and compact the databases that hold every project's history, within the [SDK](README.md). | | | | --- | --- | @@ -24,6 +24,7 @@ The `store` calls: create, connect, inspect, move and remove the databases that | (back to native) detach v v remove (file + projects) disconnect (data stays) + compact (reclaim dead bytes) ``` | Call | Kind | Returns | @@ -39,6 +40,7 @@ The `store` calls: create, connect, inspect, move and remove the databases that | [`store.push`](#storepush) | sqlite | `{ store, from, to, bytes, heads }` | | [`store.pull`](#storepull) | sqlite | `{ store, from, to, bytes, heads }` | | [`store.remove`](#storeremove) | sqlite | `{ removed: name }` | +| [`store.compact`](#storecompact) | sqlite | `{ kind: "Compacted", ... }`, the §11 report | | [`store.disconnect`](#storedisconnect) | PostgreSQL | `{ disconnected: name }` | A sqlite Store is made with the Disposable profile (WAL, @@ -372,6 +374,39 @@ uncertain. Errors: `InvalidInput` (a sqlite Store; use `store.remove`); recorded, or a call in this process is running on it, [`open.rs`](../../../../control/crates/layerfs-store/src/open.rs)); `Failed`. +### store.compact + +Reclaims one sqlite Store's dead bytes by rebuilding it from its live history +(spec §3, §7): the only byte-reclaiming call, with no confirm, force or dry +run and no automatic collection. It writes its operation intent before the +first checkpoint, verifies the rebuilt Store, and installs it by rename; a +definite failure before the rename keeps the old Store and the generation `G`, +while an installed-but-uncertain reply stays at `G + 1` and is reported, never +deleted. A Store with less than 10% wholly dead packs takes the `none` path: +it marks only, writes nothing and reports `dead_bytes_refined == +dead_bytes_bound`. + +```text +JS await layerfs.store.compact(name) +Python layerfs.store.compact(name) +CLI layerfs store compact +``` + +Returns `{ kind: "Compacted", path, generation: {before, after}, ... }` +with the report's snake_case fields: `dead_bytes_bound`, +`dead_bytes_refined`, `logical_discarded`, `backend_reusable`, +`physical_shrink`, `kept_waste {dead_in_retained_packs_bytes, delta_bases +{bytes, references}, inode_blocks_bytes}`, `peak_temp_bytes`, `residue`, +`estimate` and `zero_reason`; a capped field is `{value, cap}`. + +| Error | When | Source | +| --- | --- | --- | +| `NoSuchStore`, `Unsupported` | a missing Store, a PostgreSQL Store, a non-private Store directory, or an unsupported filesystem | [`compact.rs`](../../../../control/crates/layerfs-store/src/compact.rs) | +| `MountsActive`, `Busy`, `Unresolved` | a mount, long-lived client or operation holds the Store, or a dead owner left an uncertain one | spec §5 | +| `StaleStore`, `Conflict` | a connection bypassed admission, or the sealed identity changed | spec §7, §10 | +| `Capacity` | a real allocation refusal during the rebuild; the old Store is kept | spec §7 | +| `Unknown` | the reply was lost around install; read `store.status` and the op before any second call | spec §9 | + ## Family errors | Error | When | Source | diff --git a/docs/architecture/engine/README.md b/docs/architecture/engine/README.md index 7031ed5431..a223f0cba6 100644 --- a/docs/architecture/engine/README.md +++ b/docs/architecture/engine/README.md @@ -46,7 +46,7 @@ crate except `layerfs-project`. | Topic | Crates | What it covers | Pages | | --- | --- | --- | --- | -| [Store](store/README.md) | `layerfs-persistence` | The one global Store: every project's history and immutable objects in one SQLite file or one PostgreSQL schema, written by one writer at a time. | [SQLite](store/sqlite.md), [PostgreSQL](store/postgresql.md), [Diagnostics](store/diagnostics.md) | +| [Store](store/README.md) | `layerfs-persistence` | The one global Store: every project's history and immutable objects in one SQLite file or one PostgreSQL schema, written by one writer at a time. | [SQLite](store/sqlite.md), [PostgreSQL](store/postgresql.md), [Diagnostics](store/diagnostics.md), [Testing](store/testing.md) | | [Store calls](store-calls/README.md) | `layerfs-store-service` | Typed reads, file changes and Branch history over the Store, run once in the process that opened it, and the SDK facade that names them. | [Reads](store-calls/reads.md) | | [Project Init](project-init/README.md) | `layerfs-project` | Turning one native directory into a project's first LayerStack and Branch: import, construction, then seal and install or a live add. | — | | [Overlay](overlay/README.md) | `layerfs-overlay`, `layerfs-store-service` `overlay/` | Each Workspace's own disposable SQLite file and in-memory open state, the Workspace roster and its one lock. | [Payload](overlay/payload.md), [Lifetimes](overlay/lifetimes.md) | diff --git a/docs/architecture/engine/store/README.md b/docs/architecture/engine/store/README.md index b2a670667e..9fd8da18d9 100644 --- a/docs/architecture/engine/store/README.md +++ b/docs/architecture/engine/store/README.md @@ -196,10 +196,16 @@ Source: [`records.rs`](../../../../engine/crates/layerfs-persistence/src/backend | [`binding_hint_blocks.rs`](../../../../engine/crates/layerfs-persistence/tests/binding_hint_blocks.rs) | `cargo +1.85.1 test --locked -p layerfs-persistence --test binding_hint_blocks` | macOS, Linux | Hints merge across blocks without repeats | | [`postgresql_acquisition.rs`](../../../../engine/crates/layerfs-persistence/tests/postgresql_acquisition.rs) | `LAYERFS_TEST_POSTGRES_URL=… cargo +1.85.1 test --locked -p layerfs-persistence --features postgresql --test postgresql_acquisition` | a PostgreSQL server; prints `NOT_RUN` without the variable | Creating a PostgreSQL Store, refusing a second create, and Init's acquisition over it | +The commands above assume the test environment in [Testing](testing.md): `TMPDIR` and +`CARGO_TARGET_DIR` on ext4, xfs or btrfs (apfs or hfs on macOS). +[`tools/ci/test_store_ext4.sh`](../../../../tools/ci/test_store_ext4.sh) sets both +and refuses anything else before cargo starts. + ## Pages | Page | What it covers | | --- | --- | | [SQLite](sqlite.md) | The SQLite backend: schema, sessions, lane, profile, checkpoints, seal, snapshot, heads, acquisition and merge records. | | [PostgreSQL](postgresql.md) | The PostgreSQL backend: schema, open checks and authority, connections, transactions, publication, acquisition, access and status. | -| [Diagnostics](diagnostics.md) | Read-only Store audits: observations, the SQLite and PostgreSQL audits, table coverage and the structural fallback. | \ No newline at end of file +| [Diagnostics](diagnostics.md) | Read-only Store audits: observations, the SQLite and PostgreSQL audits, table coverage and the structural fallback. | +| [Testing](testing.md) | The filesystem the Store suites need, the harness that enforces it, and the PostgreSQL test server. | \ No newline at end of file diff --git a/docs/architecture/engine/store/testing.md b/docs/architecture/engine/store/testing.md new file mode 100644 index 0000000000..f57473ef28 --- /dev/null +++ b/docs/architecture/engine/store/testing.md @@ -0,0 +1,162 @@ +# Testing the Store + +> **Status:** Current architecture guide for LayerFS 2.0.0; maintained with the source. + +The Store suites create real SQLite Stores, and a Store opens only on a local +filesystem that carries its locks. This page is the environment contract, and +the harness that enforces it before cargo spends a build. + +| | | +| --- | --- | +| Harness | [`tools/ci/test_store_ext4.sh`](../../../../tools/ci/test_store_ext4.sh) | +| Suites | `layerfs-persistence`, `layerfs-store-service`, `layerfs-store`, and the `store_*` targets of `layerfs-api` | +| Guard | [`kernel_guard.rs`](../../../../engine/crates/layerfs-store-service/src/kernel_guard.rs) | +| Related | [Store](README.md), [SQLite](sqlite.md), [PostgreSQL](postgresql.md), [Diagnostics](diagnostics.md) | + +## Why the tests need ext4 + +`kernel_guard::check` runs before a Store file is opened. It admits direct +opening only when the Store's own directory is a real directory (not a +symlink), owned by the current effective user, with mode `0700`, and the +filesystem holding it is `ext4`, `xfs` or `btrfs` on Linux, or `apfs` or `hfs` +on macOS. Anything else is `OpenRefusal::Unsupported` with the reason +`filesystem 0x… at … does not carry SQLite locks; direct Store access needs +ext4, xfs or btrfs` +([`kernel_guard.rs`](../../../../engine/crates/layerfs-store-service/src/kernel_guard.rs)). + +The allowlist is not arbitrary. Every opener of one Store must share one kernel +and a filesystem with working advisory locks: SQLite's WAL locks and the writer +admission lane's `flock` on the Store's directory +([SQLite](sqlite.md)). `tmpfs`, `overlay`, FUSE mounts and network filesystems +do not coordinate those locks between the processes a suite starts, so a Store +there is refused rather than run without coordination. + +The suites keep their Stores in two directories, and both inherit the +filesystem of the test environment: + +| Directory | In the tests | Usual host | +| --- | --- | --- | +| `TMPDIR` | `std::env::temp_dir()` | `/tmp`, which is tmpfs in most containers | +| `$CARGO_TARGET_DIR/tmp` | `env!("CARGO_TARGET_TMPDIR")` | the checkout's `target/`, an overlay in a container | + +On a host whose `/tmp` is tmpfs, or in a container whose checkout is an +overlay, the guard refuses the Store and suites such as +`layerfs-store-service --test kernel_guard` fail at their "a private directory +on a supported filesystem passes" assertion. That is an environment failure, +not a product failure. Tests that must prove the refusal on purpose use +`/dev/shm` (tmpfs), so pointing `TMPDIR` at ext4 does not weaken them. + +## Run the suites + +The harness requires `LAYERFS_TEST_TMPDIR` on a supported filesystem, refuses +anything else with exit 2 before cargo starts, and points `TMPDIR` (through a +short symlink), `CARGO_TARGET_DIR` and `CARGO_HOME` at it. + +```bash +# A cross-crate subset: the first build is the cost, then minutes. +LAYERFS_TEST_TMPDIR=/mnt/ext4/layerfs-store-tests tools/ci/test_store_ext4.sh --quick + +# Every Store suite. +LAYERFS_TEST_TMPDIR=/mnt/ext4/layerfs-store-tests tools/ci/test_store_ext4.sh + +# Print the cargo commands and the environment, run nothing. +tools/ci/test_store_ext4.sh --list +``` + +`--quick` runs a few targets per suite: + +| Suite | Targets | What they exercise | +| --- | --- | --- | +| `layerfs-persistence` | `heads`, `sqlite_publication` | Branch heads and a publication round trip | +| `layerfs-store-service` | `kernel_guard`, `commit_pipeline` | the guard admits a private ext4 directory and refuses tmpfs; a Commit pipeline | +| `layerfs-store` | `create_directory` | `store.create`'s directory ownership and its guard refusal | +| `layerfs-api` | `store_family` | the Store family's call table | + +The full run is the unfiltered `layerfs-persistence`, `layerfs-store-service` +and `layerfs-store` suites, plus every `store_*.rs` target found under +`api/crates/layerfs-api/tests/`. Other API targets (machines, sandboxes, +Docker) are not Store tests and are not run here. + +## What the harness sets + +| Variable | Value | Why | +| --- | --- | --- | +| `LAYERFS_TEST_TMPDIR` | required, validated | the supported filesystem the run may use | +| `TMPDIR` | a short private wrapper under the system temporary directory, whose `tmp` entry links to `$LAYERFS_TEST_TMPDIR/tmp` | `std::env::temp_dir()` in the tests; Unix-domain socket paths are limited to about 108 bytes | +| `CARGO_TARGET_DIR` | `$LAYERFS_TEST_TMPDIR/target` | build output, and `CARGO_TARGET_TMPDIR` for the tests | +| `CARGO_HOME` | `$LAYERFS_TEST_TMPDIR/cargo-home` | the registry and git checkouts stay with the run, off the checkout's overlay | +| `-j` | `min(nproc, 16)` by default | keeps rustc within memory on a many-core host | +| `CARGO_NET_GIT_FETCH_WITH_CLI` | `true` | fetches the pinned `fuser` git dependency with the git CLI, which honours the host's proxy and credentials | +| `GIT_SSL_NO_VERIFY` | `true` | lets that one git fetch complete through TLS inspection; scoped to this process, not a production setting | +| `--features postgresql` | added to every suite when `LAYERFS_TEST_POSTGRES_URL` is set | the PostgreSQL test files are `#![cfg(feature = "postgresql")]` | + +The `TMPDIR` wrapper exists because a Sandbox run directory is long: a test that +binds a Unix-domain socket under `TMPDIR` otherwise fails with `path must be +shorter than SUN_LEN`. The wrapper is a `mktemp -d` directory under `/tmp` +(override with `LAYERFS_TEST_SYSTEM_TMP`), removed on exit, and holds only the +symlink; `statfs` follows it, so the Stores are still on the supported +filesystem. + +Overrides: `LAYERFS_TEST_JOBS`, `LAYERFS_TEST_CARGO_HOME`, +`LAYERFS_TEST_CARGO_TARGET_DIR` and `LAYERFS_TEST_SYSTEM_TMP`. Arguments after +`--` are appended to every `cargo test`, for example +`tools/ci/test_store_ext4.sh --quick -- --nocapture`. + +## Find a supported directory + +On Linux, ask the mount table: + +```bash +findmnt -n -o FSTYPE --target /path/to/candidate # ext4, xfs or btrfs +``` + +Inside a Docker Sandbox (the `namespaces` runtime), the sandbox run directory +is ext4 while `/tmp` is tmpfs and the checkout is an overlay: `$HOME` and +`/layerfs/data/machine/native/run/` report ext4, so a directory such +as `/layerfs/data/machine/native/run//tmp/layerfs-store-tests` is a +valid `LAYERFS_TEST_TMPDIR`. Never use `/tmp`. + +On macOS the corresponding local filesystems are `apfs` and `hfs`; the +harness reads the mount table there too. + +The build and the Stores live under `LAYERFS_TEST_TMPDIR`, so allow several +gigabytes on that mount. + +## PostgreSQL + +`LAYERFS_TEST_POSTGRES_URL` is a libpq connection string (despite the name), +not a URL: + +```bash +LAYERFS_TEST_POSTGRES_URL='host=127.0.0.1 port=55433 user=postgres password=… dbname=postgres sslmode=disable' \ + LAYERFS_TEST_TMPDIR=/mnt/ext4/layerfs-store-tests tools/ci/test_store_ext4.sh +``` + +Use PostgreSQL 17 or newer. The Store schema itself needs 16 or newer for +`STORAGE PLAIN` ([PostgreSQL](postgresql.md)), and the PostgreSQL suites are +qualified on 17.x, so 17 is the supported version for tests. + +Each PostgreSQL test creates and drops its own schema: point the variable at a +scratch server, never at a schema that holds a Store you care about, and make +sure the server is reachable from the process that runs the tests (inside a +Sandbox, `127.0.0.1` is the Sandbox). Without the variable the PostgreSQL test +files print `NOT_RUN: LAYERFS_TEST_POSTGRES_URL is unset` and check nothing; +the SQLite Store suites still run and still need the supported filesystem. + +## Troubleshooting + +| Symptom | Cause | Fix | +| --- | --- | --- | +| `LAYERFS_TEST_TMPDIR is not set.` | the harness was run without the variable | set it to a directory on a supported filesystem | +| `… is on 'tmpfs', which cannot carry a Store.` | `/tmp` (or another tmpfs/overlay) was chosen | pick ext4, xfs or btrfs on Linux, apfs or hfs on macOS | +| a suite fails with `filesystem 0x… at … does not carry SQLite locks` | `TMPDIR` or `CARGO_TARGET_DIR` escaped the harness (exported by hand) | let the harness set both; do not override them to a scratch directory | +| `NOT_RUN: LAYERFS_TEST_POSTGRES_URL is unset` | no PostgreSQL server | expected; set the variable to run those cases | +| `fatal: unable to access 'https://github.com/…/fuser.git'` or a TLS error | the pinned `fuser` git dependency could not be fetched | the harness sets `CARGO_NET_GIT_FETCH_WITH_CLI=true` and `GIT_SSL_NO_VERIFY=true`; check egress to `github.com` | +| `has mode 0755 … fix with chmod 700` | a left-over Store directory with group/other access | remove the named directory; the guard never changes permissions | +| `Updating crates.io index` stays silent for minutes | the sandbox network can stall cargo's multiplexed sparse-index connection | re-run with `CARGO_HTTP_MULTIPLEXING=false`; the download cache resumes where it stopped | +| `path must be shorter than SUN_LEN` | a Unix-domain socket path exceeded the kernel limit, usually because `TMPDIR` was set long by hand | use the harness (it keeps `TMPDIR` short) or pass a short `LAYERFS_TEST_TMPDIR` | +| `Store busy before effect` | another writer held the Store | not an environment failure; rerun the suite | + +The repository's test selection and CI lanes are separate: `tools/ci_tests.py` +decides which binaries the push and nightly runs take, and this harness only +gives the Store suites the filesystem they need. diff --git a/docs/architecture/flows/call.md b/docs/architecture/flows/call.md index 46905be63f..791ded8279 100644 --- a/docs/architecture/flows/call.md +++ b/docs/architecture/flows/call.md @@ -48,7 +48,7 @@ retries. A lost answer after the request was sent is `Unknown`, never resent. | # | What happens | Owning topic | | --- | --- | --- | | 1 | The front end makes one library call: the CLI parses `layerfs `; Node and Python pass JSON text. | [Front ends](../api/front-ends/README.md), [Bindings](../api/front-ends/bindings.md) | -| 2 | The call table finds `family.call` (73 calls in 10 families) and checks every argument before any effect. | [Calls](../api/calls/README.md#what-it-does), [SDK](../api/sdk/README.md) | +| 2 | The call table finds `family.call` (76 calls in 10 families) and checks every argument before any effect. | [Calls](../api/calls/README.md#what-it-does), [SDK](../api/sdk/README.md) | | 3 | A folder scope, when the client has one, guards and rewrites the checked arguments. | [Calls: folder scope](../api/calls/README.md#folder-scope) | | 4 | The home is opened (explicit path, else `LAYERFS_HOME`, else `~/.layerfs`). | [Home](../control/home/README.md) | | 5 | The family function reads the Store and project records, refuses a blocking intent and takes this process's lease on the Store. | [Stores and projects](../control/stores-and-projects/README.md#what-it-does), [Home: the `op` intent](../control/home/README.md#the-op-intent) | diff --git a/docs/architecture/glossary.md b/docs/architecture/glossary.md index 8654b30dc1..0a1703c9d1 100644 --- a/docs/architecture/glossary.md +++ b/docs/architecture/glossary.md @@ -18,7 +18,7 @@ LayerFS (backend, install, scope), the row gives both. | Branch | A named line of Commits in a project, with a base Layer and an optional head Commit. `main` is not a Branch. | [History: records](core/history/README.md#records) | | Bridge | `layerfs-bridge`: the wire contract between a controller and a Workspace daemon: the authenticated channel, every control and SDK record, the daemon's private setup and the Store install records. | [Bridge](engine/bridge/README.md) | | Bucket | A named place the home records where backups are kept, reached through a driver (local folder, MinIO, R2 or S3 API). Drivers know files by name and nothing about Stores. | [Backups: buckets](control/backups/buckets.md) | -| Call table | The 73 calls in 10 families that every front end exposes, with their arguments, and the one dispatcher they all go through. | [Calls](api/calls/README.md), [SDK](api/sdk/README.md) | +| Call table | The 76 calls in 10 families that every front end exposes, with their arguments, and the one dispatcher they all go through. | [Calls](api/calls/README.md), [SDK](api/sdk/README.md) | | Capture | The Commit step that seals a Workspace's active overlay generation as its published frontier and opens the next one. It copies no rows. | [Commit: what it does](engine/commit/README.md#what-it-does) | | Commit | An immutable history record: a complete filesystem root, its parent, the base Layer it was built from, an optional second parent and metadata. Also the call (`workspace.commit`) that makes one from a Workspace. | [History: records](core/history/README.md#records), [Commit](engine/commit/README.md) | | Construction | Building canonical file and tree objects from input and saving them: Init from a native folder, a Commit from its captured generation. A Commit has one construction producer. | [Commit: construction](engine/commit/construction.md), [Project Init: construction](engine/project-init/README.md#construction), [Files: construction](core/files/README.md#construction) | diff --git a/engine/crates/layerfs-bridge/src/control.rs b/engine/crates/layerfs-bridge/src/control.rs index 44a2822f4b..a82f5e6572 100644 --- a/engine/crates/layerfs-bridge/src/control.rs +++ b/engine/crates/layerfs-bridge/src/control.rs @@ -181,7 +181,7 @@ pub use crate::control_sdk::{ }; pub use crate::control_types::{ Activity, Answer, Call, CleanupObservation, ControlCode, ControlRefusal, LocalObservation, - Reply, Request, WorkspaceStatus, WorkspaceToken, HISTORY_WINDOW, + MountPlace, Reply, Request, WorkspaceStatus, WorkspaceToken, HISTORY_WINDOW, }; pub use crate::control_unmount::{DirtyReport, UnmountControl}; diff --git a/engine/crates/layerfs-bridge/src/control_request.rs b/engine/crates/layerfs-bridge/src/control_request.rs index 5c18098636..f49f9efdac 100644 --- a/engine/crates/layerfs-bridge/src/control_request.rs +++ b/engine/crates/layerfs-bridge/src/control_request.rs @@ -1,6 +1,6 @@ //! One correlated bounded control request, never an immutable-content upload. use crate::{ - control::{Call, ControlError, Request, HISTORY_WINDOW}, + control::{Call, ControlError, MountPlace, Request, HISTORY_WINDOW}, control_history::*, wire::{Reader, Writer}, }; @@ -51,6 +51,28 @@ impl Call { out.blob(project.as_bytes())?; out.blob(branch.as_bytes())?; } + Request::MountPlaced { + workspace, + branch, + place, + } => { + out.byte(16)?; + out.put(&workspace.to_bytes())?; + out.put(&branch.to_bytes())?; + put_place(&mut out, place)?; + } + Request::MountNamedPlaced { + workspace, + project, + branch, + place, + } => { + out.byte(17)?; + out.put(&workspace.to_bytes())?; + out.blob(project.as_bytes())?; + out.blob(branch.as_bytes())?; + put_place(&mut out, place)?; + } Request::Sdk(value) => { out.byte(20)?; crate::control_sdk::put_call(&mut out, value)?; @@ -169,6 +191,17 @@ impl Call { project: input.text(NAME_FIELD)?, branch: input.text(NAME_FIELD)?, }, + 16 => Request::MountPlaced { + workspace: history(WorkspaceId::from_authority(input.array()?))?, + branch: history(BranchId::from_bytes(input.array()?))?, + place: place(&mut input)?, + }, + 17 => Request::MountNamedPlaced { + workspace: history(WorkspaceId::from_authority(input.array()?))?, + project: input.text(NAME_FIELD)?, + branch: input.text(NAME_FIELD)?, + place: place(&mut input)?, + }, 2 => Request::Commit(crate::control_merge::commit_control(&mut input)?), 20 => Request::Sdk(crate::control_sdk::call(&mut input)?), 3 => Request::Status(token(&mut input)?), @@ -225,6 +258,38 @@ impl Call { Ok(Self { id, request }) } } +/// Writes the known Sandbox and machine names of one placed mount. +fn put_place(out: &mut Writer, place: &MountPlace) -> Result<(), ControlError> { + let flags = u8::from(place.sandbox.is_some()) | (u8::from(place.machine.is_some()) << 1); + out.byte(flags)?; + if let Some(sandbox) = &place.sandbox { + out.blob(sandbox.as_bytes())?; + } + if let Some(machine) = &place.machine { + out.blob(machine.as_bytes())?; + } + Ok(()) +} + +/// Reads the known Sandbox and machine names of one placed mount. +fn place(input: &mut Reader<'_>) -> Result { + let flags = input.byte()?; + if flags & !0b11 != 0 { + return Err(ControlError("mount place")); + } + let sandbox = if flags & 1 != 0 { + Some(input.text(NAME_FIELD)?) + } else { + None + }; + let machine = if flags & 2 != 0 { + Some(input.text(NAME_FIELD)?) + } else { + None + }; + Ok(MountPlace { sandbox, machine }) +} + fn window(limit: u16) -> Result<(), ControlError> { if limit == 0 || limit > HISTORY_WINDOW { Err(ControlError("history processing window")) diff --git a/engine/crates/layerfs-bridge/src/control_types.rs b/engine/crates/layerfs-bridge/src/control_types.rs index 141beadc5d..c6d6e3aa00 100644 --- a/engine/crates/layerfs-bridge/src/control_types.rs +++ b/engine/crates/layerfs-bridge/src/control_types.rs @@ -13,6 +13,37 @@ pub struct WorkspaceToken { /// Original local namespace returned by the owner; never reused by this daemon. pub namespace: i64, } +/// The Sandbox and machine a mount belongs to, when the caller knows them. +/// The holder report of a live mount shows them beside its Workspace; a +/// caller that knows neither leaves both absent and the report keeps the +/// Workspace alone. +#[derive(Clone, Debug, Default, Eq, PartialEq)] +pub struct MountPlace { + /// The Sandbox the mounting daemon serves, when known. + pub sandbox: Option, + /// The machine that Sandbox runs on, when known. + pub machine: Option, +} + +impl MountPlace { + /// The place a caller names, by the names it knows (`None` when not). + /// An empty name is no name: only a real one is reported. + #[must_use] + pub fn new(sandbox: Option<&str>, machine: Option<&str>) -> Self { + let known = |name: Option<&str>| name.filter(|name| !name.is_empty()).map(str::to_owned); + Self { + sandbox: known(sandbox), + machine: known(machine), + } + } + + /// True when either name is known: a mount then reports what it knows. + #[must_use] + pub fn known(&self) -> bool { + self.sandbox.is_some() || self.machine.is_some() + } +} + /// One explicitly requested control operation. #[derive(Clone, Debug, Eq, PartialEq)] pub enum Request { @@ -58,6 +89,28 @@ pub enum Request { /// The Branch's name in that project, as the caller gave it. branch: String, }, + /// [`Request::Mount`] whose caller knows the Sandbox and machine its + /// daemon serves: a live mount's holders then show all three. + MountPlaced { + /// New authority incarnation. + workspace: WorkspaceId, + /// Selected Branch. + branch: BranchId, + /// The Sandbox and machine the mount belongs to, as known. + place: MountPlace, + }, + /// [`Request::MountNamed`] whose caller knows the Sandbox and machine + /// its daemon serves. + MountNamedPlaced { + /// New authority incarnation. + workspace: WorkspaceId, + /// The project's name, as the caller gave it. + project: String, + /// The Branch's name in that project, as the caller gave it. + branch: String, + /// The Sandbox and machine the mount belongs to, as known. + place: MountPlace, + }, /// One SDK call answered by a value or a typed SDK refusal. Sdk(crate::control_sdk::SdkCall), /// Capture the published frontier, construct it in the daemon, merge it diff --git a/engine/crates/layerfs-bridge/tests/control_records.rs b/engine/crates/layerfs-bridge/tests/control_records.rs index a708864895..7b6aa9cad5 100644 --- a/engine/crates/layerfs-bridge/tests/control_records.rs +++ b/engine/crates/layerfs-bridge/tests/control_records.rs @@ -57,6 +57,19 @@ fn commands_are_bounded_exact_and_reject_every_truncated_prefix() { project: "project".into(), branch: "Not A Name".into(), }, + // #G4: a mount that knows where it runs travels with both names + Request::MountPlaced { + workspace: token.workspace, + branch: binding.branch.id, + place: MountPlace::new(Some("sbx-1"), Some("docker")), + }, + // a name the caller knows alone still travels exactly + Request::MountNamedPlaced { + workspace: token.workspace, + project: "project".into(), + branch: "work".into(), + place: MountPlace::new(None, Some("machine-1")), + }, Request::Commit(CommitControl { token, force: false, diff --git a/engine/crates/layerfs-daemon/src/application/diagnostics.rs b/engine/crates/layerfs-daemon/src/application/diagnostics.rs index 6df30ad60c..68a1af0b41 100644 --- a/engine/crates/layerfs-daemon/src/application/diagnostics.rs +++ b/engine/crates/layerfs-daemon/src/application/diagnostics.rs @@ -397,5 +397,7 @@ fn operation_code(operation: &Request) -> u64 { Request::Cleanup(_) => 13, Request::Sdk(_) => 15, Request::MountNamed { .. } => 16, + Request::MountPlaced { .. } => 17, + Request::MountNamedPlaced { .. } => 18, } } diff --git a/engine/crates/layerfs-daemon/src/application/retained.rs b/engine/crates/layerfs-daemon/src/application/retained.rs index ff7011dd4d..75e24e72fc 100644 --- a/engine/crates/layerfs-daemon/src/application/retained.rs +++ b/engine/crates/layerfs-daemon/src/application/retained.rs @@ -278,6 +278,8 @@ fn kind(request: &layerfs_bridge::control::Request) -> &'static str { match request { Request::Mount { .. } => "mount", Request::MountNamed { .. } => "mount", + Request::MountPlaced { .. } => "mount", + Request::MountNamedPlaced { .. } => "mount", Request::Commit(_) => "commit", Request::Status(_) => "status", Request::Unmount(_) => "unmount", diff --git a/engine/crates/layerfs-daemon/src/control/operations.rs b/engine/crates/layerfs-daemon/src/control/operations.rs index 394d64e5e2..8188165975 100644 --- a/engine/crates/layerfs-daemon/src/control/operations.rs +++ b/engine/crates/layerfs-daemon/src/control/operations.rs @@ -9,7 +9,7 @@ use crate::store::{ CommitError, CommitFailure, CommitOptions, CommitSuccess, NamedBindRequest, }; use layerfs_bridge::control::{ - Activity, ConflictReport, ControlCode, MergedCommit, Reply, Request, WorkspaceToken, + Activity, ConflictReport, ControlCode, MergedCommit, MountPlace, Reply, Request, WorkspaceToken, }; use layerfs_content::filesystem::FilesystemRootId; use layerfs_content::merge::{Conflict, ConflictKind}; @@ -102,9 +102,20 @@ impl Service { workspace: *workspace, branch: *branch, }; - self.mount(BindIntent::Id(request), timing) + self.mount(BindIntent::Id(request), MountPlace::default(), timing) }) } + Request::MountPlaced { + workspace, + branch, + place, + } => crate::telemetry::timed("sandbox.mount.bind", |timing| { + let request = BindRequest { + workspace: *workspace, + branch: *branch, + }; + self.mount(BindIntent::Id(request), place.clone(), timing) + }), Request::MountNamed { workspace, project, @@ -115,7 +126,20 @@ impl Service { project: project.clone(), branch: branch.clone(), }; - self.mount(BindIntent::Named(request), timing) + self.mount(BindIntent::Named(request), MountPlace::default(), timing) + }), + Request::MountNamedPlaced { + workspace, + project, + branch, + place, + } => crate::telemetry::timed("sandbox.mount.bind", |timing| { + let request = NamedBindRequest { + workspace: *workspace, + project: project.clone(), + branch: branch.clone(), + }; + self.mount(BindIntent::Named(request), place.clone(), timing) }), Request::Status(token) => self.status(*token), Request::Cleanup(token) => self.cleanup(*token), @@ -146,6 +170,7 @@ impl Service { pub(crate) fn mount( &self, intent: BindIntent, + place: MountPlace, timing: &layerfs_telemetry::timer::TimingScope<'_, layerfs_telemetry::timer::Active>, ) -> Result { let workspace = intent.workspace(); @@ -177,8 +202,11 @@ impl Service { entries.insert(workspace, Entry::Binding); } let bound = match crate::telemetry::phase(timing, "store.bind", || match intent { - BindIntent::Id(request) => self.store.bind(self.owner.clone(), request), - BindIntent::Named(request) => self.store.bind_named(self.owner.clone(), request), + BindIntent::Id(request) => self.store.bind_placed(self.owner.clone(), request, place), + BindIntent::Named(request) => { + self.store + .bind_named_placed(self.owner.clone(), request, place) + } }) { Ok(value) => value, Err(value) => { diff --git a/engine/crates/layerfs-daemon/tests/mount_holders.rs b/engine/crates/layerfs-daemon/tests/mount_holders.rs new file mode 100644 index 0000000000..a04962a3bb --- /dev/null +++ b/engine/crates/layerfs-daemon/tests/mount_holders.rs @@ -0,0 +1,127 @@ +//! #G4: a daemon mount registers the Sandbox and machine beside its +//! Workspace, and a mount that knows neither still registers the Workspace +//! alone. `MountsActive` reports exactly what the intent placed. +#[allow(dead_code)] +#[path = "support/control_fixture.rs"] +mod fixture; +#[allow(dead_code)] +#[path = "support/host_install.rs"] +mod support; + +use layerfs_bridge::control::{MountPlace, Reply, Request, SdkValue, WorkspaceToken}; +use layerfs_history::{BranchId, ForkRequest, ForkSource, HistoryName, LayerStackId, WorkspaceId}; +use layerfs_store_service::history::{lookup, removal}; + +/// The fixture's Store with a `work` Branch forked from the project's head. +fn work(f: &fixture::Fixture) -> (LayerStackId, BranchId) { + let store = &f.installed.opened.store; + let stack = LayerStackId::from_authority([54; 16]); + let base = store + .history() + .layer_stack(stack) + .unwrap() + .unwrap() + .head_layer; + let branch = BranchId::from_authority([64; 16]); + store + .history() + .fork(&ForkRequest { + stack, + branch, + name: HistoryName::new("work").unwrap(), + source: ForkSource::Layer(base), + }) + .unwrap(); + (stack, branch) +} + +/// Executes one mount request and returns the bound token. +fn bound(f: &fixture::Fixture, request: Request) -> WorkspaceToken { + match f.service.execute_control(&request).unwrap().reply { + Reply::Bound { token, .. } => token, + other => panic!("{other:?}"), + } +} + +/// A `workspace.mount`-shaped named bind that knows its Sandbox and machine. +fn bind_named_placed(f: &fixture::Fixture, tag: u8, place: MountPlace) -> WorkspaceToken { + bound( + f, + Request::MountNamedPlaced { + workspace: WorkspaceId::from_authority([tag; 32]).unwrap(), + project: "project".to_owned(), + branch: "work".to_owned(), + place, + }, + ) +} + +/// A named bind whose caller knows neither the Sandbox nor the machine. +fn bind_named(f: &fixture::Fixture, tag: u8) -> WorkspaceToken { + bound( + f, + Request::MountNamed { + workspace: WorkspaceId::from_authority([tag; 32]).unwrap(), + project: "project".to_owned(), + branch: "work".to_owned(), + }, + ) +} + +fn unmount(f: &fixture::Fixture, token: WorkspaceToken) { + let reply = f + .service + .execute_control(&Request::Unmount(layerfs_bridge::control::UnmountControl { + token, + discard: true, + })) + .unwrap() + .reply; + assert_eq!(reply, Reply::Unmounted(token)); +} + +/// The one holder a live mount leaves in `MountsActive`. +fn holder(f: &fixture::Fixture, stack: &layerfs_history::LayerStackRecord) -> SdkValue { + let refused = removal::remove(&f.installed.opened.store, stack, "work") + .expect_err("the live mount refuses the removal"); + assert_eq!(refused.code, "MountsActive", "{refused:?}"); + let SdkValue::List(holders) = refused.detail.get("holders").expect("holders") else { + panic!("{refused:?}"); + }; + assert_eq!(holders.len(), 1, "{holders:?}"); + holders[0].clone() +} + +/// The fixture project's live stack record, as the removal names it. +fn stack(f: &fixture::Fixture) -> layerfs_history::LayerStackRecord { + lookup::project(&f.installed.opened.store, "project").expect("project") +} + +#[test] +fn a_placed_daemon_mount_registers_sandbox_machine_and_workspace() { + let f = fixture::Fixture::new("g4-mount-place"); + work(&f); + let token = bind_named_placed(&f, 7, MountPlace::new(Some("g4sbx"), Some("docker"))); + let holder = holder(&f, &stack(&f)); + assert_eq!(holder.get_text("kind"), Some("mount")); + assert_eq!(holder.get_text("sandbox"), Some("g4sbx")); + assert_eq!(holder.get_text("machine"), Some("docker")); + let workspace = layerfs_bridge::sdk_values::hex(&[7; 32]); + assert_eq!(holder.get_text("workspace"), Some(workspace.as_str())); + unmount(&f, token); + f.cleanup(); +} + +#[test] +fn a_mount_with_no_known_context_registers_the_workspace_alone() { + let f = fixture::Fixture::new("g4-mount-unknown"); + work(&f); + let token = bind_named(&f, 8); + let holder = holder(&f, &stack(&f)); + assert_eq!(holder.get_text("kind"), Some("mount")); + assert_eq!(holder.get_text("sandbox"), None); + assert_eq!(holder.get_text("machine"), None); + assert!(holder.get_text("workspace").is_some()); + unmount(&f, token); + f.cleanup(); +} diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_all_branch.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_all_branch.sql index 42682b5053..3fb3e03c82 100644 --- a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_all_branch.sql +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_all_branch.sql @@ -4,7 +4,7 @@ FROM gc_intent WHERE state <> 'done' AND ( scope_kind = 'store' - OR ($1 IS NOT NULL AND scope_kind = 'project' AND scope_id = $1) + OR (scope_kind = 'project' AND scope_id = $1) OR (scope_kind = 'branch' AND scope_id = $2) ) AND op_id <> $3; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_all_project.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_all_project.sql index e9b5bdeac6..684af7e2ea 100644 --- a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_all_project.sql +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_all_project.sql @@ -6,7 +6,7 @@ WHERE state <> 'done' scope_kind = 'store' OR (scope_kind = 'project' AND scope_id = $1) OR (scope_kind = 'branch' AND ( - ($2 IS NOT NULL AND project = $2) + (project = $2) OR scope_id IN (SELECT branch_id FROM branch WHERE layer_stack_id = $1) )) ) diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_ops_branch.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_ops_branch.sql index 124e372af9..cfce4edba7 100644 --- a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_ops_branch.sql +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_ops_branch.sql @@ -5,7 +5,7 @@ WHERE state <> 'done' AND kind IN ('removal', 'compaction') AND ( scope_kind = 'store' - OR ($1 IS NOT NULL AND scope_kind = 'project' AND scope_id = $1) + OR (scope_kind = 'project' AND scope_id = $1) OR (scope_kind = 'branch' AND scope_id = $2) ) AND op_id <> $3; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_ops_project.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_ops_project.sql index c427223f56..5ea9c9f72c 100644 --- a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_ops_project.sql +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_ops_project.sql @@ -7,7 +7,7 @@ WHERE state <> 'done' scope_kind = 'store' OR (scope_kind = 'project' AND scope_id = $1) OR (scope_kind = 'branch' AND ( - ($2 IS NOT NULL AND project = $2) + (project = $2) OR scope_id IN (SELECT branch_id FROM branch WHERE layer_stack_id = $1) )) ) diff --git a/engine/crates/layerfs-persistence/src/backend/sqlite/compact.rs b/engine/crates/layerfs-persistence/src/backend/sqlite/compact.rs index 61c3b99aef..5a02a14703 100644 --- a/engine/crates/layerfs-persistence/src/backend/sqlite/compact.rs +++ b/engine/crates/layerfs-persistence/src/backend/sqlite/compact.rs @@ -22,6 +22,9 @@ use super::schema; use super::session::connection::{Session, SqlWork}; use super::session::rows; use crate::backend::records::BackendError; +use crate::compact_metrics::{ + self, CompactOutcome, CompactPhase, CompactRefusal, CompactRunObservation, +}; use crate::{KeptWaste, MarkResult, SqliteHandles}; use layerfs_content::ObjectId; use layerfs_history::error::{HistoryError, HistoryResult}; @@ -33,7 +36,7 @@ use std::cell::RefCell; use std::collections::BTreeMap; use std::path::{Path, PathBuf}; use std::sync::Arc; -use std::time::{SystemTime, UNIX_EPOCH}; +use std::time::{Instant, SystemTime, UNIX_EPOCH}; /// The sidecar record suffix (§11: SQLite keeps its phase outside the sealed /// database). @@ -1461,6 +1464,7 @@ fn settle_leftover( history: &crate::HistoryProvider, store: &Path, _generation: u64, + metrics: &mut RunMetrics, ) -> HistoryResult<()> { let Some(op) = RunOp::read(store) else { if artifact_paths(store) @@ -1482,6 +1486,7 @@ fn settle_leftover( if std::fs::symlink_metadata(op_path(store)).is_ok() { std::fs::remove_file(op_path(store)).map_err(io_error)?; } + metrics.leftover_settled = true; Ok(()) } @@ -1660,9 +1665,21 @@ impl SqliteHandles { /// directory-fsync failure is installed-but-uncertain: the new file and the /// op record are kept for the next `store.compact` to judge (§9). pub fn compact(self, request: &CompactRequest) -> HistoryResult { + let mut metrics = RunMetrics::start(); + let result = self.compact_measured(request, &mut metrics); + metrics.finish(&result); + result + } + + /// The measured body of [`Self::compact`]; `metrics` observes it. + fn compact_measured( + self, + request: &CompactRequest, + metrics: &mut RunMetrics, + ) -> HistoryResult { #[cfg(not(any(target_os = "linux", target_os = "macos")))] { - let _ = request; + let _ = (request, metrics); return Err(HistoryError::Unsupported("SQLite Store compaction")); } #[cfg(any(target_os = "linux", target_os = "macos"))] @@ -1689,7 +1706,8 @@ impl SqliteHandles { let live = live_tuple(&session)?; let generation = u64::try_from(live.generation) .map_err(|_| HistoryError::Integrity("Store generation"))?; - settle_leftover(&history, &store, generation)?; + metrics.generation_before = generation; + settle_leftover(&history, &store, generation, metrics)?; let op_id = request.op_id; let mut op = RunOp { @@ -1720,6 +1738,7 @@ impl SqliteHandles { // admitted sequence. A definite failure here releases the intent // before the artifact set and the op record go, so the Store is // left exactly as it was and no later call meets BusyOp. + metrics.begin_phase(CompactPhase::Mark); let admitted = (|| -> HistoryResult<(MarkResult, MarkTuple, u64, u64, CompactKeptWaste, u64)> { let mark = history.mark()?; @@ -1750,6 +1769,7 @@ impl SqliteHandles { } }; let rebuild = total > 0 && dead.saturating_mul(10) >= total; + metrics.end_phase(); if !rebuild { // §3 `none`: mark only. The intent is cleared and the op record @@ -1836,6 +1856,7 @@ impl SqliteHandles { } stop_at(request, CompactFailpoint::AfterSeal, &op, &store)?; + metrics.begin_phase(CompactPhase::Build); op.phase = "build".to_owned(); op.write(&store)?; let capacity = request.failpoint == Some(CompactFailpoint::CapacityAtBuild); @@ -1861,7 +1882,9 @@ impl SqliteHandles { }; stop_at(request, CompactFailpoint::AfterBuild, &op, &store)?; stop_at(request, CompactFailpoint::AfterWalSwitch, &op, &store)?; + metrics.end_phase(); + metrics.begin_phase(CompactPhase::Verify); op.phase = "verify".to_owned(); if let Err(error) = op.write(&store) { abort_before_install(&store); @@ -1884,7 +1907,9 @@ impl SqliteHandles { return Err(error); } stop_at(request, CompactFailpoint::AfterVerify, &op, &store)?; + metrics.end_phase(); + metrics.begin_phase(CompactPhase::Install); if let Some(hook) = request.before_install_hook { hook(&facts.path); } @@ -1940,6 +1965,106 @@ impl SqliteHandles { } } +/// The phase clock and §11 values one measured `compact` run observes. +struct RunMetrics { + started: Instant, + phase: Option<(CompactPhase, Instant)>, + phase_nanos: Vec<(CompactPhase, u64)>, + generation_before: u64, + generation_after: u64, + dead_bytes_bound: u64, + dead_bytes_refined: u64, + kept_waste: CompactKeptWaste, + residue_bytes: u64, + leftover_settled: bool, +} + +impl RunMetrics { + fn start() -> Self { + Self { + started: Instant::now(), + phase: None, + phase_nanos: Vec::new(), + generation_before: 0, + generation_after: 0, + dead_bytes_bound: 0, + dead_bytes_refined: 0, + kept_waste: CompactKeptWaste::default(), + residue_bytes: 0, + leftover_settled: false, + } + } + + /// Ends the current phase and starts `phase`; a phase is inclusive wall + /// time, never an exclusive CPU decomposition. + fn begin_phase(&mut self, phase: CompactPhase) { + self.end_phase(); + self.phase = Some((phase, Instant::now())); + } + + fn end_phase(&mut self) { + if let Some((phase, started)) = self.phase.take() { + self.phase_nanos.push(( + phase, + u64::try_from(started.elapsed().as_nanos()).unwrap_or(u64::MAX), + )); + } + } + + /// Records this run once, whatever its result. The outcome and refusal + /// come from the typed error, so a `Busy`/`Unresolved` refusal is counted + /// without changing the error the caller receives. + fn finish(mut self, result: &HistoryResult) { + self.end_phase(); + let total_nanos = + u64::try_from(self.started.elapsed().as_nanos()).unwrap_or(u64::MAX); + let (outcome, refusal) = match result { + Ok(receipt) => { + self.generation_after = receipt.generation_after; + self.dead_bytes_bound = receipt.dead_bytes_bound; + self.dead_bytes_refined = receipt.dead_bytes_refined; + self.kept_waste = receipt.kept_waste.clone(); + self.residue_bytes = receipt.residue.bytes; + let outcome = match receipt.path { + CompactPath::Rebuild => CompactOutcome::Rebuild, + CompactPath::None => CompactOutcome::None, + }; + (outcome, None) + } + Err(error) => { + if !error.unknown() { + self.generation_after = self.generation_before; + } + ( + if error.unknown() { + CompactOutcome::Uncertain + } else { + CompactOutcome::Failed + }, + match error { + HistoryError::Busy => Some(CompactRefusal::Busy), + HistoryError::Unresolved(_) => Some(CompactRefusal::Unresolved), + _ => None, + }, + ) + } + }; + compact_metrics::record_run(&CompactRunObservation { + outcome, + generation_before: self.generation_before, + generation_after: self.generation_after, + dead_bytes_bound: self.dead_bytes_bound, + dead_bytes_refined: self.dead_bytes_refined, + kept_waste: self.kept_waste, + residue_bytes: self.residue_bytes, + phase_nanos: self.phase_nanos, + total_nanos, + leftover_settled: self.leftover_settled, + refusal, + }); + } +} + #[cfg(test)] mod tests { use super::io_error; diff --git a/engine/crates/layerfs-persistence/src/compact_metrics.rs b/engine/crates/layerfs-persistence/src/compact_metrics.rs new file mode 100644 index 0000000000..c46246c63c --- /dev/null +++ b/engine/crates/layerfs-persistence/src/compact_metrics.rs @@ -0,0 +1,559 @@ +//! Bounded metrics and SLO signals for SQLite Store compaction. +//! +//! Every metric a real `store.compact` or `store.status` path records goes +//! through this module. Label values come from closed enums ([`CompactOutcome`], +//! [`CompactPhase`], [`CompactRefusal`], [`CompactStatusState`]), so the metric +//! cardinality is fixed: no Store name, path, operation id or artifact name is +//! ever a label. A finished run is observed once, in [`record_run`], and +//! recording never changes its result. +//! +//! Production reads the process totals through [`snapshot`]. A test or a +//! diagnostic probe can capture only its own thread with +//! [`CompactMetricsCapture`], so concurrent work on other threads does not +//! pollute the observation. + +use crate::backend::sqlite::compact::CompactKeptWaste; +use std::cell::RefCell; +use std::collections::BTreeMap; +use std::sync::{Mutex, OnceLock}; + +/// The outcome of one SQLite compaction call. +#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)] +pub enum CompactOutcome { + /// A rebuild installed at `G -> G + 1`. + Rebuild, + /// The `none` path: mark only, generation unchanged. + None, + /// A definite failure that left the live Store unchanged. + Failed, + /// A failed or stopped run whose persistence outcome is unknown (§9). + Uncertain, +} + +impl CompactOutcome { + /// The bounded `outcome` label value. + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Rebuild => "rebuild", + Self::None => "none", + Self::Failed => "failed", + Self::Uncertain => "uncertain", + } + } +} + +/// One SQLite phase a run may time (§11: `mark`, `build`, `verify`, `install`). +#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)] +pub enum CompactPhase { + /// The §7 step 1 mark and the wholly-dead-pack decision. + Mark, + /// The staged rebuild's build. + Build, + /// The immutable verification. + Verify, + /// The install and its settle. + Install, +} + +impl CompactPhase { + /// The bounded `phase` label value. + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Mark => "mark", + Self::Build => "build", + Self::Verify => "verify", + Self::Install => "install", + } + } +} + +/// A refusal that stops a compaction before or during its admission. +#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)] +pub enum CompactRefusal { + /// A live operation, writer or opener holds the Store. + Busy, + /// A dead or uncertain owner left an operation unresolved. + Unresolved, +} + +impl CompactRefusal { + /// The bounded `code` label value. + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Busy => "busy", + Self::Unresolved => "unresolved", + } + } +} + +/// The compaction state `store.status` reads from an unsettled op record. +#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)] +pub enum CompactStatusState { + /// The owning process still lives. + Busy, + /// The recording owner is gone, so the outcome is unresolved. + Unresolved, +} + +impl CompactStatusState { + /// The bounded `state` label value. + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Busy => "busy", + Self::Unresolved => "unresolved", + } + } +} + +/// An SLO objective one finished run evaluates. +#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)] +pub enum CompactSloObjective { + /// A successful settle left no artifact and zero residue bytes. + ResidueFree, + /// A rebuild advanced exactly one generation; `none` kept it. + Generation, +} + +impl CompactSloObjective { + /// The bounded `objective` label value. + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::ResidueFree => "residue_free", + Self::Generation => "generation", + } + } +} + +/// One SLO check's result. +#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)] +pub enum CompactSloResult { + /// The run met the objective. + Pass, + /// The run missed the objective. + Fail, +} + +impl CompactSloResult { + /// The bounded `result` label value. + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Pass => "pass", + Self::Fail => "fail", + } + } +} + +/// A duration aggregate: how many observations, their sum and their maximum, +/// all in nanoseconds. +#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)] +pub struct DurationStat { + /// Observations counted. + pub count: u64, + /// Saturating sum of the observations. + pub sum_ns: u64, + /// The longest observation. + pub max_ns: u64, +} + +impl DurationStat { + fn observe(&mut self, nanos: u64) { + self.count = self.count.saturating_add(1); + self.sum_ns = self.sum_ns.saturating_add(nanos); + self.max_ns = self.max_ns.max(nanos); + } +} + +/// Everything one finished compaction run reports to the metrics. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct CompactRunObservation { + /// The run's outcome. + pub outcome: CompactOutcome, + /// The generation the mark ran at. + pub generation_before: u64, + /// The generation the run left; equal on `none` and on a failure. + pub generation_after: u64, + /// §11 `deadBytesBound`. + pub dead_bytes_bound: u64, + /// §11 `deadBytesRefined`. + pub dead_bytes_refined: u64, + /// §11 `keptWaste`, whose delta-base references are not labels. + pub kept_waste: CompactKeptWaste, + /// §11 `residue.bytes`. + pub residue_bytes: u64, + /// The completed phases and their inclusive durations. + pub phase_nanos: Vec<(CompactPhase, u64)>, + /// The run's whole duration. + pub total_nanos: u64, + /// Whether this run settled an earlier run's leftover record. + pub leftover_settled: bool, + /// The admission refusal, when the run was refused. + pub refusal: Option, +} + +/// One rendered metric sample: a stable name, bounded label pairs, a value. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct MetricSample { + /// The metric name, for example `compact.operations`. + pub name: &'static str, + /// The bounded label pairs, in sorted key order. + pub labels: Vec<(&'static str, &'static str)>, + /// The sample's counter or gauge value. + pub value: u64, +} + +impl MetricSample { + /// The value of label `key`, when the sample carries it. + #[must_use] + pub fn label(&self, key: &str) -> Option<&'static str> { + self.labels + .iter() + .find(|(name, _)| *name == key) + .map(|(_, value)| *value) + } +} + +/// The last successful run's §11 gauges, the values a report names. +#[derive(Clone, Debug, Eq, PartialEq)] +struct LastRun { + generation_before: u64, + generation_after: u64, + dead_bytes_bound: u64, + dead_bytes_refined: u64, + kept_waste: CompactKeptWaste, + residue_bytes: u64, +} + +/// One process's compaction metric totals. +#[derive(Clone, Debug, Default, Eq, PartialEq)] +pub struct CompactMetrics { + runs: u64, + outcomes: BTreeMap<&'static str, u64>, + refusals: BTreeMap<&'static str, u64>, + settles: BTreeMap<&'static str, u64>, + retries: BTreeMap<&'static str, u64>, + statuses: BTreeMap<&'static str, u64>, + slo: BTreeMap<(&'static str, &'static str), u64>, + phases: BTreeMap<&'static str, DurationStat>, + duration: DurationStat, + last: Option, +} + +impl CompactMetrics { + /// Adds one finished run. + fn observe(&mut self, run: &CompactRunObservation) { + self.runs = self.runs.saturating_add(1); + increment(&mut self.outcomes, run.outcome.as_str()); + if let Some(refusal) = run.refusal { + increment(&mut self.refusals, refusal.as_str()); + } + if run.leftover_settled { + increment(&mut self.settles, "leftover"); + increment(&mut self.retries, "leftover"); + } + for (phase, nanos) in &run.phase_nanos { + self.phases + .entry(phase.as_str()) + .or_default() + .observe(*nanos); + } + self.duration.observe(run.total_nanos); + if !matches!(run.outcome, CompactOutcome::Rebuild | CompactOutcome::None) { + return; + } + increment(&mut self.settles, "run"); + let generation = match run.outcome { + CompactOutcome::Rebuild => { + run.generation_after == run.generation_before.saturating_add(1) + } + CompactOutcome::None => run.generation_after == run.generation_before, + CompactOutcome::Failed | CompactOutcome::Uncertain => false, + }; + increment_pair( + &mut self.slo, + ( + CompactSloObjective::Generation.as_str(), + if generation { + CompactSloResult::Pass.as_str() + } else { + CompactSloResult::Fail.as_str() + }, + ), + ); + increment_pair( + &mut self.slo, + ( + CompactSloObjective::ResidueFree.as_str(), + if run.residue_bytes == 0 { + CompactSloResult::Pass.as_str() + } else { + CompactSloResult::Fail.as_str() + }, + ), + ); + self.last = Some(LastRun { + generation_before: run.generation_before, + generation_after: run.generation_after, + dead_bytes_bound: run.dead_bytes_bound, + dead_bytes_refined: run.dead_bytes_refined, + kept_waste: run.kept_waste.clone(), + residue_bytes: run.residue_bytes, + }); + } + + /// Adds one refusal that stopped a call before a run could be observed. + fn observe_refusal(&mut self, refusal: CompactRefusal) { + increment(&mut self.refusals, refusal.as_str()); + } + + /// Adds one `store.status` read of an unsettled compaction record. + fn observe_status(&mut self, state: CompactStatusState) { + increment(&mut self.statuses, state.as_str()); + } + + /// Every sample this process or capture holds, in stable order. + /// + /// Counters are cumulative since the process started (or the capture + /// started); the gauges are the last successful run's report values. + #[must_use] + pub fn samples(&self) -> Vec { + let mut samples = Vec::new(); + samples.push(sample("compact.runs", &[], self.runs)); + for (outcome, value) in &self.outcomes { + samples.push(sample( + "compact.operations", + &[("outcome", *outcome)], + *value, + )); + } + for (code, value) in &self.refusals { + samples.push(sample("compact.refusals", &[("code", *code)], *value)); + } + for (kind, value) in &self.settles { + samples.push(sample("compact.settles", &[("kind", *kind)], *value)); + } + for (reason, value) in &self.retries { + samples.push(sample("compact.retries", &[("reason", *reason)], *value)); + } + for (state, value) in &self.statuses { + samples.push(sample("compact.status", &[("state", *state)], *value)); + } + for ((objective, result), value) in &self.slo { + samples.push(sample( + "compact.slo", + &[("objective", *objective), ("result", *result)], + *value, + )); + } + for (phase, stat) in &self.phases { + for (statistic, value) in [ + ("count", stat.count), + ("sum", stat.sum_ns), + ("max", stat.max_ns), + ] { + samples.push(sample( + "compact.phase.duration_ns", + &[("phase", *phase), ("statistic", statistic)], + value, + )); + } + } + for (statistic, value) in [ + ("count", self.duration.count), + ("sum", self.duration.sum_ns), + ("max", self.duration.max_ns), + ] { + samples.push(sample( + "compact.duration_ns", + &[("statistic", statistic)], + value, + )); + } + if let Some(last) = &self.last { + samples.push(sample( + "compact.dead_bytes", + &[("kind", "bound")], + last.dead_bytes_bound, + )); + samples.push(sample( + "compact.dead_bytes", + &[("kind", "refined")], + last.dead_bytes_refined, + )); + samples.push(sample( + "compact.kept_waste", + &[("part", "dead_in_retained_packs")], + last.kept_waste.dead_in_retained_packs_bytes, + )); + samples.push(sample( + "compact.kept_waste", + &[("part", "delta_bases")], + last.kept_waste.delta_bases_bytes, + )); + samples.push(sample( + "compact.kept_waste", + &[("part", "inode_blocks")], + last.kept_waste.inode_blocks_bytes, + )); + samples.push(sample( + "compact.kept_waste_bytes", + &[], + last.kept_waste + .dead_in_retained_packs_bytes + .saturating_add(last.kept_waste.delta_bases_bytes) + .saturating_add(last.kept_waste.inode_blocks_bytes), + )); + samples.push(sample("compact.residue_bytes", &[], last.residue_bytes)); + samples.push(sample( + "compact.generation", + &[("which", "before")], + last.generation_before, + )); + samples.push(sample( + "compact.generation", + &[("which", "after")], + last.generation_after, + )); + } + samples + } +} + +fn increment(map: &mut BTreeMap<&'static str, u64>, key: &'static str) { + let value = map.entry(key).or_insert(0); + *value = value.saturating_add(1); +} + +fn increment_pair( + map: &mut BTreeMap<(&'static str, &'static str), u64>, + key: (&'static str, &'static str), +) { + let value = map.entry(key).or_insert(0); + *value = value.saturating_add(1); +} + +fn sample(name: &'static str, labels: &[(&'static str, &'static str)], value: u64) -> MetricSample { + MetricSample { + name, + labels: labels.to_vec(), + value, + } +} + +thread_local! { + /// This thread's armed capture, if any. + static CAPTURE: RefCell> = const { RefCell::new(None) }; +} + +fn registry() -> &'static Mutex { + static METRICS: OnceLock> = OnceLock::new(); + METRICS.get_or_init(|| Mutex::new(CompactMetrics::default())) +} + +/// Records one finished compaction run in the process totals and, when this +/// thread has an armed [`CompactMetricsCapture`], in that capture too. +pub fn record_run(run: &CompactRunObservation) { + registry() + .lock() + .unwrap_or_else(|poison| poison.into_inner()) + .observe(run); + CAPTURE.with_borrow_mut(|capture| { + if let Some(metrics) = capture.as_mut() { + metrics.observe(run); + } + }); +} + +/// Records one admission refusal that stopped a call before any run. +pub fn record_refusal(refusal: CompactRefusal) { + registry() + .lock() + .unwrap_or_else(|poison| poison.into_inner()) + .observe_refusal(refusal); + CAPTURE.with_borrow_mut(|capture| { + if let Some(metrics) = capture.as_mut() { + metrics.observe_refusal(refusal); + } + }); +} + +/// Records one `store.status` read of an unsettled compaction record. +pub fn record_status(state: CompactStatusState) { + registry() + .lock() + .unwrap_or_else(|poison| poison.into_inner()) + .observe_status(state); + CAPTURE.with_borrow_mut(|capture| { + if let Some(metrics) = capture.as_mut() { + metrics.observe_status(state); + } + }); +} + +/// The process's cumulative compaction metrics. +#[must_use] +pub fn snapshot() -> CompactMetrics { + registry() + .lock() + .unwrap_or_else(|poison| poison.into_inner()) + .clone() +} + +/// Clears the process's cumulative compaction metrics. +pub fn reset() { + *registry() + .lock() + .unwrap_or_else(|poison| poison.into_inner()) = CompactMetrics::default(); +} + +/// Captures the metrics this thread records, leaving the process totals alone. +/// +/// Build one with [`Self::start`], run the compaction or status call on the +/// same thread, and read [`Self::finish`]. A capture nests: starting another +/// restores the outer one when it finishes, and a dropped capture restores it +/// too. +pub struct CompactMetricsCapture { + previous: Option, + finished: bool, +} + +impl CompactMetricsCapture { + /// Arms a capture on this thread, replacing (and saving) an outer one. + #[must_use] + pub fn start() -> Self { + let previous = + CAPTURE.with_borrow_mut(|capture| capture.replace(CompactMetrics::default())); + Self { + previous, + finished: false, + } + } + + /// The metrics this thread has recorded since the capture started. + #[must_use] + pub fn snapshot(&self) -> CompactMetrics { + CAPTURE.with_borrow(Clone::clone).unwrap_or_default() + } + + /// Ends the capture, restoring the outer one, and returns its metrics. + #[must_use] + pub fn finish(mut self) -> CompactMetrics { + let metrics = self.snapshot(); + self.finished = true; + CAPTURE.with_borrow_mut(|capture| *capture = self.previous.take()); + metrics + } +} + +impl Drop for CompactMetricsCapture { + fn drop(&mut self) { + if !self.finished { + CAPTURE.with_borrow_mut(|capture| *capture = self.previous.take()); + } + } +} diff --git a/engine/crates/layerfs-persistence/src/history/catalog.rs b/engine/crates/layerfs-persistence/src/history/catalog.rs index f4cb1cf748..64d01cc814 100644 --- a/engine/crates/layerfs-persistence/src/history/catalog.rs +++ b/engine/crates/layerfs-persistence/src/history/catalog.rs @@ -59,10 +59,23 @@ impl HistoryCatalog for HistoryProvider { self.read_statement(|tx| layerstack::layer_stack_named(tx, name)) } + // The collision statement reads the retired/deleted holder on purpose. + fn layer_stack_name_taken( + &self, + name: &HistoryName, + ) -> HistoryResult> { + self.read(|tx| layerstack::name_taken(tx, name)) + } + fn branch(&self, id: BranchId) -> HistoryResult> { self.read(|tx| branch::branch(tx, id)) } + // One statement, no visibility filter: rendering keeps a retired Branch. + fn branch_any(&self, id: BranchId) -> HistoryResult> { + self.read_statement(|tx| branch::branch_any(tx, id)) + } + fn branch_named( &self, stack: LayerStackId, diff --git a/engine/crates/layerfs-persistence/src/lib.rs b/engine/crates/layerfs-persistence/src/lib.rs index fe158ec820..0f555b7211 100644 --- a/engine/crates/layerfs-persistence/src/lib.rs +++ b/engine/crates/layerfs-persistence/src/lib.rs @@ -3,6 +3,7 @@ #![deny(unsafe_code)] #![deny(missing_docs)] mod backend; +pub mod compact_metrics; pub mod diagnostic; mod storage; mod store; diff --git a/engine/crates/layerfs-persistence/tests/compact_metrics.rs b/engine/crates/layerfs-persistence/tests/compact_metrics.rs new file mode 100644 index 0000000000..621fcfb8e6 --- /dev/null +++ b/engine/crates/layerfs-persistence/tests/compact_metrics.rs @@ -0,0 +1,448 @@ +//! T10.3: the bounded metrics a real `store.compact` path records. +//! +//! The three observations are a successful rebuild, the `none` path and the +//! leftover a stopped run leaves for the next call. The capture is +//! thread-local, so the other tests in this binary cannot pollute it. +#![cfg(any(target_os = "macos", target_os = "linux"))] +mod support; + +use layerfs_content::{encode_whole_file_payload, FinalizedObject, ObjectId, ObjectRole}; +use layerfs_history::HistoryError; +use layerfs_persistence::compact_metrics::{CompactMetrics, CompactMetricsCapture}; +use layerfs_persistence::{ + CompactFailpoint, CompactPath, CompactRequest, PersistenceConfig, SqliteHandles, + SqlitePersistenceProfile, +}; +use layerfs_storage::{Storage, StoragePolicy}; +use std::path::{Path, PathBuf}; +use support::Temp; + +const BINDING: &[u8] = b"sqlite-compact-metrics-test-binding"; + +fn create_store() -> (Temp, SqliteHandles, PathBuf) { + let temp = Temp::new("sqlite-compact-metrics"); + let path = temp.join("store.sqlite"); + let handles = SqliteHandles::create( + PersistenceConfig::sqlite(path.clone()) + .with_sqlite_profile(SqlitePersistenceProfile::Disposable), + StoragePolicy::frozen_default(), + &layerfs_history::HistoryCatalogConfig { + binding_key: BINDING.to_vec(), + cursor_key: [71; 32], + incarnation: 7, + }, + ) + .unwrap(); + (temp, handles, path) +} + +fn reopen(path: &Path) -> SqliteHandles { + SqliteHandles::open_writable( + PersistenceConfig::sqlite(path.to_path_buf()) + .with_sqlite_profile(SqlitePersistenceProfile::Disposable), + BINDING, + [71; 32], + ) + .unwrap() +} + +fn request(op: u8) -> CompactRequest { + CompactRequest { + op_id: [op; 16], + ..CompactRequest::default() + } +} + +fn request_at(op: u8, failpoint: CompactFailpoint) -> CompactRequest { + CompactRequest { + op_id: [op; 16], + failpoint: Some(failpoint), + ..CompactRequest::default() + } +} + +fn compact_path(store: &Path) -> PathBuf { + let mut name = store.as_os_str().to_os_string(); + name.push(".compact"); + PathBuf::from(name) +} + +fn whole_file(handles: &SqliteHandles, bytes: &[u8]) -> ObjectId { + let object = FinalizedObject::new( + ObjectRole::WholeFile, + encode_whole_file_payload(bytes).unwrap(), + ) + .unwrap(); + let storage = Storage::new(handles.storage.clone()).unwrap(); + let save = storage.begin_save().unwrap(); + save.accept(object.clone()).unwrap(); + save.finish().unwrap(); + object.id() +} + +/// The value of one sample, or `None` when this run did not emit it. +fn metric(metrics: &CompactMetrics, name: &str, labels: &[(&str, &str)]) -> Option { + metrics + .samples() + .into_iter() + .find(|sample| { + sample.name == name + && labels + .iter() + .all(|(key, value)| sample.label(key) == Some(*value)) + }) + .map(|sample| sample.value) +} + +fn value(metrics: &CompactMetrics, name: &str, labels: &[(&str, &str)]) -> u64 { + metric(metrics, name, labels).unwrap_or_else(|| { + panic!( + "no sample {name} {labels:?}; emitted: {:?}", + metrics.samples() + ) + }) +} + +/// Bounded cardinality: every label key is a closed dimension and every value +/// is one the enums name, never a Store name, path, operation id or artifact. +fn assert_bounded(metrics: &CompactMetrics) { + let keys = [ + "outcome", + "code", + "kind", + "reason", + "state", + "objective", + "result", + "phase", + "statistic", + "which", + "part", + ]; + let values = [ + "rebuild", + "none", + "failed", + "uncertain", + "busy", + "unresolved", + "mark", + "build", + "verify", + "install", + "run", + "leftover", + "count", + "sum", + "max", + "before", + "after", + "bound", + "refined", + "dead_in_retained_packs", + "delta_bases", + "inode_blocks", + "residue_free", + "generation", + "pass", + "fail", + ]; + for sample in metrics.samples() { + for (key, label) in &sample.labels { + assert!(keys.contains(key), "non-closed label key {key}"); + assert!( + values.contains(label), + "non-closed label value {label} for {key}" + ); + } + } +} + +#[test] +fn a_successful_rebuild_emits_phases_outcome_and_report_gauges() { + let (_temp, handles, path) = create_store(); + let _dead = whole_file(&handles, b"a pack no retained root reaches"); + let capture = CompactMetricsCapture::start(); + let receipt = handles.compact(&request(40)).unwrap(); + let metrics = capture.finish(); + + assert_eq!(receipt.path, CompactPath::Rebuild, "the dead pack rebuilds"); + assert_bounded(&metrics); + assert_eq!(value(&metrics, "compact.runs", &[]), 1); + assert_eq!( + value(&metrics, "compact.operations", &[("outcome", "rebuild")]), + 1 + ); + for phase in ["mark", "build", "verify", "install"] { + assert_eq!( + value( + &metrics, + "compact.phase.duration_ns", + &[("phase", phase), ("statistic", "count")] + ), + 1, + "{phase} was timed once" + ); + assert!( + value( + &metrics, + "compact.phase.duration_ns", + &[("phase", phase), ("statistic", "sum")] + ) > 0, + "{phase} took time" + ); + assert!( + value( + &metrics, + "compact.phase.duration_ns", + &[("phase", phase), ("statistic", "max")] + ) > 0, + "{phase} has a duration" + ); + } + assert_eq!( + value(&metrics, "compact.duration_ns", &[("statistic", "count")]), + 1 + ); + assert!( + value(&metrics, "compact.duration_ns", &[("statistic", "sum")]) > 0, + "the run took time" + ); + assert_eq!( + value(&metrics, "compact.dead_bytes", &[("kind", "bound")]), + receipt.dead_bytes_bound + ); + assert_eq!( + value(&metrics, "compact.dead_bytes", &[("kind", "refined")]), + receipt.dead_bytes_refined + ); + let kept = receipt + .kept_waste + .dead_in_retained_packs_bytes + .saturating_add(receipt.kept_waste.delta_bases_bytes) + .saturating_add(receipt.kept_waste.inode_blocks_bytes); + assert_eq!(value(&metrics, "compact.kept_waste_bytes", &[]), kept); + assert_eq!( + value(&metrics, "compact.residue_bytes", &[]), + receipt.residue.bytes, + "a successful settle leaves no residue" + ); + assert_eq!( + value(&metrics, "compact.generation", &[("which", "before")]), + receipt.generation_before + ); + assert_eq!( + value(&metrics, "compact.generation", &[("which", "after")]), + receipt.generation_after + ); + assert_eq!( + value( + &metrics, + "compact.slo", + &[("objective", "residue_free"), ("result", "pass")] + ), + 1 + ); + assert_eq!( + value( + &metrics, + "compact.slo", + &[("objective", "generation"), ("result", "pass")] + ), + 1 + ); + assert_eq!(value(&metrics, "compact.settles", &[("kind", "run")]), 1); + assert_eq!( + metric(&metrics, "compact.retries", &[("reason", "leftover")]), + None + ); + + let reopened = reopen(&path); + clean(&reopened); +} + +#[test] +fn the_none_path_emits_only_the_mark_phase_and_keeps_the_generation() { + let (_temp, handles, path) = create_store(); + let capture = CompactMetricsCapture::start(); + let receipt = handles.compact(&request(41)).unwrap(); + let metrics = capture.finish(); + + assert_eq!(receipt.path, CompactPath::None); + assert_bounded(&metrics); + assert_eq!(value(&metrics, "compact.runs", &[]), 1); + assert_eq!( + value(&metrics, "compact.operations", &[("outcome", "none")]), + 1 + ); + assert_eq!( + value( + &metrics, + "compact.phase.duration_ns", + &[("phase", "mark"), ("statistic", "count")] + ), + 1 + ); + for phase in ["build", "verify", "install"] { + assert_eq!( + metric( + &metrics, + "compact.phase.duration_ns", + &[("phase", phase), ("statistic", "count")] + ), + None, + "the none path never enters {phase}" + ); + } + assert_eq!( + value(&metrics, "compact.dead_bytes", &[("kind", "bound")]), + receipt.dead_bytes_bound + ); + assert_eq!( + value(&metrics, "compact.dead_bytes", &[("kind", "refined")]), + receipt.dead_bytes_refined + ); + assert_eq!( + value(&metrics, "compact.residue_bytes", &[]), + 0, + "none leaves no artifact" + ); + assert_eq!( + value(&metrics, "compact.generation", &[("which", "before")]), + receipt.generation_before + ); + assert_eq!( + value(&metrics, "compact.generation", &[("which", "after")]), + receipt.generation_after, + "none keeps the generation" + ); + assert_eq!( + value( + &metrics, + "compact.slo", + &[("objective", "generation"), ("result", "pass")] + ), + 1 + ); + + let reopened = reopen(&path); + clean(&reopened); +} + +#[test] +fn a_stopped_run_then_the_leftover_settle_emits_failure_retry_and_settle_metrics() { + let (_temp, handles, path) = create_store(); + let _dead = whole_file(&handles, b"a pack no retained root reaches"); + + let capture = CompactMetricsCapture::start(); + let error = handles + .compact(&request_at(42, CompactFailpoint::AfterBuild)) + .unwrap_err(); + let stopped = capture.finish(); + assert!(matches!(error, HistoryError::UnknownOutcome), "{error:?}"); + assert_bounded(&stopped); + assert_eq!(value(&stopped, "compact.runs", &[]), 1); + assert_eq!( + value(&stopped, "compact.operations", &[("outcome", "uncertain")]), + 1, + "a stop point leaves an unknown outcome" + ); + for phase in ["mark", "build"] { + assert_eq!( + value( + &stopped, + "compact.phase.duration_ns", + &[("phase", phase), ("statistic", "count")] + ), + 1, + "the stopped run reached {phase}" + ); + } + assert_eq!( + metric(&stopped, "compact.generation", &[("which", "after")]), + None, + "an unknown outcome publishes no report gauge" + ); + assert_eq!( + metric(&stopped, "compact.settles", &[("kind", "leftover")]), + None, + "the stopped run settles no leftover" + ); + + let capture = CompactMetricsCapture::start(); + let reopened = reopen(&path); + let receipt = reopened.compact(&request(43)).unwrap(); + let settled = capture.finish(); + assert_eq!(receipt.path, CompactPath::Rebuild); + assert_bounded(&settled); + assert_eq!( + value(&settled, "compact.operations", &[("outcome", "rebuild")]), + 1 + ); + assert_eq!( + value(&settled, "compact.retries", &[("reason", "leftover")]), + 1 + ); + assert_eq!( + value(&settled, "compact.settles", &[("kind", "leftover")]), + 1 + ); + assert_eq!(value(&settled, "compact.settles", &[("kind", "run")]), 1); + assert_eq!(value(&settled, "compact.residue_bytes", &[]), 0); + + let final_handles = reopen(&path); + clean(&final_handles); +} + +#[test] +fn a_definite_failure_emits_a_failed_outcome_without_report_gauges() { + let (_temp, handles, path) = create_store(); + // A stray artifact no record names makes settle_leftover refuse, before + // the mark: a definite failure, not an unknown outcome. + std::fs::write(compact_path(&path), b"stray").unwrap(); + let capture = CompactMetricsCapture::start(); + let error = handles.compact(&request(44)).unwrap_err(); + let metrics = capture.finish(); + assert!(matches!(error, HistoryError::Exists(_)), "{error:?}"); + assert_bounded(&metrics); + assert_eq!(value(&metrics, "compact.runs", &[]), 1); + assert_eq!( + value(&metrics, "compact.operations", &[("outcome", "failed")]), + 1 + ); + assert_eq!( + value(&metrics, "compact.duration_ns", &[("statistic", "count")]), + 1 + ); + assert!(value(&metrics, "compact.duration_ns", &[("statistic", "sum")]) > 0); + assert_eq!( + metric(&metrics, "compact.dead_bytes", &[("kind", "bound")]), + None + ); + assert_eq!( + metric( + &metrics, + "compact.slo", + &[("objective", "residue_free"), ("result", "pass")] + ), + None + ); +} + +fn clean(handles: &SqliteHandles) { + let mut out = Vec::new(); + handles + .diagnose( + layerfs_persistence::diagnostic::Options::default(), + &mut |observation| out.push(observation), + ) + .unwrap(); + assert!( + !out.iter().any(|observation| matches!( + observation.outcome, + layerfs_persistence::diagnostic::Outcome::Fail + | layerfs_persistence::diagnostic::Outcome::Unknown + )), + "{out:?}" + ); +} diff --git a/engine/crates/layerfs-persistence/tests/concurrent_first_installs.rs b/engine/crates/layerfs-persistence/tests/concurrent_first_installs.rs index 121e06ecbb..5c01efb8da 100644 --- a/engine/crates/layerfs-persistence/tests/concurrent_first_installs.rs +++ b/engine/crates/layerfs-persistence/tests/concurrent_first_installs.rs @@ -1,6 +1,13 @@ //! F-036: two writers, each with its own opened Store handle as a daemon has, //! save the same new content at the same time. Both Saves complete and every //! object reads back, whichever writer won each first-wins registration. +//! +//! Delta selection can propose a copy the other writer just published, so the +//! candidate's chain can name the very object this Save is storing: the two +//! writers can each pick the other's copy as a base, and storing both would +//! close a delta cycle (`Integrity("dependency cycle")` at the first read). +//! Selection refuses that edge (`DepthCache::cost_avoiding`) and stores the +//! object FULL, so the graph stays acyclic whichever registrations win. #![cfg(target_os = "linux")] mod support; use layerfs_content::{AdvisoryPredecessors, FinalizedObject, ObjectRole}; diff --git a/engine/crates/layerfs-persistence/tests/postgresql_commit_round_trips.rs b/engine/crates/layerfs-persistence/tests/postgresql_commit_round_trips.rs index 99c0df929a..d43fad8377 100644 --- a/engine/crates/layerfs-persistence/tests/postgresql_commit_round_trips.rs +++ b/engine/crates/layerfs-persistence/tests/postgresql_commit_round_trips.rs @@ -364,8 +364,9 @@ fn commit_store_calls_are_counted_on_both_engines() { assert_eq!(pg("reserve").round_trips, 3); // The lane: its BEGIN, the head read, commit_branch's BEGIN, joined // snapshot, Commit insert, parent line, lineage insert, the position - // read, advance and COMMIT, and the lane's ROLLBACK. - assert_eq!(pg("lane + head + commit_branch").round_trips, 11); + // read, advance and COMMIT, the T6.5 epoch READ and its FOR SHARE + // re-check, and the lane's ROLLBACK. + assert_eq!(pg("lane + head + commit_branch").round_trips, 13); // #70: descriptors and bodies in one statement, found or missing. assert_eq!(pg("read_packs 2").round_trips, 1); assert_eq!(pg("read_packs missing").round_trips, 1); diff --git a/engine/crates/layerfs-persistence/tests/postgresql_gc_fence.rs b/engine/crates/layerfs-persistence/tests/postgresql_gc_fence.rs new file mode 100644 index 0000000000..6595664205 --- /dev/null +++ b/engine/crates/layerfs-persistence/tests/postgresql_gc_fence.rs @@ -0,0 +1,532 @@ +//! PostgreSQL runtime evidence for the GC admission and epoch paths that +//! shipped compile-only: T6's `gc_intent` admission and T6.5's writer-side +//! `project_epoch` fence, including the `SELECT ... FOR SHARE` re-check. +//! +//! The tests drive `PostgresHandles` through the public `HistoryCatalog` +//! methods. A trigger stands in for a removal marker that bumps the epoch +//! inside the writer's own transaction, which is exactly where the fence's +//! re-read runs; a deleted epoch row stands in for a compacted-away project. +//! +//! Needs `LAYERFS_TEST_POSTGRES_URL`; NOT_RUN without it. +#![cfg(feature = "postgresql")] +mod support; + +use layerfs_history::error::{HistoryError, Missing}; +use layerfs_history::records::{ + GcDeletion, GcIntent, GcIntentKind, GcScopeKind, PathRemovalKind, PathRemovalRequest, +}; +use layerfs_history::{CatalogId, HistoryCatalog}; +use support::pg::{ + commit, commit_request, counts, epoch, layer_request, merge_request, project, publish, url, + Schema, +}; +use support::root; + +const CURSOR: [u8; 32] = [78; 32]; + +/// Every test opens its own catalog identity, as a real Store does: the +/// PostgreSQL advisory keys are server-global, so two tests that shared a +/// binding could see each other's intents while running in parallel. +fn binding(tag: &str) -> Vec { + format!("postgresql-gc-fence-{tag}").into_bytes() +} + +fn op(tag: u8) -> [u8; 16] { + [tag; 16] +} + +fn mount( + stack: layerfs_history::LayerStackId, + branch: layerfs_history::BranchId, + tag: u8, +) -> GcIntent { + GcIntent::shared( + op(tag), + GcIntentKind::Mount, + GcScopeKind::Branch, + branch.as_slice(), + ) + .in_project(stack.as_slice()) + .named(Some("proj"), Some("work")) + .placed( + Some([tag; 32]), + Some(&format!("sandbox-{tag}")), + Some(&format!("machine-{tag}")), + ) + .owned(Some("runtime-a"), Some(&format!("boot-{tag}"))) +} + +fn init(stack: layerfs_history::LayerStackId, tag: u8) -> GcIntent { + GcIntent::shared( + op(tag), + GcIntentKind::Init, + GcScopeKind::Project, + stack.as_slice(), + ) + .named(Some("proj"), None) + .owned(Some("runtime-a"), Some(&format!("boot-{tag}"))) +} + +fn merge(stack: layerfs_history::LayerStackId, tag: u8) -> GcIntent { + GcIntent::shared( + op(tag), + GcIntentKind::Merge, + GcScopeKind::Project, + stack.as_slice(), + ) + .named(Some("proj"), Some("merged")) + .owned(Some("runtime-a"), Some(&format!("boot-{tag}"))) +} + +fn removal(stack: layerfs_history::LayerStackId, body: u8) -> GcIntent { + GcIntent::operation( + op(body), + GcIntentKind::Removal, + GcScopeKind::Project, + stack.as_slice(), + ) + .named(Some("proj"), None) +} + +fn path_request(stack: layerfs_history::LayerStackId) -> PathRemovalRequest { + PathRemovalRequest { + stack, + path: b"a.txt".to_vec(), + removed_ms: 1_000, + } +} + +fn hex16(bytes: &[u8; 16]) -> String { + let mut out = String::with_capacity(32); + for byte in bytes { + out.push_str(&format!("{byte:02x}")); + } + out +} + +/// A trigger that bumps the project epoch before each inserted row, standing +/// in for a removal marker that wins the race inside the writer's transaction. +fn bump_trigger(admin: &mut postgres::Client, table: &str) { + admin + .batch_execute(&format!( + "CREATE OR REPLACE FUNCTION g6a_epoch_race() RETURNS trigger LANGUAGE plpgsql AS $$ \ + BEGIN UPDATE project_epoch SET epoch=epoch+1 WHERE layer_stack_id=NEW.layer_stack_id; RETURN NEW; END $$; \ + CREATE TRIGGER g6a_epoch_race BEFORE INSERT ON \"{table}\" FOR EACH ROW \ + EXECUTE FUNCTION g6a_epoch_race();" + )) + .unwrap(); +} + +fn drop_trigger(admin: &mut postgres::Client) { + admin + .batch_execute( + "DROP TRIGGER IF EXISTS g6a_epoch_race ON \"commit\"; \ + DROP TRIGGER IF EXISTS g6a_epoch_race ON layer; \ + DROP FUNCTION IF EXISTS g6a_epoch_race();", + ) + .unwrap(); +} + +#[test] +fn a_normal_commit_publish_and_merge_leave_the_epoch_alone() { + let Some(url) = url() else { return }; + let schema = Schema::new(url, "fence_normal"); + let binding = binding("fence_normal"); + let handles = schema.create(&binding, CURSOR); + let (shop, work, genesis) = project(&handles.history, 1); + + let first = commit(&handles.history, work, 5); + assert_eq!( + epoch(&mut schema.admin(), shop), + 0, + "a Commit does not bump the epoch" + ); + let layer = publish(&handles.history, shop, work); + assert_eq!(layer.parent, Some(genesis)); + assert_eq!( + epoch(&mut schema.admin(), shop), + 0, + "a published Layer does not bump it" + ); + let merged = handles + .history + .merge_branch(&merge_request( + &handles.history, + shop, + work, + first.id, + genesis, + 60, + )) + .unwrap(); + assert_eq!(merged.branch.name.as_str(), "merged"); + assert_eq!( + epoch(&mut schema.admin(), shop), + 0, + "a merge does not bump it" + ); + assert_eq!(counts(&mut schema.admin()), (2, 2)); +} + +#[test] +fn a_missing_epoch_row_refuses_every_writer_with_conflict() { + let Some(url) = url() else { return }; + let schema = Schema::new(url, "fence_missing"); + let binding = binding("fence_missing"); + let handles = schema.create(&binding, CURSOR); + let (shop, work, genesis) = project(&handles.history, 1); + let first = commit(&handles.history, work, 5); + let side_request = merge_request(&handles.history, shop, work, first.id, genesis, 61); + let before = counts(&mut schema.admin()); + + schema + .admin() + .execute( + "DELETE FROM project_epoch WHERE layer_stack_id=$1", + &[&shop.as_slice()], + ) + .unwrap(); + + let refused = handles + .history + .commit_branch(&commit_request(&handles.history, work, root(6))) + .unwrap_err(); + assert!( + matches!(refused, HistoryError::Conflict("project epoch")), + "{refused:?}" + ); + let refused = handles + .history + .add_layer(&layer_request(&handles.history, shop, work)) + .unwrap_err(); + assert!( + matches!(refused, HistoryError::Conflict("project epoch")), + "{refused:?}" + ); + let refused = handles.history.merge_branch(&side_request).unwrap_err(); + assert!( + matches!(refused, HistoryError::Conflict("project epoch")), + "{refused:?}" + ); + + assert_eq!(counts(&mut schema.admin()), before, "no partial write"); + let snapshot = handles.history.branch_snapshot(work).unwrap().unwrap(); + assert_eq!(snapshot.branch.head_commit, Some(first.id)); + assert_eq!( + handles + .history + .layer_stack(shop) + .unwrap() + .unwrap() + .head_layer, + genesis + ); + assert!(handles.history.branch(merged_branch()).unwrap().is_none()); +} + +/// The Branch id `merge_request` creates for the merge. +fn merged_branch() -> layerfs_history::BranchId { + layerfs_history::BranchId::from_authority([9; 16]) +} + +#[test] +fn an_epoch_change_during_a_commit_is_detected_and_rolled_back() { + let Some(url) = url() else { return }; + let schema = Schema::new(url, "fence_trigger_commit"); + let binding = binding("fence_trigger_commit"); + let handles = schema.create(&binding, CURSOR); + let (shop, work, _genesis) = project(&handles.history, 1); + + bump_trigger(&mut schema.admin(), "commit"); + let refused = handles + .history + .commit_branch(&commit_request(&handles.history, work, root(5))) + .unwrap_err(); + assert!( + matches!(refused, HistoryError::Conflict("project epoch")), + "{refused:?}" + ); + assert_eq!(counts(&mut schema.admin()).0, 0, "the Commit rolled back"); + assert_eq!( + epoch(&mut schema.admin(), shop), + 0, + "the fake bump rolled back too" + ); + assert!(handles + .history + .branch(work) + .unwrap() + .unwrap() + .head_commit + .is_none()); + + drop_trigger(&mut schema.admin()); + let record = commit(&handles.history, work, 5); + assert_eq!(record.stack, shop); + assert_eq!(epoch(&mut schema.admin(), shop), 0); + assert_eq!( + handles.history.branch(work).unwrap().unwrap().head_commit, + Some(record.id) + ); +} + +#[test] +fn an_epoch_change_during_a_publish_is_detected_and_rolled_back() { + let Some(url) = url() else { return }; + let schema = Schema::new(url, "fence_trigger_layer"); + let binding = binding("fence_trigger_layer"); + let handles = schema.create(&binding, CURSOR); + let (shop, work, genesis) = project(&handles.history, 1); + let _first = commit(&handles.history, work, 5); + let before = counts(&mut schema.admin()); + + bump_trigger(&mut schema.admin(), "layer"); + let refused = handles + .history + .add_layer(&layer_request(&handles.history, shop, work)) + .unwrap_err(); + assert!( + matches!(refused, HistoryError::Conflict("project epoch")), + "{refused:?}" + ); + assert_eq!(counts(&mut schema.admin()), before, "the Layer rolled back"); + assert_eq!(epoch(&mut schema.admin(), shop), 0); + assert_eq!( + handles + .history + .layer_stack(shop) + .unwrap() + .unwrap() + .head_layer, + genesis + ); + + drop_trigger(&mut schema.admin()); + let layer = publish(&handles.history, shop, work); + assert_eq!(layer.parent, Some(genesis)); + assert_eq!(counts(&mut schema.admin()).1, before.1 + 1); +} + +#[test] +fn an_epoch_change_during_a_merge_is_detected_and_rolled_back() { + let Some(url) = url() else { return }; + let schema = Schema::new(url, "fence_trigger_merge"); + let binding = binding("fence_trigger_merge"); + let handles = schema.create(&binding, CURSOR); + let (shop, work, genesis) = project(&handles.history, 1); + let first = commit(&handles.history, work, 5); + let request = merge_request(&handles.history, shop, work, first.id, genesis, 62); + let before = counts(&mut schema.admin()); + + bump_trigger(&mut schema.admin(), "commit"); + let refused = handles.history.merge_branch(&request).unwrap_err(); + assert!( + matches!(refused, HistoryError::Conflict("project epoch")), + "{refused:?}" + ); + assert_eq!(counts(&mut schema.admin()), before, "the merge rolled back"); + assert_eq!(epoch(&mut schema.admin(), shop), 0); + assert!(handles.history.branch(merged_branch()).unwrap().is_none()); + + drop_trigger(&mut schema.admin()); + let merged = handles.history.merge_branch(&request).unwrap(); + assert_eq!(merged.branch.name.as_str(), "merged"); + assert_eq!(counts(&mut schema.admin()).0, before.0 + 1); +} + +#[test] +fn a_mount_blocks_all_three_removals_until_released() { + let Some(url) = url() else { return }; + let schema = Schema::new(url, "admission_mount"); + let binding = binding("admission_mount"); + let handles = schema.create(&binding, CURSOR); + let (project_id, branch, _genesis) = project(&handles.history, 1); + let mount = mount(project_id, branch, 1); + handles.history.gc_register(&mount).unwrap(); + + let refusal = handles + .history + .gc_remove_branch(branch, 1_000, &removal(project_id, 2)) + .unwrap_err(); + let HistoryError::MountsActive(state) = &refusal else { + panic!("{refusal:?}"); + }; + assert_eq!(state.holders.len(), 1); + assert_eq!(state.holders[0].kind, GcIntentKind::Mount); + assert_eq!(state.holders[0].sandbox.as_deref(), Some("sandbox-1")); + assert_eq!(state.holders[0].machine.as_deref(), Some("machine-1")); + assert_eq!( + state.holders[0].workspace.as_deref(), + Some("01".repeat(32).as_str()) + ); + assert_eq!(state.holders[0].op, hex16(&op(1))); + + assert!(matches!( + handles + .history + .gc_delete_stack(project_id, 1_000, &removal(project_id, 3)) + .unwrap_err(), + HistoryError::MountsActive(_) + )); + assert!(matches!( + handles + .history + .gc_remove_path(&path_request(project_id), &removal(project_id, 4)) + .unwrap_err(), + HistoryError::MountsActive(_) + )); + + let listed = handles + .history + .gc_intents(GcScopeKind::Branch, branch.as_slice()) + .unwrap(); + assert_eq!(listed.len(), 1); + assert_eq!(listed[0].kind, GcIntentKind::Mount); + handles.history.gc_release(&op(1)).unwrap(); + assert!(handles + .history + .gc_intents(GcScopeKind::Branch, branch.as_slice()) + .unwrap() + .is_empty()); + handles.history.gc_release(&op(1)).unwrap(); + + let outcome = handles + .history + .gc_remove_path(&path_request(project_id), &removal(project_id, 4)) + .unwrap(); + assert_eq!(outcome.kind, PathRemovalKind::Removed); + assert_eq!(epoch(&mut schema.admin(), project_id), 1); + handles + .history + .gc_remove_branch(branch, 2_000, &removal(project_id, 2)) + .unwrap(); + assert_eq!(epoch(&mut schema.admin(), project_id), 2); + assert!(matches!( + handles + .history + .gc_delete_stack(project_id, 3_000, &removal(project_id, 3)) + .unwrap(), + GcDeletion::Marked { deleted_ms: 3_000 } + )); + assert_eq!(epoch(&mut schema.admin(), project_id), 3); +} + +#[test] +fn init_and_merge_are_project_holders() { + let Some(url) = url() else { return }; + let schema = Schema::new(url, "admission_shared"); + let binding = binding("admission_shared"); + let handles = schema.create(&binding, CURSOR); + let (project_id, _branch, _genesis) = project(&handles.history, 1); + + handles.history.gc_register(&init(project_id, 5)).unwrap(); + let refusal = handles + .history + .gc_delete_stack(project_id, 1_000, &removal(project_id, 6)) + .unwrap_err(); + let HistoryError::MountsActive(state) = &refusal else { + panic!("{refusal:?}"); + }; + assert_eq!(state.holders[0].kind, GcIntentKind::Init); + handles.history.gc_release(&op(5)).unwrap(); + + handles.history.gc_register(&merge(project_id, 7)).unwrap(); + let refusal = handles + .history + .gc_remove_path(&path_request(project_id), &removal(project_id, 8)) + .unwrap_err(); + let HistoryError::MountsActive(state) = &refusal else { + panic!("{refusal:?}"); + }; + assert_eq!(state.holders[0].kind, GcIntentKind::Merge); + handles.history.gc_release(&op(7)).unwrap(); + + handles + .history + .gc_remove_path(&path_request(project_id), &removal(project_id, 8)) + .unwrap(); +} + +#[test] +fn a_live_operation_is_busy_and_an_uncertain_owner_is_unresolved() { + let Some(url) = url() else { return }; + let schema = Schema::new(url, "admission_op"); + let binding = binding("admission_op"); + let handles = schema.create(&binding, CURSOR); + let (project_id, branch, _genesis) = project(&handles.history, 1); + let catalog = CatalogId::derive(&binding).unwrap(); + let compaction = GcIntent::operation( + op(9), + GcIntentKind::Compaction, + GcScopeKind::Store, + catalog.as_slice(), + ) + .owned(Some("runtime-a"), Some("boot-9")) + .with_phase(Some("mark")); + handles.history.gc_register(&compaction).unwrap(); + + let refusal = handles + .history + .gc_remove_branch(branch, 1_000, &removal(project_id, 10)) + .unwrap_err(); + let HistoryError::BusyOp(state) = &refusal else { + panic!("{refusal:?}"); + }; + assert_eq!(state.kind, GcIntentKind::Compaction); + assert_eq!(state.entity, "store"); + assert_eq!(state.phase.as_deref(), Some("mark")); + assert_eq!(state.op, hex16(&op(9))); + + assert!(matches!( + handles + .history + .gc_register(&mount(project_id, branch, 11)) + .unwrap_err(), + HistoryError::BusyOp(_) + )); + + handles.history.gc_mark_uncertain(&op(9)).unwrap(); + let refusal = handles + .history + .gc_remove_branch(branch, 1_000, &removal(project_id, 10)) + .unwrap_err(); + assert!(matches!(refusal, HistoryError::Unresolved(_))); + + handles.history.gc_release(&op(9)).unwrap(); + handles + .history + .gc_remove_branch(branch, 2_000, &removal(project_id, 10)) + .unwrap(); +} + +#[test] +fn a_removal_first_refuses_the_later_commit_and_writes_nothing() { + let Some(url) = url() else { return }; + let schema = Schema::new(url, "fence_removal_first"); + let binding = binding("fence_removal_first"); + let handles = schema.create(&binding, CURSOR); + let (shop, work, _genesis) = project(&handles.history, 1); + let _first = commit(&handles.history, work, 5); + let before = counts(&mut schema.admin()); + + // Capture the request while the Branch is still visible; the removal then + // wins, and the filtered Branch resolution hides the retired Branch before + // the fence opens, so the write is refused and leaves no Commit behind. + let request = commit_request(&handles.history, work, root(6)); + handles.history.mark_branch_removed(work, 1_000).unwrap(); + assert_eq!( + epoch(&mut schema.admin(), shop), + 1, + "the marker bumped the epoch once" + ); + + let refused = handles.history.commit_branch(&request).unwrap_err(); + assert!( + matches!( + refused, + HistoryError::Missing(Missing::Branch) | HistoryError::Conflict("project epoch") + ), + "{refused:?}" + ); + assert_eq!(counts(&mut schema.admin()), before); +} diff --git a/engine/crates/layerfs-persistence/tests/postgresql_gc_mark.rs b/engine/crates/layerfs-persistence/tests/postgresql_gc_mark.rs new file mode 100644 index 0000000000..5bb4af3df1 --- /dev/null +++ b/engine/crates/layerfs-persistence/tests/postgresql_gc_mark.rs @@ -0,0 +1,387 @@ +//! PostgreSQL runtime evidence for the GC additions that shipped without it: +//! T1.3b's additive GC tables, T7.1's `kept_node` table and history closure, +//! and T7.2's object closure and live-heads digest. +//! +//! Each test creates one disposable schema and drives it through +//! `PostgresHandles`; a test that simulates an older Store rewrites the live +//! schema, its recorded source and its recorded definition exactly as the +//! release before the feature wrote them, then opens it writable. +//! +//! Needs `LAYERFS_TEST_POSTGRES_URL`; NOT_RUN without it. +#![cfg(feature = "postgresql")] +mod support; + +use layerfs_content::{construct_bytes, read_range, ObjectId}; +use layerfs_history::HistoryCatalog; +use layerfs_persistence::{KeptNodeId, PostgresHandles}; +use layerfs_storage::{port::PackPersistence, Storage}; +use layerfs_telemetry::timer::Timing; +use std::sync::Arc; +use support::pg::{ + commit, commit_with, counts, project, project_with_genesis, publish, url, Schema, DEFINITION, +}; + +const BINDING: &[u8] = b"postgresql-gc-mark"; +const CURSOR: [u8; 32] = [76; 32]; + +/// The eight tables T1.3b appended; the pre-GC Store has none of them. +const GC_TABLES: [&str; 8] = [ + "branch_retired", + "gc_dead", + "gc_intent", + "gc_op", + "kept_node", + "layer_stack_retired", + "path_removed", + "project_epoch", +]; + +/// Rows of `kept_node`, in the statement's order. +fn kept_rows(admin: &mut postgres::Client) -> Vec<(Vec, String, Vec, i64)> { + admin + .query( + "SELECT layer_stack_id,kind,node_id,serial FROM kept_node \ + ORDER BY layer_stack_id,kind,node_id", + &[], + ) + .unwrap() + .into_iter() + .map(|row| (row.get(0), row.get(1), row.get(2), row.get(3))) + .collect() +} + +/// Rewrites a fresh Store into the format a release before T1.3b wrote: no GC +/// tables and no position columns/state. Returns the source it replaced. +fn make_pre_gc(schema: &Schema) -> String { + let fresh: String = schema + .admin() + .query_one("SELECT schema_source FROM history_meta", &[]) + .unwrap() + .get(0); + let start = fresh + .find("\nCREATE TABLE branch_retired (") + .expect("the GC schema starts with branch_retired"); + let acquisition = fresh + .find("CREATE TABLE init_operation (") + .expect("the acquisition schema follows the GC tables"); + assert!(start < acquisition); + let old = format!("{}{}", &fresh[..start], &fresh[acquisition..]); + assert_ne!(old, fresh); + schema + .admin() + .batch_execute( + "DROP TABLE gc_dead; DROP TABLE gc_intent; DROP TABLE gc_op; \ + DROP TABLE project_epoch; DROP TABLE path_removed; DROP TABLE kept_node; \ + DROP TABLE branch_retired; DROP TABLE layer_stack_retired; \ + ALTER TABLE history_meta DROP COLUMN next_history_serial; \ + ALTER TABLE \"commit\" DROP COLUMN history_serial; \ + ALTER TABLE layer DROP COLUMN history_serial; \ + ALTER TABLE store_policy DROP COLUMN trace_salt;", + ) + .unwrap(); + let definition: String = schema.admin().query_one(DEFINITION, &[]).unwrap().get(0); + schema + .admin() + .execute( + "UPDATE history_meta SET schema_source=$1,schema_definition=$2", + &[&old, &definition], + ) + .unwrap(); + fresh +} + +/// Rewrites a fresh Store into the format a release before T7.1 wrote: the +/// `kept_node` table is gone from the schema and from the recorded source. +fn make_pre_kept_node(schema: &Schema) -> String { + let fresh: String = schema + .admin() + .query_one("SELECT schema_source FROM history_meta", &[]) + .unwrap() + .get(0); + let start = fresh + .find("CREATE TABLE kept_node (") + .expect("a fresh Store holds kept_node"); + let end = start + fresh[start..].find(";\n").expect("the table ends") + 2; + let old = format!("{}{}", &fresh[..start], &fresh[end..]); + assert_ne!(old, fresh); + schema + .admin() + .batch_execute("DROP TABLE kept_node;") + .unwrap(); + let definition: String = schema.admin().query_one(DEFINITION, &[]).unwrap().get(0); + schema + .admin() + .execute( + "UPDATE history_meta SET schema_source=$1,schema_definition=$2", + &[&old, &definition], + ) + .unwrap(); + fresh +} + +/// One Save of `bytes`; returns its root. +fn save(storage: &Storage, bytes: &[u8]) -> ObjectId { + let save = storage.begin_save().unwrap(); + let root = Timing::disabled("construct", |scope| { + construct_bytes( + storage.policy().construction(), + &storage.policy().construction().capacities(), + bytes, + &mut save.sink(), + scope.child("content"), + ) + }) + .0 + .unwrap() + .root; + save.finish().unwrap(); + root +} + +fn bytes(seed: u32, len: usize) -> Vec { + let mut state = seed.wrapping_mul(2654435761) | 1; + (0..len) + .map(|_| { + state ^= state << 13; + state ^= state >> 17; + state ^= state << 5; + (state >> 24) as u8 + }) + .collect() +} + +#[test] +fn a_pre_gc_store_gains_the_gc_tables_and_its_project_epoch_rows() { + let Some(url) = url() else { return }; + let schema = Schema::new(url, "pre_gc"); + let handles = schema.create(BINDING, CURSOR); + let (shop, work, _genesis) = project(&handles.history, 1); + drop(handles); + let fresh = make_pre_gc(&schema); + + let mut before = schema.admin(); + assert_eq!( + before + .query_one("SELECT count(*) FROM layer_stack", &[]) + .unwrap() + .get::<_, i64>(0), + 1 + ); + assert!(before + .query_one( + "SELECT count(*) FROM information_schema.tables WHERE table_schema=current_schema() AND table_name='gc_intent'", + &[], + ) + .unwrap() + .get::<_, i64>(0) + == 0); + drop(before); + + let _upgraded = schema + .open(BINDING, CURSOR) + .expect("a pre-T1.3b Store opens writable"); + let mut admin = schema.admin(); + for table in GC_TABLES { + assert_eq!( + admin + .query_one( + "SELECT count(*) FROM information_schema.tables \ + WHERE table_schema=current_schema() AND table_name=$1 AND table_type='BASE TABLE'", + &[&table], + ) + .unwrap() + .get::<_, i64>(0), + 1, + "{table} exists after the additive migration" + ); + } + assert_eq!( + admin + .query_one("SELECT count(*) FROM project_epoch", &[]) + .unwrap() + .get::<_, i64>(0), + 1, + "the existing project gains one epoch row" + ); + assert_eq!( + admin + .query_one( + "SELECT epoch FROM project_epoch WHERE layer_stack_id=$1", + &[&shop.as_slice()], + ) + .unwrap() + .get::<_, i64>(0), + 0 + ); + let (source, recorded_definition): (String, String) = { + let row = admin + .query_one( + "SELECT schema_source,schema_definition FROM history_meta", + &[], + ) + .unwrap(); + (row.get(0), row.get(1)) + }; + assert_eq!(source, fresh, "the migration records the current source"); + assert_eq!(recorded_definition, schema.definition()); + drop(admin); + + // A second writable open changes nothing. + let again = schema + .open(BINDING, CURSOR) + .expect("the migrated Store reopens"); + assert_eq!( + again + .history + .branch(work) + .unwrap() + .expect("the Branch survived") + .head_commit, + None + ); +} + +#[test] +fn a_pre_kept_node_store_gains_the_table_and_a_mark_fills_it() { + let Some(url) = url() else { return }; + let schema = Schema::new(url, "pre_kept"); + let handles = schema.create(BINDING, CURSOR); + let (shop, work, genesis) = project(&handles.history, 1); + let first = commit(&handles.history, work, 5); + let layer = publish(&handles.history, shop, work); + drop(handles); + let fresh = make_pre_kept_node(&schema); + + let handles = schema + .open(BINDING, CURSOR) + .expect("a pre-T7.1 Store opens writable"); + let mut admin = schema.admin(); + assert_eq!( + admin + .query_one("SELECT count(*) FROM kept_node", &[]) + .unwrap() + .get::<_, i64>(0), + 0, + "the table is empty until a mark writes it" + ); + let source: String = admin + .query_one("SELECT schema_source FROM history_meta", &[]) + .unwrap() + .get(0); + assert_eq!(source, fresh); + drop(admin); + + let kept = handles + .history + .mark_history_closure() + .expect("a mark writes the history closure"); + assert!(kept.contains(KeptNodeId::Stack(shop))); + assert!(kept.contains(KeptNodeId::Branch(work))); + assert!(kept.contains(KeptNodeId::Commit(first.id))); + assert!(kept.contains(KeptNodeId::Layer(layer.id))); + assert!( + kept.contains(KeptNodeId::Layer(genesis)), + "the genesis Layer is reached" + ); + assert_eq!(kept_rows(&mut schema.admin()).len(), kept.len()); +} + +#[test] +fn a_mark_records_the_history_closure_on_postgresql() { + let Some(url) = url() else { return }; + let schema = Schema::new(url, "mark_history"); + let handles = schema.create(BINDING, CURSOR); + let (shop, work, genesis) = project(&handles.history, 1); + let first = commit(&handles.history, work, 5); + let layer = publish(&handles.history, shop, work); + + let kept = handles + .history + .mark_history_closure() + .expect("a mark writes kept_node"); + for id in [ + KeptNodeId::Stack(shop), + KeptNodeId::Branch(work), + KeptNodeId::Commit(first.id), + KeptNodeId::Layer(genesis), + KeptNodeId::Layer(layer.id), + ] { + assert!(kept.contains(id), "{id:?} is retained"); + } + let rows = kept_rows(&mut schema.admin()); + assert_eq!(rows.len(), kept.len()); + let mut expected: Vec<(Vec, String, Vec)> = kept + .nodes() + .iter() + .map(|node| { + ( + node.stack().as_slice().to_vec(), + node.id().kind().to_owned(), + node.id().as_slice().to_vec(), + ) + }) + .collect(); + expected.sort(); + let mut actual: Vec<(Vec, String, Vec)> = rows + .iter() + .map(|(stack, kind, id, _)| (stack.clone(), kind.clone(), id.clone())) + .collect(); + actual.sort(); + assert_eq!(actual, expected); + + // A second mark over unchanged history writes the same rows. + let again = handles.history.mark_history_closure().unwrap(); + assert_eq!(again, kept); + assert_eq!(kept_rows(&mut schema.admin()), rows); +} + +#[test] +fn a_mark_keeps_the_saved_objects_and_reports_the_live_heads_digest() { + let Some(url) = url() else { return }; + let schema = Schema::new(url, "mark_objects"); + let handles: PostgresHandles = schema.create(BINDING, CURSOR); + let storage = Storage::new(handles.storage.clone() as Arc).unwrap(); + let genesis_root = save(&storage, b"genesis tree"); + let (shop, work, genesis) = project_with_genesis(&handles.history, 1, genesis_root); + let root_id = save(&storage, &bytes(5, 5000)); + let record = commit_with(&handles.history, work, root_id); + let layer = publish(&handles.history, shop, work); + + let mark = handles.history.mark().expect("a mark writes both closures"); + assert!( + mark.objects().contains(root_id), + "the committed root's object is retained: {:?}", + mark.objects().objects() + ); + assert!(!mark.objects().packs().is_empty(), "its pack is retained"); + assert!(mark.history().contains(KeptNodeId::Commit(record.id))); + assert!(mark.history().contains(KeptNodeId::Layer(layer.id))); + assert!(mark.history().contains(KeptNodeId::Layer(genesis))); + assert_eq!(kept_rows(&mut schema.admin()).len(), mark.history().len()); + + let digest = mark.live_heads_digest(); + assert_ne!( + digest, [0; 32], + "the live-heads digest is not a placeholder" + ); + let again = handles.history.mark().expect("a second mark"); + assert_eq!(again.objects(), mark.objects()); + assert_eq!(again.live_heads_digest(), digest); + + // Nothing was compacted: the object and its pack are still readable. + let mut bytes_out = Vec::new(); + Timing::disabled("read", |scope| { + read_range( + &storage.reader().unwrap(), + root_id, + 0..5000, + &mut bytes_out, + scope.child("read"), + ) + }) + .0 + .unwrap(); + assert_eq!(bytes_out, bytes(5, 5000)); + let (commits, _layers) = counts(&mut schema.admin()); + assert_eq!(commits, 1); +} diff --git a/engine/crates/layerfs-persistence/tests/postgresql_narrow_locations.rs b/engine/crates/layerfs-persistence/tests/postgresql_narrow_locations.rs index c1e8694d9c..07305ec894 100644 --- a/engine/crates/layerfs-persistence/tests/postgresql_narrow_locations.rs +++ b/engine/crates/layerfs-persistence/tests/postgresql_narrow_locations.rs @@ -236,8 +236,27 @@ fn only_tables_with_unbounded_values_have_a_toast_relation() { .iter() .map(|row| row.get(0)) .collect(); + // The additive T1.2c/T1.3b/T7.1 tables keep PostgreSQL's default column + // storage, so they gain a TOAST relation even where every column is + // bounded (bytea ids, bigint counters, short text); the base schema marks + // exactly its bounded columns STORAGE PLAIN. assert_eq!( toasted, - ["commit", "history_meta", "layer", "pack", "reach"] + [ + "branch_retired", + "commit", + "gc_dead", + "gc_intent", + "gc_op", + "history_meta", + "kept_node", + "layer", + "layer_stack_retired", + "pack", + "path_removed", + "project_epoch", + "reach", + "store_policy", + ] ); } diff --git a/engine/crates/layerfs-persistence/tests/support/mod.rs b/engine/crates/layerfs-persistence/tests/support/mod.rs index c7d718d7dc..cc9912afde 100644 --- a/engine/crates/layerfs-persistence/tests/support/mod.rs +++ b/engine/crates/layerfs-persistence/tests/support/mod.rs @@ -140,3 +140,6 @@ pub mod sqlite { } pub mod doctor; + +#[cfg(feature = "postgresql")] +pub mod pg; diff --git a/engine/crates/layerfs-persistence/tests/support/pg.rs b/engine/crates/layerfs-persistence/tests/support/pg.rs new file mode 100644 index 0000000000..5952125420 --- /dev/null +++ b/engine/crates/layerfs-persistence/tests/support/pg.rs @@ -0,0 +1,281 @@ +#![allow(dead_code)] +//! Shared fixture for the PostgreSQL runtime-evidence tests (T1.3b, T6, T6.5, +//! T7.1, T7.2). One disposable schema per test, driven only through the public +//! `PostgresHandles`/`HistoryCatalog` API except where a test proves the +//! physical layout (a trigger, a dropped table, an epoch row). +use layerfs_content::ObjectId; +use layerfs_history::records::{ + AddLayerOutcome, AddLayerRequest, BranchMergeRequest, CommitMeta, CommitOutcome, CommitRequest, + CommitVia, ForkRequest, ForkSource, MergeCommit, MergeHead, MergeSide, StackInitialization, +}; +use layerfs_history::{ + BranchId, CommitId, CommitRecord, HistoryCatalog, HistoryCatalogConfig, LayerId, LayerRecord, + LayerStackId, NodeId, +}; +use layerfs_persistence::{PostgresHandles, PostgresSelection}; +use layerfs_storage::port::PersistenceError; +use layerfs_storage::StoragePolicy; + +use super::{name, root, stack}; + +/// The URL a PostgreSQL-backed test runs against, or `None` with the usual +/// NOT_RUN note. +pub fn url() -> Option { + let url = std::env::var("LAYERFS_TEST_POSTGRES_URL").ok(); + if url.is_none() { + eprintln!("NOT_RUN: LAYERFS_TEST_POSTGRES_URL is unset"); + } + url +} + +/// One `PostgresSelection` under a disposable schema named for the test. +pub struct Schema { + pub url: String, + pub name: String, +} + +impl Schema { + pub fn new(url: String, tag: &str) -> Self { + let name = format!("lfsg6a_{tag}_{}", std::process::id()); + let schema = Self { url, name }; + schema.drop_schema(); + schema + } + + pub fn selection(&self) -> PostgresSelection { + PostgresSelection::new(&self.url, &self.name) + } + + pub fn create(&self, binding: &[u8], cursor: [u8; 32]) -> PostgresHandles { + PostgresHandles::create( + &self.selection(), + StoragePolicy::frozen_default(), + &catalog(binding, cursor, 3), + ) + .expect("PostgreSQL Store creation") + } + + pub fn open( + &self, + binding: &[u8], + cursor: [u8; 32], + ) -> Result { + PostgresHandles::open_writable(&self.selection(), binding, cursor) + } + + /// An admin connection with `search_path` pointing at the test schema. + pub fn admin(&self) -> postgres::Client { + let mut client = postgres::Client::connect(&self.url, postgres::NoTls).unwrap(); + client + .batch_execute(&format!("SET search_path TO {}", self.name)) + .unwrap(); + client + } + + /// The live column definition the Store records, exactly as + /// `history_meta.schema_definition` holds it. + pub fn definition(&self) -> String { + self.admin().query_one(DEFINITION, &[]).unwrap().get(0) + } + + pub fn drop_schema(&self) { + if let Ok(mut client) = postgres::Client::connect(&self.url, postgres::NoTls) { + let _ = client.batch_execute(&format!("DROP SCHEMA IF EXISTS {} CASCADE", self.name)); + } + } +} + +impl Drop for Schema { + fn drop(&mut self) { + self.drop_schema(); + } +} + +/// The live column definition, as `postgresql_position_columns.rs` uses it. +pub const DEFINITION: &str = "SELECT string_agg(table_name::text||' '||column_name::text||' '||data_type::text||' '||is_nullable::text, chr(10) ORDER BY table_name, ordinal_position)||chr(10) FROM information_schema.columns WHERE table_schema=current_schema()"; + +pub fn catalog(binding: &[u8], cursor: [u8; 32], incarnation: u64) -> HistoryCatalogConfig { + HistoryCatalogConfig { + binding_key: binding.to_vec(), + cursor_key: cursor, + incarnation, + } +} + +/// Project `tag` with one Branch `work`, at its genesis Layer. +pub fn project(history: &dyn HistoryCatalog, tag: u8) -> (LayerStackId, BranchId, LayerId) { + project_with_genesis(history, tag, root(1)) +} + +/// Project `tag` with one Branch `work`, rooted at an already-published +/// genesis object (a mark needs a locator for every retained root). +pub fn project_with_genesis( + history: &dyn HistoryCatalog, + tag: u8, + genesis_root: ObjectId, +) -> (LayerStackId, BranchId, LayerId) { + let record = history + .initialize_layerstack(&StackInitialization { + logical: 10, + stack: stack(tag), + name: name(&format!("project-{tag}")), + scope: root(200), + profile: root(201), + genesis_root, + }) + .unwrap(); + let branch = branch_id(tag); + history + .fork(&ForkRequest { + stack: stack(tag), + branch, + name: name("work"), + source: ForkSource::Layer(record.head_layer), + }) + .unwrap(); + (stack(tag), branch, record.head_layer) +} + +pub fn branch_id(tag: u8) -> BranchId { + super::branch_id(tag) +} + +pub fn commit_request( + history: &dyn HistoryCatalog, + branch: BranchId, + candidate_root: ObjectId, +) -> CommitRequest { + let record = history.branch(branch).unwrap().unwrap(); + let expected_root = match record.head_commit { + Some(head) => history.commit(head).unwrap().unwrap().root, + None => history.layer(record.base_layer).unwrap().unwrap().root, + }; + CommitRequest { + branch, + expected_head: record.head_commit, + expected_base: record.base_layer, + expected_root, + candidate_root, + profile: root(201), + scope: root(200), + second_parent: None, + meta: CommitMeta::new(CommitVia::Files), + force: false, + } +} + +pub fn commit(history: &dyn HistoryCatalog, branch: BranchId, tag: u8) -> CommitRecord { + commit_with(history, branch, root(tag)) +} + +pub fn commit_with( + history: &dyn HistoryCatalog, + branch: BranchId, + candidate_root: ObjectId, +) -> CommitRecord { + match history + .commit_branch(&commit_request(history, branch, candidate_root)) + .unwrap() + { + CommitOutcome::Committed { record, .. } => *record, + other => panic!("commit: {other:?}"), + } +} + +pub fn layer_request( + history: &dyn HistoryCatalog, + stack: LayerStackId, + branch: BranchId, +) -> AddLayerRequest { + let record = history.branch(branch).unwrap().unwrap(); + let head = history.layer_stack(stack).unwrap().unwrap(); + AddLayerRequest { + stack, + branch, + commit: record.head_commit.expect("a committed Branch"), + expected_stack_head: head.head_layer, + expected_branch_base: record.base_layer, + } +} + +pub fn publish(history: &dyn HistoryCatalog, stack: LayerStackId, branch: BranchId) -> LayerRecord { + match history + .add_layer(&layer_request(history, stack, branch)) + .unwrap() + { + AddLayerOutcome::Added { layer } => layer, + other => panic!("publish: {other:?}"), + } +} + +/// A merge of `work`'s Commit with a second Branch still at the genesis Layer: +/// one new Commit, second parent the genesis node, root `tag`. +pub fn merge_request( + history: &dyn HistoryCatalog, + stack: LayerStackId, + branch: BranchId, + commit: CommitId, + genesis: LayerId, + tag: u8, +) -> BranchMergeRequest { + let side = branch_id(2); + history + .fork(&ForkRequest { + stack, + branch: side, + name: name("side"), + source: ForkSource::Layer(genesis), + }) + .unwrap(); + BranchMergeRequest { + stack, + branch: branch_id(9), + name: name("merged"), + sides: [ + (MergeSide::Branch(branch), NodeId::Commit(commit)), + (MergeSide::Branch(side), NodeId::Layer(genesis)), + ], + head: MergeHead::Commit(Box::new(MergeCommit { + base: genesis, + parent: Some(commit), + second_parent: NodeId::Layer(genesis), + root: root(tag), + meta: CommitMeta::new(CommitVia::Merge), + })), + } +} + +/// `(commit rows, layer rows)` to prove a refusal wrote nothing. +pub fn counts(admin: &mut postgres::Client) -> (i64, i64) { + let count = |admin: &mut postgres::Client, table: &str| -> i64 { + admin + .query_one(&format!("SELECT count(*) FROM \"{table}\""), &[]) + .unwrap() + .get(0) + }; + (count(admin, "commit"), count(admin, "layer")) +} + +pub fn epoch(admin: &mut postgres::Client, stack: LayerStackId) -> i64 { + admin + .query_one( + "SELECT epoch FROM project_epoch WHERE layer_stack_id=$1", + &[&stack.as_slice()], + ) + .unwrap() + .get(0) +} + +/// Name of every base table in the test schema, in name order. +pub fn tables(admin: &mut postgres::Client) -> Vec { + admin + .query( + "SELECT table_name::text FROM information_schema.tables \ + WHERE table_schema=current_schema() AND table_type='BASE TABLE' ORDER BY 1", + &[], + ) + .unwrap() + .into_iter() + .map(|row| row.get(0)) + .collect() +} diff --git a/engine/crates/layerfs-project/src/store/init.rs b/engine/crates/layerfs-project/src/store/init.rs index b2bb16565e..37af0fc0ee 100644 --- a/engine/crates/layerfs-project/src/store/init.rs +++ b/engine/crates/layerfs-project/src/store/init.rs @@ -2,8 +2,8 @@ use crate as layerfs_project; use layerfs_bridge::provision::{check_destination, ProviderKind, StoreManifest, StoreProfile}; use layerfs_history::{ - BranchId, BranchSnapshot, ForkRequest, ForkSource, HistoryCatalog, HistoryCatalogConfig, - HistoryError, HistoryName, InitStatistics, LayerStackId, + error::NameTakenState, BranchId, BranchSnapshot, ForkRequest, ForkSource, HistoryCatalog, + HistoryCatalogConfig, HistoryError, HistoryName, InitStatistics, LayerStackId, }; use layerfs_persistence::{ PersistenceConfig, SealedStore, SqliteAcquisitionSchema, SqliteHandles, @@ -77,9 +77,10 @@ pub enum InitError { Project(ProjectError), /// First Branch publication. History(HistoryError), - /// Adding a project (#506): the Store already has a project of that - /// name; nothing was written. - Exists, + /// Adding a project (#506): the Store still holds that project name. + /// It is `NameTaken` whether the holder is live, retired or deleted; + /// nothing was written. + NameTaken(Box), /// Adding a project (#506): the Store was made without the acquisition /// tables (schema versions 16 to 18), refused before anything was /// scanned or written. LayerFS adds no tables to an existing Store. diff --git a/engine/crates/layerfs-project/src/store/live.rs b/engine/crates/layerfs-project/src/store/live.rs index 143ff54cb0..e63fe2cdd4 100644 --- a/engine/crates/layerfs-project/src/store/live.rs +++ b/engine/crates/layerfs-project/src/store/live.rs @@ -15,7 +15,7 @@ use crate::store::{live_open::Opened, InitError}; use crate::{InitCounters, InitStep, Initialized, ProjectError}; use layerfs_history::{ BranchId, BranchSnapshot, ForkRequest, ForkSource, HistoryCatalog, HistoryCatalogConfig, - HistoryName, HistoryResult, LayerStackId, LayerStackRecord, Page, + HistoryError, HistoryName, HistoryResult, LayerStackId, LayerStackRecord, Page, }; use layerfs_persistence::{ SealedStore, SqliteAcquisitionSchema, SqliteHandles, SqlitePersistenceProfile, StoreSelection, @@ -132,11 +132,14 @@ pub(crate) fn add( disposable(&request.store)?; let handles = Opened::writable(&request.store, &request.binding, request.cursor_key)?; let history = handles.history(); - let taken = history - .layer_stack_named(&request.stack_name) - .map_err(InitError::History)?; - if taken.is_some() { - return Err(InitError::Exists); + // A held name (live, retired or deleted) is refused before the folder + // is scanned or any object written. The publication re-checks it, so + // a collision that appears meanwhile is refused the same way. + if let Some(state) = history + .layer_stack_name_taken(&request.stack_name) + .map_err(InitError::History)? + { + return Err(InitError::NameTaken(Box::new(state))); } let storage = Storage::new(handles.storage()).map_err(InitError::Storage)?; let imported = crate::init_observed( @@ -195,6 +198,11 @@ fn refused_acquisition(error: ProjectError) -> InitError { ProjectError::Acquisition(AcquisitionError::Persistence(PersistenceError::Refused { status, })) if status == "acquisition working rows remain" => InitError::Busy, + // The catalog's collision query read the holder (live, retired or + // deleted) and wrote nothing: keep its typed state for the SDK. + ProjectError::History(HistoryError::NameTaken(state)) => { + InitError::NameTaken(state.clone()) + } _ => InitError::Project(error), } } diff --git a/engine/crates/layerfs-project/tests/init_postgresql.rs b/engine/crates/layerfs-project/tests/init_postgresql.rs index b19f3ca345..a0dff6d834 100644 --- a/engine/crates/layerfs-project/tests/init_postgresql.rs +++ b/engine/crates/layerfs-project/tests/init_postgresql.rs @@ -7,7 +7,10 @@ //! sslmode=disable`). Without it the test reports NOT_RUN and passes nothing. #![cfg(all(unix, feature = "postgresql"))] use layerfs_content::{filesystem::root::FilesystemRootId, read_all, FilesystemRead, LogicalPath}; -use layerfs_history::{BranchId, HistoryCatalog, HistoryCatalogConfig, HistoryName, LayerStackId}; +use layerfs_history::{ + error::{HolderKind, HolderState, NameSource}, + BranchId, HistoryCatalog, HistoryCatalogConfig, HistoryName, LayerStackId, +}; use layerfs_persistence::{ PersistenceConfig, PostgresHandles, PostgresSelection, SqlitePersistenceProfile, StoreSelection, }; @@ -176,11 +179,15 @@ fn a_folder_inits_into_postgresql_with_the_root_sqlite_gives() { let work = on_postgresql.initialized.namespace_work; assert_eq!((work.wide_directories, work.regular_aliases), (1, 2)); - // A taken name is refused before anything is written; another project is added. - assert!(matches!( - add(postgresql(), &source, "app"), - Err(InitError::Exists) - )); + // A taken name is the typed `NameTaken`; another project is added. + let taken = add(postgresql(), &source, "app"); + let Err(InitError::NameTaken(state)) = taken else { + panic!("a held project name is NameTaken: {taken:?}"); + }; + assert_eq!(state.holder.kind, HolderKind::Project); + assert_eq!(state.holder.name, "app"); + assert_eq!(state.holder.state, HolderState::Live); + assert_eq!(state.source, NameSource::Store); let other = scratch.path.join("other"); fs::create_dir_all(&other).unwrap(); fs::write(other.join("README"), b"other").unwrap(); diff --git a/engine/crates/layerfs-store-service/src/history/admission.rs b/engine/crates/layerfs-store-service/src/history/admission.rs index 84b421dca8..cf614f48b2 100644 --- a/engine/crates/layerfs-store-service/src/history/admission.rs +++ b/engine/crates/layerfs-store-service/src/history/admission.rs @@ -66,10 +66,13 @@ pub fn project_removal_at(stack: LayerStackId, op: [u8; 16]) -> GcIntent { } /// A mount intent at Branch scope, naming its project identity for the -/// PostgreSQL key derivation. +/// PostgreSQL key derivation. The Workspace is always placed; the Sandbox +/// and machine are placed only when the caller that mounted knows them +/// (a daemon mount does; a private Store-call Workspace does not). pub fn mount_intent( workspace: layerfs_history::WorkspaceId, snapshot: &layerfs_history::BranchSnapshot, + place: &layerfs_bridge::control::MountPlace, ) -> GcIntent { let body: [u8; 32] = workspace.as_slice().try_into().unwrap_or([0u8; 32]); GcIntent::shared( @@ -80,7 +83,11 @@ pub fn mount_intent( ) .in_project(snapshot.branch.stack.as_slice()) .named(None, Some(snapshot.branch.name.as_str())) - .placed(Some(body), None, None) + .placed( + Some(body), + place.sandbox.as_deref(), + place.machine.as_deref(), + ) } /// A short-lived shared intent (Init or merge), released on success or drop. diff --git a/engine/crates/layerfs-store-service/src/history/branch.rs b/engine/crates/layerfs-store-service/src/history/branch.rs index eeeb766ebd..1d60ff3922 100644 --- a/engine/crates/layerfs-store-service/src/history/branch.rs +++ b/engine/crates/layerfs-store-service/src/history/branch.rs @@ -346,7 +346,7 @@ pub fn list_layers(store: &Arc, stack: &LayerStackRecord, limit: usize, p Some(id) => match names.get(&id) { Some(name) => Some(name.clone()), None => catalog - .branch(id) + .branch_any(id) .map_err(history)? .map(|branch| branch.name.as_str().to_owned()), }, diff --git a/engine/crates/layerfs-store-service/src/history/lookup.rs b/engine/crates/layerfs-store-service/src/history/lookup.rs index c197adebc4..b57dc3c6a7 100644 --- a/engine/crates/layerfs-store-service/src/history/lookup.rs +++ b/engine/crates/layerfs-store-service/src/history/lookup.rs @@ -73,7 +73,8 @@ pub fn history(error: HistoryError) -> SdkRefusal { refuse(code, message, detail) } -fn name_taken_detail(state: &NameTakenState) -> SdkValue { +/// The `NameTaken` detail: the holder and where it is held. +pub fn name_taken_detail(state: &NameTakenState) -> SdkValue { SdkValue::map([ ( "holder", diff --git a/engine/crates/layerfs-store-service/src/history/saved.rs b/engine/crates/layerfs-store-service/src/history/saved.rs index f14c40282f..31b28b2db7 100644 --- a/engine/crates/layerfs-store-service/src/history/saved.rs +++ b/engine/crates/layerfs-store-service/src/history/saved.rs @@ -18,7 +18,7 @@ pub fn reference(store: &Arc, node: NodeId) -> Result { let branch = record .meta .branch - .map(|id| store.published(|history| history.branch(id))) + .map(|id| store.published(|history| history.branch_any(id))) .transpose() .map_err(args::published)? .flatten() @@ -83,7 +83,7 @@ pub fn record(store: &Arc, node: NodeId) -> Result { .transpose()?; let source_branch = r .source_branch - .map(|id| store.published(|history| history.branch(id))) + .map(|id| store.published(|history| history.branch_any(id))) .transpose() .map_err(args::published)? .flatten(); diff --git a/engine/crates/layerfs-store-service/src/operator/files.rs b/engine/crates/layerfs-store-service/src/operator/files.rs index ec5e04acaa..078be27e11 100644 --- a/engine/crates/layerfs-store-service/src/operator/files.rs +++ b/engine/crates/layerfs-store-service/src/operator/files.rs @@ -24,7 +24,7 @@ pub fn revision( let branch = r .meta .branch - .map(|id| store.history().branch(id)) + .map(|id| store.history().branch_any(id)) .transpose() .map_err(args::history)? .flatten(); diff --git a/engine/crates/layerfs-store-service/src/operator/inspect.rs b/engine/crates/layerfs-store-service/src/operator/inspect.rs index 9dc541f56b..60bdfb4224 100644 --- a/engine/crates/layerfs-store-service/src/operator/inspect.rs +++ b/engine/crates/layerfs-store-service/src/operator/inspect.rs @@ -190,9 +190,17 @@ pub fn snapshot(store: &Arc, args: &SdkValue, views: &[WorkspaceView]) -> let mut next: Option = Some(stack.head_layer); while let Some(id) = next { let record = args::layer(store, id)?; - let source = record - .source_branch - .and_then(|branch| names.get(&branch).map(|(name, _)| name.clone())); + let source = match record.source_branch { + Some(branch) => match names.get(&branch) { + Some((name, _)) => Some(name.clone()), + None => store + .history() + .branch_any(branch) + .map_err(args::history)? + .map(|record| record.name.as_str().to_owned()), + }, + None => None, + }; let value = layer_value(&record, source.as_deref()); if layer_spent + cost(&value) > LAYER_BUDGET { break; diff --git a/engine/crates/layerfs-store-service/src/store/bind.rs b/engine/crates/layerfs-store-service/src/store/bind.rs index c4bd4b6065..fd169256c6 100644 --- a/engine/crates/layerfs-store-service/src/store/bind.rs +++ b/engine/crates/layerfs-store-service/src/store/bind.rs @@ -4,6 +4,7 @@ use super::{ NamedBindRequest, Store, }; use crate::OwnerClient; +use layerfs_bridge::control::MountPlace; use layerfs_content::filesystem::{ attributes::{read_portable, AttributeReadWork}, directory::decode_directory_page, @@ -24,7 +25,19 @@ impl Store { owner: OwnerClient, request: BindRequest, ) -> Result { - self.bind_with(owner, BindIntent::Id(request), false) + self.bind_with(owner, BindIntent::Id(request), MountPlace::default(), false) + } + /// [`Self::bind`] of a mount whose caller knows the Sandbox and machine + /// its daemon serves: the registered holder reports them beside the + /// Workspace. An unknown place is the plain [`Self::bind`]. + #[allow(clippy::result_large_err)] + pub fn bind_placed( + self: &Arc, + owner: OwnerClient, + request: BindRequest, + place: MountPlace, + ) -> Result { + self.bind_with(owner, BindIntent::Id(request), place, false) } /// [`Self::bind`] of the Branch a project and Branch name select (#64), /// found on the Workspace's own reader with its snapshot in one read. @@ -46,7 +59,23 @@ impl Store { request: BindIntent::Named(request), }); } - self.bind_with(owner, BindIntent::Named(request), false) + self.bind_with( + owner, + BindIntent::Named(request), + MountPlace::default(), + false, + ) + } + /// [`Self::bind_named`] of a mount whose caller knows the Sandbox and + /// machine its daemon serves. + #[allow(clippy::result_large_err)] + pub fn bind_named_placed( + self: &Arc, + owner: OwnerClient, + request: NamedBindRequest, + place: MountPlace, + ) -> Result { + self.bind_with(owner, BindIntent::Named(request), place, false) } /// [`Self::bind`] for an SDK call's private Workspace: its reader comes /// from, and returns to, the Store's idle readers (#352 F-025 fix 4). @@ -56,13 +85,25 @@ impl Store { owner: OwnerClient, request: BindRequest, ) -> Result { - self.bind_with(owner, BindIntent::Id(request), true) + self.bind_with(owner, BindIntent::Id(request), MountPlace::default(), true) + } + /// [`Self::bind_private`] of a caller that knows the Sandbox and + /// machine the Workspace belongs to. + #[allow(clippy::result_large_err)] + pub fn bind_private_placed( + self: &Arc, + owner: OwnerClient, + request: BindRequest, + place: MountPlace, + ) -> Result { + self.bind_with(owner, BindIntent::Id(request), place, true) } #[allow(clippy::result_large_err)] fn bind_with( self: &Arc, owner: OwnerClient, request: BindIntent, + place: MountPlace, pooled: bool, ) -> Result { let mut phase = BindPhase::Snapshot; @@ -94,7 +135,7 @@ impl Store { // Admission before any root demand: a live removal is `Busy`, an // uncertain owner `Unresolved`, and the intent lives until this // Workspace's unmount deletes it. - let intent = crate::history::admission::mount_intent(workspace, &captured); + let intent = crate::history::admission::mount_intent(workspace, &captured, &place); match self.history().gc_register(&intent) { Ok(()) => gc_op = Some(intent.op_id), // A provider without admission cannot exclude a removal; it diff --git a/engine/crates/layerfs-store-service/tests/admission.rs b/engine/crates/layerfs-store-service/tests/admission.rs index d8db93e9c8..7889ea2250 100644 --- a/engine/crates/layerfs-store-service/tests/admission.rs +++ b/engine/crates/layerfs-store-service/tests/admission.rs @@ -50,6 +50,9 @@ fn a_mount_refuses_every_removal_through_the_service() { }; assert_eq!(holders[0].get_text("kind"), Some("mount")); assert_eq!(holders[0].get_text("sandbox"), Some("sandbox-9")); + assert_eq!(holders[0].get_text("machine"), Some("machine-9")); + let workspace = lookup::hex(&[9; 32]); + assert_eq!(holders[0].get_text("workspace"), Some(workspace.as_str())); let refused = deletion::delete_stack(&fixture.service.store, stack.id, 1_000) .expect_err("the mount holds"); diff --git a/engine/crates/layerfs-store-service/tests/golden/sdk_methods.txt b/engine/crates/layerfs-store-service/tests/golden/sdk_methods.txt index 0fb8409998..cb3af3dd9b 100644 --- a/engine/crates/layerfs-store-service/tests/golden/sdk_methods.txt +++ b/engine/crates/layerfs-store-service/tests/golden/sdk_methods.txt @@ -5,8 +5,8 @@ project.list_branches -> refused InvalidInput "pageSize must be in 1..=1000" nul branch.fork -> ok {kind: "Forked", branch: "feat", base: "", head: null} branch.fork -> ok {kind: "Forked", branch: "other", base: "", head: null} branch.fork -> refused ReservedName "\"main\" names the project's main line" null -branch.fork -> refused NameTaken "Branch feat already exists" null -branch.fork -> refused InvalidInput "`nope` is not a Commit or Layer identity" null +branch.fork -> refused NameTaken "name taken: NameHolder { kind: Branch, name: \"feat\", state: Live }" {holder: {kind: "branch", name: "feat", state: "live"}, source: "store"} +branch.fork -> refused NoSuchBranch "Branch nope does not exist" null fs.write -> ok {kind: "Committed", branch: "feat", head: "", commit: {id: "", branch: "feat", parent: null, secondParent: null, base: "", root: "", via: "fs", message: "first", mergedFrom: null, time: , logical: 43, newCanonical: 957, newStored: , newMetadata: , displaced: null, lww: [], lwwTruncated: false}} fs.write -> refused ReadOnly "main changes only through publish" null fs.write -> ok {kind: "UpToDate", branch: "feat", head: "", root: ""} @@ -68,7 +68,7 @@ branch.fork -> ok {kind: "Forked", branch: "right", base: "", head: null} fs.write -> ok {kind: "Committed", branch: "right", head: "", commit: {id: "", branch: "right", parent: null, secondParent: null, base: "", root: "", via: "fs", message: "Apply filesystem changes", mergedFrom: null, time: , logical: 42, newCanonical: 958, newStored: , newMetadata: , displaced: null, lww: [], lwwTruncated: false}} branch.merge -> ok {kind: "Merged", fastForward: false, branch: "both", head: "", root: "", sources: [{ref: "left", node: ""}, {ref: "right", node: ""}], mergeBase: "", conflicts: [], lww: [], conflictsTruncated: false, lwwTruncated: false, units: [], unitsTruncated: false} fs.list -> ok {kind: "ok", snapshot: "both@", root: "", path: "/", items: [{name: "a.txt", path: "/a.txt", type: "file", inode: 2}, {name: "blob.bin", path: "/blob.bin", type: "file", inode: 3}, {name: "dir", path: "/dir", type: "dir", inode: 4}, {name: "left.txt", path: "/left.txt", type: "file", inode: 328}, {name: "right.txt", path: "/right.txt", type: "file", inode: 392}], hasMore: false, nextPagePos: null, removed_count: 0, at: {id: "", kind: "Commit", branch: "both", root: ""}} -branch.merge -> refused NameTaken "Branch both already exists" null +branch.merge -> refused NameTaken "name taken: NameHolder { kind: Branch, name: \"both\", state: Live }" {holder: {kind: "branch", name: "both", state: "live"}, source: "store"} branch.merge -> refused InvalidInput "merge takes two different sources" null branch.merge -> refused ReservedName "\"main\" names the project's main line" null branch.publish -> ok {kind: "Added", source: {branch: "feat", commit: ""}, publishedLayer: {overwroteCount: 0, logical: 55, id: "", parent: "", root: "", sourceBranch: "feat", sourceCommit: ""}, basedOn: "", overwroteCount: 0, overwrote: [], overwroteHasMore: false} diff --git a/engine/crates/layerfs-store-service/tests/sdk_path_whiteouts.rs b/engine/crates/layerfs-store-service/tests/sdk_path_whiteouts.rs index 6fff9e6b2c..3b19bf76a9 100644 --- a/engine/crates/layerfs-store-service/tests/sdk_path_whiteouts.rs +++ b/engine/crates/layerfs-store-service/tests/sdk_path_whiteouts.rs @@ -76,41 +76,67 @@ fn a_one_shot_commit_after_remove_stays_absent() { } #[test] -fn a_workspace_commit_bound_before_the_marker_materializes_it() { - // Bound first, then the marker is written before the Commit: the mount - // saw no whiteout, so the Commit path itself must remove the inherited - // entry rather than silently resurrect it. +fn a_marker_under_a_live_mount_is_refused_and_materializes_after_it_closes() { + // Admission refuses while any mount intent holds the + // project, so a marker can never appear under a live Workspace. The Commit + // path still has to materialize a marker written before the Workspace + // binds, which the second Workspace below commits through. let fixture = Fixture::new("t55-workspace", |source| { - fs::write(source.join("a"), "a\n").unwrap(); + fs::write(source.join("a"), "a +").unwrap(); 1 }); fixture.fork("work"); fixture.workspace_commit("work", &[Change::Create("/w", b"w")], 31, || { - remove(&fixture, "/a"); + let refusal = fixture + .try_call("project.remove_file", vec![("path", text("/a"))]) + .expect_err("a marker under a live mount"); + assert_eq!(refusal.code, "MountsActive", "{refusal:?}"); + let holders = match refusal.detail.get("holders") { + Some(SdkValue::List(holders)) => holders, + other => panic!("MountsActive detail without holders: {other:?}"), + }; + assert_eq!(holders.len(), 1, "{holders:?}"); + assert_eq!(holders[0].get_text("kind"), Some("mount"), "{holders:?}"); + assert_eq!( + holders[0].get_text("workspace"), + Some("1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f"), + "{holders:?}" + ); }); + remove(&fixture, "/a"); + // A Workspace bound after the marker materializes the whiteout into its + // overlay: a Commit of a change elsewhere must not resurrect /a. + fixture.workspace_commit("work", &[Change::Create("/v", b"v")], 33, || {}); absent(&fixture, "work", "/a"); assert_eq!(visible(&fixture, "work", "/w"), "w"); + assert_eq!(visible(&fixture, "work", "/v"), "v"); let listed = fixture.call( "fs.list", vec![("branch", text("work")), ("path", text("/"))], ); - assert!(!paths(&listed).contains(&"/a")); + let names = paths(&listed); + assert!(!names.contains(&"/a"), "{names:?}"); + assert!(names.contains(&"/w") && names.contains(&"/v"), "{names:?}"); fixture.cleanup(); } #[test] -fn a_workspace_commit_keeps_a_re_creation_written_before_the_marker() { - // The workspace rewrote the inherited file, then the marker was written, - // then the Commit: the rewrite is a re-creation and stays visible. +fn a_workspace_commit_keeps_a_re_creation_above_the_marker() { + // The marker comes first, as admission requires while no mount is live. + // The Workspace then binds below the frontier, materializes the whiteout, + // and writes the path again above it: the re-creation stays visible. let fixture = Fixture::new("t55-workspace-recreate", |source| { - fs::write(source.join("a"), "a\n").unwrap(); + fs::write(source.join("a"), "a +").unwrap(); 1 }); fixture.fork("work"); - fixture.workspace_commit("work", &[Change::Write("/a", b"again\n")], 32, || { - remove(&fixture, "/a"); - }); - assert_eq!(visible(&fixture, "work", "/a"), "again\n"); + remove(&fixture, "/a"); + fixture.workspace_commit("work", &[Change::Create("/a", b"again +")], 32, || {}); + assert_eq!(visible(&fixture, "work", "/a"), "again +"); fixture.cleanup(); } diff --git a/tools/ci/test_store_ext4.sh b/tools/ci/test_store_ext4.sh new file mode 100755 index 0000000000..7497dbf955 --- /dev/null +++ b/tools/ci/test_store_ext4.sh @@ -0,0 +1,327 @@ +#!/usr/bin/env bash +# Store tests need a filesystem that carries SQLite's locks. +# +# Why this exists +# --------------- +# A Store opens directly only inside a private (0700) directory, owned by this +# user, on a local filesystem whose locks reach every opener: ext4, xfs or +# btrfs on Linux; apfs or hfs on macOS. Anything else is `Unsupported` +# (engine/crates/layerfs-store-service/src/kernel_guard.rs), because SQLite's +# WAL locks and the writers' directory flock cannot coordinate across kernels +# or on tmpfs, overlay, FUSE or network mounts. +# +# The Store suites place their Stores in `std::env::temp_dir()` (TMPDIR) and in +# `env!("CARGO_TARGET_TMPDIR")` (CARGO_TARGET_DIR/tmp). On a host whose /tmp is +# tmpfs -- or inside a container whose checkout is an overlay -- the guard +# refuses every Store and suites such as `layerfs-store-service --test +# kernel_guard` fail with "does not carry SQLite locks". That is an environment +# failure, not a product failure. +# +# This script requires LAYERFS_TEST_TMPDIR on ext4, xfs or btrfs (apfs or hfs on +# macOS), refuses anything else before cargo starts, and points TMPDIR, +# CARGO_TARGET_DIR and CARGO_HOME at it. See +# docs/architecture/engine/store/testing.md. +# +# Usage +# LAYERFS_TEST_TMPDIR=/mnt/ext4/layerfs-store-tests tools/ci/test_store_ext4.sh --quick +# LAYERFS_TEST_TMPDIR=/mnt/ext4/layerfs-store-tests tools/ci/test_store_ext4.sh +# tools/ci/test_store_ext4.sh --list +# +# Options +# --quick a small cross-crate subset (heads, sqlite_publication, +# kernel_guard, commit_pipeline, create_directory, store_family) +# --full every Store suite (the default) +# --list print the cargo commands, run nothing +# --help this text +# +# Environment +# LAYERFS_TEST_TMPDIR required; must be on ext4, xfs or btrfs (Linux) +# or apfs or hfs (macOS) +# LAYERFS_TEST_JOBS cargo -j; default min(nproc, 16) +# LAYERFS_TEST_CARGO_HOME default $LAYERFS_TEST_TMPDIR/cargo-home +# LAYERFS_TEST_CARGO_TARGET_DIR +# default $LAYERFS_TEST_TMPDIR/target +# LAYERFS_TEST_POSTGRES_URL libpq connection string; enables the postgresql +# feature on every suite and the PostgreSQL cases +# Arguments after `--` are appended to every `cargo test` (e.g. -- --nocapture). +# +# Exit status: 0 every suite passed; 1 at least one failed; 2 wrong command line +# or a refused LAYERFS_TEST_TMPDIR; 127 cargo is not installed. +set -euo pipefail + +root=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd) +cd "$root" + +usage() { + sed -n '2,/^set -euo pipefail$/p' "${BASH_SOURCE[0]}" | sed '$d' | sed 's/^# \{0,1\}//' +} + +refuse() { + printf 'test_store_ext4: %s\n' "$1" >&2 + shift || true + for line in "$@"; do printf '%s\n' "$line" >&2; done + exit 2 +} + +mode=full +list_only=0 +passthrough=() +while [ "$#" -gt 0 ]; do + case "$1" in + --quick) mode=quick ;; + --full) mode=full ;; + --list) list_only=1 ;; + -h|--help) usage; exit 0 ;; + --) shift; passthrough=("$@"); break ;; + *) refuse "unknown argument: $1 (try --help)" ;; + esac + shift +done + +# ---- The directory and its filesystem ------------------------------------- + +dir=${LAYERFS_TEST_TMPDIR:-} +if [ -z "$dir" ]; then + refuse "LAYERFS_TEST_TMPDIR is not set." \ + "" \ + "The Store suites need their temporary Stores on a filesystem that carries" \ + "SQLite's locks: ext4, xfs or btrfs on Linux; apfs or hfs on macOS." \ + "Choose such a directory and re-run, for example:" \ + "" \ + " LAYERFS_TEST_TMPDIR=/mnt/ext4/layerfs-store-tests $0 --quick" \ + "" \ + "Inside a Docker Sandbox the run directory is ext4 (\$HOME and" \ + "/layerfs/data/machine/native/run/); /tmp is tmpfs there." +fi + +case "$dir" in + /*) ;; + *) dir="$PWD/$dir" ;; +esac +if command -v realpath >/dev/null 2>&1; then + dir=$(realpath -m -- "$dir") +fi + +mkdir -p -- "$dir" 2>/dev/null || refuse "cannot create LAYERFS_TEST_TMPDIR=$dir" +[ -d "$dir" ] || refuse "LAYERFS_TEST_TMPDIR=$dir is not a directory" + +uname_s=$(uname -s 2>/dev/null || printf 'Linux') + +filesystem_type() { + local target=$1 found= + if [ "$uname_s" = Darwin ]; then + # macOS: the mount table names the filesystem in parentheses; `stat -f %T` + # is a fallback for a mount line this cannot parse. + local device type + device=$(df -P "$target" 2>/dev/null | awk 'NR == 2 { print $1 }') + type=$(mount 2>/dev/null | awk -v device="$device" '$1 == device { print; exit }' \ + | sed -n 's/.*(\([^,)]*\).*/\1/p') + if [ -n "$type" ]; then + printf '%s\n' "$type" + return 0 + fi + stat -f %T "$target" 2>/dev/null || true + return 0 + fi + if command -v findmnt >/dev/null 2>&1; then + found=$(findmnt -n -o FSTYPE --target "$target" 2>/dev/null || true) + if [ -n "$found" ]; then + printf '%s\n' "$found" + return 0 + fi + fi + found=$(stat -f -c %T "$target" 2>/dev/null || true) + case "$found" in ext2/ext3) found=ext4 ;; esac + printf '%s\n' "$found" +} + +if [ "$uname_s" = Darwin ]; then + supported='apfs hfs' + supported_text='apfs or hfs' +else + supported='ext4 xfs btrfs' + supported_text='ext4, xfs or btrfs' +fi + +refuse_filesystem() { + local target=$1 label=$2 found=$3 + refuse "$label=$target is on '$found', which cannot carry a Store." \ + "" \ + "Direct Store access needs a local filesystem that carries SQLite's locks:" \ + "$supported_text. The kernel guard refuses tmpfs, overlay, FUSE and network" \ + "mounts before any Store file is opened, so the suites would fail with" \ + "'does not carry SQLite locks' -- an environment failure, not a product one." \ + "" \ + "Point LAYERFS_TEST_TMPDIR at a supported directory, for example:" \ + " LAYERFS_TEST_TMPDIR=/mnt/ext4/layerfs-store-tests $0 --quick" \ + "" \ + "Inside a Docker Sandbox the run directory is ext4 (\$HOME and" \ + "/layerfs/data/machine/native/run/); /tmp is tmpfs there." +} + +check_supported() { + local target=$1 label=$2 found + found=$(filesystem_type "$target") + case " $supported " in + *" ${found:-unknown} "*) ;; + *) refuse_filesystem "$target" "$label" "${found:-unknown}" ;; + esac +} + +check_supported "$dir" LAYERFS_TEST_TMPDIR + +probe="$dir/.layerfs-store-tests.$$" +if ! ( : > "$probe" ) 2>/dev/null; then + refuse "LAYERFS_TEST_TMPDIR=$dir is not writable by $(id -un 2>/dev/null || echo this user)." +fi +rm -f -- "$probe" + +# ---- Point the tests at it ------------------------------------------------ + +export TMPDIR="$dir/tmp" +export CARGO_TARGET_DIR="${LAYERFS_TEST_CARGO_TARGET_DIR:-$dir/target}" +export CARGO_HOME="${LAYERFS_TEST_CARGO_HOME:-$dir/cargo-home}" +mkdir -p -- "$TMPDIR" "$CARGO_TARGET_DIR" "$CARGO_HOME" 2>/dev/null \ + || refuse "cannot create TMPDIR, CARGO_TARGET_DIR and CARGO_HOME under $dir" + +# Unix-domain sockets live under TMPDIR, and Linux rejects a socket path of 108 +# bytes or more. A Sandbox run directory is long enough that its own path plus +# a test directory would overrun that, so TMPDIR itself is short: a private +# wrapper under the system temporary directory whose `tmp` entry is a symlink +# to the real one. statfs follows the symlink, so the Stores still land on +# `$dir` filesystem; the wrapper holds nothing but the link. +system_tmp=${LAYERFS_TEST_SYSTEM_TMP:-/tmp} +if [ -d "$system_tmp" ] && [ -w "$system_tmp" ]; then + tmp_wrapper=$(mktemp -d "$system_tmp/layerfs-store-tests.XXXXXX") \ + || refuse "cannot create a short TMPDIR wrapper under $system_tmp" + ln -s "$dir/tmp" "$tmp_wrapper/tmp" \ + || { rm -rf -- "$tmp_wrapper"; refuse "cannot link $system_tmp/.../tmp to $dir/tmp"; } + export TMPDIR="$tmp_wrapper/tmp" + trap 'if [ -n "${tmp_wrapper:-}" ]; then rm -rf -- "$tmp_wrapper"; fi' EXIT +else + export TMPDIR="$dir/tmp" +fi + +# `CARGO_TARGET_TMPDIR` follows CARGO_TARGET_DIR, and the tests also read TMPDIR: +# both must be on the supported filesystem, including when they are overridden. +check_supported "$TMPDIR" TMPDIR +check_supported "$CARGO_TARGET_DIR" CARGO_TARGET_DIR + +# The pinned fuser dependency is fetched over git. The git CLI honours the +# host's proxy and credential configuration where libgit2 does not, and some +# TLS-inspecting hosts need verification off for that fetch. Scoped to this +# process; not a production setting. +export CARGO_NET_GIT_FETCH_WITH_CLI=true +export GIT_SSL_NO_VERIFY=true + +# The official Rust image keeps rustup and the toolchain outside HOME. +if [ -z "${RUSTUP_HOME:-}" ] && [ -d /usr/local/rustup ] && [ -x /usr/local/cargo/bin/rustup ]; then + export RUSTUP_HOME=/usr/local/rustup +fi + +if ! command -v cargo >/dev/null 2>&1; then + for candidate in "$CARGO_HOME/bin" "${HOME:-}/.cargo/bin" /usr/local/cargo/bin; do + if [ -x "$candidate/cargo" ]; then + PATH="$candidate:$PATH" + export PATH + break + fi + done +fi +if ! command -v cargo >/dev/null 2>&1; then + refuse "cargo is not installed or not on PATH; install Rust 1.85.1 (rustup) first." +fi + +cargo_cmd=(cargo) +if command -v rustup >/dev/null 2>&1 && rustup toolchain list 2>/dev/null | grep -q '^1\.85\.1'; then + cargo_cmd=(cargo +1.85.1) +fi + +if [ -n "${LAYERFS_TEST_JOBS:-}" ]; then + case "$LAYERFS_TEST_JOBS" in + ''|*[!0-9]*) refuse "LAYERFS_TEST_JOBS must be a positive integer, not '$LAYERFS_TEST_JOBS'." ;; + esac + jobs=$LAYERFS_TEST_JOBS +else + jobs=$(getconf _NPROCESSORS_ONLN 2>/dev/null || printf '4') + if [ "$jobs" -gt 16 ]; then + jobs=16 + fi +fi +[ "$jobs" -ge 1 ] || refuse "LAYERFS_TEST_JOBS must be a positive integer, not '$jobs'." + +# ---- The suites ----------------------------------------------------------- + +ran=0 +failed=0 + +show_command() { + printf ' ' + printf ' %q' "$@" + printf '\n' +} + +run_cargo() { + local package=$1 + shift + local -a cmd=( "${cargo_cmd[@]}" test --locked -j "$jobs" -p "$package" ) + if [ -n "${LAYERFS_TEST_POSTGRES_URL:-}" ]; then + cmd+=( --features postgresql ) + fi + cmd+=( "$@" ) + if [ "${#passthrough[@]}" -gt 0 ]; then + cmd+=( -- "${passthrough[@]}" ) + fi + show_command "${cmd[@]}" + if [ "$list_only" -eq 1 ]; then + return 0 + fi + printf '\n==> %s:%s\n' "$package" "$*" + ran=$((ran + 1)) + if "${cmd[@]}"; then + printf 'PASS %s\n' "$package" + else + failed=$((failed + 1)) + printf 'FAIL %s\n' "$package" >&2 + fi +} + +printf '%s\n' \ + "Store test harness" \ + " repository: $root" \ + " LAYERFS_TEST_TMPDIR: $dir ($(filesystem_type "$dir"))" \ + " TMPDIR: $TMPDIR" \ + " CARGO_TARGET_DIR: $CARGO_TARGET_DIR" \ + " CARGO_HOME: $CARGO_HOME" \ + " jobs (-j): $jobs" \ + " mode: $mode" \ + " PostgreSQL: $([ -n "${LAYERFS_TEST_POSTGRES_URL:-}" ] && echo 'on (LAYERFS_TEST_POSTGRES_URL set)' || echo 'off (LAYERFS_TEST_POSTGRES_URL unset; PostgreSQL cases print NOT_RUN)')" + +if [ "$mode" = quick ]; then + run_cargo layerfs-persistence --test heads --test sqlite_publication + run_cargo layerfs-store-service --test kernel_guard --test commit_pipeline + run_cargo layerfs-store --test create_directory + run_cargo layerfs-api --test store_family +else + run_cargo layerfs-persistence + run_cargo layerfs-store-service + run_cargo layerfs-store + api_store_targets=() + for file in api/crates/layerfs-api/tests/store_*.rs; do + [ -f "$file" ] || continue + target=${file##*/} + api_store_targets+=( --test "${target%.rs}" ) + done + [ "${#api_store_targets[@]}" -gt 0 ] \ + || refuse "no api/crates/layerfs-api/tests/store_*.rs targets found; is $root the repository root?" + run_cargo layerfs-api "${api_store_targets[@]}" +fi + +if [ "$list_only" -eq 1 ]; then + exit 0 +fi + +printf '\n%d suite(s), %d failed\n' "$ran" "$failed" +if [ "$failed" -ne 0 ]; then + exit 1 +fi