Skip to content
Merged
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
3 changes: 0 additions & 3 deletions .golangci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,6 @@ linters:
exclusions:
# Known findings as of 2026-10-24 in code other open PRs are changing; delete each rule once fixed.
rules:
- path: ^main\.go$
linters: [staticcheck]
text: "SA1019: os\\.SEEK_"
- path: ^internal/goclusterfs/fs\.go$
linters: [unused]
text: "errRetryCreate|field sb is unused"
Expand Down
7 changes: 3 additions & 4 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ fusermount3 -u mnt # or Ctrl+C the mo
| `internal/superblock` | Superblock format and the on-disk layout; `-format` writes it, mount reads 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/extent` | File block mapping: 2 extents inline in the inode, the rest in an on-disk overflow tree |
| `internal/dir` | Directory entries |
| `internal/lock` | Distributed CAS locks stored on the device |
| `internal/node` | Node registry, heartbeats, failed-node detection |
Expand Down Expand Up @@ -89,7 +89,6 @@ Clone paths are absolute from the filesystem root, and clones can only go in the
- Linux only. Needs FUSE and a backing store that supports O_DIRECT.
- At most 64 nodes mount a volume at once, one per registry slot. Heartbeats compare wall clocks, so node clocks must agree within a few seconds.
- `goclusterfs-fsck` reports errors on healthy volumes: the superblock free block and inode counters are never updated after format, and phases 5 and 7 expect refcount and snapshot sector checksums the runtime does not write.
- 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 is disabled: writes never allocate SFB slots, so every file uses full 1 MB blocks. `internal/sfb` container I/O is broken (unaligned header buffers, no data offset) and stays until it is fixed or removed.
- No rename, symlinks, or hard links.
Expand Down Expand Up @@ -163,6 +162,6 @@ This avoids TOCTOU races in the distributed locking system.
|---------|-------|
| TaskForge Project ID | 88 |
| Build command | `make build` |
| Test command | `go test ./... -v` |
| Lint command | `gofmt -l .` |
| Test command | `make test-unit` |
| Lint command | `make lint` |
| Tech stack | Go (FUSE filesystem) |
11 changes: 11 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,17 @@ A VMFS-like clustered filesystem written in Go. GoClusterFS enables multiple nod
- For multi-node: Shared block device (SAN, iSCSI, NVMe-oF, etc.)
- A device of at least 264 MB: the layout reserves 256 MB for 64 node journals of 4 MB

## Limits and Status

- **Linux only.** GoClusterFS needs FUSE and O_DIRECT.
- **Every file with data uses at least one full 1 MB block.** The block size is 1 MB, and small-file packing (SFB) is disabled since [#12](https://github.com/SupportTools/GoClusterFS/pull/12), so `-sfb` has no effect.
- **Name lookups are slow.** Each lookup reads the whole directory from disk and scans it entry by entry. In one test on a single node, a lookup took about 25 ms, and `ls -l` on a 1,000-file directory took about 47 seconds.
- **On-disk format version 2** since [#15](https://github.com/SupportTools/GoClusterFS/pull/15). Mount refuses images formatted by earlier builds. Copy the data off with the old build, reformat, and copy it back.
- **Upgrade all nodes at once.** Unmount on every node, upgrade, then mount again. Mixing old and new binaries on one device can serve stale data or make files unreadable. See the upgrade notes in [CHANGELOG.md](CHANGELOG.md).
- **Snapshots and clones are experimental.** Before you mount an image that has snapshots or clones with a newer build, read the upgrade notes in [CHANGELOG.md](CHANGELOG.md). They say whether to run `goclusterfs-fsck` first.
- **fsck is experimental.** It reports errors on healthy volumes. See [Filesystem Check](#filesystem-check).
- **Cluster safety limits.** Node clocks, node stalls, and storage timeouts have hard limits. Read [Node Requirements](docs/OPERATIONS.md#node-requirements) and [Distributed Lock Limits](docs/OPERATIONS.md#distributed-lock-limits) before you run more than one node.

## Quick Start

### Build
Expand Down
Loading