Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
49 commits
Select commit Hold shift + click to select a range
6d28e06
feat(api): create internal/api package structure
mattmattox Dec 31, 2025
7daedbe
feat(api): implement route registration with groups
mattmattox Dec 31, 2025
8d7ecae
feat(api): implement middleware (auth, CORS, logging)
mattmattox Dec 31, 2025
3b24cce
feat(api): define comprehensive JSON request/response types
mattmattox Dec 31, 2025
215587b
feat(api): implement /health endpoint with component health checks
mattmattox Dec 31, 2025
098f467
feat(api): implement /api/v1/status endpoint with version and capacit…
mattmattox Dec 31, 2025
a247e98
feat(api): integrate API server into mount command
mattmattox Dec 31, 2025
dd68b18
feat(api): add CLI flags for API server configuration
mattmattox Dec 31, 2025
68450f4
feat(fs): add SnapshotRegistry() accessor for API endpoints
mattmattox Dec 31, 2025
760ffe5
feat(stats): create internal/stats package structure
mattmattox Dec 31, 2025
3e619d7
feat(stats): add TrimStats, SFBStats, and ClusterInfo types
mattmattox Dec 31, 2025
707e96f
feat(api): implement stats endpoints for cache, journal, trim, lock, …
mattmattox Dec 31, 2025
f5beb8c
style(api): gofmt the API and stats code
mattmattox Nov 10, 2026
a8146bf
fix(api): bind to loopback by default and refuse remote access withou…
mattmattox Nov 10, 2026
33b0bdc
fix(mount): warn at startup when broadcast runs without a secret
mattmattox Nov 10, 2026
4c94506
fix(api): read the build version from internal/version
mattmattox Nov 10, 2026
f1bbcf1
docs: document the HTTP API flags, loopback default and new warnings
mattmattox Nov 10, 2026
79c2ee5
test(stats): cover the filesystem provider
mattmattox Nov 10, 2026
e33a284
feat(api): add per-client rate limiting
mattmattox Dec 31, 2025
9688629
feat(api): serve Prometheus metrics on /metrics
mattmattox Dec 31, 2025
a8ce03c
feat(api): add /api/v1/cluster status, nodes and locks endpoints
mattmattox Dec 31, 2025
5eb160f
feat(gfsctl): add a CLI client for the HTTP API
mattmattox Dec 31, 2025
ab1feb3
feat(web): add a React dashboard for the HTTP API
mattmattox Jan 2, 2026
f58a6d3
fix(gfsctl): read the build version from internal/version
mattmattox Nov 10, 2026
e3619d7
docs: describe gfsctl, the dashboard and the new API endpoints
mattmattox Nov 10, 2026
e41d6c2
fix(api): use the collectors package for Go and process metrics
mattmattox Nov 10, 2026
78c425c
test(api): create the image file before sizing it
mattmattox Nov 10, 2026
5757ec2
Merge branch 'claude/land-api-work-c8b883' into claude/land-api-work-…
mattmattox Nov 10, 2026
76d66a8
fix(mount): skip API shutdown when the API never started
mattmattox Nov 10, 2026
e63e7f1
Merge branch 'claude/land-api-work-c8b883' into claude/land-api-work-…
mattmattox Nov 10, 2026
cbbcc4f
Merge remote-tracking branch 'origin/main' into claude/land-api-work-…
mattmattox Nov 10, 2026
69fc90b
Merge remote-tracking branch 'origin/claude/land-api-work-c8b883' int…
mattmattox Nov 10, 2026
5ad2809
Merge origin/main (#48 squash) into claude/land-api-work-uncommitted
mattmattox Nov 10, 2026
db94bf8
Merge remote-tracking branch 'origin/main' into claude/land-api-work-…
mattmattox Nov 10, 2026
2505935
refactor: move gfsctl, the dashboard and cluster endpoints to their o…
mattmattox Nov 10, 2026
548d0d9
feat: restore gfsctl, the dashboard and cluster endpoints
mattmattox Nov 10, 2026
8a1c408
fix(api): key the rate limiter on the connection and stop its cleanup
mattmattox Nov 10, 2026
673b055
feat(mount): add -api-rate-limit
mattmattox Nov 10, 2026
4f8b44e
docs: document -api-rate-limit and the Prometheus metrics
mattmattox Nov 10, 2026
e083900
fix(api): bound the rate limiter's memory and tighten its edges
mattmattox Nov 10, 2026
5382141
fix(mount): stop the rate limiter when the API fails to start
mattmattox Nov 10, 2026
6fa8c38
docs: describe the rate limiter's exempt paths, /64 grouping and clie…
mattmattox Nov 10, 2026
0232b2b
docs: say plainly how long a full rate limiter refuses new clients
mattmattox Nov 10, 2026
2094c0c
test(api): make the rate-limit burst test immune to slow hosts
mattmattox Nov 10, 2026
6910fbd
Merge commit '2094c0c' into claude/api-wip
mattmattox Nov 10, 2026
93f581c
Merge origin/main (#49 squash) into claude/api-wip
mattmattox Nov 10, 2026
ba0c4b6
docs: trim the restored CHANGELOG line to what this PR adds
mattmattox Nov 10, 2026
69173e5
ci: trigger checks after retargeting to main
mattmattox Nov 10, 2026
ecd13ce
Merge remote-tracking branch 'origin/main' into claude/api-wip
mattmattox Nov 10, 2026
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
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -29,3 +29,4 @@ tests/vm/runtime/
tests/vm/results/
/fsck
/dist/
/gfsctl
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
- HTTP API in `goclusterfs-mount` (`-api`, on by default): `/health`, `/metrics`, `/api/v1/status` and `/api/v1/stats/...`. It listens on `127.0.0.1:8080` (`-api-addr`). Mount refuses a non-loopback `-api-addr` or `-api-cors '*'` without `-api-token`, and checks the API flags before it opens the device. `/metrics` uses the Prometheus client library and adds Go runtime and process metrics. `-api-rate-limit` limits requests per client IP (off by default).
- `goclusterfs-mount -version`, which prints the same version string as `goclusterfs-fsck -version`. `/api/v1/status` reports it too.
- Mount logs a `WARNING` line at startup when `-broadcast` is on without `-broadcast-secret`.
- New `/api/v1/cluster/{status,nodes,locks}` endpoints. They answer 503 until mount gives the API a stats provider.
- Unfinished: `gfsctl`, a CLI client for the API, and a React dashboard in `web/dashboard`.
- Design, deployment, operations, and troubleshooting docs in `docs/`.
- Apache License 2.0.

Expand Down
2 changes: 2 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,8 @@ fusermount3 -u mnt # or Ctrl+C the mo
| `internal/api` | HTTP API served by `cmd/mount`: `/health`, `/metrics`, `/api/v1/status`, `/api/v1/stats/...`; loopback only unless `-api-token` is set |
| `internal/stats` | Stats types and collector behind `/api/v1/stats` |
| `internal/version` | Build version, set with `-ldflags -X` by `scripts/dist.sh` |
| `cmd/gfsctl` | `gfsctl`: CLI client for the HTTP API. `snapshot` and `admin` call endpoints the server does not have yet |
| `web/dashboard` | React dashboard for the HTTP API (`npm run dev`, proxies to `localhost:8080`). Not served by the mount |

## On-Disk Layout

Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,8 @@ With `-broadcast` on and no `-broadcast-secret`, mount logs a `WARNING` line at

The API only listens on this host by default. Mount refuses to start when `-api-addr` can be reached from other hosts and `-api-token` is empty. See [HTTP API Flags](docs/API-CONFIG.md#http-api-flags).

`cmd/gfsctl` is a CLI client for the API (`go build -o gfsctl ./cmd/gfsctl`, then `./gfsctl status`), and `web/dashboard` is a web dashboard for it. Both are unfinished: their snapshot and admin actions call endpoints the API does not have yet.

## Multi-Node Setup

For clustered deployments:
Expand Down
176 changes: 176 additions & 0 deletions cmd/gfsctl/client/api.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,176 @@
package client

import (
"context"
)

// Health fetches the health status from the API.
func (c *Client) Health(ctx context.Context) (*HealthResponse, error) {
var resp HealthResponse
if err := c.Get(ctx, "/health", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// Status fetches the filesystem status from the API.
func (c *Client) Status(ctx context.Context) (*StatusResponse, error) {
var resp StatusResponse
if err := c.Get(ctx, "/api/v1/status", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// StatsOverview fetches the stats overview from the API.
func (c *Client) StatsOverview(ctx context.Context) (*StatsOverviewResponse, error) {
var resp StatsOverviewResponse
if err := c.Get(ctx, "/api/v1/stats", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// CacheStats fetches cache statistics from the API.
func (c *Client) CacheStats(ctx context.Context) (*CacheStatsResponse, error) {
var resp CacheStatsResponse
if err := c.Get(ctx, "/api/v1/stats/cache", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// JournalStats fetches journal statistics from the API.
func (c *Client) JournalStats(ctx context.Context) (*JournalStatsResponse, error) {
var resp JournalStatsResponse
if err := c.Get(ctx, "/api/v1/stats/journal", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// TrimStats fetches TRIM statistics from the API.
func (c *Client) TrimStats(ctx context.Context) (*TrimStatsResponse, error) {
var resp TrimStatsResponse
if err := c.Get(ctx, "/api/v1/stats/trim", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// LockStats fetches lock statistics from the API.
func (c *Client) LockStats(ctx context.Context) (*LockStatsResponse, error) {
var resp LockStatsResponse
if err := c.Get(ctx, "/api/v1/stats/lock", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// SFBStats fetches SFB (Sub-File Block) statistics from the API.
func (c *Client) SFBStats(ctx context.Context) (*SFBStatsResponse, error) {
var resp SFBStatsResponse
if err := c.Get(ctx, "/api/v1/stats/sfb", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// AllStats fetches all statistics from the API.
func (c *Client) AllStats(ctx context.Context) (*AllStatsResponse, error) {
var resp AllStatsResponse
if err := c.Get(ctx, "/api/v1/stats/all", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// ClusterStatus fetches cluster status from the API.
func (c *Client) ClusterStatus(ctx context.Context) (*ClusterInfoResponse, error) {
var resp ClusterInfoResponse
if err := c.Get(ctx, "/api/v1/cluster/status", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// ClusterNodes fetches cluster node information from the API.
func (c *Client) ClusterNodes(ctx context.Context) (*ClusterNodesResponse, error) {
var resp ClusterNodesResponse
if err := c.Get(ctx, "/api/v1/cluster/nodes", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// ClusterLocks fetches distributed lock information from the API.
func (c *Client) ClusterLocks(ctx context.Context) (*ClusterLocksResponse, error) {
var resp ClusterLocksResponse
if err := c.Get(ctx, "/api/v1/cluster/locks", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// SnapshotList lists all snapshots.
func (c *Client) SnapshotList(ctx context.Context) (*SnapshotListResponse, error) {
var resp SnapshotListResponse
if err := c.Get(ctx, "/api/v1/snapshots", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// SnapshotInfo gets information about a specific snapshot.
func (c *Client) SnapshotInfo(ctx context.Context, id string) (*SnapshotInfo, error) {
var resp SnapshotInfo
if err := c.Get(ctx, "/api/v1/snapshots/"+id, &resp); err != nil {
return nil, err
}
return &resp, nil
}

// SnapshotCreate creates a new snapshot.
func (c *Client) SnapshotCreate(ctx context.Context, req *SnapshotCreateRequest) (*SnapshotCreateResponse, error) {
var resp SnapshotCreateResponse
if err := c.Post(ctx, "/api/v1/snapshots", req, &resp); err != nil {
return nil, err
}
return &resp, nil
}

// SnapshotDelete deletes a snapshot.
func (c *Client) SnapshotDelete(ctx context.Context, id string) (*SnapshotDeleteResponse, error) {
var resp SnapshotDeleteResponse
if err := c.Delete(ctx, "/api/v1/snapshots/"+id, &resp); err != nil {
return nil, err
}
return &resp, nil
}

// AdminFlushJournal flushes the journal to disk.
func (c *Client) AdminFlushJournal(ctx context.Context, req *FlushJournalRequest) (*AdminOperationResponse, error) {
var resp AdminOperationResponse
if err := c.Post(ctx, "/api/v1/admin/flush-journal", req, &resp); err != nil {
return nil, err
}
return &resp, nil
}

// AdminClearCache clears the specified cache.
func (c *Client) AdminClearCache(ctx context.Context, req *ClearCacheRequest) (*AdminOperationResponse, error) {
var resp AdminOperationResponse
if err := c.Post(ctx, "/api/v1/admin/clear-cache", req, &resp); err != nil {
return nil, err
}
return &resp, nil
}

// AdminForceTrim forces a TRIM operation.
func (c *Client) AdminForceTrim(ctx context.Context, req *ForceTrimRequest) (*AdminOperationResponse, error) {
var resp AdminOperationResponse
if err := c.Post(ctx, "/api/v1/admin/force-trim", req, &resp); err != nil {
return nil, err
}
return &resp, nil
}
Loading
Loading