feat(M6): token ring data plane + engine — pending adds disappear on claim, topology written back for full cluster view (per authoritative design)

internal/httpapi/server.go

@@ -39,6 +39,8 @@ type Handler struct {
 	SyncWorkers func()
 	// Cluster is the peer-to-peer binary registry (M6). Nil disables M6 routes.
 	Cluster *cluster.Registry
+	// Ring is the token-ring engine (M6). Nil disables ring routes.
+	Ring *cluster.Engine
 	// SelfAddr is this node's reachable listen address (from -addr), used for
 	// cluster discovery so peers can reach back for binary exchange.
 	SelfAddr string
@@ -90,6 +92,8 @@ func NewServeMux(h *Handler) (http.Handler, error) {
 	// M6: cluster nodes + per-node cached versions (UI + discovery).
 	mux.HandleFunc(apiPrefix+"/cluster/nodes", auth(h.handleClusterNodes))
 	mux.HandleFunc(apiPrefix+"/cluster/cache", auth(h.handleClusterCache))
+	mux.HandleFunc(apiPrefix+"/cluster/token", auth(h.handleClusterToken))
+	mux.HandleFunc(apiPrefix+"/cluster/ring", auth(h.handleClusterRing))
 
 	// M6: peer-to-peer binary exchange endpoint (Basic Auth, same creds).
 	// Not under /api so peers hit it directly; auth still applied.
@@ -349,6 +353,45 @@ func (h *Handler) handleClusterCache(w http.ResponseWriter, r *http.Request) {
 	}
 }
 
+// handleClusterToken receives the circulating token (POST), lets the ring
+// engine process it, returns the updated token so the caller can forward it.
+func (h *Handler) handleClusterToken(w http.ResponseWriter, r *http.Request) {
+	if h.Ring == nil {
+		http.Error(w, "ring engine not enabled", http.StatusNotFound)
+		return
+	}
+	if r.Method != http.MethodPost {
+		methodNotAllowed(w)
+		return
+	}
+	var tk cluster.Token
+	if err := json.NewDecoder(r.Body).Decode(&tk); err != nil {
+		http.Error(w, "parse token: "+err.Error(), http.StatusBadRequest)
+		return
+	}
+	updated, err := h.Ring.OnToken(r.Context(), &tk)
+	if err != nil {
+		http.Error(w, "token process: "+err.Error(), http.StatusInternalServerError)
+		return
+	}
+	// After processing, the receiving node passes it along to its successor.
+	_ = h.Ring.Forward(r.Context(), updated)
+	writeJSON(w, http.StatusOK, updated)
+}
+
+// handleClusterRing reports the local ring engine state snapshot (frontend).
+func (h *Handler) handleClusterRing(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		methodNotAllowed(w)
+		return
+	}
+	if h.Ring == nil {
+		http.Error(w, "ring engine not enabled", http.StatusNotFound)
+		return
+	}
+	writeJSON(w, http.StatusOK, h.Ring.Snapshot())
+}
+
 // frpcVersionOf extracts the frpc version from a binary path like
 // .../bin/frpc-0.71.0/frpc. Empty when not a versioned cache path.
 func frpcVersionOf(binPath string) string {