http

type AffinityGroup struct {
	ID              string   `json:"id"`
	CreateTimestamp uint64   `json:"create_timestamp"`
	LeaderStoreID   uint64   `json:"leader_store_id,omitempty"`
	VoterStoreIDs   []uint64 `json:"voter_store_ids,omitempty"`
}

type AffinityGroupKeyRange struct {
	StartKey []byte `json:"start_key"`
	EndKey   []byte `json:"end_key"`
}

type AffinityGroupState struct {
	AffinityGroup
	Phase               string `json:"phase"`
	RangeCount          int    `json:"range_count"`
	RegionCount         int    `json:"region_count"`
	AffinityRegionCount int    `json:"affinity_region_count"`
}

type AffinityGroupsResponse struct {
	AffinityGroups map[string]*AffinityGroupState `json:"affinity_groups"`
}

type BatchDeleteAffinityGroupsRequest struct {
	IDs   []string `json:"ids"`
	Force bool     `json:"force,omitempty"`
}

type BatchModifyAffinityGroupsRequest struct {
	Add    []GroupRangesModification `json:"add,omitempty"`
	Remove []GroupRangesModification `json:"remove,omitempty"`
}

type Client interface {
	/* Member-related interfaces */
	GetMembers(context.Context) (*MembersInfo, error)
	GetLeader(context.Context) (*pdpb.Member, error)
	TransferLeader(context.Context, string) error
	/* Meta-related interfaces */
	GetRegionByID(context.Context, uint64) (*RegionInfo, error)
	GetRegionByKey(context.Context, []byte) (*RegionInfo, error)
	GetRegions(context.Context) (*RegionsInfo, error)
	GetRegionsByKeyRange(context.Context, *KeyRange, int) (*RegionsInfo, error)
	GetRegionsByStoreID(context.Context, uint64) (*RegionsInfo, error)
	GetEmptyRegions(context.Context) (*RegionsInfo, error)
	GetRegionsReplicatedStateByKeyRange(context.Context, *KeyRange) (string, error)
	GetRegionSiblingsByID(context.Context, uint64) (*RegionsInfo, error)
	GetHotReadRegions(context.Context) (*StoreHotPeersInfos, error)
	GetHotWriteRegions(context.Context) (*StoreHotPeersInfos, error)
	GetHistoryHotRegions(context.Context, *HistoryHotRegionsRequest) (*HistoryHotRegions, error)
	GetRegionStatusByKeyRange(context.Context, *KeyRange, bool) (*RegionStats, error)
	GetRegionDistributionByKeyRange(ctx context.Context, keyRange *KeyRange, engine string) (*RegionDistributions, error)
	GetStores(context.Context) (*StoresInfo, error)
	GetStore(context.Context, uint64) (*StoreInfo, error)
	DeleteStore(context.Context, uint64) error
	SetStoreLabels(context.Context, int64, map[string]string) error
	DeleteStoreLabel(ctx context.Context, storeID int64, labelKey string) error
	GetHealthStatus(context.Context) ([]Health, error)
	/* Config-related interfaces */
	GetConfig(context.Context) (map[string]any, error)
	SetConfig(context.Context, map[string]any, ...float64) error
	GetScheduleConfig(context.Context) (map[string]any, error)
	SetScheduleConfig(context.Context, map[string]any) error
	GetClusterVersion(context.Context) (string, error)
	GetCluster(context.Context) (*metapb.Cluster, error)
	GetClusterStatus(context.Context) (*ClusterState, error)
	GetStatus(context.Context) (*State, error)
	GetReplicateConfig(context.Context) (map[string]any, error)
	/* Scheduler-related interfaces */
	GetSchedulers(context.Context) ([]string, error)
	CreateScheduler(ctx context.Context, name string, storeID uint64) error
	CreateSchedulerWithInput(ctx context.Context, name string, input map[string]any) error
	CancelSchedulerJob(ctx context.Context, name string, jobID uint64) error
	DeleteScheduler(ctx context.Context, name string) error
	SetSchedulerDelay(context.Context, string, int64) error
	GetSchedulerConfig(ctx context.Context, name string) (any, error)
	/* Rule-related interfaces */
	GetAllPlacementRuleBundles(context.Context) ([]*GroupBundle, error)
	GetPlacementRuleBundleByGroup(context.Context, string) (*GroupBundle, error)
	GetPlacementRulesByGroup(context.Context, string) ([]*Rule, error)
	GetPlacementRule(context.Context, string, string) (*Rule, error)
	SetPlacementRule(context.Context, *Rule) error
	SetPlacementRuleInBatch(context.Context, []*RuleOp) error
	SetPlacementRuleBundles(context.Context, []*GroupBundle, bool) error
	DeletePlacementRule(context.Context, string, string) error
	GetAllPlacementRuleGroups(context.Context) ([]*RuleGroup, error)
	GetPlacementRuleGroupByID(context.Context, string) (*RuleGroup, error)
	SetPlacementRuleGroup(context.Context, *RuleGroup) error
	DeletePlacementRuleGroupByID(context.Context, string) error
	GetAllRegionLabelRules(context.Context) ([]*LabelRule, error)
	GetRegionLabelRulesByIDs(context.Context, []string) ([]*LabelRule, error)
	// `SetRegionLabelRule` sets the label rule for a region.
	// When a label rule (deny scheduler) is set,
	//  1. All schedulers will be disabled except for the evict-leader-scheduler.
	//  2. The merge-checker will be disabled, preventing these regions from being merged.
	SetRegionLabelRule(context.Context, *LabelRule) error
	PatchRegionLabelRules(context.Context, *LabelRulePatch) error
	/* Scheduling-related interfaces */
	AccelerateSchedule(context.Context, *KeyRange) error
	AccelerateScheduleInBatch(context.Context, []*KeyRange) error
	/* Admin-related interfaces */
	ResetTS(context.Context, uint64, bool) error
	ResetBaseAllocID(context.Context, uint64) error
	SetSnapshotRecoveringMark(context.Context) error
	DeleteSnapshotRecoveringMark(context.Context) error
	SetPitrRestoreModeMark(context.Context) error
	DeletePitrRestoreModeMark(context.Context) error
	/* Other interfaces */
	GetMinResolvedTSByStoresIDs(context.Context, []uint64) (uint64, map[uint64]uint64, error)
	GetPDVersion(context.Context) (string, error)
	GetGCSafePoint(context.Context) (ListServiceGCSafepoint, error)
	DeleteGCSafePoint(context.Context, string) (string, error)
	/* Microservice interfaces */
	GetMicroserviceMembers(context.Context, string) ([]MicroserviceMember, error)
	GetMicroservicePrimary(context.Context, string) (string, error)
	CreateOperators(context.Context, map[string]any) error
	DeleteOperators(context.Context) error

	// UpdateKeyspaceGCManagementType update the `gc_management_type` in keyspace meta config.
	// If `gc_management_type` is `global_gc`, it means the current keyspace requires a tidb without 'keyspace-name'
	// configured to run a global gc worker to calculate a global gc safe point.
	// If `gc_management_type` is `keyspace_level_gc` it means the current keyspace can calculate gc safe point by its own.
	UpdateKeyspaceGCManagementType(ctx context.Context, keyspaceName string, keyspaceGCManagementType *KeyspaceGCManagementTypeConfig) error
	GetKeyspaceMetaByName(ctx context.Context, keyspaceName string) (*keyspacepb.KeyspaceMeta, error)
	GetKeyspaceMetaByID(ctx context.Context, keyspaceID uint32) (*keyspacepb.KeyspaceMeta, error)

	// CreateAffinityGroups creates one or more affinity groups with key ranges.
	// The affinityGroups parameter is a map from group ID to a list of key ranges.
	CreateAffinityGroups(ctx context.Context, affinityGroups map[string][]AffinityGroupKeyRange) (map[string]*AffinityGroupState, error)
	// GetAffinityGroup gets an affinity group by group ID.
	GetAffinityGroup(ctx context.Context, groupID string) (*AffinityGroupState, error)
	// GetAllAffinityGroups gets all affinity groups.
	GetAllAffinityGroups(ctx context.Context) (map[string]*AffinityGroupState, error)
	// UpdateAffinityGroupPeers updates the leader and voter stores of an affinity group.
	UpdateAffinityGroupPeers(ctx context.Context, groupID string, leaderStoreID uint64, voterStoreIDs []uint64) (*AffinityGroupState, error)
	// DeleteAffinityGroup deletes an affinity group by group ID.
	DeleteAffinityGroup(ctx context.Context, groupID string, force bool) error
	// BatchDeleteAffinityGroups deletes multiple affinity groups in batch.
	BatchDeleteAffinityGroups(ctx context.Context, groupIDs []string, force bool) error
	// AddAffinityGroupKeyRanges adds key ranges to affinity groups.
	AddAffinityGroupKeyRanges(ctx context.Context, groupKeyRanges map[string][]AffinityGroupKeyRange) (map[string]*AffinityGroupState, error)
	// RemoveAffinityGroupKeyRanges removes key ranges from affinity groups.
	RemoveAffinityGroupKeyRanges(ctx context.Context, groupKeyRanges map[string][]AffinityGroupKeyRange) (map[string]*AffinityGroupState, error)

	/* Client-related methods */
	// WithCallerID sets and returns a new client with the given caller ID.
	WithCallerID(string) Client
	// WithRespHandler sets and returns a new client with the given HTTP response handler.
	// This allows the caller to customize how the response is handled, including error handling logic.
	// Additionally, it is important for the caller to handle the content of the response body properly
	// in order to ensure that it can be read and marshaled correctly into `res`.
	WithRespHandler(func(resp *http.Response, res any) error) Client
	// WithBackoffer sets and returns a new client with the given backoffer.
	WithBackoffer(*retry.Backoffer) Client
	// WithTargetURL sets and returns a new client with the given target URL.
	WithTargetURL(string) Client
	// Close gracefully closes the HTTP client.
	Close()
}

