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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion acfs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
56 changes: 41 additions & 15 deletions acfs/acfs.go
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down Expand Up @@ -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 {
Expand All @@ -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)
Expand All @@ -95,36 +108,49 @@ 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)
if errors.Is(entryErr, fs.ErrNotExist) {
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
Expand Down
45 changes: 45 additions & 0 deletions acfs/acfs_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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()

Expand Down
14 changes: 12 additions & 2 deletions acfs/internal/cli/run.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
Expand All @@ -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)
Expand All @@ -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)
Expand Down Expand Up @@ -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)
}
Expand Down
53 changes: 53 additions & 0 deletions acfs/internal/cli/run_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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()

Expand Down
20 changes: 18 additions & 2 deletions acfs/types/entry.go
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down
Loading