Documentation
¶
Overview ¶
Package raftplacement validates the first TreeDB multi-group placement catalog shapes and resolves explicit route requests to Raft group decisions or token partitions through explicit helper APIs.
This package is deliberately pure catalog validation, simulation, and route-decision logic. It does not submit routed requests, start Raft groups, expose submitter APIs, choose leaders, maintain a meta Raft group, rebalance data, or provide native-wire/Mongo server routing.
Index ¶
- Constants
- Variables
- func DefaultFeatureSet() raftcluster.FeatureSet
- func DocumentIDTokenV1(documentID []byte) uint64
- type CatalogV1
- type CollectionPlacementV1
- type CollectionRefV1
- type GroupV1
- type PlacementModeV1
- type ResolvedCatalogV1
- func (c ResolvedCatalogV1) ClassifyDocumentTokenBatch(database, catalog, collection string, tokens []uint64) (RouteTokenBatchDecisionV1, error)
- func (c ResolvedCatalogV1) Group(id raftcluster.GroupID) (ResolvedGroupV1, bool)
- func (c ResolvedCatalogV1) Placement(ref CollectionRefV1) (ResolvedCollectionPlacementV1, bool)
- func (c ResolvedCatalogV1) Resolve(ref CollectionRefV1) (raftcluster.GroupID, error)
- func (c ResolvedCatalogV1) ResolveCollection(database, catalog, collection string) (raftcluster.GroupID, error)
- func (c ResolvedCatalogV1) ResolveCollectionToken(database, catalog, collection string, token uint64) (ResolvedTokenPartitionV1, error)
- func (c ResolvedCatalogV1) ResolveToken(ref CollectionRefV1, token uint64) (ResolvedTokenPartitionV1, error)
- func (c ResolvedCatalogV1) Route(req RouteRequestV1) (RouteDecisionV1, error)
- func (c ResolvedCatalogV1) RouteCollection(database, catalog, collection string) (RouteDecisionV1, error)
- func (c ResolvedCatalogV1) RouteDocumentID(database, catalog, collection string, documentID []byte) (RouteDecisionV1, error)
- func (c ResolvedCatalogV1) RouteDocumentToken(database, catalog, collection string, token uint64) (RouteDecisionV1, error)
- func (c ResolvedCatalogV1) RouteToken(database, catalog, collection string, token uint64) (RouteDecisionV1, error)
- func (c ResolvedCatalogV1) TokenPlacement(ref CollectionRefV1) (ResolvedTokenRingPlanV1, bool)
- type ResolvedCollectionPlacementV1
- type ResolvedGroupV1
- type ResolvedTokenPartitionV1
- type ResolvedTokenRingPlanV1
- type RouteDecisionV1
- type RouteRequestV1
- type RouteShapeV1
- type RouteTokenBatchDecisionV1
- type RouteTokenDecisionV1
- type TokenBatchRouteClassV1
- type TokenPartitionID
- type TokenPartitionV1
- type TokenRingPlanOptions
- type TokenRingPlanV1
Constants ¶
const ( FeatureCollectionGroups raftcluster.FeatureName = "treedb.raftplacement.collection_groups" DefaultDatabase = "default" DefaultCatalog = "default" )
Variables ¶
var ( SupportedCatalogVersion = raftcluster.Version{Major: 1, Minor: 0} SupportedFeatureFloors = map[raftcluster.FeatureName]raftcluster.Version{ FeatureCollectionGroups: {Major: 1, Minor: 0}, } ErrInvalidCatalog = errors.New("raftplacement: invalid catalog") ErrMissingGroup = errors.New("raftplacement: missing group") ErrDuplicateGroup = errors.New("raftplacement: duplicate group") ErrMissingMember = errors.New("raftplacement: missing member") ErrDuplicateMember = errors.New("raftplacement: duplicate member") ErrLeaderHintNotMember = errors.New("raftplacement: leader hint not member") ErrUnknownGroup = errors.New("raftplacement: unknown group") ErrInvalidCollection = errors.New("raftplacement: invalid collection") ErrDuplicatePlacement = errors.New("raftplacement: duplicate placement") ErrUnplacedCollection = errors.New("raftplacement: unplaced collection") ErrUnsupportedFeature = errors.New("raftplacement: unsupported feature") ErrUnsupportedVersion = errors.New("raftplacement: unsupported version") ErrUnsupportedPlacementMode = errors.New("raftplacement: unsupported placement mode") )
var ( ErrInvalidTokenRing = errors.New("raftplacement: invalid token ring") ErrInvalidTokenPartitionCount = errors.New("raftplacement: invalid token partition count") ErrMissingTokenPartition = errors.New("raftplacement: missing token partition") ErrInvalidTokenPartition = errors.New("raftplacement: invalid token partition") ErrDuplicateTokenPartition = errors.New("raftplacement: duplicate token partition") ErrInvalidTokenRange = errors.New("raftplacement: invalid token range") ErrTokenRangeGap = errors.New("raftplacement: token range gap") ErrTokenRangeOverlap = errors.New("raftplacement: token range overlap") ErrTokenRingNotFull = errors.New("raftplacement: token ring not full") ErrTokenUnassigned = errors.New("raftplacement: token unassigned") )
Functions ¶
func DefaultFeatureSet ¶
func DefaultFeatureSet() raftcluster.FeatureSet
func DocumentIDTokenV1 ¶
DocumentIDTokenV1 maps a deterministic document ID byte identity to the v1 uint64 token space. The rule is stable across processes and platforms.
Types ¶
type CatalogV1 ¶
type CatalogV1 struct {
Features raftcluster.FeatureSet
Groups []GroupV1
Placements []CollectionPlacementV1
}
type CollectionPlacementV1 ¶
type CollectionPlacementV1 struct {
Collection CollectionRefV1
GroupID raftcluster.GroupID
Mode PlacementModeV1
TokenPartitions []TokenPartitionV1
}
type CollectionRefV1 ¶
type GroupV1 ¶
type GroupV1 struct {
ID raftcluster.GroupID
Members []raftcluster.NodeID
LeaderHint raftcluster.NodeID
}
type PlacementModeV1 ¶
type PlacementModeV1 string
const ( PlacementModeCollectionV1 PlacementModeV1 = "collection" PlacementModeTokenV1 PlacementModeV1 = "token" PlacementModeRingV1 PlacementModeV1 = "ring" )
type ResolvedCatalogV1 ¶
type ResolvedCatalogV1 struct {
Features raftcluster.FeatureSet
Groups []ResolvedGroupV1
Placements []ResolvedCollectionPlacementV1
// contains filtered or unexported fields
}
func Validate ¶
func Validate(c CatalogV1) (ResolvedCatalogV1, error)
func (ResolvedCatalogV1) ClassifyDocumentTokenBatch ¶
func (c ResolvedCatalogV1) ClassifyDocumentTokenBatch(database, catalog, collection string, tokens []uint64) (RouteTokenBatchDecisionV1, error)
func (ResolvedCatalogV1) Group ¶
func (c ResolvedCatalogV1) Group(id raftcluster.GroupID) (ResolvedGroupV1, bool)
func (ResolvedCatalogV1) Placement ¶
func (c ResolvedCatalogV1) Placement(ref CollectionRefV1) (ResolvedCollectionPlacementV1, bool)
func (ResolvedCatalogV1) Resolve ¶
func (c ResolvedCatalogV1) Resolve(ref CollectionRefV1) (raftcluster.GroupID, error)
func (ResolvedCatalogV1) ResolveCollection ¶
func (c ResolvedCatalogV1) ResolveCollection(database, catalog, collection string) (raftcluster.GroupID, error)
func (ResolvedCatalogV1) ResolveCollectionToken ¶
func (c ResolvedCatalogV1) ResolveCollectionToken(database, catalog, collection string, token uint64) (ResolvedTokenPartitionV1, error)
func (ResolvedCatalogV1) ResolveToken ¶
func (c ResolvedCatalogV1) ResolveToken(ref CollectionRefV1, token uint64) (ResolvedTokenPartitionV1, error)
func (ResolvedCatalogV1) Route ¶
func (c ResolvedCatalogV1) Route(req RouteRequestV1) (RouteDecisionV1, error)
func (ResolvedCatalogV1) RouteCollection ¶
func (c ResolvedCatalogV1) RouteCollection(database, catalog, collection string) (RouteDecisionV1, error)
func (ResolvedCatalogV1) RouteDocumentID ¶
func (c ResolvedCatalogV1) RouteDocumentID(database, catalog, collection string, documentID []byte) (RouteDecisionV1, error)
func (ResolvedCatalogV1) RouteDocumentToken ¶
func (c ResolvedCatalogV1) RouteDocumentToken(database, catalog, collection string, token uint64) (RouteDecisionV1, error)
func (ResolvedCatalogV1) RouteToken ¶
func (c ResolvedCatalogV1) RouteToken(database, catalog, collection string, token uint64) (RouteDecisionV1, error)
func (ResolvedCatalogV1) TokenPlacement ¶
func (c ResolvedCatalogV1) TokenPlacement(ref CollectionRefV1) (ResolvedTokenRingPlanV1, bool)
type ResolvedCollectionPlacementV1 ¶
type ResolvedCollectionPlacementV1 struct {
Collection CollectionRefV1
GroupID raftcluster.GroupID
Mode PlacementModeV1
TokenPartitions []ResolvedTokenPartitionV1
}
type ResolvedGroupV1 ¶
type ResolvedGroupV1 struct {
ID raftcluster.GroupID
Members []raftcluster.NodeID
LeaderHint raftcluster.NodeID
}
type ResolvedTokenPartitionV1 ¶
type ResolvedTokenPartitionV1 struct {
ID TokenPartitionID
GroupID raftcluster.GroupID
Start uint64
End uint64
}
type ResolvedTokenRingPlanV1 ¶
type ResolvedTokenRingPlanV1 struct {
Partitions []ResolvedTokenPartitionV1
// contains filtered or unexported fields
}
func PlanTokenRing ¶
func PlanTokenRing(c ResolvedCatalogV1, opts TokenRingPlanOptions) (ResolvedTokenRingPlanV1, error)
PlanTokenRing builds a deterministic simulation-only token ring over the full uint64 token space. It does not attach the plan to a catalog or enable token/ring production request routing.
func ValidateTokenRingPlan ¶
func ValidateTokenRingPlan(c ResolvedCatalogV1, plan TokenRingPlanV1) (ResolvedTokenRingPlanV1, error)
func (ResolvedTokenRingPlanV1) GroupPartitionCounts ¶
func (p ResolvedTokenRingPlanV1) GroupPartitionCounts() map[raftcluster.GroupID]int
func (ResolvedTokenRingPlanV1) ResolveToken ¶
func (p ResolvedTokenRingPlanV1) ResolveToken(token uint64) (ResolvedTokenPartitionV1, error)
type RouteDecisionV1 ¶
type RouteDecisionV1 struct {
Collection CollectionRefV1
Shape RouteShapeV1
PlacementMode PlacementModeV1
Group ResolvedGroupV1
Token RouteTokenDecisionV1
}
func (RouteDecisionV1) GroupID ¶
func (d RouteDecisionV1) GroupID() raftcluster.GroupID
func (RouteDecisionV1) LeaderHint ¶
func (d RouteDecisionV1) LeaderHint() raftcluster.NodeID
type RouteRequestV1 ¶
type RouteRequestV1 struct {
Collection CollectionRefV1
Shape RouteShapeV1
Token *uint64
}
type RouteShapeV1 ¶
type RouteShapeV1 string
const ( RouteShapeCollectionV1 RouteShapeV1 = "collection" RouteShapeTokenV1 RouteShapeV1 = "token" RouteShapeQueryV1 RouteShapeV1 = "query" RouteShapeScatterGatherV1 RouteShapeV1 = "scatter_gather" )
type RouteTokenBatchDecisionV1 ¶
type RouteTokenBatchDecisionV1 struct {
Collection CollectionRefV1
PlacementMode PlacementModeV1
Class TokenBatchRouteClassV1
Tokens []uint64
Partitions []ResolvedTokenPartitionV1
Group ResolvedGroupV1
Groups []ResolvedGroupV1
}
func (RouteTokenBatchDecisionV1) FanoutRequired ¶
func (d RouteTokenBatchDecisionV1) FanoutRequired() bool
func (RouteTokenBatchDecisionV1) GroupID ¶
func (d RouteTokenBatchDecisionV1) GroupID() raftcluster.GroupID
func (RouteTokenBatchDecisionV1) LeaderHint ¶
func (d RouteTokenBatchDecisionV1) LeaderHint() raftcluster.NodeID
type RouteTokenDecisionV1 ¶
type RouteTokenDecisionV1 struct {
Present bool
Token uint64
Partition ResolvedTokenPartitionV1
}
type TokenBatchRouteClassV1 ¶
type TokenBatchRouteClassV1 string
const ( TokenBatchRouteSingleTokenV1 TokenBatchRouteClassV1 = "single_token" TokenBatchRouteSamePartitionV1 TokenBatchRouteClassV1 = "same_partition" TokenBatchRouteSameGroupV1 TokenBatchRouteClassV1 = "same_group_multi_partition" TokenBatchRouteFanoutRequiredV1 TokenBatchRouteClassV1 = "fanout_required" )
type TokenPartitionID ¶
type TokenPartitionID string
type TokenPartitionV1 ¶
type TokenPartitionV1 struct {
ID TokenPartitionID
GroupID raftcluster.GroupID
Start uint64
End uint64
}
type TokenRingPlanOptions ¶
type TokenRingPlanOptions struct {
PartitionCount int
}
type TokenRingPlanV1 ¶
type TokenRingPlanV1 struct {
Partitions []TokenPartitionV1
}