type ClientOption func(c *client)

type ClusterState struct {
	RaftBootstrapTime time.Time `json:"raft_bootstrap_time,omitempty"`
	IsInitialized     bool      `json:"is_initialized"`
	ReplicationStatus string    `json:"replication_status"`
}

type CreateAffinityGroupInput struct {
	Ranges []AffinityGroupKeyRange `json:"ranges"`
}

type CreateAffinityGroupsRequest struct {
	AffinityGroups map[string]CreateAffinityGroupInput `json:"affinity_groups"`
}

type GroupBundle struct {
	ID       string  `json:"group_id"`
	Index    int     `json:"group_index"`
	Override bool    `json:"group_override"`
	Rules    []*Rule `json:"rules"`
}

type GroupRangesModification struct {
	ID     string                  `json:"id"`
	Ranges []AffinityGroupKeyRange `json:"ranges"`
}

type HeaderOption func(header http.Header)

type Health struct {
	Name       string   `json:"name"`
	MemberID   uint64   `json:"member_id"`
	ClientUrls []string `json:"client_urls"`
	Health     bool     `json:"health"`
}

type HistoryHotRegion struct {
	UpdateTime    int64   `json:"update_time"`
	RegionID      uint64  `json:"region_id"`
	PeerID        uint64  `json:"peer_id"`
	StoreID       uint64  `json:"store_id"`
	IsLeader      bool    `json:"is_leader"`
	IsLearner     bool    `json:"is_learner"`
	HotRegionType string  `json:"hot_region_type"`
	HotDegree     int64   `json:"hot_degree"`
	FlowBytes     float64 `json:"flow_bytes"`
	KeyRate       float64 `json:"key_rate"`
	QueryRate     float64 `json:"query_rate"`
	StartKey      string  `json:"start_key"`
	EndKey        string  `json:"end_key"`
	// Encryption metadata for start_key and end_key. encryption_meta.iv is IV for start_key.
	// IV for end_key is calculated from (encryption_meta.iv + len(start_key)).
	// The field is only used by PD and should be ignored otherwise.
	// If encryption_meta is empty (i.e. nil), it means start_key and end_key are unencrypted.
	EncryptionMeta *encryptionpb.EncryptionMeta `json:"encryption_meta,omitempty"`
}

