docs: add admin UI and key visualizer design (#545)

Proposes a standalone cmd/elastickv-admin binary and a TiKV-style key
visualizer heatmap. Avoids the Prometheus client dependency in the
initial phases by adding an in-process LiveSummary alongside the
existing observers, and keeps sampler hot-path overhead below the
benchmark noise floor via adaptive 1-in-N sampling with a ≥95% capture
SLO.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Added a comprehensive design spec for the admin Web UI and Key
Visualizer (architecture, sampling, persistence, UI interactions, phased
plan).

* **New Features**
* Standalone admin HTTP server with cluster-overview API, membership
discovery, CLI controls, and graceful shutdown.
* Token-protected Admin gRPC API exposing cluster, raft, adapter,
key-visualizer, route detail, and live event streams.
* Key Visualizer: sampled heatmap, live column updates, drill-down,
uncertainty/hatched rendering, and continuity across splits/merges.

* **Tests**
* Extensive unit and integration tests covering admin HTTP/gRPC,
discovery/fanout, auth, client caching, token loading, and startup
wiring.

* **Chores**
  * Protobuf generation updated to include the new admin service.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: bootjp

adapter/admin_grpc.go

@@ -27,3 +27,16 @@ func GRPCDialOptions() []grpc.DialOption {
 		),
 	}
 }
+
+// GRPCCallOptions returns the per-call message-size cap dial option used by
+// callers that supply their own transport credentials (e.g. the admin
+// binary's TLS-aware fanout). Without this, gRPC-Go's default ~4 MiB recv
+// cap would silently fail RPCs once aggregated cluster-overview / matrix
+// admin payloads exceed 4 MiB even though node servers (GRPCServerOptions)
+// are configured for 64 MiB.
+func GRPCCallOptions() grpc.DialOption {
+	return grpc.WithDefaultCallOptions(
+		grpc.MaxCallRecvMsgSize(GRPCMaxMessageBytes),
+		grpc.MaxCallSendMsgSize(GRPCMaxMessageBytes),
+	)
+}

adapter/admin_grpc_test.go

