Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(storage): add pagination capability for ls/tree. support http-api/cli/python-sdk/go-sdk/typescript-sdk/mcp && CLI/MCP support ls sort capability (#4698)

baojun-zhang94ff079f514f
diff --git a/crates/ov_cli/README_CN.md b/crates/ov_cli/README_CN.md
index fd7ceb050..7eeb21930 100644
--- a/crates/ov_cli/README_CN.md
+++ b/crates/ov_cli/README_CN.md
@@ -272,6 +272,11 @@ ov find "authentication" --uri viking://resources/project --level 0,1
# 递归列目录
ov ls viking://resources --recursive
+# 按修改时间排序并分页
+ov ls viking://resources --offset 100 --limit 50 \
+ --sort-by mtime --sort-order desc
+ov tree viking://resources --offset 100 --limit 50
+
# 写入调用方提供的 tags,再按 tags 过滤或回显
ov write viking://resources/docs/api.md --content "# API" \
--tags team=search,env=prod
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rs
index 4ae57e6de..8c3106511 100644
--- a/crates/ov_cli/src/client.rs
+++ b/crates/ov_cli/src/client.rs
@@ -587,6 +587,10 @@ impl HttpClient {
abs_limit: i32,
show_all_hidden: bool,
node_limit: i32,
+ offset: i32,
+ limit: Option<i32>,
+ sort_by: Option<&str>,
+ sort_order: Option<&str>,
extra_fields: &[String],
tags: &[String],
include_tags: bool,
@@ -600,6 +604,18 @@ impl HttpClient {
("show_all_hidden".to_string(), show_all_hidden.to_string()),
("node_limit".to_string(), node_limit.to_string()),
];
+ if offset != 0 {
+ params.push(("offset".to_string(), offset.to_string()));
+ }
+ if let Some(limit) = limit {
+ params.push(("limit".to_string(), limit.to_string()));
+ }
+ if let Some(sort_by) = sort_by {
+ params.push(("sort_by".to_string(), sort_by.to_string()));
+ if let Some(sort_order) = sort_order {
+ params.push(("sort_order".to_string(), sort_order.to_string()));
+ }
+ }
for field in extra_fields {
params.push(("extra_fields".to_string(), field.clone()));
}
@@ -620,6 +636,8 @@ impl HttpClient {
show_all_hidden: bool,
node_limit: i32,
level_limit: i32,
+ offset: i32,
+ limit: Option<i32>,
extra_fields: &[String],
tags: &[String],
include_tags: bool,
@@ -632,6 +650,12 @@ impl HttpClient {
("node_limit".to_string(), node_limit.to_string()),
("level_limit".to_string(), level_limit.to_string()),
];
+ if offset != 0 {
+ params.push(("offset".to_string(), offset.to_string()));
+ }
+ if let Some(limit) = limit {
+ params.push(("limit".to_string(), limit.to_string()));
+ }
for field in extra_fields {
params.push(("extra_fields".to_string(), field.clone()));
}
@@ -2301,14 +2325,64 @@ mod tests {
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
- .ls("viking://resources", false, false, "agent", 256, false, 1, &[], &[], false)
+ .ls(
+ "viking://resources",
+ false,
+ false,
+ "agent",
+ 256,
+ false,
+ 20,
+ 4,
+ Some(5),
+ Some("mtime"),
+ Some("desc"),
+ &[],
+ &[],
+ false,
+ )
.await
.expect("ls request should succeed");
let request = request_rx.await.expect("request should be captured");
assert!(request.starts_with("GET /api/v1/fs/ls?"));
+ assert!(request.contains("node_limit=20"));
+ assert!(request.contains("offset=4"));
+ assert!(request.contains("limit=5"));
+ assert!(request.contains("sort_by=mtime"));
+ assert!(request.contains("sort_order=desc"));
assert!(!request.contains("tz="));
assert!(!request.contains("include_mod_time_iso="));
+
+ let (default_url, default_request_rx) = spawn_request_capture_server().await;
+ let default_client =
+ HttpClient::new(default_url, None, None, None, None, 5.0, false, None);
+ default_client
+ .ls(
+ "viking://resources",
+ false,
+ false,
+ "agent",
+ 256,
+ false,
+ 20,
+ 0,
+ None,
+ None,
+ None,
+ &[],
+ &[],
+ false,
+ )
+ .await
+ .expect("default ls request should succeed");
+ let default_request = default_request_rx
+ .await
+ .expect("default request should be captured");
+ assert!(!default_request.contains("offset="));
+ assert!(!default_request.contains("&limit="));
+ assert!(!default_request.contains("sort_by="));
+ assert!(!default_request.contains("sort_order="));
}
#[tokio::test]
@@ -2448,14 +2522,54 @@ mod tests {
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
- .tree("viking://resources", "agent", 256, false, 1, 3, &[], &[], false)
+ .tree(
+ "viking://resources",
+ "agent",
+ 256,
+ false,
+ 20,
+ 3,
+ 4,
+ Some(5),
+ &[],
+ &[],
+ false,
+ )
.await
.expect("tree request should succeed");
let request = request_rx.await.expect("request should be captured");
assert!(request.starts_with("GET /api/v1/fs/tree?"));
+ assert!(request.contains("node_limit=20"));
+ assert!(request.contains("offset=4"));
+ assert!(request.contains("limit=5"));
assert!(!request.contains("tz="));
assert!(!request.contains("include_mod_time_iso="));
+
+ let (default_url, default_request_rx) = spawn_request_capture_server().await;
+ let default_client =
+ HttpClient::new(default_url, None, None, None, None, 5.0, false, None);
+ default_client
+ .tree(
+ "viking://resources",
+ "agent",
+ 256,
+ false,
+ 20,
+ 3,
+ 0,
+ None,
+ &[],
+ &[],
+ false,
+ )
+ .await
+ .expect("default tree request should succeed");
+ let default_request = default_request_rx
+ .await
+ .expect("default request should be captured");
+ assert!(!default_request.contains("offset="));
+ assert!(!default_request.contains("&limit="));
}
#[tokio::test]
diff --git a/crates/ov_cli/src/commands/filesystem.rs b/crates/ov_cli/src/commands/filesystem.rs
index bca35f6c2..456284ca7 100644
--- a/crates/ov_cli/src/commands/filesystem.rs
+++ b/crates/ov_cli/src/commands/filesystem.rs
@@ -171,6 +171,10 @@ pub async fn ls(
abs_limit: i32,
show_all_hidden: bool,
node_limit: i32,
+ offset: i32,
+ limit: Option<i32>,
+ sort_by: Option<&str>,
+ sort_order: Option<&str>,
output_format: OutputFormat,
compact: bool,
fields: Option<Vec<String>>,
@@ -188,6 +192,10 @@ pub async fn ls(
abs_limit,
show_all_hidden,
node_limit,
+ offset,
+ limit,
+ sort_by,
+ sort_order,
&extra,
tags,
fields.as_ref().is_some_and(|items| items.iter().any(|item| item == "tags")) || !tags.is_empty(),
@@ -205,6 +213,8 @@ pub async fn tree(
show_all_hidden: bool,
node_limit: i32,
level_limit: i32,
+ offset: i32,
+ limit: Option<i32>,
output_format: OutputFormat,
compact: bool,
simple: bool,
@@ -220,6 +230,8 @@ pub async fn tree(
show_all_hidden,
node_limit,
level_limit,
+ offset,
+ limit,
&extra,
tags,
fields.as_ref().is_some_and(|items| items.iter().any(|item| item == "tags")) || !tags.is_empty(),
diff --git a/crates/ov_cli/src/handlers.rs b/crates/ov_cli/src/handlers.rs
index 246cc0b15..6d77b6fba 100644
--- a/crates/ov_cli/src/handlers.rs
+++ b/crates/ov_cli/src/handlers.rs
@@ -1644,6 +1644,10 @@ pub async fn handle_ls(
abs_limit: i32,
show_all_hidden: bool,
node_limit: i32,
+ offset: i32,
+ limit: Option<i32>,
+ sort_by: Option<String>,
+ sort_order: Option<String>,
fields: Option<Vec<String>>,
tags: Vec<String>,
ctx: CliContext,
@@ -1662,6 +1666,18 @@ pub async fn handle_ls(
if show_all_hidden {
params.push("-a".to_string());
}
+ if offset != 0 {
+ params.push(format!("--offset {}", offset));
+ }
+ if let Some(limit) = limit {
+ params.push(format!("--limit {}", limit));
+ }
+ if let Some(sort_by) = &sort_by {
+ params.push(format!("--sort-by {}", sort_by));
+ }
+ if let Some(sort_order) = &sort_order {
+ params.push(format!("--sort-order {}", sort_order));
+ }
if !tags.is_empty() {
params.push(format!("--tags {}", tags.join(",")));
}
@@ -1685,6 +1701,10 @@ pub async fn handle_ls(
abs_limit,
show_all_hidden,
node_limit,
+ offset,
+ limit,
+ sort_by.as_deref(),
+ sort_order.as_deref(),
ctx.output_format,
ctx.compact,
fields,
@@ -1698,6 +1718,8 @@ pub async fn handle_tree(
abs_limit: i32,
show_all_hidden: bool,
node_limit: i32,
+ offset: i32,
+ limit: Option<i32>,
level_limit: i32,
simple: bool,
fields: Option<Vec<String>>,
@@ -1716,6 +1738,12 @@ pub async fn handle_tree(
if simple {
params.push("-s".to_string());
}
+ if offset != 0 {
+ params.push(format!("--offset {}", offset));
+ }
+ if let Some(limit) = limit {
+ params.push(format!("--limit {}", limit));
+ }
if !tags.is_empty() {
params.push(format!("--tags {}", tags.join(",")));
}
@@ -1738,6 +1766,8 @@ pub async fn handle_tree(
show_all_hidden,
node_limit,
level_limit,
+ offset,
+ limit,
ctx.output_format,
ctx.compact,
simple,
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rs
index 7f1425fa4..2f2aec367 100644
--- a/crates/ov_cli/src/main.rs
+++ b/crates/ov_cli/src/main.rs
@@ -523,13 +523,41 @@ enum Commands {
#[arg(
long = "node-limit",
short = 'n',
- alias = "limit",
default_value = "256",
value_parser = clap::value_parser!(i32).range(0..),
value_name = "n",
help_heading = "Common options"
)]
node_limit: i32,
+ /// Number of visible entries to skip
+ #[arg(
+ long,
+ default_value = "0",
+ value_parser = clap::value_parser!(i32).range(0..),
+ value_name = "n",
+ help_heading = "Common options"
+ )]
+ offset: i32,
+ /// Maximum number of visible entries to return
+ #[arg(
+ long,
+ value_parser = clap::value_parser!(i32).range(1..),
+ value_name = "n",
+ help_heading = "Common options"
+ )]
+ limit: Option<i32>,
+ /// Sort entries by name or modification time
+ #[arg(long, value_parser = ["name", "mtime"], value_name = "field", help_heading = "Common options")]
+ sort_by: Option<String>,
+ /// Sort direction
+ #[arg(
+ long,
+ requires = "sort_by",
+ value_parser = ["asc", "desc"],
+ value_name = "order",
+ help_heading = "Common options"
+ )]
+ sort_order: Option<String>,
/// Comma-separated fields to display (name,uri,path,type,size,mode,mtime,locked,id,count,tags,abstract)
#[arg(short = 'f', long = "fields", value_delimiter = ',', value_name = "FIELDS", help_heading = "Output options")]
fields: Option<Vec<String>>,
@@ -558,13 +586,29 @@ enum Commands {
#[arg(
long = "node-limit",
short = 'n',
- alias = "limit",
default_value = "256",
value_parser = clap::value_parser!(i32).range(0..),
value_name = "n",
help_heading = "Common options"
)]
node_limit: i32,
+ /// Number of visible entries to skip
+ #[arg(
+ long,
+ default_value = "0",
+ value_parser = clap::value_parser!(i32).range(0..),
+ value_name = "n",
+ help_heading = "Common options"
+ )]
+ offset: i32,
+ /// Maximum number of visible entries to return
+ #[arg(
+ long,
+ value_parser = clap::value_parser!(i32).range(1..),
+ value_name = "n",
+ help_heading = "Common options"
+ )]
+ limit: Option<i32>,
/// Maximum depth level to traverse (default: 3)
#[arg(
short = 'L',
@@ -3518,19 +3562,57 @@ async fn main() {
abs_limit,
all,
node_limit,
+ offset,
+ limit,
+ sort_by,
+ sort_order,
fields,
tags,
- } => handlers::handle_ls(uri, simple, recursive, abs_limit, all, node_limit, fields, tags, ctx).await,
+ } => {
+ handlers::handle_ls(
+ uri,
+ simple,
+ recursive,
+ abs_limit,
+ all,
+ node_limit,
+ offset,
+ limit,
+ sort_by,
+ sort_order,
+ fields,
+ tags,
+ ctx,
+ )
+ .await
+ }
Commands::Tree {
uri,
abs_limit,
all,
node_limit,
+ offset,
+ limit,
level_limit,
simple,
fields,
tags,
- } => handlers::handle_tree(uri, abs_limit, all, node_limit, level_limit, simple, fields, tags, ctx).await,
+ } => {
+ handlers::handle_tree(
+ uri,
+ abs_limit,
+ all,
+ node_limit,
+ offset,
+ limit,
+ level_limit,
+ simple,
+ fields,
+ tags,
+ ctx,
+ )
+ .await
+ }
Commands::Mkdir { uri, description } => handlers::handle_mkdir(uri, description, ctx).await,
Commands::Rm {
uri,
@@ -4124,8 +4206,61 @@ mod tests {
#[test]
fn server_commands_require_existing_cli_config() {
let cli = Cli::try_parse_from(["ov", "ls"]).expect("ls should parse");
+ let paged_ls = Cli::try_parse_from([
+ "ov",
+ "ls",
+ "--offset",
+ "4",
+ "--limit",
+ "5",
+ "--sort-by",
+ "mtime",
+ "--sort-order",
+ "desc",
+ ])
+ .expect("paged ls should parse");
+ let paged_tree = Cli::try_parse_from([
+ "ov",
+ "tree",
+ "viking://resources",
+ "--offset",
+ "6",
+ "--limit",
+ "7",
+ ])
+ .expect("paged tree should parse");
let health = Cli::try_parse_from(["ov", "health"]).expect("health should parse");
+ match paged_ls.command {
+ Commands::Ls {
+ offset,
+ limit,
+ sort_by,
+ sort_order,
+ node_limit,
+ ..
+ } => {
+ assert_eq!(offset, 4);
+ assert_eq!(limit, Some(5));
+ assert_eq!(sort_by.as_deref(), Some("mtime"));
+ assert_eq!(sort_order.as_deref(), Some("desc"));
+ assert_eq!(node_limit, 256);
+ }
+ _ => panic!("expected ls command"),
+ }
+ match paged_tree.command {
+ Commands::Tree {
+ offset,
+ limit,
+ node_limit,
+ ..
+ } => {
+ assert_eq!(offset, 6);
+ assert_eq!(limit, Some(7));
+ assert_eq!(node_limit, 256);
+ }
+ _ => panic!("expected tree command"),
+ }
assert!(cli.command.requires_cli_config_file());
assert!(health.command.requires_cli_config_file());
}
@@ -4996,6 +5131,32 @@ mod tests {
"{args:?} should accept a positive node limit"
);
}
+
+ for prefix in [
+ vec!["ov", "ls", "--limit"],
+ vec!["ov", "tree", "viking://resources", "--limit"],
+ ] {
+ let mut zero_args = prefix.clone();
+ zero_args.push("0");
+ assert!(Cli::try_parse_from(&zero_args).is_err());
+
+ let mut positive_args = prefix;
+ positive_args.push("1");
+ assert!(Cli::try_parse_from(&positive_args).is_ok());
+ }
+
+ for prefix in [
+ vec!["ov", "ls", "--offset"],
+ vec!["ov", "tree", "viking://resources", "--offset"],
+ ] {
+ let mut negative_args = prefix.clone();
+ negative_args.push("-1");
+ assert!(Cli::try_parse_from(&negative_args).is_err());
+
+ let mut zero_args = prefix;
+ zero_args.push("0");
+ assert!(Cli::try_parse_from(&zero_args).is_ok());
+ }
}
#[test]
diff --git a/crates/ov_cli/src/tui/tree.rs b/crates/ov_cli/src/tui/tree.rs
index 3f88e50a7..995118183 100644
--- a/crates/ov_cli/src/tui/tree.rs
+++ b/crates/ov_cli/src/tui/tree.rs
@@ -139,7 +139,22 @@ impl TreeState {
async fn fetch_children(client: &HttpClient, uri: &str) -> Result<Vec<TreeNode>, String> {
let result = client
- .ls(uri, false, false, "original", 256, false, 1000, &[], &[], false)
+ .ls(
+ uri,
+ false,
+ false,
+ "original",
+ 256,
+ false,
+ 1000,
+ 0,
+ None,
+ None,
+ None,
+ &[],
+ &[],
+ false,
+ )
.await
.map_err(|e| e.to_string())?;
diff --git a/crates/ragfs-python/src/lib.rs b/crates/ragfs-python/src/lib.rs
index f1bc7e842..a3b8fe467 100644
--- a/crates/ragfs-python/src/lib.rs
+++ b/crates/ragfs-python/src/lib.rs
@@ -217,8 +217,8 @@ use ragfs::core::builder::{
};
use ragfs::core::{
build_configured_stack, ConfigValue, FileInfo, FileSystem, FilesystemStats, FsContext,
- FsContextInner, FsOperation, GlobPage, GrepResult, MountableFS, OperationStats,
- PathLockContext, PluginConfig, RagfsConfig, TreeEntry, WriteFlag, FS_CTX,
+ FsContextInner, FsOperation, GlobPage, GrepResult, ListSortBy, MountableFS, OperationStats,
+ PathLockContext, PluginConfig, RagfsConfig, SortOrder, TreeEntry, WriteFlag, FS_CTX,
};
use ragfs::lock::types::PathLockError;
use ragfs::lock::{
@@ -226,6 +226,43 @@ use ragfs::lock::{
PathLockManager, PathLockRequest,
};
+/// Parse an optional listing sort field and return the matching RagFS value.
+fn parse_list_sort_by(value: Option<&str>) -> PyResult<Option<ListSortBy>> {
+ match value {
+ None => Ok(None),
+ Some("name") => Ok(Some(ListSortBy::Name)),
+ Some("mtime") => Ok(Some(ListSortBy::Mtime)),
+ Some(value) => Err(PyValueError::new_err(format!(
+ "sort_by must be 'name' or 'mtime', got {value:?}"
+ ))),
+ }
+}
+
+/// Parse an optional listing sort direction and return the matching RagFS value.
+fn parse_sort_order(value: Option<&str>) -> PyResult<Option<SortOrder>> {
+ match value {
+ None | Some("asc") => Ok(Some(SortOrder::Asc)),
+ Some("desc") => Ok(Some(SortOrder::Desc)),
+ Some(value) => Err(PyValueError::new_err(format!(
+ "sort_order must be 'asc' or 'desc', got {value:?}"
+ ))),
+ }
+}
+
+/// Validate `offset` and return it as an unsigned RagFS offset.
+fn parse_listing_offset(offset: i64) -> PyResult<usize> {
+ usize::try_from(offset).map_err(|_| PyValueError::new_err("offset must be non-negative"))
+}
+
+/// Validate `limit` and return it as an optional unsigned RagFS limit.
+fn parse_listing_limit(limit: Option<i64>) -> PyResult<Option<usize>> {
+ match limit {
+ None => Ok(None),
+ Some(value) if value > 0 => Ok(Some(value as usize)),
+ Some(_) => Err(PyValueError::new_err("limit must be positive")),
+ }
+}
+
/// Parse one Python pathlock request without silently defaulting invalid fields.
fn parse_pathlock_request(raw: &HashMap<String, String>) -> PyResult<PathLockRequest> {
let path = raw
@@ -1599,17 +1636,28 @@ impl RAGFSBindingClient {
///
/// Returns a list of file info dicts with keys:
/// name, size, mode, modTime, isDir
- #[pyo3(signature = (path, ctx=None))]
+ #[pyo3(signature = (path, ctx=None, *, offset=0, limit=None, sort_by=None, sort_order=None))]
fn ls(
&self,
py: Python<'_>,
path: String,
ctx: Option<HashMap<String, String>>,
+ offset: i64,
+ limit: Option<i64>,
+ sort_by: Option<&str>,
+ sort_order: Option<&str>,
) -> PyResult<Py<PyAny>> {
let fs_ctx = build_fs_context(ctx);
let top = self.top.clone();
+ let offset = parse_listing_offset(offset)?;
+ let limit = parse_listing_limit(limit)?;
+ let sort_by = parse_list_sort_by(sort_by)?;
+ let sort_order = parse_sort_order(sort_order)?;
let entries = self
- .run_scoped(py, fs_ctx, move || async move { top.read_dir(&path).await })
+ .run_scoped(py, fs_ctx, move || async move {
+ top.read_dir(&path, Some(offset), limit, sort_by, sort_order)
+ .await
+ })
.map_err(to_py_err)?;
Python::attach(|py| {
@@ -2095,7 +2143,7 @@ impl RAGFSBindingClient {
///
/// Returns:
/// A list of dicts, each with keys: path, rel_path, info, extra
- #[pyo3(signature = (path, show_hidden=false, node_limit=None, level_limit=None, ctx=None))]
+ #[pyo3(signature = (path, show_hidden=false, node_limit=None, level_limit=None, ctx=None, *, offset=0, sort_by=None, sort_order=None))]
fn tree_directory(
&self,
py: Python<'_>,
@@ -2104,16 +2152,30 @@ impl RAGFSBindingClient {
node_limit: Option<i32>,
level_limit: Option<i32>,
ctx: Option<HashMap<String, String>>,
+ offset: i64,
+ sort_by: Option<&str>,
+ sort_order: Option<&str>,
) -> PyResult<Py<PyAny>> {
let fs_ctx = build_fs_context(ctx);
let top = self.top.clone();
let limit = node_limit.map(|n| if n < 0 { 0 } else { n as usize });
let level_limit_usize = level_limit.map(|n| if n < 0 { 0 } else { n as usize });
+ let offset = parse_listing_offset(offset)?;
+ let sort_by = parse_list_sort_by(sort_by)?;
+ let sort_order = parse_sort_order(sort_order)?;
let entries = self
.run_scoped(py, fs_ctx, move || async move {
- top.tree_directory(&path, show_hidden, limit, level_limit_usize)
- .await
+ top.tree_directory(
+ &path,
+ show_hidden,
+ limit,
+ level_limit_usize,
+ Some(offset),
+ sort_by,
+ sort_order,
+ )
+ .await
})
.map_err(to_py_err)?;
diff --git a/crates/ragfs/src/cache/wrapper.rs b/crates/ragfs/src/cache/wrapper.rs
index 1e91a61cc..e2e62e248 100644
--- a/crates/ragfs/src/cache/wrapper.rs
+++ b/crates/ragfs/src/cache/wrapper.rs
@@ -4,12 +4,12 @@ use super::envelope::{CacheEnvelope, CacheObjectKind, GenerationSnapshot};
use super::{CacheMetrics, CachePolicy, CacheTraversalMode};
use crate::cache_runtime::{CacheError, CacheResult, CacheRuntime, SetOptions, SetResult};
use crate::core::filesystem::{
- compile_grep_regex, is_excluded_path, normalize_prefix_path, relative_depth,
- relative_match_file, sort_directory_entries,
+ apply_read_dir_options, compile_grep_regex, is_excluded_path, normalize_prefix_path,
+ paginate_entries, relative_depth, relative_match_file,
};
use crate::core::{
- FileInfo, FileSystem, GlobPage, GrepMatch, GrepResult, MultiWriteWrappedFS, Result, TreeEntry,
- WriteFlag,
+ FileInfo, FileSystem, GlobPage, GrepMatch, GrepResult, ListSortBy, MultiWriteWrappedFS, Result,
+ SortOrder, TreeEntry, WriteFlag,
};
use async_trait::async_trait;
use bytes::Bytes;
@@ -124,6 +124,9 @@ impl CachedFileSystem {
show_hidden: bool,
node_limit: Option<usize>,
level_limit: Option<usize>,
+ offset: Option<usize>,
+ sort_by: Option<ListSortBy>,
+ sort_order: Option<SortOrder>,
) -> Result<Vec<TreeEntry>> {
enum TreeTask {
VisitDir(String),
@@ -133,9 +136,10 @@ impl CachedFileSystem {
let base_path = normalize_prefix_path(path);
let mut result = Vec::new();
let mut stack = vec![TreeTask::VisitDir(base_path.clone())];
+ let traversal_limit = node_limit.map(|limit| offset.unwrap_or(0).saturating_add(limit));
while let Some(task) = stack.pop() {
- if node_limit.is_some_and(|limit| result.len() >= limit) {
+ if traversal_limit.is_some_and(|limit| result.len() >= limit) {
break;
}
@@ -149,8 +153,9 @@ impl CachedFileSystem {
}
}
- let mut entries = self.read_dir(&current_path).await?;
- sort_directory_entries(&mut entries);
+ let entries = self
+ .read_dir(&current_path, None, None, sort_by, sort_order)
+ .await?;
for entry in entries.into_iter().rev() {
let is_hidden_file = !entry.is_dir && entry.name.starts_with('.');
if is_hidden_file && !show_hidden {
@@ -180,7 +185,7 @@ impl CachedFileSystem {
}
}
- Ok(result)
+ Ok(paginate_entries(result, offset, node_limit))
}
async fn grep_via_cache(
@@ -846,13 +851,13 @@ impl CachedFileSystem {
) -> Result<Vec<FileInfo>> {
if !self.policy.cache_directory(path) || self.is_runtime_bypassed(path).await {
self.metrics.policy_bypass();
- return self.backend.read_dir(path).await;
+ return self.backend.read_dir(path, None, None, None, None).await;
}
let _operation_guard = self.operation_lock.read().await;
if self.is_runtime_bypassed(path).await {
self.metrics.policy_bypass();
- return self.backend.read_dir(path).await;
+ return self.backend.read_dir(path, None, None, None, None).await;
}
let normalized = normalize_path(path);
@@ -890,7 +895,7 @@ impl CachedFileSystem {
}
}
- let entries = self.backend.read_dir(path).await;
+ let entries = self.backend.read_dir(path, None, None, None, None).await;
if let Ok(value) = &entries {
self.metrics.backend_fallback(0);
self.fill_directory(&key, &normalized, value).await;
@@ -1082,22 +1087,37 @@ impl FileSystem for CachedFileSystem {
Ok(written)
}
- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
+ async fn read_dir(
+ &self,
+ path: &str,
+ offset: Option<usize>,
+ limit: Option<usize>,
+ sort_by: Option<ListSortBy>,
+ sort_order: Option<SortOrder>,
+ ) -> Result<Vec<FileInfo>> {
if !self.policy.cache_directory(path) || self.is_runtime_bypassed(path).await {
self.metrics.policy_bypass();
- return self.backend.read_dir(path).await;
+ return self
+ .backend
+ .read_dir(path, offset, limit, sort_by, sort_order)
+ .await;
}
let _operation_guard = self.operation_lock.read().await;
if self.is_runtime_bypassed(path).await {
self.metrics.policy_bypass();
- return self.backend.read_dir(path).await;
+ return self
+ .backend
+ .read_dir(path, offset, limit, sort_by, sort_order)
+ .await;
}
let normalized = normalize_path(path);
let key = self.directory_key(&normalized);
if let Some(entries) = self.probe_directory(&key, &normalized, true).await {
- return Ok(entries);
+ return Ok(apply_read_dir_options(
+ entries, offset, limit, sort_by, sort_order,
+ ));
}
self.metrics.read_dir_miss();
@@ -1114,18 +1134,20 @@ impl FileSystem for CachedFileSystem {
self.metrics.inflight_backend_saved();
drop(inflight_guard);
self.release_inflight(&key, &inflight).await;
- return Ok(entries);
+ return Ok(apply_read_dir_options(
+ entries, offset, limit, sort_by, sort_order,
+ ));
}
}
- let entries = self.backend.read_dir(path).await;
+ let entries = self.backend.read_dir(path, None, None, None, None).await;
if let Ok(value) = &entries {
self.metrics.backend_fallback(0);
self.fill_directory(&key, &normalized, value).await;
}
drop(inflight_guard);
self.release_inflight(&key, &inflight).await;
- entries
+ entries.map(|entries| apply_read_dir_options(entries, offset, limit, sort_by, sort_order))
}
async fn stat(&self, path: &str) -> Result<FileInfo> {
@@ -1230,17 +1252,36 @@ impl FileSystem for CachedFileSystem {
show_hidden: bool,
node_limit: Option<usize>,
level_limit: Option<usize>,
+ offset: Option<usize>,
+ sort_by: Option<ListSortBy>,
+ sort_order: Option<SortOrder>,
) -> Result<Vec<TreeEntry>> {
if self.policy.traversal_mode() == CacheTraversalMode::CachedTraversal
&& !self.wraps_multiwrite()
{
return self
- .tree_directory_via_cache(path, show_hidden, node_limit, level_limit)
+ .tree_directory_via_cache(
+ path,
+ show_hidden,
+ node_limit,
+ level_limit,
+ offset,
+ sort_by,
+ sort_order,
+ )
.await;
}
self.backend
- .tree_directory(path, show_hidden, node_limit, level_limit)
+ .tree_directory(
+ path,
+ show_hidden,
+ node_limit,
+ level_limit,
+ offset,
+ sort_by,
+ sort_order,
+ )
.await
}
diff --git a/crates/ragfs/src/core/encryption_wrapper.rs b/crates/ragfs/src/core/encryption_wrapper.rs
index 6d014749d..9237b1596 100644
--- a/crates/ragfs/src/core/encryption_wrapper.rs
+++ b/crates/ragfs/src/core/encryption_wrapper.rs
@@ -16,17 +16,17 @@ use async_trait::async_trait;
use sha2::{Digest, Sha256};
use tracing::{debug, warn};
-use crate::crypto;
use crate::core::internal_names::is_hidden_runtime_lock_name;
-use crate::lock::{
- AutoPathLockAction, PathLockKind, PathLockManager, PathLockRequest,
-};
+use crate::crypto;
+use crate::lock::{AutoPathLockAction, PathLockKind, PathLockManager, PathLockRequest};
use crate::shape::SHAPE_MANIFEST_PATH;
use super::context::FsContextView;
use super::errors::{Error, Result};
-use super::filesystem::{compile_grep_regex, normalize_prefix_path, FileSystem};
-use super::types::{FileInfo, GlobPage, GrepResult, TreeEntry, WriteFlag};
+use super::filesystem::{
+ apply_read_dir_options, compile_grep_regex, normalize_prefix_path, paginate_entries, FileSystem,
+};
+use super::types::{FileInfo, GlobPage, GrepResult, ListSortBy, SortOrder, TreeEntry, WriteFlag};
const SYSTEM_ACCOUNT_ID: &str = "_system";
const TEMP_ROOT_CACHE_TTL: Duration = Duration::from_secs(15 * 60);
@@ -182,7 +182,10 @@ impl EncryptionWrappedFS {
} else {
format!("/{}", path)
};
- let parts: Vec<&str> = normalized.split('/').filter(|part| !part.is_empty()).collect();
+ let parts: Vec<&str> = normalized
+ .split('/')
+ .filter(|part| !part.is_empty())
+ .collect();
match parts.as_slice() {
["local", account_id, ..] => format!("/local/{}/temp/.encrypt_stage", account_id),
[mount_root, _, ..] => format!("/{}/temp/.encrypt_stage", mount_root),
@@ -275,7 +278,6 @@ impl EncryptionWrappedFS {
}
Ok(written)
}
-
}
/// Slice `data` by `(offset, size)` with `size == 0` meaning "to end", matching plugin read semantics.
@@ -379,7 +381,10 @@ impl FileSystem for EncryptionWrappedFS {
kind: PathLockKind::Exact,
};
let requests = vec![
- PathLockRequest { path: temp_lock_path, kind: PathLockKind::Exact },
+ PathLockRequest {
+ path: temp_lock_path,
+ kind: PathLockKind::Exact,
+ },
final_request.clone(),
];
let action = self
@@ -389,22 +394,20 @@ impl FileSystem for EncryptionWrappedFS {
.map_err(|error| {
Error::internal(format!("encrypted write lock context error: {error}"))
})?;
- let action_name = match &action { AutoPathLockAction::Disabled => "disabled", AutoPathLockAction::Covered(_) => "covered", AutoPathLockAction::Acquire => "acquire" };
+ let action_name = match &action {
+ AutoPathLockAction::Disabled => "disabled",
+ AutoPathLockAction::Covered(_) => "covered",
+ AutoPathLockAction::Acquire => "acquire",
+ };
debug!(path = %path, temp_path = %temp_path, final_lock_path = %requests[1].path, temp_lock_path = %requests[0].path, action = %action_name, "encrypted write resolved dual-path pathlock action");
let lock_guard = match action {
AutoPathLockAction::Disabled => None,
AutoPathLockAction::Covered(outer) => {
- let owner_capability = (
- outer.lease.lease_ref.as_str(),
- outer.ownership_ref.as_str(),
- );
+ let owner_capability =
+ (outer.lease.lease_ref.as_str(), outer.ownership_ref.as_str());
Some(
self.pathlock_manager
- .acquire_batch(
- &requests,
- Duration::from_secs(1),
- Some(owner_capability),
- )
+ .acquire_batch(&requests, Duration::from_secs(1), Some(owner_capability))
.await
.map_err(|error| {
Error::internal(format!("encrypted write lock error: {error}"))
@@ -422,7 +425,9 @@ impl FileSystem for EncryptionWrappedFS {
};
// Release lock on error. On success, release after replace.
- let result = self.encrypted_write_inner(path, &temp_path, &envelope).await;
+ let result = self
+ .encrypted_write_inner(path, &temp_path, &envelope)
+ .await;
let replace_result = match result {
Ok(written) => self.inner.replace(&temp_path, path).await.map(|_| written),
Err(e) => Err(e),
@@ -512,12 +517,22 @@ impl FileSystem for EncryptionWrappedFS {
self.inner.remove_all(path).await
}
- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
- let entries = self.inner.read_dir(path).await?;
- Ok(entries
+ async fn read_dir(
+ &self,
+ path: &str,
+ offset: Option<usize>,
+ limit: Option<usize>,
+ sort_by: Option<ListSortBy>,
+ sort_order: Option<SortOrder>,
+ ) -> Result<Vec<FileInfo>> {
+ let entries = self.inner.read_dir(path, None, None, None, None).await?;
+ let entries = entries
.into_iter()
.filter(|entry| entry.name != SHAPE_MANIFEST_PATH.trim_start_matches('/'))
- .collect())
+ .collect();
+ Ok(apply_read_dir_options(
+ entries, offset, limit, sort_by, sort_order,
+ ))
}
async fn stat(&self, path: &str) -> Result<FileInfo> {
@@ -541,16 +556,28 @@ impl FileSystem for EncryptionWrappedFS {
show_hidden: bool,
node_limit: Option<usize>,
level_limit: Option<usize>,
+ offset: Option<usize>,
+ sort_by: Option<ListSortBy>,
+ sort_order: Option<SortOrder>,
) -> Result<Vec<TreeEntry>> {
// Metadata only — no content read, so delegate to preserve plugin-native tree optimizations.
let entries = self
.inner
- .tree_directory(path, show_hidden, node_limit, level_limit)
+ .tree_directory(
+ path,
+ show_hidden,
+ None,
+ level_limit,
+ None,
+ sort_by,
+ sort_order,
+ )
.await?;
- Ok(entries
+ let entries = entries
.into_iter()
.filter(|entry| !Self::is_shape_manifest_path(&entry.path))
- .collect())
+ .collect();
+ Ok(paginate_entries(entries, offset, node_limit))
}
async fn glob_directory(
@@ -594,9 +621,7 @@ mod tests {
use crate::core::context::{FsContextInner, FS_CTX};
use crate::core::MountableFS;
use crate::core::PluginConfig;
- use crate::lock::{
- MemoryPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider,
- };
+ use crate::lock::{MemoryPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider};
use crate::plugins::MemFSPlugin;
/// Build a memfs plugin config for encryption wrapper tests.
@@ -928,12 +953,7 @@ mod tests {
})
.await;
- assert!(
- inner
- .stat(temp_path)
- .await
- .is_err()
- );
+ assert!(inner.stat(temp_path).await.is_err());
let raw = inner.read("/mem/a.txt", 0, 0).await.unwrap();
assert!(crypto::is_encrypted(&raw));
}
@@ -960,7 +980,10 @@ mod tests {
];
for (final_path, temp_path) in cases {
- assert_eq!(EncryptionWrappedFS::encrypted_temp_path(final_path), temp_path);
+ assert_eq!(
+ EncryptionWrappedFS::encrypted_temp_path(final_path),
+ temp_path
+ );
}
}
}
diff --git a/crates/ragfs/src/core/filesystem.rs b/crates/ragfs/src/core/filesystem.rs
index 7a9c7965e..429341f0b 100644
--- a/crates/ragfs/src/core/filesystem.rs
+++ b/crates/ragfs/src/core/filesystem.rs
@@ -12,7 +12,9 @@ use std::path::{Component, Path};
use super::errors::{Error, Result};
use super::glob::{compare_rel_paths, decode_offset_token, encode_offset_token, PreparedGlob};
-use super::types::{FileInfo, GlobEntry, GlobPage, GrepResult, TreeEntry, WriteFlag};
+use super::types::{
+ FileInfo, GlobEntry, GlobPage, GrepResult, ListSortBy, SortOrder, TreeEntry, WriteFlag,
+};
/// Reject virtual paths that can escape a mounted backend lexically.
pub(crate) fn validate_virtual_path(path: &str) -> Result<()> {
@@ -53,6 +55,70 @@ pub(crate) fn sort_directory_entries(entries: &mut [FileInfo]) {
});
}
+/// Sort entries by `sort_by` and `sort_order`, keeping directories before files.
+///
+/// Returns through the mutable `entries` slice.
+pub(crate) fn sort_directory_entries_by(
+ entries: &mut [FileInfo],
+ sort_by: Option<ListSortBy>,
+ sort_order: Option<SortOrder>,
+) {
+ let Some(sort_by) = sort_by else {
+ return;
+ };
+ let descending = matches!(sort_order, Some(SortOrder::Desc));
+ entries.sort_by(|a, b| {
+ let group_order = b.is_dir.cmp(&a.is_dir);
+ if group_order != Ordering::Equal {
+ return group_order;
+ }
+ match sort_by {
+ ListSortBy::Name => {
+ let order = compare_listing_names(&a.name, &b.name);
+ if descending {
+ order.reverse()
+ } else {
+ order
+ }
+ }
+ ListSortBy::Mtime => {
+ let order = a.mod_time.cmp(&b.mod_time);
+ let order = if descending { order.reverse() } else { order };
+ order.then_with(|| compare_listing_names(&a.name, &b.name))
+ }
+ }
+ });
+}
+
+/// Consume `entries` and return the range selected by `offset` and `limit`.
+pub(crate) fn paginate_entries<T>(
+ entries: Vec<T>,
+ offset: Option<usize>,
+ limit: Option<usize>,
+) -> Vec<T> {
+ entries
+ .into_iter()
+ .skip(offset.unwrap_or(0))
+ .take(limit.unwrap_or(usize::MAX))
+ .collect()
+}
+
+/// Apply the requested sorting and pagination options and return the selected entries.
+pub(crate) fn apply_read_dir_options(
+ mut entries: Vec<FileInfo>,
+ offset: Option<usize>,
+ limit: Option<usize>,
+ sort_by: Option<ListSortBy>,
+ sort_order: Option<SortOrder>,
+) -> Vec<FileInfo> {
+ if sort_by.is_some() {
+ sort_directory_entries_by(&mut entries, sort_by, sort_order);
+ } else {
+ sort_directory_entries(&mut entries);
+ }
+ paginate_entries(entries, offset, limit)
+}
+
/// Check whether `path` is under `exclude_path` (including itself).
pub(crate) fn is_excluded_path(path: &str, exclude_path: &str) -> bool {
if exclude_path == "/" {
@@ -247,6 +313,10 @@ pub trait FileSystem: Send + Sync + Any {
///
/// # Arguments
/// * `path` - The path of the directory to list
+ /// * `offset` - Number of sorted entries to skip
+ /// * `limit` - Maximum number of entries to return
+ /// * `sort_by` - Optional field used to sort entries
+ /// * `sort_order` - Optional sort direction
///
/// # Returns
/// A vector of FileInfo for each entry in the directory
@@ -254,7 +324,14 @@ pub trait FileSystem: Send + Sync + Any {
/// # Errors
/// * `Error::NotFound` - If the directory doesn't exist
/// * `Error::NotADirectory` - If the path is not a directory
- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>>;
+ async fn read_dir(
+ &self,
+ path: &str,
+ offset: Option<usize>,
+ limit: Option<usize>,
+ sort_by: Option<ListSortBy>,
+ sort_order: Option<SortOrder>,
+ ) -> Result<Vec<FileInfo>>;
/// List directory contents without public internal-name filtering.
///
@@ -264,7 +341,7 @@ pub trait FileSystem: Send + Sync + Any {
/// # Returns
/// Raw directory entries visible to filesystem internals.
async fn read_internal_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
- self.read_dir(path).await
+ self.read_dir(path, None, None, None, None).await
}
/// Get file or directory metadata
@@ -431,7 +508,7 @@ pub trait FileSystem: Send + Sync + Any {
}
}
- let entries = self.read_dir(current_path).await?;
+ let entries = self.read_dir(current_path, None, None, None, None).await?;
for entry in entries {
if node_limit.is_some_and(|limit| result.count >= limit) {
@@ -514,6 +591,9 @@ pub trait FileSystem: Send + Sync + Any {
/// * `show_hidden` - Whether to include hidden files (names starting with `.`)
/// * `node_limit` - Maximum number of nodes to return (None means no limit)
/// * `level_limit` - Maximum depth relative to query root (None means no limit)
+ /// * `offset` - Number of flattened DFS entries to skip
+ /// * `sort_by` - Optional sibling sort field
+ /// * `sort_order` - Optional sibling sort direction
///
/// # Returns
/// A flat `Vec<TreeEntry>` in DFS order (directories before their children).
@@ -523,21 +603,27 @@ pub trait FileSystem: Send + Sync + Any {
show_hidden: bool,
node_limit: Option<usize>,
level_limit: Option<usize>,
+ offset: Option<usize>,
+ sort_by: Option<ListSortBy>,
+ sort_order: Option<SortOrder>,
) -> Result<Vec<TreeEntry>> {
let normalized_path = normalize_prefix_path(path);
let mut result = Vec::new();
+ let traversal_limit = node_limit.map(|limit| offset.unwrap_or(0).saturating_add(limit));
self.tree_directory_internal(
normalized_path.as_str(),
normalized_path.as_str(),
show_hidden,
- node_limit,
+ traversal_limit,
level_limit,
+ sort_by,
+ sort_order,
&mut result,
)
.await?;
- Ok(result)
+ Ok(paginate_entries(result, offset, node_limit))
}
/// Return one page of flat glob results under `path`.
@@ -560,7 +646,7 @@ pub trait FileSystem: Send + Sync + Any {
}
let entries = self
- .tree_directory(path, show_hidden, None, level_limit)
+ .tree_directory(path, show_hidden, None, level_limit, None, None, None)
.await?;
let mut matched = Vec::new();
@@ -607,6 +693,8 @@ pub trait FileSystem: Send + Sync + Any {
/// * `show_hidden` - Whether to include hidden files
/// * `node_limit` - Maximum number of nodes to return
/// * `level_limit` - Maximum depth relative to base_path
+ /// * `sort_by` - Optional sibling sort field
+ /// * `sort_order` - Optional sibling sort direction
/// * `result` - Accumulator for the flat result list
async fn tree_directory_internal(
&self,
@@ -615,6 +703,8 @@ pub trait FileSystem: Send + Sync + Any {
show_hidden: bool,
node_limit: Option<usize>,
level_limit: Option<usize>,
+ sort_by: Option<ListSortBy>,
+ sort_order: Option<SortOrder>,
result: &mut Vec<TreeEntry>,
) -> Result<()> {
if node_limit.is_some_and(|limit| result.len() >= limit) {
@@ -633,8 +723,9 @@ pub trait FileSystem: Send + Sync + Any {
}
}
- let mut entries = self.read_dir(current_path).await?;
+ let mut entries = self.read_dir(current_path, None, None, None, None).await?;
sort_directory_entries(&mut entries);
+ sort_directory_entries_by(&mut entries, sort_by, sort_order);
for entry in entries {
if node_limit.is_some_and(|limit| result.len() >= limit) {
@@ -668,6 +759,8 @@ pub trait FileSystem: Send + Sync + Any {
show_hidden,
node_limit,
level_limit,
+ sort_by,
+ sort_order,
result,
)
.await?;
@@ -756,7 +849,14 @@ mod tests {
Ok(_data.len() as u64)
}
- async fn read_dir(&self, _path: &str) -> Result<Vec<FileInfo>> {
+ async fn read_dir(
+ &self,
+ _path: &str,
+ _offset: Option<usize>,
+ _limit: Option<usize>,
+ _sort_by: Option<ListSortBy>,
+ _sort_order: Option<SortOrder>,
+ ) -> Result<Vec<FileInfo>> {
Ok(vec![])
}
@@ -846,12 +946,22 @@ mod tests {
Ok(data.len() as u64)
}
- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
+ async fn read_dir(
+ &self,
+ path: &str,
+ offset: Option<usize>,
+ limit: Option<usize>,
+ sort_by: Option<ListSortBy>,
+ sort_order: Option<SortOrder>,
+ ) -> Result<Vec<FileInfo>> {
let entries = self.dirs.get(path).cloned().unwrap_or_default();
- Ok(entries
+ let entries = entries
.into_iter()
.map(|(name, is_dir)| TreeFS::file_info(name, is_dir))
- .collect())
+ .collect::<Vec<_>>();
+ Ok(apply_read_dir_options(
+ entries, offset, limit, sort_by, sort_order,
+ ))
}
async fn stat(&self, path: &str) -> Result<FileInfo> {
@@ -954,9 +1064,17 @@ mod tests {
node_limit: Option<usize>,
level_limit: Option<usize>,
) -> Vec<TreeEntry> {
- fs.tree_directory("/root", show_hidden, node_limit, level_limit)
- .await
- .unwrap()
+ fs.tree_directory(
+ "/root",
+ show_hidden,
+ node_limit,
+ level_limit,
+ None,
+ None,
+ None,
+ )
+ .await
+ .unwrap()
}
/// Assert tree entry names in order.
@@ -987,14 +1105,52 @@ mod tests {
async fn test_tree_single_layer_files() {
let fs = TreeFS::default().with_dir_entries(
"/root",
- vec![("a.txt", false), ("b.txt", false), ("c.txt", false)],
+ vec![("c.txt", false), ("a.txt", false), ("b.txt", false)],
);
let entries = root_tree(&fs, false, None, None).await;
+ let default_page = fs
+ .read_dir("/root", Some(1), Some(1), None, None)
+ .await
+ .unwrap();
+ let page = fs
+ .read_dir(
+ "/root",
+ Some(1),
+ Some(1),
+ Some(ListSortBy::Name),
+ Some(SortOrder::Desc),
+ )
+ .await
+ .unwrap();
assert_eq!(entries.len(), 3);
assert_tree_names(&entries, &["a.txt", "b.txt", "c.txt"]);
assert_tree_rel_paths(&entries, &["a.txt", "b.txt", "c.txt"]);
+ assert_eq!(default_page[0].name, "b.txt");
+ assert_eq!(page[0].name, "b.txt");
+
+ let mut by_mtime = vec![
+ TreeFS::file_info("a.txt".to_string(), false),
+ TreeFS::file_info("b.txt".to_string(), false),
+ TreeFS::file_info("c.txt".to_string(), false),
+ ];
+ by_mtime[0].mod_time = std::time::UNIX_EPOCH + std::time::Duration::from_secs(1);
+ by_mtime[1].mod_time = std::time::UNIX_EPOCH + std::time::Duration::from_secs(2);
+ by_mtime[2].mod_time = std::time::UNIX_EPOCH + std::time::Duration::from_secs(2);
+ let page = apply_read_dir_options(
+ by_mtime,
+ None,
+ Some(2),
+ Some(ListSortBy::Mtime),
+ Some(SortOrder::Desc),
+ );
+ assert_eq!(
+ page.iter()
+ .map(|entry| entry.name.as_str())
+ .collect::<Vec<_>>(),
+ vec!["b.txt", "c.txt"]
+ );
}
#[tokio::test]
@@ -1035,10 +1191,21 @@ mod tests {
],
);
- let entries = root_tree(&fs, false, Some(3), None).await;
+ let entries = fs
+ .tree_directory(
+ "/root",
+ false,
+ Some(3),
+ None,
+ Some(1),
+ Some(ListSortBy::Name),
+ Some(SortOrder::Asc),
+ )
+ .await
+ .unwrap();
assert_eq!(entries.len(), 3);
- assert_tree_names(&entries, &["a.txt", "b.txt", "c.txt"]);
+ assert_tree_names(&entries, &["b.txt", "c.txt", "d.txt"]);
}
#[tokio::test]
@@ -1135,7 +1302,10 @@ mod tests {
async fn test_tree_root_path() {
let fs = TreeFS::default().with_dir_entries("/", vec![("a.txt", false), ("sub", true)]);
- let entries = fs.tree_directory("/", false, None, None).await.unwrap();
+ let entries = fs
+ .tree_directory("/", false, None, None, None, None, None)
+ .await
+ .unwrap();
assert_eq!(entries.len(), 2);
assert_eq!(entries[0].path, "/sub");
@@ -1151,7 +1321,10 @@ mod tests {
.with_dir_entries("/a/b/c/d", vec![("e", true)])
.with_dir_entries("/a/b/c/d/e", vec![("f.txt", false)]);
- let entries = fs.tree_directory("/a", false, None, None).await.unwrap();
+ let entries = fs
+ .tree_directory("/a", false, None, None, None, None, None)
+ .await
+ .unwrap();
assert_eq!(entries.len(), 5);
assert_eq!(
diff --git a/crates/ragfs/src/core/mod.rs b/crates/ragfs/src/core/mod.rs
index 0d8bdcdcc..632af6545 100644
--- a/crates/ragfs/src/core/mod.rs
+++ b/crates/ragfs/src/core/mod.rs
@@ -23,14 +23,14 @@ pub mod types;
// Re-export commonly used types
pub use crate::multibackend::{FsContextResolver, MetaStateStore};
-pub use builder::{
- build_default_stack, build_stack_with_mountable, register_builtin_plugins,
- EncryptionConfig as BuilderEncryptionConfig, RagfsConfig, RagfsStack,
-};
#[cfg(feature = "cache")]
pub use builder::{
build_configured_stack, CacheFsConfig, CacheRuntimeProviderConfig, CacheStackConfig,
};
+pub use builder::{
+ build_default_stack, build_stack_with_mountable, register_builtin_plugins,
+ EncryptionConfig as BuilderEncryptionConfig, RagfsConfig, RagfsStack,
+};
pub use context::{FsContext, FsContextInner, FsContextView, PathLockContext, FS_CTX};
pub use encryption_wrapper::EncryptionWrappedFS;
pub use errors::{Error, Result};
@@ -42,7 +42,7 @@ pub use stats::{FilesystemStats, FsOperation, OperationStats, OperationTimer, St
pub use stats_wrapper::StatsWrappedFS;
pub use types::{
BackendItemConfig, BackendRole, BackendSyncState, BackendsConfig, ConfigParameter, ConfigValue,
- EncryptionConfig, FileInfo, GlobEntry, GlobPage, GrepMatch, GrepResult,
- OperationItemConfig, PluginConfig, RedirectEntry, RedirectMeta, RedirectPolicy,
+ EncryptionConfig, FileInfo, GlobEntry, GlobPage, GrepMatch, GrepResult, ListSortBy,
+ OperationItemConfig, PluginConfig, RedirectEntry, RedirectMeta, RedirectPolicy, SortOrder,
SyncLogEntry, SyncLogMeta, SyncOp, SyncType, TreeEntry, WriteFlag,
};
diff --git a/crates/ragfs/src/core/mountable.rs b/crates/ragfs/src/core/mountable.rs
index f6ecbe3b5..a6c1bda4a 100644
--- a/crates/ragfs/src/core/mountable.rs
+++ b/crates/ragfs/src/core/mountable.rs
@@ -23,7 +23,10 @@ use super::internal_names::is_hidden_internal_name;
use super::encryption_wrapper::EncryptionWrappedFS;
use super::errors::{Error, Result};
-use super::filesystem::{sort_directory_entries, validate_virtual_path, FileSystem};
+use super::filesystem::{
+ apply_read_dir_options, paginate_entries, sort_directory_entries, validate_virtual_path,
+ FileSystem,
+};
use super::multibackend_wrapper::MultiWriteWrappedFS;
use super::plugin::ServicePlugin;
use super::stats::{FilesystemStats, StatsCollector};
@@ -809,8 +812,17 @@ impl FileSystem for ArcFileSystem {
self.0.write(path, data, offset, flags).await
}
- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
- self.0.read_dir(path).await
+ async fn read_dir(
+ &self,
+ path: &str,
+ offset: Option<usize>,
+ limit: Option<usize>,
+ sort_by: Option<crate::core::ListSortBy>,
+ sort_order: Option<crate::core::SortOrder>,
+ ) -> Result<Vec<FileInfo>> {
+ self.0
+ .read_dir(path, offset, limit, sort_by, sort_order)
+ .await
}
async fn stat(&self, path: &str) -> Result<FileInfo> {
@@ -958,11 +970,20 @@ impl FileSystem for MountableFS {
Ok(changed)
}
- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
+ async fn read_dir(
+ &self,
+ path: &str,
+ offset: Option<usize>,
+ limit: Option<usize>,
+ sort_by: Option<crate::core::ListSortBy>,
+ sort_order: Option<crate::core::SortOrder>,
+ ) -> Result<Vec<FileInfo>> {
let mut entries = self.read_internal_dir(path).await?;
entries.retain(|entry| !is_hidden_internal_name(&entry.name));
sort_directory_entries(&mut entries);
- Ok(entries)
+ Ok(apply_read_dir_options(
+ entries, offset, limit, sort_by, sort_order,
+ ))
}
async fn read_internal_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
@@ -1080,6 +1101,9 @@ impl FileSystem for MountableFS {
show_hidden: bool,
node_limit: Option<usize>,
level_limit: Option<usize>,
+ offset: Option<usize>,
+ sort_by: Option<crate::core::ListSortBy>,
+ sort_order: Option<crate::core::SortOrder>,
) -> Result<Vec<TreeEntry>> {
let (mount_info, rel_path) = self.find_mount(path).await?;
@@ -1091,7 +1115,15 @@ impl FileSystem for MountableFS {
let mut entries = mount_info
.fs
- .tree_directory(&rel_path, show_hidden, node_limit, level_limit)
+ .tree_directory(
+ &rel_path,
+ show_hidden,
+ None,
+ level_limit,
+ None,
+ sort_by,
+ sort_order,
+ )
.await?;
for entry in &mut entries {
@@ -1112,7 +1144,7 @@ impl FileSystem for MountableFS {
.map_or(true, |name| !is_hidden_internal_name(name))
});
- Ok(entries)
+ Ok(paginate_entries(entries, offset, node_limit))
}
async fn glob_directory(
@@ -1277,7 +1309,14 @@ mod tests {
Ok(data.len() as u64)
}
- async fn read_dir(&self, _path: &str) -> Result<Vec<FileInfo>> {
+ async fn read_dir(
+ &self,
+ _path: &str,
+ _offset: Option<usize>,
+ _limit: Option<usize>,
+ _sort_by: Option<crate::core::ListSortBy>,
+ _sort_order: Option<crate::core::SortOrder>,
+ ) -> Result<Vec<FileInfo>> {
Ok(self
.tree_entries
.iter()
@@ -1319,6 +1358,9 @@ mod tests {
_show_hidden: bool,
_node_limit: Option<usize>,
_level_limit: Option<usize>,
+ _offset: Option<usize>,
+ _sort_by: Option<crate::core::ListSortBy>,
+ _sort_order: Option<crate::core::SortOrder>,
) -> Result<Vec<TreeEntry>> {
Ok(self.tree_entries.clone())
}
@@ -1412,7 +1454,14 @@ mod tests {
Ok(data.len() as u64)
}
- async fn read_dir(&self, _path: &str) -> Result<Vec<FileInfo>> {
+ async fn read_dir(
+ &self,
+ _path: &str,
+ _offset: Option<usize>,
+ _limit: Option<usize>,
+ _sort_by: Option<crate::core::ListSortBy>,
+ _sort_order: Option<crate::core::SortOrder>,
+ ) -> Result<Vec<FileInfo>> {
Ok(vec![])
}
@@ -1739,7 +1788,7 @@ mod tests {
assert_eq!(mfs.read("/local/dir/b.md", 0, 0).await.unwrap(), b"old");
assert_eq!(
- mfs.read_dir("/local/dir")
+ mfs.read_dir("/local/dir", None, None, None, None)
.await
.unwrap()
.into_iter()
@@ -1756,7 +1805,7 @@ mod tests {
let copied = mfs.read("/local/dir/b.md", 0, 0).await.unwrap();
let copied_size = mfs
- .read_dir("/local/dir")
+ .read_dir("/local/dir", None, None, None, None)
.await
.unwrap()
.into_iter()
@@ -2148,13 +2197,14 @@ mod tests {
make_tree_entry("/A.txt", "A.txt", "A.txt", false),
make_tree_entry("/c", "c", "c", true),
make_tree_entry("/B", "B", "B", true),
+ make_tree_entry("/.path.ovlock", ".path.ovlock", ".path.ovlock", false),
],
);
mfs.register_plugin(plugin).await;
mfs.mount(test_config("sorted", "/sorted")).await.unwrap();
let names: Vec<String> = mfs
- .read_dir("/sorted")
+ .read_dir("/sorted", None, None, None, None)
.await
.unwrap()
.into_iter()
@@ -2162,13 +2212,28 @@ mod tests {
.collect();
assert_eq!(names, vec!["B", "c", "A.txt", "b.txt"]);
+
+ let page: Vec<String> = mfs
+ .read_dir(
+ "/sorted",
+ Some(1),
+ Some(2),
+ Some(crate::core::ListSortBy::Name),
+ Some(crate::core::SortOrder::Desc),
+ )
+ .await
+ .unwrap()
+ .into_iter()
+ .map(|entry| entry.name)
+ .collect();
+ assert_eq!(page, vec!["B", "b.txt"]);
}
#[tokio::test]
async fn test_tree_directory_no_mount_returns_error() {
let mfs = MountableFS::new();
let result = mfs
- .tree_directory("/nonexistent/subdir", false, None, None)
+ .tree_directory("/nonexistent/subdir", false, None, None, None, None, None)
.await;
assert!(result.is_err());
}
@@ -2189,7 +2254,7 @@ mod tests {
mfs.mount(test_config("rewrite", "/rewrite")).await.unwrap();
let result = mfs
- .tree_directory("/rewrite/sub", false, None, None)
+ .tree_directory("/rewrite/sub", false, None, None, None, None, None)
.await
.unwrap();
assert_eq!(result.len(), 1);
@@ -2210,7 +2275,7 @@ mod tests {
.unwrap();
let result = mfs
- .tree_directory("/local/test_account/a", false, None, None)
+ .tree_directory("/local/test_account/a", false, None, None, None, None, None)
.await
.unwrap();
assert_eq!(result.len(), 1);
diff --git a/crates/ragfs/src/core/multibackend_wrapper.rs b/crates/ragfs/src/core/multibackend_wrapper.rs
index 4c2804859..b0b89777d 100644
--- a/crates/ragfs/src/core/multibackend_wrapper.rs
+++ b/crates/ragfs/src/core/multibackend_wrapper.rs
@@ -22,10 +22,14 @@ use tokio::sync::{Mutex, Notify};
use super::context::{FsContext, FS_CTX};
use super::encryption_wrapper::EncryptionWrappedFS;
use super::errors::{Error, Result};
-use super::filesystem::{normalize_prefix_path, relative_depth, relative_match_file, FileSystem};
+use super::filesystem::{
+ apply_read_dir_options, normalize_prefix_path, paginate_entries, relative_depth,
+ relative_match_file, FileSystem,
+};
use super::types::{
- BackendRole, BackendSyncState, FileInfo, GlobEntry, GlobPage, GrepResult, OperationItemConfig,
- RedirectEntry, RedirectPolicy, SyncLogEntry, SyncOp, SyncType, TreeEntry, WriteFlag,
+ BackendRole, BackendSyncState, FileInfo, GlobEntry, GlobPage, GrepResult, ListSortBy,
+ OperationItemConfig, RedirectEntry, RedirectPolicy, SortOrder, SyncLogEntry, SyncOp, SyncType,
+ TreeEntry, WriteFlag,
};
use crate::core::glob::{
compare_rel_paths, decode_offset_token, encode_offset_token, PreparedGlob,
@@ -1390,15 +1394,28 @@ impl FileSystem for MultiWriteWrappedFS {
.await
}
- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
+ async fn read_dir(
+ &self,
+ path: &str,
+ offset: Option<usize>,
+ limit: Option<usize>,
+ sort_by: Option<ListSortBy>,
+ sort_order: Option<SortOrder>,
+ ) -> Result<Vec<FileInfo>> {
let inner = &self.inner;
- let mut entries = inner.primary().backend.read_dir(path).await?;
+ let mut entries = inner
+ .primary()
+ .backend
+ .read_dir(path, None, None, None, None)
+ .await?;
// Filter multi-write internal names.
entries.retain(|e| !MULTIWRITE_INTERNAL_NAMES.contains(&e.name.as_str()));
if inner.redirects.is_empty() {
- return Ok(entries);
+ return Ok(apply_read_dir_options(
+ entries, offset, limit, sort_by, sort_order,
+ ));
}
// Merge redirect entries so users can see redirected files in listings.
@@ -1422,7 +1439,9 @@ impl FileSystem for MultiWriteWrappedFS {
}
}
- Ok(entries)
+ Ok(apply_read_dir_options(
+ entries, offset, limit, sort_by, sort_order,
+ ))
}
async fn stat(&self, path: &str) -> Result<FileInfo> {
@@ -1439,7 +1458,12 @@ impl FileSystem for MultiWriteWrappedFS {
if is_hidden_internal_name(file_name(old_path))
|| is_hidden_internal_name(file_name(new_path))
{
- return self.inner.primary().backend.rename(old_path, new_path).await;
+ return self
+ .inner
+ .primary()
+ .backend
+ .rename(old_path, new_path)
+ .await;
}
let ctx = current_required_ctx()?;
let inner = &self.inner;
@@ -1580,7 +1604,7 @@ impl FileSystem for MultiWriteWrappedFS {
if recursive && search_dir == path_owned {
let redirect_entries = self
- .tree_directory(&path_owned, true, None, level_limit)
+ .tree_directory(&path_owned, true, None, level_limit, None, None, None)
.await?;
for entry in redirect_entries {
if node_limit.is_some_and(|limit| result.count >= limit) {
@@ -1692,7 +1716,7 @@ impl FileSystem for MultiWriteWrappedFS {
}
let entries = self
- .tree_directory(path, show_hidden, None, level_limit)
+ .tree_directory(path, show_hidden, None, level_limit, None, None, None)
.await?;
let mut matched = Vec::new();
@@ -1737,13 +1761,33 @@ impl FileSystem for MultiWriteWrappedFS {
show_hidden: bool,
node_limit: Option<usize>,
level_limit: Option<usize>,
+ offset: Option<usize>,
+ sort_by: Option<ListSortBy>,
+ sort_order: Option<SortOrder>,
) -> Result<Vec<TreeEntry>> {
let base = normalize_prefix_path(path);
+ if sort_by.is_some() {
+ let mut entries = Vec::new();
+ let traversal_limit = node_limit.map(|limit| offset.unwrap_or(0).saturating_add(limit));
+ self.tree_directory_internal(
+ &base,
+ &base,
+ show_hidden,
+ traversal_limit,
+ level_limit,
+ sort_by,
+ sort_order,
+ &mut entries,
+ )
+ .await?;
+ return Ok(paginate_entries(entries, offset, node_limit));
+ }
+
let mut entries = self
.inner
.primary()
.backend
- .tree_directory(path, show_hidden, node_limit, level_limit)
+ .tree_directory(path, show_hidden, None, level_limit, None, None, None)
.await?;
entries.retain(|e| {
@@ -1752,11 +1796,7 @@ impl FileSystem for MultiWriteWrappedFS {
});
if self.inner.redirects.is_empty() {
- return Ok(entries);
- }
-
- if node_limit.is_some_and(|limit| entries.len() >= limit) {
- return Ok(entries);
+ return Ok(paginate_entries(entries, offset, node_limit));
}
let ctx = current_required_ctx()
@@ -1796,15 +1836,11 @@ impl FileSystem for MultiWriteWrappedFS {
})
.buffered(DEFAULT_TREE_REDIRECT_META_CONCURRENCY);
- 'redirect_dirs: while let Some((dir, redirect_meta)) = redirect_results.next().await {
+ while let Some((dir, redirect_meta)) = redirect_results.next().await {
let Some(redirect_meta) = redirect_meta else {
continue;
};
for (name, redirect_entry) in redirect_meta.entries {
- if node_limit.is_some_and(|limit| entries.len() >= limit) {
- break 'redirect_dirs;
- }
-
let virtual_path = if dir == "/" {
format!("/{}", name)
} else {
@@ -1840,6 +1876,6 @@ impl FileSystem for MultiWriteWrappedFS {
}
}
- Ok(entries)
+ Ok(paginate_entries(entries, offset, node_limit))
}
}
diff --git a/crates/ragfs/src/core/multibackend_wrapper/tests.rs b/crates/ragfs/src/core/multibackend_wrapper/tests.rs
index d0ec7bced..bc3763a26 100644
--- a/crates/ragfs/src/core/multibackend_wrapper/tests.rs
+++ b/crates/ragfs/src/core/multibackend_wrapper/tests.rs
@@ -80,7 +80,9 @@ async fn test_read_dir_redirect_entries_use_target_stat() {
)
.await?;
- let entries = fs.read_dir("/local/acct/docs").await?;
+ let entries = fs
+ .read_dir("/local/acct/docs", None, None, None, None)
+ .await?;
let report = entries
.iter()
.find(|entry| entry.name == "report.pdf")
@@ -143,12 +145,14 @@ async fn test_read_dir_redirect_entries_use_target_stat() {
)
.await?;
- let entries = no_redirect_fs.read_dir("/local/acct/docs").await?;
+ let entries = no_redirect_fs
+ .read_dir("/local/acct/docs", None, None, None, None)
+ .await?;
let names: Vec<&str> = entries.iter().map(|entry| entry.name.as_str()).collect();
assert_eq!(names, vec!["real.txt"]);
let tree = no_redirect_fs
- .tree_directory("/local/acct", false, None, Some(3))
+ .tree_directory("/local/acct", false, None, Some(3), None, None, None)
.await?;
let paths: Vec<&str> = tree.iter().map(|entry| entry.path.as_str()).collect();
assert!(!paths.contains(&"/local/acct/docs/ghost.pdf"));
@@ -201,19 +205,43 @@ async fn test_recursive_grep_finds_nested_redirected_files() {
.await?;
let shallow = fs
- .tree_directory("/local/acct/resources", false, None, Some(1))
+ .tree_directory(
+ "/local/acct/resources",
+ false,
+ None,
+ Some(1),
+ None,
+ None,
+ None,
+ )
.await?;
let shallow_paths: Vec<&str> =
shallow.iter().map(|entry| entry.path.as_str()).collect();
assert_eq!(shallow_paths, vec!["/local/acct/resources/doc-1"]);
let root_only = fs
- .tree_directory("/local/acct/resources", false, None, Some(0))
+ .tree_directory(
+ "/local/acct/resources",
+ false,
+ None,
+ Some(0),
+ None,
+ None,
+ None,
+ )
.await?;
assert!(root_only.is_empty());
let deep = fs
- .tree_directory("/local/acct/resources", false, None, Some(2))
+ .tree_directory(
+ "/local/acct/resources",
+ false,
+ None,
+ Some(2),
+ None,
+ None,
+ None,
+ )
.await?;
let deep_paths: Vec<&str> = deep.iter().map(|entry| entry.path.as_str()).collect();
assert_eq!(
@@ -225,7 +253,15 @@ async fn test_recursive_grep_finds_nested_redirected_files() {
);
let capped = fs
- .tree_directory("/local/acct/resources", false, Some(1), Some(2))
+ .tree_directory(
+ "/local/acct/resources",
+ false,
+ Some(1),
+ Some(2),
+ None,
+ None,
+ None,
+ )
.await?;
let capped_paths: Vec<&str> = capped.iter().map(|entry| entry.path.as_str()).collect();
assert_eq!(capped_paths, vec!["/local/acct/resources/doc-1"]);
diff --git a/crates/ragfs/src/core/plugin.rs b/crates/ragfs/src/core/plugin.rs
index 07326e902..21a656efe 100644
--- a/crates/ragfs/src/core/plugin.rs
+++ b/crates/ragfs/src/core/plugin.rs
@@ -220,7 +220,14 @@ mod tests {
) -> Result<u64> {
Ok(_data.len() as u64)
}
- async fn read_dir(&self, _path: &str) -> Result<Vec<FileInfo>> {
+ async fn read_dir(
+ &self,
+ _path: &str,
+ _offset: Option<usize>,
+ _limit: Option<usize>,
+ _sort_by: Option<crate::core::ListSortBy>,
+ _sort_order: Option<crate::core::SortOrder>,
+ ) -> Result<Vec<FileInfo>> {
Ok(vec![])
}
async fn stat(&self, _path: &str) -> Result<FileInfo> {
diff --git a/crates/ragfs/src/core/stats_wrapper.rs b/crates/ragfs/src/core/stats_wrapper.rs
index 3ee069ca1..d731698f3 100644
--- a/crates/ragfs/src/core/stats_wrapper.rs
+++ b/crates/ragfs/src/core/stats_wrapper.rs
@@ -106,9 +106,19 @@ impl FileSystem for StatsWrappedFS {
result
}
- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
+ async fn read_dir(
+ &self,
+ path: &str,
+ offset: Option<usize>,
+ limit: Option<usize>,
+ sort_by: Option<crate::core::ListSortBy>,
+ sort_order: Option<crate::core::SortOrder>,
+ ) -> Result<Vec<FileInfo>> {
let timer = OperationTimer::start(FsOperation::ReadDir, Arc::clone(&self.stats));
- let result = self.inner.read_dir(path).await;
+ let result = self
+ .inner
+ .read_dir(path, offset, limit, sort_by, sort_order)
+ .await;
timer.finish().await;
result
}
@@ -195,11 +205,22 @@ impl FileSystem for StatsWrappedFS {
show_hidden: bool,
node_limit: Option<usize>,
level_limit: Option<usize>,
+ offset: Option<usize>,
+ sort_by: Option<crate::core::ListSortBy>,
+ sort_order: Option<crate::core::SortOrder>,
) -> Result<Vec<TreeEntry>> {
let timer = OperationTimer::start(FsOperation::TreeDir, Arc::clone(&self.stats));
let result = self
.inner
- .tree_directory(path, show_hidden, node_limit, level_limit)
+ .tree_directory(
+ path,
+ show_hidden,
+ node_limit,
+ level_limit,
+ offset,
+ sort_by,
+ sort_order,
+ )
.await;
timer.finish().await;
result
diff --git a/crates/ragfs/src/core/types.rs b/crates/ragfs/src/core/types.rs
index 35d9f64f5..eb0af3c76 100644
--- a/crates/ragfs/src/core/types.rs
+++ b/crates/ragfs/src/core/types.rs
@@ -8,6 +8,26 @@ use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::time::SystemTime;
+/// Supported directory listing sort fields.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ListSortBy {
+ /// Sort entries by name.
+ Name,
+ /// Sort entries by modification time.
+ Mtime,
+}
+
+/// Supported directory listing sort directions.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum SortOrder {
+ /// Sort values in ascending order.
+ Asc,
+ /// Sort values in descending order.
+ Desc,
+}
+
/// Grep match result
///
/// Represents a single match found during a grep operation.
diff --git a/crates/ragfs/src/git/enumerate.rs b/crates/ragfs/src/git/enumerate.rs
index ff31968fe..a06c0d14d 100644
--- a/crates/ragfs/src/git/enumerate.rs
+++ b/crates/ragfs/src/git/enumerate.rs
@@ -106,7 +106,9 @@ pub async fn collect_under(
};
let account_prefix = format!("/local/{}/", account);
- let entries = vfs.tree_directory(&root, true, None, None).await?;
+ let entries = vfs
+ .tree_directory(&root, true, None, None, None, None, None)
+ .await?;
let mut survivors = Vec::new();
for entry in entries {
@@ -193,7 +195,14 @@ mod tests {
) -> Result<u64> {
unimplemented!()
}
- async fn read_dir(&self, _path: &str) -> Result<Vec<FileInfo>> {
+ async fn read_dir(
+ &self,
+ _path: &str,
+ _offset: Option<usize>,
+ _limit: Option<usize>,
+ _sort_by: Option<crate::core::ListSortBy>,
+ _sort_order: Option<crate::core::SortOrder>,
+ ) -> Result<Vec<FileInfo>> {
unimplemented!()
}
async fn stat(&self, _path: &str) -> Result<FileInfo> {
@@ -214,6 +223,9 @@ mod tests {
_show_hidden: bool,
_node_limit: Option<usize>,
_level_limit: Option<usize>,
+ _offset: Option<usize>,
+ _sort_by: Option<crate::core::ListSortBy>,
+ _sort_order: Option<crate::core::SortOrder>,
) -> Result<Vec<TreeEntry>> {
let raw = self.entries_by_root.get(path).cloned().unwrap_or_default();
diff --git a/crates/ragfs/src/git/service.rs b/crates/ragfs/src/git/service.rs
index 6d4d6a9e1..52781e54d 100644
--- a/crates/ragfs/src/git/service.rs
+++ b/crates/ragfs/src/git/service.rs
@@ -1267,6 +1267,10 @@ impl GitService {
let is_empty = match crate::core::filesystem::FileSystem::read_dir(
self.vfs.as_ref(),
&abs,
+ None,
+ None,
+ None,
+ None,
)
.await
{
@@ -1948,7 +1952,14 @@ mod tests {
.insert(path.to_string(), data.to_vec());
Ok(data.len() as u64)
}
- async fn read_dir(&self, _path: &str) -> Result<Vec<FileInfo>> {
+ async fn read_dir(
+ &self,
+ _path: &str,
+ _offset: Option<usize>,
+ _limit: Option<usize>,
+ _sort_by: Option<crate::core::ListSortBy>,
+ _sort_order: Option<crate::core::SortOrder>,
+ ) -> Result<Vec<FileInfo>> {
unimplemented!()
}
@@ -1974,6 +1985,9 @@ mod tests {
_show_hidden: bool,
_node_limit: Option<usize>,
_level_limit: Option<usize>,
+ _offset: Option<usize>,
+ _sort_by: Option<crate::core::ListSortBy>,
+ _sort_order: Option<crate::core::SortOrder>,
) -> Result<Vec<TreeEntry>> {
let prefix = if path == "/" {
"/".to_string()
@@ -6070,7 +6084,14 @@ mod fast_path1_tests {
.insert(path.to_string(), (data.to_vec(), 0));
Ok(data.len() as u64)
}
- async fn read_dir(&self, _path: &str) -> Result<Vec<FileInfo>> {
+ async fn read_dir(
+ &self,
+ _path: &str,
+ _offset: Option<usize>,
+ _limit: Option<usize>,
+ _sort_by: Option<crate::core::ListSortBy>,
+ _sort_order: Option<crate::core::SortOrder>,
+ ) -> Result<Vec<FileInfo>> {
unimplemented!()
}
@@ -6102,6 +6123,9 @@ mod fast_path1_tests {
_show_hidden: bool,
_node_limit: Option<usize>,
_level_limit: Option<usize>,
+ _offset: Option<usize>,
+ _sort_by: Option<crate::core::ListSortBy>,
+ _sort_order: Option<crate::core::SortOrder>,
) -> Result<Vec<TreeEntry>> {
let prefix = if path == "/" {
"/".to_string()
diff --git a/crates/ragfs/src/lock/manager.rs b/crates/ragfs/src/lock/manager.rs
index 5ed5b4cdb..2bcc45d62 100644
--- a/crates/ragfs/src/lock/manager.rs
+++ b/crates/ragfs/src/lock/manager.rs
@@ -2113,8 +2113,17 @@ mod tests {
self.inner.write(path, data, offset, flags).await
}
- async fn read_dir(&self, path: &str) -> FsResult<Vec<FileInfo>> {
- self.inner.read_dir(path).await
+ async fn read_dir(
+ &self,
+ path: &str,
+ offset: Option<usize>,
+ limit: Option<usize>,
+ sort_by: Option<crate::core::ListSortBy>,
+ sort_order: Option<crate::core::SortOrder>,
+ ) -> FsResult<Vec<FileInfo>> {
+ self.inner
+ .read_dir(path, offset, limit, sort_by, sort_order)
+ .await
}
async fn stat(&self, path: &str) -> FsResult<FileInfo> {
diff --git a/crates/ragfs/src/lock/wrapper.rs b/crates/ragfs/src/lock/wrapper.rs
index 89da83064..4bd9653ae 100644
--- a/crates/ragfs/src/lock/wrapper.rs
+++ b/crates/ragfs/src/lock/wrapper.rs
@@ -7,13 +7,15 @@
//! It is NOT a lock protocol implementation — all lock logic is delegated to
//! `PathLockManager`.
-use std::sync::Arc;
use async_trait::async_trait;
+use std::sync::Arc;
use tracing::debug;
use crate::core::filesystem::FileSystem;
use crate::core::internal_names::is_hidden_runtime_lock_name;
-use crate::core::types::{FileInfo, GlobPage, GrepResult, TreeEntry, WriteFlag};
+use crate::core::types::{
+ FileInfo, GlobPage, GrepResult, ListSortBy, SortOrder, TreeEntry, WriteFlag,
+};
use crate::core::MountableFS;
use super::manager::{AutoPathLockAction, PathLockManager};
@@ -58,9 +60,18 @@ impl PathLockWrappedFS {
requests: &[PathLockRequest],
) -> crate::core::Result<bool> {
match self.manager.resolve_auto_pathlock_action(requests).await {
- Ok(AutoPathLockAction::Disabled) => { debug!(requests = ?requests, "pathlock wrapper skipped auto-lock because context disabled it"); Ok(true) }
- Ok(AutoPathLockAction::Covered(lease)) => { debug!(lease_ref = %lease.lease.lease_ref, requests = ?requests, "pathlock wrapper skipped auto-lock because active lease already covers request"); Ok(true) }
- Ok(AutoPathLockAction::Acquire) => { debug!(requests = ?requests, "pathlock wrapper will auto-acquire lease for request"); Ok(false) }
+ Ok(AutoPathLockAction::Disabled) => {
+ debug!(requests = ?requests, "pathlock wrapper skipped auto-lock because context disabled it");
+ Ok(true)
+ }
+ Ok(AutoPathLockAction::Covered(lease)) => {
+ debug!(lease_ref = %lease.lease.lease_ref, requests = ?requests, "pathlock wrapper skipped auto-lock because active lease already covers request");
+ Ok(true)
+ }
+ Ok(AutoPathLockAction::Acquire) => {
+ debug!(requests = ?requests, "pathlock wrapper will auto-acquire lease for request");
+ Ok(false)
+ }
Err(error) => Err(crate::core::Error::internal(format!(
"lock lease error: {error}"
))),
@@ -191,8 +202,17 @@ impl FileSystem for PathLockWrappedFS {
Self::merge_operation_and_release(result, release)
}
- async fn read_dir(&self, path: &str) -> crate::core::Result<Vec<FileInfo>> {
- self.inner.read_dir(path).await
+ async fn read_dir(
+ &self,
+ path: &str,
+ offset: Option<usize>,
+ limit: Option<usize>,
+ sort_by: Option<ListSortBy>,
+ sort_order: Option<SortOrder>,
+ ) -> crate::core::Result<Vec<FileInfo>> {
+ self.inner
+ .read_dir(path, offset, limit, sort_by, sort_order)
+ .await
}
async fn stat(&self, path: &str) -> crate::core::Result<FileInfo> {
@@ -332,9 +352,20 @@ impl FileSystem for PathLockWrappedFS {
show_hidden: bool,
node_limit: Option<usize>,
level_limit: Option<usize>,
+ offset: Option<usize>,
+ sort_by: Option<ListSortBy>,
+ sort_order: Option<SortOrder>,
) -> crate::core::Result<Vec<TreeEntry>> {
self.inner
- .tree_directory(path, show_hidden, node_limit, level_limit)
+ .tree_directory(
+ path,
+ show_hidden,
+ node_limit,
+ level_limit,
+ offset,
+ sort_by,
+ sort_order,
+ )
.await
}
diff --git a/crates/ragfs/src/multibackend/admin.rs b/crates/ragfs/src/multibackend/admin.rs
index f9d12331b..9a5e684a2 100644
--- a/crates/ragfs/src/multibackend/admin.rs
+++ b/crates/ragfs/src/multibackend/admin.rs
@@ -39,7 +39,7 @@ impl MultiWriteWrappedFS {
for entry in inner
.primary()
.backend
- .tree_directory(&normalized, true, None, None)
+ .tree_directory(&normalized, true, None, None, None, None, None)
.await?
{
if entry.info.is_dir {
diff --git a/crates/ragfs/src/plugins/kvfs/mod.rs b/crates/ragfs/src/plugins/kvfs/mod.rs
index 85be8ed6e..32803b79d 100644
--- a/crates/ragfs/src/plugins/kvfs/mod.rs
+++ b/crates/ragfs/src/plugins/kvfs/mod.rs
@@ -256,7 +256,14 @@ impl FileSystem for KVFileSystem {
}
}
- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
+ async fn read_dir(
+ &self,
+ path: &str,
+ offset: Option<usize>,
+ limit: Option<usize>,
+ sort_by: Option<crate::core::ListSortBy>,
+ sort_order: Option<crate::core::SortOrder>,
+ ) -> Result<Vec<FileInfo>> {
let key = Self::path_to_key(path);
let store = self.store.read().await;
@@ -281,7 +288,9 @@ impl FileSystem for KVFileSystem {
}
}
- Ok(result)
+ Ok(crate::core::filesystem::apply_read_dir_options(
+ result, offset, limit, sort_by, sort_order,
+ ))
}
async fn stat(&self, path: &str) -> Result<FileInfo> {
@@ -517,7 +526,7 @@ mod tests {
write_key(&fs, "/key2", b"val2").await;
write_key(&fs, "/key3", b"val3").await;
- let entries = fs.read_dir("/").await.unwrap();
+ let entries = fs.read_dir("/", None, None, None, None).await.unwrap();
assert_eq!(entries.len(), 3);
}
@@ -531,7 +540,7 @@ mod tests {
write_key(&fs, "/user/123", b"alice").await;
write_key(&fs, "/user/456", b"bob").await;
- let entries = fs.read_dir("/user").await.unwrap();
+ let entries = fs.read_dir("/user", None, None, None, None).await.unwrap();
assert_eq!(entries.len(), 2);
}
diff --git a/crates/ragfs/src/plugins/localfs/mod.rs b/crates/ragfs/src/plugins/localfs/mod.rs
index 928f537ba..a5c1f35f3 100644
--- a/crates/ragfs/src/plugins/localfs/mod.rs
+++ b/crates/ragfs/src/plugins/localfs/mod.rs
@@ -20,7 +20,9 @@ use crate::core::errors::{Error, Result};
use crate::core::filesystem::{validate_virtual_path, FileSystem};
use crate::core::glob::{decode_offset_token, encode_offset_token, PreparedGlob};
use crate::core::plugin::ServicePlugin;
-use crate::core::types::{ConfigParameter, FileInfo, GlobEntry, GlobPage, GrepResult, PluginConfig, WriteFlag};
+use crate::core::types::{
+ ConfigParameter, FileInfo, GlobEntry, GlobPage, GrepResult, PluginConfig, WriteFlag,
+};
/// LocalFS - Local file system implementation
pub struct LocalFileSystem {
@@ -208,8 +210,9 @@ impl LocalFileSystem {
return Ok(false);
}
- file.set_len(0)
- .map_err(|e| Error::plugin(format!("failed to truncate for compare_and_write: {}", e)))?;
+ file.set_len(0).map_err(|e| {
+ Error::plugin(format!("failed to truncate for compare_and_write: {}", e))
+ })?;
file.seek(SeekFrom::Start(0))
.map_err(|e| Error::plugin(format!("failed to rewind for compare_and_write: {}", e)))?;
file.write_all(&new_data)
@@ -261,8 +264,9 @@ impl LocalFileSystem {
return Ok(false);
}
- fs::remove_file(&local_path)
- .map_err(|e| Error::plugin(format!("failed to remove for compare_and_remove: {}", e)))?;
+ fs::remove_file(&local_path).map_err(|e| {
+ Error::plugin(format!("failed to remove for compare_and_remove: {}", e))
+ })?;
Ok(true)
}
@@ -815,7 +819,8 @@ impl LocalFileSystem {
break;
}
- let dent = dent.map_err(|e| Error::plugin(format!("failed to walk directory: {}", e)))?;
+ let dent =
+ dent.map_err(|e| Error::plugin(format!("failed to walk directory: {}", e)))?;
raw_seen += 1;
if raw_seen <= start {
@@ -849,11 +854,14 @@ impl LocalFileSystem {
});
}
- let next_token = next_offset
- .filter(|_| page_size.is_some())
- .map(|offset| encode_offset_token(offset, virtual_path, pattern, show_hidden, level_limit));
+ let next_token = next_offset.filter(|_| page_size.is_some()).map(|offset| {
+ encode_offset_token(offset, virtual_path, pattern, show_hidden, level_limit)
+ });
- Ok(GlobPage { entries, next_token })
+ Ok(GlobPage {
+ entries,
+ next_token,
+ })
}
fn resolve_virtual_path(base_path: &Path, path: &str) -> PathBuf {
@@ -1058,11 +1066,18 @@ impl FileSystem for LocalFileSystem {
Self::run_blocking_fs(move || Self::compare_and_remove_locked(local_path, expected)).await
}
- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
+ async fn read_dir(
+ &self,
+ path: &str,
+ offset: Option<usize>,
+ limit: Option<usize>,
+ sort_by: Option<crate::core::ListSortBy>,
+ sort_order: Option<crate::core::SortOrder>,
+ ) -> Result<Vec<FileInfo>> {
let local_path = self.resolve_path(path)?;
let path = path.to_string();
- Self::run_blocking_fs(move || {
+ let entries = Self::run_blocking_fs(move || {
// Check if directory exists
if !local_path.exists() {
return Err(Error::NotFound(path.clone()));
@@ -1101,7 +1116,10 @@ impl FileSystem for LocalFileSystem {
Ok(files)
})
- .await
+ .await?;
+ Ok(crate::core::filesystem::apply_read_dir_options(
+ entries, offset, limit, sort_by, sort_order,
+ ))
}
async fn stat(&self, path: &str) -> Result<FileInfo> {
@@ -1180,58 +1198,58 @@ impl FileSystem for LocalFileSystem {
}
}
- // Keep replace semantics explicit instead of inheriting rename behavior:
- // encrypted publish needs an overwrite-on-destination move.
- #[cfg(windows)]
- {
- use std::ffi::OsStr;
- use std::io;
- use std::os::windows::ffi::OsStrExt;
-
- type BOOL = i32;
- type DWORD = u32;
- type LPCWSTR = *const u16;
-
- const MOVEFILE_REPLACE_EXISTING: DWORD = 0x1;
- const MOVEFILE_WRITE_THROUGH: DWORD = 0x8;
-
- unsafe extern "system" {
- fn MoveFileExW(
- lpExistingFileName: LPCWSTR,
- lpNewFileName: LPCWSTR,
- dwFlags: DWORD,
- ) -> BOOL;
- }
-
- let src_wide: Vec<u16> = OsStr::new(src_local.as_os_str())
- .encode_wide()
- .chain(std::iter::once(0))
- .collect();
- let dst_wide: Vec<u16> = OsStr::new(dst_local.as_os_str())
- .encode_wide()
- .chain(std::iter::once(0))
- .collect();
-
- let replaced = unsafe {
- MoveFileExW(
- src_wide.as_ptr(),
- dst_wide.as_ptr(),
- MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH,
- )
- };
- if replaced == 0 {
- return Err(Error::plugin(format!(
- "failed to replace: {}",
- io::Error::last_os_error()
- )));
- }
- }
-
- #[cfg(not(windows))]
- {
- fs::rename(&src_local, &dst_local)
- .map_err(|e| Error::plugin(format!("failed to replace: {}", e)))?;
- }
+ // Keep replace semantics explicit instead of inheriting rename behavior:
+ // encrypted publish needs an overwrite-on-destination move.
+ #[cfg(windows)]
+ {
+ use std::ffi::OsStr;
+ use std::io;
+ use std::os::windows::ffi::OsStrExt;
+
+ type BOOL = i32;
+ type DWORD = u32;
+ type LPCWSTR = *const u16;
+
+ const MOVEFILE_REPLACE_EXISTING: DWORD = 0x1;
+ const MOVEFILE_WRITE_THROUGH: DWORD = 0x8;
+
+ unsafe extern "system" {
+ fn MoveFileExW(
+ lpExistingFileName: LPCWSTR,
+ lpNewFileName: LPCWSTR,
+ dwFlags: DWORD,
+ ) -> BOOL;
+ }
+
+ let src_wide: Vec<u16> = OsStr::new(src_local.as_os_str())
+ .encode_wide()
+ .chain(std::iter::once(0))
+ .collect();
+ let dst_wide: Vec<u16> = OsStr::new(dst_local.as_os_str())
+ .encode_wide()
+ .chain(std::iter::once(0))
+ .collect();
+
+ let replaced = unsafe {
+ MoveFileExW(
+ src_wide.as_ptr(),
+ dst_wide.as_ptr(),
+ MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH,
+ )
+ };
+ if replaced == 0 {
+ return Err(Error::plugin(format!(
+ "failed to replace: {}",
+ io::Error::last_os_error()
+ )));
+ }
+ }
+
+ #[cfg(not(windows))]
+ {
+ fs::rename(&src_local, &dst_local)
+ .map_err(|e| Error::plugin(format!("failed to replace: {}", e)))?;
+ }
Ok(())
}
@@ -1781,7 +1799,10 @@ mod tests {
let (dir, fs) = fallback_localfs();
std::fs::create_dir_all(dir.path().join("folder")).unwrap();
- let out = fs.glob_directory("/", "**/*", false, None, None, None).await.unwrap();
+ let out = fs
+ .glob_directory("/", "**/*", false, None, None, None)
+ .await
+ .unwrap();
assert_eq!(
out.entries
.iter()
@@ -1847,7 +1868,10 @@ mod tests {
write_file(dir.path(), ".hidden.md", "");
write_file(dir.path(), ".hidden_dir/nested.md", "");
- let out = fs.glob_directory("/", "**/*.md", false, None, None, None).await.unwrap();
+ let out = fs
+ .glob_directory("/", "**/*.md", false, None, None, None)
+ .await
+ .unwrap();
assert_eq!(
out.entries
.iter()
@@ -1870,12 +1894,17 @@ mod tests {
write_file(dir.path(), "z_blocked/late.md", "");
let blocked_dir = dir.path().join("z_blocked");
- let old_mode = std::fs::metadata(&blocked_dir).unwrap().permissions().mode();
+ let old_mode = std::fs::metadata(&blocked_dir)
+ .unwrap()
+ .permissions()
+ .mode();
let mut perms = std::fs::metadata(&blocked_dir).unwrap().permissions();
perms.set_mode(0);
std::fs::set_permissions(&blocked_dir, perms).unwrap();
- let first = fs.glob_directory("/", "**/*.md", false, Some(2), None, None).await;
+ let first = fs
+ .glob_directory("/", "**/*.md", false, Some(2), None, None)
+ .await;
assert!(first.is_ok());
let first = first.unwrap();
assert_eq!(
diff --git a/crates/ragfs/src/plugins/memfs/mod.rs b/crates/ragfs/src/plugins/memfs/mod.rs
index bdec5a9e8..c3645ab22 100644
--- a/crates/ragfs/src/plugins/memfs/mod.rs
+++ b/crates/ragfs/src/plugins/memfs/mod.rs
@@ -357,7 +357,14 @@ impl FileSystem for MemFileSystem {
Ok(matches)
}
- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
+ async fn read_dir(
+ &self,
+ path: &str,
+ offset: Option<usize>,
+ limit: Option<usize>,
+ sort_by: Option<crate::core::ListSortBy>,
+ sort_order: Option<crate::core::SortOrder>,
+ ) -> Result<Vec<FileInfo>> {
let normalized = Self::normalize_path(path);
let entries = self.entries.read().await;
@@ -385,7 +392,9 @@ impl FileSystem for MemFileSystem {
}
}
- Ok(result)
+ Ok(crate::core::filesystem::apply_read_dir_options(
+ result, offset, limit, sort_by, sort_order,
+ ))
}
async fn stat(&self, path: &str) -> Result<FileInfo> {
@@ -495,7 +504,10 @@ impl FileSystem for MemFileSystem {
}
}
- if entries.get(&dst_normalized).is_some_and(|entry| entry.is_dir) {
+ if entries
+ .get(&dst_normalized)
+ .is_some_and(|entry| entry.is_dir)
+ {
return Err(Error::IsADirectory(dst_normalized));
}
@@ -641,7 +653,10 @@ mod tests {
fs.create("/testdir/file2.txt").await.unwrap();
// List directory
- let entries = fs.read_dir("/testdir").await.unwrap();
+ let entries = fs
+ .read_dir("/testdir", None, None, None, None)
+ .await
+ .unwrap();
assert_eq!(entries.len(), 2);
}
diff --git a/crates/ragfs/src/plugins/queuefs/mod.rs b/crates/ragfs/src/plugins/queuefs/mod.rs
index 43bbc8511..b0659bd75 100644
--- a/crates/ragfs/src/plugins/queuefs/mod.rs
+++ b/crates/ragfs/src/plugins/queuefs/mod.rs
@@ -436,7 +436,14 @@ impl FileSystem for QueueFileSystem {
}
}
- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
+ async fn read_dir(
+ &self,
+ path: &str,
+ offset: Option<usize>,
+ limit: Option<usize>,
+ sort_by: Option<crate::core::ListSortBy>,
+ sort_order: Option<crate::core::SortOrder>,
+ ) -> Result<Vec<FileInfo>> {
let parsed = Self::parse_queue_path(path)?;
if !parsed.is_dir {
@@ -456,7 +463,7 @@ impl FileSystem for QueueFileSystem {
}
}
- return Ok(top_level
+ let entries = top_level
.into_iter()
.map(|name| FileInfo {
name,
@@ -465,7 +472,10 @@ impl FileSystem for QueueFileSystem {
mod_time: now,
is_dir: true,
})
- .collect());
+ .collect();
+ return Ok(crate::core::filesystem::apply_read_dir_options(
+ entries, offset, limit, sort_by, sort_order,
+ ));
}
// Queue directory: check if it has nested queues
@@ -489,7 +499,7 @@ impl FileSystem for QueueFileSystem {
}
}
- return Ok(subdirs
+ let entries = subdirs
.into_iter()
.map(|name| FileInfo {
name,
@@ -498,7 +508,10 @@ impl FileSystem for QueueFileSystem {
mod_time: now,
is_dir: true,
})
- .collect());
+ .collect();
+ return Ok(crate::core::filesystem::apply_read_dir_options(
+ entries, offset, limit, sort_by, sort_order,
+ ));
}
// Leaf queue: return control files
@@ -506,7 +519,13 @@ impl FileSystem for QueueFileSystem {
return Err(Error::NotFound(format!("queue not found: {}", queue_name)));
}
- Ok(Self::leaf_control_files(now))
+ Ok(crate::core::filesystem::apply_read_dir_options(
+ Self::leaf_control_files(now),
+ offset,
+ limit,
+ sort_by,
+ sort_order,
+ ))
}
async fn stat(&self, path: &str) -> Result<FileInfo> {
@@ -979,13 +998,16 @@ mod tests {
let fs = queuefs_with("test").await;
// Root should list the queue
- let entries = fs.read_dir("/").await.unwrap();
+ let entries = fs.read_dir("/", None, None, None, None).await.unwrap();
assert_eq!(entries.len(), 1);
assert_eq!(entries[0].name, "test");
assert!(entries[0].is_dir);
// Queue directory should list control files
- let entries = fs.read_dir("/test").await.unwrap();
+ let entries = fs
+ .read_dir("/test", None, None, None, None)
+ .await
+ .unwrap();
assert_eq!(entries.len(), 7);
let names: Vec<String> = entries.iter().map(|e| e.name.clone()).collect();
@@ -1144,7 +1166,10 @@ mod tests {
fs.mkdir("/logs/warnings", 0o755).await.unwrap();
// List /logs should show subdirectories
- let entries = fs.read_dir("/logs").await.unwrap();
+ let entries = fs
+ .read_dir("/logs", None, None, None, None)
+ .await
+ .unwrap();
assert_eq!(entries.len(), 2);
let names: Vec<_> = entries.iter().map(|e| e.name.as_str()).collect();
assert!(names.contains(&"errors"));
@@ -1252,7 +1277,10 @@ mod tests {
provider.set_unavailable(true);
assert!(matches!(fs.stat("/Semantic").await, Err(Error::Network(_))));
- assert!(matches!(fs.read_dir("/").await, Err(Error::Network(_))));
+ assert!(matches!(
+ fs.read_dir("/", None, None, None, None).await,
+ Err(Error::Network(_))
+ ));
}
#[tokio::test]
diff --git a/crates/ragfs/src/plugins/s3fs/mod.rs b/crates/ragfs/src/plugins/s3fs/mod.rs
index eeec24015..4cc2297a5 100644
--- a/crates/ragfs/src/plugins/s3fs/mod.rs
+++ b/crates/ragfs/src/plugins/s3fs/mod.rs
@@ -283,12 +283,16 @@ impl S3FileSystem {
page_offset: 0,
last_rel_parts: Vec::new(),
}),
- Some(raw) if raw.is_empty() => Err(Error::invalid_operation("empty continuation token")),
+ Some(raw) if raw.is_empty() => {
+ Err(Error::invalid_operation("empty continuation token"))
+ }
Some(raw) => {
let state: S3GlobToken = serde_json::from_str(raw)
.map_err(|_| Error::invalid_operation("invalid continuation token"))?;
if state.scope != scope {
- return Err(Error::invalid_operation("continuation token scope mismatch"));
+ return Err(Error::invalid_operation(
+ "continuation token scope mismatch",
+ ));
}
Ok(state)
}
@@ -355,7 +359,6 @@ impl S3FileSystem {
Ok((matched, next_last_rel_parts))
}
-
/// Get file name from path
fn file_name(path: &str) -> String {
if path == "/" {
@@ -599,7 +602,9 @@ impl FileSystem for S3FileSystem {
match flags {
WriteFlag::CreateNew => {
- self.client.put_object_create_new(&key, data.to_vec()).await?;
+ self.client
+ .put_object_create_new(&key, data.to_vec())
+ .await?;
}
_ => {
// S3 always replaces the full object for non-exclusive writes.
@@ -656,12 +661,21 @@ impl FileSystem for S3FileSystem {
Ok(changed)
}
- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
+ async fn read_dir(
+ &self,
+ path: &str,
+ offset: Option<usize>,
+ limit: Option<usize>,
+ sort_by: Option<crate::core::ListSortBy>,
+ sort_order: Option<crate::core::SortOrder>,
+ ) -> Result<Vec<FileInfo>> {
let normalized = Self::normalize_path(path);
// Check cache
if let Some(files) = self.dir_cache.get(&normalized).await {
- return Ok(files);
+ return Ok(crate::core::filesystem::apply_read_dir_options(
+ files, offset, limit, sort_by, sort_order,
+ ));
}
// Build prefix for listing
@@ -720,7 +734,9 @@ impl FileSystem for S3FileSystem {
// Cache
self.dir_cache.put(normalized.clone(), files.clone()).await;
- Ok(files)
+ Ok(crate::core::filesystem::apply_read_dir_options(
+ files, offset, limit, sort_by, sort_order,
+ ))
}
async fn stat(&self, path: &str) -> Result<FileInfo> {
@@ -857,7 +873,6 @@ impl FileSystem for S3FileSystem {
Err(Error::not_found(&old_normalized))
}
-
async fn replace(&self, src_path: &str, dst_path: &str) -> Result<()> {
let src_normalized = Self::normalize_path(src_path);
let dst_normalized = Self::normalize_path(dst_path);
@@ -1011,8 +1026,29 @@ impl FileSystem for S3FileSystem {
show_hidden: bool,
node_limit: Option<usize>,
level_limit: Option<usize>,
+ offset: Option<usize>,
+ sort_by: Option<crate::core::ListSortBy>,
+ sort_order: Option<crate::core::SortOrder>,
) -> Result<Vec<TreeEntry>> {
let normalized = Self::normalize_path(path);
+ if sort_by.is_some() {
+ let mut result = Vec::new();
+ let traversal_limit = node_limit.map(|limit| offset.unwrap_or(0).saturating_add(limit));
+ self.tree_directory_internal(
+ &normalized,
+ &normalized,
+ show_hidden,
+ traversal_limit,
+ level_limit,
+ sort_by,
+ sort_order,
+ &mut result,
+ )
+ .await?;
+ return Ok(crate::core::filesystem::paginate_entries(
+ result, offset, node_limit,
+ ));
+ }
let prefix = if normalized == "/" {
self.client.build_key("")
@@ -1030,15 +1066,9 @@ impl FileSystem for S3FileSystem {
|key| self.client.strip_prefix(key),
)?;
- let mut result = Vec::new();
- for entry in ordered {
- if node_limit.is_some_and(|limit| result.len() >= limit) {
- break;
- }
- result.push(entry);
- }
-
- Ok(result)
+ Ok(crate::core::filesystem::paginate_entries(
+ ordered, offset, node_limit,
+ ))
}
async fn glob_directory(
diff --git a/crates/ragfs/src/plugins/serverinfofs/mod.rs b/crates/ragfs/src/plugins/serverinfofs/mod.rs
index 72df71aea..9c490ce77 100644
--- a/crates/ragfs/src/plugins/serverinfofs/mod.rs
+++ b/crates/ragfs/src/plugins/serverinfofs/mod.rs
@@ -211,7 +211,14 @@ impl FileSystem for ServerInfoFileSystem {
))
}
- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
+ async fn read_dir(
+ &self,
+ path: &str,
+ offset: Option<usize>,
+ limit: Option<usize>,
+ sort_by: Option<crate::core::ListSortBy>,
+ sort_order: Option<crate::core::SortOrder>,
+ ) -> Result<Vec<FileInfo>> {
if path != "/" {
return Err(Error::plugin(format!("not a directory: {}", path)));
}
@@ -225,7 +232,7 @@ impl FileSystem for ServerInfoFileSystem {
let stats = self.get_stats();
let readme = self.get_readme();
- Ok(vec![
+ let entries = vec![
FileInfo::new("README".to_string(), readme.len() as u64, 0o444, now, false),
FileInfo::new(
"server_info".to_string(),
@@ -243,7 +250,10 @@ impl FileSystem for ServerInfoFileSystem {
false,
),
FileInfo::new("stats".to_string(), stats.len() as u64, 0o444, now, false),
- ])
+ ];
+ Ok(crate::core::filesystem::apply_read_dir_options(
+ entries, offset, limit, sort_by, sort_order,
+ ))
}
async fn stat(&self, path: &str) -> Result<FileInfo> {
diff --git a/crates/ragfs/src/plugins/sqlfs/mod.rs b/crates/ragfs/src/plugins/sqlfs/mod.rs
index 0ab7bb367..31fe11f99 100644
--- a/crates/ragfs/src/plugins/sqlfs/mod.rs
+++ b/crates/ragfs/src/plugins/sqlfs/mod.rs
@@ -412,12 +412,21 @@ impl FileSystem for SQLFileSystem {
Ok(changed)
}
- async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
+ async fn read_dir(
+ &self,
+ path: &str,
+ offset: Option<usize>,
+ limit: Option<usize>,
+ sort_by: Option<crate::core::ListSortBy>,
+ sort_order: Option<crate::core::SortOrder>,
+ ) -> Result<Vec<FileInfo>> {
let normalized = Self::normalize_path(path);
// Try cache first
if let Some(files) = self.cache.get(&normalized).await {
- return Ok(files);
+ return Ok(crate::core::filesystem::apply_read_dir_options(
+ files, offset, limit, sort_by, sort_order,
+ ));
}
let normalized_for_db = normalized.clone();
@@ -453,7 +462,9 @@ impl FileSystem for SQLFileSystem {
// Cache the result
self.cache.put(normalized.clone(), files.clone()).await;
- Ok(files)
+ Ok(crate::core::filesystem::apply_read_dir_options(
+ files, offset, limit, sort_by, sort_order,
+ ))
}
async fn stat(&self, path: &str) -> Result<FileInfo> {
@@ -799,7 +810,10 @@ mod tests {
write_file(&fs, "/testdir/file.txt", b"data").await;
// List directory
- let entries = fs.read_dir("/testdir").await.unwrap();
+ let entries = fs
+ .read_dir("/testdir", None, None, None, None)
+ .await
+ .unwrap();
assert_eq!(entries.len(), 1);
assert_eq!(entries[0].name, "file.txt");
@@ -862,7 +876,7 @@ mod tests {
write_file(&fs, "/a/b/file.txt", b"nested").await;
// List /a should only show /a/b
- let entries = fs.read_dir("/a").await.unwrap();
+ let entries = fs.read_dir("/a", None, None, None, None).await.unwrap();
assert_eq!(entries.len(), 1);
assert_eq!(entries[0].name, "b");
assert!(entries[0].is_dir);
diff --git a/crates/ragfs/src/shape/probe.rs b/crates/ragfs/src/shape/probe.rs
index 254c78e40..2dace2ed3 100644
--- a/crates/ragfs/src/shape/probe.rs
+++ b/crates/ragfs/src/shape/probe.rs
@@ -115,7 +115,7 @@ pub async fn write_shape_guard(
/// Probe existing backend files to infer the legacy storage shape.
pub async fn detect_legacy_shape(raw_fs: &Arc<dyn FileSystem>) -> Result<Option<StorageShape>> {
- let entries = raw_fs.tree_directory("/", true, None, None).await?;
+ let entries = raw_fs.tree_directory("/", true, None, None, None, None, None).await?;
let mut candidates = Vec::new();
for entry in entries {
diff --git a/docs/en/api/03-filesystem.md b/docs/en/api/03-filesystem.md
index 1694ea715..6923b3cc5 100644
--- a/docs/en/api/03-filesystem.md
+++ b/docs/en/api/03-filesystem.md
@@ -23,12 +23,14 @@ List directory contents.
| abs_limit | int | No | 256 | Abstract length limit for `agent` output |
| show_all_hidden | bool | No | False | Include hidden files like `-a` |
| node_limit | int | No | 1000 | Maximum number of results |
-| sort_by | str | No | None | Sort directories and files within their groups by `name` or `mtime` before applying `node_limit`; directories remain first |
+| offset | int | No | 0 | Number of visible results to skip |
+| limit | int | No | None | Alias for `node_limit` |
+| sort_by | str | No | None | Sort directories and files within their groups by `name` or `mtime` before pagination; directories remain first |
| sort_order | str | No | `asc` | Sort direction: `asc` or `desc` |
| extra_fields | list[str] | No | None | Extra fields to include: `locked`, `id`, `count` |
| tags | string[] | No | Unset | Return only entries matching every supplied `k=v` retrieval tag |
-`tags` uses AND semantics and is applied before `node_limit`. Tags are included for filtered responses; for an unfiltered response, request `include_tags=true` (CLI: `-f tags`).
+`tags` uses AND semantics and is applied before `offset` and `limit`. Tags are included for filtered responses; for an unfiltered response, request `include_tags=true` (CLI: `-f tags`).
**Entry Structure**
@@ -70,7 +72,8 @@ existing hiding rules.
```python
entries = client.ls(
uri="viking://resources/",
- node_limit=200,
+ offset=100,
+ limit=100,
sort_by="mtime",
sort_order="desc",
)
@@ -101,7 +104,7 @@ for _, entry := range entries {
**HTTP API**
```
-GET /api/v1/fs/ls?uri={uri}&simple={bool}&recursive={bool}&tags={k=v}&include_tags={bool}
+GET /api/v1/fs/ls?uri={uri}&offset={int}&limit={int}
```
```bash
@@ -163,17 +166,19 @@ Get directory tree structure.
| abs_limit | int | No | HTTP: 256; SDKs: 128 | Abstract length limit for `agent` output |
| show_all_hidden | bool | No | False | Include hidden files like `-a` |
| node_limit | int | No | 1000 | Maximum number of results |
+| offset | int | No | 0 | Number of visible results to skip |
+| limit | int | No | None | Alias for `node_limit` |
| level_limit | int | No | 3 | Maximum directory depth to traverse |
| extra_fields | list[str] | No | None | Extra fields to include: `locked`, `id`, `count` |
| tags | string[] | No | Unset | Retain only nodes matching every supplied `k=v` retrieval tag |
-`tags` uses AND semantics and is applied before `node_limit`. Tags are included for filtered responses; for an unfiltered response, request `include_tags=true` (CLI: `-f tags`).
+`tags` uses AND semantics and is applied before `offset` and `limit`. Tags are included for filtered responses; for an unfiltered response, request `include_tags=true` (CLI: `-f tags`).
**Python HTTP SDK**
```python
-entries = client.tree(uri="viking://resources/")
+entries = client.tree(uri="viking://resources/", offset=100, limit=100)
for entry in entries:
type_str = "dir" if entry['isDir'] else "file"
print(f"{entry['rel_path']} - {type_str}")
@@ -201,7 +206,7 @@ for _, entry := range entries {
**HTTP API**
```
-GET /api/v1/fs/tree?uri={uri}&tags={k=v}&include_tags={bool}
+GET /api/v1/fs/tree?uri={uri}&offset={int}&limit={int}
```
```bash
diff --git a/docs/en/guides/06-mcp-integration.md b/docs/en/guides/06-mcp-integration.md
index 577f8d9ad..fc366d53e 100644
--- a/docs/en/guides/06-mcp-integration.md
+++ b/docs/en/guides/06-mcp-integration.md
@@ -136,8 +136,8 @@ Once connected, OpenViking exposes 15 tools:
| `find` | Fast semantic retrieval without session context | `query`, `target_uri` (optional), `limit`, `min_score`, `level` (optional), `context_type` (optional) |
| `search` | Deep semantic retrieval; `mode="context"` assembles injection-ready context and replaces the former `recall` tool | `query`, `mode` (`list` or `context`), `target_uri` (list mode only), `session_id` (optional), `limit`, `min_score`, `level` (list mode), `context_type` (optional), plus context-mode `quotas`, `purpose`, `max_tokens`, `detail` or `detail_by_category`, `dedup_turns`, `exclude_uris`, `peer_scope`, scalar `other_peer_penalty` or `other_peer_penalties` by category, and `rewrite` (`off` or `auto`) |
| `read` | Read one or more `viking://` URIs. PNG, JPEG, GIF, and WebP return native MCP image content; WAV, MP3, FLAC, OGG, and M4A return native audio content. Video is not supported because MCP has no standard video content block | `uris` (single string or array) |
-| `list` | List entries under a `viking://` directory | `uri`, `recursive` (optional) |
-| `tree` | Show the recursive directory tree under a `viking://` URI, indented by depth — use when you need a full picture of the file tree (prefer `list` for a single level, `glob` for filename patterns) | `uri` (optional), `level_limit` (default 3), `node_limit` (default 1000), `include_abstract` (optional — also show each file's summary) |
+| `list` | List entries under a `viking://` directory | `uri`, `recursive`, `offset`, `limit`, `sort_by`, `sort_order` (optional) |
+| `tree` | Show the recursive directory tree under a `viking://` URI, indented by depth — use when you need a full picture of the file tree (prefer `list` for a single level, `glob` for filename patterns) | `uri` (optional), `level_limit` (default 3), `node_limit` (default 1000), `offset`, `limit`, `include_abstract` (optional — also show each file's summary) |
| `remember` | Store messages into long-term memory (triggers extraction) | `messages` (list of `{role, content}`) |
| `write` | Write text to a `viking://` file (create/overwrite/append). Parent directories are created automatically; use `read` first to see current content before overwriting, and prefer `edit` for changing part of an existing file | `uri`, `content`, `mode` (optional: `replace` default — overwrites or creates if missing; `append` — appends or creates if missing; `create` — fails if it exists), `wait` (optional, block until re-indexed), `timeout` (optional) |
| `edit` | Replace an exact string with new text in an existing `viking://` file — for targeted changes instead of a full rewrite. The file is left unchanged if `old_string` is not found, or matches multiple times while `replace_all` is false | `uri`, `old_string`, `new_string`, `replace_all` (optional), `wait` (optional, block until re-indexed), `timeout` (optional) |
diff --git a/docs/zh/api/03-filesystem.md b/docs/zh/api/03-filesystem.md
index fb43a9181..4ebf06ffb 100644
--- a/docs/zh/api/03-filesystem.md
+++ b/docs/zh/api/03-filesystem.md
@@ -23,12 +23,13 @@ OpenViking 提供类 Unix 的文件系统操作来管理上下文。
| abs_limit | int | 否 | 256 | `agent` 输出中的摘要长度限制 |
| show_all_hidden | bool | 否 | False | 像 `-a` 一样包含隐藏文件 |
| node_limit | int | 否 | 1000 | 最大返回节点数 |
+| offset | int | 否 | 0 | 跳过的可见节点数 |
| limit | int | 否 | None | `node_limit` 的别名 |
-| sort_by | str | 否 | None | 在应用 `node_limit` 前,分别按 `name` 或 `mtime` 排序目录组和文件组;目录仍优先 |
+| sort_by | str | 否 | None | 在分页前,分别按 `name` 或 `mtime` 排序目录组和文件组;目录仍优先 |
| sort_order | str | 否 | `asc` | 排序方向:`asc` 或 `desc` |
| tags | string[] | 否 | 未设置 | 仅返回同时匹配全部 `k=v` 检索标签的条目 |
-`tags` 使用 AND 语义,并在 `node_limit` 前应用。带 tags 过滤的响应会返回 `tags`;未过滤时需传 `include_tags=true`(CLI:`-f tags`)才返回它们。`simple=true` 保持仅返回路径。
+`tags` 使用 AND 语义,并在 `offset` 和 `limit` 前应用。带 tags 过滤的响应会返回 `tags`;未过滤时需传 `include_tags=true`(CLI:`-f tags`)才返回它们。`simple=true` 保持仅返回路径。
**条目结构**
@@ -68,7 +69,8 @@ OpenViking 提供类 Unix 的文件系统操作来管理上下文。
```python
entries = client.ls(
uri="viking://resources/",
- node_limit=200,
+ offset=100,
+ limit=100,
sort_by="mtime",
sort_order="desc",
tags=["team=search", "env=prod"],
@@ -104,7 +106,7 @@ for _, entry := range entries {
**HTTP API**
```
-GET /api/v1/fs/ls?uri={uri}&simple={bool}&recursive={bool}&tags={k=v}&include_tags={bool}
+GET /api/v1/fs/ls?uri={uri}&offset={int}&limit={int}
```
```bash
@@ -180,16 +182,23 @@ openviking ls viking://resources/ --fields tags
| abs_limit | int | 否 | HTTP:256;SDK:128 | `agent` 输出中的摘要长度限制 |
| show_all_hidden | bool | 否 | False | 像 `-a` 一样包含隐藏文件 |
| node_limit | int | 否 | 1000 | 最大返回节点数 |
+| offset | int | 否 | 0 | 跳过的可见节点数 |
+| limit | int | 否 | None | `node_limit` 的别名 |
| level_limit | int | 否 | 3 | 最大目录遍历深度 |
| tags | string[] | 否 | 未设置 | 仅保留同时匹配全部 `k=v` 检索标签的节点 |
-`tags` 使用 AND 语义,并在 `node_limit` 前应用。带 tags 过滤的响应会返回 `tags`;未过滤时需传 `include_tags=true` 才返回它们,否则会省略 tags 以避免额外的向量库读取。
+`tags` 使用 AND 语义,并在 `offset` 和 `limit` 前应用。带 tags 过滤的响应会返回 `tags`;未过滤时需传 `include_tags=true` 才返回它们,否则会省略 tags 以避免额外的向量库读取。
**Python HTTP SDK**
```python
-entries = client.tree(uri="viking://resources/", tags=["team=search", "env=prod"])
+entries = client.tree(
+ uri="viking://resources/",
+ offset=100,
+ limit=100,
+ tags=["team=search", "env=prod"],
+)
for entry in entries:
type_str = "dir" if entry['isDir'] else "file"
print(f"{entry['rel_path']} - {type_str}")
@@ -222,7 +231,7 @@ for _, entry := range entries {
**HTTP API**
```
-GET /api/v1/fs/tree?uri={uri}&tags={k=v}&include_tags={bool}
+GET /api/v1/fs/tree?uri={uri}&offset={int}&limit={int}
```
```bash
diff --git a/openviking/pyagfs/async_client.py b/openviking/pyagfs/async_client.py
index 3732a8e82..eeb310c72 100644
--- a/openviking/pyagfs/async_client.py
+++ b/openviking/pyagfs/async_client.py
@@ -105,9 +105,25 @@ class AsyncAGFSClient:
)
async def ls(
- self, path: str = "/", *, fs_ctx: Dict[str, str] | None = None
+ self,
+ path: str = "/",
+ *,
+ offset: int = 0,
+ limit: int | None = None,
+ sort_by: str | None = None,
+ sort_order: str = "asc",
+ fs_ctx: Dict[str, str] | None = None,
) -> List[Dict[str, Any]]:
- return await self.run("ls", path, ctx=_fs_ctx_or_default(path, fs_ctx))
+ """Return a sorted directory range."""
+ kwargs: Dict[str, Any] = {}
+ if offset:
+ kwargs["offset"] = offset
+ if limit is not None:
+ kwargs["limit"] = limit
+ if sort_by is not None:
+ kwargs["sort_by"] = sort_by
+ kwargs["sort_order"] = sort_order
+ return await self.run("ls", path, **kwargs, ctx=_fs_ctx_or_default(path, fs_ctx))
async def read(
self,
@@ -279,14 +295,26 @@ class AsyncAGFSClient:
node_limit: int | None = None,
level_limit: int | None = None,
*,
+ offset: int = 0,
+ sort_by: str | None = None,
+ sort_order: str = "asc",
fs_ctx: Dict[str, str] | None = None,
) -> list[Dict[str, Any]]:
+ """Return a sorted range from a recursive directory traversal."""
+ kwargs: Dict[str, Any] = {
+ "show_hidden": show_hidden,
+ "node_limit": node_limit,
+ "level_limit": level_limit,
+ }
+ if offset:
+ kwargs["offset"] = offset
+ if sort_by is not None:
+ kwargs["sort_by"] = sort_by
+ kwargs["sort_order"] = sort_order
return await self.run(
"tree_directory",
path,
- show_hidden=show_hidden,
- node_limit=node_limit,
- level_limit=level_limit,
+ **kwargs,
ctx=_fs_ctx_or_default(path, fs_ctx),
)
diff --git a/openviking/pyagfs/protocols.py b/openviking/pyagfs/protocols.py
index d04fe6680..3920c3945 100644
--- a/openviking/pyagfs/protocols.py
+++ b/openviking/pyagfs/protocols.py
@@ -12,8 +12,17 @@ AGFSByteStream = Iterator[bytes]
class AGFSSyncClientProtocol(Protocol):
"""Minimal synchronous AGFS client contract used by OpenViking."""
- def ls(self, path: str = "/") -> list[Dict[str, Any]]:
- """List directory entries under the given AGFS path."""
+ def ls(
+ self,
+ path: str = "/",
+ ctx: Dict[str, str] | None = None,
+ *,
+ offset: int = 0,
+ limit: int | None = None,
+ sort_by: str | None = None,
+ sort_order: str = "asc",
+ ) -> list[Dict[str, Any]]:
+ """List a sorted directory range."""
@overload
def read(
@@ -90,8 +99,13 @@ class AGFSSyncClientProtocol(Protocol):
show_hidden: bool = False,
node_limit: int | None = None,
level_limit: int | None = None,
+ ctx: Dict[str, str] | None = None,
+ *,
+ offset: int = 0,
+ sort_by: str | None = None,
+ sort_order: str = "asc",
) -> list[Dict[str, Any]]:
- """Return a tree view for the given AGFS directory."""
+ """Return a sorted range from a directory tree."""
def glob_directory(
self,
diff --git a/openviking/server/mcp_endpoint.py b/openviking/server/mcp_endpoint.py
index 145425957..a6edcaa45 100644
--- a/openviking/server/mcp_endpoint.py
+++ b/openviking/server/mcp_endpoint.py
@@ -630,13 +630,49 @@ async def read(uris: str | list[str]) -> str | list[ContentBlock]:
@mcp.tool(name="list")
-async def ls(uri: str, recursive: bool = False) -> str:
- """List files and subdirectories under a viking:// directory URI. Use recursive=true for deep listing."""
+async def ls(
+ uri: str,
+ recursive: bool = False,
+ offset: int = 0,
+ limit: int | None = None,
+ sort_by: Literal["name", "mtime"] | None = None,
+ sort_order: Literal["asc", "desc"] = "asc",
+) -> str:
+ """List one sorted page under a viking:// directory URI.
+
+ Args:
+ uri: Directory URI to list.
+ recursive: Whether to recursively list descendants.
+ offset: Number of visible entries to skip.
+ limit: Optional maximum number of entries.
+ sort_by: Optional name or modification-time ordering.
+ sort_order: Ascending or descending order.
+
+ Returns:
+ A line-oriented directory listing.
+ """
+ if offset < 0:
+ raise InvalidArgumentError("offset must be greater than or equal to 0")
+ if limit is not None and limit <= 0:
+ raise InvalidArgumentError("limit must be greater than 0")
+
service = get_service()
ctx = _get_ctx()
resolved_uri = _resolve_mcp_workspace_uri(uri, ctx)
- entries = await service.fs.ls(resolved_uri, ctx=ctx, recursive=recursive, output="original")
+ options: dict[str, Any] = {
+ "ctx": ctx,
+ "recursive": recursive,
+ "output": "original",
+ }
+ if offset:
+ options["offset"] = offset
+ if limit is not None:
+ options["node_limit"] = limit
+ if sort_by is not None:
+ options["sort_by"] = sort_by
+ options["sort_order"] = sort_order
+ entries = await service.fs.ls(resolved_uri, **options)
if not entries:
return f"(no entries under {uri})"
@@ -661,19 +697,40 @@ async def tree(
level_limit: int = 3,
node_limit: int = 1000,
include_abstract: bool = False,
+ offset: int = 0,
+ limit: int | None = None,
) -> str:
- """Show the recursive directory tree under a viking:// URI, indented by depth, so you can understand the whole layout at a glance. Use this when you need a full picture of the file tree; use list for a single directory level, glob for filename patterns, and grep for content. level_limit caps the depth (default 3); node_limit caps the total entries. Set include_abstract=true to also see each file's summary (slower, but useful for orientation in unfamiliar directories)."""
+ """Show one visible page from a recursive directory tree.
+
+ Args:
+ uri: Directory URI to traverse.
+ level_limit: Maximum traversal depth.
+ node_limit: Existing default result limit.
+ include_abstract: Whether to include file summaries.
+ offset: Number of visible nodes to skip.
+ limit: Optional result limit that overrides node_limit.
+
+ Returns:
+ An indented directory tree.
+ """
+ if offset < 0:
+ raise InvalidArgumentError("offset must be greater than or equal to 0")
+ if limit is not None and limit <= 0:
+ raise InvalidArgumentError("limit must be greater than 0")
+
service = get_service()
ctx = _get_ctx()
resolved_uri = _resolve_mcp_workspace_uri(uri, ctx)
output = "agent" if include_abstract else "original"
+ effective_limit = limit if limit is not None else node_limit
try:
entries = await service.fs.tree(
resolved_uri,
ctx=ctx,
output=output,
- node_limit=node_limit,
+ node_limit=effective_limit,
level_limit=level_limit,
+ offset=offset,
)
except NotFoundError:
entries = []
@@ -695,9 +752,9 @@ async def tree(
abstract = (e.get("abstract") or "").strip().replace("\n", " ")
if include_abstract and abstract:
lines.append(f"{indent} - {abstract}")
- if len(entries) >= node_limit:
+ if len(entries) >= effective_limit:
lines.append(
- f"(truncated at node_limit={node_limit}; narrow the uri or raise node_limit to see more)"
+ f"(truncated at node_limit={effective_limit}; narrow the uri or raise node_limit to see more)"
)
return "\n".join(lines)
diff --git a/openviking/server/routers/filesystem.py b/openviking/server/routers/filesystem.py
index 3db41d2c4..8c9320dbc 100644
--- a/openviking/server/routers/filesystem.py
+++ b/openviking/server/routers/filesystem.py
@@ -74,7 +74,8 @@ async def ls(
abs_limit: int = Query(256, description="Abstract limit (only for agent output)"),
show_all_hidden: bool = Query(False, description="List all hidden files, like -a"),
node_limit: int = Query(1000, description="Maximum number of nodes to list"),
- limit: Optional[int] = Query(None, description="Alias for node_limit"),
+ offset: int = Query(0, ge=0, description="Number of visible nodes to skip"),
+ limit: Optional[int] = Query(None, ge=1, description="Alias for node_limit"),
sort_by: Optional[Literal["name", "mtime"]] = Query(
None,
description="Sort directory and file groups before applying node_limit",
@@ -102,6 +103,7 @@ async def ls(
abs_limit=abs_limit,
show_all_hidden=show_all_hidden,
node_limit=actual_node_limit,
+ offset=offset,
sort_by=sort_by,
sort_order=sort_order,
extra_fields=extra_fields,
@@ -125,7 +127,8 @@ async def tree(
abs_limit: int = Query(256, description="Abstract limit (only for agent output)"),
show_all_hidden: bool = Query(False, description="List all hidden files, like -a"),
node_limit: int = Query(1000, description="Maximum number of nodes to list"),
- limit: Optional[int] = Query(None, description="Alias for node_limit"),
+ offset: int = Query(0, ge=0, description="Number of visible nodes to skip"),
+ limit: Optional[int] = Query(None, ge=1, description="Alias for node_limit"),
level_limit: int = Query(3, description="Maximum depth level to traverse"),
extra_fields: Optional[list[str]] = Query(
None, description="Extra fields to include: locked, id, count"
@@ -148,6 +151,7 @@ async def tree(
show_all_hidden=show_all_hidden,
node_limit=actual_node_limit,
level_limit=level_limit,
+ offset=offset,
extra_fields=extra_fields,
tags=tags,
include_tags=include_tags,
diff --git a/openviking/service/fs_service.py b/openviking/service/fs_service.py
index b1cba9b7a..6310a933f 100644
--- a/openviking/service/fs_service.py
+++ b/openviking/service/fs_service.py
@@ -8,7 +8,7 @@ Provides file system operations: ls, mkdir, rm, mv, tree, stat, read, abstract,
import asyncio
from collections.abc import Coroutine
-from typing import TYPE_CHECKING, Any, Dict, List, Literal, Optional
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict, List, Literal, Optional
from openviking.core.context import ContextLevel
from openviking.core.namespace import classify_uri, context_type_for_uri, uri_leaf_name
@@ -178,6 +178,52 @@ class FSService:
result_entries.append(entry)
return result_entries
+ async def _collect_tagged_page(
+ self,
+ fetch_page: Callable[[int, Optional[int]], Awaitable[List[Dict[str, Any]]]],
+ ctx: RequestContext,
+ tags: List[str],
+ include_tags: bool,
+ offset: int,
+ node_limit: int,
+ ) -> List[Dict[str, Any]]:
+ """Collect a visible page after tag filtering.
+
+ Args:
+ fetch_page: Loads one pre-tag page by offset and limit.
+ ctx: Request identity used for tag lookup.
+ tags: Required retrieval tags.
+ include_tags: Whether to retain tags in returned entries.
+ offset: Number of matched entries to skip.
+ node_limit: Maximum matched entries to return.
+
+ Returns:
+ The requested page of tag-filtered entries.
+ """
+ if node_limit <= 0:
+ entries = await fetch_page(0, None)
+ entries = await self._attach_and_filter_tags(entries, ctx, tags, include_tags)
+ return entries[offset:]
+
+ batch_size = max(node_limit, 256)
+ source_offset = 0
+ remaining_offset = offset
+ result: List[Dict[str, Any]] = []
+ while len(result) < node_limit:
+ entries = await fetch_page(source_offset, batch_size)
+ filtered = await self._attach_and_filter_tags(entries, ctx, tags, include_tags)
+ if remaining_offset >= len(filtered):
+ remaining_offset -= len(filtered)
+ else:
+ result.extend(
+ filtered[remaining_offset : remaining_offset + node_limit - len(result)]
+ )
+ remaining_offset = 0
+ if len(entries) < batch_size:
+ break
+ source_offset += len(entries)
+ return result
+
async def ls(
self,
uri: str,
@@ -194,6 +240,7 @@ class FSService:
extra_fields: Optional[List[str]] = None,
tags: Optional[List[str]] = None,
include_tags: bool = False,
+ offset: int = 0,
) -> List[Any]:
"""List directory contents.
@@ -211,63 +258,62 @@ class FSService:
"""
viking_fs = self._ensure_initialized()
extra_fields = extra_fields or []
-
use_simple_paths = simple and not extra_fields
- if use_simple_paths:
- # Only return URIs — skip expensive abstract fetching to save tokens
+ async def fetch_page(page_offset: int, page_limit: Optional[int]) -> List[Dict[str, Any]]:
+ """Fetch and return one pre-tag page."""
if recursive:
- entries = await viking_fs.tree(
+ return await viking_fs.tree(
uri,
ctx=ctx,
- output="original",
+ output="original" if tags or use_simple_paths else output,
+ abs_limit=abs_limit,
show_all_hidden=show_all_hidden,
- node_limit=None if tags else node_limit,
+ node_limit=page_limit,
level_limit=level_limit,
- )
- else:
- entries = await viking_fs.ls(
- uri,
- ctx=ctx,
- output="original",
- show_all_hidden=show_all_hidden,
- node_limit=None if tags else node_limit,
+ offset=page_offset,
sort_by=sort_by,
sort_order=sort_order,
+ extra_fields=None if tags or use_simple_paths else extra_fields,
)
- entries = await self._attach_and_filter_tags(entries, ctx, tags, include_tags=False)
- if tags and node_limit > 0:
- entries = entries[:node_limit]
- return [e.get("uri", "") for e in entries]
-
- if recursive:
- entries = await viking_fs.tree(
+ return await viking_fs.ls(
uri,
ctx=ctx,
- output=output,
+ output="original" if tags or use_simple_paths else output,
abs_limit=abs_limit,
show_all_hidden=show_all_hidden,
- node_limit=None if tags else node_limit,
- level_limit=level_limit,
- extra_fields=extra_fields,
+ node_limit=page_limit,
+ offset=page_offset,
+ sort_by=sort_by,
+ sort_order=sort_order,
+ extra_fields=None if tags or use_simple_paths else extra_fields,
+ )
+
+ if tags:
+ entries = await self._collect_tagged_page(
+ fetch_page,
+ ctx,
+ tags,
+ False if use_simple_paths else include_tags or bool(tags) or "tags" in extra_fields,
+ offset,
+ node_limit,
)
else:
- entries = await viking_fs.ls(
- uri,
+ entries = await fetch_page(offset, node_limit)
+ entries = await self._attach_and_filter_tags(
+ entries, ctx, None, include_tags or "tags" in extra_fields
+ )
+ if use_simple_paths:
+ return [entry.get("uri", "") for entry in entries]
+ if tags and (output != "original" or extra_fields):
+ return await viking_fs._finalize_listing_entries(
+ entries,
+ output,
+ abs_limit,
+ extra_fields,
+ recursive,
ctx=ctx,
- output=output,
- abs_limit=abs_limit,
- show_all_hidden=show_all_hidden,
- node_limit=None if tags else node_limit,
- sort_by=sort_by,
- sort_order=sort_order,
- extra_fields=extra_fields,
)
- entries = await self._attach_and_filter_tags(
- entries, ctx, tags, include_tags or bool(tags) or "tags" in extra_fields
- )
- if tags and node_limit > 0:
- entries = entries[:node_limit]
return entries
async def mkdir(
@@ -838,25 +884,49 @@ class FSService:
extra_fields: Optional[List[str]] = None,
tags: Optional[List[str]] = None,
include_tags: bool = False,
+ offset: int = 0,
) -> List[Dict[str, Any]]:
"""Get directory tree."""
viking_fs = self._ensure_initialized()
- result = await viking_fs.tree(
- uri,
- ctx=ctx,
- output=output,
- abs_limit=abs_limit,
- show_all_hidden=show_all_hidden,
- node_limit=None if tags else node_limit,
- level_limit=level_limit,
- extra_fields=extra_fields,
- )
- result = await self._attach_and_filter_tags(
- result, ctx, tags, include_tags or bool(tags) or "tags" in (extra_fields or [])
+
+ async def fetch_page(page_offset: int, page_limit: Optional[int]) -> List[Dict[str, Any]]:
+ """Fetch and return one pre-tag tree page."""
+ return await viking_fs.tree(
+ uri,
+ ctx=ctx,
+ output="original" if tags else output,
+ abs_limit=abs_limit,
+ show_all_hidden=show_all_hidden,
+ node_limit=page_limit,
+ level_limit=level_limit,
+ extra_fields=None if tags else extra_fields,
+ offset=page_offset,
+ )
+
+ if tags:
+ result = await self._collect_tagged_page(
+ fetch_page,
+ ctx,
+ tags,
+ include_tags or bool(tags) or "tags" in (extra_fields or []),
+ offset,
+ node_limit,
+ )
+ if output != "original" or extra_fields:
+ return await viking_fs._finalize_listing_entries(
+ result,
+ output,
+ abs_limit,
+ extra_fields,
+ True,
+ ctx=ctx,
+ )
+ return result
+
+ result = await fetch_page(offset, node_limit)
+ return await self._attach_and_filter_tags(
+ result, ctx, None, include_tags or "tags" in (extra_fields or [])
)
- if tags and node_limit > 0:
- result = result[:node_limit]
- return result
async def stat(self, uri: str, ctx: RequestContext, skip_count: bool = False) -> Dict[str, Any]:
"""Get resource status."""
diff --git a/openviking/storage/viking_fs/_access.py b/openviking/storage/viking_fs/_access.py
index c7b85a2c3..502e68c85 100644
--- a/openviking/storage/viking_fs/_access.py
+++ b/openviking/storage/viking_fs/_access.py
@@ -43,10 +43,6 @@ from openviking_cli.utils.uri import VikingURI
class _AccessMixin:
"""URI normalization, access control, path conversion, and visibility helpers."""
- # Over-fetch multiplier for bounded tree traversal. When a node_limit is
- # set, we push down node_limit * this factor as the raw-node limit to Rust,
- # leaving headroom for ACL/internal-name filtering before re-fetching.
- _TREE_OVERFETCH_FACTOR = 4
_GLOB_PAGE_SIZE_DEFAULT = 1024
# Maximum bytes for a single filename component (filesystem limit is typically 255)
@@ -59,14 +55,16 @@ class _AccessMixin:
# crates/ragfs/src/git/enumerate.rs and VikingFS._INTERNAL_NAMES so that
# callers fail fast in Python with a clear error rather than passing a
# path that the Rust side will silently drop.
- _GIT_INTERNAL_FIRST_SEGMENTS = frozenset({
- "_system",
- "tasks",
- "temp",
- "queue",
- "upload",
- ".path.ovlock",
- })
+ _GIT_INTERNAL_FIRST_SEGMENTS = frozenset(
+ {
+ "_system",
+ "tasks",
+ "temp",
+ "queue",
+ "upload",
+ ".path.ovlock",
+ }
+ )
_DEFAULT_GIT_AUTHOR_NAME = "viking-bot"
_DEFAULT_GIT_AUTHOR_EMAIL = "[email protected]"
@@ -259,9 +257,7 @@ class _AccessMixin:
resource=uri,
)
- async def _ensure_retrieval_scope(
- self, uri: str, ctx: Optional[RequestContext]
- ) -> None:
+ async def _ensure_retrieval_scope(self, uri: str, ctx: Optional[RequestContext]) -> None:
self._safe_uri_parts(uri)
if self._acl_enabled(ctx) and is_acl_uri(uri):
return
@@ -269,13 +265,9 @@ class _AccessMixin:
def _acl_enabled(self, ctx: Optional[RequestContext]) -> bool:
real_ctx = self._ctx_or_default(ctx)
- return self.acl_manager is not None and self.acl_manager.is_enabled(
- real_ctx.account_id
- )
+ return self.acl_manager is not None and self.acl_manager.is_enabled(real_ctx.account_id)
- async def _ensure_acl_manage(
- self, uri: str, ctx: Optional[RequestContext]
- ) -> RequestContext:
+ async def _ensure_acl_manage(self, uri: str, ctx: Optional[RequestContext]) -> RequestContext:
if self.acl_manager is None:
raise RuntimeError("ACL is not initialized")
real_ctx = self._ctx_or_default(ctx)
@@ -367,11 +359,7 @@ class _AccessMixin:
def _ensure_user_not_deleting(self, ctx: RequestContext) -> None:
guard = getattr(self, "_user_deletion_guard", None)
- if (
- ctx.role != Role.ROOT
- and guard is not None
- and guard(ctx.account_id, ctx.user.user_id)
- ):
+ if ctx.role != Role.ROOT and guard is not None and guard(ctx.account_id, ctx.user.user_id):
raise FailedPreconditionError("User deletion is in progress")
def _ensure_supported_delete_namespace(self, normalized_uri: str) -> None:
@@ -513,25 +501,12 @@ class _AccessMixin:
show_all_hidden: bool = False,
node_limit: Optional[int] = None,
level_limit: Optional[int] = None,
+ offset: int = 0,
+ sort_by: Optional[str] = None,
+ sort_order: str = "asc",
ctx: Optional[RequestContext] = None,
):
- """Shared generator: fetch raw TreeEntry list from Rust, yield (entry, uri) tuples.
-
- node_limit counts ACL-visible entries, so the user's node_limit cannot
- be pushed directly to Rust — doing so would truncate before filtering
- and drop entries that should be visible.
-
- To keep memory bounded without changing that semantic, we push down an
- *amplified* raw-node limit (node_limit * _TREE_OVERFETCH_FACTOR). If ACL
- filtering leaves fewer than node_limit visible entries while Rust still
- returned a full page (i.e. more raw nodes may exist), we double the raw
- limit and re-fetch. Because Rust truncates a deterministic sorted prefix,
- this yields exactly the same result as an unbounded fetch, while avoiding
- materializing the entire prefix in the common case.
-
- When node_limit is None (full-tree callers), no limit is pushed down.
- level_limit IS always passed to Rust.
- """
+ """Yield one visible tree page after namespace and ACL filtering."""
real_ctx = self._ctx_or_default(ctx)
primary_path = self._uri_to_path(uri, ctx=ctx)
path: Optional[str] = None
@@ -546,11 +521,15 @@ class _AccessMixin:
return
raise NotFoundError(uri, "directory")
- if node_limit is None:
- raw_limit: Optional[int] = None
- else:
- raw_limit = max(node_limit * self._TREE_OVERFETCH_FACTOR, node_limit)
+ if node_limit == 0:
+ return
+ raw_offset = 0
+ raw_limit = None if node_limit is None else max(node_limit, 256)
+ remaining_offset = offset
+ yielded = 0
acl_enabled = self._acl_enabled(real_ctx)
+ expose_resource_names = acl_enabled and is_acl_uri(uri)
+ denied_directories: set[str] = set()
while True:
raw_entries = await self._async_agfs.tree_directory(
@@ -558,7 +537,12 @@ class _AccessMixin:
show_hidden=show_all_hidden,
node_limit=raw_limit,
level_limit=level_limit,
+ offset=raw_offset,
+ sort_by=sort_by,
+ sort_order=sort_order,
)
+ if not raw_entries:
+ return
candidates: List[tuple] = []
for entry in raw_entries:
@@ -573,14 +557,14 @@ class _AccessMixin:
ctx=ctx,
)
candidates.append((entry, entry_uri))
+ remaining_limit = None if node_limit is None else node_limit - yielded
if (
not acl_enabled
- and node_limit is not None
- and len(candidates) >= node_limit
+ and remaining_limit is not None
+ and len(candidates) >= (remaining_offset + remaining_limit)
):
break
- expose_resource_names = acl_enabled and is_acl_uri(uri)
if not acl_enabled:
visible = candidates
else:
@@ -588,12 +572,14 @@ class _AccessMixin:
[entry_uri for _, entry_uri in candidates], real_ctx
)
if expose_resource_names:
- denied_directories = {
- entry["path"].rstrip("/")
- for entry, entry_uri in candidates
- if entry.get("info", {}).get("isDir", False)
- and not access.get(entry_uri, False)
- }
+ denied_directories.update(
+ {
+ entry["path"].rstrip("/")
+ for entry, entry_uri in candidates
+ if entry.get("info", {}).get("isDir", False)
+ and not access.get(entry_uri, False)
+ }
+ )
visible = []
base = path.rstrip("/")
for entry, entry_uri in candidates:
@@ -614,25 +600,19 @@ class _AccessMixin:
visible.append((denied_entry, entry_uri))
else:
visible = [item for item in candidates if access.get(item[1], False)]
- if node_limit is not None:
- visible = visible[:node_limit]
-
- # If we still lack enough visible entries but Rust returned a full
- # page (raw_limit reached), more raw nodes may exist — re-fetch with
- # a doubled limit. Otherwise Rust is exhausted and we yield as-is.
- need_more = (
- node_limit is not None
- and len(visible) < node_limit
- and raw_limit is not None
- and len(raw_entries) >= raw_limit
- )
- if need_more:
- raw_limit *= 2
- continue
for item in visible:
+ if remaining_offset:
+ remaining_offset -= 1
+ continue
yield item
- return
+ yielded += 1
+ if node_limit is not None and yielded >= node_limit:
+ return
+
+ if raw_limit is None or len(raw_entries) < raw_limit:
+ return
+ raw_offset += len(raw_entries)
# ========== URI Conversion ==========
@@ -662,9 +642,7 @@ class _AccessMixin:
raise ValueError(f"Legacy session URI is not accepted internally: {uri}")
if parts and parts[0] == "agent" and self._is_legacy_agent_id_uri(uri):
# Old format: viking://agent/{agent_id}/... — direct mapping for read-only compat
- safe_parts = [
- self._shorten_component(p, self._MAX_FILENAME_BYTES) for p in parts
- ]
+ safe_parts = [self._shorten_component(p, self._MAX_FILENAME_BYTES) for p in parts]
return f"/local/{account_id}/{'/'.join(safe_parts)}"
if not parts:
return f"/local/{account_id}"
@@ -736,9 +714,7 @@ class _AccessMixin:
return True
if self._legacy_session_alias(request_uri):
owner_user_id = self._safe_uri_parts(request_uri)[1]
- return await self._legacy_session_path_visible(
- path, owner_user_id=owner_user_id
- )
+ return await self._legacy_session_path_visible(path, owner_user_id=owner_user_id)
return True
def _alias_uri_for_path(
@@ -751,9 +727,7 @@ class _AccessMixin:
) -> str:
base = base_path.rstrip("/")
request_parts = self._safe_uri_parts(request_uri)
- request_root = (
- request_uri if request_uri == "viking://" else request_uri.rstrip("/")
- )
+ request_root = request_uri if request_uri == "viking://" else request_uri.rstrip("/")
preserve_request_alias = request_uri in {"viking://", "viking://user"} or bool(
request_parts
and request_parts[0] == "agent"
@@ -932,23 +906,38 @@ class _AccessMixin:
async def _list_read_path_items(
self,
uri: str,
+ raw_offset: int = 0,
+ raw_limit: Optional[int] = None,
+ sort_by: Optional[str] = None,
+ sort_order: str = "asc",
ctx: Optional[RequestContext] = None,
- ) -> List[tuple[Dict[str, Any], str]]:
+ ) -> tuple[List[tuple[Dict[str, Any], str]], int, bool]:
+ """Return one mapped RagFS page, consumed count, and exhaustion state."""
real_ctx = self._ctx_or_default(ctx)
if self._is_session_root_uri(uri):
- return await self._session_root_items(uri, real_ctx)
+ items = await self._session_root_items(uri, real_ctx)
+ return items, len(items), True
primary_path = self._uri_to_path(uri, ctx=ctx)
merge_paths = self._legacy_session_alias(uri) is not None
found_path = False
last_not_found: Optional[Exception] = None
by_uri: Dict[str, tuple[Dict[str, Any], str]] = {}
+ raw_count = 0
for path in self._read_paths(uri, ctx=ctx):
if not await self._read_path_visible(uri, path, primary_path, real_ctx):
continue
try:
- entries = await self._ls_entries(path, ctx=ctx)
+ entries = await self._ls_entries(
+ path,
+ offset=0 if merge_paths else raw_offset,
+ limit=None if merge_paths else raw_limit,
+ sort_by=sort_by,
+ sort_order=sort_order,
+ filter_internal=False,
+ ctx=ctx,
+ )
except Exception as exc:
if is_not_found_error(exc):
last_not_found = exc
@@ -956,6 +945,8 @@ class _AccessMixin:
raise
found_path = True
+ raw_count += len(entries)
+ entries = self._filter_ls_entries(path, entries)
for entry in entries:
entry_uri = self._alias_uri_for_path(
request_uri=uri,
@@ -968,7 +959,8 @@ class _AccessMixin:
break
if found_path:
- return list(by_uri.values())
+ exhausted = raw_limit is None or merge_paths or raw_count < raw_limit
+ return list(by_uri.values()), raw_count, exhausted
raise NotFoundError(uri, "directory") from last_not_found
def _path_to_uri(self, path: str, ctx: Optional[RequestContext] = None) -> str:
diff --git a/openviking/storage/viking_fs/_ops.py b/openviking/storage/viking_fs/_ops.py
index cba385e17..d289d514b 100644
--- a/openviking/storage/viking_fs/_ops.py
+++ b/openviking/storage/viking_fs/_ops.py
@@ -1257,6 +1257,80 @@ class _OpsMixin:
abstract = abstract[: abs_limit - 3] + "..."
entries[index]["abstract"] = abstract
+ async def _finalize_listing_entries(
+ self,
+ entries: List[Dict[str, Any]],
+ output: str,
+ abs_limit: int,
+ extra_fields: Optional[List[str]],
+ recursive: bool,
+ ctx: Optional[RequestContext] = None,
+ ) -> List[Dict[str, Any]]:
+ """Format and enrich entries after visible-page selection.
+
+ Args:
+ entries: Selected entries in original format.
+ output: Requested output format.
+ abs_limit: Maximum abstract length.
+ extra_fields: Optional original-output fields.
+ recursive: Whether entries came from a tree traversal.
+ ctx: Request identity used for enrichment.
+
+ Returns:
+ Entries in the requested output format.
+ """
+ if output == "original":
+ if extra_fields:
+ await self._augment_entries_extra_fields(entries, extra_fields, ctx=ctx)
+ return entries
+ if output != "agent":
+ raise ValueError(f"Invalid output format: {output}")
+
+ fallback_time = datetime.now(timezone.utc)
+ result: List[Dict[str, Any]] = []
+ for entry in entries:
+ is_dir = bool(entry.get("isDir", False))
+ if entry.get("access") == "denied":
+ item = {
+ "uri": entry.get("uri", ""),
+ "isDir": is_dir,
+ "access": "denied",
+ }
+ if recursive:
+ item["rel_path"] = entry.get("rel_path", "")
+ else:
+ item["name"] = entry.get("name", "")
+ else:
+ raw_time = entry.get("modTime", "")
+ parsed_time = fallback_time
+ if isinstance(raw_time, (int, float)):
+ parsed_time = datetime.fromtimestamp(raw_time, tz=timezone.utc)
+ elif raw_time:
+ if len(raw_time) > 26 and "+" in raw_time:
+ parts = raw_time.split("+")
+ raw_time = parts[0][:26] + "+" + parts[1]
+ parsed_time = parse_iso_datetime(raw_time)
+ elif isinstance(entry.get("mtime"), (int, float)):
+ parsed_time = datetime.fromtimestamp(entry["mtime"], tz=timezone.utc)
+ item = {
+ "uri": entry.get("uri", ""),
+ "size": 0 if is_dir else entry.get("size", 0),
+ "isDir": is_dir,
+ "modTime": format_iso8601(parsed_time),
+ }
+ if recursive:
+ item["rel_path"] = entry.get("rel_path", "")
+ if "tags" in entry:
+ item["tags"] = entry["tags"]
+ result.append(item)
+
+ await self._batch_fetch_abstracts(
+ [entry for entry in result if entry.get("access") != "denied"],
+ abs_limit,
+ ctx=ctx,
+ )
+ return result
+
async def tree(
self,
uri: str = "viking://",
@@ -1267,6 +1341,9 @@ class _OpsMixin:
level_limit: Optional[int] = 3,
ctx: Optional[RequestContext] = None,
extra_fields: Optional[List[str]] = None,
+ offset: int = 0,
+ sort_by: Optional[str] = None,
+ sort_order: str = "asc",
) -> List[Dict[str, Any]]:
"""
Recursively list all contents (includes rel_path).
@@ -1286,15 +1363,32 @@ class _OpsMixin:
output="agent"
[{'uri': 'viking://resources...', 'size': 100, 'isDir': False, 'modTime': '2026-02-11T08:52:16.256Z', 'rel_path': '.abstract.md', 'abstract': "..."}]
"""
+ if offset < 0:
+ raise ValueError("offset must be non-negative")
await self._ensure_access(uri, ctx)
extra_fields = extra_fields or []
if output == "original":
entries = await self._tree_original(
- uri, show_all_hidden, node_limit, level_limit, ctx=ctx
+ uri,
+ show_all_hidden,
+ node_limit,
+ level_limit,
+ offset=offset,
+ sort_by=sort_by,
+ sort_order=sort_order,
+ ctx=ctx,
)
elif output == "agent":
entries = await self._tree_agent(
- uri, abs_limit, show_all_hidden, node_limit, level_limit, ctx=ctx
+ uri,
+ abs_limit,
+ show_all_hidden,
+ node_limit,
+ level_limit,
+ offset=offset,
+ sort_by=sort_by,
+ sort_order=sort_order,
+ ctx=ctx,
)
else:
raise ValueError(f"Invalid output format: {output}")
@@ -1308,6 +1402,9 @@ class _OpsMixin:
show_all_hidden: bool = False,
node_limit: Optional[int] = 1000,
level_limit: Optional[int] = 3,
+ offset: int = 0,
+ sort_by: Optional[str] = None,
+ sort_order: str = "asc",
ctx: Optional[RequestContext] = None,
) -> List[Dict[str, Any]]:
"""Recursively list all contents (original format)."""
@@ -1317,6 +1414,9 @@ class _OpsMixin:
show_all_hidden=show_all_hidden,
node_limit=node_limit,
level_limit=level_limit,
+ offset=offset,
+ sort_by=sort_by,
+ sort_order=sort_order,
ctx=ctx,
):
info = entry["info"]
@@ -1353,48 +1453,31 @@ class _OpsMixin:
show_all_hidden: bool = False,
node_limit: Optional[int] = 1000,
level_limit: Optional[int] = 3,
+ offset: int = 0,
+ sort_by: Optional[str] = None,
+ sort_order: str = "asc",
ctx: Optional[RequestContext] = None,
) -> List[Dict[str, Any]]:
"""Recursively list all contents (agent format with abstracts)."""
- result = []
-
- async for entry, entry_uri in self._iter_visible_tree_entries(
+ entries = await self._tree_original(
uri,
- show_all_hidden=show_all_hidden,
- node_limit=node_limit,
- level_limit=level_limit,
+ show_all_hidden,
+ node_limit,
+ level_limit,
+ offset=offset,
+ sort_by=sort_by,
+ sort_order=sort_order,
ctx=ctx,
- ):
- info = entry["info"]
- is_dir = info["isDir"]
- if entry.get("access") == "denied":
- result.append(
- {
- "uri": entry_uri,
- "isDir": is_dir,
- "rel_path": entry["rel_path"],
- "access": "denied",
- }
- )
- continue
- result.append(
- {
- "uri": entry_uri,
- "size": 0 if is_dir else info["size"],
- "isDir": is_dir,
- "modTime": format_iso8601(parse_iso_datetime(info["modTime"])),
- "rel_path": entry["rel_path"],
- }
- )
-
- await self._batch_fetch_abstracts(
- [entry for entry in result if entry.get("access") != "denied"],
+ )
+ return await self._finalize_listing_entries(
+ entries,
+ "agent",
abs_limit,
+ None,
+ True,
ctx=ctx,
)
- return result
-
# ========== Vector Sync Helper Methods ==========
async def _collect_uris(
@@ -1707,6 +1790,7 @@ class _OpsMixin:
sort_order: str = "asc",
ctx: Optional[RequestContext] = None,
extra_fields: Optional[List[str]] = None,
+ offset: int = 0,
) -> List[Dict[str, Any]]:
"""
List directory contents (URI version).
@@ -1738,6 +1822,7 @@ class _OpsMixin:
uri,
show_all_hidden,
node_limit,
+ offset=offset,
sort_by=sort_by,
sort_order=sort_order,
ctx=ctx,
@@ -1748,6 +1833,7 @@ class _OpsMixin:
abs_limit,
show_all_hidden,
node_limit,
+ offset=offset,
sort_by=sort_by,
sort_order=sort_order,
ctx=ctx,
@@ -1788,12 +1874,12 @@ class _OpsMixin:
directories = [item for item in entry_items if item[0].get("isDir", False)]
files = [item for item in entry_items if not item[0].get("isDir", False)]
- if sort_by == "name":
-
- def name_key(item: tuple[Dict[str, Any], str]) -> tuple[str, str]:
- name = str(item[0].get("name", ""))
- return name.lower(), name
+ def name_key(item: tuple[Dict[str, Any], str]) -> tuple[str, str]:
+ """Return the case-insensitive and original entry name."""
+ name = str(item[0].get("name", ""))
+ return name.lower(), name
+ if sort_by == "name":
directories.sort(key=name_key, reverse=descending)
files.sort(key=name_key, reverse=descending)
return directories + files
@@ -1809,10 +1895,12 @@ class _OpsMixin:
missing.append(item)
else:
timestamped.append((timestamp, item))
+ timestamped.sort(key=lambda pair: name_key(pair[1]))
timestamped.sort(
key=lambda pair: pair[0],
reverse=descending,
)
+ missing.sort(key=name_key)
return [item for _, item in timestamped] + missing
return sort_by_mtime(directories) + sort_by_mtime(files)
@@ -1823,73 +1911,50 @@ class _OpsMixin:
abs_limit: int,
show_all_hidden: bool,
node_limit: int = 1000,
+ offset: int = 0,
sort_by: Optional[str] = None,
sort_order: str = "asc",
ctx: Optional[RequestContext] = None,
) -> List[Dict[str, Any]]:
"""List directory contents (URI version)."""
- entry_items = await self._ls_browsable_items(uri, ctx=ctx)
- entry_items = self._sort_ls_entry_items(entry_items, sort_by, sort_order)
- # basic info
- fallback_time = datetime.now(timezone.utc)
- all_entries = []
- for entry, entry_uri in entry_items:
- name = entry.get("name", "")
- if entry.get("access") == "denied":
- if entry.get("isDir") or not name.startswith(".") or show_all_hidden:
- all_entries.append(
- {
- "name": name,
- "uri": entry_uri,
- "isDir": bool(entry.get("isDir", False)),
- "access": "denied",
- }
- )
- continue
- raw_time = entry.get("modTime", "")
- parsed_time = fallback_time
- if isinstance(raw_time, (int, float)):
- parsed_time = datetime.fromtimestamp(raw_time, tz=timezone.utc)
- elif raw_time:
- if len(raw_time) > 26 and "+" in raw_time:
- parts = raw_time.split("+")
- raw_time = parts[0][:26] + "+" + parts[1]
- parsed_time = parse_iso_datetime(raw_time)
- elif isinstance(entry.get("mtime"), (int, float)):
- parsed_time = datetime.fromtimestamp(entry["mtime"], tz=timezone.utc)
- is_dir = entry.get("isDir", False)
- new_entry = {
- "uri": entry_uri,
- "size": 0 if is_dir else entry.get("size", 0),
- "isDir": is_dir,
- "modTime": format_iso8601(parsed_time),
- }
- if is_dir:
- all_entries.append(new_entry)
- elif not name.startswith("."):
- all_entries.append(new_entry)
- elif show_all_hidden:
- all_entries.append(new_entry)
- all_entries = all_entries[:node_limit]
- await self._batch_fetch_abstracts(
- [entry for entry in all_entries if entry.get("access") != "denied"],
+ entries = await self._ls_original(
+ uri,
+ show_all_hidden=show_all_hidden,
+ offset=offset,
+ node_limit=node_limit,
+ sort_by=sort_by,
+ sort_order=sort_order,
+ ctx=ctx,
+ )
+ return await self._finalize_listing_entries(
+ entries,
+ "agent",
abs_limit,
+ None,
+ False,
ctx=ctx,
)
- return all_entries
async def _ls_original(
self,
uri: str,
show_all_hidden: bool = False,
node_limit: int = 1000,
+ offset: int = 0,
sort_by: Optional[str] = None,
sort_order: str = "asc",
ctx: Optional[RequestContext] = None,
) -> List[Dict[str, Any]]:
"""List directory contents (URI version)."""
- entry_items = await self._ls_browsable_items(uri, ctx=ctx)
- entry_items = self._sort_ls_entry_items(entry_items, sort_by, sort_order)
+ entry_items = await self._ls_browsable_items(
+ uri,
+ show_all_hidden=show_all_hidden,
+ offset=offset,
+ node_limit=node_limit,
+ sort_by=sort_by,
+ sort_order=sort_order,
+ ctx=ctx,
+ )
# AGFS returns read-only structure, need to create new dict
all_entries = []
for entry, entry_uri in entry_items:
@@ -1910,25 +1975,55 @@ class _OpsMixin:
all_entries.append(new_entry)
elif show_all_hidden:
all_entries.append(new_entry)
- return all_entries[:node_limit]
+ return all_entries
async def _ls_browsable_items(
self,
uri: str,
+ show_all_hidden: bool = False,
+ offset: int = 0,
+ node_limit: Optional[int] = None,
+ sort_by: Optional[str] = None,
+ sort_order: str = "asc",
ctx: Optional[RequestContext] = None,
) -> List[tuple[Dict[str, Any], str]]:
- """Return list entries according to namespace-enumeration semantics."""
- entry_items = await self._list_read_path_items(uri, ctx=ctx)
- access = await self._can_access_many([entry_uri for _, entry_uri in entry_items], ctx)
+ """Return one visible page while preserving RagFS ordering."""
+ if offset < 0:
+ raise ValueError("offset must be non-negative")
+ if node_limit == 0:
+ return []
+
+ raw_offset = 0
+ raw_limit = None if node_limit is None else max(node_limit, 256)
+ remaining_offset = offset
+ merge_paths = self._legacy_session_alias(uri) is not None
+ browsable: List[tuple[Dict[str, Any], str]] = []
expose_resource_names = self._acl_enabled(ctx) and is_acl_uri(uri)
- browsable = []
- for entry, entry_uri in entry_items:
- if access.get(entry_uri, False):
- browsable.append((entry, entry_uri))
- elif expose_resource_names:
- browsable.append(
- (
+ while True:
+ entry_items, consumed, exhausted = await self._list_read_path_items(
+ uri,
+ raw_offset=raw_offset,
+ raw_limit=raw_limit,
+ sort_by=sort_by,
+ sort_order=sort_order,
+ ctx=ctx,
+ )
+ if merge_paths:
+ entry_items = self._sort_ls_entry_items(entry_items, sort_by, sort_order)
+ entry_items = [
+ item
+ for item in entry_items
+ if item[0].get("isDir")
+ or not str(item[0].get("name", "")).startswith(".")
+ or show_all_hidden
+ ]
+ access = await self._can_access_many([entry_uri for _, entry_uri in entry_items], ctx)
+ for entry, entry_uri in entry_items:
+ if access.get(entry_uri, False):
+ item = (entry, entry_uri)
+ elif expose_resource_names:
+ item = (
{
"name": entry.get("name", ""),
"isDir": bool(entry.get("isDir", False)),
@@ -1936,7 +2031,19 @@ class _OpsMixin:
},
entry_uri,
)
- )
+ else:
+ continue
+
+ if remaining_offset:
+ remaining_offset -= 1
+ continue
+ browsable.append(item)
+ if node_limit is not None and len(browsable) >= node_limit:
+ return browsable
+ if exhausted:
+ break
+ raw_offset += consumed
+
return browsable
async def _augment_entries_extra_fields(
@@ -2055,16 +2162,34 @@ class _OpsMixin:
except Exception as e:
logger.warning(f"[VikingFS] Failed to delete temp {temp_uri}: {e}")
+ @staticmethod
+ def _filter_ls_entries(path: str, entries: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+ """Return entries visible at the given storage path."""
+ parts = [p for p in path.strip("/").split("/") if p]
+ if len(parts) == 2 and parts[0] == "local":
+ return [e for e in entries if e.get("name") in VikingURI.LISTABLE_SCOPES]
+ return [e for e in entries if e.get("name") not in STORAGE_INTERNAL_ENTRY_NAMES]
+
async def _ls_entries(
- self, path: str, ctx: Optional[RequestContext] = None
+ self,
+ path: str,
+ offset: int = 0,
+ limit: Optional[int] = None,
+ sort_by: Optional[str] = None,
+ sort_order: str = "asc",
+ filter_internal: bool = True,
+ ctx: Optional[RequestContext] = None,
) -> List[Dict[str, Any]]:
"""List directory entries, filtering out internal directories.
At account root (/local/{account}), uses LISTABLE_SCOPES whitelist.
At other levels, uses the shared storage internal-name blacklist.
"""
- entries = await self._async_agfs.ls(path)
- parts = [p for p in path.strip("/").split("/") if p]
- if len(parts) == 2 and parts[0] == "local":
- return [e for e in entries if e.get("name") in VikingURI.LISTABLE_SCOPES]
- return [e for e in entries if e.get("name") not in STORAGE_INTERNAL_ENTRY_NAMES]
+ entries = await self._async_agfs.ls(
+ path,
+ offset=offset,
+ limit=limit,
+ sort_by=sort_by,
+ sort_order=sort_order,
+ )
+ return self._filter_ls_entries(path, entries) if filter_internal else entries
diff --git a/sdk/go/client_test.go b/sdk/go/client_test.go
index 1717a8bd3..948ca131c 100644
--- a/sdk/go/client_test.go
+++ b/sdk/go/client_test.go
@@ -237,6 +237,12 @@ func TestListAndTreeSendQueryOptions(t *testing.T) {
if got := r.URL.Query().Get("node_limit"); got != "200" {
t.Fatalf("node_limit = %q", got)
}
+ if got := r.URL.Query().Get("offset"); got != "4" {
+ t.Fatalf("offset = %q", got)
+ }
+ if got := r.URL.Query().Get("limit"); got != "5" {
+ t.Fatalf("limit = %q", got)
+ }
if got := r.URL.Query().Get("sort_by"); got != "mtime" {
t.Fatalf("sort_by = %q", got)
}
@@ -251,11 +257,25 @@ func TestListAndTreeSendQueryOptions(t *testing.T) {
if got := r.URL.Query().Get("level_limit"); got != "0" {
t.Fatalf("level_limit = %q, want 0", got)
}
+ if got := r.URL.Query().Get("offset"); got != "6" {
+ t.Fatalf("offset = %q", got)
+ }
+ if got := r.URL.Query().Get("limit"); got != "7" {
+ t.Fatalf("limit = %q", got)
+ }
if got := r.URL.Query()["tags"]; !reflect.DeepEqual(got, []string{"env=prod"}) {
t.Fatalf("tags = %#v", got)
}
- } else if got := r.URL.Query().Get("level_limit"); got != "3" {
- t.Fatalf("level_limit = %q, want 3", got)
+ } else {
+ if got := r.URL.Query().Get("level_limit"); got != "3" {
+ t.Fatalf("level_limit = %q, want 3", got)
+ }
+ if _, ok := r.URL.Query()["offset"]; ok {
+ t.Fatal("default tree request should omit offset")
+ }
+ if _, ok := r.URL.Query()["limit"]; ok {
+ t.Fatal("default tree request should omit limit")
+ }
}
treeCalls++
default:
@@ -267,13 +287,21 @@ func TestListAndTreeSendQueryOptions(t *testing.T) {
if _, err := client.List(context.Background(), "viking://session", &ListOptions{
NodeLimit: 200,
+ Offset: 4,
+ Limit: 5,
SortBy: "mtime",
SortOrder: "desc",
Tags: []string{"env=prod", "team=search"},
}); err != nil {
t.Fatal(err)
}
- if _, err := client.Tree(context.Background(), "viking://resources/docs", &TreeOptions{LevelLimit: Int(0), Tags: []string{"env=prod"}}); err != nil {
+ if _, err := client.Tree(context.Background(), "viking://resources/docs", &TreeOptions{
+ NodeLimit: 200,
+ LevelLimit: Int(0),
+ Offset: 6,
+ Limit: 7,
+ Tags: []string{"env=prod"},
+ }); err != nil {
t.Fatal(err)
}
if _, err := client.Tree(context.Background(), "viking://resources/docs", nil); err != nil {
diff --git a/sdk/go/filesystem.go b/sdk/go/filesystem.go
index a9ff82e0a..04529a671 100644
--- a/sdk/go/filesystem.go
+++ b/sdk/go/filesystem.go
@@ -32,6 +32,12 @@ func (c *Client) List(ctx context.Context, uri string, opts *ListOptions) ([]any
queryInt(query, "abs_limit", absLimit)
queryBool(query, "show_all_hidden", opts.ShowAllHidden)
queryInt(query, "node_limit", nodeLimit)
+ if opts.Offset != 0 {
+ queryInt(query, "offset", opts.Offset)
+ }
+ if opts.Limit != 0 {
+ queryInt(query, "limit", opts.Limit)
+ }
if opts.Tags != nil {
query["tags"] = opts.Tags
}
@@ -77,6 +83,12 @@ func (c *Client) Tree(ctx context.Context, uri string, opts *TreeOptions) ([]map
queryBool(query, "show_all_hidden", opts.ShowAllHidden)
queryInt(query, "node_limit", nodeLimit)
queryInt(query, "level_limit", levelLimit)
+ if opts.Offset != 0 {
+ queryInt(query, "offset", opts.Offset)
+ }
+ if opts.Limit != 0 {
+ queryInt(query, "limit", opts.Limit)
+ }
if opts.Tags != nil {
query["tags"] = opts.Tags
}
diff --git a/sdk/go/types.go b/sdk/go/types.go
index 4f7d2beae..74ab1cd0d 100644
--- a/sdk/go/types.go
+++ b/sdk/go/types.go
@@ -177,6 +177,8 @@ type ListOptions struct {
AbsLimit int
ShowAllHidden bool
NodeLimit int
+ Offset int
+ Limit int
SortBy string
SortOrder string
Tags []string
@@ -190,6 +192,8 @@ type TreeOptions struct {
ShowAllHidden bool
NodeLimit int
LevelLimit *int
+ Offset int
+ Limit int
Tags []string
IncludeTags bool
}
diff --git a/sdk/python/openviking_sdk/client.py b/sdk/python/openviking_sdk/client.py
index 5fff2ff96..ae1e33f64 100644
--- a/sdk/python/openviking_sdk/client.py
+++ b/sdk/python/openviking_sdk/client.py
@@ -1065,6 +1065,8 @@ class AsyncHTTPClient:
extra_fields: Optional[List[str]] = None,
tags: Optional[List[str]] = None,
include_tags: bool = False,
+ offset: int = 0,
+ limit: Optional[int] = None,
) -> List[Any]:
params: Dict[str, Any] = {
"uri": VikingURI.normalize(uri),
@@ -1074,6 +1076,7 @@ class AsyncHTTPClient:
"abs_limit": abs_limit,
"show_all_hidden": show_all_hidden,
"node_limit": node_limit,
+ "offset": offset,
}
if sort_by is not None:
params["sort_by"] = sort_by
@@ -1084,6 +1087,8 @@ class AsyncHTTPClient:
params["tags"] = tags
if include_tags:
params["include_tags"] = True
+ if limit is not None:
+ params["limit"] = limit
response = await self._request(
"GET",
"/api/v1/fs/ls",
@@ -1102,6 +1107,8 @@ class AsyncHTTPClient:
extra_fields: Optional[List[str]] = None,
tags: Optional[List[str]] = None,
include_tags: bool = False,
+ offset: int = 0,
+ limit: Optional[int] = None,
) -> List[Dict[str, Any]]:
params: Dict[str, Any] = {
"uri": VikingURI.normalize(uri),
@@ -1110,6 +1117,7 @@ class AsyncHTTPClient:
"show_all_hidden": show_all_hidden,
"node_limit": node_limit,
"level_limit": level_limit,
+ "offset": offset,
}
if extra_fields:
params["extra_fields"] = list(extra_fields)
@@ -1117,6 +1125,8 @@ class AsyncHTTPClient:
params["tags"] = tags
if include_tags:
params["include_tags"] = True
+ if limit is not None:
+ params["limit"] = limit
response = await self._request(
"GET",
"/api/v1/fs/tree",
@@ -1300,14 +1310,10 @@ class AsyncHTTPClient:
return self._handle_response_data(response).get("result", {})
async def acl_get(self, uri: str) -> Dict[str, Any]:
- response = await self._http.get(
- "/api/v1/acl", params={"uri": VikingURI.normalize(uri)}
- )
+ response = await self._http.get("/api/v1/acl", params={"uri": VikingURI.normalize(uri)})
return self._handle_response_data(response).get("result", {})
- async def acl_set(
- self, uri: str, entries: List[Dict[str, str]]
- ) -> Dict[str, Any]:
+ async def acl_set(self, uri: str, entries: List[Dict[str, str]]) -> Dict[str, Any]:
response = await self._http.put(
"/api/v1/acl",
json={"uri": VikingURI.normalize(uri), "entries": entries},
@@ -1884,14 +1890,10 @@ class AsyncHTTPClient:
return self._handle_response(response)
async def admin_delete_group(self, account_id: str, group_id: str) -> Dict[str, Any]:
- response = await self._http.delete(
- f"/api/v1/admin/accounts/{account_id}/groups/{group_id}"
- )
+ response = await self._http.delete(f"/api/v1/admin/accounts/{account_id}/groups/{group_id}")
return self._handle_response(response)
- async def admin_list_group_members(
- self, account_id: str, group_id: str
- ) -> Dict[str, Any]:
+ async def admin_list_group_members(self, account_id: str, group_id: str) -> Dict[str, Any]:
response = await self._http.get(
f"/api/v1/admin/accounts/{account_id}/groups/{group_id}/members"
)
@@ -2386,6 +2388,8 @@ class SyncHTTPClient:
extra_fields: Optional[List[str]] = None,
tags: Optional[List[str]] = None,
include_tags: bool = False,
+ offset: int = 0,
+ limit: Optional[int] = None,
) -> List[Any]:
return run_async(
self._async_client.ls(
@@ -2401,6 +2405,8 @@ class SyncHTTPClient:
extra_fields=extra_fields,
tags=tags,
include_tags=include_tags,
+ offset=offset,
+ limit=limit,
)
)
@@ -2415,6 +2421,8 @@ class SyncHTTPClient:
extra_fields: Optional[List[str]] = None,
tags: Optional[List[str]] = None,
include_tags: bool = False,
+ offset: int = 0,
+ limit: Optional[int] = None,
) -> List[Dict[str, Any]]:
return run_async(
self._async_client.tree(
@@ -2427,6 +2435,8 @@ class SyncHTTPClient:
extra_fields=extra_fields,
tags=tags,
include_tags=include_tags,
+ offset=offset,
+ limit=limit,
)
)
@@ -2504,9 +2514,7 @@ class SyncHTTPClient:
options: Optional[SetTagsOptions] = None,
) -> Dict[str, Any]:
return run_async(
- self._async_client.set_tags(
- uri, tags, mode=mode, recursive=recursive, options=options
- )
+ self._async_client.set_tags(uri, tags, mode=mode, recursive=recursive, options=options)
)
def acl_get(self, uri: str) -> Dict[str, Any]:
@@ -2795,9 +2803,7 @@ class SyncHTTPClient:
limit: Optional[int] = None,
page: int = 1,
) -> List[Any]:
- return run_async(
- self._async_client.admin_list_accounts(name=name, limit=limit, page=page)
- )
+ return run_async(self._async_client.admin_list_accounts(name=name, limit=limit, page=page))
def admin_delete_account(self, account_id: str) -> Dict[str, Any]:
return run_async(self._async_client.admin_delete_account(account_id))
@@ -2860,9 +2866,7 @@ class SyncHTTPClient:
def admin_add_group_member(
self, account_id: str, group_id: str, user_id: str
) -> Dict[str, Any]:
- return run_async(
- self._async_client.admin_add_group_member(account_id, group_id, user_id)
- )
+ return run_async(self._async_client.admin_add_group_member(account_id, group_id, user_id))
def admin_remove_group_member(
self, account_id: str, group_id: str, user_id: str
@@ -2891,9 +2895,7 @@ class SyncHTTPClient:
experience_uri: str,
options: Optional[ExperienceTrajectoryOptions] = None,
) -> Dict[str, Any]:
- return run_async(
- self._async_client.list_experience_trajectories(experience_uri, options)
- )
+ return run_async(self._async_client.list_experience_trajectories(experience_uri, options))
def get_experience_outcomes(
self,
diff --git a/sdk/python/tests/test_async_client_behaviors.py b/sdk/python/tests/test_async_client_behaviors.py
index 47212b97b..0220d043f 100644
--- a/sdk/python/tests/test_async_client_behaviors.py
+++ b/sdk/python/tests/test_async_client_behaviors.py
@@ -265,9 +265,7 @@ async def test_async_http_client_sends_event_memory_tag_configuration():
client._handle_response_data = lambda _response: {"result": {"status": "ok"}}
config = {"events": {"tags": ["team=search", "channel=web"]}}
- await client.create_session(
- "tagged-session", options={"memory_extraction_config": config}
- )
+ await client.create_session("tagged-session", options={"memory_extraction_config": config})
await client.update_session_config(
"tagged-session",
{
@@ -1322,10 +1320,12 @@ async def test_ls_and_tree_pass_query_params():
abs_limit=32,
show_all_hidden=True,
node_limit=44,
+ offset=5,
+ limit=7,
sort_by="mtime",
sort_order="desc",
)
- await client.tree("viking://resources/", level_limit=2)
+ await client.tree("viking://resources/", level_limit=2, offset=4, limit=6)
await client.tree("viking://resources/", level_limit=0)
await client.tree("viking://resources/")
@@ -1340,13 +1340,16 @@ async def test_ls_and_tree_pass_query_params():
"abs_limit": 32,
"show_all_hidden": True,
"node_limit": 44,
+ "offset": 5,
+ "limit": 7,
"sort_by": "mtime",
"sort_order": "desc",
},
}
+ assert fake_http.get.await_args_list[1].kwargs["params"]["offset"] == 4
+ assert fake_http.get.await_args_list[1].kwargs["params"]["limit"] == 6
assert [
- tree_call.kwargs["params"]["level_limit"]
- for tree_call in fake_http.get.await_args_list[1:]
+ tree_call.kwargs["params"]["level_limit"] for tree_call in fake_http.get.await_args_list[1:]
] == [2, 0, 3]
diff --git a/sdk/typescript/src/client.ts b/sdk/typescript/src/client.ts
index e4c0c4553..b356f3950 100644
--- a/sdk/typescript/src/client.ts
+++ b/sdk/typescript/src/client.ts
@@ -485,6 +485,8 @@ export class OpenVikingClient {
abs_limit: options.absLimit ?? 256,
show_all_hidden: options.showAllHidden ?? false,
node_limit: options.nodeLimit ?? 1000,
+ offset: options.offset,
+ limit: options.limit,
sort_by: options.sortBy,
sort_order: options.sortOrder,
tags: options.tags,
@@ -502,6 +504,8 @@ export class OpenVikingClient {
show_all_hidden: options.showAllHidden ?? false,
node_limit: options.nodeLimit ?? 1000,
level_limit: options.levelLimit ?? 3,
+ offset: options.offset,
+ limit: options.limit,
tags: options.tags,
include_tags: options.includeTags || undefined,
},
diff --git a/sdk/typescript/src/types.ts b/sdk/typescript/src/types.ts
index 55b289f01..33859c1c8 100644
--- a/sdk/typescript/src/types.ts
+++ b/sdk/typescript/src/types.ts
@@ -202,6 +202,8 @@ export interface ListOptions {
absLimit?: number;
showAllHidden?: boolean;
nodeLimit?: number;
+ offset?: number;
+ limit?: number;
sortBy?: "name" | "mtime";
sortOrder?: "asc" | "desc";
tags?: string[];
@@ -214,6 +216,8 @@ export interface TreeOptions {
showAllHidden?: boolean;
nodeLimit?: number;
levelLimit?: number;
+ offset?: number;
+ limit?: number;
tags?: string[];
includeTags?: boolean;
}
diff --git a/sdk/typescript/tests/client.test.ts b/sdk/typescript/tests/client.test.ts
index 38f65a024..558958f89 100644
--- a/sdk/typescript/tests/client.test.ts
+++ b/sdk/typescript/tests/client.test.ts
@@ -556,21 +556,38 @@ describe("OpenVikingClient", () => {
await client.list("viking://session", {
nodeLimit: 200,
+ offset: 4,
+ limit: 5,
sortBy: "mtime",
sortOrder: "desc",
});
- await client.tree("viking://resources/docs", { levelLimit: 2 });
+ await client.tree("viking://resources/docs", {
+ levelLimit: 2,
+ offset: 6,
+ limit: 7,
+ });
await client.tree("viking://resources/docs", { levelLimit: 0 });
await client.tree("viking://resources/docs");
const listUrl = new URL(String(fetcher.mock.calls[0]![0]));
expect(listUrl.searchParams.get("node_limit")).toBe("200");
+ expect(listUrl.searchParams.get("offset")).toBe("4");
+ expect(listUrl.searchParams.get("limit")).toBe("5");
expect(listUrl.searchParams.get("sort_by")).toBe("mtime");
expect(listUrl.searchParams.get("sort_order")).toBe("desc");
- const treeLimits = fetcher.mock.calls
+ const treeUrls = fetcher.mock.calls
.slice(1)
- .map((call) => new URL(String(call[0])).searchParams.get("level_limit"));
+ .map((call) => new URL(String(call[0])));
+ const treeLimits = treeUrls.map((url) =>
+ url.searchParams.get("level_limit"),
+ );
expect(treeLimits).toEqual(["2", "0", "3"]);
+ expect(treeUrls[0]!.searchParams.get("offset")).toBe("6");
+ expect(treeUrls[0]!.searchParams.get("limit")).toBe("7");
+ expect(treeUrls[1]!.searchParams.has("offset")).toBe(false);
+ expect(treeUrls[1]!.searchParams.has("limit")).toBe(false);
+ expect(treeUrls[2]!.searchParams.has("offset")).toBe(false);
+ expect(treeUrls[2]!.searchParams.has("limit")).toBe(false);
});
it("sends addResource tags and tagMode to the server", async () => {
diff --git a/tests/agfs/test_fs_binding.py b/tests/agfs/test_fs_binding.py
index a80fde066..9525be1ec 100644
--- a/tests/agfs/test_fs_binding.py
+++ b/tests/agfs/test_fs_binding.py
@@ -61,9 +61,23 @@ class TestVikingFSBindingLocal:
entries = await vfs.ls("viking://temp/")
assert any(e["name"] == test_filename for e in entries)
+ page_dir_uri = f"viking://temp/page_{uuid.uuid4().hex}/"
+ await vfs.mkdir(page_dir_uri)
+ for name in ("a.txt", "b.txt", "c.txt"):
+ await vfs.write(f"{page_dir_uri}{name}", name)
+ page = await vfs.ls(
+ page_dir_uri,
+ output="original",
+ node_limit=1,
+ offset=1,
+ sort_by="name",
+ )
+ assert [entry["name"] for entry in page] == ["b.txt"]
+
read_data = await vfs.read(test_uri)
assert read_data.decode("utf-8") == test_content
+ await vfs.rm(page_dir_uri, recursive=True)
await vfs.rm(test_uri)
async def test_directory_operations(self, viking_fs_binding_instance):
@@ -83,9 +97,17 @@ class TestVikingFSBindingLocal:
file_uri = f"{test_dir_uri}inner.txt"
await vfs.write(file_uri, "inner content")
+ await vfs.write(f"{test_dir_uri}z.txt", "second")
sub_entries = await vfs.ls(test_dir_uri)
assert any(e["name"] == "inner.txt" for e in sub_entries)
+ tree_page = await vfs.tree(
+ test_dir_uri,
+ output="original",
+ node_limit=1,
+ offset=1,
+ )
+ assert [entry["name"] for entry in tree_page] == ["z.txt"]
await vfs.rm(test_dir_uri, recursive=True)
diff --git a/tests/pyagfs/test_async_client_fs_ctx.py b/tests/pyagfs/test_async_client_fs_ctx.py
index a05f184e0..01816d053 100644
--- a/tests/pyagfs/test_async_client_fs_ctx.py
+++ b/tests/pyagfs/test_async_client_fs_ctx.py
@@ -13,6 +13,7 @@ class _RecordingClient:
def __init__(self) -> None:
self.calls: list[tuple[str, str, dict[str, str] | None]] = []
+ self.list_options: dict[str, Any] = {}
def write(self, path: str, data: bytes, *, ctx: dict[str, str] | None = None) -> str:
"""Record write ctx and return a stable fake backend id."""
@@ -24,6 +25,18 @@ class _RecordingClient:
self.calls.append(("read", path, ctx))
return b"payload"
+ def ls(
+ self,
+ path: str,
+ *,
+ ctx: dict[str, str] | None = None,
+ **options: Any,
+ ) -> list[dict[str, Any]]:
+ """Record listing options and return an empty result."""
+ self.calls.append(("ls", path, ctx))
+ self.list_options = options
+ return []
+
@pytest.mark.asyncio
async def test_async_client_derives_account_ctx_from_local_agfs_path() -> None:
@@ -31,8 +44,24 @@ async def test_async_client_derives_account_ctx_from_local_agfs_path() -> None:
agfs = AsyncAGFSClient(client)
await agfs.write("/local/acct-1/data/file.txt", b"x")
+ await agfs.ls(
+ "/local/acct-1/data",
+ offset=2,
+ limit=3,
+ sort_by="mtime",
+ sort_order="desc",
+ )
- assert client.calls == [("write", "/local/acct-1/data/file.txt", {"account_id": "acct-1"})]
+ assert client.calls == [
+ ("write", "/local/acct-1/data/file.txt", {"account_id": "acct-1"}),
+ ("ls", "/local/acct-1/data", {"account_id": "acct-1"}),
+ ]
+ assert client.list_options == {
+ "offset": 2,
+ "limit": 3,
+ "sort_by": "mtime",
+ "sort_order": "desc",
+ }
@pytest.mark.asyncio
diff --git a/tests/server/test_api_fs_ls_sort.py b/tests/server/test_api_fs_ls_sort.py
index a4b591243..1372c0e13 100644
--- a/tests/server/test_api_fs_ls_sort.py
+++ b/tests/server/test_api_fs_ls_sort.py
@@ -27,20 +27,21 @@ def service(temp_dir):
)
-async def test_ls_sorts_by_mtime_before_applying_node_limit(client, service):
+async def test_ls_sorts_before_applying_offset_and_node_limit(client, service):
ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.ROOT)
root_uri = "viking://resources/mtime-before-limit"
await service.viking_fs.mkdir(root_uri, exist_ok=True, ctx=ctx)
- for index in range(200):
+ for index in range(300):
await service.viking_fs.mkdir(f"{root_uri}/a-{index:03d}", ctx=ctx)
newest_uri = f"{root_uri}/zz-newest"
await service.viking_fs.mkdir(newest_uri, ctx=ctx)
+ await service.viking_fs.mkdir(f"{root_uri}/tasks", ctx=ctx)
await service.viking_fs.mkdir(f"{newest_uri}/activity", ctx=ctx)
await service.viking_fs.write_file(f"{root_uri}/newer-file.md", "newer", ctx=ctx)
- response = await client.get(
+ mtime_response = await client.get(
"/api/v1/fs/ls",
params={
"uri": root_uri,
@@ -50,11 +51,48 @@ async def test_ls_sorts_by_mtime_before_applying_node_limit(client, service):
"sort_order": "desc",
},
)
+ response = await client.get(
+ "/api/v1/fs/ls",
+ params={
+ "uri": root_uri,
+ "output": "original",
+ "offset": 1,
+ "node_limit": 2,
+ "sort_by": "name",
+ "sort_order": "desc",
+ },
+ )
+ assert mtime_response.status_code == 200
+ assert mtime_response.json()["result"][0]["name"] == "zz-newest"
assert response.status_code == 200
entries = response.json()["result"]
- assert len(entries) == 200
- assert entries[0]["name"] == "zz-newest"
+ assert [entry["name"] for entry in entries] == ["a-299", "a-298"]
+
+ filtered_page = await client.get(
+ "/api/v1/fs/ls",
+ params={
+ "uri": root_uri,
+ "output": "original",
+ "limit": 256,
+ "sort_by": "name",
+ "sort_order": "desc",
+ },
+ )
+ filtered_entries = filtered_page.json()["result"]
+ assert len(filtered_entries) == 256
+ assert all(entry["name"] != "tasks" for entry in filtered_entries)
+
+ invalid_offset = await client.get(
+ "/api/v1/fs/ls",
+ params={"uri": root_uri, "offset": -1},
+ )
+ invalid_limit = await client.get(
+ "/api/v1/fs/ls",
+ params={"uri": root_uri, "limit": 0},
+ )
+ assert invalid_offset.status_code == 400
+ assert invalid_limit.status_code == 400
async def test_session_list_keeps_newest_directory_past_storage_limit(client, service):
diff --git a/tests/server/test_filesystem_router.py b/tests/server/test_filesystem_router.py
index 071e89ee6..48b865c6e 100644
--- a/tests/server/test_filesystem_router.py
+++ b/tests/server/test_filesystem_router.py
@@ -369,23 +369,39 @@ async def test_ls_user_container_lists_only_caller_space(app, client, service):
@pytest.mark.asyncio
-async def test_ls_forwards_tags_to_filesystem_service(monkeypatch):
- seen = {}
+async def test_ls_and_tree_forward_pagination_to_filesystem_service(monkeypatch):
+ seen = {"ls": {}, "tree": {}}
async def fake_ls(uri, **kwargs):
- seen.update(uri=uri, **kwargs)
+ seen["ls"].update(uri=uri, **kwargs)
+ return []
+
+ async def fake_tree(uri, **kwargs):
+ seen["tree"].update(uri=uri, **kwargs)
return []
monkeypatch.setattr(
filesystem,
"get_service",
- lambda: SimpleNamespace(fs=SimpleNamespace(ls=fake_ls)),
+ lambda: SimpleNamespace(fs=SimpleNamespace(ls=fake_ls, tree=fake_tree)),
)
await filesystem.ls(
uri="viking://resources",
tags=["team=search", "env=prod"],
+ offset=4,
+ limit=9,
+ _ctx=RequestContext(user=UserIdentifier("acct", "alice"), role=Role.USER),
+ )
+ await filesystem.tree(
+ uri="viking://resources",
+ offset=3,
+ limit=5,
_ctx=RequestContext(user=UserIdentifier("acct", "alice"), role=Role.USER),
)
- assert seen["tags"] == ["team=search", "env=prod"]
+ assert seen["ls"]["tags"] == ["team=search", "env=prod"]
+ assert seen["ls"]["offset"] == 4
+ assert seen["ls"]["node_limit"] == 9
+ assert seen["tree"]["offset"] == 3
+ assert seen["tree"]["node_limit"] == 5
diff --git a/tests/service/test_fs_service.py b/tests/service/test_fs_service.py
index bbdfbda3d..e378ff8f6 100644
--- a/tests/service/test_fs_service.py
+++ b/tests/service/test_fs_service.py
@@ -530,18 +530,30 @@ async def test_tagged_grep_reuses_tags_returned_by_viking_fs(request_context):
@pytest.mark.asyncio
-async def test_ls_projects_tags_filters_with_and_before_applying_node_limit(request_context):
+async def test_ls_applies_offset_and_node_limit_after_tag_filtering(request_context):
entries = [
- {"uri": "viking://resources/a.md", "isDir": False},
+ {
+ "uri": f"viking://resources/unmatched-{index:03d}.md",
+ "isDir": False,
+ }
+ for index in range(256)
+ ] + [
{"uri": "viking://resources/b.md", "isDir": False},
{"uri": "viking://resources/c.md", "isDir": False},
]
- viking_fs = SimpleNamespace(ls=AsyncMock(return_value=entries))
+
+ async def fake_ls(*_args, offset=0, node_limit=None, **_kwargs):
+ return entries[offset:] if node_limit is None else entries[offset : offset + node_limit]
+
+ finalized = [{"uri": "viking://resources/c.md", "isDir": False, "abstract": "summary"}]
+ viking_fs = SimpleNamespace(
+ ls=AsyncMock(side_effect=fake_ls),
+ _finalize_listing_entries=AsyncMock(return_value=finalized),
+ )
class FakeVikingDB:
async def filter(self, **_kwargs):
return [
- {"uri": "viking://resources/a.md", "level": 2, "search_tags": ["team=search"]},
{
"uri": "viking://resources/b.md",
"level": 2,
@@ -560,12 +572,19 @@ async def test_ls_projects_tags_filters_with_and_before_applying_node_limit(requ
ctx=request_context,
tags=["team=search", "env=prod"],
node_limit=1,
+ offset=1,
+ output="agent",
)
- assert result == [
- {"uri": "viking://resources/b.md", "isDir": False, "tags": ["team=search", "env=prod"]}
+ assert result == finalized
+ assert viking_fs.ls.await_count == 2
+ assert viking_fs.ls.await_args_list[0].kwargs["output"] == "original"
+ assert viking_fs.ls.await_args_list[0].kwargs["node_limit"] == 256
+ assert viking_fs.ls.await_args_list[1].kwargs["offset"] == 256
+ selected = viking_fs._finalize_listing_entries.await_args.args[0]
+ assert selected == [
+ {"uri": "viking://resources/c.md", "isDir": False, "tags": ["team=search", "env=prod"]}
]
- assert viking_fs.ls.await_args.kwargs["node_limit"] is None
@pytest.mark.asyncio
@@ -635,7 +654,7 @@ async def test_tree_projects_directory_tags_from_abstract_and_overview_records(r
assert result == [
{"uri": "viking://resources/docs", "isDir": True, "tags": ["team=search", "env=prod"]}
]
- assert viking_fs.tree.await_args.kwargs["node_limit"] is None
+ assert viking_fs.tree.await_args.kwargs["node_limit"] == 1000
@pytest.mark.asyncio
diff --git a/tests/storage/test_viking_fs_tree.py b/tests/storage/test_viking_fs_tree.py
index 17c3efe51..885b084bc 100644
--- a/tests/storage/test_viking_fs_tree.py
+++ b/tests/storage/test_viking_fs_tree.py
@@ -258,13 +258,13 @@ def test_is_tree_entry_visible_default_ctx(monkeypatch, fs):
@pytest.mark.asyncio
-async def test_iter_visible_tree_entries_node_limit_amplified_to_rust(monkeypatch, fs):
- """PY-ITER-001: node_limit is amplified (× overfetch factor) when pushed to
- Rust, keeping memory bounded while preserving the ACL-after-filter semantic."""
+async def test_iter_visible_tree_entries_uses_minimum_backend_page_size(monkeypatch, fs):
+ """PY-ITER-001: bounded tree reads use the minimum backend page size."""
captured = {}
async def fake_tree_directory(_path, **kwargs):
captured["node_limit"] = kwargs.get("node_limit")
+ captured["offset"] = kwargs.get("offset")
return []
patch_tree_env(monkeypatch, fs, fake_tree_directory)
@@ -274,7 +274,7 @@ async def test_iter_visible_tree_entries_node_limit_amplified_to_rust(monkeypatc
):
pass
- assert captured["node_limit"] == 10 * fs._TREE_OVERFETCH_FACTOR
+ assert captured == {"node_limit": 256, "offset": 0}
@pytest.mark.asyncio
@@ -318,8 +318,8 @@ async def test_iter_visible_tree_entries_level_limit_passed_to_rust(monkeypatch,
@pytest.mark.asyncio
-async def test_iter_visible_tree_entries_node_limit_after_acl(monkeypatch, fs):
- """PY-ITER-002: node_limit applied AFTER ACL filtering."""
+async def test_iter_visible_tree_entries_offset_and_node_limit_after_acl(monkeypatch, fs):
+ """PY-ITER-002: offset and node_limit apply after ACL filtering."""
visible_count = 0
entries = [
@@ -336,41 +336,33 @@ async def test_iter_visible_tree_entries_node_limit_after_acl(monkeypatch, fs):
results = []
async for entry, _entry_uri in fs._iter_visible_tree_entries(
- "viking://resources", node_limit=3, ctx=_default_ctx()
+ "viking://resources", offset=1, node_limit=2, ctx=_default_ctx()
):
results.append(entry)
- assert len(results) == 3
- assert visible_count == 3, "only 3 entries should have ACL checked before limit hit"
+ assert [entry["info"]["name"] for entry in results] == ["b", "c"]
+ assert visible_count == 3, "only skipped and returned entries should be ACL checked"
@pytest.mark.asyncio
-async def test_iter_visible_tree_entries_refetch_when_under_limit(monkeypatch, fs):
- """PY-ITER-004: when ACL filtering leaves too few visible entries and Rust
- returned a full page, the raw limit is doubled and re-fetched (zero-regression
- bounded over-fetch)."""
- factor = fs._TREE_OVERFETCH_FACTOR
+async def test_iter_visible_tree_entries_reads_next_page_when_filtering_is_sparse(monkeypatch, fs):
+ """PY-ITER-004: sparse visible results advance the RagFS offset."""
node_limit = 2
- # First page (size == raw_limit) is entirely invisible; second page after
- # doubling contains the visible entries.
invisible = [
- make_entry(f"/local/test_account/resources/h{i}/x", "x", is_dir=False)
- for i in range(node_limit * factor)
+ make_entry(f"/local/test_account/resources/h{i}/x", "x", is_dir=False) for i in range(256)
]
visible = [
make_entry(f"/local/test_account/resources/v{i}", f"v{i}", is_dir=False)
for i in range(node_limit)
]
- captured_limits = []
+ entries = invisible + visible
+ captured_pages = []
async def fake_tree_directory(_path, **kwargs):
+ raw_offset = kwargs.get("offset")
raw_limit = kwargs.get("node_limit")
- captured_limits.append(raw_limit)
- # First call returns a full page of invisible entries; subsequent call
- # (doubled limit) returns invisible + visible.
- if len(captured_limits) == 1:
- return invisible[:raw_limit]
- return invisible + visible
+ captured_pages.append((raw_offset, raw_limit))
+ return entries[raw_offset : raw_offset + raw_limit]
def fake_is_accessible(uri, _ctx):
# Entries under an "hN" directory are invisible (ACL denied).
@@ -385,9 +377,7 @@ async def test_iter_visible_tree_entries_refetch_when_under_limit(monkeypatch, f
results.append(entry)
assert len(results) == node_limit
- # Re-fetch happened: first raw_limit = node_limit*factor, then doubled.
- assert captured_limits[0] == node_limit * factor
- assert captured_limits[1] == node_limit * factor * 2
+ assert captured_pages == [(0, 256), (256, 256)]
@pytest.mark.asyncio
@@ -657,6 +647,14 @@ async def test_ls_agent_modtime_is_raw_utc_iso(monkeypatch, fs):
"isDir": True,
"access": "denied",
}
+ tied = [
+ ({"name": name, "isDir": False, "modTime": "2026-01-01T00:00:00Z"}, name)
+ for name in ["b.md", "a.md"]
+ ]
+ assert [entry["name"] for entry, _ in fs._sort_ls_entry_items(tied, "mtime", "desc")] == [
+ "a.md",
+ "b.md",
+ ]
@pytest.mark.asyncio
diff --git a/tests/utils/mock_agfs.py b/tests/utils/mock_agfs.py
index ecb080f6f..ee061d89d 100644
--- a/tests/utils/mock_agfs.py
+++ b/tests/utils/mock_agfs.py
@@ -34,6 +34,7 @@ class MockLocalAGFS:
self._resolve(path).mkdir(parents=parents, exist_ok=exist_ok)
def ls(self, path, ctx=None, **kwargs):
+ """List test entries with the same sorting and pagination contract as RagFS."""
p = self._resolve(path)
if not p.exists():
return []
@@ -49,7 +50,28 @@ class MockLocalAGFS:
"uri": f"viking://{path}/{item.name}".replace("//", "/"),
}
)
- return res
+ sort_by = kwargs.get("sort_by")
+ reverse = kwargs.get("sort_order", "asc") == "desc"
+ if sort_by:
+ key = (
+ (lambda entry: (str(entry["name"]).lower(), str(entry["name"])))
+ if sort_by == "name"
+ else (
+ lambda entry: (
+ entry["mtime"],
+ str(entry["name"]).lower(),
+ str(entry["name"]),
+ )
+ )
+ )
+ directories = sorted(
+ (entry for entry in res if entry["isDir"]), key=key, reverse=reverse
+ )
+ files = sorted((entry for entry in res if not entry["isDir"]), key=key, reverse=reverse)
+ res = directories + files
+ offset = kwargs.get("offset", 0)
+ limit = kwargs.get("limit")
+ return res[offset:] if limit is None else res[offset : offset + limit]
def glob_directory(
self,