type HistoryHotRegions struct {
	HistoryHotRegion []*HistoryHotRegion `json:"history_hot_region"`
}

type HistoryHotRegionsRequest struct {
	StartTime      int64    `json:"start_time,omitempty"`
	EndTime        int64    `json:"end_time,omitempty"`
	RegionIDs      []uint64 `json:"region_ids,omitempty"`
	StoreIDs       []uint64 `json:"store_ids,omitempty"`
	PeerIDs        []uint64 `json:"peer_ids,omitempty"`
	IsLearners     []bool   `json:"is_learners,omitempty"`
	IsLeaders      []bool   `json:"is_leaders,omitempty"`
	HotRegionTypes []string `json:"hot_region_type,omitempty"`
}

type HotPeerStatShow struct {
	StoreID        uint64    `json:"store_id"`
	Stores         []uint64  `json:"stores"`
	IsLeader       bool      `json:"is_leader"`
	IsLearner      bool      `json:"is_learner"`
	RegionID       uint64    `json:"region_id"`
	HotDegree      int       `json:"hot_degree"`
	ByteRate       float64   `json:"flow_bytes"`
	KeyRate        float64   `json:"flow_keys"`
	QueryRate      float64   `json:"flow_query"`
	AntiCount      int       `json:"anti_count"`
	LastUpdateTime time.Time `json:"last_update_time,omitempty"`
}

