ACFS

Root-confined filesystem operations for Arcane and other Go applications.

ACFS provides efficient directory listing, recursive walking, metadata, and streaming file operations without spawning a process for every entry. Logical paths are confined with os.Root, and directory traversal never follows symlinks.

Important

This module is in early development. The API is not stable and may change before v1.0.0.

Getting started

go get go.getarcane.app/acfs@latest

entries, err := acfs.List(ctx, "/var/lib/docker/volumes/example/_data", "/")
if err != nil {
	return err
}

err = acfs.Walk(ctx, root, "/logs", func(entry types.Entry) error {
	fmt.Println(entry.Path, entry.Mode, entry.Size)
	return nil
})

The root package also provides WalkBounded, Stat, Exists, ReadFile, ReadTo, WriteFile, WriteFrom, Mkdir, MkdirAll, MkdirTemp, Rename, Remove, RemoveAll, CopyDir, MirrorDir, LogicalPath, and ordered batch Apply. Public filesystem and protocol DTOs live in types.

Subpackage acfs/atomic provides a crash-safe WriteFile for the rare destination that has no natural workspace root, such as a user-specified output file. Unlike acfs.WriteFile it refuses a symlinked destination rather than replacing it.

CLI

GoReleaser publishes the static acfs Linux binary for every architecture 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 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.

License

ACFS is released under the BSD 3-Clause License.