Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions .agents/skills/layerfs-sdk-observe/references/tracing.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,16 @@ Python, direct `layerfs_api::call`) appends one line to
and `LAYERFS_TRACE` / `LAYERFS_TRACE_STEP` do not affect it.

```json
{"v":1,"at":1793000004120,"ms":212,"client":"node","argv":["file","write","demo/app","main","/index.ts","<5321 bytes>"],"outcome":"ok","kind":"Committed","commit":"<66 hex>","tag":"dsh:s_4d2a:a91e"}
{"v":1,"at":1793000004120,"ms":212,"client":"node","argv":["file","write","demo/app","main","<8 bytes>","<5321 bytes>"],"outcome":"ok","kind":"Committed","commit":"<66 hex>","tag":"dsh:s_4d2a:a91e"}
```

It keeps 1.1.0's redaction rule (values cut to 200 characters; contents,
JSON, commands, messages, edit strings, passwords and URLs as byte counts)
and drops the daemon telemetry: no `sizes`, `scope` or `daemon`. `argv` is
JSON, commands, messages, edit strings, passwords and URLs as byte counts;
a path argument as the byte count of its normalized form, one leading `/`
stripped, so `/a` and `a` are both `<1 bytes>`; a glob or grep `pattern` by
its own bytes) and drops the daemon telemetry: no `sizes`, `scope` or
`daemon`. A refusal is logged as its code only: its message and `detail` are
never traced, so a `Removed` path stays out of the line. `argv` is
the call as CLI words (`argv[0]`/`argv[1]` are the family and call),
`outcome` is `"ok"` or the refusal code, `kind` and `commit`/`layer` come
from the result, `client` is `cli`/`node`/`python`/`rust`, and `tag` is the
Expand Down
4 changes: 3 additions & 1 deletion api/crates/layerfs-api/src/branch/mod.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
//! The `branch` family: 8 calls, one file each.
//! The `branch` family: 9 calls, one file each.
mod commits;
mod diff;
mod fork;
Expand All @@ -7,6 +7,7 @@ mod get_commit;
mod list;
mod merge;
mod publish;
mod remove;

use crate::calls::Calls;

Expand All @@ -21,5 +22,6 @@ pub(crate) fn calls() -> Calls {
merge::CALL,
publish::CALL,
diff::CALL,
remove::CALL,
]
}
28 changes: 28 additions & 0 deletions api/crates/layerfs-api/src/branch/remove.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
//! `branch.remove`: soft-remove one Branch through its Store marker.
use crate::calls::table::Kind::{Name, Project};
use crate::calls::table::{a, call, Call};
use crate::calls::Context;
use layerfs_bridge::control::SdkValue;
use layerfs_home::outcome::Outcome;
use layerfs_store::calls::branch::{remove, BranchRemove};

/// Its table entry.
pub(crate) const CALL: Call = call(
"branch",
"remove",
&[a("project", Project), a("branch", Name)],
&[],
"soft-remove one Branch; its name stays taken until compaction",
run,
);

/// Runs `branch.remove`.
fn run(context: &mut Context<'_>, args: &SdkValue) -> Outcome {
let text = |name: &str| args.get_text(name).map(str::to_owned);
let request = BranchRemove {
project: text("project").unwrap_or_default(),
branch: text("branch").unwrap_or_default(),
};
let (home, events) = context.parts();
remove(home, events, &request)
}
1 change: 1 addition & 0 deletions api/crates/layerfs-api/src/calls/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ pub use check::size;
pub use context::Context;
pub use dispatch::{call, call_scoped, home, Client};
pub use layerfs_home::json;
pub use render::REDACTED;
pub use scope::Scope;
pub use table::{find, table_json, Arg, Call, CallRef, Calls, Families, Family, Kind, Run};
pub use text::call_json;
97 changes: 94 additions & 3 deletions api/crates/layerfs-api/src/calls/render.rs
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,46 @@ use layerfs_bridge::control::{SdkRefusal, SdkValue};
use layerfs_home::outcome::Outcome;