type HotPeersStat struct {
	StoreByteRate  float64           `json:"store_bytes"`
	StoreKeyRate   float64           `json:"store_keys"`
	StoreQueryRate float64           `json:"store_query"`
	TotalBytesRate float64           `json:"total_flow_bytes"`
	TotalKeysRate  float64           `json:"total_flow_keys"`
	TotalQueryRate float64           `json:"total_flow_query"`
	Count          int               `json:"regions_count"`
	Stats          []HotPeerStatShow `json:"statistics"`
}

type KeyRange = pd.KeyRange

type KeyspaceGCManagementType struct {
	GCManagementType string `json:"gc_management_type,omitempty"`
}

type KeyspaceGCManagementTypeConfig struct {
	Config KeyspaceGCManagementType `json:"config"`
}

type LabelConstraint struct {
	Key    string            `json:"key,omitempty"`
	Op     LabelConstraintOp `json:"op,omitempty"`
	Values []string          `json:"values,omitempty"`
}

type LabelConstraintOp string

type LabelRule struct {
	ID       string        `json:"id"`
	Index    int           `json:"index"`
	Labels   []RegionLabel `json:"labels"`
	RuleType string        `json:"rule_type"`
	Data     any           `json:"data"`
}

type LabelRulePatch struct {
	SetRules    []*LabelRule `json:"sets"`
	DeleteRules []string     `json:"deletes"`
}

type ListServiceGCSafepoint struct {
	ServiceGCSafepoints   []*ServiceSafePoint `json:"service_gc_safe_points"`
	MinServiceGcSafepoint uint64              `json:"min_service_gc_safe_point,omitempty"`
	GCSafePoint           uint64              `json:"gc_safe_point"`
}

type MembersInfo struct {
	Header     *pdpb.ResponseHeader `json:"header,omitempty"`
	Members    []*pdpb.Member       `json:"members,omitempty"`
	Leader     *pdpb.Member         `json:"leader,omitempty"`
	EtcdLeader *pdpb.Member         `json:"etcd_leader,omitempty"`
}

type MetaStore struct {
	ID             int64        `json:"id"`
	Address        string       `json:"address"`
	State          int64        `json:"state"`
	StateName      string       `json:"state_name"`
	Version        string       `json:"version"`
	Labels         []StoreLabel `json:"labels"`
	StatusAddress  string       `json:"status_address"`
	GitHash        string       `json:"git_hash"`
	StartTimestamp int64        `json:"start_timestamp"`
}

type MicroserviceMember struct {
	ServiceAddr    string `json:"service-addr"`
	Version        string `json:"version"`
	GitHash        string `json:"git-hash"`
	DeployPath     string `json:"deploy-path"`
	StartTimestamp int64  `json:"start-timestamp"`
}

type PeerRoleType string

