rac2: introduce range controller interface

Introduce the `RangeController` interface, which provides flow control
for replication traffic in KV, for a range.

Resolves: cockroachdb#128021
Release note: None

pkg/kv/kvserver/kvflowcontrol/rac2/BUILD.bazel

@@ -3,13 +3,15 @@ load("@io_bazel_rules_go//go:def.bzl", "go_library")
 go_library(
     name = "rac2",
     srcs = [
+        "range_controller.go",
         "store_stream.go",
         "token_counter.go",
     ],
     importpath = "github.com/cockroachdb/cockroach/pkg/kv/kvserver/kvflowcontrol/rac2",
     visibility = ["//visibility:public"],
     deps = [
         "//pkg/kv/kvserver/kvflowcontrol",
+        "//pkg/roachpb",
         "//pkg/util/admission/admissionpb",
     ],
 )

pkg/kv/kvserver/kvflowcontrol/rac2/range_controller.go

@@ -0,0 +1,56 @@
+// Copyright 2024 The Cockroach Authors.
+//
+// Use of this software is governed by the Business Source License
+// included in the file licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with
+// the Business Source License, use of this software will be governed
+// by the Apache License, Version 2.0, included in the file
+// licenses/APL.txt.
+
+package rac2
+
+import (
+	"context"
+
+	"github.com/cockroachdb/cockroach/pkg/roachpb"
+	"github.com/cockroachdb/cockroach/pkg/util/admission/admissionpb"
+)
+
+// RangeController provides flow control for replication traffic in KV, for a
+// range at the leader.
+type RangeController interface {
+	// WaitForEval seeks admission to evaluate a request at the given priority.
+	// This blocks until there are positive tokens available for the request to
+	// be admitted for evaluation. Note the number of tokens required by the
+	// request is not considered, only the priority of the request, as the number
+	// of tokens is not known until eval.
+	//
+	// No mutexes should be held.
+	WaitForEval(ctx context.Context, pri admissionpb.WorkPriority) error
+	// HandleRaftEventRaftMuLocked handles the provided raft event for the range.
+	//
+	// Requires replica.raftMu to be held.
+	HandleRaftEventRaftMuLocked(ctx context.Context, e RaftEvent) error
+	// HandleSchedulerEventRaftMuLocked processes an event scheduled by the
+	// controller.
+	//
+	// Requires replica.raftMu to be held.
+	HandleSchedulerEventRaftMuLocked(ctx context.Context) error
+	// SetReplicasLocked sets the replicas of the range.
+	//
+	// Requires replica.raftMu and replica.mu to be held.
+	SetReplicasLocked(ctx context.Context, replicas roachpb.ReplicaSet) error
+	// SetLeaseholderRaftMuLocked sets the leaseholder of the range.
+	//
+	// Requires raftMu to be held.
+	SetLeaseholderRaftMuLocked(ctx context.Context, replica roachpb.ReplicaID)
+	// CloseRaftMuLocked closes the range controller.
+	//
+	// Requires replica.raftMu to be held.
+	CloseRaftMuLocked(ctx context.Context)
+}
+
+// TODO(pav-kv): This struct is a placeholder for the interface or struct
+// containing raft entries. Replace this as part of #128019.
+type RaftEvent struct{}