/// The `Text` arguments logged only as `<N bytes>`: exec command text,
/// Commit messages, edit strings, Store passwords and connection URLs that
/// may embed `user:pass@`. A new call with such an argument adds its name.
pub const REDACTED: [&str; 6] = ["command", "message", "old", "new", "password", "url"];
/// Commit messages, edit strings, Store passwords, connection URLs that may
/// embed `user:pass@`, every path argument (`path`, `left_path`,
/// `right_path`, `from_path`, `to_path`, `path_prefix`) and a glob or grep
/// `pattern`. A path is counted in its normalized form ([`PATHS`]), so a
/// `project.remove_file` or `file.*` path never enters the call log (#41
/// §4.3). A new call with such an argument adds its name.
pub const REDACTED: [&str; 13] = [
"command",
"message",
"old",
"new",
"password",
"url",
"path",
"left_path",
"right_path",
"from_path",
"to_path",
"path_prefix",
"pattern",
];

/// The arguments that name a path: they log the length of the normalized
/// path, one leading `/` stripped, so `/a` and `a` count the same and a root
/// `/` counts as 0 (#41 §4.3). A `pattern` is not a path and keeps every
/// byte it has.
const PATHS: [&str; 6] = [
"path",
"left_path",
"right_path",
"from_path",
"to_path",
"path_prefix",
];

/// A path argument's logged byte length: the §4.3 normalization (strip one
/// leading `/`) applied before counting.
fn path_len(text: &str) -> usize {
text.strip_prefix('/').unwrap_or(text).len()
}

/// The most characters a logged value keeps.
const CUT: usize = 200;
Expand Down Expand Up @@ -46,6 +83,7 @@ fn word(name: &str, kind: Kind, value: &SdkValue) -> Option<SdkValue> {
(Kind::Content, SdkValue::Text(text)) => bytes(text.len()),
(Kind::Content, SdkValue::Bytes(raw)) => bytes(raw.len()),
(Kind::Content | Kind::Json, value) => bytes(layerfs_home::json::print(value).len()),
(Kind::Text, SdkValue::Text(text)) if PATHS.contains(&name) => bytes(path_len(text)),
(Kind::Text, SdkValue::Text(text)) if REDACTED.contains(&name) => bytes(text.len()),
(_, SdkValue::Text(text)) => SdkValue::Text(cut(text)),
(_, SdkValue::Int(n)) => SdkValue::Text(n.to_string()),
Expand Down Expand Up @@ -187,3 +225,56 @@ pub fn line(
}
SdkValue::Map(fields)
}

