From 36869be575392e086e85e1e0ac82540fb0077d17 Mon Sep 17 00:00:00 2001 From: Matthew Mattox Date: Wed, 31 Dec 2025 04:19:15 -0600 Subject: [PATCH 1/8] feat(gfsctl): add a CLI client for the HTTP API The user's gfsctl from their uncommitted work, unchanged (5eb160f in #52). The following commits make it read-only and fix it. Adds spf13/cobra v1.10.2 and gopkg.in/yaml.v2 v2.4.0. Co-Authored-By: Claude Opus 5.5 --- cmd/gfsctl/client/api.go | 176 ++++++++++++++ cmd/gfsctl/client/client.go | 258 ++++++++++++++++++++ cmd/gfsctl/client/types.go | 271 +++++++++++++++++++++ cmd/gfsctl/commands/admin.go | 227 ++++++++++++++++++ cmd/gfsctl/commands/cluster.go | 202 ++++++++++++++++ cmd/gfsctl/commands/completion.go | 69 ++++++ cmd/gfsctl/commands/config.go | 131 +++++++++++ cmd/gfsctl/commands/config_cmd.go | 146 ++++++++++++ cmd/gfsctl/commands/health.go | 70 ++++++ cmd/gfsctl/commands/output.go | 209 +++++++++++++++++ cmd/gfsctl/commands/root.go | 102 ++++++++ cmd/gfsctl/commands/snapshot.go | 243 +++++++++++++++++++ cmd/gfsctl/commands/stats.go | 376 ++++++++++++++++++++++++++++++ cmd/gfsctl/commands/status.go | 145 ++++++++++++ cmd/gfsctl/commands/version.go | 59 +++++ cmd/gfsctl/commands/watch.go | 96 ++++++++ cmd/gfsctl/main.go | 36 +++ go.mod | 4 + go.sum | 11 + 19 files changed, 2831 insertions(+) create mode 100644 cmd/gfsctl/client/api.go create mode 100644 cmd/gfsctl/client/client.go create mode 100644 cmd/gfsctl/client/types.go create mode 100644 cmd/gfsctl/commands/admin.go create mode 100644 cmd/gfsctl/commands/cluster.go create mode 100644 cmd/gfsctl/commands/completion.go create mode 100644 cmd/gfsctl/commands/config.go create mode 100644 cmd/gfsctl/commands/config_cmd.go create mode 100644 cmd/gfsctl/commands/health.go create mode 100644 cmd/gfsctl/commands/output.go create mode 100644 cmd/gfsctl/commands/root.go create mode 100644 cmd/gfsctl/commands/snapshot.go create mode 100644 cmd/gfsctl/commands/stats.go create mode 100644 cmd/gfsctl/commands/status.go create mode 100644 cmd/gfsctl/commands/version.go create mode 100644 cmd/gfsctl/commands/watch.go create mode 100644 cmd/gfsctl/main.go diff --git a/cmd/gfsctl/client/api.go b/cmd/gfsctl/client/api.go new file mode 100644 index 00000000..30028b0d --- /dev/null +++ b/cmd/gfsctl/client/api.go @@ -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 +} diff --git a/cmd/gfsctl/client/client.go b/cmd/gfsctl/client/client.go new file mode 100644 index 00000000..9a1c1c65 --- /dev/null +++ b/cmd/gfsctl/client/client.go @@ -0,0 +1,258 @@ +// Package client provides an HTTP client for the GoClusterFS API. +package client + +import ( + "bytes" + "context" + "encoding/json" + "fmt" + "io" + "net/http" + "time" +) + +// Client is an HTTP client for the GoClusterFS API. +type Client struct { + baseURL string + token string + httpClient *http.Client +} + +// Option configures a Client. +type Option func(*Client) + +// WithHost sets the API server host. +func WithHost(host string) Option { + return func(c *Client) { + c.baseURL = fmt.Sprintf("http://%s", host) + } +} + +// WithPort sets the API server port. +func WithPort(port int) Option { + return func(c *Client) { + // Extract host from existing baseURL or default to localhost + host := "localhost" + if c.baseURL != "" { + // Parse existing host + if len(c.baseURL) > 7 { // len("http://") + host = c.baseURL[7:] + } + } + c.baseURL = fmt.Sprintf("http://%s:%d", host, 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{ + baseURL: "http://localhost:8080", + httpClient: &http.Client{ + Timeout: 30 * time.Second, + }, + } + for _, opt := range opts { + opt(c) + } + 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) +} + +// Post performs a POST request with JSON body and decodes the response into v. +func (c *Client) Post(ctx context.Context, path string, body interface{}, v interface{}) error { + respBody, err := c.doRequestWithBody(ctx, http.MethodPost, path, body) + if err != nil { + return err + } + if v != nil { + if err := json.Unmarshal(respBody, v); err != nil { + return fmt.Errorf("decode response: %w", err) + } + } + return nil +} + +// Delete performs a DELETE request and decodes the response into v. +func (c *Client) Delete(ctx context.Context, path string, v interface{}) error { + respBody, err := c.doRequest(ctx, http.MethodDelete, path) + if err != nil { + return err + } + if v != nil { + if err := json.Unmarshal(respBody, v); err != nil { + return fmt.Errorf("decode response: %w", err) + } + } + return nil +} + +// doRequestWithBody performs an HTTP request with a JSON body. +func (c *Client) doRequestWithBody(ctx context.Context, method, path string, body interface{}) ([]byte, error) { + url := c.baseURL + path + + var reqBody io.Reader + if body != nil { + data, err := json.Marshal(body) + if err != nil { + return nil, fmt.Errorf("encode request body: %w", err) + } + reqBody = bytes.NewReader(data) + } + + req, err := http.NewRequestWithContext(ctx, method, url, reqBody) + if err != nil { + return nil, fmt.Errorf("create request: %w", err) + } + + req.Header.Set("Accept", "application/json") + if body != nil { + req.Header.Set("Content-Type", "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() + + respData, 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(respData, &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 respData, nil +} + +// 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/types.go b/cmd/gfsctl/client/types.go new file mode 100644 index 00000000..2948ddc6 --- /dev/null +++ b/cmd/gfsctl/client/types.go @@ -0,0 +1,271 @@ +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"` +} + +// ClusterNodeInfo provides detailed information about a cluster node. +type ClusterNodeInfo struct { + NodeID string `json:"node_id"` + Address string `json:"address"` + Role string `json:"role"` + State string `json:"state"` + LastHeartbeat string `json:"last_heartbeat,omitempty"` + JoinedAt string `json:"joined_at,omitempty"` + Version string `json:"version,omitempty"` + LatencyMs float64 `json:"latency_ms,omitempty"` + IsSelf bool `json:"is_self"` +} + +// ClusterNodesResponse is returned by GET /api/v1/cluster/nodes. +type ClusterNodesResponse struct { + ClusterID string `json:"cluster_id,omitempty"` + TotalNodes int `json:"total_nodes"` + HealthyNodes int `json:"healthy_nodes"` + LeaderID string `json:"leader_id,omitempty"` + Nodes []ClusterNodeInfo `json:"nodes"` +} + +// DistributedLockInfo provides information about an active distributed lock. +type DistributedLockInfo struct { + LockID string `json:"lock_id"` + Resource string `json:"resource"` + OwnerNodeID string `json:"owner_node_id"` + OwnerProcess string `json:"owner_process,omitempty"` + AcquiredAt string `json:"acquired_at"` + ExpiresAt string `json:"expires_at,omitempty"` + LockType string `json:"lock_type"` +} + +// ClusterLocksResponse is returned by GET /api/v1/cluster/locks. +type ClusterLocksResponse struct { + ActiveLocks int `json:"active_locks"` + PendingLocks int `json:"pending_locks"` + Locks []DistributedLockInfo `json:"locks"` +} + +// 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"` +} + +// SnapshotInfo provides information about a snapshot. +type SnapshotInfo struct { + ID string `json:"id"` + Name string `json:"name"` + CreatedAt string `json:"created_at"` + SizeBytes uint64 `json:"size_bytes"` + Status string `json:"status"` + Description string `json:"description,omitempty"` +} + +// SnapshotListResponse is returned by GET /api/v1/snapshots. +type SnapshotListResponse struct { + Snapshots []SnapshotInfo `json:"snapshots"` + Total int `json:"total"` +} + +// SnapshotCreateRequest is sent to POST /api/v1/snapshots. +type SnapshotCreateRequest struct { + Name string `json:"name"` + Description string `json:"description,omitempty"` +} + +// SnapshotCreateResponse is returned by POST /api/v1/snapshots. +type SnapshotCreateResponse struct { + Snapshot SnapshotInfo `json:"snapshot"` + Message string `json:"message"` +} + +// SnapshotDeleteResponse is returned by DELETE /api/v1/snapshots/:id. +type SnapshotDeleteResponse struct { + ID string `json:"id"` + Message string `json:"message"` +} + +// AdminOperationResponse is returned by admin operations. +type AdminOperationResponse struct { + Operation string `json:"operation"` + Status string `json:"status"` + Message string `json:"message"` + Details string `json:"details,omitempty"` +} + +// FlushJournalRequest is sent to POST /api/v1/admin/flush-journal. +type FlushJournalRequest struct { + Force bool `json:"force,omitempty"` +} + +// ClearCacheRequest is sent to POST /api/v1/admin/clear-cache. +type ClearCacheRequest struct { + CacheType string `json:"cache_type,omitempty"` // all, inode, extent, negative +} + +// ForceTrimRequest is sent to POST /api/v1/admin/force-trim. +type ForceTrimRequest struct { + Force bool `json:"force,omitempty"` +} diff --git a/cmd/gfsctl/commands/admin.go b/cmd/gfsctl/commands/admin.go new file mode 100644 index 00000000..f221d2f3 --- /dev/null +++ b/cmd/gfsctl/commands/admin.go @@ -0,0 +1,227 @@ +package commands + +import ( + "context" + "fmt" + "os" + + "github.com/spf13/cobra" + + "github.com/supporttools/GoClusterFS/cmd/gfsctl/client" +) + +var adminCmd = &cobra.Command{ + Use: "admin [subcommand]", + Short: "Administrative commands", + Long: `Administrative operations for filesystem maintenance. + +Available subcommands: + flush-journal - Flush pending journal transactions to disk + clear-cache - Clear filesystem caches + force-trim - Force TRIM operation on the block device + +These commands require careful consideration and may impact performance +while running. Use --force to skip confirmation prompts. + +Examples: + gfsctl admin flush-journal # Flush journal with confirmation + gfsctl admin clear-cache # Clear all caches + gfsctl admin clear-cache --type inode # Clear only inode cache + gfsctl admin force-trim # Force TRIM operation`, + Args: cobra.MaximumNArgs(1), + RunE: runAdmin, +} + +var ( + adminForce bool + adminCacheType string +) + +func init() { + adminCmd.Flags().BoolVarP(&adminForce, "force", "f", false, "Skip confirmation prompts") + adminCmd.Flags().StringVar(&adminCacheType, "type", "all", "Cache type to clear (all, inode, extent, negative)") + rootCmd.AddCommand(adminCmd) +} + +func runAdmin(cmd *cobra.Command, args []string) error { + ctx := context.Background() + apiClient := GetClient() + f := NewFormatter(cmd.OutOrStdout(), GetOutputFormat()) + + if len(args) == 0 { + return fmt.Errorf("subcommand required (valid: flush-journal, clear-cache, force-trim)") + } + + subcmd := args[0] + + switch subcmd { + case "flush-journal": + return flushJournal(ctx, apiClient, f) + case "clear-cache": + return clearCache(ctx, apiClient, f) + case "force-trim": + return forceTrim(ctx, apiClient, f) + default: + return fmt.Errorf("unknown subcommand: %s (valid: flush-journal, clear-cache, force-trim)", subcmd) + } +} + +func flushJournal(ctx context.Context, c *client.Client, f *Formatter) error { + if !adminForce && !f.IsJSON() { + f.Printf("This will flush all pending journal transactions to disk.\n") + f.Printf("The operation may cause a brief pause in I/O operations.\n\n") + + if !confirmAction("Proceed with journal flush?") { + f.Printf("Cancelled.\n") + return nil + } + } + + if !f.IsJSON() { + f.Printf("Flushing journal...") + } + + req := &client.FlushJournalRequest{ + Force: adminForce, + } + + resp, err := c.AdminFlushJournal(ctx, req) + if err != nil { + if !f.IsJSON() { + f.Printf(" failed\n") + } + printError("failed to flush journal: %v", err) + return err + } + + if f.IsJSON() { + return f.JSON(resp) + } + + f.Printf(" done\n\n") + f.Header("Journal Flush Complete") + f.KeyValue("Operation", resp.Operation) + f.KeyValueColor("Status", resp.Status, statusColor(resp.Status)) + if resp.Message != "" { + f.KeyValue("Message", resp.Message) + } + if resp.Details != "" { + f.KeyValue("Details", resp.Details) + } + + fmt.Fprintln(os.Stdout) + return nil +} + +func clearCache(ctx context.Context, c *client.Client, f *Formatter) error { + cacheDesc := adminCacheType + if cacheDesc == "all" { + cacheDesc = "all caches" + } else { + cacheDesc = adminCacheType + " cache" + } + + if !adminForce && !f.IsJSON() { + f.Printf("This will clear %s.\n", cacheDesc) + f.Printf("Cached data will need to be re-read from disk.\n\n") + + if !confirmAction("Proceed with cache clear?") { + f.Printf("Cancelled.\n") + return nil + } + } + + if !f.IsJSON() { + f.Printf("Clearing %s...", cacheDesc) + } + + req := &client.ClearCacheRequest{ + CacheType: adminCacheType, + } + + resp, err := c.AdminClearCache(ctx, req) + if err != nil { + if !f.IsJSON() { + f.Printf(" failed\n") + } + printError("failed to clear cache: %v", err) + return err + } + + if f.IsJSON() { + return f.JSON(resp) + } + + f.Printf(" done\n\n") + f.Header("Cache Clear Complete") + f.KeyValue("Operation", resp.Operation) + f.KeyValueColor("Status", resp.Status, statusColor(resp.Status)) + if resp.Message != "" { + f.KeyValue("Message", resp.Message) + } + if resp.Details != "" { + f.KeyValue("Details", resp.Details) + } + + fmt.Fprintln(os.Stdout) + return nil +} + +func forceTrim(ctx context.Context, c *client.Client, f *Formatter) error { + if !adminForce && !f.IsJSON() { + f.Printf("This will force a TRIM operation on the underlying block device.\n") + f.Printf("This may take some time depending on the amount of free space.\n\n") + + if !confirmAction("Proceed with TRIM operation?") { + f.Printf("Cancelled.\n") + return nil + } + } + + if !f.IsJSON() { + f.Printf("Performing TRIM operation...") + } + + req := &client.ForceTrimRequest{ + Force: adminForce, + } + + resp, err := c.AdminForceTrim(ctx, req) + if err != nil { + if !f.IsJSON() { + f.Printf(" failed\n") + } + printError("failed to perform TRIM: %v", err) + return err + } + + if f.IsJSON() { + return f.JSON(resp) + } + + f.Printf(" done\n\n") + f.Header("TRIM Operation Complete") + f.KeyValue("Operation", resp.Operation) + f.KeyValueColor("Status", resp.Status, statusColor(resp.Status)) + if resp.Message != "" { + f.KeyValue("Message", resp.Message) + } + if resp.Details != "" { + f.KeyValue("Details", resp.Details) + } + + fmt.Fprintln(os.Stdout) + return nil +} + +// statusColor returns the color indicator for an operation status. +func statusColor(status string) string { + switch status { + case "success", "complete", "ok": + return "ok" + case "failed", "error": + return "error" + default: + return "warning" + } +} diff --git a/cmd/gfsctl/commands/cluster.go b/cmd/gfsctl/commands/cluster.go new file mode 100644 index 00000000..c82e7051 --- /dev/null +++ b/cmd/gfsctl/commands/cluster.go @@ -0,0 +1,202 @@ +package commands + +import ( + "context" + "fmt" + "os" + + "github.com/spf13/cobra" + + "github.com/supporttools/GoClusterFS/cmd/gfsctl/client" +) + +var clusterCmd = &cobra.Command{ + Use: "cluster [subcommand]", + Short: "Cluster management commands", + Long: `Manage and inspect cluster state. + +Available subcommands: + status - Show cluster status + nodes - List cluster nodes + locks - Show active distributed locks + +Examples: + gfsctl cluster status # Show cluster status + gfsctl cluster nodes # List all nodes + gfsctl cluster locks # Show distributed locks`, + Args: cobra.MaximumNArgs(1), + RunE: runCluster, +} + +func init() { + rootCmd.AddCommand(clusterCmd) +} + +func runCluster(cmd *cobra.Command, args []string) error { + ctx := context.Background() + apiClient := GetClient() + f := NewFormatter(cmd.OutOrStdout(), GetOutputFormat()) + + // Determine which subcommand + subcmd := "status" + if len(args) > 0 { + subcmd = args[0] + } + + switch subcmd { + case "status": + return showClusterStatus(ctx, apiClient, f) + case "nodes": + return showClusterNodes(ctx, apiClient, f) + case "locks": + return showClusterLocks(ctx, apiClient, f) + default: + return fmt.Errorf("unknown subcommand: %s (valid: status, nodes, locks)", subcmd) + } +} + +func showClusterStatus(ctx context.Context, c *client.Client, f *Formatter) error { + status, err := c.ClusterStatus(ctx) + if err != nil { + printError("failed to get cluster status: %v", err) + return err + } + + if f.IsJSON() { + return f.JSON(status) + } + + f.Header("Cluster Status") + + f.KeyValue("Node ID", status.NodeID) + if status.NodeAddress != "" { + f.KeyValue("Address", status.NodeAddress) + } + + roleColor := "follower" + if status.Role == "leader" { + roleColor = "leader" + } + f.KeyValueColor("Role", status.Role, roleColor) + + stateColor := "ok" + if status.State != "active" { + stateColor = "warning" + } + f.KeyValueColor("State", status.State, stateColor) + + f.KeyValue("Cluster Size", fmt.Sprintf("%d", status.ClusterSize)) + + healthColor := "ok" + if status.HealthyNodes < status.ClusterSize { + healthColor = "warning" + } + f.KeyValueColor("Healthy Nodes", fmt.Sprintf("%d/%d", status.HealthyNodes, status.ClusterSize), healthColor) + + if status.LeaderID != "" { + f.KeyValue("Leader ID", status.LeaderID) + } + if status.LastHeartbeatAt != "" { + f.KeyValue("Last Heartbeat", status.LastHeartbeatAt) + } + if status.JoinedAt != "" { + f.KeyValue("Joined At", status.JoinedAt) + } + + // Show peers if present + if len(status.Peers) > 0 { + f.Header("Peers") + table := f.NewTable("Node ID", "Address", "State", "Latency") + for _, peer := range status.Peers { + latency := "-" + if peer.Latency > 0 { + latency = fmt.Sprintf("%.1fms", peer.Latency) + } + table.AddRow(peer.NodeID, peer.Address, peer.State, latency) + } + table.Render() + } + + fmt.Fprintln(os.Stdout) + return nil +} + +func showClusterNodes(ctx context.Context, c *client.Client, f *Formatter) error { + nodes, err := c.ClusterNodes(ctx) + if err != nil { + printError("failed to get cluster nodes: %v", err) + return err + } + + if f.IsJSON() { + return f.JSON(nodes) + } + + f.Header("Cluster Nodes") + + if nodes.ClusterID != "" { + f.KeyValue("Cluster ID", nodes.ClusterID) + } + f.KeyValue("Total Nodes", fmt.Sprintf("%d", nodes.TotalNodes)) + + healthColor := "ok" + if nodes.HealthyNodes < nodes.TotalNodes { + healthColor = "warning" + } + f.KeyValueColor("Healthy Nodes", fmt.Sprintf("%d", nodes.HealthyNodes), healthColor) + + if nodes.LeaderID != "" { + f.KeyValue("Leader", nodes.LeaderID) + } + + if len(nodes.Nodes) > 0 { + f.Printf("\n") + table := f.NewTable("Node ID", "Address", "Role", "State", "Latency", "Self") + for _, node := range nodes.Nodes { + latency := "-" + if node.LatencyMs > 0 { + latency = fmt.Sprintf("%.1fms", node.LatencyMs) + } + self := "" + if node.IsSelf { + self = "*" + } + table.AddRow(node.NodeID, node.Address, node.Role, node.State, latency, self) + } + table.Render() + } + + fmt.Fprintln(os.Stdout) + return nil +} + +func showClusterLocks(ctx context.Context, c *client.Client, f *Formatter) error { + locks, err := c.ClusterLocks(ctx) + if err != nil { + printError("failed to get cluster locks: %v", err) + return err + } + + if f.IsJSON() { + return f.JSON(locks) + } + + f.Header("Distributed Locks") + + f.KeyValue("Active Locks", fmt.Sprintf("%d", locks.ActiveLocks)) + f.KeyValue("Pending Locks", fmt.Sprintf("%d", locks.PendingLocks)) + + if len(locks.Locks) > 0 { + f.Printf("\n") + table := f.NewTable("Lock ID", "Resource", "Type", "Owner Node", "Acquired At") + for _, lock := range locks.Locks { + table.AddRow(lock.LockID, lock.Resource, lock.LockType, lock.OwnerNodeID, lock.AcquiredAt) + } + table.Render() + } else { + f.Printf("\n (no active locks)\n") + } + + fmt.Fprintln(os.Stdout) + return nil +} diff --git a/cmd/gfsctl/commands/completion.go b/cmd/gfsctl/commands/completion.go new file mode 100644 index 00000000..569b613a --- /dev/null +++ b/cmd/gfsctl/commands/completion.go @@ -0,0 +1,69 @@ +package commands + +import ( + "os" + + "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(os.Stdout) + case "zsh": + return rootCmd.GenZshCompletion(os.Stdout) + case "fish": + return rootCmd.GenFishCompletion(os.Stdout, true) + case "powershell": + return rootCmd.GenPowerShellCompletionWithDesc(os.Stdout) + } + 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..d55533d3 --- /dev/null +++ b/cmd/gfsctl/commands/config.go @@ -0,0 +1,131 @@ +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 +} + +// initConfig loads the config file and applies values to global flags. +// Environment variables and command-line flags take precedence. +func initConfig() { + cfg, err := loadConfig() + if err != nil { + // Silently ignore config errors - CLI should still work + return + } + + // Apply config values only if not already set by env/flag + // Note: cobra doesn't easily support checking if a flag was set, + // so we check if values are at their defaults + + if cfg.Host != "" && cfgHost == "localhost" && os.Getenv("GFSCTL_HOST") == "" { + cfgHost = cfg.Host + } + + if cfg.Port != 0 && cfgPort == 8080 && os.Getenv("GFSCTL_PORT") == "" { + cfgPort = cfg.Port + } + + if cfg.Token != "" && cfgToken == "" && os.Getenv("GFSCTL_TOKEN") == "" { + cfgToken = cfg.Token + } + + if cfg.Output != "" && cfgOutput == "text" && os.Getenv("GFSCTL_OUTPUT") == "" { + cfgOutput = cfg.Output + } + + if cfg.Timeout != 0 && cfgTimeout == 30*time.Second && os.Getenv("GFSCTL_TIMEOUT") == "" { + cfgTimeout = cfg.Timeout + } +} + +// 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..7917210a --- /dev/null +++ b/cmd/gfsctl/commands/config_cmd.go @@ -0,0 +1,146 @@ +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()) + + fmt.Fprintln(os.Stdout) + return nil +} + +func initConfigFile(cmd *cobra.Command) error { + path := configPath() + if path == "" { + printError("unable to determine config directory") + return fmt.Errorf("unable to determine config directory") + } + + // Check if file already exists + if _, err := os.Stat(path); err == nil { + printError("config file already exists: %s", path) + 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 { + printError("failed to create config directory: %v", err) + return err + } + + // Write sample config + content := GenerateSampleConfig() + if err := os.WriteFile(path, []byte(content), 0600); err != nil { + printError("failed to write config file: %v", err) + return 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..baedf590 --- /dev/null +++ b/cmd/gfsctl/commands/health.go @@ -0,0 +1,70 @@ +package commands + +import ( + "context" + "fmt" + "os" + + "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 { + printError("failed to get health: %v", err) + return 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) + } + } + + fmt.Fprintln(os.Stdout) + + // Return error if unhealthy (for scripting) + if health.Status == "unhealthy" { + return fmt.Errorf("filesystem is unhealthy") + } + + return nil +} diff --git a/cmd/gfsctl/commands/output.go b/cmd/gfsctl/commands/output.go new file mode 100644 index 00000000..e1e9c81c --- /dev/null +++ b/cmd/gfsctl/commands/output.go @@ -0,0 +1,209 @@ +package commands + +import ( + "encoding/json" + "fmt" + "io" + "strings" +) + +// Formatter provides output formatting utilities. +type Formatter struct { + w io.Writer + format string +} + +// NewFormatter creates a new formatter with the given writer and format. +func NewFormatter(w io.Writer, format string) *Formatter { + return &Formatter{w: w, format: format} +} + +// 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) { + colored := colorize(value, status) + fmt.Fprintf(f.w, " %-20s %s\n", key+":", colored) +} + +// 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..ba1b14c3 --- /dev/null +++ b/cmd/gfsctl/commands/root.go @@ -0,0 +1,102 @@ +// Package commands implements the gfsctl CLI commands. +package commands + +import ( + "fmt" + "os" + "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 communicates with a running GoClusterFS mount via its HTTP API +to query status, statistics, and perform administrative operations. + +Examples: + gfsctl status # Show filesystem status + gfsctl health # Check health status + gfsctl stats cache # Show cache statistics + gfsctl cluster nodes # List cluster nodes + gfsctl --host 10.0.0.1 status # Connect to remote host`, + SilenceUsage: true, + SilenceErrors: true, + PersistentPreRunE: func(cmd *cobra.Command, args []string) error { + // Skip client initialization for version command + if cmd.Name() == "version" { + return nil + } + + // Create API client with configured options + apiClient = client.New( + client.WithHost(cfgHost), + client.WithPort(cfgPort), + client.WithToken(cfgToken), + client.WithTimeout(cfgTimeout), + ) + return nil + }, +} + +// Execute runs the root command. +func Execute() error { + return rootCmd.Execute() +} + +func init() { + // Global flags available to all commands + 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") + rootCmd.PersistentFlags().DurationVar(&cfgTimeout, "timeout", 30*time.Second, "Request timeout") + rootCmd.PersistentFlags().StringVarP(&cfgOutput, "output", "o", "text", "Output format (text, json)") + + // Load configuration file (lowest priority) + initConfig() + + // Environment variable fallbacks (higher priority than config file) + if host := os.Getenv("GFSCTL_HOST"); host != "" { + cfgHost = host + } + if token := os.Getenv("GFSCTL_TOKEN"); token != "" { + cfgToken = token + } + if output := os.Getenv("GFSCTL_OUTPUT"); output != "" { + cfgOutput = output + } +} + +// 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 +} + +// printError prints an error message to stderr. +func printError(format string, args ...interface{}) { + fmt.Fprintf(os.Stderr, "Error: "+format+"\n", args...) +} diff --git a/cmd/gfsctl/commands/snapshot.go b/cmd/gfsctl/commands/snapshot.go new file mode 100644 index 00000000..94d83de5 --- /dev/null +++ b/cmd/gfsctl/commands/snapshot.go @@ -0,0 +1,243 @@ +package commands + +import ( + "bufio" + "context" + "fmt" + "os" + "strings" + + "github.com/spf13/cobra" + + "github.com/supporttools/GoClusterFS/cmd/gfsctl/client" +) + +var snapshotCmd = &cobra.Command{ + Use: "snapshot [subcommand]", + Short: "Snapshot management commands", + Long: `Manage filesystem snapshots. + +Available subcommands: + list - List all snapshots + create - Create a new snapshot + delete - Delete a snapshot + info - Show snapshot details + +Examples: + gfsctl snapshot list # List all snapshots + gfsctl snapshot create mysnap # Create snapshot named "mysnap" + gfsctl snapshot delete snap-123 # Delete snapshot by ID + gfsctl snapshot info snap-123 # Show snapshot details`, + Args: cobra.MaximumNArgs(2), + RunE: runSnapshot, +} + +var ( + snapshotDescription string + snapshotForce bool +) + +func init() { + snapshotCmd.Flags().StringVarP(&snapshotDescription, "description", "d", "", "Snapshot description (for create)") + snapshotCmd.Flags().BoolVarP(&snapshotForce, "force", "f", false, "Skip confirmation prompts") + rootCmd.AddCommand(snapshotCmd) +} + +func runSnapshot(cmd *cobra.Command, args []string) error { + ctx := context.Background() + apiClient := GetClient() + f := NewFormatter(cmd.OutOrStdout(), GetOutputFormat()) + + // Determine which subcommand + subcmd := "list" + if len(args) > 0 { + subcmd = args[0] + } + + switch subcmd { + case "list": + return listSnapshots(ctx, apiClient, f) + case "create": + if len(args) < 2 { + return fmt.Errorf("snapshot name required: gfsctl snapshot create ") + } + return createSnapshot(ctx, apiClient, f, args[1]) + case "delete": + if len(args) < 2 { + return fmt.Errorf("snapshot ID required: gfsctl snapshot delete ") + } + return deleteSnapshot(ctx, apiClient, f, args[1]) + case "info": + if len(args) < 2 { + return fmt.Errorf("snapshot ID required: gfsctl snapshot info ") + } + return showSnapshotInfo(ctx, apiClient, f, args[1]) + default: + return fmt.Errorf("unknown subcommand: %s (valid: list, create, delete, info)", subcmd) + } +} + +func listSnapshots(ctx context.Context, c *client.Client, f *Formatter) error { + resp, err := c.SnapshotList(ctx) + if err != nil { + printError("failed to list snapshots: %v", err) + return err + } + + if f.IsJSON() { + return f.JSON(resp) + } + + f.Header("Snapshots") + f.KeyValue("Total", fmt.Sprintf("%d", resp.Total)) + + if len(resp.Snapshots) > 0 { + f.Printf("\n") + table := f.NewTable("ID", "Name", "Created", "Size", "Status") + for _, snap := range resp.Snapshots { + table.AddRow(snap.ID, snap.Name, snap.CreatedAt, FormatBytes(snap.SizeBytes), snap.Status) + } + table.Render() + } else { + f.Printf("\n (no snapshots)\n") + } + + fmt.Fprintln(os.Stdout) + return nil +} + +func createSnapshot(ctx context.Context, c *client.Client, f *Formatter, name string) error { + // Show what we're about to do + if !snapshotForce && !f.IsJSON() { + f.Printf("Creating snapshot: %s\n", name) + if snapshotDescription != "" { + f.Printf("Description: %s\n", snapshotDescription) + } + if !confirmAction("Create this snapshot?") { + f.Printf("Cancelled.\n") + return nil + } + } + + req := &client.SnapshotCreateRequest{ + Name: name, + Description: snapshotDescription, + } + + // Show progress + if !f.IsJSON() { + f.Printf("Creating snapshot...") + } + + resp, err := c.SnapshotCreate(ctx, req) + if err != nil { + if !f.IsJSON() { + f.Printf(" failed\n") + } + printError("failed to create snapshot: %v", err) + return err + } + + if f.IsJSON() { + return f.JSON(resp) + } + + f.Printf(" done\n\n") + f.Header("Snapshot Created") + f.KeyValue("ID", resp.Snapshot.ID) + f.KeyValue("Name", resp.Snapshot.Name) + f.KeyValue("Created At", resp.Snapshot.CreatedAt) + f.KeyValueColor("Status", resp.Snapshot.Status, "ok") + + fmt.Fprintln(os.Stdout) + return nil +} + +func deleteSnapshot(ctx context.Context, c *client.Client, f *Formatter, id string) error { + // Get snapshot info first for confirmation + if !snapshotForce && !f.IsJSON() { + info, err := c.SnapshotInfo(ctx, id) + if err != nil { + printError("failed to get snapshot info: %v", err) + return err + } + + f.Printf("Snapshot to delete:\n") + f.KeyValue("ID", info.ID) + f.KeyValue("Name", info.Name) + f.KeyValue("Size", FormatBytes(info.SizeBytes)) + f.Printf("\n") + + if !confirmAction("Delete this snapshot? This cannot be undone.") { + f.Printf("Cancelled.\n") + return nil + } + } + + // Show progress + if !f.IsJSON() { + f.Printf("Deleting snapshot...") + } + + resp, err := c.SnapshotDelete(ctx, id) + if err != nil { + if !f.IsJSON() { + f.Printf(" failed\n") + } + printError("failed to delete snapshot: %v", err) + return err + } + + if f.IsJSON() { + return f.JSON(resp) + } + + f.Printf(" done\n") + f.Printf("Snapshot %s deleted.\n", resp.ID) + + fmt.Fprintln(os.Stdout) + return nil +} + +func showSnapshotInfo(ctx context.Context, c *client.Client, f *Formatter, id string) error { + info, err := c.SnapshotInfo(ctx, id) + if err != nil { + printError("failed to get snapshot info: %v", err) + return err + } + + if f.IsJSON() { + return f.JSON(info) + } + + f.Header("Snapshot Details") + f.KeyValue("ID", info.ID) + f.KeyValue("Name", info.Name) + f.KeyValue("Created At", info.CreatedAt) + f.KeyValue("Size", FormatBytes(info.SizeBytes)) + + statusColor := "ok" + if info.Status != "complete" && info.Status != "ready" { + statusColor = "warning" + } + f.KeyValueColor("Status", info.Status, statusColor) + + if info.Description != "" { + f.KeyValue("Description", info.Description) + } + + fmt.Fprintln(os.Stdout) + return nil +} + +// confirmAction prompts the user for confirmation. +func confirmAction(prompt string) bool { + reader := bufio.NewReader(os.Stdin) + fmt.Printf("%s [y/N]: ", prompt) + response, err := reader.ReadString('\n') + if err != nil { + return false + } + response = strings.TrimSpace(strings.ToLower(response)) + return response == "y" || response == "yes" +} diff --git a/cmd/gfsctl/commands/stats.go b/cmd/gfsctl/commands/stats.go new file mode 100644 index 00000000..01ffd15c --- /dev/null +++ b/cmd/gfsctl/commands/stats.go @@ -0,0 +1,376 @@ +package commands + +import ( + "context" + "fmt" + "os" + "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 + 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" { + printError("watch mode is not compatible with JSON output") + 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", "all": + // valid + default: + return fmt.Errorf("unknown component: %s (valid: cache, journal, trim, lock, sfb, 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 "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 { + printError("failed to get stats: %v", err) + return 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)) + } + + fmt.Fprintln(os.Stdout) + return nil +} + +func showCacheStats(ctx context.Context, c *client.Client, f *Formatter) error { + stats, err := c.CacheStats(ctx) + if err != nil { + printError("failed to get cache stats: %v", err) + return 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() + + fmt.Fprintln(os.Stdout) + return nil +} + +func showJournalStats(ctx context.Context, c *client.Client, f *Formatter) error { + stats, err := c.JournalStats(ctx) + if err != nil { + printError("failed to get journal stats: %v", err) + return 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)) + + fmt.Fprintln(os.Stdout) + return nil +} + +func showTrimStats(ctx context.Context, c *client.Client, f *Formatter) error { + stats, err := c.TrimStats(ctx) + if err != nil { + printError("failed to get trim stats: %v", err) + return 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) + } + + fmt.Fprintln(os.Stdout) + return nil +} + +func showLockStats(ctx context.Context, c *client.Client, f *Formatter) error { + stats, err := c.LockStats(ctx) + if err != nil { + printError("failed to get lock stats: %v", err) + return 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)) + + fmt.Fprintln(os.Stdout) + return nil +} + +func showSFBStats(ctx context.Context, c *client.Client, f *Formatter) error { + stats, err := c.SFBStats(ctx) + if err != nil { + printError("failed to get sfb stats: %v", err) + return 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") + } + + fmt.Fprintln(os.Stdout) + return nil +} + +func showAllStats(ctx context.Context, c *client.Client, f *Formatter) error { + stats, err := c.AllStats(ctx) + if err != nil { + printError("failed to get all stats: %v", err) + return 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)) + } + + fmt.Fprintln(os.Stdout) + return nil +} diff --git a/cmd/gfsctl/commands/status.go b/cmd/gfsctl/commands/status.go new file mode 100644 index 00000000..2f523955 --- /dev/null +++ b/cmd/gfsctl/commands/status.go @@ -0,0 +1,145 @@ +package commands + +import ( + "context" + "fmt" + "os" + "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" { + printError("watch mode is not compatible with JSON output") + 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 { + printError("failed to get status: %v", err) + return 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) + } + } + + fmt.Fprintln(os.Stdout) + return nil +} diff --git a/cmd/gfsctl/commands/version.go b/cmd/gfsctl/commands/version.go new file mode 100644 index 00000000..cf2da86f --- /dev/null +++ b/cmd/gfsctl/commands/version.go @@ -0,0 +1,59 @@ +package commands + +import ( + "encoding/json" + "fmt" + "runtime" + + "github.com/spf13/cobra" +) + +var ( + // Version information, set at build time via ldflags + Version = "dev" + GitCommit = "unknown" + BuildTime = "unknown" +) + +// 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, + GitCommit: GitCommit, + BuildTime: BuildTime, + 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..3df45691 --- /dev/null +++ b/cmd/gfsctl/main.go @@ -0,0 +1,36 @@ +// Command gfsctl is the management CLI for GoClusterFS. +// +// gfsctl communicates with a running GoClusterFS mount via its HTTP API +// to query status, statistics, and perform administrative operations. +// +// Usage: +// +// gfsctl [global flags] [command flags] +// +// Global flags: +// +// --host API server host (default: localhost) +// --port API server port (default: 8080) +// --token Bearer token for authentication +// --timeout Request timeout (default: 30s) +// +// Commands: +// +// status Show filesystem status +// health Check filesystem health +// stats Show component statistics +// cluster Cluster management commands +// version Show version information +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/go.mod b/go.mod index b18f9c14..6664a50c 100644 --- a/go.mod +++ b/go.mod @@ -6,17 +6,21 @@ 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 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 github.com/prometheus/common v0.66.1 // indirect github.com/prometheus/procfs v0.16.1 // indirect + github.com/spf13/pflag v1.0.9 // indirect go.yaml.in/yaml/v2 v2.4.2 // indirect google.golang.org/protobuf v1.36.8 // 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= From e2f61792511734f8e8e189a38b974fd8496fad8f Mon Sep 17 00:00:00 2001 From: Matthew Mattox Date: Tue, 10 Nov 2026 16:03:21 -0600 Subject: [PATCH 2/8] refactor(gfsctl): drop the write and cluster commands snapshot and admin change the filesystem through endpoints the server does not have yet; they come back with those endpoints. cluster called /api/v1/cluster/*, which is not on main. The client keeps GET only. Co-Authored-By: Claude Opus 5.5 --- cmd/gfsctl/client/api.go | 90 ------------ cmd/gfsctl/client/client.go | 84 ----------- cmd/gfsctl/client/types.go | 97 ------------- cmd/gfsctl/commands/admin.go | 227 ----------------------------- cmd/gfsctl/commands/cluster.go | 202 -------------------------- cmd/gfsctl/commands/snapshot.go | 243 -------------------------------- 6 files changed, 943 deletions(-) delete mode 100644 cmd/gfsctl/commands/admin.go delete mode 100644 cmd/gfsctl/commands/cluster.go delete mode 100644 cmd/gfsctl/commands/snapshot.go diff --git a/cmd/gfsctl/client/api.go b/cmd/gfsctl/client/api.go index 30028b0d..3aae93c2 100644 --- a/cmd/gfsctl/client/api.go +++ b/cmd/gfsctl/client/api.go @@ -84,93 +84,3 @@ func (c *Client) AllStats(ctx context.Context) (*AllStatsResponse, error) { } 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 -} diff --git a/cmd/gfsctl/client/client.go b/cmd/gfsctl/client/client.go index 9a1c1c65..364ac24b 100644 --- a/cmd/gfsctl/client/client.go +++ b/cmd/gfsctl/client/client.go @@ -2,7 +2,6 @@ package client import ( - "bytes" "context" "encoding/json" "fmt" @@ -138,89 +137,6 @@ func (c *Client) GetRaw(ctx context.Context, path string) ([]byte, error) { return c.doRequest(ctx, http.MethodGet, path) } -// Post performs a POST request with JSON body and decodes the response into v. -func (c *Client) Post(ctx context.Context, path string, body interface{}, v interface{}) error { - respBody, err := c.doRequestWithBody(ctx, http.MethodPost, path, body) - if err != nil { - return err - } - if v != nil { - if err := json.Unmarshal(respBody, v); err != nil { - return fmt.Errorf("decode response: %w", err) - } - } - return nil -} - -// Delete performs a DELETE request and decodes the response into v. -func (c *Client) Delete(ctx context.Context, path string, v interface{}) error { - respBody, err := c.doRequest(ctx, http.MethodDelete, path) - if err != nil { - return err - } - if v != nil { - if err := json.Unmarshal(respBody, v); err != nil { - return fmt.Errorf("decode response: %w", err) - } - } - return nil -} - -// doRequestWithBody performs an HTTP request with a JSON body. -func (c *Client) doRequestWithBody(ctx context.Context, method, path string, body interface{}) ([]byte, error) { - url := c.baseURL + path - - var reqBody io.Reader - if body != nil { - data, err := json.Marshal(body) - if err != nil { - return nil, fmt.Errorf("encode request body: %w", err) - } - reqBody = bytes.NewReader(data) - } - - req, err := http.NewRequestWithContext(ctx, method, url, reqBody) - if err != nil { - return nil, fmt.Errorf("create request: %w", err) - } - - req.Header.Set("Accept", "application/json") - if body != nil { - req.Header.Set("Content-Type", "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() - - respData, 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(respData, &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 respData, nil -} - // ErrorResponse represents an API error response. type ErrorResponse struct { Error string `json:"error"` diff --git a/cmd/gfsctl/client/types.go b/cmd/gfsctl/client/types.go index 2948ddc6..f834176c 100644 --- a/cmd/gfsctl/client/types.go +++ b/cmd/gfsctl/client/types.go @@ -156,46 +156,6 @@ type ClusterInfoResponse struct { Peers []ClusterPeerInfo `json:"peers,omitempty"` } -// ClusterNodeInfo provides detailed information about a cluster node. -type ClusterNodeInfo struct { - NodeID string `json:"node_id"` - Address string `json:"address"` - Role string `json:"role"` - State string `json:"state"` - LastHeartbeat string `json:"last_heartbeat,omitempty"` - JoinedAt string `json:"joined_at,omitempty"` - Version string `json:"version,omitempty"` - LatencyMs float64 `json:"latency_ms,omitempty"` - IsSelf bool `json:"is_self"` -} - -// ClusterNodesResponse is returned by GET /api/v1/cluster/nodes. -type ClusterNodesResponse struct { - ClusterID string `json:"cluster_id,omitempty"` - TotalNodes int `json:"total_nodes"` - HealthyNodes int `json:"healthy_nodes"` - LeaderID string `json:"leader_id,omitempty"` - Nodes []ClusterNodeInfo `json:"nodes"` -} - -// DistributedLockInfo provides information about an active distributed lock. -type DistributedLockInfo struct { - LockID string `json:"lock_id"` - Resource string `json:"resource"` - OwnerNodeID string `json:"owner_node_id"` - OwnerProcess string `json:"owner_process,omitempty"` - AcquiredAt string `json:"acquired_at"` - ExpiresAt string `json:"expires_at,omitempty"` - LockType string `json:"lock_type"` -} - -// ClusterLocksResponse is returned by GET /api/v1/cluster/locks. -type ClusterLocksResponse struct { - ActiveLocks int `json:"active_locks"` - PendingLocks int `json:"pending_locks"` - Locks []DistributedLockInfo `json:"locks"` -} - // AllStatsResponse is returned by GET /api/v1/stats/all. type AllStatsResponse struct { CollectedAt string `json:"collected_at"` @@ -212,60 +172,3 @@ type StatsOverviewResponse struct { Cache *CacheStatsResponse `json:"cache,omitempty"` Journal *JournalStatsResponse `json:"journal,omitempty"` } - -// SnapshotInfo provides information about a snapshot. -type SnapshotInfo struct { - ID string `json:"id"` - Name string `json:"name"` - CreatedAt string `json:"created_at"` - SizeBytes uint64 `json:"size_bytes"` - Status string `json:"status"` - Description string `json:"description,omitempty"` -} - -// SnapshotListResponse is returned by GET /api/v1/snapshots. -type SnapshotListResponse struct { - Snapshots []SnapshotInfo `json:"snapshots"` - Total int `json:"total"` -} - -// SnapshotCreateRequest is sent to POST /api/v1/snapshots. -type SnapshotCreateRequest struct { - Name string `json:"name"` - Description string `json:"description,omitempty"` -} - -// SnapshotCreateResponse is returned by POST /api/v1/snapshots. -type SnapshotCreateResponse struct { - Snapshot SnapshotInfo `json:"snapshot"` - Message string `json:"message"` -} - -// SnapshotDeleteResponse is returned by DELETE /api/v1/snapshots/:id. -type SnapshotDeleteResponse struct { - ID string `json:"id"` - Message string `json:"message"` -} - -// AdminOperationResponse is returned by admin operations. -type AdminOperationResponse struct { - Operation string `json:"operation"` - Status string `json:"status"` - Message string `json:"message"` - Details string `json:"details,omitempty"` -} - -// FlushJournalRequest is sent to POST /api/v1/admin/flush-journal. -type FlushJournalRequest struct { - Force bool `json:"force,omitempty"` -} - -// ClearCacheRequest is sent to POST /api/v1/admin/clear-cache. -type ClearCacheRequest struct { - CacheType string `json:"cache_type,omitempty"` // all, inode, extent, negative -} - -// ForceTrimRequest is sent to POST /api/v1/admin/force-trim. -type ForceTrimRequest struct { - Force bool `json:"force,omitempty"` -} diff --git a/cmd/gfsctl/commands/admin.go b/cmd/gfsctl/commands/admin.go deleted file mode 100644 index f221d2f3..00000000 --- a/cmd/gfsctl/commands/admin.go +++ /dev/null @@ -1,227 +0,0 @@ -package commands - -import ( - "context" - "fmt" - "os" - - "github.com/spf13/cobra" - - "github.com/supporttools/GoClusterFS/cmd/gfsctl/client" -) - -var adminCmd = &cobra.Command{ - Use: "admin [subcommand]", - Short: "Administrative commands", - Long: `Administrative operations for filesystem maintenance. - -Available subcommands: - flush-journal - Flush pending journal transactions to disk - clear-cache - Clear filesystem caches - force-trim - Force TRIM operation on the block device - -These commands require careful consideration and may impact performance -while running. Use --force to skip confirmation prompts. - -Examples: - gfsctl admin flush-journal # Flush journal with confirmation - gfsctl admin clear-cache # Clear all caches - gfsctl admin clear-cache --type inode # Clear only inode cache - gfsctl admin force-trim # Force TRIM operation`, - Args: cobra.MaximumNArgs(1), - RunE: runAdmin, -} - -var ( - adminForce bool - adminCacheType string -) - -func init() { - adminCmd.Flags().BoolVarP(&adminForce, "force", "f", false, "Skip confirmation prompts") - adminCmd.Flags().StringVar(&adminCacheType, "type", "all", "Cache type to clear (all, inode, extent, negative)") - rootCmd.AddCommand(adminCmd) -} - -func runAdmin(cmd *cobra.Command, args []string) error { - ctx := context.Background() - apiClient := GetClient() - f := NewFormatter(cmd.OutOrStdout(), GetOutputFormat()) - - if len(args) == 0 { - return fmt.Errorf("subcommand required (valid: flush-journal, clear-cache, force-trim)") - } - - subcmd := args[0] - - switch subcmd { - case "flush-journal": - return flushJournal(ctx, apiClient, f) - case "clear-cache": - return clearCache(ctx, apiClient, f) - case "force-trim": - return forceTrim(ctx, apiClient, f) - default: - return fmt.Errorf("unknown subcommand: %s (valid: flush-journal, clear-cache, force-trim)", subcmd) - } -} - -func flushJournal(ctx context.Context, c *client.Client, f *Formatter) error { - if !adminForce && !f.IsJSON() { - f.Printf("This will flush all pending journal transactions to disk.\n") - f.Printf("The operation may cause a brief pause in I/O operations.\n\n") - - if !confirmAction("Proceed with journal flush?") { - f.Printf("Cancelled.\n") - return nil - } - } - - if !f.IsJSON() { - f.Printf("Flushing journal...") - } - - req := &client.FlushJournalRequest{ - Force: adminForce, - } - - resp, err := c.AdminFlushJournal(ctx, req) - if err != nil { - if !f.IsJSON() { - f.Printf(" failed\n") - } - printError("failed to flush journal: %v", err) - return err - } - - if f.IsJSON() { - return f.JSON(resp) - } - - f.Printf(" done\n\n") - f.Header("Journal Flush Complete") - f.KeyValue("Operation", resp.Operation) - f.KeyValueColor("Status", resp.Status, statusColor(resp.Status)) - if resp.Message != "" { - f.KeyValue("Message", resp.Message) - } - if resp.Details != "" { - f.KeyValue("Details", resp.Details) - } - - fmt.Fprintln(os.Stdout) - return nil -} - -func clearCache(ctx context.Context, c *client.Client, f *Formatter) error { - cacheDesc := adminCacheType - if cacheDesc == "all" { - cacheDesc = "all caches" - } else { - cacheDesc = adminCacheType + " cache" - } - - if !adminForce && !f.IsJSON() { - f.Printf("This will clear %s.\n", cacheDesc) - f.Printf("Cached data will need to be re-read from disk.\n\n") - - if !confirmAction("Proceed with cache clear?") { - f.Printf("Cancelled.\n") - return nil - } - } - - if !f.IsJSON() { - f.Printf("Clearing %s...", cacheDesc) - } - - req := &client.ClearCacheRequest{ - CacheType: adminCacheType, - } - - resp, err := c.AdminClearCache(ctx, req) - if err != nil { - if !f.IsJSON() { - f.Printf(" failed\n") - } - printError("failed to clear cache: %v", err) - return err - } - - if f.IsJSON() { - return f.JSON(resp) - } - - f.Printf(" done\n\n") - f.Header("Cache Clear Complete") - f.KeyValue("Operation", resp.Operation) - f.KeyValueColor("Status", resp.Status, statusColor(resp.Status)) - if resp.Message != "" { - f.KeyValue("Message", resp.Message) - } - if resp.Details != "" { - f.KeyValue("Details", resp.Details) - } - - fmt.Fprintln(os.Stdout) - return nil -} - -func forceTrim(ctx context.Context, c *client.Client, f *Formatter) error { - if !adminForce && !f.IsJSON() { - f.Printf("This will force a TRIM operation on the underlying block device.\n") - f.Printf("This may take some time depending on the amount of free space.\n\n") - - if !confirmAction("Proceed with TRIM operation?") { - f.Printf("Cancelled.\n") - return nil - } - } - - if !f.IsJSON() { - f.Printf("Performing TRIM operation...") - } - - req := &client.ForceTrimRequest{ - Force: adminForce, - } - - resp, err := c.AdminForceTrim(ctx, req) - if err != nil { - if !f.IsJSON() { - f.Printf(" failed\n") - } - printError("failed to perform TRIM: %v", err) - return err - } - - if f.IsJSON() { - return f.JSON(resp) - } - - f.Printf(" done\n\n") - f.Header("TRIM Operation Complete") - f.KeyValue("Operation", resp.Operation) - f.KeyValueColor("Status", resp.Status, statusColor(resp.Status)) - if resp.Message != "" { - f.KeyValue("Message", resp.Message) - } - if resp.Details != "" { - f.KeyValue("Details", resp.Details) - } - - fmt.Fprintln(os.Stdout) - return nil -} - -// statusColor returns the color indicator for an operation status. -func statusColor(status string) string { - switch status { - case "success", "complete", "ok": - return "ok" - case "failed", "error": - return "error" - default: - return "warning" - } -} diff --git a/cmd/gfsctl/commands/cluster.go b/cmd/gfsctl/commands/cluster.go deleted file mode 100644 index c82e7051..00000000 --- a/cmd/gfsctl/commands/cluster.go +++ /dev/null @@ -1,202 +0,0 @@ -package commands - -import ( - "context" - "fmt" - "os" - - "github.com/spf13/cobra" - - "github.com/supporttools/GoClusterFS/cmd/gfsctl/client" -) - -var clusterCmd = &cobra.Command{ - Use: "cluster [subcommand]", - Short: "Cluster management commands", - Long: `Manage and inspect cluster state. - -Available subcommands: - status - Show cluster status - nodes - List cluster nodes - locks - Show active distributed locks - -Examples: - gfsctl cluster status # Show cluster status - gfsctl cluster nodes # List all nodes - gfsctl cluster locks # Show distributed locks`, - Args: cobra.MaximumNArgs(1), - RunE: runCluster, -} - -func init() { - rootCmd.AddCommand(clusterCmd) -} - -func runCluster(cmd *cobra.Command, args []string) error { - ctx := context.Background() - apiClient := GetClient() - f := NewFormatter(cmd.OutOrStdout(), GetOutputFormat()) - - // Determine which subcommand - subcmd := "status" - if len(args) > 0 { - subcmd = args[0] - } - - switch subcmd { - case "status": - return showClusterStatus(ctx, apiClient, f) - case "nodes": - return showClusterNodes(ctx, apiClient, f) - case "locks": - return showClusterLocks(ctx, apiClient, f) - default: - return fmt.Errorf("unknown subcommand: %s (valid: status, nodes, locks)", subcmd) - } -} - -func showClusterStatus(ctx context.Context, c *client.Client, f *Formatter) error { - status, err := c.ClusterStatus(ctx) - if err != nil { - printError("failed to get cluster status: %v", err) - return err - } - - if f.IsJSON() { - return f.JSON(status) - } - - f.Header("Cluster Status") - - f.KeyValue("Node ID", status.NodeID) - if status.NodeAddress != "" { - f.KeyValue("Address", status.NodeAddress) - } - - roleColor := "follower" - if status.Role == "leader" { - roleColor = "leader" - } - f.KeyValueColor("Role", status.Role, roleColor) - - stateColor := "ok" - if status.State != "active" { - stateColor = "warning" - } - f.KeyValueColor("State", status.State, stateColor) - - f.KeyValue("Cluster Size", fmt.Sprintf("%d", status.ClusterSize)) - - healthColor := "ok" - if status.HealthyNodes < status.ClusterSize { - healthColor = "warning" - } - f.KeyValueColor("Healthy Nodes", fmt.Sprintf("%d/%d", status.HealthyNodes, status.ClusterSize), healthColor) - - if status.LeaderID != "" { - f.KeyValue("Leader ID", status.LeaderID) - } - if status.LastHeartbeatAt != "" { - f.KeyValue("Last Heartbeat", status.LastHeartbeatAt) - } - if status.JoinedAt != "" { - f.KeyValue("Joined At", status.JoinedAt) - } - - // Show peers if present - if len(status.Peers) > 0 { - f.Header("Peers") - table := f.NewTable("Node ID", "Address", "State", "Latency") - for _, peer := range status.Peers { - latency := "-" - if peer.Latency > 0 { - latency = fmt.Sprintf("%.1fms", peer.Latency) - } - table.AddRow(peer.NodeID, peer.Address, peer.State, latency) - } - table.Render() - } - - fmt.Fprintln(os.Stdout) - return nil -} - -func showClusterNodes(ctx context.Context, c *client.Client, f *Formatter) error { - nodes, err := c.ClusterNodes(ctx) - if err != nil { - printError("failed to get cluster nodes: %v", err) - return err - } - - if f.IsJSON() { - return f.JSON(nodes) - } - - f.Header("Cluster Nodes") - - if nodes.ClusterID != "" { - f.KeyValue("Cluster ID", nodes.ClusterID) - } - f.KeyValue("Total Nodes", fmt.Sprintf("%d", nodes.TotalNodes)) - - healthColor := "ok" - if nodes.HealthyNodes < nodes.TotalNodes { - healthColor = "warning" - } - f.KeyValueColor("Healthy Nodes", fmt.Sprintf("%d", nodes.HealthyNodes), healthColor) - - if nodes.LeaderID != "" { - f.KeyValue("Leader", nodes.LeaderID) - } - - if len(nodes.Nodes) > 0 { - f.Printf("\n") - table := f.NewTable("Node ID", "Address", "Role", "State", "Latency", "Self") - for _, node := range nodes.Nodes { - latency := "-" - if node.LatencyMs > 0 { - latency = fmt.Sprintf("%.1fms", node.LatencyMs) - } - self := "" - if node.IsSelf { - self = "*" - } - table.AddRow(node.NodeID, node.Address, node.Role, node.State, latency, self) - } - table.Render() - } - - fmt.Fprintln(os.Stdout) - return nil -} - -func showClusterLocks(ctx context.Context, c *client.Client, f *Formatter) error { - locks, err := c.ClusterLocks(ctx) - if err != nil { - printError("failed to get cluster locks: %v", err) - return err - } - - if f.IsJSON() { - return f.JSON(locks) - } - - f.Header("Distributed Locks") - - f.KeyValue("Active Locks", fmt.Sprintf("%d", locks.ActiveLocks)) - f.KeyValue("Pending Locks", fmt.Sprintf("%d", locks.PendingLocks)) - - if len(locks.Locks) > 0 { - f.Printf("\n") - table := f.NewTable("Lock ID", "Resource", "Type", "Owner Node", "Acquired At") - for _, lock := range locks.Locks { - table.AddRow(lock.LockID, lock.Resource, lock.LockType, lock.OwnerNodeID, lock.AcquiredAt) - } - table.Render() - } else { - f.Printf("\n (no active locks)\n") - } - - fmt.Fprintln(os.Stdout) - return nil -} diff --git a/cmd/gfsctl/commands/snapshot.go b/cmd/gfsctl/commands/snapshot.go deleted file mode 100644 index 94d83de5..00000000 --- a/cmd/gfsctl/commands/snapshot.go +++ /dev/null @@ -1,243 +0,0 @@ -package commands - -import ( - "bufio" - "context" - "fmt" - "os" - "strings" - - "github.com/spf13/cobra" - - "github.com/supporttools/GoClusterFS/cmd/gfsctl/client" -) - -var snapshotCmd = &cobra.Command{ - Use: "snapshot [subcommand]", - Short: "Snapshot management commands", - Long: `Manage filesystem snapshots. - -Available subcommands: - list - List all snapshots - create - Create a new snapshot - delete - Delete a snapshot - info - Show snapshot details - -Examples: - gfsctl snapshot list # List all snapshots - gfsctl snapshot create mysnap # Create snapshot named "mysnap" - gfsctl snapshot delete snap-123 # Delete snapshot by ID - gfsctl snapshot info snap-123 # Show snapshot details`, - Args: cobra.MaximumNArgs(2), - RunE: runSnapshot, -} - -var ( - snapshotDescription string - snapshotForce bool -) - -func init() { - snapshotCmd.Flags().StringVarP(&snapshotDescription, "description", "d", "", "Snapshot description (for create)") - snapshotCmd.Flags().BoolVarP(&snapshotForce, "force", "f", false, "Skip confirmation prompts") - rootCmd.AddCommand(snapshotCmd) -} - -func runSnapshot(cmd *cobra.Command, args []string) error { - ctx := context.Background() - apiClient := GetClient() - f := NewFormatter(cmd.OutOrStdout(), GetOutputFormat()) - - // Determine which subcommand - subcmd := "list" - if len(args) > 0 { - subcmd = args[0] - } - - switch subcmd { - case "list": - return listSnapshots(ctx, apiClient, f) - case "create": - if len(args) < 2 { - return fmt.Errorf("snapshot name required: gfsctl snapshot create ") - } - return createSnapshot(ctx, apiClient, f, args[1]) - case "delete": - if len(args) < 2 { - return fmt.Errorf("snapshot ID required: gfsctl snapshot delete ") - } - return deleteSnapshot(ctx, apiClient, f, args[1]) - case "info": - if len(args) < 2 { - return fmt.Errorf("snapshot ID required: gfsctl snapshot info ") - } - return showSnapshotInfo(ctx, apiClient, f, args[1]) - default: - return fmt.Errorf("unknown subcommand: %s (valid: list, create, delete, info)", subcmd) - } -} - -func listSnapshots(ctx context.Context, c *client.Client, f *Formatter) error { - resp, err := c.SnapshotList(ctx) - if err != nil { - printError("failed to list snapshots: %v", err) - return err - } - - if f.IsJSON() { - return f.JSON(resp) - } - - f.Header("Snapshots") - f.KeyValue("Total", fmt.Sprintf("%d", resp.Total)) - - if len(resp.Snapshots) > 0 { - f.Printf("\n") - table := f.NewTable("ID", "Name", "Created", "Size", "Status") - for _, snap := range resp.Snapshots { - table.AddRow(snap.ID, snap.Name, snap.CreatedAt, FormatBytes(snap.SizeBytes), snap.Status) - } - table.Render() - } else { - f.Printf("\n (no snapshots)\n") - } - - fmt.Fprintln(os.Stdout) - return nil -} - -func createSnapshot(ctx context.Context, c *client.Client, f *Formatter, name string) error { - // Show what we're about to do - if !snapshotForce && !f.IsJSON() { - f.Printf("Creating snapshot: %s\n", name) - if snapshotDescription != "" { - f.Printf("Description: %s\n", snapshotDescription) - } - if !confirmAction("Create this snapshot?") { - f.Printf("Cancelled.\n") - return nil - } - } - - req := &client.SnapshotCreateRequest{ - Name: name, - Description: snapshotDescription, - } - - // Show progress - if !f.IsJSON() { - f.Printf("Creating snapshot...") - } - - resp, err := c.SnapshotCreate(ctx, req) - if err != nil { - if !f.IsJSON() { - f.Printf(" failed\n") - } - printError("failed to create snapshot: %v", err) - return err - } - - if f.IsJSON() { - return f.JSON(resp) - } - - f.Printf(" done\n\n") - f.Header("Snapshot Created") - f.KeyValue("ID", resp.Snapshot.ID) - f.KeyValue("Name", resp.Snapshot.Name) - f.KeyValue("Created At", resp.Snapshot.CreatedAt) - f.KeyValueColor("Status", resp.Snapshot.Status, "ok") - - fmt.Fprintln(os.Stdout) - return nil -} - -func deleteSnapshot(ctx context.Context, c *client.Client, f *Formatter, id string) error { - // Get snapshot info first for confirmation - if !snapshotForce && !f.IsJSON() { - info, err := c.SnapshotInfo(ctx, id) - if err != nil { - printError("failed to get snapshot info: %v", err) - return err - } - - f.Printf("Snapshot to delete:\n") - f.KeyValue("ID", info.ID) - f.KeyValue("Name", info.Name) - f.KeyValue("Size", FormatBytes(info.SizeBytes)) - f.Printf("\n") - - if !confirmAction("Delete this snapshot? This cannot be undone.") { - f.Printf("Cancelled.\n") - return nil - } - } - - // Show progress - if !f.IsJSON() { - f.Printf("Deleting snapshot...") - } - - resp, err := c.SnapshotDelete(ctx, id) - if err != nil { - if !f.IsJSON() { - f.Printf(" failed\n") - } - printError("failed to delete snapshot: %v", err) - return err - } - - if f.IsJSON() { - return f.JSON(resp) - } - - f.Printf(" done\n") - f.Printf("Snapshot %s deleted.\n", resp.ID) - - fmt.Fprintln(os.Stdout) - return nil -} - -func showSnapshotInfo(ctx context.Context, c *client.Client, f *Formatter, id string) error { - info, err := c.SnapshotInfo(ctx, id) - if err != nil { - printError("failed to get snapshot info: %v", err) - return err - } - - if f.IsJSON() { - return f.JSON(info) - } - - f.Header("Snapshot Details") - f.KeyValue("ID", info.ID) - f.KeyValue("Name", info.Name) - f.KeyValue("Created At", info.CreatedAt) - f.KeyValue("Size", FormatBytes(info.SizeBytes)) - - statusColor := "ok" - if info.Status != "complete" && info.Status != "ready" { - statusColor = "warning" - } - f.KeyValueColor("Status", info.Status, statusColor) - - if info.Description != "" { - f.KeyValue("Description", info.Description) - } - - fmt.Fprintln(os.Stdout) - return nil -} - -// confirmAction prompts the user for confirmation. -func confirmAction(prompt string) bool { - reader := bufio.NewReader(os.Stdin) - fmt.Printf("%s [y/N]: ", prompt) - response, err := reader.ReadString('\n') - if err != nil { - return false - } - response = strings.TrimSpace(strings.ToLower(response)) - return response == "y" || response == "yes" -} From 716fe6f5da4c84c92f2ebb64f27d6d4fb2768349 Mon Sep 17 00:00:00 2001 From: Matthew Mattox Date: Tue, 10 Nov 2026 16:03:36 -0600 Subject: [PATCH 3/8] fix(gfsctl): make settings, errors and output behave, add metrics - Settings resolve per field from a flag that was set, then GFSCTL_*, then the config file, then the default. GFSCTL_PORT and GFSCTL_TIMEOUT were checked but never read, and the config file loaded at package init. - Bad GFSCTL_PORT, GFSCTL_TIMEOUT, output format or config file are errors, not silently ignored. - Every error prints once. Some paths exited 1 with no message, and watch mode printed errors twice. - Output goes to the command's writer, not os.Stdout, and is colored only on a terminal without NO_COLOR. - An IPv6 --host gave http://::1:8080; the URL now uses JoinHostPort. - version reads internal/version, like the other binaries. - New: gfsctl metrics, and gfsctl stats cluster (/api/v1/stats/cluster). Co-Authored-By: Claude Opus 5.5 --- cmd/gfsctl/client/api.go | 14 +++++ cmd/gfsctl/client/client.go | 23 ++++---- cmd/gfsctl/commands/completion.go | 10 ++-- cmd/gfsctl/commands/config.go | 34 ----------- cmd/gfsctl/commands/config_cmd.go | 10 +--- cmd/gfsctl/commands/health.go | 6 +- cmd/gfsctl/commands/metrics.go | 31 +++++++++++ cmd/gfsctl/commands/output.go | 20 ++++++- cmd/gfsctl/commands/root.go | 93 ++++++++++++++++++++++--------- cmd/gfsctl/commands/stats.go | 73 +++++++++++++++--------- cmd/gfsctl/commands/status.go | 7 +-- cmd/gfsctl/commands/version.go | 13 ++--- cmd/gfsctl/main.go | 25 +-------- 13 files changed, 205 insertions(+), 154 deletions(-) create mode 100644 cmd/gfsctl/commands/metrics.go diff --git a/cmd/gfsctl/client/api.go b/cmd/gfsctl/client/api.go index 3aae93c2..67b0be85 100644 --- a/cmd/gfsctl/client/api.go +++ b/cmd/gfsctl/client/api.go @@ -84,3 +84,17 @@ func (c *Client) AllStats(ctx context.Context) (*AllStatsResponse, error) { } 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 index 364ac24b..c3042244 100644 --- a/cmd/gfsctl/client/client.go +++ b/cmd/gfsctl/client/client.go @@ -6,12 +6,17 @@ import ( "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 @@ -20,25 +25,17 @@ type Client struct { // Option configures a Client. type Option func(*Client) -// WithHost sets the API server host. +// WithHost sets the API server host name or IP address. func WithHost(host string) Option { return func(c *Client) { - c.baseURL = fmt.Sprintf("http://%s", host) + c.host = host } } // WithPort sets the API server port. func WithPort(port int) Option { return func(c *Client) { - // Extract host from existing baseURL or default to localhost - host := "localhost" - if c.baseURL != "" { - // Parse existing host - if len(c.baseURL) > 7 { // len("http://") - host = c.baseURL[7:] - } - } - c.baseURL = fmt.Sprintf("http://%s:%d", host, port) + c.port = port } } @@ -59,7 +56,8 @@ func WithTimeout(timeout time.Duration) Option { // New creates a new API client with the given options. func New(opts ...Option) *Client { c := &Client{ - baseURL: "http://localhost:8080", + host: "localhost", + port: 8080, httpClient: &http.Client{ Timeout: 30 * time.Second, }, @@ -67,6 +65,7 @@ func New(opts ...Option) *Client { for _, opt := range opts { opt(c) } + c.baseURL = "http://" + net.JoinHostPort(strings.Trim(c.host, "[]"), strconv.Itoa(c.port)) return c } diff --git a/cmd/gfsctl/commands/completion.go b/cmd/gfsctl/commands/completion.go index 569b613a..e2c40751 100644 --- a/cmd/gfsctl/commands/completion.go +++ b/cmd/gfsctl/commands/completion.go @@ -1,8 +1,6 @@ package commands import ( - "os" - "github.com/spf13/cobra" ) @@ -52,13 +50,13 @@ PowerShell: RunE: func(cmd *cobra.Command, args []string) error { switch args[0] { case "bash": - return rootCmd.GenBashCompletion(os.Stdout) + return rootCmd.GenBashCompletion(cmd.OutOrStdout()) case "zsh": - return rootCmd.GenZshCompletion(os.Stdout) + return rootCmd.GenZshCompletion(cmd.OutOrStdout()) case "fish": - return rootCmd.GenFishCompletion(os.Stdout, true) + return rootCmd.GenFishCompletion(cmd.OutOrStdout(), true) case "powershell": - return rootCmd.GenPowerShellCompletionWithDesc(os.Stdout) + return rootCmd.GenPowerShellCompletionWithDesc(cmd.OutOrStdout()) } return nil }, diff --git a/cmd/gfsctl/commands/config.go b/cmd/gfsctl/commands/config.go index d55533d3..844abbf3 100644 --- a/cmd/gfsctl/commands/config.go +++ b/cmd/gfsctl/commands/config.go @@ -73,40 +73,6 @@ func loadConfig() (*AppConfig, error) { return &cfg, nil } -// initConfig loads the config file and applies values to global flags. -// Environment variables and command-line flags take precedence. -func initConfig() { - cfg, err := loadConfig() - if err != nil { - // Silently ignore config errors - CLI should still work - return - } - - // Apply config values only if not already set by env/flag - // Note: cobra doesn't easily support checking if a flag was set, - // so we check if values are at their defaults - - if cfg.Host != "" && cfgHost == "localhost" && os.Getenv("GFSCTL_HOST") == "" { - cfgHost = cfg.Host - } - - if cfg.Port != 0 && cfgPort == 8080 && os.Getenv("GFSCTL_PORT") == "" { - cfgPort = cfg.Port - } - - if cfg.Token != "" && cfgToken == "" && os.Getenv("GFSCTL_TOKEN") == "" { - cfgToken = cfg.Token - } - - if cfg.Output != "" && cfgOutput == "text" && os.Getenv("GFSCTL_OUTPUT") == "" { - cfgOutput = cfg.Output - } - - if cfg.Timeout != 0 && cfgTimeout == 30*time.Second && os.Getenv("GFSCTL_TIMEOUT") == "" { - cfgTimeout = cfg.Timeout - } -} - // GenerateSampleConfig returns a sample configuration file content. func GenerateSampleConfig() string { return `# gfsctl configuration file diff --git a/cmd/gfsctl/commands/config_cmd.go b/cmd/gfsctl/commands/config_cmd.go index 7917210a..2024d6c2 100644 --- a/cmd/gfsctl/commands/config_cmd.go +++ b/cmd/gfsctl/commands/config_cmd.go @@ -99,35 +99,31 @@ func showCurrentConfig(cmd *cobra.Command) error { f.KeyValue("Output", cfgOutput) f.KeyValue("Timeout", cfgTimeout.String()) - fmt.Fprintln(os.Stdout) + f.Println() return nil } func initConfigFile(cmd *cobra.Command) error { path := configPath() if path == "" { - printError("unable to determine config directory") return fmt.Errorf("unable to determine config directory") } // Check if file already exists if _, err := os.Stat(path); err == nil { - printError("config file already exists: %s", path) 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 { - printError("failed to create config directory: %v", err) - return err + 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 { - printError("failed to write config file: %v", err) - return err + return fmt.Errorf("failed to write config file: %w", err) } fmt.Fprintf(cmd.OutOrStdout(), "Created config file: %s\n", path) diff --git a/cmd/gfsctl/commands/health.go b/cmd/gfsctl/commands/health.go index baedf590..a940c8fe 100644 --- a/cmd/gfsctl/commands/health.go +++ b/cmd/gfsctl/commands/health.go @@ -3,7 +3,6 @@ package commands import ( "context" "fmt" - "os" "github.com/spf13/cobra" ) @@ -30,8 +29,7 @@ func runHealth(cmd *cobra.Command, args []string) error { health, err := client.Health(ctx) if err != nil { - printError("failed to get health: %v", err) - return err + return fmt.Errorf("failed to get health: %w", err) } f := NewFormatter(cmd.OutOrStdout(), GetOutputFormat()) @@ -59,7 +57,7 @@ func runHealth(cmd *cobra.Command, args []string) error { } } - fmt.Fprintln(os.Stdout) + f.Println() // Return error if unhealthy (for scripting) if health.Status == "unhealthy" { 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 index e1e9c81c..51ff6016 100644 --- a/cmd/gfsctl/commands/output.go +++ b/cmd/gfsctl/commands/output.go @@ -4,6 +4,7 @@ import ( "encoding/json" "fmt" "io" + "os" "strings" ) @@ -11,11 +12,22 @@ import ( 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} + 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. @@ -58,8 +70,10 @@ func (f *Formatter) KeyValue(key string, value interface{}) { // KeyValueColor prints a key-value pair with color for status values. func (f *Formatter) KeyValueColor(key string, value string, status string) { - colored := colorize(value, status) - fmt.Fprintf(f.w, " %-20s %s\n", key+":", colored) + 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. diff --git a/cmd/gfsctl/commands/root.go b/cmd/gfsctl/commands/root.go index ba1b14c3..4cc79f53 100644 --- a/cmd/gfsctl/commands/root.go +++ b/cmd/gfsctl/commands/root.go @@ -4,6 +4,7 @@ package commands import ( "fmt" "os" + "strconv" "time" "github.com/spf13/cobra" @@ -29,24 +30,24 @@ var rootCmd = &cobra.Command{ Short: "GoClusterFS management CLI", Long: `gfsctl is the management CLI for GoClusterFS. -It communicates with a running GoClusterFS mount via its HTTP API -to query status, statistics, and perform administrative operations. +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 cluster nodes # List cluster nodes + 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 { - // Skip client initialization for version command - if cmd.Name() == "version" { - return nil + if err := resolveSettings(cmd); err != nil { + return err } - - // Create API client with configured options apiClient = client.New( client.WithHost(cfgHost), client.WithPort(cfgPort), @@ -57,32 +58,77 @@ Examples: }, } -// Execute runs the root command. +// Execute runs the root command and prints any error to stderr. func Execute() error { - return rootCmd.Execute() + err := rootCmd.Execute() + if err != nil { + fmt.Fprintln(rootCmd.ErrOrStderr(), "Error:", err) + } + return err } func init() { - // Global flags available to all commands 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") + 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)") +} - // Load configuration file (lowest priority) - initConfig() +// 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() - // Environment variable fallbacks (higher priority than config file) - if host := os.Getenv("GFSCTL_HOST"); host != "" { - cfgHost = host + if !flags.Changed("host") { + cfgHost = firstNonEmpty(os.Getenv("GFSCTL_HOST"), file.Host, cfgHost) } - if token := os.Getenv("GFSCTL_TOKEN"); token != "" { - cfgToken = token + 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 output := os.Getenv("GFSCTL_OUTPUT"); output != "" { - cfgOutput = output + 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. @@ -95,8 +141,3 @@ func GetClient() *client.Client { func GetOutputFormat() string { return cfgOutput } - -// printError prints an error message to stderr. -func printError(format string, args ...interface{}) { - fmt.Fprintf(os.Stderr, "Error: "+format+"\n", args...) -} diff --git a/cmd/gfsctl/commands/stats.go b/cmd/gfsctl/commands/stats.go index 01ffd15c..add5f1b8 100644 --- a/cmd/gfsctl/commands/stats.go +++ b/cmd/gfsctl/commands/stats.go @@ -3,7 +3,6 @@ package commands import ( "context" "fmt" - "os" "time" "github.com/spf13/cobra" @@ -27,6 +26,7 @@ Available components: 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. @@ -51,7 +51,6 @@ func init() { func runStats(cmd *cobra.Command, args []string) error { // Watch mode not compatible with JSON output if statsWatch && GetOutputFormat() == "json" { - printError("watch mode is not compatible with JSON output") return fmt.Errorf("watch mode is not compatible with JSON output") } @@ -63,10 +62,10 @@ func runStats(cmd *cobra.Command, args []string) error { // Validate component name upfront switch component { - case "", "cache", "journal", "trim", "lock", "sfb", "all": + case "", "cache", "journal", "trim", "lock", "sfb", "cluster", "all": // valid default: - return fmt.Errorf("unknown component: %s (valid: cache, journal, trim, lock, sfb, all)", component) + return fmt.Errorf("unknown component: %s (valid: cache, journal, trim, lock, sfb, cluster, all)", component) } // Create the display function @@ -98,6 +97,8 @@ func displayStats(cmd *cobra.Command, ctx context.Context, component string) err 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: @@ -108,8 +109,7 @@ func displayStats(cmd *cobra.Command, ctx context.Context, component string) err func showStatsOverview(ctx context.Context, c *client.Client, f *Formatter) error { stats, err := c.StatsOverview(ctx) if err != nil { - printError("failed to get stats: %v", err) - return err + return fmt.Errorf("failed to get stats: %w", err) } if f.IsJSON() { @@ -131,15 +131,14 @@ func showStatsOverview(ctx context.Context, c *client.Client, f *Formatter) erro f.KeyValue(" Bytes Written", FormatBytes(stats.Journal.BytesWritten)) } - fmt.Fprintln(os.Stdout) + f.Println() return nil } func showCacheStats(ctx context.Context, c *client.Client, f *Formatter) error { stats, err := c.CacheStats(ctx) if err != nil { - printError("failed to get cache stats: %v", err) - return err + return fmt.Errorf("failed to get cache stats: %w", err) } if f.IsJSON() { @@ -173,15 +172,14 @@ func showCacheStats(ctx context.Context, c *client.Client, f *Formatter) error { } table.Render() - fmt.Fprintln(os.Stdout) + f.Println() return nil } func showJournalStats(ctx context.Context, c *client.Client, f *Formatter) error { stats, err := c.JournalStats(ctx) if err != nil { - printError("failed to get journal stats: %v", err) - return err + return fmt.Errorf("failed to get journal stats: %w", err) } if f.IsJSON() { @@ -204,15 +202,14 @@ func showJournalStats(ctx context.Context, c *client.Client, f *Formatter) error f.KeyValue("Last Checkpoint", fmt.Sprintf("%d", stats.LastCheckpointSeq)) f.KeyValue("Batch Syncs", fmt.Sprintf("%d", stats.BatchSyncCount)) - fmt.Fprintln(os.Stdout) + f.Println() return nil } func showTrimStats(ctx context.Context, c *client.Client, f *Formatter) error { stats, err := c.TrimStats(ctx) if err != nil { - printError("failed to get trim stats: %v", err) - return err + return fmt.Errorf("failed to get trim stats: %w", err) } if f.IsJSON() { @@ -241,15 +238,14 @@ func showTrimStats(ctx context.Context, c *client.Client, f *Formatter) error { f.KeyValue("Last TRIM", stats.LastTrimAt) } - fmt.Fprintln(os.Stdout) + f.Println() return nil } func showLockStats(ctx context.Context, c *client.Client, f *Formatter) error { stats, err := c.LockStats(ctx) if err != nil { - printError("failed to get lock stats: %v", err) - return err + return fmt.Errorf("failed to get lock stats: %w", err) } if f.IsJSON() { @@ -264,15 +260,14 @@ func showLockStats(ctx context.Context, c *client.Client, f *Formatter) error { f.KeyValue("Active Locks", fmt.Sprintf("%d", stats.ActiveLocks)) f.KeyValue("Pending Locks", fmt.Sprintf("%d", stats.PendingLocks)) - fmt.Fprintln(os.Stdout) + f.Println() return nil } func showSFBStats(ctx context.Context, c *client.Client, f *Formatter) error { stats, err := c.SFBStats(ctx) if err != nil { - printError("failed to get sfb stats: %v", err) - return err + return fmt.Errorf("failed to get sfb stats: %w", err) } if f.IsJSON() { @@ -297,15 +292,43 @@ func showSFBStats(ctx context.Context, c *client.Client, f *Formatter) error { f.KeyValueColor("Allocation Failures", fmt.Sprintf("%d", stats.AllocationFailures), "error") } - fmt.Fprintln(os.Stdout) + 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 { - printError("failed to get all stats: %v", err) - return err + return fmt.Errorf("failed to get all stats: %w", err) } if f.IsJSON() { @@ -371,6 +394,6 @@ func showAllStats(ctx context.Context, c *client.Client, f *Formatter) error { f.KeyValue("Healthy Nodes", fmt.Sprintf("%d", stats.Cluster.HealthyNodes)) } - fmt.Fprintln(os.Stdout) + f.Println() return nil } diff --git a/cmd/gfsctl/commands/status.go b/cmd/gfsctl/commands/status.go index 2f523955..45dc80b0 100644 --- a/cmd/gfsctl/commands/status.go +++ b/cmd/gfsctl/commands/status.go @@ -3,7 +3,6 @@ package commands import ( "context" "fmt" - "os" "time" "github.com/spf13/cobra" @@ -37,7 +36,6 @@ func init() { func runStatus(cmd *cobra.Command, args []string) error { // Watch mode not compatible with JSON output if statusWatch && GetOutputFormat() == "json" { - printError("watch mode is not compatible with JSON output") return fmt.Errorf("watch mode is not compatible with JSON output") } @@ -58,8 +56,7 @@ func displayStatus(cmd *cobra.Command, ctx context.Context) error { status, err := client.Status(ctx) if err != nil { - printError("failed to get status: %v", err) - return err + return fmt.Errorf("failed to get status: %w", err) } f := NewFormatter(cmd.OutOrStdout(), GetOutputFormat()) @@ -140,6 +137,6 @@ func displayStatus(cmd *cobra.Command, ctx context.Context) error { } } - fmt.Fprintln(os.Stdout) + f.Println() return nil } diff --git a/cmd/gfsctl/commands/version.go b/cmd/gfsctl/commands/version.go index cf2da86f..6f73e252 100644 --- a/cmd/gfsctl/commands/version.go +++ b/cmd/gfsctl/commands/version.go @@ -6,13 +6,8 @@ import ( "runtime" "github.com/spf13/cobra" -) -var ( - // Version information, set at build time via ldflags - Version = "dev" - GitCommit = "unknown" - BuildTime = "unknown" + "github.com/supporttools/GoClusterFS/internal/version" ) // VersionInfo contains version information for JSON output. @@ -31,9 +26,9 @@ var versionCmd = &cobra.Command{ Long: `Display version, build information, and runtime details for gfsctl.`, RunE: func(cmd *cobra.Command, args []string) error { info := VersionInfo{ - Version: Version, - GitCommit: GitCommit, - BuildTime: BuildTime, + Version: version.Version, + GitCommit: version.Commit, + BuildTime: version.Date, GoVersion: runtime.Version(), OS: runtime.GOOS, Arch: runtime.GOARCH, diff --git a/cmd/gfsctl/main.go b/cmd/gfsctl/main.go index 3df45691..2031504e 100644 --- a/cmd/gfsctl/main.go +++ b/cmd/gfsctl/main.go @@ -1,26 +1,5 @@ -// Command gfsctl is the management CLI for GoClusterFS. -// -// gfsctl communicates with a running GoClusterFS mount via its HTTP API -// to query status, statistics, and perform administrative operations. -// -// Usage: -// -// gfsctl [global flags] [command flags] -// -// Global flags: -// -// --host API server host (default: localhost) -// --port API server port (default: 8080) -// --token Bearer token for authentication -// --timeout Request timeout (default: 30s) -// -// Commands: -// -// status Show filesystem status -// health Check filesystem health -// stats Show component statistics -// cluster Cluster management commands -// version Show version information +// Command gfsctl reads status, health, statistics and metrics from a +// running GoClusterFS mount through its HTTP API. It changes nothing. package main import ( From 442f11f295b50fd2ada050ed75a3b90dd394ea80 Mon Sep 17 00:00:00 2001 From: Matthew Mattox Date: Tue, 10 Nov 2026 16:03:36 -0600 Subject: [PATCH 4/8] test(gfsctl): check every read command against the server's types A fake API answers with JSON built from internal/api's response types, and each command's -o json output must decode back to the same value. This found that stats overview dropped the server's io section; the client now has IOStatsResponse. Also tests settings precedence, bad settings, error output, metrics and the base URL for IPv6 hosts. Co-Authored-By: Claude Opus 5.5 --- cmd/gfsctl/client/client_test.go | 52 +++++ cmd/gfsctl/client/types.go | 11 ++ cmd/gfsctl/commands/commands_test.go | 286 +++++++++++++++++++++++++++ 3 files changed, 349 insertions(+) create mode 100644 cmd/gfsctl/client/client_test.go create mode 100644 cmd/gfsctl/commands/commands_test.go 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 index f834176c..fb90a7c9 100644 --- a/cmd/gfsctl/client/types.go +++ b/cmd/gfsctl/client/types.go @@ -171,4 +171,15 @@ type AllStatsResponse struct { 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) + } +} From e620f34b1373ff1c324a30813ba77ac86a037cd8 Mon Sep 17 00:00:00 2001 From: Matthew Mattox Date: Tue, 10 Nov 2026 16:03:36 -0600 Subject: [PATCH 5/8] build: build gfsctl with make build and ship it in release archives dist.sh also collects gfsctl's dependency licenses, and the release workflow checks that gfsctl reports the build commit. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release.yml | 6 +++++- .gitignore | 1 + Makefile | 12 +++++++++--- scripts/dist.sh | 4 +++- 4 files changed, 18 insertions(+), 5 deletions(-) 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/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/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/" From 3b66c55e6edc88eab1407d768b796d49a60dad9e Mon Sep 17 00:00:00 2001 From: Matthew Mattox Date: Tue, 10 Nov 2026 16:03:36 -0600 Subject: [PATCH 6/8] test(gfsctl): read status, health and metrics from a live mount Co-Authored-By: Claude Opus 5.5 --- tests/integration/api_test.go | 54 +++++++++++++++++++++++++++++++++++ tests/test-manifest.yaml | 7 +++++ 2 files changed, 61 insertions(+) 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 87e59770..89e24312 100644 --- a/tests/test-manifest.yaml +++ b/tests/test-manifest.yaml @@ -2327,3 +2327,10 @@ scenarios: priority: go_only 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 From 8471696ac8307dd31f1aa38586ecad80e9d15f08 Mon Sep 17 00:00:00 2001 From: Matthew Mattox Date: Tue, 10 Nov 2026 16:03:36 -0600 Subject: [PATCH 7/8] docs: document gfsctl Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 1 + CLAUDE.md | 3 ++- README.md | 27 ++++++++++++++++++++++++++- docs/DEPLOYMENT.md | 5 +++-- 4 files changed, 32 insertions(+), 4 deletions(-) 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 de3fe2f2..d2b1aa7d 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/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/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. From e32640980b0417315e4c36f15f8ef8b53df2ea8a Mon Sep 17 00:00:00 2001 From: Matthew Mattox Date: Tue, 10 Nov 2026 16:07:17 -0600 Subject: [PATCH 8/8] build: list spf13/pflag as a direct dependency The gfsctl tests import it to reset flags between runs. Co-Authored-By: Claude Opus 5.5 --- go.mod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/go.mod b/go.mod index 6664a50c..52fa5782 100644 --- a/go.mod +++ b/go.mod @@ -7,6 +7,7 @@ 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 ) @@ -20,7 +21,6 @@ require ( github.com/prometheus/client_model v0.6.2 // indirect github.com/prometheus/common v0.66.1 // indirect github.com/prometheus/procfs v0.16.1 // indirect - github.com/spf13/pflag v1.0.9 // indirect go.yaml.in/yaml/v2 v2.4.2 // indirect google.golang.org/protobuf v1.36.8 // indirect )