diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 4886ded0..b6b6108c 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -9,6 +9,7 @@ on: - .github/workflows/release.yml - scripts/dist.sh - internal/version/** + - cmd/gfsctl/** - go.mod workflow_dispatch: @@ -40,12 +41,15 @@ jobs: - name: Build archives run: scripts/dist.sh - - name: Check fsck reports the build version + - name: Check fsck and gfsctl report the build version run: | tar -xzf dist/goclusterfs_*_linux_amd64.tar.gz -C "$RUNNER_TEMP" out="$("$RUNNER_TEMP"/goclusterfs_*_linux_amd64/goclusterfs-fsck -version)" echo "$out" grep -qF "commit $(git rev-parse HEAD)" <<<"$out" + out="$("$RUNNER_TEMP"/goclusterfs_*_linux_amd64/gfsctl version)" + echo "$out" + grep -qF "$(git rev-parse HEAD)" <<<"$out" - name: List artifacts run: | diff --git a/.gitignore b/.gitignore index 2f2a6839..bf89786f 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ /goclusterfs /goclusterfs-mount /goclusterfs-fsck +/gfsctl /GoClusterFS /coverage.out diff --git a/CHANGELOG.md b/CHANGELOG.md index 8b1b0fd4..430d248f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -40,6 +40,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), - Release workflow: pushing a `v*` tag publishes a GitHub Release with `linux/amd64` and `linux/arm64` archives, checksums, and the matching `CHANGELOG.md` section. `scripts/dist.sh` builds the same archives locally. - `goclusterfs-fsck -version` prints the release version, commit, and commit date. - 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). +- `gfsctl`, a read-only CLI for the HTTP API: `status`, `health`, `stats`, `metrics`, with watch mode and JSON output. Release archives include it. - `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`. - Design, deployment, operations, and troubleshooting docs in `docs/`. diff --git a/CLAUDE.md b/CLAUDE.md index 712b94b3..f95e3493 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,7 +11,7 @@ FUSE binding: `github.com/hanwen/go-fuse/v2`. Linux only. ## Build and Run ```bash -make build # ./goclusterfs-mount and ./goclusterfs-fsck +make build # ./goclusterfs-mount, ./goclusterfs-fsck and ./gfsctl go build ./... && go vet ./... ``` @@ -35,6 +35,7 @@ fusermount3 -u mnt # or Ctrl+C the mo | `cmd/mount` | `goclusterfs-mount`: fixes the on-disk layout, runs journal recovery, wires all managers, mounts with go-fuse | | `cmd/fsck` | `goclusterfs-fsck`: 8-phase checker with `-repair` and `-force` modes | | `cmd/crctest` | Prints CRC32C test values | +| `cmd/gfsctl` | `gfsctl`: read-only CLI for the HTTP API (status, health, stats, metrics) | | `internal/goclusterfs` | FUSE nodes (`FS` root, `Dir`, `File`) and every VFS operation | | `internal/storage` | O_DIRECT device, 4 KB aligned buffers, CRC32C | | `internal/superblock` | Superblock format and the on-disk layout; `-format` writes it, mount reads it | diff --git a/Makefile b/Makefile index 883d9ba3..fa9adb46 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,7 @@ # GoClusterFS Makefile # Build and test automation for the distributed filesystem -.PHONY: build build-mount build-fsck test test-unit test-integration test-all test-parity test-multinode-docker docker-build-test docker-clean-test test-multinode-vm vm-clean clean fmt vet check-fuse check-qemu lint vuln help +.PHONY: build build-mount build-fsck build-gfsctl test test-unit test-integration test-all test-parity test-multinode-docker docker-build-test docker-clean-test test-multinode-vm vm-clean clean fmt vet check-fuse check-qemu lint vuln help # Go parameters GOCMD=go @@ -14,6 +14,7 @@ GOMOD=$(GOCMD) mod # Binary names MOUNT_BINARY=goclusterfs-mount FSCK_BINARY=goclusterfs-fsck +GFSCTL_BINARY=gfsctl GOLANGCI_LINT_VERSION=v2.15.0 GOVULNCHECK_VERSION=v1.9.0 @@ -23,7 +24,7 @@ COVER_PROFILE=coverage.out .DEFAULT_GOAL := help # Build all binaries -build: build-mount build-fsck +build: build-mount build-fsck build-gfsctl build-mount: @echo "Building $(MOUNT_BINARY)..." @@ -35,6 +36,11 @@ build-fsck: $(GOBUILD) -o $(FSCK_BINARY) ./cmd/fsck @echo "Built $(FSCK_BINARY) successfully" +build-gfsctl: + @echo "Building $(GFSCTL_BINARY)..." + $(GOBUILD) -o $(GFSCTL_BINARY) ./cmd/gfsctl + @echo "Built $(GFSCTL_BINARY) successfully" + # Unit tests (fast, no FUSE needed) test: test-unit @@ -167,7 +173,7 @@ vuln: # Utilities clean: @echo "Cleaning build artifacts..." - rm -f $(MOUNT_BINARY) $(FSCK_BINARY) $(COVER_PROFILE) + rm -f $(MOUNT_BINARY) $(FSCK_BINARY) $(GFSCTL_BINARY) $(COVER_PROFILE) rm -f *.img @echo "Clean complete" diff --git a/README.md b/README.md index 3a75df2b..892b3fd9 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ cd GoClusterFS make build ``` -This builds `goclusterfs-mount` and `goclusterfs-fsck` in the repo root. +This builds `goclusterfs-mount`, `goclusterfs-fsck` and `gfsctl` in the repo root. ### Format and Mount @@ -143,6 +143,31 @@ 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). +## gfsctl + +`gfsctl` reads a mount's HTTP API from the command line. It only reads; it changes nothing. `make build` builds it, and release archives include it. + +```bash +./gfsctl status # mount state, version, capacity +./gfsctl health # exits 1 when a component is unhealthy +./gfsctl stats # overview; also: cache, journal, trim, lock, sfb, cluster, all +./gfsctl metrics # Prometheus text from /metrics +./gfsctl status -w -i 5s # refresh every 5 s +./gfsctl stats all -o json # JSON for scripts +``` + +It connects to `localhost:8080` by default. Each setting comes from the first of: a flag, an environment variable, the config file (`gfsctl config path`; `gfsctl config init` writes a sample with mode 0600), then the default. + +| Flag | Environment | Default | +|------|-------------|---------| +| `--host` | `GFSCTL_HOST` | `localhost` | +| `--port` | `GFSCTL_PORT` | `8080` | +| `--token` | `GFSCTL_TOKEN` | (none) | +| `--output`, `-o` | `GFSCTL_OUTPUT` | `text` (or `json`) | +| `--timeout` | `GFSCTL_TIMEOUT` | `30s` | + +Use `GFSCTL_TOKEN` or the config file for the token: other local users can read `--token` with `ps`. Statistics answer 503 until mount feeds them to the API, and `gfsctl` prints that error. + ## Multi-Node Setup For clustered deployments: diff --git a/cmd/gfsctl/client/api.go b/cmd/gfsctl/client/api.go new file mode 100644 index 00000000..67b0be85 --- /dev/null +++ b/cmd/gfsctl/client/api.go @@ -0,0 +1,100 @@ +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 +} + +// ClusterInfo returns cluster membership from /api/v1/stats/cluster. +func (c *Client) ClusterInfo(ctx context.Context) (*ClusterInfoResponse, error) { + var resp ClusterInfoResponse + if err := c.Get(ctx, "/api/v1/stats/cluster", &resp); err != nil { + return nil, err + } + return &resp, nil +} + +// Metrics returns the Prometheus text from /metrics. +func (c *Client) Metrics(ctx context.Context) ([]byte, error) { + return c.GetRaw(ctx, "/metrics") +} diff --git a/cmd/gfsctl/client/client.go b/cmd/gfsctl/client/client.go new file mode 100644 index 00000000..c3042244 --- /dev/null +++ b/cmd/gfsctl/client/client.go @@ -0,0 +1,173 @@ +// Package client provides an HTTP client for the GoClusterFS API. +package client + +import ( + "context" + "encoding/json" + "fmt" + "io" + "net" + "net/http" + "strconv" + "strings" + "time" +) + +// Client is an HTTP client for the GoClusterFS API. +type Client struct { + host string + port int + baseURL string + token string + httpClient *http.Client +} + +// Option configures a Client. +type Option func(*Client) + +// WithHost sets the API server host name or IP address. +func WithHost(host string) Option { + return func(c *Client) { + c.host = host + } +} + +// WithPort sets the API server port. +func WithPort(port int) Option { + return func(c *Client) { + c.port = port + } +} + +// WithToken sets the Bearer token for authentication. +func WithToken(token string) Option { + return func(c *Client) { + c.token = token + } +} + +// WithTimeout sets the HTTP client timeout. +func WithTimeout(timeout time.Duration) Option { + return func(c *Client) { + c.httpClient.Timeout = timeout + } +} + +// New creates a new API client with the given options. +func New(opts ...Option) *Client { + c := &Client{ + host: "localhost", + port: 8080, + httpClient: &http.Client{ + Timeout: 30 * time.Second, + }, + } + for _, opt := range opts { + opt(c) + } + c.baseURL = "http://" + net.JoinHostPort(strings.Trim(c.host, "[]"), strconv.Itoa(c.port)) + return c +} + +// BaseURL returns the configured base URL. +func (c *Client) BaseURL() string { + return c.baseURL +} + +// doRequest performs an HTTP request and returns the response body. +func (c *Client) doRequest(ctx context.Context, method, path string) ([]byte, error) { + url := c.baseURL + path + + req, err := http.NewRequestWithContext(ctx, method, url, nil) + if err != nil { + return nil, fmt.Errorf("create request: %w", err) + } + + req.Header.Set("Accept", "application/json") + if c.token != "" { + req.Header.Set("Authorization", "Bearer "+c.token) + } + + resp, err := c.httpClient.Do(req) + if err != nil { + return nil, fmt.Errorf("request failed: %w", err) + } + defer resp.Body.Close() + + body, err := io.ReadAll(resp.Body) + if err != nil { + return nil, fmt.Errorf("read response: %w", err) + } + + if resp.StatusCode >= 400 { + var errResp ErrorResponse + if json.Unmarshal(body, &errResp) == nil && errResp.Error != "" { + return nil, &APIError{ + StatusCode: resp.StatusCode, + Message: errResp.Error, + Details: errResp.Details, + } + } + return nil, &APIError{ + StatusCode: resp.StatusCode, + Message: http.StatusText(resp.StatusCode), + } + } + + return body, nil +} + +// Get performs a GET request and decodes the JSON response into v. +func (c *Client) Get(ctx context.Context, path string, v interface{}) error { + body, err := c.doRequest(ctx, http.MethodGet, path) + if err != nil { + return err + } + if v != nil { + if err := json.Unmarshal(body, v); err != nil { + return fmt.Errorf("decode response: %w", err) + } + } + return nil +} + +// GetRaw performs a GET request and returns the raw response body. +func (c *Client) GetRaw(ctx context.Context, path string) ([]byte, error) { + return c.doRequest(ctx, http.MethodGet, path) +} + +// ErrorResponse represents an API error response. +type ErrorResponse struct { + Error string `json:"error"` + Code int `json:"code"` + Details string `json:"details,omitempty"` +} + +// APIError represents an error returned by the API. +type APIError struct { + StatusCode int + Message string + Details string +} + +func (e *APIError) Error() string { + if e.Details != "" { + return fmt.Sprintf("%s: %s", e.Message, e.Details) + } + return e.Message +} + +// IsNotFound returns true if the error is a 404 Not Found error. +func (e *APIError) IsNotFound() bool { + return e.StatusCode == http.StatusNotFound +} + +// IsUnauthorized returns true if the error is a 401 Unauthorized error. +func (e *APIError) IsUnauthorized() bool { + return e.StatusCode == http.StatusUnauthorized +} + +// IsServerError returns true if the error is a 5xx server error. +func (e *APIError) IsServerError() bool { + return e.StatusCode >= 500 +} diff --git a/cmd/gfsctl/client/client_test.go b/cmd/gfsctl/client/client_test.go new file mode 100644 index 00000000..75463bac --- /dev/null +++ b/cmd/gfsctl/client/client_test.go @@ -0,0 +1,52 @@ +package client + +import ( + "context" + "errors" + "net/http" + "net/http/httptest" + "testing" +) + +func TestBaseURL(t *testing.T) { + for _, tc := range []struct { + host string + port int + want string + }{ + {"localhost", 8080, "http://localhost:8080"}, + {"10.0.0.5", 9090, "http://10.0.0.5:9090"}, + {"::1", 8080, "http://[::1]:8080"}, + {"[::1]", 8080, "http://[::1]:8080"}, + } { + if got := New(WithHost(tc.host), WithPort(tc.port)).BaseURL(); got != tc.want { + t.Errorf("host %q port %d: BaseURL %q, want %q", tc.host, tc.port, got, tc.want) + } + } + if got := New(WithPort(9000), WithHost("h")).BaseURL(); got != "http://h:9000" { + t.Errorf("option order changed the URL: %q", got) + } +} + +func TestAPIErrorCarriesStatusAndDetails(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Header.Get("Authorization") != "Bearer secret" { + w.WriteHeader(http.StatusUnauthorized) + w.Write([]byte(`{"error":"invalid token","code":401}`)) + return + } + w.WriteHeader(http.StatusServiceUnavailable) + w.Write([]byte("not json")) + })) + defer srv.Close() + c := &Client{baseURL: srv.URL, httpClient: srv.Client()} + + var apiErr *APIError + if _, err := c.GetRaw(context.Background(), "/metrics"); !errors.As(err, &apiErr) || !apiErr.IsUnauthorized() || apiErr.Message != "invalid token" { + t.Fatalf("without token: %v", err) + } + c.token = "secret" + if _, err := c.GetRaw(context.Background(), "/metrics"); !errors.As(err, &apiErr) || !apiErr.IsServerError() || apiErr.Message != "Service Unavailable" { + t.Fatalf("non-JSON 503: %v", err) + } +} diff --git a/cmd/gfsctl/client/types.go b/cmd/gfsctl/client/types.go new file mode 100644 index 00000000..fb90a7c9 --- /dev/null +++ b/cmd/gfsctl/client/types.go @@ -0,0 +1,185 @@ +package client + +// HealthStatus represents the overall health state. +type HealthStatus string + +const ( + HealthStatusOK HealthStatus = "ok" + HealthStatusDegraded HealthStatus = "degraded" + HealthStatusUnhealthy HealthStatus = "unhealthy" +) + +// ComponentHealth represents the health of a single component. +type ComponentHealth struct { + Status HealthStatus `json:"status"` + Message string `json:"message,omitempty"` +} + +// HealthResponse is returned by GET /health. +type HealthResponse struct { + Status HealthStatus `json:"status"` + Checks map[string]ComponentHealth `json:"checks,omitempty"` +} + +// MountState represents the current mount state. +type MountState string + +const ( + MountStateUnmounted MountState = "unmounted" + MountStateMounting MountState = "mounting" + MountStateMounted MountState = "mounted" + MountStateUnmounting MountState = "unmounting" + MountStateError MountState = "error" +) + +// CapacityInfo provides storage capacity information. +type CapacityInfo struct { + TotalBytes uint64 `json:"total_bytes"` + UsedBytes uint64 `json:"used_bytes"` + FreeBytes uint64 `json:"free_bytes"` + UsedPercent float64 `json:"used_percent"` + TotalBlocks uint64 `json:"total_blocks"` + UsedBlocks uint64 `json:"used_blocks"` + FreeBlocks uint64 `json:"free_blocks"` + BlockSizeBytes uint64 `json:"block_size_bytes"` +} + +// ClusterInfo provides cluster membership information. +type ClusterInfo struct { + NodeID string `json:"node_id,omitempty"` + PeerCount int `json:"peer_count"` + Peers []string `json:"peers,omitempty"` + IsLeader bool `json:"is_leader,omitempty"` + LeaderID string `json:"leader_id,omitempty"` + ClusterState string `json:"cluster_state,omitempty"` +} + +// StatusResponse is returned by GET /api/v1/status. +type StatusResponse struct { + Status string `json:"status"` + Version string `json:"version"` + GitCommit string `json:"git_commit,omitempty"` + BuildTime string `json:"build_time,omitempty"` + GoVersion string `json:"go_version,omitempty"` + UptimeSeconds int64 `json:"uptime_seconds"` + MountPath string `json:"mount_path,omitempty"` + DevicePath string `json:"device_path,omitempty"` + MountState MountState `json:"mount_state,omitempty"` + ReadOnly bool `json:"read_only,omitempty"` + Capacity *CapacityInfo `json:"capacity,omitempty"` + Cluster *ClusterInfo `json:"cluster,omitempty"` +} + +// CacheHitRateInfo contains hit rate metrics for a cache type. +type CacheHitRateInfo struct { + Size int `json:"size"` + Hits uint64 `json:"hits"` + Misses uint64 `json:"misses"` + HitRate float64 `json:"hit_rate"` +} + +// CacheStatsResponse is returned by GET /api/v1/stats/cache. +type CacheStatsResponse struct { + InodeCache CacheHitRateInfo `json:"inode_cache"` + ExtentCache CacheHitRateInfo `json:"extent_cache"` + NegativeCache CacheHitRateInfo `json:"negative_cache"` + LockHintCache CacheHitRateInfo `json:"lock_hint_cache,omitempty"` +} + +// JournalStatsResponse is returned by GET /api/v1/stats/journal. +type JournalStatsResponse struct { + State string `json:"state"` + HeadOffset uint32 `json:"head_offset"` + TailOffset uint32 `json:"tail_offset"` + AvailableSpace uint32 `json:"available_space"` + ActiveTxnCount int `json:"active_txn_count"` + CommitCount uint64 `json:"commit_count"` + BytesWritten uint64 `json:"bytes_written"` + LastCheckpointSeq uint64 `json:"last_checkpoint_seq"` + BatchSyncCount uint64 `json:"batch_sync_count"` +} + +// TrimStatsResponse is returned by GET /api/v1/stats/trim. +type TrimStatsResponse struct { + TrimOperations uint64 `json:"trim_operations"` + TrimBytes uint64 `json:"trim_bytes"` + TrimBlocks uint64 `json:"trim_blocks"` + PendingTrimBlocks uint64 `json:"pending_trim_blocks,omitempty"` + LastTrimAt string `json:"last_trim_at,omitempty"` + TrimErrors uint64 `json:"trim_errors,omitempty"` + TrimEnabled bool `json:"trim_enabled"` + BatchSize int `json:"batch_size,omitempty"` +} + +// LockStatsResponse is returned by GET /api/v1/stats/lock. +type LockStatsResponse struct { + HintCacheHits uint64 `json:"hint_cache_hits"` + HintCacheMisses uint64 `json:"hint_cache_misses"` + HintCacheHitRate float64 `json:"hint_cache_hit_rate"` + ActiveLocks int `json:"active_locks,omitempty"` + PendingLocks int `json:"pending_locks,omitempty"` +} + +// SFBStatsResponse is returned by GET /api/v1/stats/sfb. +type SFBStatsResponse struct { + TotalBlocks uint64 `json:"total_blocks"` + AllocatedBlocks uint64 `json:"allocated_blocks"` + FreeBlocks uint64 `json:"free_blocks"` + AllocationPercent float64 `json:"allocation_percent"` + FragmentationRatio float64 `json:"fragmentation_ratio,omitempty"` + LargestFreeExtent uint64 `json:"largest_free_extent,omitempty"` + AllocationsTotal uint64 `json:"allocations_total"` + DeallocationsTotal uint64 `json:"deallocations_total"` + AllocationFailures uint64 `json:"allocation_failures,omitempty"` +} + +// ClusterPeerInfo contains information about a cluster peer node. +type ClusterPeerInfo struct { + NodeID string `json:"node_id"` + Address string `json:"address"` + State string `json:"state"` + LastSeen string `json:"last_seen,omitempty"` + Latency float64 `json:"latency_ms,omitempty"` +} + +// ClusterInfoResponse is returned by GET /api/v1/stats/cluster. +type ClusterInfoResponse struct { + NodeID string `json:"node_id"` + NodeAddress string `json:"node_address,omitempty"` + Role string `json:"role"` + State string `json:"state"` + ClusterSize int `json:"cluster_size"` + HealthyNodes int `json:"healthy_nodes"` + LeaderID string `json:"leader_id,omitempty"` + LastHeartbeatAt string `json:"last_heartbeat_at,omitempty"` + JoinedAt string `json:"joined_at,omitempty"` + Peers []ClusterPeerInfo `json:"peers,omitempty"` +} + +// AllStatsResponse is returned by GET /api/v1/stats/all. +type AllStatsResponse struct { + CollectedAt string `json:"collected_at"` + Cache *CacheStatsResponse `json:"cache,omitempty"` + Journal *JournalStatsResponse `json:"journal,omitempty"` + Trim *TrimStatsResponse `json:"trim,omitempty"` + Lock *LockStatsResponse `json:"lock,omitempty"` + SFB *SFBStatsResponse `json:"sfb,omitempty"` + Cluster *ClusterInfoResponse `json:"cluster,omitempty"` +} + +// StatsOverviewResponse is returned by GET /api/v1/stats. +type StatsOverviewResponse struct { + Cache *CacheStatsResponse `json:"cache,omitempty"` + Journal *JournalStatsResponse `json:"journal,omitempty"` + IO *IOStatsResponse `json:"io,omitempty"` +} + +// IOStatsResponse contains I/O operation statistics. +type IOStatsResponse struct { + ReadOps uint64 `json:"read_ops"` + WriteOps uint64 `json:"write_ops"` + BytesRead uint64 `json:"bytes_read"` + BytesWritten uint64 `json:"bytes_written"` + AvgReadLatUs float64 `json:"avg_read_latency_us"` + AvgWriteLatUs float64 `json:"avg_write_latency_us"` +} diff --git a/cmd/gfsctl/commands/commands_test.go b/cmd/gfsctl/commands/commands_test.go new file mode 100644 index 00000000..1e590174 --- /dev/null +++ b/cmd/gfsctl/commands/commands_test.go @@ -0,0 +1,286 @@ +package commands + +import ( + "bytes" + "encoding/json" + "net/http" + "net/http/httptest" + "net/url" + "os" + "path/filepath" + "reflect" + "strconv" + "strings" + "sync" + "testing" + + "github.com/spf13/cobra" + "github.com/spf13/pflag" + + "github.com/supporttools/GoClusterFS/internal/api" +) + +func TestMain(m *testing.M) { + dir, err := os.MkdirTemp("", "gfsctl-test") + if err != nil { + panic(err) + } + os.Setenv("XDG_CONFIG_HOME", dir) + for _, name := range []string{"GFSCTL_HOST", "GFSCTL_PORT", "GFSCTL_TOKEN", "GFSCTL_OUTPUT", "GFSCTL_TIMEOUT", "NO_COLOR"} { + os.Unsetenv(name) + } + code := m.Run() + os.RemoveAll(dir) + os.Exit(code) +} + +type fakeAPI struct { + host string + port string + mu sync.Mutex + tokens []string +} + +func (f *fakeAPI) lastToken() string { + f.mu.Lock() + defer f.mu.Unlock() + if len(f.tokens) == 0 { + return "" + } + return f.tokens[len(f.tokens)-1] +} + +// startFakeAPI serves routes: an int answers with that status, a string as text, anything else as JSON. +func startFakeAPI(t *testing.T, routes map[string]any) *fakeAPI { + t.Helper() + f := &fakeAPI{} + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + f.mu.Lock() + f.tokens = append(f.tokens, r.Header.Get("Authorization")) + f.mu.Unlock() + switch v := routes[r.URL.Path].(type) { + case nil: + http.NotFound(w, r) + case int: + w.WriteHeader(v) + json.NewEncoder(w).Encode(api.ErrorResponse{Error: "stats not available", Code: v, Details: "no stats provider configured"}) + case string: + w.Write([]byte(v)) + default: + json.NewEncoder(w).Encode(v) + } + })) + t.Cleanup(srv.Close) + u, err := url.Parse(srv.URL) + if err != nil { + t.Fatal(err) + } + f.host, f.port = u.Hostname(), u.Port() + return f +} + +func resetFlags(c *cobra.Command) { + reset := func(fl *pflag.Flag) { + fl.Value.Set(fl.DefValue) + fl.Changed = false + } + c.Flags().VisitAll(reset) + c.PersistentFlags().VisitAll(reset) + for _, sub := range c.Commands() { + resetFlags(sub) + } +} + +func run(t *testing.T, args ...string) (string, string, error) { + t.Helper() + resetFlags(rootCmd) + var stdout, stderr bytes.Buffer + rootCmd.SetOut(&stdout) + rootCmd.SetErr(&stderr) + rootCmd.SetArgs(args) + err := Execute() + return stdout.String(), stderr.String(), err +} + +func (f *fakeAPI) run(t *testing.T, args ...string) (string, string, error) { + t.Helper() + return run(t, append([]string{"--host", f.host, "--port", f.port}, args...)...) +} + +var sampleStatus = api.StatusResponse{ + Status: "ok", + Version: "1.2.3", + GitCommit: "abc123", + BuildTime: "2026-11-10T00:00:00Z", + GoVersion: "go1.26.0", + UptimeSeconds: 3661, + MountPath: "/mnt/cluster", + DevicePath: "/dev/sdb", + MountState: api.MountStateMounted, + Capacity: &api.CapacityInfo{ + TotalBytes: 1 << 30, UsedBytes: 1 << 29, FreeBytes: 1 << 29, UsedPercent: 50, + TotalBlocks: 1024, UsedBlocks: 512, FreeBlocks: 512, BlockSizeBytes: 1 << 20, + }, +} + +func TestStatusText(t *testing.T) { + f := startFakeAPI(t, map[string]any{"/api/v1/status": sampleStatus}) + out, _, err := f.run(t, "status") + if err != nil { + t.Fatal(err) + } + for _, want := range []string{"1.2.3", "/mnt/cluster", "1h 1m", "512.00 MB (50.0%)"} { + if !strings.Contains(out, want) { + t.Errorf("status output lacks %q:\n%s", want, out) + } + } + if strings.Contains(out, "\033[") { + t.Errorf("status output to a buffer has color codes:\n%q", out) + } +} + +// TestJSONMatchesServerTypes checks that every read command keeps every field the server sends. +func TestJSONMatchesServerTypes(t *testing.T) { + cache := api.CacheHitRateInfo{Size: 100, Hits: 90, Misses: 10, HitRate: 0.9} + cluster := &api.ClusterInfoResponse{ + NodeID: "n1", NodeAddress: "10.0.0.1", Role: "member", State: "active", ClusterSize: 2, HealthyNodes: 2, + Peers: []api.ClusterPeerInfo{{NodeID: "n2", Address: "10.0.0.2", State: "active", LastSeen: "now", Latency: 1.5}}, + } + cacheStats := &api.CacheStatsResponse{InodeCache: cache, ExtentCache: cache, NegativeCache: cache, LockHintCache: cache} + trim := &api.TrimStatsResponse{TrimOperations: 1, TrimBytes: 2, TrimBlocks: 3, PendingTrimBlocks: 4, LastTrimAt: "now", TrimErrors: 5, TrimEnabled: true, BatchSize: 6} + lock := &api.LockStatsResponse{HintCacheHits: 1, HintCacheMisses: 2, HintCacheHitRate: 0.5, ActiveLocks: 3, PendingLocks: 4} + sfb := &api.SFBStatsResponse{TotalBlocks: 1, AllocatedBlocks: 2, FreeBlocks: 3, AllocationPercent: 4.5, FragmentationRatio: 0.5, LargestFreeExtent: 6, AllocationsTotal: 7, DeallocationsTotal: 8, AllocationFailures: 9} + io := &api.IOStatsResponse{ReadOps: 1, WriteOps: 2, BytesRead: 3, BytesWritten: 4, AvgReadLatUs: 5.5, AvgWriteLatUs: 6.5} + journal := &api.JournalStatsResponse{State: "clean", HeadOffset: 1, TailOffset: 2, AvailableSpace: 3, ActiveTxnCount: 4, CommitCount: 5, BytesWritten: 6, LastCheckpointSeq: 7, BatchSyncCount: 8} + cases := []struct { + args []string + path string + value any + }{ + {[]string{"status"}, "/api/v1/status", &sampleStatus}, + {[]string{"health"}, "/health", &api.HealthResponse{Status: api.HealthStatusOK, Checks: map[string]api.ComponentHealth{"api": {Status: api.HealthStatusOK, Message: "fine"}}}}, + {[]string{"stats"}, "/api/v1/stats", &api.StatsOverviewResponse{Cache: cacheStats, Journal: journal, IO: io}}, + {[]string{"stats", "cache"}, "/api/v1/stats/cache", cacheStats}, + {[]string{"stats", "journal"}, "/api/v1/stats/journal", journal}, + {[]string{"stats", "trim"}, "/api/v1/stats/trim", trim}, + {[]string{"stats", "lock"}, "/api/v1/stats/lock", lock}, + {[]string{"stats", "sfb"}, "/api/v1/stats/sfb", sfb}, + {[]string{"stats", "cluster"}, "/api/v1/stats/cluster", cluster}, + {[]string{"stats", "all"}, "/api/v1/stats/all", &api.AllStatsResponse{CollectedAt: "now", Cache: cacheStats, Journal: journal, Trim: trim, Lock: lock, SFB: sfb, Cluster: cluster}}, + } + for _, tc := range cases { + f := startFakeAPI(t, map[string]any{tc.path: tc.value}) + out, _, err := f.run(t, append(tc.args, "-o", "json")...) + if err != nil { + t.Fatalf("%v: %v", tc.args, err) + } + got := reflect.New(reflect.TypeOf(tc.value).Elem()).Interface() + if err := json.Unmarshal([]byte(out), got); err != nil { + t.Fatalf("%v: decode output: %v\n%s", tc.args, err, out) + } + if !reflect.DeepEqual(got, tc.value) { + t.Errorf("%v dropped or changed server fields:\nserver: %+v\ngfsctl: %+v", tc.args, tc.value, got) + } + } +} + +func TestHealthFailsWhenUnhealthy(t *testing.T) { + f := startFakeAPI(t, map[string]any{"/health": api.HealthResponse{ + Status: api.HealthStatusUnhealthy, + Checks: map[string]api.ComponentHealth{"journal": {Status: api.HealthStatusUnhealthy, Message: "replay failed"}}, + }}) + out, stderr, err := f.run(t, "health") + if err == nil { + t.Fatal("health of an unhealthy mount returned no error") + } + if !strings.Contains(out, "replay failed") || !strings.Contains(stderr, "Error: filesystem is unhealthy") { + t.Errorf("stdout:\n%s\nstderr:\n%s", out, stderr) + } +} + +func TestErrorsArePrintedOnce(t *testing.T) { + f := startFakeAPI(t, map[string]any{"/api/v1/stats/cache": http.StatusServiceUnavailable}) + _, stderr, err := f.run(t, "stats", "cache") + if err == nil || strings.Count(stderr, "Error:") != 1 || !strings.Contains(stderr, "no stats provider configured") { + t.Errorf("err=%v stderr:\n%s", err, stderr) + } + _, stderr, err = f.run(t, "stats", "bogus") + if err == nil || !strings.Contains(stderr, "unknown component: bogus") { + t.Errorf("unknown component: err=%v stderr:\n%s", err, stderr) + } +} + +func TestMetricsPrintsText(t *testing.T) { + const text = "# TYPE goclusterfs_up gauge\ngoclusterfs_up 1\n" + f := startFakeAPI(t, map[string]any{"/metrics": text}) + out, _, err := f.run(t, "metrics") + if err != nil || out != text { + t.Fatalf("err=%v output=%q", err, out) + } +} + +func writeConfig(t *testing.T, content string) { + t.Helper() + path := filepath.Join(os.Getenv("XDG_CONFIG_HOME"), "gfsctl", "config.yaml") + if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, []byte(content), 0o600); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { os.Remove(path) }) +} + +func TestSettingsPrecedence(t *testing.T) { + f := startFakeAPI(t, map[string]any{"/metrics": "x\n"}) + + writeConfig(t, "host: "+f.host+"\nport: "+f.port+"\ntoken: from-file\n") + if _, _, err := run(t, "metrics"); err != nil || f.lastToken() != "Bearer from-file" { + t.Fatalf("config file: err=%v token=%q", err, f.lastToken()) + } + + t.Setenv("GFSCTL_TOKEN", "from-env") + if _, _, err := run(t, "metrics"); err != nil || f.lastToken() != "Bearer from-env" { + t.Fatalf("env over file: err=%v token=%q", err, f.lastToken()) + } + + if _, _, err := run(t, "--token", "from-flag", "metrics"); err != nil || f.lastToken() != "Bearer from-flag" { + t.Fatalf("flag over env: err=%v token=%q", err, f.lastToken()) + } + + writeConfig(t, "host: "+f.host+"\nport: 1\n") + t.Setenv("GFSCTL_PORT", f.port) + if _, _, err := run(t, "metrics"); err != nil { + t.Fatalf("GFSCTL_PORT over file: %v", err) + } +} + +func TestBadSettingsAreRefused(t *testing.T) { + for _, tc := range []struct { + env, value string + args []string + want string + }{ + {"GFSCTL_PORT", "abc", []string{"metrics"}, "GFSCTL_PORT"}, + {"GFSCTL_TIMEOUT", "soon", []string{"metrics"}, "GFSCTL_TIMEOUT"}, + {"", "", []string{"-o", "yaml", "metrics"}, "unknown output format"}, + } { + if tc.env != "" { + t.Setenv(tc.env, tc.value) + } + _, stderr, err := run(t, tc.args...) + if err == nil || !strings.Contains(stderr, tc.want) { + t.Errorf("%s=%q %v: err=%v stderr=%q", tc.env, tc.value, tc.args, err, stderr) + } + if tc.env != "" { + os.Unsetenv(tc.env) + } + } +} + +func TestVersionNeedsNoServer(t *testing.T) { + out, _, err := run(t, "--port", strconv.Itoa(1), "version") + if err != nil || !strings.HasPrefix(out, "gfsctl version ") { + t.Fatalf("err=%v output=%q", err, out) + } +} diff --git a/cmd/gfsctl/commands/completion.go b/cmd/gfsctl/commands/completion.go new file mode 100644 index 00000000..e2c40751 --- /dev/null +++ b/cmd/gfsctl/commands/completion.go @@ -0,0 +1,67 @@ +package commands + +import ( + "github.com/spf13/cobra" +) + +var completionCmd = &cobra.Command{ + Use: "completion [shell]", + Short: "Generate shell completion scripts", + Long: `Generate shell completion scripts for gfsctl. + +Supported shells: bash, zsh, fish, powershell + +To load completions: + +Bash: + # Linux + $ gfsctl completion bash > /etc/bash_completion.d/gfsctl + + # macOS (Homebrew) + $ gfsctl completion bash > $(brew --prefix)/etc/bash_completion.d/gfsctl + + # Current session only + $ source <(gfsctl completion bash) + +Zsh: + # If shell completion is not already enabled in your environment, + # you will need to enable it. You can execute the following once: + $ echo "autoload -U compinit; compinit" >> ~/.zshrc + + # To load completions for each session, execute once: + $ gfsctl completion zsh > "${fpath[1]}/_gfsctl" + + # You will need to start a new shell for this setup to take effect. + +Fish: + $ gfsctl completion fish > ~/.config/fish/completions/gfsctl.fish + + # Or for system-wide installation: + $ gfsctl completion fish > /usr/share/fish/vendor_completions.d/gfsctl.fish + +PowerShell: + PS> gfsctl completion powershell | Out-String | Invoke-Expression + + # To load completions for every new session, add the output of the above + # command to your PowerShell profile.`, + DisableFlagsInUseLine: true, + ValidArgs: []string{"bash", "zsh", "fish", "powershell"}, + Args: cobra.MatchAll(cobra.ExactArgs(1), cobra.OnlyValidArgs), + RunE: func(cmd *cobra.Command, args []string) error { + switch args[0] { + case "bash": + return rootCmd.GenBashCompletion(cmd.OutOrStdout()) + case "zsh": + return rootCmd.GenZshCompletion(cmd.OutOrStdout()) + case "fish": + return rootCmd.GenFishCompletion(cmd.OutOrStdout(), true) + case "powershell": + return rootCmd.GenPowerShellCompletionWithDesc(cmd.OutOrStdout()) + } + return nil + }, +} + +func init() { + rootCmd.AddCommand(completionCmd) +} diff --git a/cmd/gfsctl/commands/config.go b/cmd/gfsctl/commands/config.go new file mode 100644 index 00000000..844abbf3 --- /dev/null +++ b/cmd/gfsctl/commands/config.go @@ -0,0 +1,97 @@ +package commands + +import ( + "fmt" + "os" + "path/filepath" + "time" + + "gopkg.in/yaml.v2" +) + +// AppConfig represents the configuration file structure. +type AppConfig struct { + // Host is the default API server host. + Host string `yaml:"host,omitempty"` + + // Port is the default API server port. + Port int `yaml:"port,omitempty"` + + // Token is the default Bearer token for authentication. + Token string `yaml:"token,omitempty"` + + // Output is the default output format (text, json). + Output string `yaml:"output,omitempty"` + + // Timeout is the default request timeout. + Timeout time.Duration `yaml:"timeout,omitempty"` +} + +// configDir returns the configuration directory path. +// Uses XDG_CONFIG_HOME if set, otherwise ~/.config/gfsctl +func configDir() string { + if xdg := os.Getenv("XDG_CONFIG_HOME"); xdg != "" { + return filepath.Join(xdg, "gfsctl") + } + home, err := os.UserHomeDir() + if err != nil { + return "" + } + return filepath.Join(home, ".config", "gfsctl") +} + +// configPath returns the full path to the config file. +func configPath() string { + dir := configDir() + if dir == "" { + return "" + } + return filepath.Join(dir, "config.yaml") +} + +// loadConfig loads configuration from the config file. +// Returns an empty config if the file doesn't exist. +func loadConfig() (*AppConfig, error) { + path := configPath() + if path == "" { + return &AppConfig{}, nil + } + + data, err := os.ReadFile(path) + if err != nil { + if os.IsNotExist(err) { + return &AppConfig{}, nil + } + return nil, fmt.Errorf("read config: %w", err) + } + + var cfg AppConfig + if err := yaml.Unmarshal(data, &cfg); err != nil { + return nil, fmt.Errorf("parse config: %w", err) + } + + return &cfg, nil +} + +// GenerateSampleConfig returns a sample configuration file content. +func GenerateSampleConfig() string { + return `# gfsctl configuration file +# Place this file at ~/.config/gfsctl/config.yaml +# or set XDG_CONFIG_HOME and use $XDG_CONFIG_HOME/gfsctl/config.yaml + +# API server host (default: localhost) +# host: localhost + +# API server port (default: 8080) +# port: 8080 + +# Bearer token for authentication (default: none) +# token: your-secret-token + +# Output format: text or json (default: text) +# output: text + +# Request timeout (default: 30s) +# timeout: 30s +` +} diff --git a/cmd/gfsctl/commands/config_cmd.go b/cmd/gfsctl/commands/config_cmd.go new file mode 100644 index 00000000..2024d6c2 --- /dev/null +++ b/cmd/gfsctl/commands/config_cmd.go @@ -0,0 +1,142 @@ +package commands + +import ( + "fmt" + "os" + "path/filepath" + + "github.com/spf13/cobra" +) + +var configCmd = &cobra.Command{ + Use: "config [subcommand]", + Short: "Manage gfsctl configuration", + Long: `Manage gfsctl configuration file. + +The configuration file is located at: + $XDG_CONFIG_HOME/gfsctl/config.yaml + or ~/.config/gfsctl/config.yaml + +Subcommands: + path - Show configuration file path + show - Show current configuration values + init - Create a sample configuration file + +Configuration values can be overridden by: + 1. Environment variables (GFSCTL_HOST, GFSCTL_TOKEN, etc.) + 2. Command-line flags (--host, --token, etc.) + +Examples: + gfsctl config path # Show config file location + gfsctl config show # Show current configuration + gfsctl config init # Create sample config file`, + Args: cobra.MaximumNArgs(1), + RunE: runConfig, +} + +func init() { + rootCmd.AddCommand(configCmd) +} + +func runConfig(cmd *cobra.Command, args []string) error { + if len(args) == 0 { + return cmd.Help() + } + + subcmd := args[0] + + switch subcmd { + case "path": + return showConfigPath(cmd) + case "show": + return showCurrentConfig(cmd) + case "init": + return initConfigFile(cmd) + default: + return fmt.Errorf("unknown subcommand: %s (valid: path, show, init)", subcmd) + } +} + +func showConfigPath(cmd *cobra.Command) error { + path := configPath() + if path == "" { + fmt.Fprintln(cmd.OutOrStdout(), "Unable to determine config path") + return nil + } + + fmt.Fprintln(cmd.OutOrStdout(), path) + + // Check if file exists + if _, err := os.Stat(path); os.IsNotExist(err) { + fmt.Fprintln(cmd.OutOrStdout(), "(file does not exist)") + } + + return nil +} + +func showCurrentConfig(cmd *cobra.Command) error { + f := NewFormatter(cmd.OutOrStdout(), GetOutputFormat()) + + if f.IsJSON() { + return f.JSON(map[string]interface{}{ + "config_path": configPath(), + "host": cfgHost, + "port": cfgPort, + "token": maskToken(cfgToken), + "output": cfgOutput, + "timeout": cfgTimeout.String(), + }) + } + + f.Header("Current Configuration") + f.KeyValue("Config File", configPath()) + f.Printf("\n") + + // Show effective values with source indication + f.KeyValue("Host", cfgHost) + f.KeyValue("Port", fmt.Sprintf("%d", cfgPort)) + f.KeyValue("Token", maskToken(cfgToken)) + f.KeyValue("Output", cfgOutput) + f.KeyValue("Timeout", cfgTimeout.String()) + + f.Println() + return nil +} + +func initConfigFile(cmd *cobra.Command) error { + path := configPath() + if path == "" { + return fmt.Errorf("unable to determine config directory") + } + + // Check if file already exists + if _, err := os.Stat(path); err == nil { + return fmt.Errorf("config file already exists: %s", path) + } + + // Create directory if needed + dir := filepath.Dir(path) + if err := os.MkdirAll(dir, 0755); err != nil { + return fmt.Errorf("failed to create config directory: %w", err) + } + + // Write sample config + content := GenerateSampleConfig() + if err := os.WriteFile(path, []byte(content), 0600); err != nil { + return fmt.Errorf("failed to write config file: %w", err) + } + + fmt.Fprintf(cmd.OutOrStdout(), "Created config file: %s\n", path) + return nil +} + +// maskToken masks a token for display, showing only first/last 4 chars. +func maskToken(token string) string { + if token == "" { + return "(not set)" + } + if len(token) <= 8 { + return "****" + } + return token[:4] + "..." + token[len(token)-4:] +} diff --git a/cmd/gfsctl/commands/health.go b/cmd/gfsctl/commands/health.go new file mode 100644 index 00000000..a940c8fe --- /dev/null +++ b/cmd/gfsctl/commands/health.go @@ -0,0 +1,68 @@ +package commands + +import ( + "context" + "fmt" + + "github.com/spf13/cobra" +) + +var healthCmd = &cobra.Command{ + Use: "health", + Short: "Check filesystem health", + Long: `Check the health status of the filesystem and its components. +Returns exit code 0 if healthy, 1 if unhealthy. + +Examples: + gfsctl health # Check health in text format + gfsctl health -o json # Check health in JSON format`, + RunE: runHealth, +} + +func init() { + rootCmd.AddCommand(healthCmd) +} + +func runHealth(cmd *cobra.Command, args []string) error { + ctx := context.Background() + client := GetClient() + + health, err := client.Health(ctx) + if err != nil { + return fmt.Errorf("failed to get health: %w", err) + } + + f := NewFormatter(cmd.OutOrStdout(), GetOutputFormat()) + + if f.IsJSON() { + return f.JSON(health) + } + + // Text output + f.Header("Health Status") + + statusColor := string(health.Status) + f.KeyValueColor("Overall", string(health.Status), statusColor) + + // Component checks + if len(health.Checks) > 0 { + f.Header("Component Checks") + for name, check := range health.Checks { + checkColor := string(check.Status) + msg := string(check.Status) + if check.Message != "" { + msg = fmt.Sprintf("%s - %s", check.Status, check.Message) + } + f.KeyValueColor(name, msg, checkColor) + } + } + + f.Println() + + // Return error if unhealthy (for scripting) + if health.Status == "unhealthy" { + return fmt.Errorf("filesystem is unhealthy") + } + + return nil +} diff --git a/cmd/gfsctl/commands/metrics.go b/cmd/gfsctl/commands/metrics.go new file mode 100644 index 00000000..c58024db --- /dev/null +++ b/cmd/gfsctl/commands/metrics.go @@ -0,0 +1,31 @@ +package commands + +import ( + "context" + "fmt" + + "github.com/spf13/cobra" +) + +var metricsCmd = &cobra.Command{ + Use: "metrics", + Short: "Print Prometheus metrics", + Long: `Print the mount's Prometheus metrics from /metrics as text. + +Examples: + gfsctl metrics # All metrics + gfsctl metrics | grep '^goclusterfs_' # Only GoClusterFS metrics`, + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, args []string) error { + body, err := GetClient().Metrics(context.Background()) + if err != nil { + return fmt.Errorf("failed to get metrics: %w", err) + } + _, err = cmd.OutOrStdout().Write(body) + return err + }, +} + +func init() { + rootCmd.AddCommand(metricsCmd) +} diff --git a/cmd/gfsctl/commands/output.go b/cmd/gfsctl/commands/output.go new file mode 100644 index 00000000..51ff6016 --- /dev/null +++ b/cmd/gfsctl/commands/output.go @@ -0,0 +1,223 @@ +package commands + +import ( + "encoding/json" + "fmt" + "io" + "os" + "strings" +) + +// Formatter provides output formatting utilities. +type Formatter struct { + w io.Writer + format string + color bool +} + +// NewFormatter creates a new formatter with the given writer and format. +// It colors output only for a terminal, and never when NO_COLOR is set. +func NewFormatter(w io.Writer, format string) *Formatter { + return &Formatter{w: w, format: format, color: isTerminal(w) && os.Getenv("NO_COLOR") == ""} +} + +func isTerminal(w io.Writer) bool { + f, ok := w.(*os.File) + if !ok { + return false + } + info, err := f.Stat() + return err == nil && info.Mode()&os.ModeCharDevice != 0 +} + +// IsJSON returns true if the output format is JSON. +func (f *Formatter) IsJSON() bool { + return f.format == "json" +} + +// JSON outputs the value as formatted JSON. +func (f *Formatter) JSON(v interface{}) error { + enc := json.NewEncoder(f.w) + enc.SetIndent("", " ") + return enc.Encode(v) +} + +// Print prints a simple message. +func (f *Formatter) Print(format string, args ...interface{}) { + fmt.Fprintf(f.w, format, args...) +} + +// Println prints a message with a newline. +func (f *Formatter) Println(args ...interface{}) { + fmt.Fprintln(f.w, args...) +} + +// Printf prints a formatted message. +func (f *Formatter) Printf(format string, args ...interface{}) { + fmt.Fprintf(f.w, format, args...) +} + +// Header prints a section header. +func (f *Formatter) Header(title string) { + fmt.Fprintf(f.w, "\n%s\n", title) + fmt.Fprintf(f.w, "%s\n", strings.Repeat("─", len(title))) +} + +// KeyValue prints a key-value pair with proper alignment. +func (f *Formatter) KeyValue(key string, value interface{}) { + fmt.Fprintf(f.w, " %-20s %v\n", key+":", value) +} + +// KeyValueColor prints a key-value pair with color for status values. +func (f *Formatter) KeyValueColor(key string, value string, status string) { + if f.color { + value = colorize(value, status) + } + fmt.Fprintf(f.w, " %-20s %s\n", key+":", value) +} + +// Table prints a simple table with headers and rows. +type Table struct { + f *Formatter + headers []string + widths []int + rows [][]string +} + +// NewTable creates a new table with the given headers. +func (f *Formatter) NewTable(headers ...string) *Table { + widths := make([]int, len(headers)) + for i, h := range headers { + widths[i] = len(h) + } + return &Table{ + f: f, + headers: headers, + widths: widths, + } +} + +// AddRow adds a row to the table. +func (t *Table) AddRow(values ...string) { + // Pad values if fewer than headers + for len(values) < len(t.headers) { + values = append(values, "") + } + // Truncate if more than headers + if len(values) > len(t.headers) { + values = values[:len(t.headers)] + } + // Update widths + for i, v := range values { + if len(v) > t.widths[i] { + t.widths[i] = len(v) + } + } + t.rows = append(t.rows, values) +} + +// Render prints the table. +func (t *Table) Render() { + if len(t.rows) == 0 { + fmt.Fprintln(t.f.w, " (no data)") + return + } + + // Print headers + fmt.Fprint(t.f.w, " ") + for i, h := range t.headers { + fmt.Fprintf(t.f.w, "%-*s ", t.widths[i], h) + } + fmt.Fprintln(t.f.w) + + // Print separator + fmt.Fprint(t.f.w, " ") + for i := range t.headers { + fmt.Fprintf(t.f.w, "%s ", strings.Repeat("─", t.widths[i])) + } + fmt.Fprintln(t.f.w) + + // Print rows + for _, row := range t.rows { + fmt.Fprint(t.f.w, " ") + for i, v := range row { + fmt.Fprintf(t.f.w, "%-*s ", t.widths[i], v) + } + fmt.Fprintln(t.f.w) + } +} + +// ANSI color codes +const ( + colorReset = "\033[0m" + colorRed = "\033[31m" + colorGreen = "\033[32m" + colorYellow = "\033[33m" + colorBlue = "\033[34m" + colorCyan = "\033[36m" +) + +// colorize returns a colored string based on the status. +func colorize(value, status string) string { + switch status { + case "ok", "healthy", "active", "leader", "mounted", "open": + return colorGreen + value + colorReset + case "degraded", "warning", "follower": + return colorYellow + value + colorReset + case "unhealthy", "error", "failed", "closed": + return colorRed + value + colorReset + case "info": + return colorCyan + value + colorReset + default: + return value + } +} + +// FormatBytes formats bytes in human-readable form. +func FormatBytes(bytes uint64) string { + const ( + KB = 1024 + MB = KB * 1024 + GB = MB * 1024 + TB = GB * 1024 + ) + + switch { + case bytes >= TB: + return fmt.Sprintf("%.2f TB", float64(bytes)/TB) + case bytes >= GB: + return fmt.Sprintf("%.2f GB", float64(bytes)/GB) + case bytes >= MB: + return fmt.Sprintf("%.2f MB", float64(bytes)/MB) + case bytes >= KB: + return fmt.Sprintf("%.2f KB", float64(bytes)/KB) + default: + return fmt.Sprintf("%d B", bytes) + } +} + +// FormatDuration formats seconds in human-readable form. +func FormatDuration(seconds int64) string { + if seconds < 60 { + return fmt.Sprintf("%ds", seconds) + } + if seconds < 3600 { + return fmt.Sprintf("%dm %ds", seconds/60, seconds%60) + } + if seconds < 86400 { + hours := seconds / 3600 + mins := (seconds % 3600) / 60 + return fmt.Sprintf("%dh %dm", hours, mins) + } + days := seconds / 86400 + hours := (seconds % 86400) / 3600 + return fmt.Sprintf("%dd %dh", days, hours) +} + +// FormatPercent formats a percentage with appropriate precision. +func FormatPercent(pct float64) string { + if pct < 10 { + return fmt.Sprintf("%.2f%%", pct) + } + return fmt.Sprintf("%.1f%%", pct) +} diff --git a/cmd/gfsctl/commands/root.go b/cmd/gfsctl/commands/root.go new file mode 100644 index 00000000..4cc79f53 --- /dev/null +++ b/cmd/gfsctl/commands/root.go @@ -0,0 +1,143 @@ +// Package commands implements the gfsctl CLI commands. +package commands + +import ( + "fmt" + "os" + "strconv" + "time" + + "github.com/spf13/cobra" + + "github.com/supporttools/GoClusterFS/cmd/gfsctl/client" +) + +var ( + // Global flags + cfgHost string + cfgPort int + cfgToken string + cfgTimeout time.Duration + cfgOutput string + + // API client (initialized in PersistentPreRunE) + apiClient *client.Client +) + +// rootCmd is the base command when called without subcommands. +var rootCmd = &cobra.Command{ + Use: "gfsctl", + Short: "GoClusterFS management CLI", + Long: `gfsctl is the management CLI for GoClusterFS. + +It reads status, health, statistics and metrics from a running +GoClusterFS mount through its HTTP API. It changes nothing. + +Settings come from flags, then GFSCTL_HOST, GFSCTL_PORT, GFSCTL_TOKEN, +GFSCTL_OUTPUT and GFSCTL_TIMEOUT, then the config file (gfsctl config path). + +Examples: + gfsctl status # Show filesystem status + gfsctl health # Check health status + gfsctl stats cache # Show cache statistics + gfsctl metrics # Print Prometheus metrics + gfsctl --host 10.0.0.1 status # Connect to remote host`, + SilenceUsage: true, + SilenceErrors: true, + PersistentPreRunE: func(cmd *cobra.Command, args []string) error { + if err := resolveSettings(cmd); err != nil { + return err + } + apiClient = client.New( + client.WithHost(cfgHost), + client.WithPort(cfgPort), + client.WithToken(cfgToken), + client.WithTimeout(cfgTimeout), + ) + return nil + }, +} + +// Execute runs the root command and prints any error to stderr. +func Execute() error { + err := rootCmd.Execute() + if err != nil { + fmt.Fprintln(rootCmd.ErrOrStderr(), "Error:", err) + } + return err +} + +func init() { + rootCmd.PersistentFlags().StringVar(&cfgHost, "host", "localhost", "API server host") + rootCmd.PersistentFlags().IntVar(&cfgPort, "port", 8080, "API server port") + rootCmd.PersistentFlags().StringVar(&cfgToken, "token", "", "Bearer token for authentication (visible in ps; prefer GFSCTL_TOKEN or the config file)") + rootCmd.PersistentFlags().DurationVar(&cfgTimeout, "timeout", 30*time.Second, "Request timeout") + rootCmd.PersistentFlags().StringVarP(&cfgOutput, "output", "o", "text", "Output format (text, json)") +} + +// resolveSettings fills every setting whose flag was not given from the +// environment, then from the config file. +func resolveSettings(cmd *cobra.Command) error { + file, err := loadConfig() + if err != nil { + return fmt.Errorf("%w (%s)", err, configPath()) + } + flags := cmd.Flags() + + if !flags.Changed("host") { + cfgHost = firstNonEmpty(os.Getenv("GFSCTL_HOST"), file.Host, cfgHost) + } + if !flags.Changed("port") { + if env := os.Getenv("GFSCTL_PORT"); env != "" { + port, err := strconv.Atoi(env) + if err != nil || port <= 0 || port > 65535 { + return fmt.Errorf("GFSCTL_PORT=%q is not a port number", env) + } + cfgPort = port + } else if file.Port != 0 { + cfgPort = file.Port + } + } + if !flags.Changed("token") { + cfgToken = firstNonEmpty(os.Getenv("GFSCTL_TOKEN"), file.Token, cfgToken) + } + if !flags.Changed("output") { + cfgOutput = firstNonEmpty(os.Getenv("GFSCTL_OUTPUT"), file.Output, cfgOutput) + } + if !flags.Changed("timeout") { + if env := os.Getenv("GFSCTL_TIMEOUT"); env != "" { + timeout, err := time.ParseDuration(env) + if err != nil { + return fmt.Errorf("GFSCTL_TIMEOUT=%q: %w", env, err) + } + cfgTimeout = timeout + } else if file.Timeout != 0 { + cfgTimeout = file.Timeout + } + } + + if cfgOutput != "text" && cfgOutput != "json" { + return fmt.Errorf("unknown output format %q (valid: text, json)", cfgOutput) + } + return nil +} + +func firstNonEmpty(values ...string) string { + for _, v := range values { + if v != "" { + return v + } + } + return "" +} + +// GetClient returns the initialized API client. +// Commands should call this after PersistentPreRunE has executed. +func GetClient() *client.Client { + return apiClient +} + +// GetOutputFormat returns the configured output format. +func GetOutputFormat() string { + return cfgOutput +} diff --git a/cmd/gfsctl/commands/stats.go b/cmd/gfsctl/commands/stats.go new file mode 100644 index 00000000..add5f1b8 --- /dev/null +++ b/cmd/gfsctl/commands/stats.go @@ -0,0 +1,399 @@ +package commands + +import ( + "context" + "fmt" + "time" + + "github.com/spf13/cobra" + + "github.com/supporttools/GoClusterFS/cmd/gfsctl/client" +) + +var ( + statsWatch bool + statsInterval time.Duration +) + +var statsCmd = &cobra.Command{ + Use: "stats [component]", + Short: "Show component statistics", + Long: `Display statistics for filesystem components. + +Available components: + cache - Cache hit/miss statistics + journal - Journal transaction statistics + trim - TRIM operation statistics + lock - Lock contention statistics + sfb - Sub-File Block allocation statistics + cluster - Cluster membership and peers + all - All statistics combined + +If no component is specified, shows an overview of key stats. + +Examples: + gfsctl stats # Show overview + gfsctl stats cache # Show cache stats + gfsctl stats all # Show all stats + gfsctl stats -o json # Show overview in JSON + gfsctl stats cache -w # Watch cache stats with 2s refresh + gfsctl stats all -w -i 5s # Watch all stats with 5s refresh`, + Args: cobra.MaximumNArgs(1), + RunE: runStats, +} + +func init() { + statsCmd.Flags().BoolVarP(&statsWatch, "watch", "w", false, "Enable watch mode for live updates") + statsCmd.Flags().DurationVarP(&statsInterval, "interval", "i", 2*time.Second, "Refresh interval for watch mode") + rootCmd.AddCommand(statsCmd) +} + +func runStats(cmd *cobra.Command, args []string) error { + // Watch mode not compatible with JSON output + if statsWatch && GetOutputFormat() == "json" { + return fmt.Errorf("watch mode is not compatible with JSON output") + } + + // Determine which stats to show + component := "" + if len(args) > 0 { + component = args[0] + } + + // Validate component name upfront + switch component { + case "", "cache", "journal", "trim", "lock", "sfb", "cluster", "all": + // valid + default: + return fmt.Errorf("unknown component: %s (valid: cache, journal, trim, lock, sfb, cluster, all)", component) + } + + // Create the display function + displayFn := func(ctx context.Context) error { + return displayStats(cmd, ctx, component) + } + + // Run with or without watch + return RunWithWatch(WatchConfig{ + Enabled: statsWatch, + Interval: statsInterval, + }, displayFn) +} + +func displayStats(cmd *cobra.Command, ctx context.Context, component string) error { + apiClient := GetClient() + f := NewFormatter(cmd.OutOrStdout(), GetOutputFormat()) + + switch component { + case "": + return showStatsOverview(ctx, apiClient, f) + case "cache": + return showCacheStats(ctx, apiClient, f) + case "journal": + return showJournalStats(ctx, apiClient, f) + case "trim": + return showTrimStats(ctx, apiClient, f) + case "lock": + return showLockStats(ctx, apiClient, f) + case "sfb": + return showSFBStats(ctx, apiClient, f) + case "cluster": + return showClusterStats(ctx, apiClient, f) + case "all": + return showAllStats(ctx, apiClient, f) + default: + return fmt.Errorf("unknown component: %s", component) + } +} + +func showStatsOverview(ctx context.Context, c *client.Client, f *Formatter) error { + stats, err := c.StatsOverview(ctx) + if err != nil { + return fmt.Errorf("failed to get stats: %w", err) + } + + if f.IsJSON() { + return f.JSON(stats) + } + + f.Header("Statistics Overview") + + if stats.Cache != nil { + f.Printf("\n Cache:\n") + f.KeyValue(" Inode Hit Rate", FormatPercent(stats.Cache.InodeCache.HitRate*100)) + f.KeyValue(" Extent Hit Rate", FormatPercent(stats.Cache.ExtentCache.HitRate*100)) + } + + if stats.Journal != nil { + f.Printf("\n Journal:\n") + f.KeyValue(" State", stats.Journal.State) + f.KeyValue(" Commits", fmt.Sprintf("%d", stats.Journal.CommitCount)) + f.KeyValue(" Bytes Written", FormatBytes(stats.Journal.BytesWritten)) + } + + f.Println() + return nil +} + +func showCacheStats(ctx context.Context, c *client.Client, f *Formatter) error { + stats, err := c.CacheStats(ctx) + if err != nil { + return fmt.Errorf("failed to get cache stats: %w", err) + } + + if f.IsJSON() { + return f.JSON(stats) + } + + f.Header("Cache Statistics") + + table := f.NewTable("Cache", "Size", "Hits", "Misses", "Hit Rate") + table.AddRow("Inode", + fmt.Sprintf("%d", stats.InodeCache.Size), + fmt.Sprintf("%d", stats.InodeCache.Hits), + fmt.Sprintf("%d", stats.InodeCache.Misses), + FormatPercent(stats.InodeCache.HitRate*100)) + table.AddRow("Extent", + fmt.Sprintf("%d", stats.ExtentCache.Size), + fmt.Sprintf("%d", stats.ExtentCache.Hits), + fmt.Sprintf("%d", stats.ExtentCache.Misses), + FormatPercent(stats.ExtentCache.HitRate*100)) + table.AddRow("Negative", + fmt.Sprintf("%d", stats.NegativeCache.Size), + fmt.Sprintf("%d", stats.NegativeCache.Hits), + fmt.Sprintf("%d", stats.NegativeCache.Misses), + FormatPercent(stats.NegativeCache.HitRate*100)) + if stats.LockHintCache.Size > 0 { + table.AddRow("Lock Hint", + fmt.Sprintf("%d", stats.LockHintCache.Size), + fmt.Sprintf("%d", stats.LockHintCache.Hits), + fmt.Sprintf("%d", stats.LockHintCache.Misses), + FormatPercent(stats.LockHintCache.HitRate*100)) + } + table.Render() + + f.Println() + return nil +} + +func showJournalStats(ctx context.Context, c *client.Client, f *Formatter) error { + stats, err := c.JournalStats(ctx) + if err != nil { + return fmt.Errorf("failed to get journal stats: %w", err) + } + + if f.IsJSON() { + return f.JSON(stats) + } + + f.Header("Journal Statistics") + + stateColor := "ok" + if stats.State != "open" { + stateColor = "warning" + } + f.KeyValueColor("State", stats.State, stateColor) + f.KeyValue("Head Offset", fmt.Sprintf("%d", stats.HeadOffset)) + f.KeyValue("Tail Offset", fmt.Sprintf("%d", stats.TailOffset)) + f.KeyValue("Available Space", FormatBytes(uint64(stats.AvailableSpace))) + f.KeyValue("Active Transactions", fmt.Sprintf("%d", stats.ActiveTxnCount)) + f.KeyValue("Commits", fmt.Sprintf("%d", stats.CommitCount)) + f.KeyValue("Bytes Written", FormatBytes(stats.BytesWritten)) + f.KeyValue("Last Checkpoint", fmt.Sprintf("%d", stats.LastCheckpointSeq)) + f.KeyValue("Batch Syncs", fmt.Sprintf("%d", stats.BatchSyncCount)) + + f.Println() + return nil +} + +func showTrimStats(ctx context.Context, c *client.Client, f *Formatter) error { + stats, err := c.TrimStats(ctx) + if err != nil { + return fmt.Errorf("failed to get trim stats: %w", err) + } + + if f.IsJSON() { + return f.JSON(stats) + } + + f.Header("TRIM Statistics") + + enabledStr := "disabled" + enabledColor := "warning" + if stats.TrimEnabled { + enabledStr = "enabled" + enabledColor = "ok" + } + f.KeyValueColor("TRIM", enabledStr, enabledColor) + f.KeyValue("Operations", fmt.Sprintf("%d", stats.TrimOperations)) + f.KeyValue("Bytes Trimmed", FormatBytes(stats.TrimBytes)) + f.KeyValue("Blocks Trimmed", fmt.Sprintf("%d", stats.TrimBlocks)) + f.KeyValue("Pending Blocks", fmt.Sprintf("%d", stats.PendingTrimBlocks)) + if stats.TrimErrors > 0 { + f.KeyValueColor("Errors", fmt.Sprintf("%d", stats.TrimErrors), "error") + } else { + f.KeyValue("Errors", "0") + } + if stats.LastTrimAt != "" { + f.KeyValue("Last TRIM", stats.LastTrimAt) + } + + f.Println() + return nil +} + +func showLockStats(ctx context.Context, c *client.Client, f *Formatter) error { + stats, err := c.LockStats(ctx) + if err != nil { + return fmt.Errorf("failed to get lock stats: %w", err) + } + + if f.IsJSON() { + return f.JSON(stats) + } + + f.Header("Lock Statistics") + + f.KeyValue("Hint Cache Hits", fmt.Sprintf("%d", stats.HintCacheHits)) + f.KeyValue("Hint Cache Misses", fmt.Sprintf("%d", stats.HintCacheMisses)) + f.KeyValue("Hint Cache Hit Rate", FormatPercent(stats.HintCacheHitRate*100)) + f.KeyValue("Active Locks", fmt.Sprintf("%d", stats.ActiveLocks)) + f.KeyValue("Pending Locks", fmt.Sprintf("%d", stats.PendingLocks)) + + f.Println() + return nil +} + +func showSFBStats(ctx context.Context, c *client.Client, f *Formatter) error { + stats, err := c.SFBStats(ctx) + if err != nil { + return fmt.Errorf("failed to get sfb stats: %w", err) + } + + if f.IsJSON() { + return f.JSON(stats) + } + + f.Header("SFB (Sub-File Block) Statistics") + + f.KeyValue("Total Blocks", fmt.Sprintf("%d", stats.TotalBlocks)) + f.KeyValue("Allocated Blocks", fmt.Sprintf("%d", stats.AllocatedBlocks)) + f.KeyValue("Free Blocks", fmt.Sprintf("%d", stats.FreeBlocks)) + f.KeyValue("Allocation", FormatPercent(stats.AllocationPercent)) + if stats.FragmentationRatio > 0 { + f.KeyValue("Fragmentation", FormatPercent(stats.FragmentationRatio*100)) + } + if stats.LargestFreeExtent > 0 { + f.KeyValue("Largest Free Extent", fmt.Sprintf("%d blocks", stats.LargestFreeExtent)) + } + f.KeyValue("Total Allocations", fmt.Sprintf("%d", stats.AllocationsTotal)) + f.KeyValue("Total Deallocations", fmt.Sprintf("%d", stats.DeallocationsTotal)) + if stats.AllocationFailures > 0 { + f.KeyValueColor("Allocation Failures", fmt.Sprintf("%d", stats.AllocationFailures), "error") + } + + f.Println() + return nil +} + +func showClusterStats(ctx context.Context, c *client.Client, f *Formatter) error { + stats, err := c.ClusterInfo(ctx) + if err != nil { + return fmt.Errorf("failed to get cluster stats: %w", err) + } + + if f.IsJSON() { + return f.JSON(stats) + } + + f.Header("Cluster") + f.KeyValue("Node ID", stats.NodeID) + f.KeyValue("Role", stats.Role) + f.KeyValue("State", stats.State) + f.KeyValue("Cluster Size", fmt.Sprintf("%d", stats.ClusterSize)) + f.KeyValue("Healthy Nodes", fmt.Sprintf("%d", stats.HealthyNodes)) + if len(stats.Peers) > 0 { + f.Printf("\n") + table := f.NewTable("Peer", "Address", "State", "Last Seen") + for _, p := range stats.Peers { + table.AddRow(p.NodeID, p.Address, p.State, p.LastSeen) + } + table.Render() + } + + f.Println() + return nil +} + +func showAllStats(ctx context.Context, c *client.Client, f *Formatter) error { + stats, err := c.AllStats(ctx) + if err != nil { + return fmt.Errorf("failed to get all stats: %w", err) + } + + if f.IsJSON() { + return f.JSON(stats) + } + + f.Header("All Statistics") + f.KeyValue("Collected At", stats.CollectedAt) + + // Show each component's stats inline + if stats.Cache != nil { + f.Printf("\n") + f.Header("Cache") + table := f.NewTable("Cache", "Size", "Hits", "Misses", "Hit Rate") + table.AddRow("Inode", + fmt.Sprintf("%d", stats.Cache.InodeCache.Size), + fmt.Sprintf("%d", stats.Cache.InodeCache.Hits), + fmt.Sprintf("%d", stats.Cache.InodeCache.Misses), + FormatPercent(stats.Cache.InodeCache.HitRate*100)) + table.AddRow("Extent", + fmt.Sprintf("%d", stats.Cache.ExtentCache.Size), + fmt.Sprintf("%d", stats.Cache.ExtentCache.Hits), + fmt.Sprintf("%d", stats.Cache.ExtentCache.Misses), + FormatPercent(stats.Cache.ExtentCache.HitRate*100)) + table.Render() + } + + if stats.Journal != nil { + f.Printf("\n") + f.Header("Journal") + f.KeyValue("State", stats.Journal.State) + f.KeyValue("Commits", fmt.Sprintf("%d", stats.Journal.CommitCount)) + f.KeyValue("Bytes Written", FormatBytes(stats.Journal.BytesWritten)) + } + + if stats.Trim != nil { + f.Printf("\n") + f.Header("TRIM") + f.KeyValue("Operations", fmt.Sprintf("%d", stats.Trim.TrimOperations)) + f.KeyValue("Bytes Trimmed", FormatBytes(stats.Trim.TrimBytes)) + } + + if stats.Lock != nil { + f.Printf("\n") + f.Header("Lock") + f.KeyValue("Hint Cache Hit Rate", FormatPercent(stats.Lock.HintCacheHitRate*100)) + f.KeyValue("Active Locks", fmt.Sprintf("%d", stats.Lock.ActiveLocks)) + } + + if stats.SFB != nil { + f.Printf("\n") + f.Header("SFB") + f.KeyValue("Allocation", FormatPercent(stats.SFB.AllocationPercent)) + f.KeyValue("Free Blocks", fmt.Sprintf("%d", stats.SFB.FreeBlocks)) + } + + if stats.Cluster != nil { + f.Printf("\n") + f.Header("Cluster") + f.KeyValue("Node ID", stats.Cluster.NodeID) + f.KeyValue("Role", stats.Cluster.Role) + f.KeyValue("Cluster Size", fmt.Sprintf("%d", stats.Cluster.ClusterSize)) + f.KeyValue("Healthy Nodes", fmt.Sprintf("%d", stats.Cluster.HealthyNodes)) + } + + f.Println() + return nil +} diff --git a/cmd/gfsctl/commands/status.go b/cmd/gfsctl/commands/status.go new file mode 100644 index 00000000..45dc80b0 --- /dev/null +++ b/cmd/gfsctl/commands/status.go @@ -0,0 +1,142 @@ +package commands + +import ( + "context" + "fmt" + "time" + + "github.com/spf13/cobra" +) + +var ( + statusWatch bool + statusInterval time.Duration +) + +var statusCmd = &cobra.Command{ + Use: "status", + Short: "Show filesystem status", + Long: `Display comprehensive filesystem status including mount state, version, +uptime, and storage capacity. + +Examples: + gfsctl status # Show status in text format + gfsctl status -o json # Show status in JSON format + gfsctl status -w # Watch mode with 2s refresh + gfsctl status -w -i 5s # Watch mode with 5s refresh`, + RunE: runStatus, +} + +func init() { + statusCmd.Flags().BoolVarP(&statusWatch, "watch", "w", false, "Enable watch mode for live updates") + statusCmd.Flags().DurationVarP(&statusInterval, "interval", "i", 2*time.Second, "Refresh interval for watch mode") + rootCmd.AddCommand(statusCmd) +} + +func runStatus(cmd *cobra.Command, args []string) error { + // Watch mode not compatible with JSON output + if statusWatch && GetOutputFormat() == "json" { + return fmt.Errorf("watch mode is not compatible with JSON output") + } + + // Create the display function + displayFn := func(ctx context.Context) error { + return displayStatus(cmd, ctx) + } + + // Run with or without watch + return RunWithWatch(WatchConfig{ + Enabled: statusWatch, + Interval: statusInterval, + }, displayFn) +} + +func displayStatus(cmd *cobra.Command, ctx context.Context) error { + client := GetClient() + + status, err := client.Status(ctx) + if err != nil { + return fmt.Errorf("failed to get status: %w", err) + } + + f := NewFormatter(cmd.OutOrStdout(), GetOutputFormat()) + + if f.IsJSON() { + return f.JSON(status) + } + + // Text output with colored status + f.Header("GoClusterFS Status") + + // Status indicator + statusColor := "ok" + if status.Status != "ok" { + statusColor = "error" + } + f.KeyValueColor("Status", status.Status, statusColor) + + // Version info + f.KeyValue("Version", status.Version) + if status.GitCommit != "" { + f.KeyValue("Git Commit", status.GitCommit) + } + if status.BuildTime != "" { + f.KeyValue("Build Time", status.BuildTime) + } + if status.GoVersion != "" { + f.KeyValue("Go Version", status.GoVersion) + } + + // Uptime + f.KeyValue("Uptime", FormatDuration(status.UptimeSeconds)) + + // Mount info + if status.MountPath != "" { + f.Header("Mount") + f.KeyValue("Mount Path", status.MountPath) + f.KeyValue("Device Path", status.DevicePath) + + mountColor := "ok" + if status.MountState != "mounted" { + mountColor = "warning" + } + f.KeyValueColor("Mount State", string(status.MountState), mountColor) + + if status.ReadOnly { + f.KeyValueColor("Read Only", "yes", "warning") + } + } + + // Capacity info + if status.Capacity != nil { + c := status.Capacity + f.Header("Storage Capacity") + f.KeyValue("Total", FormatBytes(c.TotalBytes)) + f.KeyValue("Used", fmt.Sprintf("%s (%s)", FormatBytes(c.UsedBytes), FormatPercent(c.UsedPercent))) + f.KeyValue("Free", FormatBytes(c.FreeBytes)) + f.KeyValue("Block Size", FormatBytes(c.BlockSizeBytes)) + f.KeyValue("Total Blocks", fmt.Sprintf("%d", c.TotalBlocks)) + f.KeyValue("Used Blocks", fmt.Sprintf("%d", c.UsedBlocks)) + f.KeyValue("Free Blocks", fmt.Sprintf("%d", c.FreeBlocks)) + } + + // Cluster info + if status.Cluster != nil { + c := status.Cluster + f.Header("Cluster") + f.KeyValue("Node ID", c.NodeID) + f.KeyValue("Peer Count", fmt.Sprintf("%d", c.PeerCount)) + if c.LeaderID != "" { + f.KeyValue("Leader ID", c.LeaderID) + } + if c.IsLeader { + f.KeyValueColor("Role", "leader", "leader") + } + if c.ClusterState != "" { + f.KeyValue("State", c.ClusterState) + } + } + + f.Println() + return nil +} diff --git a/cmd/gfsctl/commands/version.go b/cmd/gfsctl/commands/version.go new file mode 100644 index 00000000..6f73e252 --- /dev/null +++ b/cmd/gfsctl/commands/version.go @@ -0,0 +1,54 @@ +package commands + +import ( + "encoding/json" + "fmt" + "runtime" + + "github.com/spf13/cobra" + + "github.com/supporttools/GoClusterFS/internal/version" +) + +// VersionInfo contains version information for JSON output. +type VersionInfo struct { + Version string `json:"version"` + GitCommit string `json:"git_commit"` + BuildTime string `json:"build_time"` + GoVersion string `json:"go_version"` + OS string `json:"os"` + Arch string `json:"arch"` +} + +var versionCmd = &cobra.Command{ + Use: "version", + Short: "Show gfsctl version information", + Long: `Display version, build information, and runtime details for gfsctl.`, + RunE: func(cmd *cobra.Command, args []string) error { + info := VersionInfo{ + Version: version.Version, + GitCommit: version.Commit, + BuildTime: version.Date, + GoVersion: runtime.Version(), + OS: runtime.GOOS, + Arch: runtime.GOARCH, + } + + if GetOutputFormat() == "json" { + enc := json.NewEncoder(cmd.OutOrStdout()) + enc.SetIndent("", " ") + return enc.Encode(info) + } + + fmt.Fprintf(cmd.OutOrStdout(), "gfsctl version %s\n", info.Version) + fmt.Fprintf(cmd.OutOrStdout(), " Git commit: %s\n", info.GitCommit) + fmt.Fprintf(cmd.OutOrStdout(), " Built: %s\n", info.BuildTime) + fmt.Fprintf(cmd.OutOrStdout(), " Go version: %s\n", info.GoVersion) + fmt.Fprintf(cmd.OutOrStdout(), " OS/Arch: %s/%s\n", info.OS, info.Arch) + return nil + }, +} + +func init() { + rootCmd.AddCommand(versionCmd) +} diff --git a/cmd/gfsctl/commands/watch.go b/cmd/gfsctl/commands/watch.go new file mode 100644 index 00000000..de595196 --- /dev/null +++ b/cmd/gfsctl/commands/watch.go @@ -0,0 +1,96 @@ +package commands + +import ( + "context" + "fmt" + "os" + "os/signal" + "syscall" + "time" +) + +// WatchConfig holds configuration for watch mode. +type WatchConfig struct { + Enabled bool + Interval time.Duration +} + +// WatchFunc is a function that can be watched (called repeatedly). +type WatchFunc func(ctx context.Context) error + +// RunWithWatch executes the given function once or repeatedly based on watch mode. +// If watch mode is enabled, it clears the screen and re-runs the function +// at the configured interval until interrupted. +func RunWithWatch(cfg WatchConfig, fn WatchFunc) error { + if !cfg.Enabled { + return fn(context.Background()) + } + + // Set up signal handling for graceful exit + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + + sigCh := make(chan os.Signal, 1) + signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM) + + // Channel for watch loop to signal completion + done := make(chan struct{}) + + go func() { + defer close(done) + ticker := time.NewTicker(cfg.Interval) + defer ticker.Stop() + + // Initial run + clearScreen() + printWatchHeader(cfg.Interval) + if err := fn(ctx); err != nil { + fmt.Fprintf(os.Stderr, "Error: %v\n", err) + } + + for { + select { + case <-ctx.Done(): + return + case <-ticker.C: + clearScreen() + printWatchHeader(cfg.Interval) + if err := fn(ctx); err != nil { + fmt.Fprintf(os.Stderr, "Error: %v\n", err) + } + } + } + }() + + // Wait for signal or context cancellation + select { + case <-sigCh: + cancel() + <-done + fmt.Println("\nWatch mode terminated.") + case <-done: + } + + return nil +} + +// clearScreen clears the terminal screen using ANSI escape codes. +func clearScreen() { + // Move cursor to home position and clear screen + fmt.Print("\033[H\033[2J") +} + +// printWatchHeader prints the watch mode header with timestamp. +func printWatchHeader(interval time.Duration) { + now := time.Now().Format("2006-01-02 15:04:05") + fmt.Printf("Every %s: gfsctl (updated: %s) [Ctrl+C to exit]\n\n", + formatInterval(interval), now) +} + +// formatInterval formats a duration for display. +func formatInterval(d time.Duration) string { + if d >= time.Minute { + return fmt.Sprintf("%.0fm", d.Minutes()) + } + return fmt.Sprintf("%.0fs", d.Seconds()) +} diff --git a/cmd/gfsctl/main.go b/cmd/gfsctl/main.go new file mode 100644 index 00000000..2031504e --- /dev/null +++ b/cmd/gfsctl/main.go @@ -0,0 +1,15 @@ +// Command gfsctl reads status, health, statistics and metrics from a +// running GoClusterFS mount through its HTTP API. It changes nothing. +package main + +import ( + "os" + + "github.com/supporttools/GoClusterFS/cmd/gfsctl/commands" +) + +func main() { + if err := commands.Execute(); err != nil { + os.Exit(1) + } +} diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index 4e3db66e..65c648ee 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -77,11 +77,11 @@ newgrp fuse git clone https://github.com/supporttools/GoClusterFS.git cd GoClusterFS -# Build goclusterfs-mount and goclusterfs-fsck +# Build goclusterfs-mount, goclusterfs-fsck and gfsctl make build # Optional: Install to system path -sudo cp goclusterfs-mount goclusterfs-fsck /usr/local/bin/ +sudo cp goclusterfs-mount goclusterfs-fsck gfsctl /usr/local/bin/ ``` ### Verify Build @@ -89,6 +89,7 @@ sudo cp goclusterfs-mount goclusterfs-fsck /usr/local/bin/ ```bash ./goclusterfs-mount -version ./goclusterfs-fsck -version +./gfsctl version ``` Each `v*` tag publishes prebuilt `linux/amd64` and `linux/arm64` archives on the GitHub Releases page. diff --git a/go.mod b/go.mod index b18f9c14..52fa5782 100644 --- a/go.mod +++ b/go.mod @@ -6,12 +6,16 @@ require github.com/hanwen/go-fuse/v2 v2.9.0 require ( github.com/prometheus/client_golang v1.23.2 + github.com/spf13/cobra v1.10.2 + github.com/spf13/pflag v1.0.9 golang.org/x/sys v0.50.0 + gopkg.in/yaml.v2 v2.4.0 ) require ( github.com/beorn7/perks v1.0.1 // indirect github.com/cespare/xxhash/v2 v2.3.0 // indirect + github.com/inconshreveable/mousetrap v1.1.0 // indirect github.com/kr/text v0.2.0 // indirect github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect github.com/prometheus/client_model v0.6.2 // indirect diff --git a/go.sum b/go.sum index 825cfc82..6997ac81 100644 --- a/go.sum +++ b/go.sum @@ -2,6 +2,7 @@ github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM= github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw= github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs= github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs= +github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g= github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E= github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= @@ -9,6 +10,8 @@ github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU= github.com/hanwen/go-fuse/v2 v2.9.0 h1:0AOGUkHtbOVeyGLr0tXupiid1Vg7QB7M6YUcdmVdC58= github.com/hanwen/go-fuse/v2 v2.9.0/go.mod h1:yE6D2PqWwm3CbYRxFXV9xUd8Md5d6NG0WBs5spCswmI= +github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8= +github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= github.com/klauspost/compress v1.18.0 h1:c/Cqfb0r+Yi+JtIEq73FWXVkRonBlf0CRNYc8Zttxdo= github.com/klauspost/compress v1.18.0/go.mod h1:2Pp+KzxcywXVXMr50+X0Q/Lsb43OQHYWRCY2AiWywWQ= github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE= @@ -33,12 +36,18 @@ github.com/prometheus/procfs v0.16.1 h1:hZ15bTNuirocR6u0JZ6BAHHmwS1p8B4P6MRqxtzM github.com/prometheus/procfs v0.16.1/go.mod h1:teAbpZRB1iIAJYREa1LsoWUXykVXA1KlTmWl8x/U+Is= github.com/rogpeppe/go-internal v1.10.0 h1:TMyTOH3F/DB16zRVcYyreMH6GnZZrwQVAoYjRBZyWFQ= github.com/rogpeppe/go-internal v1.10.0/go.mod h1:UQnix2H7Ngw/k4C5ijL5+65zddjncjaFoBhdsK/akog= +github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= +github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU= +github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4= +github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY= +github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U= github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto= go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE= go.yaml.in/yaml/v2 v2.4.2 h1:DzmwEr2rDGHl7lsFgAHxmNz/1NlQ7xLIrlN2h5d1eGI= go.yaml.in/yaml/v2 v2.4.2/go.mod h1:081UH+NErpNdqlCXm3TtEran0rJZGxAYx9hb/ELlsPU= +go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg= golang.org/x/sys v0.50.0 h1:dkKZEFTEKaLr1sjhs0WiKqoi8Jj5nHbS3Njmx1UoMJs= golang.org/x/sys v0.50.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og= google.golang.org/protobuf v1.36.8 h1:xHScyCOEuuwZEc6UtSOvPbAT4zRh0xcNRYekJwfqyMc= @@ -46,5 +55,7 @@ google.golang.org/protobuf v1.36.8/go.mod h1:fuxRtAxBytpl4zzqUh6/eyUujkJdNiuEkXn gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk= gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q= +gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY= +gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ= gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= diff --git a/scripts/dist.sh b/scripts/dist.sh index 07b400f0..155d5d8d 100755 --- a/scripts/dist.sh +++ b/scripts/dist.sh @@ -28,10 +28,12 @@ for platform in $platforms; do CGO_ENABLED=0 GOOS="$goos" GOARCH="$goarch" \ go build -trimpath -ldflags "$ldflags" -o "$dir/goclusterfs-$cmd" "./cmd/$cmd" done + CGO_ENABLED=0 GOOS="$goos" GOARCH="$goarch" \ + go build -trimpath -ldflags "$ldflags" -o "$dir/gfsctl" ./cmd/gfsctl cp LICENSE README.md "$dir/" cp "$go_license" "$dir/licenses/go/" - go version -m "$dir"/goclusterfs-* | awk '$1 == "dep" { print $2 }' | sort -u | + go version -m "$dir"/goclusterfs-* "$dir"/gfsctl | awk '$1 == "dep" { print $2 }' | sort -u | while read -r mod; do mkdir -p "$dir/licenses/$mod" cp "$(go list -m -f '{{.Dir}}' "$mod")"/LICENSE* "$dir/licenses/$mod/" diff --git a/tests/integration/api_test.go b/tests/integration/api_test.go index 69e7aff6..390e8847 100644 --- a/tests/integration/api_test.go +++ b/tests/integration/api_test.go @@ -3,6 +3,7 @@ package integration import ( "bytes" "context" + "encoding/json" "io" "net" "net/http" @@ -155,3 +156,56 @@ func TestMountRejectsBadAPISettingsBeforeOpeningDevice(t *testing.T) { } } } + +func TestGfsctlReadsLiveMount(t *testing.T) { + mountBinary, err := findBinary() + if err != nil { + t.Fatalf("Failed to find binary: %v", err) + } + gfsctl := filepath.Join(filepath.Dir(mountBinary), "gfsctl") + if _, err := os.Stat(gfsctl); err != nil { + t.Fatalf("gfsctl not found next to %s; run 'make build' first", mountBinary) + } + + mfs := NewMountedFS(t, 20) + addr := freeLoopbackAddr(t) + mfs.ExtraArgs = []string{"-format", "-api-addr", addr} + if err := mfs.Mount(false); err != nil { + t.Fatalf("Mount failed: %v", err) + } + host, port, _ := net.SplitHostPort(addr) + + ctl := func(args ...string) (string, error) { + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + cmd := exec.CommandContext(ctx, gfsctl, append([]string{"--host", host, "--port", port}, args...)...) + cmd.Env = append(os.Environ(), "XDG_CONFIG_HOME="+t.TempDir()) + out, err := cmd.CombinedOutput() + return string(out), err + } + + var out string + deadline := time.Now().Add(10 * time.Second) + for { + if out, err = ctl("status", "-o", "json"); err == nil || time.Now().After(deadline) { + break + } + time.Sleep(100 * time.Millisecond) + } + if err != nil { + t.Fatalf("gfsctl status: %v\n%s", err, out) + } + var status struct { + MountState string `json:"mount_state"` + MountPath string `json:"mount_path"` + } + if err := json.Unmarshal([]byte(out), &status); err != nil || status.MountState != "mounted" || status.MountPath != mfs.MountPoint { + t.Fatalf("gfsctl status -o json: %v\n%s", err, out) + } + if out, err := ctl("health"); err != nil || !strings.Contains(out, "ok") { + t.Errorf("gfsctl health: %v\n%s", err, out) + } + if out, err := ctl("metrics"); err != nil || !strings.Contains(out, "goclusterfs_up 1") { + t.Errorf("gfsctl metrics: %v\n%s", err, out) + } +} diff --git a/tests/test-manifest.yaml b/tests/test-manifest.yaml index 6b26b955..bab13e38 100644 --- a/tests/test-manifest.yaml +++ b/tests/test-manifest.yaml @@ -2328,6 +2328,13 @@ scenarios: environments: go: api_test.go::TestMountRejectsBadAPISettingsBeforeOpeningDevice + - id: gfsctl-reads-live-mount + name: gfsctl reads a live mount + description: gfsctl status, health and metrics work against a mounted filesystem's API + priority: go_only + environments: + go: api_test.go::TestGfsctlReadsLiveMount + - id: api-stats-live-values name: API stats report live values description: After writes, reads, a delete and a mkdir, /api/v1/stats/{cache,journal,lock,trim,all,cluster} and /metrics show non-zero counters, /stats/sfb answers 404, and a second node sees both nodes and the first node's blocks