Feat v0.6.0 cluster registry (#36)

Co-authored-by: Jeffrey Smith <jasafpro@gmail.com>
Co-committed-by: Jeffrey Smith <jasafpro@gmail.com>

server/store/cluster_iface.go

@@ -0,0 +1,37 @@
+package store
+
+import (
+	"context"
+	"encoding/json"
+	"time"
+)
+
+// ClusterNode represents a registered node in the cluster registry.
+type ClusterNode struct {
+	NodeID       string          `json:"node_id"`
+	Endpoint     string          `json:"endpoint"`
+	Seq          int             `json:"seq"`
+	RegisteredAt time.Time       `json:"registered_at"`
+	Heartbeat    time.Time       `json:"heartbeat"`
+	Stats        json.RawMessage `json:"stats"`
+}
+
+// ClusterStore manages the node_registry table for cluster self-assembly.
+// Postgres-only — SQLite deployments set this to nil.
+type ClusterStore interface {
+	// Register inserts or re-registers a node (idempotent).
+	Register(ctx context.Context, nodeID, endpoint string) error
+
+	// Heartbeat updates the node's heartbeat timestamp and stats.
+	// Returns rows affected — 0 means the node was swept (self-eviction).
+	Heartbeat(ctx context.Context, nodeID string, stats json.RawMessage) (int64, error)
+
+	// SweepStale deletes nodes whose heartbeat is older than threshold.
+	SweepStale(ctx context.Context, threshold time.Duration) (int64, error)
+
+	// ListNodes returns all registered nodes ordered by sequence.
+	ListNodes(ctx context.Context) ([]ClusterNode, error)
+
+	// Deregister removes a node (best-effort cleanup on shutdown).
+	Deregister(ctx context.Context, nodeID string) error
+}

server/store/interfaces.go

@@ -54,6 +54,7 @@ type Stores struct {
 	RateLimits      RateLimitStore           // v0.32.0: Distributed rate limiting
 	Triggers        TriggerStore             // v0.2.2: Extension event/webhook triggers
 	ScheduledTasks  ScheduledTaskStore       // v0.2.2: User-created cron tasks
+	Cluster         ClusterStore             // v0.6.0: PG-backed cluster node registry (nil on SQLite)
 }
 
 // TeamAvailableModel is returned by CatalogStore.ListTeamAvailable.

server/store/postgres/cluster.go

@@ -0,0 +1,78 @@
+package postgres
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"switchboard-core/store"
+)
+
+// ClusterStore manages node_registry — Postgres-only UNLOGGED table.
+type ClusterStore struct{}
+
+func NewClusterStore() *ClusterStore { return &ClusterStore{} }
+
+func (s *ClusterStore) Register(ctx context.Context, nodeID, endpoint string) error {
+	_, err := DB.ExecContext(ctx, `
+		INSERT INTO node_registry (node_id, endpoint)
+		VALUES ($1, $2)
+		ON CONFLICT (node_id) DO UPDATE
+		SET endpoint      = EXCLUDED.endpoint,
+		    registered_at = now(),
+		    heartbeat     = now(),
+		    stats         = '{}'
+	`, nodeID, endpoint)
+	return err
+}
+
+func (s *ClusterStore) Heartbeat(ctx context.Context, nodeID string, stats json.RawMessage) (int64, error) {
+	result, err := DB.ExecContext(ctx, `
+		UPDATE node_registry
+		SET heartbeat = now(), stats = $2
+		WHERE node_id = $1
+	`, nodeID, stats)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
+func (s *ClusterStore) SweepStale(ctx context.Context, threshold time.Duration) (int64, error) {
+	result, err := DB.ExecContext(ctx, `
+		DELETE FROM node_registry
+		WHERE heartbeat < now() - $1 * interval '1 second'
+	`, threshold.Seconds())
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
+func (s *ClusterStore) ListNodes(ctx context.Context) ([]store.ClusterNode, error) {
+	rows, err := DB.QueryContext(ctx, `
+		SELECT node_id, endpoint, seq, registered_at, heartbeat, stats
+		FROM node_registry
+		ORDER BY seq
+	`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var nodes []store.ClusterNode
+	for rows.Next() {
+		var n store.ClusterNode
+		if err := rows.Scan(&n.NodeID, &n.Endpoint, &n.Seq, &n.RegisteredAt, &n.Heartbeat, &n.Stats); err != nil {
+			return nil, fmt.Errorf("scan cluster node: %w", err)
+		}
+		nodes = append(nodes, n)
+	}
+	return nodes, rows.Err()
+}
+
+func (s *ClusterStore) Deregister(ctx context.Context, nodeID string) error {
+	_, err := DB.ExecContext(ctx, `DELETE FROM node_registry WHERE node_id = $1`, nodeID)
+	return err
+}

server/store/postgres/stores.go

@@ -32,5 +32,6 @@ func NewStores(db *sql.DB) store.Stores {
 		RateLimits:     NewRateLimitStore(),
 		Triggers:       NewTriggerStore(),
 		ScheduledTasks: NewScheduledTaskStore(),
+		Cluster:        NewClusterStore(),
 	}
 }