type RegionDistribution struct {
	StoreID           uint64 `json:"store_id"`
	EngineType        string `json:"engine_type"`
	RegionLeaderCount int    `json:"region_leader_count"`
	RegionPeerCount   int    `json:"region_peer_count"`
	ApproximateSize   int64  `json:"approximate_size"`
	ApproximateKeys   int64  `json:"approximate_keys"`
	// write
	RegionWriteBytes uint64 `json:"region_write_bytes"`
	RegionWriteKeys  uint64 `json:"region_write_keys"`
	RegionWriteQuery uint64 `json:"region_write_query"`
	// leader read
	RegionLeaderReadBytes uint64 `json:"region_leader_read_bytes"`
	RegionLeaderReadKeys  uint64 `json:"region_leader_read_keys"`
	RegionLeaderReadQuery uint64 `json:"region_leader_read_query"`
	// peer read
	RegionPeerReadBytes uint64 `json:"region_peer_read_bytes"`
	RegionPeerReadKeys  uint64 `json:"region_peer_read_keys"`
	RegionPeerReadQuery uint64 `json:"region_peer_read_query"`
}

type RegionDistributions struct {
	RegionDistributions []*RegionDistribution `json:"region_distribution"`
}

type RegionEpoch struct {
	ConfVer int64 `json:"conf_ver"`
	Version int64 `json:"version"`
}

type RegionInfo struct {
	ID              int64            `json:"id"`
	StartKey        string           `json:"start_key"`
	EndKey          string           `json:"end_key"`
	Epoch           RegionEpoch      `json:"epoch"`
	Peers           []RegionPeer     `json:"peers"`
	Leader          RegionPeer       `json:"leader"`
	DownPeers       []RegionPeerStat `json:"down_peers"`
	PendingPeers    []RegionPeer     `json:"pending_peers"`
	WrittenBytes    uint64           `json:"written_bytes"`
	ReadBytes       uint64           `json:"read_bytes"`
	WrittenKeys     uint64           `json:"written_keys"`
	ReadKeys        uint64           `json:"read_keys"`
	ApproximateSize int64            `json:"approximate_size"`
	ApproximateKeys int64            `json:"approximate_keys"`

	ReplicationStatus *ReplicationStatus `json:"replication_status,omitempty"`
}

type RegionLabel struct {
	Key     string `json:"key"`
	Value   string `json:"value"`
	TTL     string `json:"ttl,omitempty"`
	StartAt string `json:"start_at,omitempty"`
}

type RegionPeer struct {
	ID        int64 `json:"id"`
	StoreID   int64 `json:"store_id"`
	IsLearner bool  `json:"is_learner"`
}

type RegionPeerStat struct {
	Peer    RegionPeer `json:"peer"`
	DownSec int64      `json:"down_seconds"`
}

type RegionStats struct {
	Count                int               `json:"count"`
	EmptyCount           int               `json:"empty_count"`
	StorageSize          int64             `json:"storage_size"`
	StorageKeys          int64             `json:"storage_keys"`
	StoreLeaderCount     map[uint64]int    `json:"store_leader_count"`
	StorePeerCount       map[uint64]int    `json:"store_peer_count"`
	StorePeerSize        map[uint64]int64  `json:"store_peer_size,omitempty"`
	StorePeerKeys        map[uint64]int64  `json:"store_peer_keys,omitempty"`
	StoreWriteBytes      map[uint64]uint64 `json:"store_write_bytes,omitempty"`
	StoreWriteKeys       map[uint64]uint64 `json:"store_write_keys,omitempty"`
	StoreWriteQuery      map[uint64]uint64 `json:"store_write_query,omitempty"`
	StoreLeaderReadBytes map[uint64]uint64 `json:"store_leader_read_bytes,omitempty"`
	StoreLeaderReadKeys  map[uint64]uint64 `json:"store_leader_read_keys,omitempty"`
	StoreLeaderReadQuery map[uint64]uint64 `json:"store_leader_read_query,omitempty"`
	StorePeerReadBytes   map[uint64]uint64 `json:"store_peer_read_bytes,omitempty"`
	StorePeerReadKeys    map[uint64]uint64 `json:"store_peer_read_keys,omitempty"`
	StorePeerReadQuery   map[uint64]uint64 `json:"store_peer_read_query,omitempty"`
	StoreEngine          map[uint64]string `json:"store_engine,omitempty"`
}

