diff --git a/.golangci.yml b/.golangci.yml index 333fc989..952a2132 100644 --- a/.golangci.yml +++ b/.golangci.yml @@ -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" diff --git a/CLAUDE.md b/CLAUDE.md index 12f2e814..16b3f3dd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 | @@ -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. @@ -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) | diff --git a/README.md b/README.md index 7e4c7d52..7f3b05ce 100644 --- a/README.md +++ b/README.md @@ -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