vibe: this is an implementation spike of the planned items for review

Author: centerorbit

README.md

@@ -48,9 +48,15 @@ export PSSTD_GOSSIP=":7947"                       # peer sync listen address, de
 export PSSTD_SEEDS="10.0.1.20:7946,10.0.1.21:7946" # explicit peer sync addresses
 export PSSTD_DB="./data"                          # local state directory
 export PSSTD_WEB="true"                           # set false for sync-only nodes
+export PSSTD_NODE_NAME="rack-a-01"                # optional stable node identity override
 ./psstd
 ```
 
+By default, psstd uses the OS hostname as the node identity. Set
+`PSSTD_NODE_NAME` for cloned hosts, containers, or multiple test instances that
+would otherwise publish the same hostname. The override must be non-empty and
+must not contain whitespace.
+
 ## Discovery
 
 | Environment | How nodes find each other |

discovery.go

@@ -63,7 +63,6 @@ func discoverPeers() []string {
 			continue
 		}
 		peer := fmt.Sprintf("%s:%d", addr.String(), entry.Port)
-		log.Printf("mDNS: discovered peer %s (%s)", entry.Name, peer)
 		peers = append(peers, peer)
 	}
 	return peers

gossip.go

@@ -5,7 +5,6 @@ import (
 	"errors"
 	"log"
 	"sync"
-	"time"
 
 	"github.com/cockroachdb/pebble/v2"
 	"github.com/hashicorp/memberlist"
@@ -14,14 +13,15 @@ import (
 var appVersion = "dev"
 
 type NodeStats struct {
-	Name      string     `json:"name"`
-	Version   string     `json:"version,omitempty"`
-	WebURL    string     `json:"web,omitempty"`
-	CPU       []float64  `json:"cpu"`
-	MemUsed   uint64     `json:"mu"`
-	MemTotal  uint64     `json:"mt"`
-	Load      [3]float64 `json:"ld"`
-	UpdatedAt int64      `json:"ts"` // unix nano, LWW key
+	Name       string     `json:"name"`
+	Version    string     `json:"version,omitempty"`
+	WebURL     string     `json:"web,omitempty"`
+	TTLSeconds int        `json:"ttl,omitempty"`
+	CPU        []float64  `json:"cpu"`
+	MemUsed    uint64     `json:"mu"`
+	MemTotal   uint64     `json:"mt"`
+	Load       [3]float64 `json:"ld"`
+	UpdatedAt  int64      `json:"ts"` // unix nano, LWW key
 }
 
 var errStaleVersion = errors.New("stale version")
@@ -107,7 +107,7 @@ func purgeOfflineDifferentVersion(db *pebble.DB, version string) error {
 }
 
 func nodeRecordOffline(s NodeStats) bool {
-	return s.UpdatedAt == 0 || time.Since(time.Unix(0, s.UpdatedAt)) > 15*time.Second
+	return nodeHealth(s).State == healthOffline
 }
 
 // ── Delegate ──────────────────────────────────────────────────────────────────

main.go

@@ -16,18 +16,23 @@ import (
 )
 
 const (
-	envDB      = "PSSTD_DB"
-	envHTTP    = "PSSTD_HTTP"
-	envGossip  = "PSSTD_GOSSIP"
-	envSeeds   = "PSSTD_SEEDS"
-	envHTTPAd  = "PSSTD_ADVERTISE_HTTP"
-	envWeb     = "PSSTD_WEB" // "true" to enable HTTP, default true
-	gossipPort = 7946
-	httpPort   = 8080
+	envDB       = "PSSTD_DB"
+	envHTTP     = "PSSTD_HTTP"
+	envGossip   = "PSSTD_GOSSIP"
+	envSeeds    = "PSSTD_SEEDS"
+	envHTTPAd   = "PSSTD_ADVERTISE_HTTP"
+	envWeb      = "PSSTD_WEB" // "true" to enable HTTP, default true
+	envNodeName = "PSSTD_NODE_NAME"
+	gossipPort  = 7946
+	httpPort    = 8080
 )
 
 func main() {
 	hostname, _ := os.Hostname()
+	nodeName, err := nodeNameFromEnv(hostname)
+	if err != nil {
+		log.Fatalf("node name: %v", err)
+	}
 
 	dbPath := envOr(envDB, "./data")
 	httpAddr := envOr(envHTTP, fmt.Sprintf(":%d", httpPort))
@@ -47,7 +52,7 @@ func main() {
 	if err != nil {
 		if pebbleLockHeld(err) {
 			log.Printf("psstd already appears to own %s; starting terminal mirror instead", dbPath)
-			runTerminalMirror(hostname, gossipAddr, seeds)
+			runTerminalMirror(nodeName, gossipAddr, seeds)
 			return
 		}
 		log.Fatalf("pebble open: %v", err)
@@ -65,7 +70,7 @@ func main() {
 	delegate := newKVDelegate(db, appVersion)
 
 	cfg := memberlist.DefaultLANConfig()
-	cfg.Name = hostname
+	cfg.Name = nodeName
 	cfg.BindAddr, cfg.BindPort = splitHostPort(gossipAddr)
 	cfg.Delegate = delegate
 	cfg.Events = newEventDelegate(db, appVersion)
@@ -79,7 +84,7 @@ func main() {
 			}
 			db = nil
 			log.Printf("psstd already appears to be listening on %s; starting terminal mirror instead", gossipAddr)
-			runTerminalMirror(hostname, gossipAddr, seeds)
+			runTerminalMirror(nodeName, gossipAddr, seeds)
 			return
 		}
 		log.Fatalf("memberlist create: %v", err)
@@ -88,12 +93,23 @@ func main() {
 
 	// ── Discovery ────────────────────────────────────────────────────────────
 	// 1. Register ourselves via mDNS so peers can find us on LAN
-	stopMDNS := registerMDNS(hostname, cfg.BindPort)
+	stopMDNS := registerMDNS(nodeName, cfg.BindPort)
 	defer stopMDNS()
 
 	// 2. Scan for existing peers (mDNS + any explicit seeds)
 	discovered := discoverPeers()
 	allSeeds := append(seeds, discovered...)
+	logStartupConfig(startupConfig{
+		NodeName:   nodeName,
+		DBPath:     dbPath,
+		HTTPAddr:   httpAddr,
+		WebURL:     webURL,
+		GossipAddr: gossipAddr,
+		WebEnabled: webEnabled,
+		Version:    appVersion,
+		SeedCount:  len(seeds),
+		MDNSCount:  len(discovered),
+	})
 	if len(allSeeds) > 0 {
 		if n, err := list.Join(allSeeds); err != nil {
 			log.Printf("join warning (joined %d): %v", n, err)
@@ -105,22 +121,37 @@ func main() {
 	}
 
 	// ── Stats heartbeat ─────────────────────────────────────────────────────
-	go statsLoop(hostname, webURL, appVersion, db, delegate)
+	go statsLoop(nodeName, webURL, appVersion, db, delegate)
 
 	// ── HTTP ─────────────────────────────────────────────────────────────────
 	if webEnabled {
 		mux := http.NewServeMux()
-		mux.HandleFunc("/", makeHandler(db, hostname))
-		log.Printf("psstd version=%s node=%s http=%s advertise=%s gossip=%s web=true", appVersion, hostname, httpAddr, webURL, gossipAddr)
+		mux.HandleFunc("/", makeHandler(db, nodeName))
 		if err := http.ListenAndServe(httpAddr, mux); err != nil {
 			log.Fatalf("http: %v", err)
 		}
 	} else {
-		log.Printf("psstd version=%s node=%s gossip=%s web=false", appVersion, hostname, gossipAddr)
 		select {} // block forever
 	}
 }
 
+type startupConfig struct {
+	NodeName   string
+	DBPath     string
+	HTTPAddr   string
+	WebURL     string
+	GossipAddr string
+	WebEnabled bool
+	Version    string
+	SeedCount  int
+	MDNSCount  int
+}
+
+func logStartupConfig(cfg startupConfig) {
+	log.Printf("psstd startup: version=%s node=%s db=%s web=%t http=%s advertise=%s gossip=%s seeds=%d mdns=%d",
+		cfg.Version, cfg.NodeName, cfg.DBPath, cfg.WebEnabled, cfg.HTTPAddr, cfg.WebURL, cfg.GossipAddr, cfg.SeedCount, cfg.MDNSCount)
+}
+
 func pebbleLockHeld(err error) bool {
 	msg := strings.ToLower(err.Error())
 	return strings.Contains(msg, "lock") &&
@@ -255,6 +286,23 @@ func envOr(key, def string) string {
 	return def
 }
 
+func nodeNameFromEnv(hostname string) (string, error) {
+	override, ok := os.LookupEnv(envNodeName)
+	if !ok || override == "" {
+		if strings.TrimSpace(hostname) == "" {
+			return "", fmt.Errorf("hostname is empty; set %s", envNodeName)
+		}
+		return hostname, nil
+	}
+	if strings.TrimSpace(override) != override || override == "" {
+		return "", fmt.Errorf("%s must not be empty or have leading/trailing whitespace", envNodeName)
+	}
+	if strings.ContainsAny(override, " \t\r\n") {
+		return "", fmt.Errorf("%s must not contain whitespace", envNodeName)
+	}
+	return override, nil
+}
+
 func splitCSV(s string) []string {
 	var out []string
 	for _, p := range strings.Split(s, ",") {

main_test.go

@@ -0,0 +1,56 @@
+package main
+
+import (
+	"os"
+	"testing"
+)
+
+func withoutNodeNameEnv(t *testing.T) {
+	t.Helper()
+	old, hadOld := os.LookupEnv(envNodeName)
+	if err := os.Unsetenv(envNodeName); err != nil {
+		t.Fatalf("unset %s: %v", envNodeName, err)
+	}
+	t.Cleanup(func() {
+		if hadOld {
+			_ = os.Setenv(envNodeName, old)
+		} else {
+			_ = os.Unsetenv(envNodeName)
+		}
+	})
+}
+
+func TestNodeNameFromEnvUsesHostnameByDefault(t *testing.T) {
+	withoutNodeNameEnv(t)
+
+	got, err := nodeNameFromEnv("host-a")
+	if err != nil {
+		t.Fatalf("nodeNameFromEnv: %v", err)
+	}
+	if got != "host-a" {
+		t.Fatalf("name = %q, want host-a", got)
+	}
+}
+
+func TestNodeNameFromEnvUsesOverride(t *testing.T) {
+	t.Setenv(envNodeName, "test-node")
+
+	got, err := nodeNameFromEnv("host-a")
+	if err != nil {
+		t.Fatalf("nodeNameFromEnv: %v", err)
+	}
+	if got != "test-node" {
+		t.Fatalf("name = %q, want test-node", got)
+	}
+}
+
+func TestNodeNameFromEnvRejectsWhitespaceOverride(t *testing.T) {
+	for _, value := range []string{" test-node", "test-node ", "test node", "\t"} {
+		t.Run(value, func(t *testing.T) {
+			t.Setenv(envNodeName, value)
+			if got, err := nodeNameFromEnv("host-a"); err == nil {
+				t.Fatalf("name = %q, want error", got)
+			}
+		})
+	}
+}