diff --git a/CHANGELOG.md b/CHANGELOG.md index df8b13c4..353cebf8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -39,6 +39,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), - CI gates: unit tests with the race detector and coverage, golangci-lint (`make lint`), govulncheck (`make vuln`), and a `go mod tidy` check. - 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` without `-api-token`. +- `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/`. - Apache License 2.0. diff --git a/CLAUDE.md b/CLAUDE.md index 9190b368..de3fe2f2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -53,6 +53,9 @@ fusermount3 -u mnt # or Ctrl+C the mo | `internal/trim` | Batched `BLKDISCARD` for freed blocks | | `internal/fsck` | The fsck phases | | `internal/metrics` | Atomic counters, not used by `cmd/mount` yet | +| `internal/api` | HTTP API served by `cmd/mount`: `/health`, `/metrics`, `/api/v1/status`, `/api/v1/stats/...`; loopback only unless `-api-token` is set | +| `internal/stats` | Stats types and collector behind `/api/v1/stats` | +| `internal/version` | Build version, set with `-ldflags -X` by `scripts/dist.sh` | ## On-Disk Layout diff --git a/README.md b/README.md index b0b54e8f..f68d1aae 100644 --- a/README.md +++ b/README.md @@ -88,6 +88,7 @@ These are the `goclusterfs-mount` flags. Run `./goclusterfs-mount -h` for the fu | `-format` | `false` | Format the device, then mount it (destroys data) | | `-bytes-per-inode` | `1048576` | With `-format`: one inode per this many bytes of device (4096 to 16,777,216 inodes) | | `-debug` | `false` | Log every FUSE request | +| `-version` | `false` | Print the version and exit | ### Cache Options @@ -113,6 +114,8 @@ These are the `goclusterfs-mount` flags. Run `./goclusterfs-mount -h` for the fu | `-broadcast-secret` | (empty) | HMAC secret for message authentication | | `-broadcast-iface` | (auto) | Network interface for multicast | +With `-broadcast` on and no `-broadcast-secret`, mount logs a `WARNING` line at startup: any host that can send to the port can make nodes drop their caches. Set the same secret on every node. + ### TRIM Options | Flag | Default | Description | @@ -128,6 +131,17 @@ These are the `goclusterfs-mount` flags. Run `./goclusterfs-mount -h` for the fu | `-sfb` | `true` | Ignored. SFB containers are disabled and every file uses full blocks | | `-snapshots` | `true` | Enable O(1) file snapshots | +### HTTP API Options + +| Flag | Default | Description | +|------|---------|-------------| +| `-api` | `true` | Serve the HTTP API (`/health`, `/metrics`, `/api/v1/...`) | +| `-api-addr` | `127.0.0.1:8080` | API listen address | +| `-api-token` | (empty) | Bearer token required on `/api/v1/...` | +| `-api-cors` | (empty) | Comma-separated CORS allowed origins | + +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). + ## Multi-Node Setup For clustered deployments: diff --git a/cmd/mount/main.go b/cmd/mount/main.go index 58782781..9e4d6003 100644 --- a/cmd/mount/main.go +++ b/cmd/mount/main.go @@ -8,12 +8,14 @@ import ( "log" "os" "os/signal" + "strings" "syscall" "time" "github.com/hanwen/go-fuse/v2/fs" "github.com/hanwen/go-fuse/v2/fuse" + "github.com/supporttools/GoClusterFS/internal/api" "github.com/supporttools/GoClusterFS/internal/bitmap" "github.com/supporttools/GoClusterFS/internal/cache" "github.com/supporttools/GoClusterFS/internal/cache/broadcast" @@ -29,8 +31,65 @@ import ( "github.com/supporttools/GoClusterFS/internal/storage" "github.com/supporttools/GoClusterFS/internal/superblock" "github.com/supporttools/GoClusterFS/internal/trim" + "github.com/supporttools/GoClusterFS/internal/version" ) +// fsStatusProvider implements api.StatusProvider by wrapping the filesystem. +type fsStatusProvider struct { + mountPath string + devicePath string + dev *storage.Device + bitmapMgr *bitmap.Region +} + +func (p *fsStatusProvider) MountPath() string { return p.mountPath } +func (p *fsStatusProvider) DevicePath() string { return p.devicePath } + +func (p *fsStatusProvider) MountState() api.MountState { + // If we get here, the filesystem is mounted and running + return api.MountStateMounted +} + +func (p *fsStatusProvider) Capacity() *api.CapacityInfo { + totalBlocks := p.bitmapMgr.TotalBlocks() + freeBlocks := p.bitmapMgr.FreeCount() + usedBlocks := totalBlocks - freeBlocks + + const blockSize uint64 = 1024 * 1024 // 1MB blocks + totalBytes := totalBlocks * blockSize + usedBytes := usedBlocks * blockSize + freeBytes := freeBlocks * blockSize + + var usedPercent float64 + if totalBlocks > 0 { + usedPercent = float64(usedBlocks) / float64(totalBlocks) * 100 + } + + return &api.CapacityInfo{ + TotalBytes: totalBytes, + UsedBytes: usedBytes, + FreeBytes: freeBytes, + UsedPercent: usedPercent, + TotalBlocks: totalBlocks, + UsedBlocks: usedBlocks, + FreeBlocks: freeBlocks, + BlockSizeBytes: blockSize, + } +} + +func apiConfig(addr, token, corsList string) api.Config { + var origins []string + for _, origin := range strings.Split(corsList, ",") { + if origin = strings.TrimSpace(origin); origin != "" { + origins = append(origins, origin) + } + } + return api.DefaultConfig(). + WithListenAddr(addr). + WithAuthToken(token). + WithCORSOrigins(origins...) +} + func main() { var ( devicePath = flag.String("device", "", "Path to block device or image file") @@ -38,7 +97,8 @@ func main() { format = flag.Bool("format", false, "Format the device (WARNING: destroys data)") inodeRatio = flag.Uint64("bytes-per-inode", superblock.DefaultBytesPerInode, fmt.Sprintf("With -format: one inode per this many bytes of device (%d to %d inodes)", superblock.MinInodes, superblock.MaxInodes)) - debug = flag.Bool("debug", false, "Enable FUSE debug output") + debug = flag.Bool("debug", false, "Enable FUSE debug output") + showVer = flag.Bool("version", false, "Print version and exit") // Cache configuration cacheStrict = flag.Bool("cache-strict", false, "Enable strict cache mode (always validate)") @@ -66,15 +126,36 @@ func main() { // Snapshot configuration snapshotsEnabled = flag.Bool("snapshots", true, "Enable O(1) file snapshots via xattr") + + // API server configuration + apiEnabled = flag.Bool("api", true, "Enable HTTP API server for management") + apiAddr = flag.String("api-addr", "127.0.0.1:8080", "API server listen address; any non-loopback address needs -api-token") + apiToken = flag.String("api-token", "", "Bearer token for API authentication (empty=disabled, loopback only)") + apiCORS = flag.String("api-cors", "", "Comma-separated CORS allowed origins (empty=disabled)") ) flag.Parse() + if *showVer { + fmt.Println("goclusterfs-mount", version.String()) + os.Exit(0) + } + if *devicePath == "" || *mountPoint == "" { fmt.Fprintf(os.Stderr, "Usage: %s -device -mount [-format] [-debug]\n", os.Args[0]) flag.PrintDefaults() os.Exit(1) } + apiCfg := apiConfig(*apiAddr, *apiToken, *apiCORS) + if *apiEnabled { + if err := apiCfg.CheckExposure(); err != nil { + log.Fatalf("Refusing to start the API: %v. Set -api-token, set -api-addr to a loopback address such as 127.0.0.1:8080, or pass -api=false", err) + } + } + if *broadcastEnabled && *broadcastSecret == "" { + log.Printf("WARNING: -broadcast is on without -broadcast-secret. Broadcast messages are not authenticated: any host that can send UDP to port %d can make this node drop its caches and add itself as a peer. Set the same -broadcast-secret on every node, or pass -broadcast=false.", *multicastPort) + } + // Check mount point exists if _, err := os.Stat(*mountPoint); os.IsNotExist(err) { log.Fatalf("Mount point does not exist: %s", *mountPoint) @@ -351,6 +432,33 @@ func main() { log.Fatalf("Failed to mount: %v", err) } + // Start API server for management and monitoring + var apiServer *api.Server + if *apiEnabled { + var err error + apiServer, err = api.NewServer(apiCfg) + if err != nil { + log.Printf("Warning: Failed to create API server: %v", err) + } else { + apiServer.SetStatusProvider(&fsStatusProvider{ + mountPath: *mountPoint, + devicePath: *devicePath, + dev: dev, + bitmapMgr: bm, + }) + apiServer.RegisterHealthChecker(api.DefaultHealthChecker()) + if err := apiServer.Start(ctx); err != nil { + log.Printf("Warning: Failed to start API server: %v", err) + apiServer = nil + } else { + log.Printf("API server listening on %s (auth=%v, cors=%v)", + apiServer.Addr(), apiCfg.AuthToken != "", len(apiCfg.CORSOrigins) > 0) + } + } + } else { + log.Println("API server: disabled") + } + // Handle signals for clean unmount sigChan := make(chan os.Signal, 1) signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM) @@ -358,6 +466,13 @@ func main() { <-sigChan log.Println("Received signal, unmounting...") + // Stop API server first + if apiServer != nil { + if err := apiServer.Stop(); err != nil { + log.Printf("Warning: Failed to stop API server: %v", err) + } + } + // Close filesystem (stops snapshot worker, TRIM, journal, etc.) nodeReg.Stop() if err := gfs.Close(); err != nil { @@ -378,6 +493,13 @@ func main() { // Wait for filesystem to be unmounted - this blocks until unmount server.Wait() + // Stop API server + if apiServer != nil { + if err := apiServer.Stop(); err != nil { + log.Printf("Warning: Failed to stop API server on exit: %v", err) + } + } + // Clean shutdown - close filesystem (handles snapshot worker, TRIM, journal) nodeReg.Stop() if err := gfs.Close(); err != nil { diff --git a/docs/API-CONFIG.md b/docs/API-CONFIG.md index bcfe5bf2..afa026d2 100644 --- a/docs/API-CONFIG.md +++ b/docs/API-CONFIG.md @@ -36,6 +36,7 @@ These flags are passed when starting `goclusterfs`: | `-format` | bool | `false` | Format the device (destroys all data) | | `-bytes-per-inode` | uint | `1048576` | With `-format`: one inode per this many bytes of device, 4096 to 16,777,216 inodes | | `-debug` | bool | `false` | Enable verbose debug logging | +| `-version` | bool | `false` | Print the version, commit and commit date, then exit | ### Cache Flags @@ -81,6 +82,21 @@ The kernel caches file attributes and directory entries for `-attr-timeout`. For | `-sfb` | bool | `true` | Ignored. SFB containers are disabled | | `-snapshots` | bool | `true` | Enable O(1) file snapshots | +### HTTP API Flags + +| Flag | Type | Default | Description | +|------|------|---------|-------------| +| `-api` | bool | `true` | Serve the HTTP API | +| `-api-addr` | string | `127.0.0.1:8080` | Listen address | +| `-api-token` | string | (empty) | Bearer token for `/api/v1/...` requests | +| `-api-cors` | string | (empty) | Comma-separated CORS allowed origins, or `*` | + +The API serves `GET /health`, `GET /metrics`, `GET /api/v1/status` and `GET /api/v1/stats/...`. Mount does not feed statistics to the API yet, so `/api/v1/stats/...` answers 503, `/health` only checks the API itself, and `/metrics` only reports `goclusterfs_up`. With `-api-token` set, `/api/v1/...` requests need `Authorization: Bearer `. `/health` and `/metrics` never need the token. + +By default the API only accepts connections from this host. To serve other hosts, set `-api-addr` (for example `:8080` or `10.0.0.5:8080`) and `-api-token`. Mount exits before it opens the device when the address is not loopback (`127.0.0.0/8`, `::1` or `localhost`) and the token is empty. The token is a command-line flag, so local users can read it with `ps`. + +Each mount on a host needs its own `-api-addr`. When the port is taken, mount logs a warning and runs without the API. + --- ## Cache Configuration @@ -413,7 +429,7 @@ Interval between heartbeat messages to detect node failures. |----------|-------| | Default | (empty) | -HMAC secret for message authentication. All nodes must use the same secret. +HMAC secret for message authentication. All nodes must use the same secret. With broadcast on and no secret, mount logs a `WARNING` line at startup. **Generating a secret**: ```bash diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index ac77360a..4e3db66e 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -63,7 +63,7 @@ newgrp fuse |-------------|---------| | Connectivity | All nodes on same L2 network segment | | Multicast | UDP multicast between all nodes. Unicast is only a fallback to peers learned over multicast. | -| Ports | UDP 31337 (configurable) | +| Ports | UDP 31337 (configurable). TCP 8080 on loopback for the HTTP API; open it only if you expose the API | | Latency | < 10ms between nodes recommended | --- @@ -87,7 +87,7 @@ sudo cp goclusterfs-mount goclusterfs-fsck /usr/local/bin/ ### Verify Build ```bash -./goclusterfs-mount -h +./goclusterfs-mount -version ./goclusterfs-fsck -version ``` @@ -417,6 +417,18 @@ openssl rand -hex 32 See the [Security Model](OPERATIONS.md#security-model) for what this does and does not protect. +Mount logs a `WARNING` line at startup when broadcast is on without a secret. + +### HTTP API Access + +The API listens on `127.0.0.1:8080` by default. To scrape `/metrics` or call the API from another host, set a token and a reachable address: + +```bash +./goclusterfs-mount ... -api-addr :8080 -api-token "$(openssl rand -hex 32)" +``` + +Mount refuses a non-loopback `-api-addr` without `-api-token`. See [HTTP API Flags](API-CONFIG.md#http-api-flags). + ### Firewall Rules ```bash diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md index 81f272c4..2d04cfad 100644 --- a/docs/OPERATIONS.md +++ b/docs/OPERATIONS.md @@ -522,13 +522,20 @@ GoClusterFS assumes every node, and everything that can reach the shared device **Broadcast cache invalidation.** Nodes send UDP messages (multicast group `239.192.74.75`, port `31337` by default) that tell peers to drop cached inodes and extents. Heartbeat and announce messages add unicast peers, which a node uses when multicast sends fail. Messages carry inode numbers but no file data. Losing them only delays cache updates until `-cache-ttl`. -- With an empty `-broadcast-secret` (the default), messages are not authenticated. Any host that can send to the port can make nodes drop their caches, and can add any address as a unicast peer. +- With an empty `-broadcast-secret` (the default), messages are not authenticated. Any host that can send to the port can make nodes drop their caches, and can add any address as a unicast peer. Mount logs a `WARNING` line at startup in this case. - With `-broadcast-secret`, every message carries an HMAC-SHA256 tag. Nodes drop messages with a missing or wrong tag, so all nodes need the same secret. - The only replay protection is a sequence number check that forgets messages after 5 minutes, so a recorded message can be sent again later, even with a secret. - Messages are never encrypted. Any host that joins the multicast group can see which inodes change. - The secret is a command-line flag, so local users on a node can read it with `ps`. -**Network listeners.** GoClusterFS has no HTTP API. Its only listener is UDP port 31337 on all interfaces, plus the multicast group. Limit that port to the cluster nodes with a firewall. +**HTTP API.** Each mount serves an HTTP API on `127.0.0.1:8080` (`-api-addr`), so only local users can reach it. It only answers `GET` requests and changes nothing. + +- To expose it, set `-api-addr` and `-api-token`. Mount refuses a non-loopback address without a token. +- `/health` and `/metrics` never need the token, so anyone who can reach the port can read them. +- The API uses plain HTTP. Put a TLS proxy in front of it if the token crosses an untrusted network. +- The token is a command-line flag, so local users can read it with `ps`. + +**Network listeners.** Each node listens on UDP port 31337 on all interfaces, plus the multicast group, and on TCP `-api-addr`. Limit the UDP port, and the API port if you expose it, to the cluster nodes and your monitoring hosts with a firewall. --- diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index e30dd8ce..b3ff397e 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -544,8 +544,8 @@ If this guide doesn't resolve your issue: uname -a cat /etc/os-release - # GoClusterFS version (goclusterfs-mount has no -version flag yet) - ./goclusterfs-fsck -version + # GoClusterFS version + ./goclusterfs-mount -version # Recent mount log tail -1000 /var/log/goclusterfs.log > mount.log diff --git a/internal/api/config.go b/internal/api/config.go new file mode 100644 index 00000000..ef4e4ca5 --- /dev/null +++ b/internal/api/config.go @@ -0,0 +1,160 @@ +package api + +import ( + "fmt" + "net" + "net/url" + "strings" + "time" +) + +// Config holds the configuration for the API server. +type Config struct { + // ListenAddr is the address to listen on (e.g., "127.0.0.1:8080" or ":8080"). + // Default: "127.0.0.1:8080" + ListenAddr string + + // AuthToken is the Bearer token for API authentication. + // If empty, authentication is disabled. + // Default: "" (disabled) + AuthToken string + + // CORSOrigins is the list of allowed CORS origins. + // If empty, CORS is disabled. + // Use "*" to allow all origins (not recommended for production). + // Default: nil (disabled) + CORSOrigins []string + + // ReadTimeout is the maximum duration for reading the entire request. + // Default: 30s + ReadTimeout time.Duration + + // WriteTimeout is the maximum duration for writing the response. + // Default: 30s + WriteTimeout time.Duration + + // IdleTimeout is the maximum duration to wait for the next request. + // Default: 60s + IdleTimeout time.Duration + + // ShutdownTimeout is the maximum duration to wait for graceful shutdown. + // Default: 10s + ShutdownTimeout time.Duration +} + +// DefaultConfig returns a Config with sensible defaults. +func DefaultConfig() Config { + return Config{ + ListenAddr: "127.0.0.1:8080", + AuthToken: "", + CORSOrigins: nil, + ReadTimeout: 30 * time.Second, + WriteTimeout: 30 * time.Second, + IdleTimeout: 60 * time.Second, + ShutdownTimeout: 10 * time.Second, + } +} + +// Validate checks the configuration for errors. +func (c *Config) Validate() error { + // Validate listen address + if c.ListenAddr == "" { + return fmt.Errorf("%w: listen address cannot be empty", ErrInvalidListenAddr) + } + + // Check if it's a valid host:port format + host, port, err := net.SplitHostPort(c.ListenAddr) + if err != nil { + return fmt.Errorf("%w: %v", ErrInvalidListenAddr, err) + } + + // If host is specified, validate it + if host != "" { + ip := net.ParseIP(host) + if ip == nil { + // Not an IP, check if it could be a hostname + if strings.ContainsAny(host, " \t\n\r") { + return fmt.Errorf("%w: invalid host %q", ErrInvalidListenAddr, host) + } + } + } + + // Port should be a number or empty (for dynamic allocation) + if port != "" && port != "0" { + // net.SplitHostPort already validated it's a valid port string + _ = port + } + + // Validate timeouts + if c.ReadTimeout < 0 { + return fmt.Errorf("%w: read timeout must be >= 0", ErrInvalidTimeout) + } + if c.WriteTimeout < 0 { + return fmt.Errorf("%w: write timeout must be >= 0", ErrInvalidTimeout) + } + if c.IdleTimeout < 0 { + return fmt.Errorf("%w: idle timeout must be >= 0", ErrInvalidTimeout) + } + if c.ShutdownTimeout < 0 { + return fmt.Errorf("%w: shutdown timeout must be >= 0", ErrInvalidTimeout) + } + + // Validate CORS origins + for _, origin := range c.CORSOrigins { + if origin == "*" { + continue // Wildcard is allowed + } + if origin == "" { + return fmt.Errorf("%w: empty origin", ErrInvalidCORSOrigin) + } + // Parse as URL to validate format + u, err := url.Parse(origin) + if err != nil { + return fmt.Errorf("%w: %v", ErrInvalidCORSOrigin, err) + } + if u.Scheme == "" || u.Host == "" { + return fmt.Errorf("%w: origin must have scheme and host: %q", ErrInvalidCORSOrigin, origin) + } + } + + return nil +} + +// LoopbackOnly reports whether ListenAddr accepts connections only from this host. +func (c *Config) LoopbackOnly() bool { + host, _, err := net.SplitHostPort(c.ListenAddr) + if err != nil { + return false + } + if host == "localhost" { + return true + } + ip := net.ParseIP(host) + return ip != nil && ip.IsLoopback() +} + +// CheckExposure refuses a config that serves other hosts without an auth token. +func (c *Config) CheckExposure() error { + if c.AuthToken == "" && !c.LoopbackOnly() { + return fmt.Errorf("%w: %s", ErrUnauthenticatedRemote, c.ListenAddr) + } + return nil +} + +// WithListenAddr returns a copy of the config with a new listen address. +func (c Config) WithListenAddr(addr string) Config { + c.ListenAddr = addr + return c +} + +// WithAuthToken returns a copy of the config with a new auth token. +func (c Config) WithAuthToken(token string) Config { + c.AuthToken = token + return c +} + +// WithCORSOrigins returns a copy of the config with new CORS origins. +func (c Config) WithCORSOrigins(origins ...string) Config { + c.CORSOrigins = origins + return c +} diff --git a/internal/api/doc.go b/internal/api/doc.go new file mode 100644 index 00000000..d73d2bd9 --- /dev/null +++ b/internal/api/doc.go @@ -0,0 +1,46 @@ +// Package api provides the HTTP JSON API server for GoClusterFS. +// +// The API server runs embedded within the mount process and exposes +// endpoints for health checks, status queries, statistics, and +// administrative operations. It is consumed by the gfsctl CLI tool +// and the web dashboard. +// +// # Endpoints +// +// The following endpoints are available: +// +// - GET /health - Health check (always returns 200) +// - GET /api/v1/status - Filesystem status overview +// - GET /api/v1/stats/* - Detailed component statistics +// - GET /metrics - Prometheus metrics export +// +// # Authentication +// +// Authentication is via Bearer token when configured. Set the AuthToken +// in Config to enable authentication. When enabled, all endpoints except +// /health require a valid Authorization header: +// +// Authorization: Bearer +// +// # Configuration +// +// Use DefaultConfig() to get sensible defaults, then customize as needed: +// +// cfg := api.DefaultConfig() +// cfg.ListenAddr = ":9090" +// cfg.AuthToken = "secret-token" +// server, err := api.NewServer(cfg) +// +// # Lifecycle +// +// The server follows the standard Start/Stop pattern: +// +// server, err := api.NewServer(cfg) +// if err != nil { +// log.Fatal(err) +// } +// if err := server.Start(ctx); err != nil { +// log.Fatal(err) +// } +// defer server.Stop() +package api diff --git a/internal/api/errors.go b/internal/api/errors.go new file mode 100644 index 00000000..ee229a5b --- /dev/null +++ b/internal/api/errors.go @@ -0,0 +1,27 @@ +package api + +import "errors" + +// Package-level errors for the API server. +var ( + // ErrServerAlreadyStarted is returned when Start is called on an already running server. + ErrServerAlreadyStarted = errors.New("api: server already started") + + // ErrServerNotStarted is returned when operations require a running server. + ErrServerNotStarted = errors.New("api: server not started") + + // ErrInvalidListenAddr is returned when the listen address is malformed. + ErrInvalidListenAddr = errors.New("api: invalid listen address") + + // ErrInvalidTimeout is returned when a timeout value is invalid. + ErrInvalidTimeout = errors.New("api: invalid timeout value (must be positive)") + + // ErrInvalidCORSOrigin is returned when a CORS origin is malformed. + ErrInvalidCORSOrigin = errors.New("api: invalid CORS origin") + + // ErrUnauthenticatedRemote is returned when other hosts could reach the API without a token. + ErrUnauthenticatedRemote = errors.New("api: no auth token set for an address other hosts can reach") + + // ErrShutdownTimeout is returned when graceful shutdown times out. + ErrShutdownTimeout = errors.New("api: shutdown timed out") +) diff --git a/internal/api/exposure_test.go b/internal/api/exposure_test.go new file mode 100644 index 00000000..b59c4ef6 --- /dev/null +++ b/internal/api/exposure_test.go @@ -0,0 +1,40 @@ +package api + +import ( + "errors" + "testing" +) + +func TestCheckExposure(t *testing.T) { + tests := []struct { + addr string + token string + refused bool + }{ + {"127.0.0.1:8080", "", false}, + {"127.1.2.3:8080", "", false}, + {"localhost:8080", "", false}, + {"[::1]:8080", "", false}, + {":8080", "", true}, + {"0.0.0.0:8080", "", true}, + {"[::]:8080", "", true}, + {"10.0.0.5:8080", "", true}, + {"node1.example.com:8080", "", true}, + {":8080", "secret", false}, + {"10.0.0.5:8080", "secret", false}, + } + for _, tt := range tests { + cfg := DefaultConfig().WithListenAddr(tt.addr).WithAuthToken(tt.token) + err := cfg.CheckExposure() + if tt.refused != errors.Is(err, ErrUnauthenticatedRemote) { + t.Errorf("CheckExposure(%q, token=%q) = %v, want refused=%v", tt.addr, tt.token, err, tt.refused) + } + } +} + +func TestDefaultConfigPassesExposureCheck(t *testing.T) { + cfg := DefaultConfig() + if err := cfg.CheckExposure(); err != nil { + t.Fatalf("default config refused: %v", err) + } +} diff --git a/internal/api/health.go b/internal/api/health.go new file mode 100644 index 00000000..a89b291b --- /dev/null +++ b/internal/api/health.go @@ -0,0 +1,69 @@ +package api + +import "context" + +// HealthChecker is the interface that components implement to report health. +type HealthChecker interface { + // Name returns the component name for health reporting. + Name() string + + // CheckHealth returns the health status of the component. + // The context allows for timeout on health checks. + CheckHealth(ctx context.Context) ComponentHealth +} + +// HealthCheckFunc allows a function to implement HealthChecker. +type HealthCheckFunc struct { + name string + fn func(ctx context.Context) ComponentHealth +} + +// NewHealthCheckFunc creates a HealthChecker from a function. +func NewHealthCheckFunc(name string, fn func(ctx context.Context) ComponentHealth) HealthChecker { + return &HealthCheckFunc{name: name, fn: fn} +} + +func (h *HealthCheckFunc) Name() string { + return h.name +} + +func (h *HealthCheckFunc) CheckHealth(ctx context.Context) ComponentHealth { + return h.fn(ctx) +} + +// AggregateHealth runs all health checks and returns aggregate status. +// Returns HealthStatusOK if all checks pass. +// Returns HealthStatusDegraded if any check is degraded (but none unhealthy). +// Returns HealthStatusUnhealthy if any check is unhealthy. +func AggregateHealth(ctx context.Context, checkers ...HealthChecker) HealthResponse { + checks := make(map[string]ComponentHealth) + overall := HealthStatusOK + + for _, checker := range checkers { + health := checker.CheckHealth(ctx) + checks[checker.Name()] = health + + // Determine overall status (unhealthy > degraded > ok) + switch health.Status { + case HealthStatusUnhealthy: + overall = HealthStatusUnhealthy + case HealthStatusDegraded: + if overall != HealthStatusUnhealthy { + overall = HealthStatusDegraded + } + } + } + + return HealthResponse{ + Status: overall, + Checks: checks, + } +} + +// DefaultHealthChecker returns a checker that always reports healthy. +// This is used as a placeholder until real components are injected. +func DefaultHealthChecker() HealthChecker { + return NewHealthCheckFunc("api", func(ctx context.Context) ComponentHealth { + return ComponentHealth{Status: HealthStatusOK} + }) +} diff --git a/internal/api/health_test.go b/internal/api/health_test.go new file mode 100644 index 00000000..b0e9f2ac --- /dev/null +++ b/internal/api/health_test.go @@ -0,0 +1,214 @@ +package api + +import ( + "context" + "encoding/json" + "net/http" + "testing" + "time" +) + +func TestAggregateHealth_AllOK(t *testing.T) { + checkers := []HealthChecker{ + NewHealthCheckFunc("cache", func(ctx context.Context) ComponentHealth { + return ComponentHealth{Status: HealthStatusOK} + }), + NewHealthCheckFunc("journal", func(ctx context.Context) ComponentHealth { + return ComponentHealth{Status: HealthStatusOK} + }), + } + + resp := AggregateHealth(context.Background(), checkers...) + + if resp.Status != HealthStatusOK { + t.Errorf("expected OK, got %s", resp.Status) + } + if len(resp.Checks) != 2 { + t.Errorf("expected 2 checks, got %d", len(resp.Checks)) + } +} + +func TestAggregateHealth_OneDegraded(t *testing.T) { + checkers := []HealthChecker{ + NewHealthCheckFunc("cache", func(ctx context.Context) ComponentHealth { + return ComponentHealth{Status: HealthStatusOK} + }), + NewHealthCheckFunc("journal", func(ctx context.Context) ComponentHealth { + return ComponentHealth{Status: HealthStatusDegraded, Message: "low disk space"} + }), + } + + resp := AggregateHealth(context.Background(), checkers...) + + if resp.Status != HealthStatusDegraded { + t.Errorf("expected Degraded, got %s", resp.Status) + } + if resp.Checks["journal"].Message != "low disk space" { + t.Errorf("expected message, got %q", resp.Checks["journal"].Message) + } +} + +func TestAggregateHealth_OneUnhealthy(t *testing.T) { + checkers := []HealthChecker{ + NewHealthCheckFunc("cache", func(ctx context.Context) ComponentHealth { + return ComponentHealth{Status: HealthStatusDegraded} + }), + NewHealthCheckFunc("journal", func(ctx context.Context) ComponentHealth { + return ComponentHealth{Status: HealthStatusUnhealthy, Message: "write failure"} + }), + } + + resp := AggregateHealth(context.Background(), checkers...) + + if resp.Status != HealthStatusUnhealthy { + t.Errorf("expected Unhealthy, got %s", resp.Status) + } +} + +func TestAggregateHealth_Empty(t *testing.T) { + resp := AggregateHealth(context.Background()) + + if resp.Status != HealthStatusOK { + t.Errorf("expected OK for empty checkers, got %s", resp.Status) + } + if len(resp.Checks) != 0 { + t.Errorf("expected no checks, got %d", len(resp.Checks)) + } +} + +func TestHealthEndpoint_WithCheckers(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + // Register a degraded checker + server.RegisterHealthChecker(NewHealthCheckFunc("test", func(ctx context.Context) ComponentHealth { + return ComponentHealth{Status: HealthStatusDegraded, Message: "test warning"} + })) + + if err := server.Start(context.Background()); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + time.Sleep(10 * time.Millisecond) + + resp, err := http.Get("http://" + server.Addr() + "/health") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + // Degraded returns 200 (only unhealthy returns 503) + if resp.StatusCode != http.StatusOK { + t.Errorf("expected 200, got %d", resp.StatusCode) + } + + var health HealthResponse + if err := json.NewDecoder(resp.Body).Decode(&health); err != nil { + t.Fatalf("decode error: %v", err) + } + + if health.Status != HealthStatusDegraded { + t.Errorf("expected degraded status, got %s", health.Status) + } + if health.Checks["test"].Message != "test warning" { + t.Errorf("expected message, got %q", health.Checks["test"].Message) + } +} + +func TestHealthEndpoint_Unhealthy_Returns503(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + // Register an unhealthy checker + server.RegisterHealthChecker(NewHealthCheckFunc("critical", func(ctx context.Context) ComponentHealth { + return ComponentHealth{Status: HealthStatusUnhealthy, Message: "critical failure"} + })) + + if err := server.Start(context.Background()); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + time.Sleep(10 * time.Millisecond) + + resp, err := http.Get("http://" + server.Addr() + "/health") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + // Unhealthy returns 503 + if resp.StatusCode != http.StatusServiceUnavailable { + t.Errorf("expected 503, got %d", resp.StatusCode) + } + + var health HealthResponse + if err := json.NewDecoder(resp.Body).Decode(&health); err != nil { + t.Fatalf("decode error: %v", err) + } + + if health.Status != HealthStatusUnhealthy { + t.Errorf("expected unhealthy status, got %s", health.Status) + } +} + +func TestHealthEndpoint_MultipleCheckers(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + // Register multiple checkers + server.RegisterHealthChecker(NewHealthCheckFunc("cache", func(ctx context.Context) ComponentHealth { + return ComponentHealth{Status: HealthStatusOK} + })) + server.RegisterHealthChecker(NewHealthCheckFunc("journal", func(ctx context.Context) ComponentHealth { + return ComponentHealth{Status: HealthStatusOK} + })) + server.RegisterHealthChecker(NewHealthCheckFunc("device", func(ctx context.Context) ComponentHealth { + return ComponentHealth{Status: HealthStatusOK} + })) + + if err := server.Start(context.Background()); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + time.Sleep(10 * time.Millisecond) + + resp, err := http.Get("http://" + server.Addr() + "/health") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusOK { + t.Errorf("expected 200, got %d", resp.StatusCode) + } + + var health HealthResponse + if err := json.NewDecoder(resp.Body).Decode(&health); err != nil { + t.Fatalf("decode error: %v", err) + } + + if len(health.Checks) != 3 { + t.Errorf("expected 3 checks, got %d", len(health.Checks)) + } +} + +func TestDefaultHealthChecker(t *testing.T) { + checker := DefaultHealthChecker() + if checker.Name() != "api" { + t.Errorf("expected name 'api', got %q", checker.Name()) + } + + health := checker.CheckHealth(context.Background()) + if health.Status != HealthStatusOK { + t.Errorf("expected OK, got %s", health.Status) + } +} diff --git a/internal/api/middleware.go b/internal/api/middleware.go new file mode 100644 index 00000000..3d267d19 --- /dev/null +++ b/internal/api/middleware.go @@ -0,0 +1,142 @@ +package api + +import ( + "crypto/subtle" + "log" + "net/http" + "strings" + "time" +) + +// Middleware is a function that wraps an http.Handler. +type Middleware func(http.Handler) http.Handler + +// Chain applies middlewares in order (first middleware is outermost). +func Chain(h http.Handler, middlewares ...Middleware) http.Handler { + for i := len(middlewares) - 1; i >= 0; i-- { + h = middlewares[i](h) + } + return h +} + +// responseWriter wraps http.ResponseWriter to capture status code. +type responseWriter struct { + http.ResponseWriter + status int +} + +func (rw *responseWriter) WriteHeader(code int) { + rw.status = code + rw.ResponseWriter.WriteHeader(code) +} + +// LoggingMiddleware logs HTTP requests with method, path, status, and duration. +func LoggingMiddleware(next http.Handler) http.Handler { + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + start := time.Now() + + rw := &responseWriter{ResponseWriter: w, status: http.StatusOK} + next.ServeHTTP(rw, r) + + log.Printf("api: %s %s %d %s", + r.Method, + r.URL.Path, + rw.status, + time.Since(start).Round(time.Microsecond), + ) + }) +} + +// AuthMiddleware returns a middleware that validates Bearer tokens. +// If token is empty, authentication is disabled. +// Paths in skipPaths are not authenticated (e.g., /health, /metrics). +func AuthMiddleware(token string, skipPaths ...string) Middleware { + return func(next http.Handler) http.Handler { + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + // If no token configured, skip auth + if token == "" { + next.ServeHTTP(w, r) + return + } + + // Check if path should skip auth + for _, path := range skipPaths { + if r.URL.Path == path || strings.HasPrefix(r.URL.Path, path+"/") { + next.ServeHTTP(w, r) + return + } + } + + // Extract Bearer token from Authorization header + auth := r.Header.Get("Authorization") + if auth == "" { + writeError(w, http.StatusUnauthorized, "missing authorization header", "") + return + } + + if !strings.HasPrefix(auth, "Bearer ") { + writeError(w, http.StatusUnauthorized, "invalid authorization format", "use Bearer token") + return + } + + providedToken := strings.TrimPrefix(auth, "Bearer ") + + // Constant-time comparison to prevent timing attacks + if subtle.ConstantTimeCompare([]byte(providedToken), []byte(token)) != 1 { + writeError(w, http.StatusUnauthorized, "invalid token", "") + return + } + + next.ServeHTTP(w, r) + }) + } +} + +// CORSMiddleware returns a middleware that handles CORS headers. +// If origins is empty, CORS is disabled. +// Use "*" to allow all origins (not recommended for production). +func CORSMiddleware(origins []string) Middleware { + return func(next http.Handler) http.Handler { + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + // If no origins configured, skip CORS + if len(origins) == 0 { + next.ServeHTTP(w, r) + return + } + + origin := r.Header.Get("Origin") + if origin == "" { + next.ServeHTTP(w, r) + return + } + + // Check if origin is allowed + allowed := false + for _, o := range origins { + if o == "*" || o == origin { + allowed = true + break + } + } + + if !allowed { + next.ServeHTTP(w, r) + return + } + + // Set CORS headers + w.Header().Set("Access-Control-Allow-Origin", origin) + w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS") + w.Header().Set("Access-Control-Allow-Headers", "Authorization, Content-Type") + w.Header().Set("Access-Control-Max-Age", "86400") + + // Handle preflight requests + if r.Method == http.MethodOptions { + w.WriteHeader(http.StatusNoContent) + return + } + + next.ServeHTTP(w, r) + }) + } +} diff --git a/internal/api/middleware_test.go b/internal/api/middleware_test.go new file mode 100644 index 00000000..b43e6a72 --- /dev/null +++ b/internal/api/middleware_test.go @@ -0,0 +1,324 @@ +package api + +import ( + "context" + "net/http" + "testing" + "time" +) + +func TestAuthMiddleware_NoTokenConfigured(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + if err := server.Start(context.Background()); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + time.Sleep(10 * time.Millisecond) + + // Request without auth should succeed when no token configured + resp, err := http.Get("http://" + server.Addr() + "/api/v1/status") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusOK { + t.Errorf("expected 200, got %d", resp.StatusCode) + } +} + +func TestAuthMiddleware_ValidToken(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0").WithAuthToken("secret-token") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + if err := server.Start(context.Background()); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + time.Sleep(10 * time.Millisecond) + + client := &http.Client{} + req, _ := http.NewRequest("GET", "http://"+server.Addr()+"/api/v1/status", nil) + req.Header.Set("Authorization", "Bearer secret-token") + + resp, err := client.Do(req) + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusOK { + t.Errorf("expected 200, got %d", resp.StatusCode) + } +} + +func TestAuthMiddleware_MissingHeader(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0").WithAuthToken("secret-token") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + if err := server.Start(context.Background()); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + time.Sleep(10 * time.Millisecond) + + resp, err := http.Get("http://" + server.Addr() + "/api/v1/status") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusUnauthorized { + t.Errorf("expected 401, got %d", resp.StatusCode) + } +} + +func TestAuthMiddleware_InvalidFormat(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0").WithAuthToken("secret-token") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + if err := server.Start(context.Background()); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + time.Sleep(10 * time.Millisecond) + + client := &http.Client{} + req, _ := http.NewRequest("GET", "http://"+server.Addr()+"/api/v1/status", nil) + req.Header.Set("Authorization", "Basic secret-token") + + resp, err := client.Do(req) + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusUnauthorized { + t.Errorf("expected 401, got %d", resp.StatusCode) + } +} + +func TestAuthMiddleware_WrongToken(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0").WithAuthToken("secret-token") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + if err := server.Start(context.Background()); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + time.Sleep(10 * time.Millisecond) + + client := &http.Client{} + req, _ := http.NewRequest("GET", "http://"+server.Addr()+"/api/v1/status", nil) + req.Header.Set("Authorization", "Bearer wrong-token") + + resp, err := client.Do(req) + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusUnauthorized { + t.Errorf("expected 401, got %d", resp.StatusCode) + } +} + +func TestAuthMiddleware_SkipPaths(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0").WithAuthToken("secret-token") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + if err := server.Start(context.Background()); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + time.Sleep(10 * time.Millisecond) + + // /health and /metrics should be accessible without auth + paths := []string{"/health", "/metrics"} + for _, path := range paths { + t.Run(path, func(t *testing.T) { + resp, err := http.Get("http://" + server.Addr() + path) + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusOK { + t.Errorf("expected 200 for %s, got %d", path, resp.StatusCode) + } + }) + } +} + +func TestCORSMiddleware_NoOrigins(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + if err := server.Start(context.Background()); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + time.Sleep(10 * time.Millisecond) + + client := &http.Client{} + req, _ := http.NewRequest("GET", "http://"+server.Addr()+"/health", nil) + req.Header.Set("Origin", "http://example.com") + + resp, err := client.Do(req) + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + // No CORS headers should be set + if cors := resp.Header.Get("Access-Control-Allow-Origin"); cors != "" { + t.Errorf("expected no CORS header, got %q", cors) + } +} + +func TestCORSMiddleware_AllowedOrigin(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0").WithCORSOrigins("http://example.com") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + if err := server.Start(context.Background()); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + time.Sleep(10 * time.Millisecond) + + client := &http.Client{} + req, _ := http.NewRequest("GET", "http://"+server.Addr()+"/health", nil) + req.Header.Set("Origin", "http://example.com") + + resp, err := client.Do(req) + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + cors := resp.Header.Get("Access-Control-Allow-Origin") + if cors != "http://example.com" { + t.Errorf("expected CORS header 'http://example.com', got %q", cors) + } +} + +func TestCORSMiddleware_DisallowedOrigin(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0").WithCORSOrigins("http://example.com") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + if err := server.Start(context.Background()); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + time.Sleep(10 * time.Millisecond) + + client := &http.Client{} + req, _ := http.NewRequest("GET", "http://"+server.Addr()+"/health", nil) + req.Header.Set("Origin", "http://evil.com") + + resp, err := client.Do(req) + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + // No CORS headers for disallowed origin + if cors := resp.Header.Get("Access-Control-Allow-Origin"); cors != "" { + t.Errorf("expected no CORS header for disallowed origin, got %q", cors) + } +} + +func TestCORSMiddleware_Wildcard(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0").WithCORSOrigins("*") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + if err := server.Start(context.Background()); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + time.Sleep(10 * time.Millisecond) + + client := &http.Client{} + req, _ := http.NewRequest("GET", "http://"+server.Addr()+"/health", nil) + req.Header.Set("Origin", "http://any-origin.com") + + resp, err := client.Do(req) + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + cors := resp.Header.Get("Access-Control-Allow-Origin") + if cors != "http://any-origin.com" { + t.Errorf("expected CORS header 'http://any-origin.com', got %q", cors) + } +} + +func TestCORSMiddleware_Preflight(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0").WithCORSOrigins("http://example.com") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + if err := server.Start(context.Background()); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + time.Sleep(10 * time.Millisecond) + + client := &http.Client{} + req, _ := http.NewRequest("OPTIONS", "http://"+server.Addr()+"/api/v1/status", nil) + req.Header.Set("Origin", "http://example.com") + req.Header.Set("Access-Control-Request-Method", "GET") + + resp, err := client.Do(req) + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusNoContent { + t.Errorf("expected 204 for preflight, got %d", resp.StatusCode) + } + + if cors := resp.Header.Get("Access-Control-Allow-Origin"); cors != "http://example.com" { + t.Errorf("expected CORS header, got %q", cors) + } + + if methods := resp.Header.Get("Access-Control-Allow-Methods"); methods == "" { + t.Error("expected Access-Control-Allow-Methods header") + } +} diff --git a/internal/api/routes.go b/internal/api/routes.go new file mode 100644 index 00000000..690e1b4e --- /dev/null +++ b/internal/api/routes.go @@ -0,0 +1,284 @@ +package api + +import ( + "net/http" + "strings" +) + +// registerRoutes registers all API routes with the server's router. +// Routes are organized into logical groups: +// - /health - Health check (no auth required) +// - /api/v1/* - Versioned API endpoints (auth required when configured) +// - /metrics - Prometheus metrics (no auth required) +func (s *Server) registerRoutes() { + // Health check endpoint - always accessible, no auth required + s.router.HandleFunc("/health", s.handleHealth) + + // API v1 route group - catch-all handler for versioned endpoints + s.router.HandleFunc("/api/v1/", s.handleAPIv1) + + // Metrics endpoint for Prometheus scraping + s.router.HandleFunc("/metrics", s.handleMetrics) +} + +// handleHealth handles GET /health requests. +// Returns aggregate health status from all registered health checkers. +// Status codes: 200 OK, 503 Service Unavailable (if unhealthy). +func (s *Server) handleHealth(w http.ResponseWriter, r *http.Request) { + if r.Method != http.MethodGet && r.Method != http.MethodHead { + writeError(w, http.StatusMethodNotAllowed, "method not allowed", "use GET or HEAD") + return + } + + checkers := s.GetHealthCheckers() + if len(checkers) == 0 { + // No checkers registered - just report API is OK + writeJSON(w, http.StatusOK, HealthResponse{ + Status: HealthStatusOK, + }) + return + } + + // Aggregate health from all checkers + resp := AggregateHealth(r.Context(), checkers...) + + // Return 503 if unhealthy, otherwise 200 + status := http.StatusOK + if resp.Status == HealthStatusUnhealthy { + status = http.StatusServiceUnavailable + } + writeJSON(w, status, resp) +} + +// handleAPIv1 is the catch-all handler for /api/v1/* routes. +func (s *Server) handleAPIv1(w http.ResponseWriter, r *http.Request) { + path := strings.TrimPrefix(r.URL.Path, "/api/v1") + + switch { + case path == "/status" || path == "/status/": + s.handleStatus(w, r) + case strings.HasPrefix(path, "/stats"): + s.handleStats(w, r) + default: + writeError(w, http.StatusNotFound, "endpoint not found", "") + } +} + +// handleStatus handles GET /api/v1/status requests. +// Returns comprehensive filesystem status including version, uptime, and capacity. +func (s *Server) handleStatus(w http.ResponseWriter, r *http.Request) { + if r.Method != http.MethodGet { + writeError(w, http.StatusMethodNotAllowed, "method not allowed", "use GET") + return + } + + build := GetBuildInfo() + resp := StatusResponse{ + Status: "ok", + Version: build.Version, + GitCommit: build.GitCommit, + BuildTime: build.BuildTime, + GoVersion: build.GoVersion, + UptimeSeconds: int64(s.Uptime().Seconds()), + } + + // Add filesystem status if provider is available + if provider := s.GetStatusProvider(); provider != nil { + resp.MountPath = provider.MountPath() + resp.DevicePath = provider.DevicePath() + resp.MountState = provider.MountState() + resp.Capacity = provider.Capacity() + } + + writeJSON(w, http.StatusOK, resp) +} + +// handleStats handles GET /api/v1/stats/* requests. +// Routes to specific stats handlers based on the path suffix. +func (s *Server) handleStats(w http.ResponseWriter, r *http.Request) { + if r.Method != http.MethodGet { + writeError(w, http.StatusMethodNotAllowed, "method not allowed", "use GET") + return + } + + // Extract the stats sub-path + path := strings.TrimPrefix(r.URL.Path, "/api/v1/stats") + path = strings.TrimSuffix(path, "/") + + switch path { + case "", "/overview": + s.handleStatsOverview(w, r) + case "/cache": + s.handleStatsCache(w, r) + case "/journal": + s.handleStatsJournal(w, r) + case "/trim": + s.handleStatsTrim(w, r) + case "/lock": + s.handleStatsLock(w, r) + case "/sfb": + s.handleStatsSFB(w, r) + case "/cluster": + s.handleStatsCluster(w, r) + case "/all": + s.handleStatsAll(w, r) + default: + writeError(w, http.StatusNotFound, "stats endpoint not found", "valid endpoints: cache, journal, trim, lock, sfb, cluster, all") + } +} + +// handleStatsOverview handles GET /api/v1/stats requests. +// Returns a summary of key statistics from all components. +func (s *Server) handleStatsOverview(w http.ResponseWriter, r *http.Request) { + provider := s.GetStatsProvider() + if provider == nil { + writeError(w, http.StatusServiceUnavailable, "stats not available", "no stats provider configured") + return + } + + resp := StatsOverviewResponse{ + Cache: provider.CacheStats(), + Journal: provider.JournalStats(), + } + writeJSON(w, http.StatusOK, resp) +} + +// handleStatsCache handles GET /api/v1/stats/cache requests. +// Returns detailed cache hit/miss statistics. +func (s *Server) handleStatsCache(w http.ResponseWriter, r *http.Request) { + provider := s.GetStatsProvider() + if provider == nil { + writeError(w, http.StatusServiceUnavailable, "stats not available", "no stats provider configured") + return + } + + stats := provider.CacheStats() + if stats == nil { + writeError(w, http.StatusNotFound, "cache stats not available", "cache component not initialized") + return + } + + writeJSON(w, http.StatusOK, stats) +} + +// handleStatsJournal handles GET /api/v1/stats/journal requests. +// Returns journal transaction and space statistics. +func (s *Server) handleStatsJournal(w http.ResponseWriter, r *http.Request) { + provider := s.GetStatsProvider() + if provider == nil { + writeError(w, http.StatusServiceUnavailable, "stats not available", "no stats provider configured") + return + } + + stats := provider.JournalStats() + if stats == nil { + writeError(w, http.StatusNotFound, "journal stats not available", "journal component not initialized") + return + } + + writeJSON(w, http.StatusOK, stats) +} + +// handleStatsTrim handles GET /api/v1/stats/trim requests. +// Returns TRIM/discard operation statistics. +func (s *Server) handleStatsTrim(w http.ResponseWriter, r *http.Request) { + provider := s.GetStatsProvider() + if provider == nil { + writeError(w, http.StatusServiceUnavailable, "stats not available", "no stats provider configured") + return + } + + stats := provider.TrimStats() + if stats == nil { + writeError(w, http.StatusNotFound, "trim stats not available", "trim component not initialized") + return + } + + writeJSON(w, http.StatusOK, stats) +} + +// handleStatsLock handles GET /api/v1/stats/lock requests. +// Returns lock contention and hint cache statistics. +func (s *Server) handleStatsLock(w http.ResponseWriter, r *http.Request) { + provider := s.GetStatsProvider() + if provider == nil { + writeError(w, http.StatusServiceUnavailable, "stats not available", "no stats provider configured") + return + } + + stats := provider.LockStats() + if stats == nil { + writeError(w, http.StatusNotFound, "lock stats not available", "lock component not initialized") + return + } + + writeJSON(w, http.StatusOK, stats) +} + +// handleStatsSFB handles GET /api/v1/stats/sfb requests. +// Returns Sparse File Bitmap (block allocation) statistics. +func (s *Server) handleStatsSFB(w http.ResponseWriter, r *http.Request) { + provider := s.GetStatsProvider() + if provider == nil { + writeError(w, http.StatusServiceUnavailable, "stats not available", "no stats provider configured") + return + } + + stats := provider.SFBStats() + if stats == nil { + writeError(w, http.StatusNotFound, "sfb stats not available", "block allocator not initialized") + return + } + + writeJSON(w, http.StatusOK, stats) +} + +// handleStatsCluster handles GET /api/v1/stats/cluster requests. +// Returns cluster membership and node information. +func (s *Server) handleStatsCluster(w http.ResponseWriter, r *http.Request) { + provider := s.GetStatsProvider() + if provider == nil { + writeError(w, http.StatusServiceUnavailable, "stats not available", "no stats provider configured") + return + } + + stats := provider.ClusterInfo() + if stats == nil { + writeError(w, http.StatusNotFound, "cluster info not available", "running in standalone mode") + return + } + + writeJSON(w, http.StatusOK, stats) +} + +// handleStatsAll handles GET /api/v1/stats/all requests. +// Returns a combined snapshot of all available statistics. +func (s *Server) handleStatsAll(w http.ResponseWriter, r *http.Request) { + provider := s.GetStatsProvider() + if provider == nil { + writeError(w, http.StatusServiceUnavailable, "stats not available", "no stats provider configured") + return + } + + stats := provider.AllStats() + if stats == nil { + writeError(w, http.StatusServiceUnavailable, "failed to collect stats", "") + return + } + + writeJSON(w, http.StatusOK, stats) +} + +// handleMetrics handles GET /metrics requests for Prometheus scraping. +func (s *Server) handleMetrics(w http.ResponseWriter, r *http.Request) { + if r.Method != http.MethodGet { + writeError(w, http.StatusMethodNotAllowed, "method not allowed", "use GET") + return + } + + w.Header().Set("Content-Type", "text/plain; charset=utf-8") + w.WriteHeader(http.StatusOK) + w.Write([]byte("# HELP goclusterfs_up Indicates if GoClusterFS is up\n")) + w.Write([]byte("# TYPE goclusterfs_up gauge\n")) + w.Write([]byte("goclusterfs_up 1\n")) +} diff --git a/internal/api/routes_test.go b/internal/api/routes_test.go new file mode 100644 index 00000000..66cc5364 --- /dev/null +++ b/internal/api/routes_test.go @@ -0,0 +1,275 @@ +package api + +import ( + "context" + "encoding/json" + "net/http" + "strings" + "testing" + "time" +) + +// startTestServer creates and starts a test server, returning it for cleanup. +func startTestServer(t *testing.T) *Server { + t.Helper() + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + if err := server.Start(context.Background()); err != nil { + t.Fatalf("Start error: %v", err) + } + + time.Sleep(10 * time.Millisecond) + return server +} + +func TestRoutes_Status(t *testing.T) { + server := startTestServer(t) + defer server.Stop() + + resp, err := http.Get("http://" + server.Addr() + "/api/v1/status") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusOK { + t.Errorf("expected status 200, got %d", resp.StatusCode) + } + + var status StatusResponse + if err := json.NewDecoder(resp.Body).Decode(&status); err != nil { + t.Fatalf("decode error: %v", err) + } + + if status.Status != "ok" { + t.Errorf("expected status 'ok', got %q", status.Status) + } + if status.Version != "dev" { + t.Errorf("expected version 'dev', got %q", status.Version) + } +} + +func TestRoutes_StatusWithTrailingSlash(t *testing.T) { + server := startTestServer(t) + defer server.Stop() + + resp, err := http.Get("http://" + server.Addr() + "/api/v1/status/") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusOK { + t.Errorf("expected status 200, got %d", resp.StatusCode) + } +} + +func TestRoutes_Metrics(t *testing.T) { + server := startTestServer(t) + defer server.Stop() + + resp, err := http.Get("http://" + server.Addr() + "/metrics") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusOK { + t.Errorf("expected status 200, got %d", resp.StatusCode) + } + + contentType := resp.Header.Get("Content-Type") + if !strings.HasPrefix(contentType, "text/plain") { + t.Errorf("expected text/plain content-type, got %q", contentType) + } +} + +func TestRoutes_Stats_NoProvider(t *testing.T) { + server := startTestServer(t) + defer server.Stop() + + // Without a StatsProvider configured, stats endpoints return 503 + resp, err := http.Get("http://" + server.Addr() + "/api/v1/stats/cache") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusServiceUnavailable { + t.Errorf("expected status 503, got %d", resp.StatusCode) + } +} + +func TestRoutes_APIv1_NotFound(t *testing.T) { + server := startTestServer(t) + defer server.Stop() + + resp, err := http.Get("http://" + server.Addr() + "/api/v1/unknown") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusNotFound { + t.Errorf("expected status 404, got %d", resp.StatusCode) + } +} + +func TestRoutes_MethodNotAllowed(t *testing.T) { + server := startTestServer(t) + defer server.Stop() + + tests := []struct { + name string + path string + method string + }{ + {"health POST", "/health", http.MethodPost}, + {"status POST", "/api/v1/status", http.MethodPost}, + {"metrics POST", "/metrics", http.MethodPost}, + } + + client := &http.Client{} + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + req, err := http.NewRequest(tt.method, "http://"+server.Addr()+tt.path, nil) + if err != nil { + t.Fatalf("create request error: %v", err) + } + + resp, err := client.Do(req) + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusMethodNotAllowed { + t.Errorf("expected status 405, got %d", resp.StatusCode) + } + }) + } +} + +func TestRoutes_HealthHEAD(t *testing.T) { + server := startTestServer(t) + defer server.Stop() + + client := &http.Client{} + req, err := http.NewRequest(http.MethodHead, "http://"+server.Addr()+"/health", nil) + if err != nil { + t.Fatalf("create request error: %v", err) + } + + resp, err := client.Do(req) + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusOK { + t.Errorf("expected status 200, got %d", resp.StatusCode) + } +} + +func TestRoutes_Status_WithBuildInfo(t *testing.T) { + server := startTestServer(t) + defer server.Stop() + + resp, err := http.Get("http://" + server.Addr() + "/api/v1/status") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + var status StatusResponse + if err := json.NewDecoder(resp.Body).Decode(&status); err != nil { + t.Fatalf("decode error: %v", err) + } + + // Should have Go version + if status.GoVersion == "" { + t.Error("expected go_version to be set") + } + if !strings.HasPrefix(status.GoVersion, "go") { + t.Errorf("expected go_version to start with 'go', got %q", status.GoVersion) + } + + // Uptime should be positive (since server was started) + if status.UptimeSeconds < 0 { + t.Errorf("expected positive uptime, got %d", status.UptimeSeconds) + } +} + +// mockStatusProvider implements StatusProvider for testing. +type mockStatusProvider struct { + mountPath string + devicePath string + mountState MountState + capacity *CapacityInfo +} + +func (m *mockStatusProvider) MountPath() string { return m.mountPath } +func (m *mockStatusProvider) DevicePath() string { return m.devicePath } +func (m *mockStatusProvider) MountState() MountState { return m.mountState } +func (m *mockStatusProvider) Capacity() *CapacityInfo { return m.capacity } + +func TestRoutes_Status_WithStatusProvider(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + // Set up mock status provider + server.SetStatusProvider(&mockStatusProvider{ + mountPath: "/mnt/test", + devicePath: "/dev/sda1", + mountState: MountStateMounted, + capacity: &CapacityInfo{ + TotalBytes: 1073741824, // 1GB + UsedBytes: 536870912, // 512MB + FreeBytes: 536870912, + UsedPercent: 50.0, + TotalBlocks: 1024, + UsedBlocks: 512, + FreeBlocks: 512, + }, + }) + + if err := server.Start(context.Background()); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + time.Sleep(10 * time.Millisecond) + + resp, err := http.Get("http://" + server.Addr() + "/api/v1/status") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + var status StatusResponse + if err := json.NewDecoder(resp.Body).Decode(&status); err != nil { + t.Fatalf("decode error: %v", err) + } + + if status.MountPath != "/mnt/test" { + t.Errorf("expected mount_path '/mnt/test', got %q", status.MountPath) + } + if status.DevicePath != "/dev/sda1" { + t.Errorf("expected device_path '/dev/sda1', got %q", status.DevicePath) + } + if status.MountState != MountStateMounted { + t.Errorf("expected mount_state 'mounted', got %q", status.MountState) + } + if status.Capacity == nil { + t.Fatal("expected capacity to be set") + } + if status.Capacity.UsedPercent != 50.0 { + t.Errorf("expected used_percent 50.0, got %f", status.Capacity.UsedPercent) + } +} diff --git a/internal/api/server.go b/internal/api/server.go new file mode 100644 index 00000000..c31d1cc8 --- /dev/null +++ b/internal/api/server.go @@ -0,0 +1,255 @@ +package api + +import ( + "context" + "fmt" + "log" + "net" + "net/http" + "sync" + "time" +) + +// Server is the HTTP API server for GoClusterFS. +type Server struct { + mu sync.RWMutex + config Config + + // HTTP server components + server *http.Server + router *http.ServeMux + listener net.Listener + + // Health checkers for component health reporting + healthCheckers []HealthChecker + + // Status provider for filesystem status (optional) + statusProvider StatusProvider + + // Stats provider for statistics collection (optional) + statsProvider StatsProvider + + // Lifecycle state + started bool + startTime time.Time + stopOnce sync.Once + stopErr error +} + +// NewServer creates a new API server with the given configuration. +// The server is not started until Start is called. +func NewServer(cfg Config) (*Server, error) { + if err := cfg.Validate(); err != nil { + return nil, fmt.Errorf("invalid config: %w", err) + } + + s := &Server{ + config: cfg, + router: http.NewServeMux(), + } + + // Register routes + s.registerRoutes() + + // Build middleware chain (order: logging -> CORS -> auth) + handler := Chain( + s.router, + LoggingMiddleware, + CORSMiddleware(cfg.CORSOrigins), + AuthMiddleware(cfg.AuthToken, "/health", "/metrics"), + ) + + // Create HTTP server + s.server = &http.Server{ + Handler: handler, + ReadTimeout: cfg.ReadTimeout, + WriteTimeout: cfg.WriteTimeout, + IdleTimeout: cfg.IdleTimeout, + } + + return s, nil +} + +// Start starts the API server and begins accepting connections. +// The server runs in a background goroutine and returns immediately. +// Use Stop to shut down the server gracefully. +func (s *Server) Start(ctx context.Context) error { + s.mu.Lock() + defer s.mu.Unlock() + + if s.started { + return ErrServerAlreadyStarted + } + + // Create listener + ln, err := net.Listen("tcp", s.config.ListenAddr) + if err != nil { + return fmt.Errorf("failed to listen on %s: %w", s.config.ListenAddr, err) + } + s.listener = ln + + // Mark as started + s.started = true + s.startTime = time.Now() + + // Start serving in background + go func() { + log.Printf("api: server listening on %s", ln.Addr()) + if err := s.server.Serve(ln); err != nil && err != http.ErrServerClosed { + log.Printf("api: server error: %v", err) + } + }() + + return nil +} + +// Stop gracefully shuts down the API server. +// It waits for active connections to complete up to the configured +// ShutdownTimeout before forcefully closing them. +func (s *Server) Stop() error { + s.stopOnce.Do(func() { + s.mu.Lock() + if !s.started { + s.mu.Unlock() + s.stopErr = ErrServerNotStarted + return + } + timeout := s.config.ShutdownTimeout + s.mu.Unlock() + + log.Printf("api: shutting down server...") + + // Create shutdown context with timeout + ctx, cancel := context.WithTimeout(context.Background(), timeout) + defer cancel() + + // Attempt graceful shutdown + if err := s.server.Shutdown(ctx); err != nil { + if ctx.Err() == context.DeadlineExceeded { + s.stopErr = ErrShutdownTimeout + } else { + s.stopErr = fmt.Errorf("shutdown error: %w", err) + } + return + } + + log.Printf("api: server stopped") + }) + + return s.stopErr +} + +// Addr returns the address the server is listening on. +// Returns an empty string if the server has not been started. +func (s *Server) Addr() string { + s.mu.RLock() + defer s.mu.RUnlock() + + if s.listener == nil { + return "" + } + return s.listener.Addr().String() +} + +// Started returns true if the server has been started. +func (s *Server) Started() bool { + s.mu.RLock() + defer s.mu.RUnlock() + return s.started +} + +// Uptime returns the duration since the server was started. +// Returns 0 if the server has not been started. +func (s *Server) Uptime() time.Duration { + s.mu.RLock() + defer s.mu.RUnlock() + + if !s.started { + return 0 + } + return time.Since(s.startTime) +} + +// RegisterHealthChecker adds a health checker to the server. +// Health checkers are called when the /health endpoint is accessed. +func (s *Server) RegisterHealthChecker(checker HealthChecker) { + s.mu.Lock() + defer s.mu.Unlock() + s.healthCheckers = append(s.healthCheckers, checker) +} + +// GetHealthCheckers returns a copy of the registered health checkers. +func (s *Server) GetHealthCheckers() []HealthChecker { + s.mu.RLock() + defer s.mu.RUnlock() + checkers := make([]HealthChecker, len(s.healthCheckers)) + copy(checkers, s.healthCheckers) + return checkers +} + +// StatusProvider provides filesystem status information. +type StatusProvider interface { + // MountPath returns the current mount path. + MountPath() string + + // DevicePath returns the underlying device path. + DevicePath() string + + // MountState returns the current mount state. + MountState() MountState + + // Capacity returns storage capacity information. + Capacity() *CapacityInfo +} + +// SetStatusProvider sets the status provider for filesystem status. +func (s *Server) SetStatusProvider(provider StatusProvider) { + s.mu.Lock() + defer s.mu.Unlock() + s.statusProvider = provider +} + +// GetStatusProvider returns the current status provider. +func (s *Server) GetStatusProvider() StatusProvider { + s.mu.RLock() + defer s.mu.RUnlock() + return s.statusProvider +} + +// StatsProvider provides statistics from the filesystem components. +type StatsProvider interface { + // CacheStats returns cache statistics, or nil if not available. + CacheStats() *CacheStatsResponse + + // JournalStats returns journal statistics, or nil if not available. + JournalStats() *JournalStatsResponse + + // TrimStats returns TRIM/discard statistics, or nil if not available. + TrimStats() *TrimStatsResponse + + // LockStats returns lock statistics, or nil if not available. + LockStats() *LockStatsResponse + + // SFBStats returns Sparse File Bitmap statistics, or nil if not available. + SFBStats() *SFBStatsResponse + + // ClusterInfo returns cluster information, or nil if not available. + ClusterInfo() *ClusterInfoResponse + + // AllStats returns a combined snapshot of all statistics. + AllStats() *AllStatsResponse +} + +// SetStatsProvider sets the stats provider for statistics collection. +func (s *Server) SetStatsProvider(provider StatsProvider) { + s.mu.Lock() + defer s.mu.Unlock() + s.statsProvider = provider +} + +// GetStatsProvider returns the current stats provider. +func (s *Server) GetStatsProvider() StatsProvider { + s.mu.RLock() + defer s.mu.RUnlock() + return s.statsProvider +} diff --git a/internal/api/server_test.go b/internal/api/server_test.go new file mode 100644 index 00000000..32e3e5ac --- /dev/null +++ b/internal/api/server_test.go @@ -0,0 +1,880 @@ +package api + +import ( + "context" + "encoding/json" + "errors" + "net/http" + "testing" + "time" +) + +func TestDefaultConfig(t *testing.T) { + cfg := DefaultConfig() + + if cfg.ListenAddr != "127.0.0.1:8080" { + t.Errorf("expected ListenAddr 127.0.0.1:8080, got %s", cfg.ListenAddr) + } + if cfg.AuthToken != "" { + t.Errorf("expected empty AuthToken, got %s", cfg.AuthToken) + } + if cfg.CORSOrigins != nil { + t.Errorf("expected nil CORSOrigins, got %v", cfg.CORSOrigins) + } + if cfg.ReadTimeout != 30*time.Second { + t.Errorf("expected ReadTimeout 30s, got %s", cfg.ReadTimeout) + } + if cfg.WriteTimeout != 30*time.Second { + t.Errorf("expected WriteTimeout 30s, got %s", cfg.WriteTimeout) + } + if cfg.IdleTimeout != 60*time.Second { + t.Errorf("expected IdleTimeout 60s, got %s", cfg.IdleTimeout) + } + if cfg.ShutdownTimeout != 10*time.Second { + t.Errorf("expected ShutdownTimeout 10s, got %s", cfg.ShutdownTimeout) + } +} + +func TestConfig_Validate_Valid(t *testing.T) { + tests := []struct { + name string + cfg Config + }{ + { + name: "default config", + cfg: DefaultConfig(), + }, + { + name: "with auth token", + cfg: DefaultConfig().WithAuthToken("secret"), + }, + { + name: "with CORS origins", + cfg: DefaultConfig().WithCORSOrigins("http://localhost:3000", "https://example.com"), + }, + { + name: "with wildcard CORS", + cfg: DefaultConfig().WithCORSOrigins("*"), + }, + { + name: "localhost address", + cfg: DefaultConfig().WithListenAddr("127.0.0.1:9090"), + }, + { + name: "dynamic port", + cfg: DefaultConfig().WithListenAddr(":0"), + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + if err := tt.cfg.Validate(); err != nil { + t.Errorf("expected valid config, got error: %v", err) + } + }) + } +} + +func TestConfig_Validate_Invalid(t *testing.T) { + tests := []struct { + name string + cfg Config + wantError error + }{ + { + name: "empty listen addr", + cfg: func() Config { + cfg := DefaultConfig() + cfg.ListenAddr = "" + return cfg + }(), + wantError: ErrInvalidListenAddr, + }, + { + name: "invalid listen addr format", + cfg: func() Config { + cfg := DefaultConfig() + cfg.ListenAddr = "not-a-valid-addr" + return cfg + }(), + wantError: ErrInvalidListenAddr, + }, + { + name: "negative read timeout", + cfg: func() Config { + cfg := DefaultConfig() + cfg.ReadTimeout = -1 * time.Second + return cfg + }(), + wantError: ErrInvalidTimeout, + }, + { + name: "negative write timeout", + cfg: func() Config { + cfg := DefaultConfig() + cfg.WriteTimeout = -1 * time.Second + return cfg + }(), + wantError: ErrInvalidTimeout, + }, + { + name: "empty CORS origin", + cfg: func() Config { + cfg := DefaultConfig() + cfg.CORSOrigins = []string{""} + return cfg + }(), + wantError: ErrInvalidCORSOrigin, + }, + { + name: "invalid CORS origin - no scheme", + cfg: func() Config { + cfg := DefaultConfig() + cfg.CORSOrigins = []string{"localhost:3000"} + return cfg + }(), + wantError: ErrInvalidCORSOrigin, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + err := tt.cfg.Validate() + if err == nil { + t.Errorf("expected error, got nil") + return + } + if !errors.Is(err, tt.wantError) { + t.Errorf("expected error %v, got %v", tt.wantError, err) + } + }) + } +} + +func TestNewServer_ValidConfig(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") // Use dynamic port + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("expected no error, got: %v", err) + } + if server == nil { + t.Fatal("expected server, got nil") + } +} + +func TestNewServer_InvalidConfig(t *testing.T) { + cfg := DefaultConfig() + cfg.ListenAddr = "" + + server, err := NewServer(cfg) + if err == nil { + t.Error("expected error for invalid config, got nil") + } + if server != nil { + t.Error("expected nil server for invalid config") + } +} + +func TestServer_StartStop(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + // Start server + ctx := context.Background() + if err := server.Start(ctx); err != nil { + t.Fatalf("Start error: %v", err) + } + + // Verify server is running + if !server.Started() { + t.Error("expected server to be started") + } + + addr := server.Addr() + if addr == "" { + t.Error("expected non-empty address") + } + + // Give it a moment to start listening + time.Sleep(10 * time.Millisecond) + + // Stop server + if err := server.Stop(); err != nil { + t.Errorf("Stop error: %v", err) + } +} + +func TestServer_HealthEndpoint(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + ctx := context.Background() + if err := server.Start(ctx); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + + // Give it a moment to start listening + time.Sleep(10 * time.Millisecond) + + // Make health check request + resp, err := http.Get("http://" + server.Addr() + "/health") + if err != nil { + t.Fatalf("health check request error: %v", err) + } + defer resp.Body.Close() + + // Check status code + if resp.StatusCode != http.StatusOK { + t.Errorf("expected status 200, got %d", resp.StatusCode) + } + + // Check response body + var health HealthResponse + if err := json.NewDecoder(resp.Body).Decode(&health); err != nil { + t.Fatalf("decode error: %v", err) + } + + if health.Status != "ok" { + t.Errorf("expected status 'ok', got %q", health.Status) + } +} + +func TestServer_DoubleStart(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + ctx := context.Background() + if err := server.Start(ctx); err != nil { + t.Fatalf("first Start error: %v", err) + } + defer server.Stop() + + // Second start should return error + if err := server.Start(ctx); !errors.Is(err, ErrServerAlreadyStarted) { + t.Errorf("expected ErrServerAlreadyStarted, got: %v", err) + } +} + +func TestServer_StopWithoutStart(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + // Stop without start should return error + if err := server.Stop(); !errors.Is(err, ErrServerNotStarted) { + t.Errorf("expected ErrServerNotStarted, got: %v", err) + } +} + +func TestServer_Uptime(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + // Uptime before start should be 0 + if uptime := server.Uptime(); uptime != 0 { + t.Errorf("expected 0 uptime before start, got %v", uptime) + } + + ctx := context.Background() + if err := server.Start(ctx); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + + // Wait a bit + time.Sleep(50 * time.Millisecond) + + // Uptime should be > 0 + if uptime := server.Uptime(); uptime <= 0 { + t.Errorf("expected positive uptime after start, got %v", uptime) + } +} + +func TestServer_AddrBeforeStart(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + // Addr before start should be empty + if addr := server.Addr(); addr != "" { + t.Errorf("expected empty addr before start, got %q", addr) + } +} + +// mockStatsProvider implements StatsProvider for testing. +type mockStatsProvider struct { + cache *CacheStatsResponse + journal *JournalStatsResponse + trim *TrimStatsResponse + lock *LockStatsResponse + sfb *SFBStatsResponse + cluster *ClusterInfoResponse + all *AllStatsResponse +} + +func (m *mockStatsProvider) CacheStats() *CacheStatsResponse { return m.cache } +func (m *mockStatsProvider) JournalStats() *JournalStatsResponse { return m.journal } +func (m *mockStatsProvider) TrimStats() *TrimStatsResponse { return m.trim } +func (m *mockStatsProvider) LockStats() *LockStatsResponse { return m.lock } +func (m *mockStatsProvider) SFBStats() *SFBStatsResponse { return m.sfb } +func (m *mockStatsProvider) ClusterInfo() *ClusterInfoResponse { return m.cluster } +func (m *mockStatsProvider) AllStats() *AllStatsResponse { return m.all } + +func TestServer_StatsEndpoints_NoProvider(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + ctx := context.Background() + if err := server.Start(ctx); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + + time.Sleep(10 * time.Millisecond) + + endpoints := []string{ + "/api/v1/stats", + "/api/v1/stats/cache", + "/api/v1/stats/journal", + "/api/v1/stats/trim", + "/api/v1/stats/lock", + "/api/v1/stats/sfb", + "/api/v1/stats/cluster", + "/api/v1/stats/all", + } + + for _, endpoint := range endpoints { + t.Run(endpoint, func(t *testing.T) { + resp, err := http.Get("http://" + server.Addr() + endpoint) + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + // Should return 503 when no provider is configured + if resp.StatusCode != http.StatusServiceUnavailable { + t.Errorf("expected status 503, got %d", resp.StatusCode) + } + }) + } +} + +func TestServer_StatsCache_Success(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + // Set up mock provider with cache stats + mockProvider := &mockStatsProvider{ + cache: &CacheStatsResponse{ + InodeCache: CacheHitRateInfo{ + Size: 1000, + Hits: 800, + Misses: 200, + HitRate: 0.8, + }, + ExtentCache: CacheHitRateInfo{ + Size: 500, + Hits: 400, + Misses: 100, + HitRate: 0.8, + }, + NegativeCache: CacheHitRateInfo{ + Size: 100, + Hits: 50, + Misses: 50, + HitRate: 0.5, + }, + }, + } + server.SetStatsProvider(mockProvider) + + ctx := context.Background() + if err := server.Start(ctx); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + + time.Sleep(10 * time.Millisecond) + + resp, err := http.Get("http://" + server.Addr() + "/api/v1/stats/cache") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusOK { + t.Fatalf("expected status 200, got %d", resp.StatusCode) + } + + var stats CacheStatsResponse + if err := json.NewDecoder(resp.Body).Decode(&stats); err != nil { + t.Fatalf("decode error: %v", err) + } + + if stats.InodeCache.Size != 1000 { + t.Errorf("expected inode cache size 1000, got %d", stats.InodeCache.Size) + } + if stats.InodeCache.HitRate != 0.8 { + t.Errorf("expected inode hit rate 0.8, got %f", stats.InodeCache.HitRate) + } +} + +func TestServer_StatsCache_NotAvailable(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + // Provider with nil cache stats + mockProvider := &mockStatsProvider{} + server.SetStatsProvider(mockProvider) + + ctx := context.Background() + if err := server.Start(ctx); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + + time.Sleep(10 * time.Millisecond) + + resp, err := http.Get("http://" + server.Addr() + "/api/v1/stats/cache") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + // Should return 404 when cache stats are nil + if resp.StatusCode != http.StatusNotFound { + t.Errorf("expected status 404, got %d", resp.StatusCode) + } +} + +func TestServer_StatsJournal_Success(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + mockProvider := &mockStatsProvider{ + journal: &JournalStatsResponse{ + State: "clean", + HeadOffset: 1024, + TailOffset: 512, + AvailableSpace: 4096, + ActiveTxnCount: 5, + CommitCount: 100, + BytesWritten: 1024 * 1024, + LastCheckpointSeq: 50, + }, + } + server.SetStatsProvider(mockProvider) + + ctx := context.Background() + if err := server.Start(ctx); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + + time.Sleep(10 * time.Millisecond) + + resp, err := http.Get("http://" + server.Addr() + "/api/v1/stats/journal") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusOK { + t.Fatalf("expected status 200, got %d", resp.StatusCode) + } + + var stats JournalStatsResponse + if err := json.NewDecoder(resp.Body).Decode(&stats); err != nil { + t.Fatalf("decode error: %v", err) + } + + if stats.State != "clean" { + t.Errorf("expected state 'clean', got %q", stats.State) + } + if stats.CommitCount != 100 { + t.Errorf("expected commit count 100, got %d", stats.CommitCount) + } +} + +func TestServer_StatsTrim_Success(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + mockProvider := &mockStatsProvider{ + trim: &TrimStatsResponse{ + TrimOperations: 50, + TrimBytes: 1024 * 1024 * 10, + TrimBlocks: 2560, + TrimEnabled: true, + BatchSize: 64, + }, + } + server.SetStatsProvider(mockProvider) + + ctx := context.Background() + if err := server.Start(ctx); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + + time.Sleep(10 * time.Millisecond) + + resp, err := http.Get("http://" + server.Addr() + "/api/v1/stats/trim") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusOK { + t.Fatalf("expected status 200, got %d", resp.StatusCode) + } + + var stats TrimStatsResponse + if err := json.NewDecoder(resp.Body).Decode(&stats); err != nil { + t.Fatalf("decode error: %v", err) + } + + if stats.TrimOperations != 50 { + t.Errorf("expected 50 trim operations, got %d", stats.TrimOperations) + } + if !stats.TrimEnabled { + t.Error("expected trim enabled") + } +} + +func TestServer_StatsLock_Success(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + mockProvider := &mockStatsProvider{ + lock: &LockStatsResponse{ + HintCacheHits: 900, + HintCacheMisses: 100, + HintCacheHitRate: 0.9, + ActiveLocks: 5, + PendingLocks: 2, + }, + } + server.SetStatsProvider(mockProvider) + + ctx := context.Background() + if err := server.Start(ctx); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + + time.Sleep(10 * time.Millisecond) + + resp, err := http.Get("http://" + server.Addr() + "/api/v1/stats/lock") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusOK { + t.Fatalf("expected status 200, got %d", resp.StatusCode) + } + + var stats LockStatsResponse + if err := json.NewDecoder(resp.Body).Decode(&stats); err != nil { + t.Fatalf("decode error: %v", err) + } + + if stats.HintCacheHitRate != 0.9 { + t.Errorf("expected hit rate 0.9, got %f", stats.HintCacheHitRate) + } +} + +func TestServer_StatsSFB_Success(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + mockProvider := &mockStatsProvider{ + sfb: &SFBStatsResponse{ + TotalBlocks: 10000, + AllocatedBlocks: 7500, + FreeBlocks: 2500, + AllocationPercent: 75.0, + AllocationsTotal: 5000, + DeallocationsTotal: 2500, + }, + } + server.SetStatsProvider(mockProvider) + + ctx := context.Background() + if err := server.Start(ctx); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + + time.Sleep(10 * time.Millisecond) + + resp, err := http.Get("http://" + server.Addr() + "/api/v1/stats/sfb") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusOK { + t.Fatalf("expected status 200, got %d", resp.StatusCode) + } + + var stats SFBStatsResponse + if err := json.NewDecoder(resp.Body).Decode(&stats); err != nil { + t.Fatalf("decode error: %v", err) + } + + if stats.AllocationPercent != 75.0 { + t.Errorf("expected allocation 75%%, got %f%%", stats.AllocationPercent) + } +} + +func TestServer_StatsCluster_Success(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + mockProvider := &mockStatsProvider{ + cluster: &ClusterInfoResponse{ + NodeID: "node-1", + Role: "primary", + State: "active", + ClusterSize: 3, + HealthyNodes: 3, + LeaderID: "node-1", + Peers: []ClusterPeerInfo{ + {NodeID: "node-2", Address: "192.168.1.2:7946", State: "active"}, + {NodeID: "node-3", Address: "192.168.1.3:7946", State: "active"}, + }, + }, + } + server.SetStatsProvider(mockProvider) + + ctx := context.Background() + if err := server.Start(ctx); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + + time.Sleep(10 * time.Millisecond) + + resp, err := http.Get("http://" + server.Addr() + "/api/v1/stats/cluster") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusOK { + t.Fatalf("expected status 200, got %d", resp.StatusCode) + } + + var stats ClusterInfoResponse + if err := json.NewDecoder(resp.Body).Decode(&stats); err != nil { + t.Fatalf("decode error: %v", err) + } + + if stats.NodeID != "node-1" { + t.Errorf("expected node-1, got %q", stats.NodeID) + } + if len(stats.Peers) != 2 { + t.Errorf("expected 2 peers, got %d", len(stats.Peers)) + } +} + +func TestServer_StatsAll_Success(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + mockProvider := &mockStatsProvider{ + all: &AllStatsResponse{ + CollectedAt: "2025-01-01T00:00:00Z", + Cache: &CacheStatsResponse{ + InodeCache: CacheHitRateInfo{Size: 100}, + }, + Journal: &JournalStatsResponse{ + State: "clean", + }, + }, + } + server.SetStatsProvider(mockProvider) + + ctx := context.Background() + if err := server.Start(ctx); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + + time.Sleep(10 * time.Millisecond) + + resp, err := http.Get("http://" + server.Addr() + "/api/v1/stats/all") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusOK { + t.Fatalf("expected status 200, got %d", resp.StatusCode) + } + + var stats AllStatsResponse + if err := json.NewDecoder(resp.Body).Decode(&stats); err != nil { + t.Fatalf("decode error: %v", err) + } + + if stats.CollectedAt != "2025-01-01T00:00:00Z" { + t.Errorf("expected collected_at, got %q", stats.CollectedAt) + } + if stats.Cache == nil { + t.Error("expected cache stats") + } + if stats.Journal == nil { + t.Error("expected journal stats") + } +} + +func TestServer_StatsOverview_Success(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + mockProvider := &mockStatsProvider{ + cache: &CacheStatsResponse{ + InodeCache: CacheHitRateInfo{Size: 100}, + }, + journal: &JournalStatsResponse{ + State: "clean", + }, + } + server.SetStatsProvider(mockProvider) + + ctx := context.Background() + if err := server.Start(ctx); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + + time.Sleep(10 * time.Millisecond) + + resp, err := http.Get("http://" + server.Addr() + "/api/v1/stats") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusOK { + t.Fatalf("expected status 200, got %d", resp.StatusCode) + } + + var stats StatsOverviewResponse + if err := json.NewDecoder(resp.Body).Decode(&stats); err != nil { + t.Fatalf("decode error: %v", err) + } + + if stats.Cache == nil { + t.Error("expected cache stats in overview") + } + if stats.Journal == nil { + t.Error("expected journal stats in overview") + } +} + +func TestServer_StatsUnknownEndpoint(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + mockProvider := &mockStatsProvider{} + server.SetStatsProvider(mockProvider) + + ctx := context.Background() + if err := server.Start(ctx); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + + time.Sleep(10 * time.Millisecond) + + resp, err := http.Get("http://" + server.Addr() + "/api/v1/stats/unknown") + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusNotFound { + t.Errorf("expected status 404, got %d", resp.StatusCode) + } +} + +func TestServer_StatsMethodNotAllowed(t *testing.T) { + cfg := DefaultConfig().WithListenAddr(":0") + server, err := NewServer(cfg) + if err != nil { + t.Fatalf("NewServer error: %v", err) + } + + ctx := context.Background() + if err := server.Start(ctx); err != nil { + t.Fatalf("Start error: %v", err) + } + defer server.Stop() + + time.Sleep(10 * time.Millisecond) + + // POST should not be allowed + resp, err := http.Post("http://"+server.Addr()+"/api/v1/stats/cache", "application/json", nil) + if err != nil { + t.Fatalf("request error: %v", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusMethodNotAllowed { + t.Errorf("expected status 405, got %d", resp.StatusCode) + } +} diff --git a/internal/api/types.go b/internal/api/types.go new file mode 100644 index 00000000..06e9cab2 --- /dev/null +++ b/internal/api/types.go @@ -0,0 +1,228 @@ +package api + +import ( + "encoding/json" + "net/http" +) + +// 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. +// Provides overall system health and individual component checks. +type HealthResponse struct { + Status HealthStatus `json:"status"` + Checks map[string]ComponentHealth `json:"checks,omitempty"` +} + +// ErrorResponse is returned for API errors. +type ErrorResponse struct { + Error string `json:"error"` + Code int `json:"code"` + Details string `json:"details,omitempty"` +} + +// 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"` +} + +// 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" +) + +// StatusResponse is returned by GET /api/v1/status. +// Provides comprehensive system status information. +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. +// Matches internal/cache.Stats structure. +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. +// Matches internal/journal.JournalStats structure. +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"` +} + +// 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"` +} + +// MetricsStatsResponse is returned by GET /api/v1/stats/metrics. +type MetricsStatsResponse struct { + IO *IOStatsResponse `json:"io,omitempty"` + StartTime int64 `json:"start_time_unix"` + Uptime int64 `json:"uptime_seconds"` +} + +// TrimStatsResponse is returned by GET /api/v1/stats/trim. +type TrimStatsResponse struct { + TrimOperations uint64 `json:"trim_operations"` + TrimBytes uint64 `json:"trim_bytes"` + TrimBlocks uint64 `json:"trim_blocks"` + PendingTrimBlocks uint64 `json:"pending_trim_blocks,omitempty"` + LastTrimAt string `json:"last_trim_at,omitempty"` + TrimErrors uint64 `json:"trim_errors,omitempty"` + TrimEnabled bool `json:"trim_enabled"` + BatchSize int `json:"batch_size,omitempty"` +} + +// LockStatsResponse is returned by GET /api/v1/stats/lock. +type LockStatsResponse struct { + HintCacheHits uint64 `json:"hint_cache_hits"` + HintCacheMisses uint64 `json:"hint_cache_misses"` + HintCacheHitRate float64 `json:"hint_cache_hit_rate"` + ActiveLocks int `json:"active_locks,omitempty"` + PendingLocks int `json:"pending_locks,omitempty"` +} + +// SFBStatsResponse is returned by GET /api/v1/stats/sfb. +type SFBStatsResponse struct { + TotalBlocks uint64 `json:"total_blocks"` + AllocatedBlocks uint64 `json:"allocated_blocks"` + FreeBlocks uint64 `json:"free_blocks"` + AllocationPercent float64 `json:"allocation_percent"` + FragmentationRatio float64 `json:"fragmentation_ratio,omitempty"` + LargestFreeExtent uint64 `json:"largest_free_extent,omitempty"` + AllocationsTotal uint64 `json:"allocations_total"` + DeallocationsTotal uint64 `json:"deallocations_total"` + AllocationFailures uint64 `json:"allocation_failures,omitempty"` +} + +// ClusterPeerInfo contains information about a cluster peer node. +type ClusterPeerInfo struct { + NodeID string `json:"node_id"` + Address string `json:"address"` + State string `json:"state"` + LastSeen string `json:"last_seen,omitempty"` + Latency float64 `json:"latency_ms,omitempty"` +} + +// ClusterInfoResponse is returned by GET /api/v1/stats/cluster. +type ClusterInfoResponse struct { + NodeID string `json:"node_id"` + NodeAddress string `json:"node_address,omitempty"` + Role string `json:"role"` + State string `json:"state"` + ClusterSize int `json:"cluster_size"` + HealthyNodes int `json:"healthy_nodes"` + LeaderID string `json:"leader_id,omitempty"` + LastHeartbeatAt string `json:"last_heartbeat_at,omitempty"` + JoinedAt string `json:"joined_at,omitempty"` + Peers []ClusterPeerInfo `json:"peers,omitempty"` +} + +// AllStatsResponse is returned by GET /api/v1/stats/all. +// Provides a combined snapshot of all statistics. +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. +// Provides a summary of all component stats. +type StatsOverviewResponse struct { + Cache *CacheStatsResponse `json:"cache,omitempty"` + Journal *JournalStatsResponse `json:"journal,omitempty"` + IO *IOStatsResponse `json:"io,omitempty"` +} + +// writeJSON writes a JSON response with the given status code. +func writeJSON(w http.ResponseWriter, status int, v interface{}) { + w.Header().Set("Content-Type", "application/json; charset=utf-8") + w.WriteHeader(status) + if v != nil { + json.NewEncoder(w).Encode(v) + } +} + +// writeError writes an error response with the given status code. +func writeError(w http.ResponseWriter, status int, err string, details string) { + writeJSON(w, status, ErrorResponse{ + Error: err, + Code: status, + Details: details, + }) +} diff --git a/internal/api/types_test.go b/internal/api/types_test.go new file mode 100644 index 00000000..6a265d98 --- /dev/null +++ b/internal/api/types_test.go @@ -0,0 +1,205 @@ +package api + +import ( + "encoding/json" + "testing" +) + +func TestHealthResponse_JSONMarshaling(t *testing.T) { + tests := []struct { + name string + resp HealthResponse + wantJSON string + }{ + { + name: "simple ok", + resp: HealthResponse{ + Status: HealthStatusOK, + }, + wantJSON: `{"status":"ok"}`, + }, + { + name: "with checks", + resp: HealthResponse{ + Status: HealthStatusDegraded, + Checks: map[string]ComponentHealth{ + "cache": {Status: HealthStatusOK}, + "journal": {Status: HealthStatusDegraded, Message: "low disk space"}, + }, + }, + wantJSON: "", // Complex; just verify round-trip + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + data, err := json.Marshal(tt.resp) + if err != nil { + t.Fatalf("Marshal error: %v", err) + } + + if tt.wantJSON != "" { + if string(data) != tt.wantJSON { + t.Errorf("got %s, want %s", string(data), tt.wantJSON) + } + } + + // Verify round-trip + var got HealthResponse + if err := json.Unmarshal(data, &got); err != nil { + t.Fatalf("Unmarshal error: %v", err) + } + if got.Status != tt.resp.Status { + t.Errorf("Status: got %s, want %s", got.Status, tt.resp.Status) + } + }) + } +} + +func TestStatusResponse_JSONMarshaling(t *testing.T) { + resp := StatusResponse{ + Status: "ok", + Version: "1.0.0", + UptimeSeconds: 3600, + MountPath: "/mnt/test", + Capacity: &CapacityInfo{ + TotalBytes: 1073741824, // 1GB + UsedBytes: 536870912, // 512MB + FreeBytes: 536870912, + UsedPercent: 50.0, + }, + } + + data, err := json.Marshal(resp) + if err != nil { + t.Fatalf("Marshal error: %v", err) + } + + var got StatusResponse + if err := json.Unmarshal(data, &got); err != nil { + t.Fatalf("Unmarshal error: %v", err) + } + + if got.Status != resp.Status { + t.Errorf("Status: got %s, want %s", got.Status, resp.Status) + } + if got.UptimeSeconds != resp.UptimeSeconds { + t.Errorf("UptimeSeconds: got %d, want %d", got.UptimeSeconds, resp.UptimeSeconds) + } + if got.Capacity == nil { + t.Error("Capacity should not be nil") + } else if got.Capacity.UsedPercent != resp.Capacity.UsedPercent { + t.Errorf("UsedPercent: got %f, want %f", got.Capacity.UsedPercent, resp.Capacity.UsedPercent) + } +} + +func TestCacheStatsResponse_JSONMarshaling(t *testing.T) { + resp := CacheStatsResponse{ + InodeCache: CacheHitRateInfo{ + Size: 1000, + Hits: 9500, + Misses: 500, + HitRate: 0.95, + }, + ExtentCache: CacheHitRateInfo{ + Size: 500, + Hits: 4800, + Misses: 200, + HitRate: 0.96, + }, + } + + data, err := json.Marshal(resp) + if err != nil { + t.Fatalf("Marshal error: %v", err) + } + + var got CacheStatsResponse + if err := json.Unmarshal(data, &got); err != nil { + t.Fatalf("Unmarshal error: %v", err) + } + + if got.InodeCache.HitRate != resp.InodeCache.HitRate { + t.Errorf("InodeCache.HitRate: got %f, want %f", got.InodeCache.HitRate, resp.InodeCache.HitRate) + } +} + +func TestJournalStatsResponse_JSONMarshaling(t *testing.T) { + resp := JournalStatsResponse{ + State: "active", + HeadOffset: 1024, + TailOffset: 512, + AvailableSpace: 65536, + CommitCount: 12345, + BytesWritten: 1048576, + } + + data, err := json.Marshal(resp) + if err != nil { + t.Fatalf("Marshal error: %v", err) + } + + var got JournalStatsResponse + if err := json.Unmarshal(data, &got); err != nil { + t.Fatalf("Unmarshal error: %v", err) + } + + if got.CommitCount != resp.CommitCount { + t.Errorf("CommitCount: got %d, want %d", got.CommitCount, resp.CommitCount) + } +} + +func TestErrorResponse_JSONMarshaling(t *testing.T) { + resp := ErrorResponse{ + Error: "not found", + Code: 404, + Details: "resource does not exist", + } + + data, err := json.Marshal(resp) + if err != nil { + t.Fatalf("Marshal error: %v", err) + } + + expected := `{"error":"not found","code":404,"details":"resource does not exist"}` + if string(data) != expected { + t.Errorf("got %s, want %s", string(data), expected) + } +} + +func TestOmitEmpty(t *testing.T) { + // Verify omitempty works correctly + resp := StatusResponse{ + Status: "ok", + Version: "dev", + UptimeSeconds: 0, + // MountPath intentionally empty + } + + data, err := json.Marshal(resp) + if err != nil { + t.Fatalf("Marshal error: %v", err) + } + + // Should not contain mount_path since it's empty and has omitempty + str := string(data) + if contains(str, "mount_path") { + t.Errorf("empty mount_path should be omitted: %s", str) + } + if contains(str, "capacity") { + t.Errorf("nil capacity should be omitted: %s", str) + } +} + +func contains(s, substr string) bool { + return len(s) >= len(substr) && (s == substr || len(s) > 0 && containsAt(s, substr)) +} + +func containsAt(s, substr string) bool { + for i := 0; i <= len(s)-len(substr); i++ { + if s[i:i+len(substr)] == substr { + return true + } + } + return false +} diff --git a/internal/api/version.go b/internal/api/version.go new file mode 100644 index 00000000..df0c0ac8 --- /dev/null +++ b/internal/api/version.go @@ -0,0 +1,25 @@ +package api + +import ( + "runtime" + + "github.com/supporttools/GoClusterFS/internal/version" +) + +// BuildInfo contains build version information. +type BuildInfo struct { + Version string `json:"version"` + GitCommit string `json:"git_commit,omitempty"` + BuildTime string `json:"build_time,omitempty"` + GoVersion string `json:"go_version"` +} + +// GetBuildInfo returns the build metadata from internal/version. +func GetBuildInfo() BuildInfo { + return BuildInfo{ + Version: version.Version, + GitCommit: version.Commit, + BuildTime: version.Date, + GoVersion: runtime.Version(), + } +} diff --git a/internal/api/version_test.go b/internal/api/version_test.go new file mode 100644 index 00000000..142b4168 --- /dev/null +++ b/internal/api/version_test.go @@ -0,0 +1,17 @@ +package api + +import ( + "testing" + + "github.com/supporttools/GoClusterFS/internal/version" +) + +func TestBuildInfoUsesVersionPackage(t *testing.T) { + saved := version.Version + t.Cleanup(func() { version.Version = saved }) + version.Version = "1.2.3" + + if got := GetBuildInfo().Version; got != "1.2.3" { + t.Fatalf("GetBuildInfo().Version = %q, want internal/version's 1.2.3", got) + } +} diff --git a/internal/goclusterfs/fs.go b/internal/goclusterfs/fs.go index 2ef2478a..01c23e29 100644 --- a/internal/goclusterfs/fs.go +++ b/internal/goclusterfs/fs.go @@ -435,6 +435,15 @@ func (f *FS) RootDir() *Dir { } } +// SnapshotRegistry returns the snapshot registry for API endpoints. +// Returns nil if snapshots are not enabled. +// Thread-safe: the returned Registry has its own internal mutex. +func (f *FS) SnapshotRegistry() *snapshot.Registry { + f.mu.RLock() + defer f.mu.RUnlock() + return f.snapshotReg +} + // hashString returns a 64-bit FNV-1a hash of the string. // Used for journal verification of filenames. func hashString(s string) uint64 { diff --git a/internal/stats/cache.go b/internal/stats/cache.go new file mode 100644 index 00000000..10f25979 --- /dev/null +++ b/internal/stats/cache.go @@ -0,0 +1,91 @@ +package stats + +import "time" + +// CacheInfo contains metadata about the statistics cache state. +type CacheInfo struct { + // Valid indicates if the cache contains valid data. + Valid bool `json:"valid"` + + // Age is how long since the cached data was collected. + Age time.Duration `json:"age"` + + // TTL is the configured cache time-to-live. + TTL time.Duration `json:"ttl"` + + // Stale indicates if the cache is past its TTL (needs refresh). + Stale bool `json:"stale"` + + // LastCollected is when the cached snapshot was collected. + LastCollected time.Time `json:"last_collected,omitempty"` +} + +// CacheInfo returns information about the current cache state. +func (c *Collector) CacheInfo() CacheInfo { + c.mu.RLock() + defer c.mu.RUnlock() + + info := CacheInfo{ + Valid: c.cacheValid, + TTL: c.config.CacheTTL, + } + + if c.cacheValid { + info.Age = time.Since(c.cacheTime) + info.LastCollected = c.cacheTime + info.Stale = info.Age >= c.config.CacheTTL + } + + return info +} + +// IsCacheValid returns true if the cache contains valid, non-stale data. +func (c *Collector) IsCacheValid() bool { + c.mu.RLock() + defer c.mu.RUnlock() + + return c.cacheValid && time.Since(c.cacheTime) < c.config.CacheTTL +} + +// CacheAge returns how long since the cache was last refreshed. +// Returns 0 if the cache is not valid. +func (c *Collector) CacheAge() time.Duration { + c.mu.RLock() + defer c.mu.RUnlock() + + if !c.cacheValid { + return 0 + } + return time.Since(c.cacheTime) +} + +// CachedSnapshot wraps a Snapshot with cache metadata. +// This is useful for API responses that need to indicate cache freshness. +type CachedSnapshot struct { + // Snapshot contains the actual statistics. + *Snapshot + + // FromCache indicates if this snapshot was served from cache. + FromCache bool `json:"from_cache"` + + // CacheAge is how old the cached data is. + CacheAge time.Duration `json:"cache_age,omitempty"` +} + +// CollectWithMeta returns a snapshot along with cache metadata. +func (c *Collector) CollectWithMeta() CachedSnapshot { + c.mu.RLock() + wasValid := c.cacheValid && time.Since(c.cacheTime) < c.config.CacheTTL + c.mu.RUnlock() + + snapshot := c.Collect() + + c.mu.RLock() + defer c.mu.RUnlock() + + return CachedSnapshot{ + Snapshot: snapshot, + FromCache: wasValid, + CacheAge: time.Since(c.cacheTime), + } +} diff --git a/internal/stats/collector.go b/internal/stats/collector.go new file mode 100644 index 00000000..f84984a6 --- /dev/null +++ b/internal/stats/collector.go @@ -0,0 +1,292 @@ +package stats + +import ( + "sync" + "time" +) + +// Collector aggregates statistics from multiple components. +// It caches collected statistics for a configurable TTL to avoid +// expensive repeated queries. +type Collector struct { + mu sync.RWMutex + config Config + + // Providers + cacheProvider CacheStatsProvider + journalProvider JournalStatsProvider + filesystemProvider FilesystemStatsProvider + lockProvider LockStatsProvider + trimProvider TrimStatsProvider + sfbProvider SFBStatsProvider + clusterProvider ClusterInfoProvider + + // Cached snapshot + cache *Snapshot + cacheTime time.Time + cacheValid bool +} + +// NewCollector creates a new statistics collector with the given configuration. +func NewCollector(cfg Config) *Collector { + return &Collector{ + config: cfg, + } +} + +// SetCacheProvider sets the cache statistics provider. +func (c *Collector) SetCacheProvider(provider CacheStatsProvider) { + c.mu.Lock() + defer c.mu.Unlock() + c.cacheProvider = provider + c.invalidateCache() +} + +// SetJournalProvider sets the journal statistics provider. +func (c *Collector) SetJournalProvider(provider JournalStatsProvider) { + c.mu.Lock() + defer c.mu.Unlock() + c.journalProvider = provider + c.invalidateCache() +} + +// SetFilesystemProvider sets the filesystem statistics provider. +func (c *Collector) SetFilesystemProvider(provider FilesystemStatsProvider) { + c.mu.Lock() + defer c.mu.Unlock() + c.filesystemProvider = provider + c.invalidateCache() +} + +// SetLockProvider sets the lock statistics provider. +func (c *Collector) SetLockProvider(provider LockStatsProvider) { + c.mu.Lock() + defer c.mu.Unlock() + c.lockProvider = provider + c.invalidateCache() +} + +// SetTrimProvider sets the TRIM statistics provider. +func (c *Collector) SetTrimProvider(provider TrimStatsProvider) { + c.mu.Lock() + defer c.mu.Unlock() + c.trimProvider = provider + c.invalidateCache() +} + +// SetSFBProvider sets the Sparse File Bitmap statistics provider. +func (c *Collector) SetSFBProvider(provider SFBStatsProvider) { + c.mu.Lock() + defer c.mu.Unlock() + c.sfbProvider = provider + c.invalidateCache() +} + +// SetClusterProvider sets the cluster information provider. +func (c *Collector) SetClusterProvider(provider ClusterInfoProvider) { + c.mu.Lock() + defer c.mu.Unlock() + c.clusterProvider = provider + c.invalidateCache() +} + +// Collect returns a snapshot of all current statistics. +// The snapshot may be cached if within the TTL period. +func (c *Collector) Collect() *Snapshot { + c.mu.RLock() + if c.cacheValid && time.Since(c.cacheTime) < c.config.CacheTTL { + snapshot := c.cache + c.mu.RUnlock() + return snapshot + } + c.mu.RUnlock() + + // Need to collect fresh stats + c.mu.Lock() + defer c.mu.Unlock() + + // Double-check after acquiring write lock + if c.cacheValid && time.Since(c.cacheTime) < c.config.CacheTTL { + return c.cache + } + + // Collect fresh statistics + snapshot := c.collectLocked() + c.cache = snapshot + c.cacheTime = time.Now() + c.cacheValid = true + + return snapshot +} + +// CollectFresh forces collection of fresh statistics, bypassing the cache. +func (c *Collector) CollectFresh() *Snapshot { + c.mu.Lock() + defer c.mu.Unlock() + + snapshot := c.collectLocked() + c.cache = snapshot + c.cacheTime = time.Now() + c.cacheValid = true + + return snapshot +} + +// InvalidateCache forces the next Collect call to fetch fresh data. +func (c *Collector) InvalidateCache() { + c.mu.Lock() + defer c.mu.Unlock() + c.invalidateCache() +} + +// invalidateCache marks the cache as invalid (caller must hold mu). +func (c *Collector) invalidateCache() { + c.cacheValid = false +} + +// collectLocked performs the actual statistics collection. +// Caller must hold c.mu. +func (c *Collector) collectLocked() *Snapshot { + snapshot := &Snapshot{ + CollectedAt: time.Now(), + } + + // Collect from each provider if available + if c.config.EnableComponentStats { + if c.cacheProvider != nil { + snapshot.Cache = c.cacheProvider.CacheStats() + } + + if c.journalProvider != nil { + snapshot.Journal = c.journalProvider.JournalStats() + } + + if c.filesystemProvider != nil { + snapshot.Filesystem = c.filesystemProvider.FilesystemStats() + } + + if c.lockProvider != nil { + snapshot.Lock = c.lockProvider.LockStats() + } + + if c.trimProvider != nil { + snapshot.Trim = c.trimProvider.TrimStats() + } + + if c.sfbProvider != nil { + snapshot.SFB = c.sfbProvider.SFBStats() + } + + if c.clusterProvider != nil { + snapshot.Cluster = c.clusterProvider.ClusterInfo() + } + } + + return snapshot +} + +// CacheStats returns just the cache statistics. +// Returns nil if no cache provider is set. +func (c *Collector) CacheStats() *CacheStats { + c.mu.RLock() + provider := c.cacheProvider + c.mu.RUnlock() + + if provider == nil { + return nil + } + return provider.CacheStats() +} + +// JournalStats returns just the journal statistics. +// Returns nil if no journal provider is set. +func (c *Collector) JournalStats() *JournalStats { + c.mu.RLock() + provider := c.journalProvider + c.mu.RUnlock() + + if provider == nil { + return nil + } + return provider.JournalStats() +} + +// FilesystemStats returns just the filesystem statistics. +// Returns nil if no filesystem provider is set. +func (c *Collector) FilesystemStats() *FilesystemStats { + c.mu.RLock() + provider := c.filesystemProvider + c.mu.RUnlock() + + if provider == nil { + return nil + } + return provider.FilesystemStats() +} + +// LockStats returns just the lock statistics. +// Returns nil if no lock provider is set. +func (c *Collector) LockStats() *LockStats { + c.mu.RLock() + provider := c.lockProvider + c.mu.RUnlock() + + if provider == nil { + return nil + } + return provider.LockStats() +} + +// TrimStats returns just the TRIM statistics. +// Returns nil if no trim provider is set. +func (c *Collector) TrimStats() *TrimStats { + c.mu.RLock() + provider := c.trimProvider + c.mu.RUnlock() + + if provider == nil { + return nil + } + return provider.TrimStats() +} + +// SFBStats returns just the Sparse File Bitmap statistics. +// Returns nil if no SFB provider is set. +func (c *Collector) SFBStats() *SFBStats { + c.mu.RLock() + provider := c.sfbProvider + c.mu.RUnlock() + + if provider == nil { + return nil + } + return provider.SFBStats() +} + +// ClusterInfo returns just the cluster information. +// Returns nil if no cluster provider is set. +func (c *Collector) ClusterInfo() *ClusterInfo { + c.mu.RLock() + provider := c.clusterProvider + c.mu.RUnlock() + + if provider == nil { + return nil + } + return provider.ClusterInfo() +} + +// Config returns the collector's configuration. +func (c *Collector) Config() Config { + c.mu.RLock() + defer c.mu.RUnlock() + return c.config +} + +// SetConfig updates the collector's configuration. +func (c *Collector) SetConfig(cfg Config) { + c.mu.Lock() + defer c.mu.Unlock() + c.config = cfg + c.invalidateCache() +} diff --git a/internal/stats/doc.go b/internal/stats/doc.go new file mode 100644 index 00000000..cea2e452 --- /dev/null +++ b/internal/stats/doc.go @@ -0,0 +1,48 @@ +// Package stats provides unified statistics collection and aggregation for GoClusterFS. +// +// The stats package serves as an aggregation layer that collects statistics from +// multiple internal components (cache, journal, filesystem, etc.) and presents +// them through a unified interface for API endpoints and monitoring. +// +// # Architecture +// +// Unlike the metrics package which provides raw counters/gauges/histograms, +// the stats package provides high-level system status aggregation: +// +// - Cache stats: hit rates, sizes, broadcast status +// - Journal stats: transaction counts, space utilization +// - Filesystem stats: file counts, capacity, mount state +// - Lock stats: contention metrics, hint cache performance +// +// # Collection Model +// +// Statistics are collected on-demand using a "pull" model. The [Collector] queries +// registered providers when [Collector.Collect] is called. Results are cached +// with a configurable TTL to avoid expensive repeated queries. +// +// # Provider Interfaces +// +// Components implement provider interfaces to expose their statistics: +// +// - [CacheStatsProvider]: cache hit/miss rates and sizes +// - [JournalStatsProvider]: journal state and transaction stats +// - [FilesystemStatsProvider]: file counts and capacity +// - [LockStatsProvider]: lock contention metrics +// +// This interface-based approach keeps the stats package decoupled from +// internal implementation details. +// +// # Usage +// +// // Create collector with 1-second cache TTL +// cfg := stats.DefaultConfig() +// collector := stats.NewCollector(cfg) +// +// // Register providers +// collector.SetCacheProvider(cacheManager) +// collector.SetJournalProvider(journal) +// +// // Collect statistics (cached for TTL) +// snapshot := collector.Collect() +// fmt.Printf("Cache hit rate: %.2f%%\n", snapshot.Cache.InodeHitRate*100) +package stats diff --git a/internal/stats/errors.go b/internal/stats/errors.go new file mode 100644 index 00000000..6e7268b3 --- /dev/null +++ b/internal/stats/errors.go @@ -0,0 +1,12 @@ +package stats + +import "errors" + +// Package-level errors for stats collection. +var ( + // ErrInvalidTTL is returned when the cache TTL is invalid. + ErrInvalidTTL = errors.New("stats: invalid cache TTL") + + // ErrCollectorStopped is returned when operations are attempted on a stopped collector. + ErrCollectorStopped = errors.New("stats: collector is stopped") +) diff --git a/internal/stats/stats.go b/internal/stats/stats.go new file mode 100644 index 00000000..922ce176 --- /dev/null +++ b/internal/stats/stats.go @@ -0,0 +1,345 @@ +package stats + +import "time" + +// Config holds configuration for the statistics collector. +type Config struct { + // CacheTTL is how long collected statistics are cached before re-collection. + // Shorter values provide fresher data but may impact performance. + // Default: 1 second + CacheTTL time.Duration + + // EnableComponentStats controls whether per-component stats are collected. + // Disable for minimal overhead in production. + // Default: true + EnableComponentStats bool +} + +// DefaultConfig returns a Config with sensible defaults. +func DefaultConfig() Config { + return Config{ + CacheTTL: 1 * time.Second, + EnableComponentStats: true, + } +} + +// HighFrequencyConfig returns a Config optimized for frequent collection. +// Use when stats need to be very fresh (e.g., real-time dashboards). +func HighFrequencyConfig() Config { + return Config{ + CacheTTL: 100 * time.Millisecond, + EnableComponentStats: true, + } +} + +// LowOverheadConfig returns a Config optimized for minimal overhead. +// Use in production when stats are infrequently accessed. +func LowOverheadConfig() Config { + return Config{ + CacheTTL: 10 * time.Second, + EnableComponentStats: false, + } +} + +// Validate checks that the configuration is valid. +func (c *Config) Validate() error { + if c.CacheTTL < 0 { + return ErrInvalidTTL + } + return nil +} + +// Snapshot contains a point-in-time snapshot of all system statistics. +// All fields are optional and may be nil if the corresponding component +// is not available or statistics collection is disabled. +type Snapshot struct { + // CollectedAt is when this snapshot was collected. + CollectedAt time.Time `json:"collected_at"` + + // Cache contains cache hit/miss statistics. + Cache *CacheStats `json:"cache,omitempty"` + + // Journal contains journal transaction statistics. + Journal *JournalStats `json:"journal,omitempty"` + + // Filesystem contains filesystem capacity and file count statistics. + Filesystem *FilesystemStats `json:"filesystem,omitempty"` + + // Lock contains lock contention statistics. + Lock *LockStats `json:"lock,omitempty"` + + // Trim contains TRIM/discard operation statistics. + Trim *TrimStats `json:"trim,omitempty"` + + // SFB contains Sparse File Bitmap (block allocation) statistics. + SFB *SFBStats `json:"sfb,omitempty"` + + // Cluster contains cluster membership and node information. + Cluster *ClusterInfo `json:"cluster,omitempty"` +} + +// CacheStats contains aggregated cache statistics. +type CacheStats struct { + // Inode cache + InodeCacheSize int `json:"inode_cache_size"` + InodeCacheHits uint64 `json:"inode_cache_hits"` + InodeCacheMisses uint64 `json:"inode_cache_misses"` + InodeHitRate float64 `json:"inode_hit_rate"` + + // Extent cache + ExtentCacheSize int `json:"extent_cache_size"` + ExtentCacheHits uint64 `json:"extent_cache_hits"` + ExtentCacheMisses uint64 `json:"extent_cache_misses"` + ExtentHitRate float64 `json:"extent_hit_rate"` + + // Negative cache (caches "not found" results) + NegativeCacheSize int `json:"negative_cache_size"` + NegativeHits uint64 `json:"negative_hits"` + NegativeMisses uint64 `json:"negative_misses"` + + // Broadcast/network invalidation stats + BroadcastEnabled bool `json:"broadcast_enabled"` + InvalidationsSent uint64 `json:"invalidations_sent,omitempty"` + InvalidationsReceived uint64 `json:"invalidations_received,omitempty"` + BroadcastDuplicates uint64 `json:"broadcast_duplicates,omitempty"` + MulticastEnabled bool `json:"multicast_enabled,omitempty"` + PeerCount int `json:"peer_count,omitempty"` +} + +// JournalStats contains journal transaction statistics. +type JournalStats struct { + // State is the current journal state (clean, dirty, recovering). + State string `json:"state"` + + // HeadOffset is the current write position in the journal. + HeadOffset uint32 `json:"head_offset"` + + // TailOffset is the oldest valid entry position. + TailOffset uint32 `json:"tail_offset"` + + // AvailableSpace is bytes available for new entries. + AvailableSpace uint32 `json:"available_space"` + + // ActiveTxnCount is the number of in-flight transactions. + ActiveTxnCount int `json:"active_txn_count"` + + // CommitCount is the total number of committed transactions. + CommitCount uint64 `json:"commit_count"` + + // BytesWritten is the total bytes written to the journal. + BytesWritten uint64 `json:"bytes_written"` + + // LastCheckpointSeq is the sequence number of the last checkpoint. + LastCheckpointSeq uint64 `json:"last_checkpoint_seq"` + + // BatchSyncCount is the number of batch syncs (for CommitBatch mode). + BatchSyncCount uint64 `json:"batch_sync_count,omitempty"` +} + +// FilesystemStats contains filesystem capacity and usage statistics. +type FilesystemStats struct { + // TotalBytes is the total filesystem capacity in bytes. + TotalBytes uint64 `json:"total_bytes"` + + // UsedBytes is the bytes currently in use. + UsedBytes uint64 `json:"used_bytes"` + + // FreeBytes is the bytes available for new data. + FreeBytes uint64 `json:"free_bytes"` + + // UsedPercent is the percentage of capacity in use. + UsedPercent float64 `json:"used_percent"` + + // TotalBlocks is the total number of blocks. + TotalBlocks uint64 `json:"total_blocks"` + + // UsedBlocks is the number of blocks in use. + UsedBlocks uint64 `json:"used_blocks"` + + // FreeBlocks is the number of free blocks. + FreeBlocks uint64 `json:"free_blocks"` + + // FileCount is the total number of files. + FileCount uint64 `json:"file_count,omitempty"` + + // DirectoryCount is the total number of directories. + DirectoryCount uint64 `json:"directory_count,omitempty"` + + // SnapshotCount is the number of active snapshots. + SnapshotCount int `json:"snapshot_count,omitempty"` +} + +// LockStats contains lock contention and hint cache statistics. +type LockStats struct { + // HintCacheHits is the number of lock hint cache hits. + HintCacheHits uint64 `json:"hint_cache_hits"` + + // HintCacheMisses is the number of lock hint cache misses. + HintCacheMisses uint64 `json:"hint_cache_misses"` + + // HintCacheHitRate is the hit rate as a ratio (0.0-1.0). + HintCacheHitRate float64 `json:"hint_cache_hit_rate"` + + // ActiveLocks is the number of currently held locks. + ActiveLocks int `json:"active_locks,omitempty"` + + // PendingLocks is the number of locks waiting to be acquired. + PendingLocks int `json:"pending_locks,omitempty"` +} + +// TrimStats contains TRIM/discard operation statistics. +type TrimStats struct { + // TrimOperations is the total number of TRIM operations performed. + TrimOperations uint64 `json:"trim_operations"` + + // TrimBytes is the total bytes trimmed. + TrimBytes uint64 `json:"trim_bytes"` + + // TrimBlocks is the total blocks trimmed. + TrimBlocks uint64 `json:"trim_blocks"` + + // PendingTrimBlocks is blocks queued for TRIM. + PendingTrimBlocks uint64 `json:"pending_trim_blocks,omitempty"` + + // LastTrimAt is when the last TRIM operation occurred. + LastTrimAt time.Time `json:"last_trim_at,omitempty"` + + // TrimErrors is the count of failed TRIM operations. + TrimErrors uint64 `json:"trim_errors,omitempty"` + + // TrimEnabled indicates if TRIM is enabled. + TrimEnabled bool `json:"trim_enabled"` + + // BatchSize is the current batch size for TRIM operations. + BatchSize int `json:"batch_size,omitempty"` +} + +// SFBStats contains Sparse File Bitmap (block allocation) statistics. +type SFBStats struct { + // TotalBlocks is the total number of blocks in the bitmap. + TotalBlocks uint64 `json:"total_blocks"` + + // AllocatedBlocks is the number of blocks currently allocated. + AllocatedBlocks uint64 `json:"allocated_blocks"` + + // FreeBlocks is the number of blocks available for allocation. + FreeBlocks uint64 `json:"free_blocks"` + + // AllocationPercent is the percentage of blocks allocated (0.0-100.0). + AllocationPercent float64 `json:"allocation_percent"` + + // FragmentationRatio estimates fragmentation (0.0-1.0, higher = more fragmented). + FragmentationRatio float64 `json:"fragmentation_ratio,omitempty"` + + // LargestFreeExtent is the size of the largest contiguous free region in blocks. + LargestFreeExtent uint64 `json:"largest_free_extent,omitempty"` + + // AllocationsTotal is the total number of allocation operations. + AllocationsTotal uint64 `json:"allocations_total"` + + // DeallocationsTotal is the total number of deallocation operations. + DeallocationsTotal uint64 `json:"deallocations_total"` + + // AllocationFailures is the count of failed allocations (e.g., no space). + AllocationFailures uint64 `json:"allocation_failures,omitempty"` +} + +// ClusterInfo contains cluster node and membership information. +type ClusterInfo struct { + // NodeID is this node's unique identifier. + NodeID string `json:"node_id"` + + // NodeAddress is this node's network address. + NodeAddress string `json:"node_address,omitempty"` + + // Role is this node's role (e.g., "primary", "replica", "standalone"). + Role string `json:"role"` + + // State is this node's current state (e.g., "active", "syncing", "offline"). + State string `json:"state"` + + // ClusterSize is the total number of nodes in the cluster. + ClusterSize int `json:"cluster_size"` + + // HealthyNodes is the number of nodes currently healthy. + HealthyNodes int `json:"healthy_nodes"` + + // LeaderID is the current cluster leader's ID (if applicable). + LeaderID string `json:"leader_id,omitempty"` + + // LastHeartbeatAt is when the last heartbeat was received/sent. + LastHeartbeatAt time.Time `json:"last_heartbeat_at,omitempty"` + + // JoinedAt is when this node joined the cluster. + JoinedAt time.Time `json:"joined_at,omitempty"` + + // Peers contains information about peer nodes. + Peers []PeerInfo `json:"peers,omitempty"` +} + +// PeerInfo contains information about a cluster peer node. +type PeerInfo struct { + // NodeID is the peer's unique identifier. + NodeID string `json:"node_id"` + + // Address is the peer's network address. + Address string `json:"address"` + + // State is the peer's current state. + State string `json:"state"` + + // LastSeen is when the peer was last seen. + LastSeen time.Time `json:"last_seen,omitempty"` + + // Latency is the round-trip latency to this peer in milliseconds. + Latency float64 `json:"latency_ms,omitempty"` +} + +// CacheStatsProvider is implemented by components that provide cache statistics. +type CacheStatsProvider interface { + // CacheStats returns current cache statistics. + // Returns nil if cache statistics are not available. + CacheStats() *CacheStats +} + +// JournalStatsProvider is implemented by components that provide journal statistics. +type JournalStatsProvider interface { + // JournalStats returns current journal statistics. + // Returns nil if journal statistics are not available. + JournalStats() *JournalStats +} + +// FilesystemStatsProvider is implemented by components that provide filesystem statistics. +type FilesystemStatsProvider interface { + // FilesystemStats returns current filesystem statistics. + // Returns nil if filesystem statistics are not available. + FilesystemStats() *FilesystemStats +} + +// LockStatsProvider is implemented by components that provide lock statistics. +type LockStatsProvider interface { + // LockStats returns current lock statistics. + // Returns nil if lock statistics are not available. + LockStats() *LockStats +} + +// TrimStatsProvider is implemented by components that provide TRIM statistics. +type TrimStatsProvider interface { + // TrimStats returns current TRIM/discard statistics. + // Returns nil if TRIM statistics are not available. + TrimStats() *TrimStats +} + +// SFBStatsProvider is implemented by components that provide block allocation statistics. +type SFBStatsProvider interface { + // SFBStats returns current Sparse File Bitmap statistics. + // Returns nil if SFB statistics are not available. + SFBStats() *SFBStats +} + +// ClusterInfoProvider is implemented by components that provide cluster information. +type ClusterInfoProvider interface { + // ClusterInfo returns current cluster membership and node information. + // Returns nil if cluster information is not available. + ClusterInfo() *ClusterInfo +} diff --git a/internal/stats/stats_test.go b/internal/stats/stats_test.go new file mode 100644 index 00000000..c57a250f --- /dev/null +++ b/internal/stats/stats_test.go @@ -0,0 +1,615 @@ +package stats + +import ( + "testing" + "time" +) + +// mockCacheProvider implements CacheStatsProvider for testing. +type mockCacheProvider struct { + stats *CacheStats +} + +func (m *mockCacheProvider) CacheStats() *CacheStats { + return m.stats +} + +// mockJournalProvider implements JournalStatsProvider for testing. +type mockJournalProvider struct { + stats *JournalStats +} + +func (m *mockJournalProvider) JournalStats() *JournalStats { + return m.stats +} + +// mockFilesystemProvider implements FilesystemStatsProvider for testing. +type mockFilesystemProvider struct { + stats *FilesystemStats +} + +func (m *mockFilesystemProvider) FilesystemStats() *FilesystemStats { + return m.stats +} + +// mockLockProvider implements LockStatsProvider for testing. +type mockLockProvider struct { + stats *LockStats +} + +func (m *mockLockProvider) LockStats() *LockStats { + return m.stats +} + +// mockTrimProvider implements TrimStatsProvider for testing. +type mockTrimProvider struct { + stats *TrimStats +} + +func (m *mockTrimProvider) TrimStats() *TrimStats { + return m.stats +} + +// mockSFBProvider implements SFBStatsProvider for testing. +type mockSFBProvider struct { + stats *SFBStats +} + +func (m *mockSFBProvider) SFBStats() *SFBStats { + return m.stats +} + +// mockClusterProvider implements ClusterInfoProvider for testing. +type mockClusterProvider struct { + info *ClusterInfo +} + +func (m *mockClusterProvider) ClusterInfo() *ClusterInfo { + return m.info +} + +func TestDefaultConfig(t *testing.T) { + cfg := DefaultConfig() + + if cfg.CacheTTL != 1*time.Second { + t.Errorf("expected CacheTTL 1s, got %v", cfg.CacheTTL) + } + if !cfg.EnableComponentStats { + t.Error("expected EnableComponentStats true") + } +} + +func TestConfig_Validate(t *testing.T) { + tests := []struct { + name string + config Config + wantErr error + }{ + { + name: "valid default", + config: DefaultConfig(), + wantErr: nil, + }, + { + name: "valid zero TTL", + config: Config{CacheTTL: 0}, + wantErr: nil, + }, + { + name: "invalid negative TTL", + config: Config{CacheTTL: -1 * time.Second}, + wantErr: ErrInvalidTTL, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + err := tt.config.Validate() + if err != tt.wantErr { + t.Errorf("Validate() = %v, want %v", err, tt.wantErr) + } + }) + } +} + +func TestNewCollector(t *testing.T) { + cfg := DefaultConfig() + collector := NewCollector(cfg) + + if collector == nil { + t.Fatal("NewCollector returned nil") + } +} + +func TestCollector_Collect_Empty(t *testing.T) { + cfg := DefaultConfig() + collector := NewCollector(cfg) + + snapshot := collector.Collect() + + if snapshot == nil { + t.Fatal("Collect returned nil") + } + if snapshot.CollectedAt.IsZero() { + t.Error("CollectedAt should not be zero") + } + if snapshot.Cache != nil { + t.Error("expected Cache to be nil with no provider") + } + if snapshot.Journal != nil { + t.Error("expected Journal to be nil with no provider") + } +} + +func TestCollector_SetProviders(t *testing.T) { + cfg := DefaultConfig() + collector := NewCollector(cfg) + + // Set cache provider + cacheStats := &CacheStats{ + InodeCacheSize: 100, + InodeHitRate: 0.95, + } + collector.SetCacheProvider(&mockCacheProvider{stats: cacheStats}) + + // Set journal provider + journalStats := &JournalStats{ + State: "clean", + CommitCount: 500, + } + collector.SetJournalProvider(&mockJournalProvider{stats: journalStats}) + + // Collect and verify + snapshot := collector.Collect() + + if snapshot.Cache == nil { + t.Fatal("expected Cache to be set") + } + if snapshot.Cache.InodeCacheSize != 100 { + t.Errorf("expected InodeCacheSize 100, got %d", snapshot.Cache.InodeCacheSize) + } + if snapshot.Cache.InodeHitRate != 0.95 { + t.Errorf("expected InodeHitRate 0.95, got %f", snapshot.Cache.InodeHitRate) + } + + if snapshot.Journal == nil { + t.Fatal("expected Journal to be set") + } + if snapshot.Journal.State != "clean" { + t.Errorf("expected State 'clean', got %q", snapshot.Journal.State) + } + if snapshot.Journal.CommitCount != 500 { + t.Errorf("expected CommitCount 500, got %d", snapshot.Journal.CommitCount) + } +} + +func TestCollector_CacheTTL(t *testing.T) { + cfg := Config{ + CacheTTL: 50 * time.Millisecond, + EnableComponentStats: true, + } + collector := NewCollector(cfg) + + // Track how many times provider is called + callCount := 0 + provider := &countingProvider{count: &callCount} + collector.SetCacheProvider(provider) + + // First collect + snapshot1 := collector.Collect() + if callCount != 1 { + t.Errorf("expected 1 call, got %d", callCount) + } + + // Second collect within TTL - should use cache + snapshot2 := collector.Collect() + if callCount != 1 { + t.Errorf("expected still 1 call (cached), got %d", callCount) + } + + // Verify same snapshot returned (via CollectedAt) + if !snapshot1.CollectedAt.Equal(snapshot2.CollectedAt) { + t.Error("expected cached snapshot to have same CollectedAt") + } + + // Wait for TTL to expire + time.Sleep(60 * time.Millisecond) + + // Third collect after TTL - should refresh + snapshot3 := collector.Collect() + if callCount != 2 { + t.Errorf("expected 2 calls after TTL, got %d", callCount) + } + if snapshot3.CollectedAt.Equal(snapshot1.CollectedAt) { + t.Error("expected fresh snapshot after TTL") + } +} + +// countingProvider tracks how many times CacheStats is called. +type countingProvider struct { + count *int +} + +func (p *countingProvider) CacheStats() *CacheStats { + *p.count++ + return &CacheStats{InodeCacheSize: *p.count} +} + +func TestCollector_CollectFresh(t *testing.T) { + cfg := Config{ + CacheTTL: 1 * time.Hour, // Long TTL + EnableComponentStats: true, + } + collector := NewCollector(cfg) + + callCount := 0 + provider := &countingProvider{count: &callCount} + collector.SetCacheProvider(provider) + + // First collect + collector.Collect() + if callCount != 1 { + t.Errorf("expected 1 call, got %d", callCount) + } + + // CollectFresh should bypass cache + collector.CollectFresh() + if callCount != 2 { + t.Errorf("expected 2 calls with CollectFresh, got %d", callCount) + } +} + +func TestCollector_InvalidateCache(t *testing.T) { + cfg := Config{ + CacheTTL: 1 * time.Hour, // Long TTL + EnableComponentStats: true, + } + collector := NewCollector(cfg) + + callCount := 0 + provider := &countingProvider{count: &callCount} + collector.SetCacheProvider(provider) + + // First collect + collector.Collect() + if callCount != 1 { + t.Errorf("expected 1 call, got %d", callCount) + } + + // Invalidate cache + collector.InvalidateCache() + + // Next collect should refresh + collector.Collect() + if callCount != 2 { + t.Errorf("expected 2 calls after InvalidateCache, got %d", callCount) + } +} + +func TestCollector_DisabledComponentStats(t *testing.T) { + cfg := Config{ + CacheTTL: 1 * time.Second, + EnableComponentStats: false, // Disabled + } + collector := NewCollector(cfg) + + // Set provider + collector.SetCacheProvider(&mockCacheProvider{ + stats: &CacheStats{InodeCacheSize: 100}, + }) + + // Collect - should not include stats + snapshot := collector.Collect() + + if snapshot.Cache != nil { + t.Error("expected Cache to be nil when component stats disabled") + } +} + +func TestCollector_DirectStats(t *testing.T) { + cfg := DefaultConfig() + collector := NewCollector(cfg) + + // No providers - should return nil + if collector.CacheStats() != nil { + t.Error("expected nil CacheStats with no provider") + } + if collector.JournalStats() != nil { + t.Error("expected nil JournalStats with no provider") + } + if collector.FilesystemStats() != nil { + t.Error("expected nil FilesystemStats with no provider") + } + if collector.LockStats() != nil { + t.Error("expected nil LockStats with no provider") + } + + // Set providers and verify direct access + collector.SetCacheProvider(&mockCacheProvider{ + stats: &CacheStats{InodeCacheSize: 42}, + }) + collector.SetLockProvider(&mockLockProvider{ + stats: &LockStats{HintCacheHits: 999}, + }) + + if stats := collector.CacheStats(); stats == nil || stats.InodeCacheSize != 42 { + t.Error("expected CacheStats with InodeCacheSize 42") + } + if stats := collector.LockStats(); stats == nil || stats.HintCacheHits != 999 { + t.Error("expected LockStats with HintCacheHits 999") + } +} + +func TestCacheInfo(t *testing.T) { + cfg := Config{ + CacheTTL: 100 * time.Millisecond, + EnableComponentStats: true, + } + collector := NewCollector(cfg) + + // Before any collection + info := collector.CacheInfo() + if info.Valid { + t.Error("expected cache to be invalid before collection") + } + + // After collection + collector.Collect() + info = collector.CacheInfo() + if !info.Valid { + t.Error("expected cache to be valid after collection") + } + if info.Stale { + t.Error("expected cache to not be stale immediately after collection") + } + if info.TTL != 100*time.Millisecond { + t.Errorf("expected TTL 100ms, got %v", info.TTL) + } + + // Wait for TTL to expire + time.Sleep(110 * time.Millisecond) + info = collector.CacheInfo() + if !info.Stale { + t.Error("expected cache to be stale after TTL") + } +} + +func TestIsCacheValid(t *testing.T) { + cfg := Config{ + CacheTTL: 50 * time.Millisecond, + EnableComponentStats: true, + } + collector := NewCollector(cfg) + + // Before collection + if collector.IsCacheValid() { + t.Error("expected cache invalid before collection") + } + + // After collection + collector.Collect() + if !collector.IsCacheValid() { + t.Error("expected cache valid after collection") + } + + // After TTL expires + time.Sleep(60 * time.Millisecond) + if collector.IsCacheValid() { + t.Error("expected cache invalid after TTL") + } +} + +func TestCollectWithMeta(t *testing.T) { + cfg := Config{ + CacheTTL: 100 * time.Millisecond, + EnableComponentStats: true, + } + collector := NewCollector(cfg) + + // First collection - not from cache + result1 := collector.CollectWithMeta() + if result1.FromCache { + t.Error("expected FromCache=false on first collection") + } + + // Second collection - from cache + result2 := collector.CollectWithMeta() + if !result2.FromCache { + t.Error("expected FromCache=true on second collection") + } + if result2.CacheAge < 0 { + t.Error("expected positive CacheAge") + } +} + +func TestPresetConfigs(t *testing.T) { + // Test HighFrequencyConfig + high := HighFrequencyConfig() + if high.CacheTTL != 100*time.Millisecond { + t.Errorf("HighFrequencyConfig TTL = %v, want 100ms", high.CacheTTL) + } + if err := high.Validate(); err != nil { + t.Errorf("HighFrequencyConfig validation failed: %v", err) + } + + // Test LowOverheadConfig + low := LowOverheadConfig() + if low.CacheTTL != 10*time.Second { + t.Errorf("LowOverheadConfig TTL = %v, want 10s", low.CacheTTL) + } + if low.EnableComponentStats { + t.Error("LowOverheadConfig should have EnableComponentStats=false") + } + if err := low.Validate(); err != nil { + t.Errorf("LowOverheadConfig validation failed: %v", err) + } +} + +func TestCollector_SetConfig(t *testing.T) { + collector := NewCollector(DefaultConfig()) + + // Verify initial config + if collector.Config().CacheTTL != 1*time.Second { + t.Error("expected default TTL") + } + + // Update config + newCfg := Config{CacheTTL: 5 * time.Second, EnableComponentStats: true} + collector.SetConfig(newCfg) + + if collector.Config().CacheTTL != 5*time.Second { + t.Errorf("expected new TTL 5s, got %v", collector.Config().CacheTTL) + } +} + +func TestCollector_NewProviders(t *testing.T) { + cfg := DefaultConfig() + collector := NewCollector(cfg) + + // Set all new providers + trimStats := &TrimStats{ + TrimOperations: 100, + TrimBytes: 1024 * 1024, + TrimBlocks: 256, + TrimEnabled: true, + } + collector.SetTrimProvider(&mockTrimProvider{stats: trimStats}) + + sfbStats := &SFBStats{ + TotalBlocks: 10000, + AllocatedBlocks: 7500, + FreeBlocks: 2500, + AllocationPercent: 75.0, + } + collector.SetSFBProvider(&mockSFBProvider{stats: sfbStats}) + + clusterInfo := &ClusterInfo{ + NodeID: "node-1", + Role: "primary", + State: "active", + ClusterSize: 3, + HealthyNodes: 3, + } + collector.SetClusterProvider(&mockClusterProvider{info: clusterInfo}) + + // Collect and verify + snapshot := collector.Collect() + + // Verify TrimStats + if snapshot.Trim == nil { + t.Fatal("expected Trim to be set") + } + if snapshot.Trim.TrimOperations != 100 { + t.Errorf("expected TrimOperations 100, got %d", snapshot.Trim.TrimOperations) + } + if !snapshot.Trim.TrimEnabled { + t.Error("expected TrimEnabled true") + } + + // Verify SFBStats + if snapshot.SFB == nil { + t.Fatal("expected SFB to be set") + } + if snapshot.SFB.TotalBlocks != 10000 { + t.Errorf("expected TotalBlocks 10000, got %d", snapshot.SFB.TotalBlocks) + } + if snapshot.SFB.AllocationPercent != 75.0 { + t.Errorf("expected AllocationPercent 75.0, got %f", snapshot.SFB.AllocationPercent) + } + + // Verify ClusterInfo + if snapshot.Cluster == nil { + t.Fatal("expected Cluster to be set") + } + if snapshot.Cluster.NodeID != "node-1" { + t.Errorf("expected NodeID 'node-1', got %q", snapshot.Cluster.NodeID) + } + if snapshot.Cluster.ClusterSize != 3 { + t.Errorf("expected ClusterSize 3, got %d", snapshot.Cluster.ClusterSize) + } +} + +func TestCollector_DirectStatsNewProviders(t *testing.T) { + cfg := DefaultConfig() + collector := NewCollector(cfg) + + // No providers - should return nil + if collector.TrimStats() != nil { + t.Error("expected nil TrimStats with no provider") + } + if collector.SFBStats() != nil { + t.Error("expected nil SFBStats with no provider") + } + if collector.ClusterInfo() != nil { + t.Error("expected nil ClusterInfo with no provider") + } + + // Set providers and verify direct access + collector.SetTrimProvider(&mockTrimProvider{ + stats: &TrimStats{TrimOperations: 42, TrimEnabled: true}, + }) + collector.SetSFBProvider(&mockSFBProvider{ + stats: &SFBStats{TotalBlocks: 999}, + }) + collector.SetClusterProvider(&mockClusterProvider{ + info: &ClusterInfo{NodeID: "test-node", State: "active"}, + }) + + if stats := collector.TrimStats(); stats == nil || stats.TrimOperations != 42 { + t.Error("expected TrimStats with TrimOperations 42") + } + if stats := collector.SFBStats(); stats == nil || stats.TotalBlocks != 999 { + t.Error("expected SFBStats with TotalBlocks 999") + } + if info := collector.ClusterInfo(); info == nil || info.NodeID != "test-node" { + t.Error("expected ClusterInfo with NodeID 'test-node'") + } +} + +func TestClusterInfo_WithPeers(t *testing.T) { + cfg := DefaultConfig() + collector := NewCollector(cfg) + + clusterInfo := &ClusterInfo{ + NodeID: "node-1", + NodeAddress: "192.168.1.10:8080", + Role: "primary", + State: "active", + ClusterSize: 3, + HealthyNodes: 3, + LeaderID: "node-1", + Peers: []PeerInfo{ + {NodeID: "node-2", Address: "192.168.1.11:8080", State: "active", Latency: 1.5}, + {NodeID: "node-3", Address: "192.168.1.12:8080", State: "active", Latency: 2.1}, + }, + } + collector.SetClusterProvider(&mockClusterProvider{info: clusterInfo}) + + snapshot := collector.Collect() + + if snapshot.Cluster == nil { + t.Fatal("expected Cluster to be set") + } + if len(snapshot.Cluster.Peers) != 2 { + t.Errorf("expected 2 peers, got %d", len(snapshot.Cluster.Peers)) + } + if snapshot.Cluster.Peers[0].NodeID != "node-2" { + t.Errorf("expected first peer NodeID 'node-2', got %q", snapshot.Cluster.Peers[0].NodeID) + } + if snapshot.Cluster.Peers[1].Latency != 2.1 { + t.Errorf("expected second peer Latency 2.1, got %f", snapshot.Cluster.Peers[1].Latency) + } +} + +func TestCollector_FilesystemProvider(t *testing.T) { + collector := NewCollector(DefaultConfig()) + collector.SetFilesystemProvider(&mockFilesystemProvider{stats: &FilesystemStats{TotalBytes: 1 << 30, UsedBytes: 1 << 20}}) + + snapshot := collector.Collect() + if snapshot.Filesystem == nil || snapshot.Filesystem.TotalBytes != 1<<30 || snapshot.Filesystem.UsedBytes != 1<<20 { + t.Fatalf("Collect().Filesystem = %+v, want the provider's stats", snapshot.Filesystem) + } + if got := collector.FilesystemStats(); got == nil || got.TotalBytes != 1<<30 { + t.Fatalf("FilesystemStats() = %+v, want the provider's stats", got) + } +} diff --git a/tests/integration/api_test.go b/tests/integration/api_test.go new file mode 100644 index 00000000..6e23f99e --- /dev/null +++ b/tests/integration/api_test.go @@ -0,0 +1,104 @@ +package integration + +import ( + "bytes" + "context" + "io" + "net" + "net/http" + "os" + "os/exec" + "path/filepath" + "strings" + "testing" + "time" +) + +func freeLoopbackAddr(t *testing.T) string { + t.Helper() + ln, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + t.Fatalf("Failed to find a free port: %v", err) + } + addr := ln.Addr().String() + ln.Close() + return addr +} + +func TestAPIServesHealthOnLoopback(t *testing.T) { + mfs := NewMountedFS(t, 20) + if err := mfs.Format(); err != nil { + t.Fatalf("Format failed: %v", err) + } + addr := freeLoopbackAddr(t) + mfs.ExtraArgs = []string{"-api-addr", addr} + if err := mfs.Mount(false); err != nil { + t.Fatalf("Mount failed: %v", err) + } + + client := &http.Client{Timeout: 2 * time.Second} + deadline := time.Now().Add(10 * time.Second) + for { + resp, err := client.Get("http://" + addr + "/health") + if err == nil { + resp.Body.Close() + if resp.StatusCode != http.StatusOK { + t.Fatalf("GET /health returned %d, want 200", resp.StatusCode) + } + return + } + if time.Now().After(deadline) { + t.Fatalf("API never answered on %s: %v", addr, err) + } + time.Sleep(100 * time.Millisecond) + } +} + +func TestMountRefusesUnauthenticatedRemoteAPI(t *testing.T) { + binary, err := findBinary() + if err != nil { + t.Fatalf("Failed to find binary: %v", err) + } + dir := t.TempDir() + mountPoint := filepath.Join(dir, "mnt") + image := filepath.Join(dir, "disk.img") + if err := os.Mkdir(mountPoint, 0o755); err != nil { + t.Fatalf("Failed to create mount point: %v", err) + } + if err := os.WriteFile(image, nil, 0o644); err != nil { + t.Fatalf("Failed to create image: %v", err) + } + if err := allocateImage(image, 20); err != nil { + t.Fatalf("Failed to allocate image: %v", err) + } + + for _, addr := range []string{":8080", "0.0.0.0:8080"} { + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + out, err := exec.CommandContext(ctx, binary, "-device", image, "-mount", mountPoint, "-format", "-api-addr", addr).CombinedOutput() + timedOut := ctx.Err() != nil + cancel() + if timedOut { + exec.Command("fusermount", "-u", mountPoint).Run() + t.Fatalf("-api-addr %s without -api-token: mount kept running", addr) + } + if err == nil { + t.Fatalf("-api-addr %s without -api-token: mount exited 0", addr) + } + if !strings.Contains(string(out), "-api-token") { + t.Errorf("-api-addr %s: error does not mention -api-token:\n%s", addr, out) + } + } + + f, err := os.Open(image) + if err != nil { + t.Fatalf("Failed to open image: %v", err) + } + defer f.Close() + head := make([]byte, 4096) + if _, err := io.ReadFull(f, head); err != nil { + t.Fatalf("Failed to read image: %v", err) + } + if !bytes.Equal(head, make([]byte, len(head))) { + t.Error("refused mount still wrote a superblock") + } +} diff --git a/tests/test-manifest.yaml b/tests/test-manifest.yaml index e7ac05df..205ddbff 100644 --- a/tests/test-manifest.yaml +++ b/tests/test-manifest.yaml @@ -2250,3 +2250,21 @@ scenarios: priority: go_only environments: go: internal/lock/safety_test.go::TestLockRegionStaysBoundedAcrossCycles + + # =========================================================================== + # HTTP API (one process on one host; Docker and VM would test nothing more) + # =========================================================================== + + - id: api-health-loopback + name: API answers /health on loopback + description: A mount started with -api-addr on 127.0.0.1 serves GET /health with 200 + priority: go_only + environments: + go: api_test.go::TestAPIServesHealthOnLoopback + + - id: api-refuses-remote-without-token + name: Mount refuses an unauthenticated remote API + description: With -api-addr on all interfaces and no -api-token, mount exits non-zero naming -api-token and never writes the device + priority: go_only + environments: + go: api_test.go::TestMountRefusesUnauthenticatedRemoteAPI