@@ -19,6 +19,7 @@ import (
 
 const (
 	fsmSnapDirName       = "fsm-snap"
+	snapFileExt          = ".snap"
 	snapshotTokenSize    = 17 // 4 (magic) + 1 (version) + 8 (index) + 4 (crc32c)
 	snapshotTokenVersion = byte(0x01)
 
@@ -135,7 +136,7 @@ func fsmSnapPath(fsmSnapDir string, index uint64) string {
 // Snap files are named "{term:016x}-{index:016x}.snap".
 // Returns 0 on parse failure.
 func parseSnapFileIndex(name string) uint64 {
-	base := strings.TrimSuffix(name, ".snap")
+	base := strings.TrimSuffix(name, snapFileExt)
 	idx := strings.LastIndex(base, "-")
 	if idx < 0 {
 		return 0
@@ -554,7 +555,7 @@ func collectLiveSnapIndexes(snapDir string) (map[uint64]bool, error) {
 	}
 	liveIndexes := make(map[uint64]bool, len(snapEntries))
 	for _, e := range snapEntries {
-		if !e.IsDir() && filepath.Ext(e.Name()) == ".snap" {
+		if !e.IsDir() && filepath.Ext(e.Name()) == snapFileExt {
 			if idx := parseSnapFileIndex(e.Name()); idx > 0 {
 				liveIndexes[idx] = true
 			}
@@ -644,7 +645,7 @@ func purgeOldSnapshotFiles(snapDir, fsmSnapDir string) error {
 func collectSnapNames(entries []os.DirEntry) []string {
 	var snaps []string
 	for _, e := range entries {
-		if !e.IsDir() && filepath.Ext(e.Name()) == ".snap" {
+		if !e.IsDir() && filepath.Ext(e.Name()) == snapFileExt {
 			snaps = append(snaps, e.Name())
 		}
 	}

cmd/elastickv-admin/main.go

@@ -0,0 +1,57 @@
+package internal
+
+import (
+	"fmt"
+	"io"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/cockroachdb/errors"
+)
+
+// LoadBearerTokenFile materialises a bearer-token file with a strict upper
+// bound on size so a misconfigured path (for example, pointing at a log)
+// cannot force an arbitrary allocation before the bearer-token check.
+// The file is read through an io.LimitReader bounded to maxBytes+1 so a
+// file that grows or is swapped between stat() and read() still cannot
+// sneak past the cap.
+//
+// The returned string has surrounding whitespace trimmed; an empty file (or
+// one that is only whitespace) is reported as an error so operators notice
+// the misconfiguration immediately.
+//
+// The humanName is used in error messages to distinguish token files (e.g.
+// "admin token" vs "node token"); callers typically pass a fixed string like
+// "admin token" or "node token".
+func LoadBearerTokenFile(path string, maxBytes int64, humanName string) (string, error) {
+	if humanName == "" {
+		humanName = "token"
+	}
+	abs, err := filepath.Abs(path)
+	if err != nil {
+		return "", errors.Wrapf(err, "resolve %s path", humanName)
+	}
+	f, err := os.Open(abs)
+	if err != nil {
+		return "", errors.Wrapf(err, "open %s file", humanName)
+	}
+	defer func() {
+		if cerr := f.Close(); cerr != nil {
+			log.Printf("internal: close %s file %s: %v", humanName, abs, cerr)
+		}
+	}()
+	b, err := io.ReadAll(io.LimitReader(f, maxBytes+1))
+	if err != nil {
+		return "", errors.Wrapf(err, "read %s file", humanName)
+	}
+	if int64(len(b)) > maxBytes {
+		return "", fmt.Errorf("%s file %s exceeds maximum of %d bytes", humanName, abs, maxBytes)
+	}
+	tok := strings.TrimSpace(string(b))
+	if tok == "" {
+		return "", fmt.Errorf("%s file %s is empty", humanName, abs)
+	}
+	return tok, nil
+}

cmd/elastickv-admin/main_test.go

@@ -0,0 +1,59 @@
+package internal
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestLoadBearerTokenFileHappyPath(t *testing.T) {
+	t.Parallel()
+	dir := t.TempDir()
+	path := filepath.Join(dir, "tok")
+	if err := os.WriteFile(path, []byte("\n  s3cret \n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	got, err := LoadBearerTokenFile(path, 4<<10, "admin token")
+	if err != nil {
+		t.Fatalf("LoadBearerTokenFile: %v", err)
+	}
+	if got != "s3cret" {
+		t.Fatalf("tok = %q, want s3cret", got)
+	}
+}
+
+func TestLoadBearerTokenFileRejectsEmpty(t *testing.T) {
+	t.Parallel()
+	dir := t.TempDir()
+	path := filepath.Join(dir, "empty")
+	if err := os.WriteFile(path, []byte("   \n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	_, err := LoadBearerTokenFile(path, 4<<10, "admin token")
+	if err == nil || !strings.Contains(err.Error(), "is empty") {
+		t.Fatalf("want empty-file error, got %v", err)
+	}
+}
+
+func TestLoadBearerTokenFileRejectsOversize(t *testing.T) {
+	t.Parallel()
+	dir := t.TempDir()
+	path := filepath.Join(dir, "huge")
+	const cap_ = 64
+	if err := os.WriteFile(path, []byte(strings.Repeat("x", cap_+1)), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	_, err := LoadBearerTokenFile(path, cap_, "admin token")
+	if err == nil || !strings.Contains(err.Error(), "exceeds maximum") {
+		t.Fatalf("want oversize error, got %v", err)
+	}
+}
+
+func TestLoadBearerTokenFileMissingFile(t *testing.T) {
+	t.Parallel()
+	_, err := LoadBearerTokenFile("/definitely/not/there", 4<<10, "admin token")
+	if err == nil {
+		t.Fatal("expected open-failure error")
+	}
+}