#[cfg(test)]
mod tests {
use super::*;

#[test]
fn every_path_argument_name_is_redacted() {
for name in [
"path",
"left_path",
"right_path",
"from_path",
"to_path",
"path_prefix",
"pattern",
] {
assert!(REDACTED.contains(&name), "{name} is not redacted");
}
for name in ["project", "branch", "name", "commit", "content", "changes"] {
assert!(!REDACTED.contains(&name), "{name} is redacted");
}
}

#[test]
fn a_path_logs_the_byte_length_of_its_normalized_form() {
// `/a` and `a` are the same path (§4.3), so they log the same count;
// the root `/` normalizes to the empty relative path.
for (text, len) in [
("/base.txt", 8),
("base.txt", 8),
("/a", 1),
("a", 1),
("/", 0),
] {
let value = SdkValue::text(text);
assert_eq!(
word("path", Kind::Text, &value),
Some(SdkValue::text(format!("<{len} bytes>"))),
"{text}"
);
}
// A glob pattern is not a path and keeps every byte it has.
assert_eq!(
word("pattern", Kind::Text, &SdkValue::text("*.txt")),
Some(SdkValue::text("<5 bytes>"))
);
// Text that is not a path is still its own (cut) text.
assert_eq!(
word("branch", Kind::Text, &SdkValue::text("/main")),
Some(SdkValue::text("/main"))
);
}
}
5 changes: 5 additions & 0 deletions api/crates/layerfs-api/src/calls/scope.rs
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,11 @@ impl Scope {
| ("file", "revision") => {
return Err(out("history"));
}
// GC retires or compacts a whole entity, never one folder:
// a scope refuses these instead of widening them (§10).
("branch", "remove") | ("project", "delete" | "remove_file") | ("store", "compact") => {
return Err(out(name));
}
("file", _) => {
bound(&args)?;
let paths: &[&str] = match call {
Expand Down
2 changes: 1 addition & 1 deletion api/crates/layerfs-api/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ pub use layerfs_sandbox::{
BoundWorkspace, MountFailure, MountedWorkspace, Unmounted, WorkspaceApi,
};

/// The ten families, in the order help lists them: 73 calls, the same
/// The ten families, in the order help lists them: 77 calls, the same
/// from the `layerfs` binary, Node and Python.
pub fn families() -> Families {
&[
Expand Down
24 changes: 24 additions & 0 deletions api/crates/layerfs-api/src/project/delete.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
//! `project.delete`: retire one project in its Store and remove its home entry.
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",
"delete",
&[a("project", Project)],
&[],
"retire one project in its Store and remove its home entry",
run,
);

/// Runs `project.delete`.
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::delete(home, events, &project)
}
6 changes: 5 additions & 1 deletion api/crates/layerfs-api/src/project/mod.rs
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
//! The `project` family: 6 calls, one file each.
//! The `project` family: 8 calls, one file each.
mod delete;
mod export;
mod get;
mod init;
mod list;
mod remove;
mod remove_file;
mod stats;

use crate::calls::Calls;
Expand All @@ -16,6 +18,8 @@ pub(crate) fn calls() -> Calls {
get::CALL,
stats::CALL,
export::CALL,
delete::CALL,
remove_file::CALL,
remove::CALL,
]
}
29 changes: 29 additions & 0 deletions api/crates/layerfs-api/src/project/remove_file.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
//! `project.remove_file`: hide one absolute path from every node at or below
//! its marker frontier.
use crate::calls::table::Kind::{Project, Text};
use crate::calls::table::{a, call, Call};
use crate::calls::Context;
use layerfs_bridge::control::SdkValue;
use layerfs_home::outcome::Outcome;
use layerfs_store::calls::project::{remove_file, ProjectRemoveFile};

/// Its table entry.
pub(crate) const CALL: Call = call(
"project",
"remove_file",
&[a("project", Project), a("path", Text)],
&[],
"hide one absolute path from every node at or below its marker frontier",
run,
);

/// Runs `project.remove_file`.
fn run(context: &mut Context<'_>, args: &SdkValue) -> Outcome {
let text = |name: &str| args.get_text(name).map(str::to_owned);
let request = ProjectRemoveFile {
project: text("project").unwrap_or_default(),
path: text("path").unwrap_or_default(),
};
let (home, events) = context.parts();
remove_file(home, events, &request)
}
24 changes: 24 additions & 0 deletions api/crates/layerfs-api/src/store/compact.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
//! `store.compact`: reclaim dead bytes from one sqlite Store.
use crate::calls::table::Kind::Name;
use crate::calls::table::{a, call, Call};
use crate::calls::Context;
use layerfs_bridge::control::SdkValue;
use layerfs_home::names::StoreName;
use layerfs_home::outcome::Outcome;

/// Its table entry.
pub(crate) const CALL: Call = call(
"store",
"compact",
&[a("name", Name)],
&[],
"reclaim dead bytes from one sqlite Store",
run,
);

/// Runs `store.compact`.
fn run(context: &mut Context<'_>, args: &SdkValue) -> Outcome {
let name = StoreName::parse(args.get_text("name").unwrap_or(""))?;
let (home, events) = context.parts();
layerfs_control::store::compact(home, events, &name)
}
4 changes: 3 additions & 1 deletion api/crates/layerfs-api/src/store/mod.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
//! The `store` family: 12 calls, one file each (H1: push and pull replace
//! The `store` family: 13 calls, one file each (H1: push and pull replace
//! move; attach and detach supersede #536 C4).
mod attach;
mod compact;
mod connect;
mod create;
mod detach;
Expand Down Expand Up @@ -29,6 +30,7 @@ pub(crate) fn calls() -> Calls {
push::CALL,
pull::CALL,
remove::CALL,
compact::CALL,
disconnect::CALL,
]
}
10 changes: 10 additions & 0 deletions api/crates/layerfs-api/tests/calls_scope.rs
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,16 @@ fn a_scope_refuses_every_call_it_does_not_cover() {
("store.remove", &[("name", t("shop"))]),
("store.list", &[]),
("project.remove", &[("project", t("shop/api"))]),
(
"branch.remove",
&[("project", t("shop/api")), ("branch", t("main"))],
),
("project.delete", &[("project", t("shop/api"))]),
(
"project.remove_file",
&[("project", t("shop/api")), ("path", t("/web/a"))],
),
("store.compact", &[("name", t("shop"))]),
(
"project.init",
&[("project", t("shop/x")), ("folder", t("/tmp"))],
Expand Down
Loading
Loading