From e858867f918b4c649a0718e8dc4aa80f55140703 Mon Sep 17 00:00:00 2001 From: Matthew Mattox Date: Sat, 24 Oct 2026 03:45:51 -0500 Subject: [PATCH 1/4] chore: remove legacy gob prototype main.go The root main.go was the original single-block gob prototype. The real filesystem lives in cmd/mount, cmd/fsck and internal/. Nothing builds, tests or imports the root package. Co-Authored-By: Claude Opus 5.5 --- main.go | 352 -------------------------------------------------------- 1 file changed, 352 deletions(-) delete mode 100644 main.go diff --git a/main.go b/main.go deleted file mode 100644 index 29934865..00000000 --- a/main.go +++ /dev/null @@ -1,352 +0,0 @@ -package main - -import ( - "bytes" - "context" - "encoding/gob" - "flag" - "fmt" - "log" - "os" - "strconv" - "syscall" - - "github.com/hanwen/go-fuse/v2/fs" - "github.com/hanwen/go-fuse/v2/fuse" -) - -var device *os.File -var deviceSize int64 - -const blockSize = 1024 * 1024 // 1 MB per block -const metadataBlockIndex = 0 // The block index where metadata is stored - -type FileMetadata struct { - Inode uint64 - Filename string - Size uint64 - Block int64 -} - -type File struct { - fs.Inode - metadata *FileMetadata - isLocked bool - lockOwner uint64 -} - -var fileTable = map[string]*FileMetadata{} -var currentBlock int64 = 1 // Start from block 1 to reserve block 0 for metadata - -// Compile-time interface checks -var ( - _ fs.InodeEmbedder = (*File)(nil) - _ fs.NodeGetattrer = (*File)(nil) - _ fs.NodeReader = (*File)(nil) - _ fs.NodeWriter = (*File)(nil) - _ fs.NodeFsyncer = (*File)(nil) - _ fs.NodeSetxattrer = (*File)(nil) -) - -var ( - _ fs.InodeEmbedder = (*Dir)(nil) - _ fs.NodeGetattrer = (*Dir)(nil) - _ fs.NodeReaddirer = (*Dir)(nil) - _ fs.NodeLookuper = (*Dir)(nil) - _ fs.NodeCreater = (*Dir)(nil) -) - -var ( - _ fs.InodeEmbedder = (*FS)(nil) - _ fs.NodeOnAdder = (*FS)(nil) - _ fs.NodeStatfser = (*FS)(nil) -) - -func openDevice(path string) error { - var err error - device, err = os.OpenFile(path, os.O_RDWR, 0660) - if err != nil { - return err - } - - // Determine device size for Statfs - deviceSize, err = device.Seek(0, os.SEEK_END) - if err != nil { - return err - } - // Rewind after getting size - _, err = device.Seek(0, os.SEEK_SET) - return err -} - -func saveMetadata() error { - var buf bytes.Buffer - enc := gob.NewEncoder(&buf) - if err := enc.Encode(fileTable); err != nil { - return err - } - _, err := device.WriteAt(buf.Bytes(), metadataBlockIndex*blockSize) - return err -} - -func loadMetadata() error { - var buf bytes.Buffer - metadataBlock := make([]byte, blockSize) - _, err := device.ReadAt(metadataBlock, metadataBlockIndex*blockSize) - if err != nil { - return err - } - buf.Write(metadataBlock) - dec := gob.NewDecoder(&buf) - err = dec.Decode(&fileTable) - return err -} - -func (f *File) SetLock(ctx context.Context, owner uint64) error { - if f.isLocked { - return fmt.Errorf("file is already locked") - } - f.isLocked = true - f.lockOwner = owner - return nil -} - -func (f *File) ReleaseLock(ctx context.Context, owner uint64) error { - if !f.isLocked || f.lockOwner != owner { - return fmt.Errorf("file is not locked by this owner") - } - f.isLocked = false - f.lockOwner = 0 - return nil -} - -func (f *File) Getattr(ctx context.Context, fh fs.FileHandle, out *fuse.AttrOut) syscall.Errno { - log.Println("Attr called for File") - out.Ino = f.metadata.Inode - out.Mode = fuse.S_IFREG | 0666 - out.Size = f.metadata.Size - return 0 -} - -func (f *File) Read(ctx context.Context, fh fs.FileHandle, dest []byte, off int64) (fuse.ReadResult, syscall.Errno) { - buf := make([]byte, blockSize) - _, err := device.ReadAt(buf, f.metadata.Block*blockSize) - if err != nil { - return nil, syscall.EIO - } - data := buf[:f.metadata.Size] - - // Handle offset - if off >= int64(len(data)) { - return fuse.ReadResultData(nil), 0 - } - data = data[off:] - - // Limit to requested size - if len(data) > len(dest) { - data = data[:len(dest)] - } - - return fuse.ReadResultData(data), 0 -} - -func (f *File) Setxattr(ctx context.Context, attr string, data []byte, flags uint32) syscall.Errno { - switch attr { - case "user.lock": - owner, _ := strconv.ParseUint(string(data), 10, 64) - if err := f.SetLock(ctx, owner); err != nil { - return syscall.EBUSY - } - return 0 - case "user.unlock": - owner, _ := strconv.ParseUint(string(data), 10, 64) - if err := f.ReleaseLock(ctx, owner); err != nil { - return syscall.EINVAL - } - return 0 - } - return syscall.ENODATA -} - -func (f *File) Write(ctx context.Context, fh fs.FileHandle, data []byte, off int64) (uint32, syscall.Errno) { - if uint64(len(data)) > blockSize { - return 0, syscall.EFBIG - } - _, err := device.WriteAt(data, f.metadata.Block*blockSize) - if err != nil { - return 0, syscall.EIO - } - f.metadata.Size = uint64(len(data)) - - if err := saveMetadata(); err != nil { - log.Printf("Failed to save metadata: %v", err) - } - return uint32(len(data)), 0 -} - -func (f *File) Fsync(ctx context.Context, fh fs.FileHandle, flags uint32) syscall.Errno { - log.Println("Fsync called for File") - if err := device.Sync(); err != nil { - return syscall.EIO - } - return 0 -} - -type Dir struct { - fs.Inode -} - -func (d *Dir) Getattr(ctx context.Context, fh fs.FileHandle, out *fuse.AttrOut) syscall.Errno { - log.Println("Attr called for Dir") - out.Ino = 1 - out.Mode = fuse.S_IFDIR | 0555 - out.Uid = uint32(os.Getuid()) - out.Gid = uint32(os.Getgid()) - return 0 -} - -// dirStream implements fs.DirStream -type dirStream struct { - entries []fuse.DirEntry - pos int -} - -func (ds *dirStream) HasNext() bool { - return ds.pos < len(ds.entries) -} - -func (ds *dirStream) Next() (fuse.DirEntry, syscall.Errno) { - if ds.pos >= len(ds.entries) { - return fuse.DirEntry{}, 0 - } - e := ds.entries[ds.pos] - ds.pos++ - return e, 0 -} - -func (ds *dirStream) Close() {} - -func (d *Dir) Readdir(ctx context.Context) (fs.DirStream, syscall.Errno) { - log.Println("Readdir called for Dir") - var entries []fuse.DirEntry - for _, meta := range fileTable { - entries = append(entries, fuse.DirEntry{ - Ino: meta.Inode, - Name: meta.Filename, - Mode: fuse.S_IFREG, - }) - } - return &dirStream{entries: entries}, 0 -} - -func (d *Dir) Lookup(ctx context.Context, name string, out *fuse.EntryOut) (*fs.Inode, syscall.Errno) { - log.Printf("Lookup called for name: %s", name) - if meta, ok := fileTable[name]; ok { - file := &File{metadata: meta} - child := d.NewPersistentInode(ctx, file, fs.StableAttr{ - Mode: fuse.S_IFREG, - Ino: meta.Inode, - }) - out.Ino = meta.Inode - out.Mode = fuse.S_IFREG | 0666 - out.Size = meta.Size - return child, 0 - } - return nil, syscall.ENOENT -} - -func (d *Dir) Create(ctx context.Context, name string, flags uint32, mode uint32, out *fuse.EntryOut) (*fs.Inode, fs.FileHandle, uint32, syscall.Errno) { - log.Printf("Create called for %s", name) - meta := &FileMetadata{ - Inode: uint64(currentBlock + 3), - Filename: name, - Size: 0, - Block: currentBlock, - } - fileTable[name] = meta - currentBlock++ - - file := &File{metadata: meta} - child := d.NewPersistentInode(ctx, file, fs.StableAttr{ - Mode: fuse.S_IFREG, - Ino: meta.Inode, - }) - - if err := saveMetadata(); err != nil { - log.Printf("Failed to save metadata: %v", err) - } - - out.Ino = meta.Inode - out.Mode = fuse.S_IFREG | 0666 - out.Size = 0 - - return child, nil, 0, 0 -} - -type FS struct { - fs.Inode -} - -func (f *FS) OnAdd(ctx context.Context) { - dir := &Dir{} - ch := f.NewPersistentInode(ctx, dir, fs.StableAttr{ - Mode: fuse.S_IFDIR, - Ino: 1, - }) - f.AddChild("", ch, true) -} - -func (f *FS) Statfs(ctx context.Context, out *fuse.StatfsOut) syscall.Errno { - totalBlocks := deviceSize / blockSize - freeBlocks := totalBlocks - int64(len(fileTable)) - - out.Blocks = uint64(totalBlocks) - out.Bfree = uint64(freeBlocks) - out.Bavail = uint64(freeBlocks) - out.Files = uint64(len(fileTable)) - out.Ffree = uint64(freeBlocks) - out.Bsize = blockSize - out.NameLen = 255 - out.Frsize = blockSize - - return 0 -} - -func main() { - flag.Parse() - if flag.NArg() != 2 { - log.Println("Usage: MOUNTPOINT BLOCK_DEVICE") - os.Exit(2) - } - mountpoint := flag.Arg(0) - blockDevice := flag.Arg(1) - - err := openDevice(blockDevice) - if err != nil { - log.Fatalf("Failed to open device: %v", err) - } - defer device.Close() - - if err := loadMetadata(); err != nil { - log.Printf("Failed to load metadata: %v", err) - } - - root := &FS{} - opts := &fs.Options{ - MountOptions: fuse.MountOptions{ - FsName: "GoClusterFS", - Name: "goclusterfs", - AllowOther: true, - MaxReadAhead: 1 << 17, // 128KB - }, - } - - server, err := fs.Mount(mountpoint, root, opts) - if err != nil { - log.Println("Error mounting:", err) - os.Exit(1) - } - - log.Println("Filesystem mounted. Press Ctrl+C to unmount.") - server.Wait() -} From 1667dc76538f3f26c76d8adfe7a21215e52ad47c Mon Sep 17 00:00:00 2001 From: Matthew Mattox Date: Sat, 24 Oct 2026 03:45:51 -0500 Subject: [PATCH 2/4] docs: describe the v2 system and fix the README quick start CLAUDE.md described the deleted prototype. It now covers the real package map, the on-disk layout from cmd/mount, build and run commands, and current limitations. The README quick start used a binary name and flags that do not exist. It now uses make build output and the real goclusterfs-mount and goclusterfs-fsck flags. fsck takes the device as a positional argument. It also notes that fsck rejects volumes made by -format, because cmd/mount does not write a superblock. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 116 ++++++++++++------ README.md | 78 ++++++------ .../multi-task-execution-workflow.md | 20 +-- docs/development/task-execution-workflow.md | 35 +++--- 4 files changed, 148 insertions(+), 101 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3a651332..473436b9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,48 +4,94 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -GoClusterFS is a FUSE-based clustered filesystem written in Go. It mounts a block device and exposes it as a filesystem, designed for shared storage scenarios across cluster nodes. +GoClusterFS is a clustered FUSE filesystem written in Go. Several Linux nodes mount the same shared block device at the same time. Nodes coordinate through structures on the device itself: a node registry, CAS locks, and a write-ahead journal. All device I/O uses O_DIRECT, so no node trusts its own page cache. UDP multicast messages make cache invalidation faster, but correctness does not depend on them. -## Build and Run Commands +FUSE binding: `github.com/hanwen/go-fuse/v2`. Linux only. -```bash -# Build the binary -go build -o GoClusterFS . +## Build and Run -# Run (requires root or fuse group membership) -./GoClusterFS +```bash +make build # ./goclusterfs-mount and ./goclusterfs-fsck +go build ./... && go vet ./... +``` -# Example with a file-backed block device -dd if=/dev/zero of=VirtBlock.img bs=1M count=3000 # Create 3GB virtual block -./GoClusterFS /mnt/goclusterfs ./VirtBlock.img +Run against a file-backed image. The image must sit on a filesystem that supports O_DIRECT (not tmpfs). -# Unmount -fusermount -u /mnt/goclusterfs +```bash +truncate -s 1G disk.img +mkdir -p mnt +./goclusterfs-mount -device ./disk.img -mount ./mnt -format # first time only, wipes the volume +./goclusterfs-mount -device ./disk.img -mount ./mnt # later mounts +fusermount3 -u mnt # or Ctrl+C the mount process +./goclusterfs-fsck ./disk.img # device is a positional argument ``` -## Architecture - -### Storage Layout -- **Block size**: 1MB fixed blocks -- **Block 0**: Reserved for metadata (file table serialized with `gob`) -- **Blocks 1+**: File data (one block per file currently) - -### Core Types -- `FS`: Root filesystem implementing `fs.FS` and `Statfs` -- `Dir`: Root directory implementing `Attr`, `ReadDirAll`, `Lookup`, `Create` -- `File`: File node implementing `Attr`, `ReadAll`, `Write`, `Flush`, `Setxattr` -- `FileMetadata`: Persisted file info (inode, filename, size, block index) - -### File Locking -File locks are managed via extended attributes for cluster coordination: -- Set lock: `setfattr -n user.lock -v ` -- Release lock: `setfattr -n user.unlock -v ` - -### Current Limitations -- Single block per file (max 1MB file size) -- No directory hierarchy (flat namespace) -- No delete operation implemented -- Metadata not checksummed +`goclusterfs-mount` stays in the foreground until the filesystem is unmounted. `-format` formats and then mounts. It logs a lot of `[DEBUG]` lines even without `-debug`, which only turns on go-fuse request tracing. Flags and defaults: `./goclusterfs-mount -h`, `./goclusterfs-fsck -h`, [docs/API-CONFIG.md](docs/API-CONFIG.md). + +## Code Map + +| Path | What it does | +|------|--------------| +| `cmd/mount` | `goclusterfs-mount`: fixes the on-disk layout, runs journal recovery, wires all managers, mounts with go-fuse | +| `cmd/fsck` | `goclusterfs-fsck`: 8-phase checker with `-repair` and `-force` modes | +| `cmd/crctest` | Prints CRC32C test values | +| `internal/goclusterfs` | FUSE nodes (`FS` root, `Dir`, `File`) and every VFS operation | +| `internal/storage` | O_DIRECT device, 4 KB aligned buffers, CRC32C | +| `internal/superblock` | Superblock format (see limitations: `cmd/mount` does not write it) | +| `internal/bitmap` | Block allocation bitmap, CRC32C per 4 KB sector | +| `internal/inode` | Inode table, 256-byte inodes, CRC32C per sector | +| `internal/extent` | File block mapping, up to 2 extents inline in the inode | +| `internal/dir` | Directory entries | +| `internal/lock` | Distributed CAS locks stored on the device | +| `internal/node` | Node registry, heartbeats, failed-node detection | +| `internal/journal` | Write-ahead journal, local and cross-node recovery | +| `internal/cache` | Inode and extent caches, checked against on-disk generation counters | +| `internal/cache/broadcast` | UDP multicast/unicast cache invalidation, optional HMAC | +| `internal/refcount` | Per-block reference counts for copy-on-write | +| `internal/snapshot` | Snapshot registry and background refcount worker | +| `internal/sfb` | Small-file containers: 4/8/16/64 KB slots inside a 1 MB block | +| `internal/trim` | Batched `BLKDISCARD` for freed blocks | +| `internal/fsck` | The fsck phases | +| `internal/metrics` | Atomic counters, not used by `cmd/mount` yet | + +## On-Disk Layout + +`cmd/mount/main.go` hardcodes this layout. Data blocks are 1 MB. Metadata I/O uses 4 KB sectors. + +| Offset | Size | Region | +|--------|------|--------| +| 0 | 1 MB | Reserved for the superblock (not written today) | +| 1 MB | 1 MB | Block bitmap | +| 2 MB | 1 MB | Inode table: 4096 inodes of 256 bytes; root is inode 2 | +| 3 MB | 1 MB | Node registry | +| 4 MB | 1 MB | Lock records | +| 5 MB | 4 MB | Journal | +| 9 MB | 1 MB | Block refcounts | +| 10 MB | 1 MB | Snapshot registry | +| 11 MB | rest | Data blocks | + +The smallest device is 12 MB. + +## Snapshots and Clones + +Snapshots and clones work through extended attributes on a file (`internal/goclusterfs/fs.go`, `File.Setxattr`): + +- `setfattr -n user.snapshot -v ` creates a snapshot +- `getfattr -n user.snapshots ` lists snapshots +- `setfattr -n user.snapshot.delete -v ` or `setfattr -x user.snapshot. ` deletes one +- `setfattr -n user.clone -v / ` clones the file +- `setfattr -n user.snapshot.clone -v :/ ` clones from a snapshot + +Clone paths are absolute from the filesystem root, and clones can only go in the root directory. + +## Current Limitations + +- Linux only. Needs FUSE and a backing store that supports O_DIRECT. +- `cmd/mount` never writes a superblock, and `internal/superblock` describes a different layout from the one above. `goclusterfs-fsck` checks the superblock first, so it stops at phase 1 with `invalid superblock magic` on any volume made with `-format`. +- Every node uses the same 4 MB journal region at 5 MB. `cmd/mount` does not give each node its own journal slot. +- Each file holds at most 2 extents (inline in the inode). The overflow extent tree is being built. +- The inode count is fixed at 4096. +- No rename, symlinks, or hard links. ## Testing diff --git a/README.md b/README.md index 56d86cb7..ceb6cb34 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ A VMFS-like clustered filesystem written in Go. GoClusterFS enables multiple nod ## Requirements -- Go 1.21 or later +- Go 1.26 or later - Linux with FUSE support (`fusermount3`) - O_DIRECT-capable storage (not tmpfs) - Root or `fuse` group membership @@ -30,54 +30,50 @@ A VMFS-like clustered filesystem written in Go. GoClusterFS enables multiple nod ```bash git clone https://github.com/supporttools/GoClusterFS.git cd GoClusterFS -go build -o goclusterfs ./cmd/mount +make build ``` -### Create and Format a Block Device +This builds `goclusterfs-mount` and `goclusterfs-fsck` in the repo root. -```bash -# Create a file-backed block device (3GB example) -dd if=/dev/zero of=VirtBlock.img bs=1M count=3000 - -# Format the filesystem -./goclusterfs -format -device ./VirtBlock.img -``` +### Format and Mount -### Mount +Use a file as the block device. Keep it on a filesystem that supports O_DIRECT, not tmpfs. ```bash -# Create mount point -mkdir -p /mnt/goclusterfs +truncate -s 1G disk.img +mkdir -p mnt +./goclusterfs-mount -device ./disk.img -mount ./mnt -format > mount.log 2>&1 & +sleep 2 +``` -# Mount with default settings -./goclusterfs -device ./VirtBlock.img -mount /mnt/goclusterfs +`-format` wipes the device and then mounts it. The mount process keeps running until you unmount, and logs to `mount.log`. -# Mount with journaling and network broadcast (multi-node) -./goclusterfs -device ./VirtBlock.img -mount /mnt/goclusterfs \ - -journal -broadcast -mcast-group 239.192.74.75 +### Use It -# Unmount -fusermount -u /mnt/goclusterfs +```bash +echo "Hello, Cluster!" > mnt/hello.txt +cat mnt/hello.txt +df -h mnt ``` -### Verify +### Unmount ```bash -# Create a file -echo "Hello, Cluster!" > /mnt/goclusterfs/test.txt - -# Check filesystem stats -df -h /mnt/goclusterfs +fusermount3 -u mnt ``` +The mount process exits after the unmount. To mount the same image again, run the mount command without `-format`. + ## Command-Line Options +These are the `goclusterfs-mount` flags. Run `./goclusterfs-mount -h` for the full list. + | Flag | Default | Description | |------|---------|-------------| -| `-device` | (required) | Path to block device | -| `-mount` | (required) | Mount point directory | -| `-format` | `false` | Format the device (destroys data) | -| `-debug` | `false` | Enable debug logging | +| `-device` | (required) | Path to block device or image file | +| `-mount` | (required) | Mount point directory (must exist) | +| `-format` | `false` | Format the device, then mount it (destroys data) | +| `-debug` | `false` | Log every FUSE request | ### Cache Options @@ -126,13 +122,15 @@ For clustered deployments: 2. **Network**: Nodes should be on the same subnet for multicast invalidation 3. **Mount Command**: Use identical mount options across all nodes +Format the device once, from one node, with `-format`. Then mount it on every node without `-format`: + ```bash # Node 1 -./goclusterfs -device /dev/shared/lun0 -mount /mnt/cluster \ +./goclusterfs-mount -device /dev/shared/lun0 -mount /mnt/cluster \ -journal -broadcast -mcast-group 239.192.74.75 # Node 2 (same block device, same options) -./goclusterfs -device /dev/shared/lun0 -mount /mnt/cluster \ +./goclusterfs-mount -device /dev/shared/lun0 -mount /mnt/cluster \ -journal -broadcast -mcast-group 239.192.74.75 ``` @@ -146,19 +144,23 @@ For clustered deployments: ## Filesystem Check -Run fsck to verify or repair the filesystem: +Run fsck on an unmounted device. The device is a positional argument, and flags go before it: ```bash # Check only (read-only) -./goclusterfs-fsck -device ./VirtBlock.img +./goclusterfs-fsck ./disk.img # Check and repair -./goclusterfs-fsck -device ./VirtBlock.img -repair +./goclusterfs-fsck -repair ./disk.img -# Force check (ignore clean flag) -./goclusterfs-fsck -device ./VirtBlock.img -force +# Keep going past fatal errors (data recovery) +./goclusterfs-fsck -force ./disk.img ``` +Exit codes: `0` clean, `1` errors found, `2` usage error or fatal failure. + +**Known issue:** fsck does not work yet on volumes made with `goclusterfs-mount -format`. The mount tool does not write a superblock, so fsck stops at phase 1 with `invalid superblock magic` and exits with `2`. + ## Architecture GoClusterFS uses a layered architecture: @@ -166,7 +168,7 @@ GoClusterFS uses a layered architecture: ``` ┌─────────────────────────────────────────────────────┐ │ FUSE Layer │ -│ (bazil.org/fuse) │ +│ (hanwen/go-fuse v2) │ ├─────────────────────────────────────────────────────┤ │ VFS Operations │ │ (Dir, File, Attr, Read, Write, Lookup) │ diff --git a/docs/development/multi-task-execution-workflow.md b/docs/development/multi-task-execution-workflow.md index b61a8d69..68434686 100644 --- a/docs/development/multi-task-execution-workflow.md +++ b/docs/development/multi-task-execution-workflow.md @@ -231,7 +231,7 @@ Follow implementation guidelines from [Task Execution Workflow](./task-execution ### 4.3 Build Verification (BLOCKER) ```bash -go build -o GoClusterFS . +make build ``` **MUST PASS** - Zero errors. If fails, fix and retry. @@ -258,20 +258,20 @@ When task affects filesystem operations: ```bash # Create test environment -dd if=/dev/zero of=/tmp/test.img bs=1M count=100 -mkdir -p /tmp/testmount +truncate -s 100M test.img +mkdir -p testmount -# Mount and test -./GoClusterFS /tmp/testmount /tmp/test.img & +# Mount and test (the image must not be on tmpfs) +./goclusterfs-mount -device ./test.img -mount ./testmount -format > mount.log 2>&1 & sleep 2 # Verify operations -ls -la /tmp/testmount -echo "test" > /tmp/testmount/testfile -cat /tmp/testmount/testfile +ls -la testmount +echo "test" > testmount/testfile +cat testmount/testfile # Unmount -fusermount -u /tmp/testmount +fusermount3 -u testmount ``` ### 4.7 Task Completion @@ -397,7 +397,7 @@ Clear todo list for next batch | Phase | Gate | Command | Blocker | |-------|------|---------|---------| -| Build | Binary compiles | `go build -o GoClusterFS .` | YES | +| Build | Binary compiles | `make build` | YES | | Format | Code formatted | `gofmt -l .` | YES | | Test | All tests pass | `go test ./... -v` | YES | | FUSE | Mount/unmount works | Manual test | Conditional | diff --git a/docs/development/task-execution-workflow.md b/docs/development/task-execution-workflow.md index 0220c5d2..142c2dc2 100644 --- a/docs/development/task-execution-workflow.md +++ b/docs/development/task-execution-workflow.md @@ -15,7 +15,7 @@ The project uses PostgreSQL-backed TaskForge for persistent task management: ### Development Environment **Requirements:** -- Go 1.21+ (check with `go version`) +- Go 1.26+ (check with `go version`) - FUSE 3 libraries (`libfuse3-dev` on Debian/Ubuntu) - Linux kernel with FUSE support @@ -34,12 +34,11 @@ GoClusterFS is a **single repository** project: ``` GoClusterFS/ -├── main.go # FUSE mount entry point -├── internal/ -│ ├── block/ # Block device I/O, O_DIRECT -│ ├── journal/ # Write-ahead logging -│ ├── node/ # Cluster node registry -│ └── fs/ # FUSE filesystem handlers +├── cmd/ +│ ├── mount/ # goclusterfs-mount +│ └── fsck/ # goclusterfs-fsck +├── internal/ # See CLAUDE.md for the package map +├── tests/ # Integration, Docker and VM tests ├── docs/ # Documentation └── CLAUDE.md # Project coding standards ``` @@ -86,7 +85,7 @@ Clear summary aligned with project architecture #### Design Approach Technical strategy following established patterns: - Block-level operations (1MB blocks) -- Metadata handling (gob encoding in block 0) +- On-disk layout as defined in `cmd/mount/main.go` - FUSE handler patterns - Thread-safe concurrent access @@ -145,7 +144,7 @@ Implement the approved design with strict adherence to: #### Step 5.1: Build Verification (BLOCKER) ```bash -go build -o GoClusterFS . +make build ``` - **MUST PASS**: Zero compilation errors @@ -174,20 +173,20 @@ go test ./... -v ```bash # Create test environment -dd if=/dev/zero of=/tmp/test.img bs=1M count=100 -mkdir -p /tmp/testmount +truncate -s 100M test.img +mkdir -p testmount -# Mount and test -./GoClusterFS /tmp/testmount /tmp/test.img & +# Mount and test (the image must not be on tmpfs) +./goclusterfs-mount -device ./test.img -mount ./testmount -format > mount.log 2>&1 & sleep 2 # Verify basic operations -ls -la /tmp/testmount -echo "test" > /tmp/testmount/testfile -cat /tmp/testmount/testfile +ls -la testmount +echo "test" > testmount/testfile +cat testmount/testfile # Unmount -fusermount -u /tmp/testmount +fusermount3 -u testmount ``` ### 6. Task Completion @@ -295,7 +294,7 @@ Before marking task complete, verify: ▼ ┌─────────────────────────────────────────────────────────────┐ │ 5.1 Build Verification (BLOCKER) │ -│ go build -o GoClusterFS . │ +│ make build │ │ ❌ Failed → Fix → Retry │ └────────────────────────┬────────────────────────────────────┘ │ (passed) From 5503b19638edf837e279ed0443410adf36508c3c Mon Sep 17 00:00:00 2001 From: Matthew Mattox Date: Sat, 24 Oct 2026 04:23:19 -0500 Subject: [PATCH 3/4] docs: note SFB alignment failure and tmpfs O_DIRECT support Verified on Linux 7.0: tmpfs images work with O_DIRECT, and SFB container writes fail with an unaligned-buffer error. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 3 ++- README.md | 4 ++-- docs/development/multi-task-execution-workflow.md | 2 +- docs/development/task-execution-workflow.md | 2 +- 4 files changed, 6 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 473436b9..8ea7bde8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,7 +15,7 @@ make build # ./goclusterfs-mount and ./goclusterfs-fsck go build ./... && go vet ./... ``` -Run against a file-backed image. The image must sit on a filesystem that supports O_DIRECT (not tmpfs). +Run against a file-backed image. The image must sit on a filesystem that supports O_DIRECT (tmpfs only on Linux 6.6+). ```bash truncate -s 1G disk.img @@ -91,6 +91,7 @@ Clone paths are absolute from the filesystem root, and clones can only go in the - Every node uses the same 4 MB journal region at 5 MB. `cmd/mount` does not give each node its own journal slot. - Each file holds at most 2 extents (inline in the inode). The overflow extent tree is being built. - The inode count is fixed at 4096. +- SFB containers fail on real devices: `internal/sfb` writes buffers that are not 4 KB aligned, so `storage.WriteAt` rejects them and small files fall back to full 1 MB blocks. - No rename, symlinks, or hard links. ## Testing diff --git a/README.md b/README.md index ceb6cb34..a5d786dc 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ A VMFS-like clustered filesystem written in Go. GoClusterFS enables multiple nod - Go 1.26 or later - Linux with FUSE support (`fusermount3`) -- O_DIRECT-capable storage (not tmpfs) +- O_DIRECT-capable storage (tmpfs supports O_DIRECT only on Linux 6.6 and later) - Root or `fuse` group membership - For multi-node: Shared block device (SAN, iSCSI, NVMe-oF, etc.) @@ -37,7 +37,7 @@ This builds `goclusterfs-mount` and `goclusterfs-fsck` in the repo root. ### Format and Mount -Use a file as the block device. Keep it on a filesystem that supports O_DIRECT, not tmpfs. +Use a file as the block device. Keep it on a filesystem that supports O_DIRECT. ```bash truncate -s 1G disk.img diff --git a/docs/development/multi-task-execution-workflow.md b/docs/development/multi-task-execution-workflow.md index 68434686..a1811760 100644 --- a/docs/development/multi-task-execution-workflow.md +++ b/docs/development/multi-task-execution-workflow.md @@ -261,7 +261,7 @@ When task affects filesystem operations: truncate -s 100M test.img mkdir -p testmount -# Mount and test (the image must not be on tmpfs) +# Mount and test ./goclusterfs-mount -device ./test.img -mount ./testmount -format > mount.log 2>&1 & sleep 2 diff --git a/docs/development/task-execution-workflow.md b/docs/development/task-execution-workflow.md index 142c2dc2..cc85a0ae 100644 --- a/docs/development/task-execution-workflow.md +++ b/docs/development/task-execution-workflow.md @@ -176,7 +176,7 @@ go test ./... -v truncate -s 100M test.img mkdir -p testmount -# Mount and test (the image must not be on tmpfs) +# Mount and test ./goclusterfs-mount -device ./test.img -mount ./testmount -format > mount.log 2>&1 & sleep 2 From 80a332e18b402ef3f844a4436cf1852265291073 Mon Sep 17 00:00:00 2001 From: Matthew Mattox Date: Sat, 24 Oct 2026 04:24:38 -0500 Subject: [PATCH 4/4] docs: add Commands Config table with make build The table exists only on local main and still names the deleted root binary. Adding it here with the real build command makes the later merge of local main resolve to this version. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 8ea7bde8..86750ec0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -156,3 +156,13 @@ For tests involving concurrent writes from multiple nodes, use the **pre-extensi 4. Verify data at each offset after writes complete This avoids TOCTOU races in the distributed locking system. + +## Commands Config + +| Setting | Value | +|---------|-------| +| TaskForge Project ID | 88 | +| Build command | `make build` | +| Test command | `go test ./... -v` | +| Lint command | `gofmt -l .` | +| Tech stack | Go (FUSE filesystem) |