From 7a30cb656e34bed568ca472c481fe0e39922a6df Mon Sep 17 00:00:00 2001 From: Neureka Date: Sun, 8 Nov 2026 10:15:29 -0800 Subject: [PATCH] feat(acfs): add a limit to list `acfs list --limit N` and the new Root.ListEachBounded and Root.ListBounded stop after N entries. Names are still read and sorted for the order, but only the emitted entries and one more are inspected, so the helper's temporary output and stat calls are bounded by the caller's cap instead of the folder size. A limited response adds "truncated":true when entries were left out. Without --limit the output is byte-identical, so the protocol stays at version 2. ListEach and List keep their signatures. --- acfs/README.md | 4 ++- acfs/acfs.go | 56 +++++++++++++++++++++++++---------- acfs/acfs_test.go | 45 ++++++++++++++++++++++++++++ acfs/internal/cli/run.go | 14 +++++++-- acfs/internal/cli/run_test.go | 53 +++++++++++++++++++++++++++++++++ acfs/types/entry.go | 20 +++++++++++-- 6 files changed, 172 insertions(+), 20 deletions(-) diff --git a/acfs/README.md b/acfs/README.md index 944e4d8..cda55b8 100644 --- a/acfs/README.md +++ b/acfs/README.md @@ -66,7 +66,9 @@ used by the Arcane tools image: acfs list|walk|stat|read|write|mkdir|remove|apply|version ``` -`list`, `stat`, and `apply` emit JSON. `walk` emits NDJSON with a mandatory end +`list`, `stat`, and `apply` emit JSON. `list --limit N` emits at most `N` +entries in name order and adds `"truncated":true` when it left any out; without +`--limit` the output is unchanged. `walk` emits NDJSON with a mandatory end record and supports depth and entry limits. `read` emits an `ARCW` protocol-v2 header followed by raw file content. Failures are emitted as structured JSON only on stderr. diff --git a/acfs/acfs.go b/acfs/acfs.go index b9002a9..92f35a3 100644 --- a/acfs/acfs.go +++ b/acfs/acfs.go @@ -23,31 +23,44 @@ const directoryReadBatchSize = 256 // ListEach visits the direct children of a root-confined directory in // deterministic name order without retaining all metadata in memory. func (r Root) ListEach(ctx context.Context, logicalPath string, visit func(acfstypes.Entry) error) error { + _, err := r.ListEachBounded(ctx, logicalPath, acfstypes.ListOptions{}, visit) + return err +} + +// ListEachBounded is ListEach with options.Limit capping the number of visited +// entries. Every name is still read and sorted to keep the order +// deterministic, but only the visited entries and one more, to report +// truncation, are inspected. +func (r Root) ListEachBounded(ctx context.Context, logicalPath string, options acfstypes.ListOptions, visit func(acfstypes.Entry) error) (acfstypes.ListResult, error) { + var result acfstypes.ListResult if visit == nil { - return errors.New("visit callback is required") + return result, errors.New("visit callback is required") + } + if options.Limit < 0 { + return result, errors.New("list limit must be non-negative") } if err := ctx.Err(); err != nil { - return err + return result, err } relativePath, err := kitfs.NormalizeLogicalPath(logicalPath) if err != nil { - return err + return result, err } err = rejectReservedPath(relativePath) if err != nil { - return err + return result, err } root, err := os.OpenRoot(r.Path) if err != nil { - return fmt.Errorf("open workspace root: %w", err) + return result, fmt.Errorf("open workspace root: %w", err) } defer func() { _ = root.Close() }() resolvedPath, err := resolvePath(root, relativePath, true) if err != nil { - return err + return result, err } names, err := func() ([]string, error) { @@ -77,7 +90,7 @@ func (r Root) ListEach(ctx context.Context, logicalPath string, visit func(acfst return names, nil }() if err != nil { - return err + return result, err } for _, name := range names { @@ -86,7 +99,7 @@ func (r Root) ListEach(ctx context.Context, logicalPath string, visit func(acfst } err = ctx.Err() if err != nil { - return err + return result, err } entryPath := path.Join(resolvedPath, name) @@ -95,8 +108,13 @@ func (r Root) ListEach(ctx context.Context, logicalPath string, visit func(acfst if errors.Is(statErr, fs.ErrNotExist) { continue } + if options.Limit > 0 && result.Count >= options.Limit { + // The child still exists, so the limit omitted at least one entry. + result.Truncated = true + return result, nil + } if statErr != nil { - return fmt.Errorf("stat %q: %w", kitfs.LogicalPath(entryPath), statErr) + return result, fmt.Errorf("stat %q: %w", kitfs.LogicalPath(entryPath), statErr) } entry, entryErr := entryFromInfo(root, entryPath, info) @@ -104,27 +122,35 @@ func (r Root) ListEach(ctx context.Context, logicalPath string, visit func(acfst continue } if entryErr != nil { - return entryErr + return result, entryErr } err = visit(entry) if err != nil { - return fmt.Errorf("visit %q: %w", entry.Path, err) + return result, fmt.Errorf("visit %q: %w", entry.Path, err) } + result.Count++ } - return nil + return result, nil } // List returns the direct children of a root-confined directory. func (r Root) List(ctx context.Context, logicalPath string) ([]acfstypes.Entry, error) { + entries, _, err := r.ListBounded(ctx, logicalPath, acfstypes.ListOptions{}) + return entries, err +} + +// ListBounded is List with options.Limit capping the number of returned +// entries. The result reports whether the limit omitted any entries. +func (r Root) ListBounded(ctx context.Context, logicalPath string, options acfstypes.ListOptions) ([]acfstypes.Entry, acfstypes.ListResult, error) { entries := make([]acfstypes.Entry, 0) - err := r.ListEach(ctx, logicalPath, func(entry acfstypes.Entry) error { + result, err := r.ListEachBounded(ctx, logicalPath, options, func(entry acfstypes.Entry) error { entries = append(entries, entry) return nil }) if err != nil { - return nil, err + return nil, acfstypes.ListResult{}, err } - return entries, nil + return entries, result, nil } // Stat returns metadata for a root-confined path. By default the final symbolic diff --git a/acfs/acfs_test.go b/acfs/acfs_test.go index fe29fbe..d3b2ac9 100644 --- a/acfs/acfs_test.go +++ b/acfs/acfs_test.go @@ -119,6 +119,51 @@ func TestListEmptyDirectory(t *testing.T) { } } +func TestListBounded(t *testing.T) { + t.Parallel() + + root := t.TempDir() + for _, name := range []string{"c", "a", "b"} { + writeFixtureFile(t, filepath.Join(root, name), name, 0o600) + } + writeFixtureFile(t, filepath.Join(root, temporaryWritePrefix+"pending"), "", 0o600) + + tests := map[string]struct { + want []string + limit int + truncated bool + }{ + "unlimited": {limit: 0, want: []string{"a", "b", "c"}}, + "below count": {limit: 2, want: []string{"a", "b"}, truncated: true}, + "equal to count": {limit: 3, want: []string{"a", "b", "c"}}, + "above count": {limit: 10, want: []string{"a", "b", "c"}}, + "single entry": {limit: 1, want: []string{"a"}, truncated: true}, + } + for name, test := range tests { + t.Run(name, func(t *testing.T) { + t.Parallel() + entries, result, err := Root{Path: root}.ListBounded(t.Context(), "/", acfstypes.ListOptions{Limit: test.limit}) + if err != nil { + t.Fatalf("ListBounded: %v", err) + } + names := make([]string, 0, len(entries)) + for _, entry := range entries { + names = append(names, entry.Name) + } + if !slices.Equal(names, test.want) { + t.Errorf("names = %q, want %q", names, test.want) + } + if result.Count != len(test.want) || result.Truncated != test.truncated { + t.Errorf("result = %#v, want count %d, truncated %t", result, len(test.want), test.truncated) + } + }) + } + + if _, _, err := (Root{Path: root}).ListBounded(t.Context(), "/", acfstypes.ListOptions{Limit: -1}); err == nil { + t.Error("ListBounded accepted a negative limit") + } +} + func TestReadToResolvesOnlyInternalSymlinks(t *testing.T) { t.Parallel() diff --git a/acfs/internal/cli/run.go b/acfs/internal/cli/run.go index 76d7cbe..c4e6370 100644 --- a/acfs/internal/cli/run.go +++ b/acfs/internal/cli/run.go @@ -123,6 +123,7 @@ func encodeJSON(destination io.Writer, value any) error { func runList(ctx context.Context, args []string, stdout io.Writer) error { flags := newFlagSet("list") values := addPathFlags(flags) + limit := flags.Int("limit", 0, "maximum entries to emit; zero is unlimited") if err := flags.Parse(args); err != nil { return err } @@ -132,6 +133,9 @@ func runList(ctx context.Context, args []string, stdout io.Writer) error { if err := validatePathFlags(values); err != nil { return err } + if *limit < 0 { + return errors.New("--limit must be non-negative") + } temporaryOutput, err := os.CreateTemp("", "acfs-list-*") if err != nil { return fmt.Errorf("create list output: %w", err) @@ -147,7 +151,7 @@ func runList(ctx context.Context, args []string, stdout io.Writer) error { var encodedEntry bytes.Buffer entryEncoder := json.NewEncoder(&encodedEntry) entryEncoder.SetEscapeHTML(false) - err = acfs.Root{Path: values.root}.ListEach(ctx, values.path, func(entry acfstypes.Entry) error { + result, err := acfs.Root{Path: values.root}.ListEachBounded(ctx, values.path, acfstypes.ListOptions{Limit: *limit}, func(entry acfstypes.Entry) error { if !started { if _, writeErr := io.WriteString(bufferedOutput, `{"entries":[`); writeErr != nil { return fmt.Errorf("write list prefix: %w", writeErr) @@ -180,7 +184,13 @@ func runList(ctx context.Context, args []string, stdout io.Writer) error { return fmt.Errorf("write list prefix: %w", err) } } - _, err = fmt.Fprintf(bufferedOutput, `],"version":%d}`+"\n", acfstypes.ProtocolVersion) + // Keep the response byte-identical to earlier releases unless entries were + // omitted, so callers that predate the limit see no change. + suffix := `],"version":%d}` + "\n" + if result.Truncated { + suffix = `],"truncated":true,"version":%d}` + "\n" + } + _, err = fmt.Fprintf(bufferedOutput, suffix, acfstypes.ProtocolVersion) if err != nil { return fmt.Errorf("write list suffix: %w", err) } diff --git a/acfs/internal/cli/run_test.go b/acfs/internal/cli/run_test.go index 7621fc9..fb23351 100644 --- a/acfs/internal/cli/run_test.go +++ b/acfs/internal/cli/run_test.go @@ -77,6 +77,59 @@ func TestListAndStatGolden(t *testing.T) { } } +func TestListLimit(t *testing.T) { + t.Parallel() + + root := t.TempDir() + for _, name := range []string{"b", "a"} { + if err := os.WriteFile(filepath.Join(root, name), []byte(name), 0o600); err != nil { + t.Fatal(err) + } + } + + tests := map[string]struct { + limit string + want []string + truncated bool + }{ + "truncated": {limit: "1", want: []string{"a"}, truncated: true}, + "not truncated": {limit: "2", want: []string{"a", "b"}}, + "unlimited": {limit: "0", want: []string{"a", "b"}}, + } + for name, test := range tests { + t.Run(name, func(t *testing.T) { + t.Parallel() + exitCode, stdout, stderr := runCommand(t, []string{ + "list", "--root", root, "--path", "/", "--limit", test.limit, + }, "") + if exitCode != exitSuccess || stderr != "" { + t.Fatalf("Run = (exit %d, stderr %q), want success", exitCode, stderr) + } + var response acfstypes.ListResponse + if err := json.Unmarshal(stdout, &response); err != nil { + t.Fatalf("decode %q: %v", stdout, err) + } + names := make([]string, 0, len(response.Entries)) + for _, entry := range response.Entries { + names = append(names, entry.Name) + } + if strings.Join(names, ",") != strings.Join(test.want, ",") || response.Truncated != test.truncated { + t.Fatalf("response = %s, want names %q, truncated %t", stdout, test.want, test.truncated) + } + if !test.truncated && bytes.Contains(stdout, []byte(`"truncated"`)) { + t.Fatalf("untruncated response mentions truncation: %s", stdout) + } + }) + } + + exitCode, stdout, stderr := runCommand(t, []string{ + "list", "--root", root, "--path", "/", "--limit", "-1", + }, "") + if exitCode != exitFailure || len(stdout) != 0 || !strings.Contains(stderr, "--limit must be non-negative") { + t.Fatalf("Run = (exit %d, stdout %q, stderr %q), want limit error", exitCode, stdout, stderr) + } +} + func TestReadFramingAndLimit(t *testing.T) { t.Parallel() diff --git a/acfs/types/entry.go b/acfs/types/entry.go index 9db778f..0531598 100644 --- a/acfs/types/entry.go +++ b/acfs/types/entry.go @@ -25,9 +25,11 @@ type Entry struct { } // ListResponse is the versioned response emitted by the list command. +// Truncated reports that a --limit omitted entries; it is absent otherwise. type ListResponse struct { - Entries []Entry `json:"entries"` - Version int `json:"version"` + Entries []Entry `json:"entries"` + Truncated bool `json:"truncated,omitempty"` + Version int `json:"version"` } // StatResponse is the versioned response emitted by the stat command. @@ -54,6 +56,20 @@ type StatOptions struct { FollowFinal bool } +// ListOptions bounds a directory listing. The zero value is unlimited. +type ListOptions struct { + // Limit is the maximum number of entries to visit; zero is unlimited. + Limit int +} + +// ListResult summarizes a bounded directory listing. +type ListResult struct { + // Count is the number of visited entries. + Count int + // Truncated reports that Limit omitted at least one entry. + Truncated bool +} + // WalkOptions bounds a recursive traversal. Zero values are unlimited. type WalkOptions struct { MaxDepth int