raftplacement

package
v0.6.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 1, 2026 License: MIT Imports: 9 Imported by: 0

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

View Source
const (
	FeatureCollectionGroups raftcluster.FeatureName = "treedb.raftplacement.collection_groups"

	DefaultDatabase = "default"
	DefaultCatalog  = "default"
)

Variables

View Source
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")
)
View Source
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")
)
View Source
var (
	ErrInvalidRouteRequest   = errors.New("raftplacement: invalid route request")
	ErrUnsupportedRouteShape = errors.New("raftplacement: unsupported route shape")
	ErrMissingRouteToken     = errors.New("raftplacement: missing route token")
)

Functions

func DefaultFeatureSet

func DefaultFeatureSet() raftcluster.FeatureSet

func DocumentIDTokenV1

func DocumentIDTokenV1(documentID []byte) uint64

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 CollectionRefV1 struct {
	Database   string
	Catalog    string
	Collection string
}

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 (ResolvedCatalogV1) Placement

func (ResolvedCatalogV1) Resolve

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 (ResolvedCatalogV1) Route

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

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

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 (ResolvedTokenRingPlanV1) GroupPartitionCounts

func (p ResolvedTokenRingPlanV1) GroupPartitionCounts() map[raftcluster.GroupID]int

func (ResolvedTokenRingPlanV1) ResolveToken

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 (RouteTokenBatchDecisionV1) LeaderHint

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
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL