Skip to content

feat(api): add snapshot, clone and admin write endpoints - #57

Merged
mattmattox merged 20 commits into
mainfrom
claude/api-writes
Nov 10, 2026
Merged

mattmattox merged 20 commits into
mainfrom
claude/api-writes

Conversation

@mattmattox

Copy link
Copy Markdown
Contributor

Second of the three PRs that replace draft #52: the API's write endpoints, built to the plan the PM approved. Endpoints, request bodies and status codes are in API-CONFIG.md, under "HTTP API Write Endpoints".

Same path as setfattr. Snapshot and clone requests call fsetxattr on the file through the mount, so the kernel sends them to File.Setxattr, with the same inode lock and the same detached context the CLI gets. The PR adds no new FS code for snapshots. Listing reads the snapshot registry. Snapshots are per-file and named by path. There's no description field, because the FS doesn't store one.

Checks the PM asked for:

  • Self-mount syscalls: go-fuse runs 2-16 reader goroutines (GOMAXPROCS) and isn't single-threaded. The handler makes the syscall from its own HTTP goroutine, so it can't block the FUSE reader that serves it. No FS lock is held across it, because fileops only touches the FS through the kernel. TestAPIWritesDuringFileIO runs snapshot, clone and delete requests while goroutines write and read the same files. It checks every 4 KB chunk of every clone, the final contents, and a clean fsck.
  • Shutdown: Server.Stop stops taking requests, then waits for writes in flight even past the 10 s HTTP shutdown timeout, and mount unmounts only after that. The mount root is opened per request, because a descriptor held open would make unmount fail with EBUSY. TestMountExitsCleanlyDuringSnapshots sends SIGTERM while 4 clients keep snapshotting a 32 MB file, then checks the exit code, that nothing is left mounted, and fsck.
  • Path escape: openat2 runs under the mount root with RESOLVE_BENEATH | RESOLVE_NO_SYMLINKS | RESOLVE_NO_MAGICLINKS, and paths must also be absolute and clean. GoClusterFS has no symlinks, so the symlink test in internal/fileops runs against a temp directory. It covers a link to a file outside the root, a link to a directory outside it, and a link inside the root.
  • CORS: unchanged, GET/HEAD/OPTIONS only.
  • ENOTSUP: answers 409, and so does a feature turned off by -snapshots, -journal or -trim. Documented.

Auth: every write needs -api-token, even on loopback. Without one, writes answer 403 and mount logs that they're off. Each write is logged at INFO with the client, action, arguments and result.

New journal.Checkpoint() and trim.Manager.Flush() run the existing periodic checkpoint and flush on demand. Clear-cache only offers "all", which is cache.Manager.Clear().

Results: golangci-lint (linux) 0 issues, tidy, gofmt, parity, and the API unit tests here. The fileops, journal and trim unit tests and the four new integration tests need Linux, so GitHub CI is their gate.

🤖 Generated with Claude Code

mattmattox and others added 17 commits November 10, 2026 16:21
Checkpoint is the periodic checkpoint, run now and with its error and
result returned. Flush runs the TRIM flush now and returns how many
blocks it took; it still goes through the free guard.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
GET/POST /api/v1/snapshots, DELETE /api/v1/snapshots/{name},
POST /api/v1/snapshots/{name}/clone, POST /api/v1/clones and
POST /api/v1/admin/{flush-journal,force-trim,clear-cache}.
- Writes need -api-token even on loopback, and answer 403 without one.
- Bodies are strict JSON, at most 64 KB.
- Each write is logged at INFO with client, action, arguments and result.
- Snapshot and clone handlers get a 10-minute write deadline.
- Stop waits for writes in flight after the HTTP shutdown, so mount
  never unmounts under a running request.
- Errno maps to 400/404/409/507/500; a feature turned off by flag is 409.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each request opens the file with openat2 under the mount root
(RESOLVE_BENEATH, NO_SYMLINKS, NO_MAGICLINKS), checks that it is a
regular file, and calls fsetxattr with the same attribute setfattr
would. The root is opened per request, because a descriptor held open
would make unmount fail with EBUSY. Listing reads the snapshot registry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mount gives the API a fileops service on the mount point and an admin
service over the journal, TRIM and cache managers, and logs when the
write endpoints are off because -api-token is empty.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Lifecycle: snapshot, list, clone from snapshot, clone, delete, the
  refusals, and that getxattr sees the API's snapshot.
- Writes refused without a token.
- Snapshot, clone and delete requests while goroutines write and read
  the same files: every 4 KB chunk in every clone is whole, files end at
  their last version, and fsck is clean.