type RegionsInfo struct {
	Count   int64        `json:"count"`
	Regions []RegionInfo `json:"regions"`
}

type ReplicationStatus struct {
	State   string `json:"state"`
	StateID int64  `json:"state_id"`
}

type Rule struct {
	GroupID          string            `json:"group_id"`                    // mark the source that add the rule
	ID               string            `json:"id"`                          // unique ID within a group
	Index            int               `json:"index,omitempty"`             // rule apply order in a group, rule with less ID is applied first when indexes are equal
	Override         bool              `json:"override,omitempty"`          // when it is true, all rules with less indexes are disabled
	StartKey         []byte            `json:"-"`                           // range start key
	StartKeyHex      string            `json:"start_key"`                   // hex format start key, for marshal/unmarshal
	EndKey           []byte            `json:"-"`                           // range end key
	EndKeyHex        string            `json:"end_key"`                     // hex format end key, for marshal/unmarshal
	Role             PeerRoleType      `json:"role"`                        // expected role of the peers
	IsWitness        bool              `json:"is_witness"`                  // when it is true, it means the role is also a witness
	Count            int               `json:"count"`                       // expected count of the peers
	LabelConstraints []LabelConstraint `json:"label_constraints,omitempty"` // used to select stores to place peers
	LocationLabels   []string          `json:"location_labels,omitempty"`   // used to make peers isolated physically
	IsolationLevel   string            `json:"isolation_level,omitempty"`   // used to isolate replicas explicitly and forcibly
	Version          uint64            `json:"version,omitempty"`           // only set at runtime, add 1 each time rules updated, begin from 0.
	CreateTimestamp  uint64            `json:"create_timestamp,omitempty"`  // only set at runtime, recorded rule create timestamp
}

type RuleGroup struct {
	ID       string `json:"id,omitempty"`
	Index    int    `json:"index,omitempty"`
	Override bool   `json:"override,omitempty"`
}

type RuleOp struct {
	*Rule                       // information of the placement rule to add/delete the operation type
	Action           RuleOpType `json:"action"`
	DeleteByIDPrefix bool       `json:"delete_by_id_prefix"` // if action == delete, delete by the prefix of id
}

type RuleOpType string

type ServiceSafePoint struct {
	ServiceID string `json:"service_id"`
	ExpiredAt int64  `json:"expired_at"`
	SafePoint uint64 `json:"safe_point"`
}

type State struct {
	BuildTS        string `json:"build_ts"`
	Version        string `json:"version"`
	GitHash        string `json:"git_hash"`
	StartTimestamp int64  `json:"start_timestamp"`
	KernelType     string `json:"kernel_type"`
}

type StoreHotPeersInfos struct {
	AsPeer   StoreHotPeersStat `json:"as_peer"`
	AsLeader StoreHotPeersStat `json:"as_leader"`
}

type StoreHotPeersStat map[uint64]*HotPeersStat

type StoreInfo struct {
	Store  MetaStore   `json:"store"`
	Status StoreStatus `json:"status"`
}

type StoreLabel struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

type StoreStatus struct {
	Capacity        string    `json:"capacity"`
	Available       string    `json:"available"`
	LeaderCount     int64     `json:"leader_count"`
	LeaderWeight    float64   `json:"leader_weight"`
	LeaderScore     float64   `json:"leader_score"`
	LeaderSize      int64     `json:"leader_size"`
	RegionCount     int64     `json:"region_count"`
	RegionWeight    float64   `json:"region_weight"`
	RegionScore     float64   `json:"region_score"`
	RegionSize      int64     `json:"region_size"`
	StartTS         time.Time `json:"start_ts"`
	LastHeartbeatTS time.Time `json:"last_heartbeat_ts"`
	Uptime          string    `json:"uptime"`
}

type StoresInfo struct {
	Count  int         `json:"count"`
	Stores []StoreInfo `json:"stores"`
}

type UpdateAffinityGroupPeersRequest struct {
	LeaderStoreID uint64   `json:"leader_store_id"`
	VoterStoreIDs []uint64 `json:"voter_store_ids"`
}