From f56277b98929e85bdaa197cd0180de512d9e2ce1 Mon Sep 17 00:00:00 2001
From: sumeerbhola <sumeer@cockroachlabs.com>
Date: Mon, 5 Aug 2024 11:47:24 -0400
Subject: [PATCH] raftpb: add Priority for use in RACv2

Informs #123509

Epic: none

Release note: None
---
 pkg/raft/raftpb/BUILD.bazel |  5 +++-
 pkg/raft/raftpb/raft.go     | 59 +++++++++++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+), 1 deletion(-)

diff --git a/pkg/raft/raftpb/BUILD.bazel b/pkg/raft/raftpb/BUILD.bazel
index 91088cc2903e..c7cbe40a903a 100644
--- a/pkg/raft/raftpb/BUILD.bazel
+++ b/pkg/raft/raftpb/BUILD.bazel
@@ -31,7 +31,10 @@ go_library(
     embed = [":raftpb_go_proto"],
     importpath = "github.com/cockroachdb/cockroach/pkg/raft/raftpb",
     visibility = ["//visibility:public"],
-    deps = ["@com_github_gogo_protobuf//proto"],
+    deps = [
+        "@com_github_cockroachdb_redact//:redact",
+        "@com_github_gogo_protobuf//proto",
+    ],
 )
 
 go_test(
diff --git a/pkg/raft/raftpb/raft.go b/pkg/raft/raftpb/raft.go
index c57eb0d1b9b5..9d5ee7836570 100644
--- a/pkg/raft/raftpb/raft.go
+++ b/pkg/raft/raftpb/raft.go
@@ -10,6 +10,8 @@
 
 package raftpb
 
+import "github.com/cockroachdb/redact"
+
 // PeerID is a custom type for peer IDs in a raft group.
 type PeerID uint64
 
@@ -22,3 +24,60 @@ type Epoch int64
 
 // SafeValue implements the redact.SafeValue interface.
 func (e Epoch) SafeValue() {}
+
+// Priority specifies per-entry priorities, that are local to the interaction
+// between a leader-replica pair, i.e., they are not an invariant of a
+// particular entry in the raft log (the replica could be the leader itself or
+// a follower). There are four priorities, ranging from low to high. These
+// form the foundation for a priority based admission control sub-system, for
+// the replication layer, where the functionality is split between the Raft
+// layer and higher layer that exercises Raft. We discuss Raft's
+// responsibility in the functionality below.
+//
+// Raft is not concerned with how the higher layer at the leader assigns
+// priorities, or communicates them to a replica.
+//
+// Raft provides (a) tracking of an Admitted vector (one element per priority,
+// for each replica), (b) pinging for followers (using MsgApps) when Admitted
+// vector elements are lagging behind Match, (c) (for followers) piggy-backing
+// Admitted vectors on MsgApp and MsgAppResp to allow the leader to converge
+// to the follower's state, (d) method for a replica to advance the value of
+// the Admitted vector.
+//
+// (d) is the entry point for the higher layer to participate in the liveness
+// of Admitted, but the nitty-gritty details of liveness are handled by Raft.
+//
+// Note that even though the priorities are per-entry on a leader-replica
+// pair, we expect the higher layer to advance Admitted for all priorities.
+// That is, if Admitted[LowPri]=10 and entries 11, 12 are assigned HighPri, it
+// is the responsibility of the higher layer to set Admitted[LowPri]=12,
+// without waiting for future LowPri entries to arrive.
+type Priority uint8
+
+const (
+	LowPri Priority = iota
+	NormalPri
+	AboveNormalPri
+	HighPri
+	NumPriorities
+)
+
+func (p Priority) String() string {
+	return redact.StringWithoutMarkers(p)
+}
+
+// SafeFormat implements the redact.SafeFormatter interface.
+func (p Priority) SafeFormat(w redact.SafePrinter, _ rune) {
+	switch p {
+	case LowPri:
+		w.Printf("LowPri")
+	case NormalPri:
+		w.Printf("NormalPri")
+	case AboveNormalPri:
+		w.Printf("AboveNormalPri")
+	case HighPri:
+		w.Printf("HighPri")
+	default:
+		panic("invalid raft priority")
+	}
+}