maintainer,heartbeatpb: clarify drain comments

Author: hongyunyan

heartbeatpb/heartbeat.pb.go

@@ -141,9 +141,17 @@ message MaintainerHeartbeat {
 
 // DrainProgress is maintainer-observed progress for dispatcher drain on one target.
 message DrainProgress {
+    // target_node_id is the node currently being evacuated for this changefeed.
+    // It matches the active dispatcher drain target seen by this maintainer.
     string target_node_id = 1;
+    // target_epoch is the epoch attached to target_node_id.
+    // Reviewers should read (target_node_id, target_epoch) as one monotonic target snapshot.
     uint64 target_epoch = 2;
+    // target_dispatcher_count is the current number of this changefeed's
+    // dispatchers still hosted on target_node_id in the maintainer snapshot.
     uint32 target_dispatcher_count = 3;
+    // target_inflight_drain_move_count is the number of unfinished move
+    // operators already evacuating dispatchers away from target_node_id.
     uint32 target_inflight_drain_move_count = 4;
 }
 

heartbeatpb/heartbeat.proto

@@ -31,6 +31,17 @@ import (
 	"go.uber.org/zap"
 )
 
+// managerMaintainerSet owns the changefeed-scoped part of a maintainer manager.
+// It tracks the local changefeedID -> maintainer registry, creates and removes
+// maintainers, routes maintainer-bound messages, and aggregates maintainer
+// heartbeats back to coordinator.
+//
+// In contrast, managerNodeState owns node-scoped state shared by the whole
+// capture, such as liveness, node epoch, and the latest manager-level drain
+// target. The Manager combines both layers: managerNodeState is the single
+// node-wide source of truth, while managerMaintainerSet fans that node-scoped
+// state out to individual maintainers and manages their per-changefeed
+// lifecycles.
 type managerMaintainerSet struct {
 	// conf is shared scheduler configuration for newly created maintainers.
 	conf *config.SchedulerConfig

maintainer/maintainer_manager_maintainers.go

@@ -38,9 +38,13 @@ type managerNodeState struct {
 	// must match it so stale requests from a previous process instance are ignored.
 	nodeEpoch uint64
 
-	// dispatcherDrainTarget caches the latest coordinator-issued dispatcher drain
-	// target at manager scope so this node can acknowledge activation and clear
-	// even when it temporarily hosts no maintainers.
+	// dispatcherDrainTarget stores the latest drain target for dispatcher
+	// evacuation already applied on this capture. Here "dispatcher" explains
+	// what is being drained: the dispatcher tasks currently hosted on the target
+	// node, not the maintainer itself and not the node-liveness state. It is
+	// capture-wide state, not per-changefeed state. Keeping it here lets the
+	// manager acknowledge "target set" and "target cleared" in node heartbeat
+	// even when this capture currently hosts no maintainers.
 	dispatcherDrainTarget struct {
 		sync.RWMutex
 		target node.ID

maintainer/maintainer_manager_node.go

@@ -29,17 +29,25 @@ const balanceDrainCooldown = 120 * time.Second
 // changefeed. All schedulers read it through snapshots so a single tick sees a
 // consistent view of the maintainer host and the active drain target.
 type DrainState struct {
+	// mu protects the full drain-state snapshot so schedulers can read a
+	// consistent self/target view within one tick.
 	mu sync.RWMutex
 
-	selfNodeID   node.ID
+	// selfNodeID is the node currently hosting this changefeed maintainer.
+	selfNodeID node.ID
+	// targetNodeID is the node currently being evacuated for this changefeed.
 	targetNodeID node.ID
-	targetEpoch  uint64
+	// targetEpoch is the monotonic epoch paired with targetNodeID.
+	targetEpoch uint64
 }
 
 type drainStateSnapshot struct {
-	selfNodeID   node.ID
+	// selfNodeID is the snapshot copy of the maintainer host node.
+	selfNodeID node.ID
+	// targetNodeID is the snapshot copy of the active drain target node.
 	targetNodeID node.ID
-	targetEpoch  uint64
+	// targetEpoch is the snapshot copy of the active drain target epoch.
+	targetEpoch uint64
 }
 
 // NewDrainState creates an empty drain state with no active drain target.