feat(M6): token-ring incremental log sync — append-only op log, delta rides token round-2, nodes converge on identical history (e2e verified join events)

internal/httpapi/server.go

@@ -2,6 +2,8 @@
 package httpapi
 
 import (
+	"bytes"
+	"context"
 	"embed"
 	"encoding/json"
 	"fmt"
@@ -94,6 +96,7 @@ func NewServeMux(h *Handler) (http.Handler, error) {
 	mux.HandleFunc(apiPrefix+"/cluster/cache", auth(h.handleClusterCache))
 	mux.HandleFunc(apiPrefix+"/cluster/token", auth(h.handleClusterToken))
 	mux.HandleFunc(apiPrefix+"/cluster/ring", auth(h.handleClusterRing))
+	mux.HandleFunc(apiPrefix+"/cluster/join", auth(h.handleClusterJoin))
 
 	// M6: peer-to-peer binary exchange endpoint (Basic Auth, same creds).
 	// Not under /api so peers hit it directly; auth still applied.
@@ -364,8 +367,19 @@ func (h *Handler) handleClusterToken(w http.ResponseWriter, r *http.Request) {
 		methodNotAllowed(w)
 		return
 	}
+	// Heartbeat ping: empty body (no token) is a liveness check from the
+	// leader's predecessor — answer 200 without processing.
+	if r.Body == nil {
+		w.WriteHeader(http.StatusOK)
+		return
+	}
+	body, _ := io.ReadAll(r.Body)
+	if len(bytes.TrimSpace(body)) == 0 {
+		w.WriteHeader(http.StatusOK)
+		return
+	}
 	var tk cluster.Token
-	if err := json.NewDecoder(r.Body).Decode(&tk); err != nil {
+	if err := json.Unmarshal(body, &tk); err != nil {
 		http.Error(w, "parse token: "+err.Error(), http.StatusBadRequest)
 		return
 	}
@@ -374,8 +388,13 @@ func (h *Handler) handleClusterToken(w http.ResponseWriter, r *http.Request) {
 		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)
+	// Phase flips and cycle completion happen at the leader; other nodes just
+	// forward the token along the ring.
+	if h.Ring.IsLeader() {
+		_ = h.Ring.Send(r.Context(), updated)
+	} else {
+		_ = h.Ring.Forward(r.Context(), updated)
+	}
 	writeJSON(w, http.StatusOK, updated)
 }
 
@@ -392,6 +411,37 @@ func (h *Handler) handleClusterRing(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, h.Ring.Snapshot())
 }
 
+// handleClusterJoin accepts a newcomer join request: the target node inserts
+// the newcomer after itself in the ring and returns the updated ring state
+// for the newcomer to adopt.
+func (h *Handler) handleClusterJoin(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		methodNotAllowed(w)
+		return
+	}
+	if h.Ring == nil {
+		http.Error(w, "ring engine not enabled", http.StatusNotFound)
+		return
+	}
+	var ji cluster.JoinInfo
+	if err := json.NewDecoder(r.Body).Decode(&ji); err != nil {
+		http.Error(w, "parse join: "+err.Error(), http.StatusBadRequest)
+		return
+	}
+	wasSingle := len(h.Ring.State().Nodes) <= 1
+	state := h.Ring.JoinNode(ji)
+	writeJSON(w, http.StatusOK, map[string]any{"state": state})
+	// Kick off the token cycle AFTER the newcomer has adopted (respond first,
+	// then start in background so the new node is no longer single when the
+	// token reaches it).
+	if wasSingle && h.Ring.IsLeader() {
+		go func() {
+			time.Sleep(800 * time.Millisecond)
+			h.Ring.StartRing(context.Background())
+		}()
+	}
+}
+
 // 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 {