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