- SIGTERM while snapshot requests run: mount exits 0 within 60 s,
  nothing is left mounted, and fsck is clean.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts:
#	docs/API-CONFIG.md
#	internal/trim/trim_test.go
#	tests/test-manifest.yaml
Review of #57: -api-token was the only way to pass the token, so it sat
in /proc/<pid>/cmdline, and any local user could read it and use API
writes on a mount they cannot open. Now:
- -api-token-file refuses a file group or others can read.
- GOCLUSTERFS_API_TOKEN can carry it instead.
- Setting more than one source is an error.
- -api-token still works but logs a WARNING.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…hots

- POST is CORS-safelisted, so a page on an allowed origin holding the
  token could POST. Preflights for anything but GET and HEAD now fail,
  and a write whose Origin is another site gets 403.
- GET /api/v1/snapshots needs the token like writes, because it reads
  registry data the caller may not be able to see through the mount.
- Snapshot names come from the escaped path, so names with / can be
  deleted. DELETE gets the long write deadline.
- Too-large bodies are 413, ENOSYS is 501, an unmounted filesystem is 503.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…locking

If FUSE has exited, the mount point is a plain directory and setxattr
would set a host xattr and report success; the root must be
FUSE_SUPER_MAGIC. RESOLVE_NO_XDEV keeps paths on that filesystem, and
O_NONBLOCK|O_NOCTTY keeps a FIFO or tty from hanging the open.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Flush returns the blocks it handed to the discard path; the free guard
can still skip some, and the admin message now says so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Also corrects the CORS sentence, documents 413, 501 and 503, and
recommends a TLS proxy or SSH tunnel for remote access.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The 6446322 merge left a bare ======= line, which made the manifest
invalid YAML, and shortened one section separator.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The token file must belong to the mount's user or root, must be at most
4 KB rather than silently cut, and is opened O_NONBLOCK so a FIFO at
that path cannot block startup. GOCLUSTERFS_API_TOKEN is trimmed like
the file, and a whitespace-only value is an error.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Any FUSE filesystem passed the magic check, for example another one
mounted over the mount point after ours exits. New records the mount's
st_dev and every request compares it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
mattmattox and others added 3 commits November 10, 2026 17:02
ErrSnapshotExists was defined and mapped to EEXIST but never returned,
so a second user.snapshot with a taken name added a duplicate. Delete
and clone look snapshots up by name with GetByName, which then picked
either one. Names are global, so Create now refuses a taken name in the
same pass that finds a free slot, under the registry's cluster lock.
Found by TestAPISnapshotLifecycle in #57.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts:
#	CHANGELOG.md
#	tests/test-manifest.yaml
Delete marks the snapshot deleting and queues the drop, so the list can
still show it right after DELETE returns, as CI did. The lifecycle test
polls for up to 15 s, and the docs say delete finishes in the background.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mattmattox
mattmattox merged commit 49e4265 into main Nov 10, 2026
10 checks passed
mattmattox added a commit that referenced this pull request Nov 12, 2026
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
mattmattox added a commit that referenced this pull request Nov 12, 2026
* test: give each integration node its own API port

Every test node started the API on the default 127.0.0.1:8080. Only one
mount at a time could bind it, and on .68 an unrelated service holds it,
so a -short run logged about 150 "Failed to start API server" lines. Each
node now gets a free loopback port next to its broadcast ports.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test: keep the net import that #57's gfsctl test needs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* ci: run checks on main

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
mattmattox added a commit that referenced this pull request Nov 13, 2026
* fix(broadcast): count multicast failures in a row and retry after a pause

The failure counter never reset, so after 3 failed multicast sends in
total over a mount, a node sent invalidations only to unicast peers
until it unmounted. Now a successful send resets the count, and after
MaxMulticastFailures failures in a row the node sends only to unicast
peers for 30 seconds before it tries multicast again. The total stays
in TransportStats; /metrics does not export broadcast counters.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(journal): remove the unused FullThreshold setting

Nothing read it. A checkpoint already runs every 5 seconds and is
forced when a transaction does not fit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(mount): log that SFB is disabled and stop creating its unused manager

-sfb defaulted to true and logged "SFB: enabled", but nothing used the
SFB manager it created: writes never allocate slots, and reading,
migrating and freeing old slots does not go through it. Mount now logs
what is in effect and still accepts -sfb.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore: raise the integration test timeout and fix stale help text

make test-integration ran the full suite with a 5 minute timeout; it
takes about 15 minutes, so allow 30 and say so in make help.

goclusterfs-fsck -h said repair never frees blocks or deletes inodes,
which changed with #72 and #86, and the api package doc called the API
read-only, which changed with #57.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant