Repository navigation
feat(api): add snapshot, clone and admin write endpoints - #57
Merged
Merged
Conversation
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>
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
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 callfsetxattron the file through the mount, so the kernel sends them toFile.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:
TestAPIWritesDuringFileIOruns 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.Server.Stopstops 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.TestMountExitsCleanlyDuringSnapshotssends SIGTERM while 4 clients keep snapshotting a 32 MB file, then checks the exit code, that nothing is left mounted, and fsck.RESOLVE_BENEATH | RESOLVE_NO_SYMLINKS | RESOLVE_NO_MAGICLINKS, and paths must also be absolute and clean. GoClusterFS has no symlinks, so the symlink test ininternal/fileopsruns 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.-snapshots,-journalor-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()andtrim.Manager.Flush()run the existing periodic checkpoint and flush on demand. Clear-cache only offers "all", which iscache.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