snapshot of https://github.com/livekit/livekit.git @ 08c5433449c106943231037d0b892895f6e92d3b (2026-09-15)

pkg/routing/selector/any.go

@@ -0,0 +1,34 @@
+// Copyright 2023 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package selector
+
+import (
+	"github.com/livekit/protocol/livekit"
+)
+
+// AnySelector selects any available node with no limitations
+type AnySelector struct {
+	SortBy    string
+	Algorithm string
+}
+
+func (s *AnySelector) SelectNode(nodes []*livekit.Node) (*livekit.Node, error) {
+	nodes = GetAvailableNodes(nodes)
+	if len(nodes) == 0 {
+		return nil, ErrNoAvailableNodes
+	}
+
+	return SelectSortedNode(nodes, s.SortBy, s.Algorithm)
+}

pkg/routing/selector/any_test.go

@@ -0,0 +1,287 @@
+// Copyright 2023 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package selector
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/livekit/protocol/livekit"
+)
+
+func createTestNode(id string, cpuLoad float32, numRooms int32, numClients int32, state livekit.NodeState) *livekit.Node {
+	return &livekit.Node{
+		Id:    id,
+		State: state,
+		Stats: &livekit.NodeStats{
+			UpdatedAt:       time.Now().Unix() - 1, // Recent update to be considered available
+			CpuLoad:         cpuLoad,
+			NumRooms:        numRooms,
+			NumClients:      numClients,
+			NumCpus:         4,
+			LoadAvgLast1Min: cpuLoad * 4, // Simulate system load
+		},
+	}
+}
+
+func TestAnySelector_SelectNode_TwoChoice(t *testing.T) {
+	tests := []struct {
+		name        string
+		sortBy      string
+		algorithm   string
+		nodes       []*livekit.Node
+		wantErr     string
+		expected    string
+		notExpected string
+	}{
+		{
+			name:      "successful selection with cpuload sorting",
+			sortBy:    "cpuload",
+			algorithm: "twochoice",
+			nodes: []*livekit.Node{
+				createTestNode("node1", 0.8, 5, 10, livekit.NodeState_SERVING),
+				createTestNode("node2", 0.3, 2, 5, livekit.NodeState_SERVING),
+				createTestNode("node3", 0.6, 3, 8, livekit.NodeState_SERVING),
+				createTestNode("node4", 0.9, 6, 12, livekit.NodeState_SERVING),
+			},
+			wantErr:     "",
+			expected:    "",      // Not deterministic selection, so no specific expected node
+			notExpected: "node4", // Node with highest load should not be selected
+		},
+		{
+			name:      "successful selection with rooms sorting",
+			sortBy:    "rooms",
+			algorithm: "twochoice",
+			nodes: []*livekit.Node{
+				createTestNode("node1", 0.5, 8, 15, livekit.NodeState_SERVING),
+				createTestNode("node2", 0.4, 2, 5, livekit.NodeState_SERVING),
+				createTestNode("node3", 0.6, 12, 20, livekit.NodeState_SERVING),
+			},
+			wantErr:     "",
+			expected:    "",      // Not deterministic selection, so no specific expected node
+			notExpected: "node3", // Node with highest room count should not be selected
+		},
+		{
+			name:      "successful selection with clients sorting",
+			sortBy:    "clients",
+			algorithm: "twochoice",
+			nodes: []*livekit.Node{
+				createTestNode("node1", 0.5, 3, 25, livekit.NodeState_SERVING),
+				createTestNode("node2", 0.4, 2, 5, livekit.NodeState_SERVING),
+				createTestNode("node3", 0.6, 4, 30, livekit.NodeState_SERVING),
+			},
+			wantErr:     "",
+			expected:    "",      // Not deterministic selection, so no specific expected node
+			notExpected: "node3", // Node with highest clients should not be selected
+		},
+		{
+			name:      "empty nodes list",
+			sortBy:    "cpuload",
+			algorithm: "twochoice",
+			nodes:     []*livekit.Node{},
+			wantErr:   "could not find any available nodes",
+		},
+		{
+			name:      "no available nodes - all unavailable",
+			sortBy:    "cpuload",
+			algorithm: "twochoice",
+			nodes: []*livekit.Node{
+				{
+					Id:    "node1",
+					State: livekit.NodeState_SERVING,
+					Stats: &livekit.NodeStats{
+						UpdatedAt: time.Now().Unix() - 10, // Too old
+						CpuLoad:   0.3,
+					},
+				},
+			},
+			wantErr: "could not find any available nodes",
+		},
+		{
+			name:      "no available nodes - not serving",
+			sortBy:    "cpuload",
+			algorithm: "twochoice",
+			nodes: []*livekit.Node{
+				{
+					Id:    "node1",
+					State: livekit.NodeState_SHUTTING_DOWN,
+					Stats: &livekit.NodeStats{
+						UpdatedAt: time.Now().Unix() - 1,
+						CpuLoad:   0.3,
+					},
+				},
+			},
+			wantErr: "could not find any available nodes",
+		},
+		{
+			name:      "single available node",
+			sortBy:    "cpuload",
+			algorithm: "twochoice",
+			nodes: []*livekit.Node{
+				createTestNode("node1", 0.5, 3, 10, livekit.NodeState_SERVING),
+			},
+			wantErr:     "",
+			expected:    "node1", // Should select the only available node
+			notExpected: "",      // No other nodes to compare against
+		},
+		{
+			name:      "two available nodes",
+			sortBy:    "cpuload",
+			algorithm: "twochoice",
+			nodes: []*livekit.Node{
+				createTestNode("node1", 0.8, 5, 15, livekit.NodeState_SERVING),
+				createTestNode("node2", 0.3, 2, 5, livekit.NodeState_SERVING),
+			},
+			wantErr:     "",
+			expected:    "node2", // Should select the node with lower load
+			notExpected: "node1", // Should not select the node with higher load
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			selector := &AnySelector{
+				SortBy:    tt.sortBy,
+				Algorithm: tt.algorithm,
+			}
+
+			node, err := selector.SelectNode(tt.nodes)
+
+			if tt.wantErr != "" {
+				require.Error(t, err)
+				require.Contains(t, err.Error(), tt.wantErr)
+				require.Nil(t, node)
+			} else {
+				require.NoError(t, err)
+				require.NotNil(t, node)
+				require.NotEmpty(t, node.Id)
+
+				// Verify the selected node is one of the available nodes
+				found := false
+				availableNodes := GetAvailableNodes(tt.nodes)
+				for _, availableNode := range availableNodes {
+					if availableNode.Id == node.Id {
+						found = true
+						break
+					}
+				}
+				require.True(t, found, "Selected node should be one of the available nodes")
+
+				if tt.expected != "" {
+					require.Equal(t, tt.expected, node.Id, "Selected node should match expected")
+				}
+				if tt.notExpected != "" {
+					require.NotEqual(t, tt.notExpected, node.Id, "Selected node should not match not expected")
+				}
+			}
+		})
+	}
+}
+
+func TestAnySelector_SelectNode_TwoChoice_Probabilistic_Behavior(t *testing.T) {
+	// Test that two-choice algorithm favors nodes with lower metrics
+	// This test runs multiple iterations to increase confidence in the probabilistic behavior
+	selector := &AnySelector{
+		SortBy:    "cpuload",
+		Algorithm: "twochoice",
+	}
+
+	// Create nodes where node2 has significantly lower CPU load
+	nodes := []*livekit.Node{
+		createTestNode("node1", 0.95, 10, 20, livekit.NodeState_SERVING), // Very high load
+		createTestNode("node2", 0.1, 1, 2, livekit.NodeState_SERVING),    // Low load
+		createTestNode("node3", 0.5, 9, 18, livekit.NodeState_SERVING),   // Medium load
+		createTestNode("node4", 0.85, 8, 16, livekit.NodeState_SERVING),  // High load
+	}
+
+	// Run multiple selections and count how often the low-load node is selected
+	iterations := 1000
+	lowLoadSelections := 0
+	higestLoadSelections := 0
+
+	for range iterations {
+		node, err := selector.SelectNode(nodes)
+		require.NoError(t, err)
+		require.NotNil(t, node)
+
+		if node.Id == "node2" {
+			lowLoadSelections++
+		}
+		if node.Id == "node1" {
+			higestLoadSelections++
+		}
+	}
+
+	// The low-load node should be selected more often than pure random (25%)
+	// Due to the two-choice algorithm favoring the better node
+	selectionRate := float64(lowLoadSelections) / float64(iterations)
+	require.Greater(t, selectionRate, 0.4, "Two-choice algorithm should favor the low-load node more than random selection")
+	require.Equal(t, higestLoadSelections, 0, "Two-choice algorithm should never favor the highest load node")
+}
+
+func TestAnySelector_SelectNode_InvalidParameters(t *testing.T) {
+	nodes := []*livekit.Node{
+		createTestNode("node1", 0.5, 3, 10, livekit.NodeState_SERVING),
+	}
+
+	tests := []struct {
+		name      string
+		sortBy    string
+		algorithm string
+		wantErr   string
+	}{
+		{
+			name:      "empty sortBy",
+			sortBy:    "",
+			algorithm: "twochoice",
+			wantErr:   "sort by option cannot be blank",
+		},
+		{
+			name:      "empty algorithm",
+			sortBy:    "cpuload",
+			algorithm: "",
+			wantErr:   "node selector algorithm option cannot be blank",
+		},
+		{
+			name:      "unknown sortBy",
+			sortBy:    "invalid",
+			algorithm: "twochoice",
+			wantErr:   "unknown sort by option",
+		},
+		{
+			name:      "unknown algorithm",
+			sortBy:    "cpuload",
+			algorithm: "invalid",
+			wantErr:   "unknown node selector algorithm option",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			selector := &AnySelector{
+				SortBy:    tt.sortBy,
+				Algorithm: tt.algorithm,
+			}
+
+			node, err := selector.SelectNode(nodes)
+
+			require.Error(t, err)
+			require.Contains(t, err.Error(), tt.wantErr)
+			require.Nil(t, node)
+		})
+	}
+}

pkg/routing/selector/cpuload.go

@@ -0,0 +1,47 @@
+// Copyright 2023 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package selector
+
+import (
+	"github.com/livekit/protocol/livekit"
+)
+
+// CPULoadSelector eliminates nodes that have CPU usage higher than CPULoadLimit
+// then selects a node from nodes that are not overloaded
+type CPULoadSelector struct {
+	CPULoadLimit float32
+	SortBy       string
+	Algorithm    string
+}
+
+func (s *CPULoadSelector) filterNodes(nodes []*livekit.Node) ([]*livekit.Node, error) {
+	nodes, err := FilterNodesByCriteria(nodes, s.CPULoadLimit, func(node *livekit.Node) float32 {
+		return node.Stats.CpuLoad
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	return nodes, nil
+}
+
+func (s *CPULoadSelector) SelectNode(nodes []*livekit.Node) (*livekit.Node, error) {
+	nodes, err := s.filterNodes(nodes)
+	if err != nil {
+		return nil, err
+	}
+
+	return SelectSortedNode(nodes, s.SortBy, s.Algorithm)
+}

pkg/routing/selector/cpuload_test.go

@@ -0,0 +1,51 @@
+// Copyright 2023 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package selector_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/livekit/protocol/livekit"
+
+	"github.com/livekit/livekit-server/pkg/routing/selector"
+)
+
+func TestCPULoadSelector_SelectNode(t *testing.T) {
+	sel := selector.CPULoadSelector{CPULoadLimit: 0.8, SortBy: "random", Algorithm: "lowest"}
+
+	var nodes []*livekit.Node
+	_, err := sel.SelectNode(nodes)
+	require.Error(t, err, "should error no available nodes")
+
+	// Select a node with high load when no nodes with low load are available
+	nodes = []*livekit.Node{nodeLoadHigh}
+	if _, err := sel.SelectNode(nodes); err != nil {
+		t.Error(err)
+	}
+
+	// Select a node with low load when available
+	nodes = []*livekit.Node{nodeLoadLow, nodeLoadHigh}
+	for range 5 {
+		node, err := sel.SelectNode(nodes)
+		if err != nil {
+			t.Error(err)
+		}
+		if node != nodeLoadLow {
+			t.Error("selected the wrong node")
+		}
+	}
+}

pkg/routing/selector/errors.go

@@ -0,0 +1,27 @@
+// Copyright 2023 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package selector
+
+import "errors"
+
+var (
+	ErrNoAvailableNodes           = errors.New("could not find any available nodes")
+	ErrCurrentRegionNotSet        = errors.New("current region cannot be blank")
+	ErrCurrentRegionUnknownLatLon = errors.New("unknown lat and lon for the current region")
+	ErrSortByNotSet               = errors.New("sort by option cannot be blank")
+	ErrAlgorithmNotSet            = errors.New("node selector algorithm option cannot be blank")
+	ErrSortByUnknown              = errors.New("unknown sort by option")
+	ErrAlgorithmUnknown           = errors.New("unknown node selector algorithm option")
+)

pkg/routing/selector/interfaces.go

@@ -0,0 +1,66 @@
+// Copyright 2023 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package selector
+
+import (
+	"errors"
+
+	"github.com/livekit/protocol/livekit"
+	"github.com/livekit/protocol/logger"
+
+	"github.com/livekit/livekit-server/pkg/config"
+)
+
+var ErrUnsupportedSelector = errors.New("unsupported node selector")
+
+// NodeSelector selects an appropriate node to run the current session
+type NodeSelector interface {
+	SelectNode(nodes []*livekit.Node) (*livekit.Node, error)
+}
+
+func CreateNodeSelector(conf *config.Config) (NodeSelector, error) {
+	kind := conf.NodeSelector.Kind
+	if kind == "" {
+		kind = "any"
+	}
+	switch kind {
+	case "any":
+		return &AnySelector{conf.NodeSelector.SortBy, conf.NodeSelector.Algorithm}, nil
+	case "cpuload":
+		return &CPULoadSelector{
+			CPULoadLimit: conf.NodeSelector.CPULoadLimit,
+			SortBy:       conf.NodeSelector.SortBy,
+			Algorithm:    conf.NodeSelector.Algorithm,
+		}, nil
+	case "sysload":
+		return &SystemLoadSelector{
+			SysloadLimit: conf.NodeSelector.SysloadLimit,
+			SortBy:       conf.NodeSelector.SortBy,
+			Algorithm:    conf.NodeSelector.Algorithm,
+		}, nil
+	case "regionaware":
+		s, err := NewRegionAwareSelector(conf.Region, conf.NodeSelector.Regions, conf.NodeSelector.SortBy, conf.NodeSelector.Algorithm)
+		if err != nil {
+			return nil, err
+		}
+		s.SysloadLimit = conf.NodeSelector.SysloadLimit
+		return s, nil
+	case "random":
+		logger.Warnw("random node selector is deprecated, please switch to \"any\" or another selector", nil)
+		return &AnySelector{conf.NodeSelector.SortBy, conf.NodeSelector.Algorithm}, nil
+	default:
+		return nil, ErrUnsupportedSelector
+	}
+}

pkg/routing/selector/nodesfilter.go

@@ -0,0 +1,21 @@
+package selector
+
+import "github.com/livekit/protocol/livekit"
+
+func FilterNodesByCriteria(nodes []*livekit.Node, criteriaThreshold float32, calculateCriteriaFunc func(*livekit.Node) float32) ([]*livekit.Node, error) {
+	nodes = GetAvailableNodes(nodes)
+	if len(nodes) == 0 {
+		return nil, ErrNoAvailableNodes
+	}
+
+	filteredNodes := make([]*livekit.Node, 0)
+	for _, node := range nodes {
+		if calculateCriteriaFunc(node) < criteriaThreshold {
+			filteredNodes = append(filteredNodes, node)
+		}
+	}
+	if len(filteredNodes) > 0 {
+		nodes = filteredNodes
+	}
+	return nodes, nil
+}

pkg/routing/selector/regionaware.go

@@ -0,0 +1,127 @@
+// Copyright 2023 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package selector
+
+import (
+	"math"
+
+	"github.com/livekit/protocol/livekit"
+
+	"github.com/livekit/livekit-server/pkg/config"
+)
+
+// RegionAwareSelector prefers available nodes that are closest to the region of the current instance
+type RegionAwareSelector struct {
+	SystemLoadSelector
+	CurrentRegion   string
+	regionDistances map[string]float64
+	regions         []config.RegionConfig
+	SortBy          string
+	Algorithm       string
+}
+
+func NewRegionAwareSelector(currentRegion string, regions []config.RegionConfig, sortBy string, algorithm string) (*RegionAwareSelector, error) {
+	if currentRegion == "" {
+		return nil, ErrCurrentRegionNotSet
+	}
+	// build internal map of distances
+	s := &RegionAwareSelector{
+		CurrentRegion:   currentRegion,
+		regionDistances: make(map[string]float64),
+		regions:         regions,
+		SortBy:          sortBy,
+		Algorithm:       algorithm,
+	}
+
+	var currentRC *config.RegionConfig
+
+	for _, region := range regions {
+		if region.Name == currentRegion {
+			currentRC = &region
+			break
+		}
+	}
+
+	if currentRC == nil && len(regions) > 0 {
+		return nil, ErrCurrentRegionUnknownLatLon
+	}
+
+	if currentRC != nil {
+		for _, region := range regions {
+			s.regionDistances[region.Name] = distanceBetween(currentRC.Lat, currentRC.Lon, region.Lat, region.Lon)
+		}
+	}
+
+	return s, nil
+}
+
+func (s *RegionAwareSelector) SelectNode(nodes []*livekit.Node) (*livekit.Node, error) {
+	nodes, err := s.SystemLoadSelector.filterNodes(nodes)
+	if err != nil {
+		return nil, err
+	}
+
+	// find nodes nearest to current region
+	var nearestNodes []*livekit.Node
+	nearestRegion := ""
+	minDist := math.MaxFloat64
+	for _, node := range nodes {
+		if node.Region == nearestRegion {
+			nearestNodes = append(nearestNodes, node)
+			continue
+		}
+		if dist, ok := s.regionDistances[node.Region]; ok {
+			if dist < minDist {
+				minDist = dist
+				nearestRegion = node.Region
+				nearestNodes = nearestNodes[:0]
+				nearestNodes = append(nearestNodes, node)
+			}
+		}
+	}
+
+	if len(nearestNodes) > 0 {
+		nodes = nearestNodes
+	}
+
+	return SelectSortedNode(nodes, s.SortBy, s.Algorithm)
+}
+
+// haversine(θ) function
+func hsin(theta float64) float64 {
+	return math.Pow(math.Sin(theta/2), 2)
+}
+
+var piBy180 = math.Pi / 180
+
+// Haversine Distance Formula
+// http://en.wikipedia.org/wiki/Haversine_formula
+// from https://gist.github.com/cdipaolo/d3f8db3848278b49db68
+func distanceBetween(lat1, lon1, lat2, lon2 float64) float64 {
+	// convert to radians
+	// must cast radius as float to multiply later
+	var la1, lo1, la2, lo2, r float64
+	la1 = lat1 * piBy180
+	lo1 = lon1 * piBy180
+	la2 = lat2 * piBy180
+	lo2 = lon2 * piBy180
+
+	r = 6378100 // Earth radius in METERS
+
+	// calculate
+	h := hsin(la2-la1) + math.Cos(la1)*math.Cos(la2)*hsin(lo2-lo1)
+
+	return 2 * r * math.Asin(math.Sqrt(h))
+}

pkg/routing/selector/regionaware_test.go

@@ -0,0 +1,166 @@
+// Copyright 2023 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package selector_test
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/livekit/protocol/livekit"
+	"github.com/livekit/protocol/utils"
+	"github.com/livekit/protocol/utils/guid"
+
+	"github.com/livekit/livekit-server/pkg/config"
+	"github.com/livekit/livekit-server/pkg/routing/selector"
+)
+
+const (
+	loadLimit     = 0.5
+	regionWest    = "us-west"
+	regionEast    = "us-east"
+	regionSeattle = "seattle"
+	sortBy        = "random"
+	algorithm     = "lowest"
+)
+
+func TestRegionAwareRouting(t *testing.T) {
+	rc := []config.RegionConfig{
+		{
+			Name: regionWest,
+			Lat:  37.64046607830567,
+			Lon:  -120.88026233189062,
+		},
+		{
+			Name: regionEast,
+			Lat:  40.68914362140307,
+			Lon:  -74.04445748616385,
+		},
+		{
+			Name: regionSeattle,
+			Lat:  47.620426730945454,
+			Lon:  -122.34938468973702,
+		},
+	}
+	t.Run("works without region config", func(t *testing.T) {
+		nodes := []*livekit.Node{
+			newTestNodeInRegion("", false),
+		}
+		s, err := selector.NewRegionAwareSelector(regionEast, nil, sortBy, algorithm)
+		require.NoError(t, err)
+
+		node, err := s.SelectNode(nodes)
+		require.NoError(t, err)
+		require.NotNil(t, node)
+	})
+
+	t.Run("picks available nodes in same region", func(t *testing.T) {
+		expectedNode := newTestNodeInRegion(regionEast, true)
+		nodes := []*livekit.Node{
+			newTestNodeInRegion(regionSeattle, true),
+			newTestNodeInRegion(regionWest, true),
+			expectedNode,
+			newTestNodeInRegion(regionEast, false),
+		}
+		s, err := selector.NewRegionAwareSelector(regionEast, rc, sortBy, algorithm)
+		require.NoError(t, err)
+		s.SysloadLimit = loadLimit
+
+		node, err := s.SelectNode(nodes)
+		require.NoError(t, err)
+		require.Equal(t, expectedNode, node)
+	})
+
+	t.Run("picks available nodes in same region when current node is first in the list", func(t *testing.T) {
+		expectedNode := newTestNodeInRegion(regionEast, true)
+		nodes := []*livekit.Node{
+			expectedNode,
+			newTestNodeInRegion(regionSeattle, true),
+			newTestNodeInRegion(regionWest, true),
+			newTestNodeInRegion(regionEast, false),
+		}
+		s, err := selector.NewRegionAwareSelector(regionEast, rc, sortBy, algorithm)
+		require.NoError(t, err)
+		s.SysloadLimit = loadLimit
+
+		node, err := s.SelectNode(nodes)
+		require.NoError(t, err)
+		require.Equal(t, expectedNode, node)
+	})
+
+	t.Run("picks closest node in a diff region", func(t *testing.T) {
+		expectedNode := newTestNodeInRegion(regionWest, true)
+		nodes := []*livekit.Node{
+			newTestNodeInRegion(regionSeattle, false),
+			expectedNode,
+			newTestNodeInRegion(regionEast, true),
+		}
+		s, err := selector.NewRegionAwareSelector(regionSeattle, rc, sortBy, algorithm)
+		require.NoError(t, err)
+		s.SysloadLimit = loadLimit
+
+		node, err := s.SelectNode(nodes)
+		require.NoError(t, err)
+		require.Equal(t, expectedNode, node)
+	})
+
+	t.Run("handles multiple nodes in same region", func(t *testing.T) {
+		expectedNode := newTestNodeInRegion(regionWest, true)
+		nodes := []*livekit.Node{
+			newTestNodeInRegion(regionSeattle, false),
+			newTestNodeInRegion(regionEast, true),
+			newTestNodeInRegion(regionEast, true),
+			expectedNode,
+			expectedNode,
+		}
+		s, err := selector.NewRegionAwareSelector(regionSeattle, rc, sortBy, algorithm)
+		require.NoError(t, err)
+		s.SysloadLimit = loadLimit
+
+		node, err := s.SelectNode(nodes)
+		require.NoError(t, err)
+		require.Equal(t, expectedNode, node)
+	})
+
+	t.Run("functions when current region is full", func(t *testing.T) {
+		nodes := []*livekit.Node{
+			newTestNodeInRegion(regionWest, true),
+		}
+		s, err := selector.NewRegionAwareSelector(regionEast, rc, sortBy, algorithm)
+		require.NoError(t, err)
+
+		node, err := s.SelectNode(nodes)
+		require.NoError(t, err)
+		require.NotNil(t, node)
+	})
+}
+
+func newTestNodeInRegion(region string, available bool) *livekit.Node {
+	load := float32(0.4)
+	if !available {
+		load = 1.0
+	}
+	return &livekit.Node{
+		Id:     guid.New(utils.NodePrefix),
+		Region: region,
+		State:  livekit.NodeState_SERVING,
+		Stats: &livekit.NodeStats{
+			UpdatedAt:       time.Now().Unix(),
+			NumCpus:         1,
+			LoadAvgLast1Min: load,
+		},
+	}
+}

pkg/routing/selector/sortby_test.go

@@ -0,0 +1,64 @@
+// Copyright 2023 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package selector_test
+
+import (
+	"testing"
+
+	"github.com/livekit/protocol/livekit"
+
+	"github.com/livekit/livekit-server/pkg/routing/selector"
+)
+
+func SortByTest(t *testing.T, sortBy string) {
+	sel := selector.SystemLoadSelector{SortBy: sortBy, Algorithm: "lowest"}
+	nodes := []*livekit.Node{nodeLoadLow, nodeLoadMedium, nodeLoadHigh}
+
+	for range 5 {
+		node, err := sel.SelectNode(nodes)
+		if err != nil {
+			t.Error(err)
+		}
+		if node != nodeLoadLow {
+			t.Error("selected the wrong node for SortBy:", sortBy)
+		}
+	}
+}
+
+func TestSortByErrors(t *testing.T) {
+	sel := selector.SystemLoadSelector{Algorithm: "lowest"}
+	nodes := []*livekit.Node{nodeLoadLow, nodeLoadMedium, nodeLoadHigh}
+
+	// Test unset sort by option error
+	_, err := sel.SelectNode(nodes)
+	if err != selector.ErrSortByNotSet {
+		t.Error("shouldn't allow empty sortBy")
+	}
+
+	// Test unknown sort by option error
+	sel.SortBy = "testFail"
+	_, err = sel.SelectNode(nodes)
+	if err != selector.ErrSortByUnknown {
+		t.Error("shouldn't allow unknown sortBy")
+	}
+}
+
+func TestSortBy(t *testing.T) {
+	sortByTests := []string{"sysload", "cpuload", "rooms", "clients", "tracks", "bytespersec"}
+
+	for _, sortBy := range sortByTests {
+		SortByTest(t, sortBy)
+	}
+}

pkg/routing/selector/sysload.go

@@ -0,0 +1,45 @@
+// Copyright 2023 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package selector
+
+import (
+	"github.com/livekit/protocol/livekit"
+)
+
+// SystemLoadSelector eliminates nodes that surpass has a per-cpu node higher than SysloadLimit
+// then selects a node from nodes that are not overloaded
+type SystemLoadSelector struct {
+	SysloadLimit float32
+	SortBy       string
+	Algorithm    string
+}
+
+func (s *SystemLoadSelector) filterNodes(nodes []*livekit.Node) ([]*livekit.Node, error) {
+	nodes, err := FilterNodesByCriteria(nodes, s.SysloadLimit, GetNodeSysload)
+	if err != nil {
+		return nil, err
+	}
+
+	return nodes, nil
+}
+
+func (s *SystemLoadSelector) SelectNode(nodes []*livekit.Node) (*livekit.Node, error) {
+	nodes, err := s.filterNodes(nodes)
+	if err != nil {
+		return nil, err
+	}
+
+	return SelectSortedNode(nodes, s.SortBy, s.Algorithm)
+}

pkg/routing/selector/sysload_test.go

@@ -0,0 +1,114 @@
+// Copyright 2023 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package selector_test
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/livekit/protocol/livekit"
+
+	"github.com/livekit/livekit-server/pkg/routing/selector"
+)
+
+var (
+	nodeLoadLow = &livekit.Node{
+		State: livekit.NodeState_SERVING,
+		Stats: &livekit.NodeStats{
+			UpdatedAt:       time.Now().Unix(),
+			NumCpus:         1,
+			CpuLoad:         0.1,
+			LoadAvgLast1Min: 0.0,
+			NumRooms:        1,
+			NumClients:      2,
+			NumTracksIn:     4,
+			NumTracksOut:    8,
+			Rates: []*livekit.NodeStatsRate{
+				{
+					BytesIn:  1000,
+					BytesOut: 2000,
+				},
+			},
+		},
+	}
+
+	nodeLoadMedium = &livekit.Node{
+		State: livekit.NodeState_SERVING,
+		Stats: &livekit.NodeStats{
+			UpdatedAt:       time.Now().Unix(),
+			NumCpus:         1,
+			CpuLoad:         0.5,
+			LoadAvgLast1Min: 0.5,
+			NumRooms:        5,
+			NumClients:      10,
+			NumTracksIn:     20,
+			NumTracksOut:    200,
+			Rates: []*livekit.NodeStatsRate{
+				{
+					BytesIn:  5000,
+					BytesOut: 10000,
+				},
+			},
+		},
+	}
+
+	nodeLoadHigh = &livekit.Node{
+		State: livekit.NodeState_SERVING,
+		Stats: &livekit.NodeStats{
+			UpdatedAt:       time.Now().Unix(),
+			NumCpus:         1,
+			CpuLoad:         0.99,
+			LoadAvgLast1Min: 2.0,
+			NumRooms:        10,
+			NumClients:      20,
+			NumTracksIn:     40,
+			NumTracksOut:    800,
+			Rates: []*livekit.NodeStatsRate{
+				{
+					BytesIn:  10000,
+					BytesOut: 40000,
+				},
+			},
+		},
+	}
+)
+
+func TestSystemLoadSelector_SelectNode(t *testing.T) {
+	sel := selector.SystemLoadSelector{SysloadLimit: 1.0, SortBy: "random", Algorithm: "lowest"}
+
+	var nodes []*livekit.Node
+	_, err := sel.SelectNode(nodes)
+	require.Error(t, err, "should error no available nodes")
+
+	// Select a node with high load when no nodes with low load are available
+	nodes = []*livekit.Node{nodeLoadHigh}
+	if _, err := sel.SelectNode(nodes); err != nil {
+		t.Error(err)
+	}
+
+	// Select a node with low load when available
+	nodes = []*livekit.Node{nodeLoadLow, nodeLoadHigh}
+	for range 5 {
+		node, err := sel.SelectNode(nodes)
+		if err != nil {
+			t.Error(err)
+		}
+		if node != nodeLoadLow {
+			t.Error("selected the wrong node")
+		}
+	}
+}

pkg/routing/selector/utils.go

@@ -0,0 +1,179 @@
+// Copyright 2023 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package selector
+
+import (
+	"math/rand/v2"
+	"slices"
+	"time"
+
+	"github.com/thoas/go-funk"
+
+	"github.com/livekit/protocol/livekit"
+
+	"github.com/livekit/livekit-server/pkg/config"
+	"github.com/livekit/livekit-server/pkg/utils"
+)
+
+const AvailableSeconds = 5
+
+// checks if a node has been updated recently to be considered for selection
+func IsAvailable(node *livekit.Node) bool {
+	if node.Stats == nil {
+		// available till stats are available
+		return true
+	}
+
+	delta := time.Now().Unix() - node.Stats.UpdatedAt
+	return int(delta) < AvailableSeconds
+}
+
+func GetAvailableNodes(nodes []*livekit.Node) []*livekit.Node {
+	return funk.Filter(nodes, func(node *livekit.Node) bool {
+		return IsAvailable(node) && node.State == livekit.NodeState_SERVING
+	}).([]*livekit.Node)
+}
+
+func GetNodeSysload(node *livekit.Node) float32 {
+	stats := node.Stats
+	numCpus := stats.NumCpus
+	if numCpus == 0 {
+		numCpus = 1
+	}
+	return stats.LoadAvgLast1Min / float32(numCpus)
+}
+
+// TODO: check remote node configured limit, instead of this node's config
+func LimitsReached(limitConfig config.LimitConfig, nodeStats *livekit.NodeStats) bool {
+	if nodeStats == nil {
+		return false
+	}
+
+	if limitConfig.NumTracks > 0 && limitConfig.NumTracks <= nodeStats.NumTracksIn+nodeStats.NumTracksOut {
+		return true
+	}
+
+	rate := &livekit.NodeStatsRate{}
+	if len(nodeStats.Rates) > 0 {
+		rate = nodeStats.Rates[0]
+	}
+	if limitConfig.BytesPerSec > 0 && limitConfig.BytesPerSec <= rate.BytesIn+rate.BytesOut {
+		return true
+	}
+
+	return false
+}
+
+func SelectSortedNode(nodes []*livekit.Node, sortBy string, algorithm string) (*livekit.Node, error) {
+	if sortBy == "" {
+		return nil, ErrSortByNotSet
+	}
+	if algorithm == "" {
+		return nil, ErrAlgorithmNotSet
+	}
+
+	switch algorithm {
+	case "lowest": // examine all nodes and select the lowest based on sort criteria
+		return selectLowestSortedNode(nodes, sortBy)
+	case "twochoice": // randomly select two nodes and return the lowest based on sort criteria "Power of Two Random Choices"
+		return selectTwoChoiceSortedNode(nodes, sortBy)
+	default:
+		return nil, ErrAlgorithmUnknown
+	}
+}
+
+func selectTwoChoiceSortedNode(nodes []*livekit.Node, sortBy string) (*livekit.Node, error) {
+	if len(nodes) <= 2 {
+		return selectLowestSortedNode(nodes, sortBy)
+	}
+
+	// randomly select two nodes
+	node1, node2, err := selectTwoRandomNodes(nodes)
+	if err != nil {
+		return nil, err
+	}
+
+	// compare the two nodes based on the sort criteria
+	if node1 == nil || node2 == nil {
+		return nil, ErrNoAvailableNodes
+	}
+
+	selectedNode, err := selectLowestSortedNode([]*livekit.Node{node1, node2}, sortBy)
+	if err != nil {
+		return nil, err
+	}
+
+	return selectedNode, nil
+}
+
+func selectLowestSortedNode(nodes []*livekit.Node, sortBy string) (*livekit.Node, error) {
+	// Return a node based on what it should be sorted by for priority
+	switch sortBy {
+	case "random":
+		idx := funk.RandomInt(0, len(nodes))
+		return nodes[idx], nil
+	case "sysload":
+		slices.SortFunc(nodes, func(a, b *livekit.Node) int {
+			return utils.Signum(GetNodeSysload(a) - GetNodeSysload(b))
+		})
+		return nodes[0], nil
+	case "cpuload":
+		slices.SortFunc(nodes, func(a, b *livekit.Node) int {
+			return utils.Signum(a.Stats.CpuLoad - b.Stats.CpuLoad)
+		})
+		return nodes[0], nil
+	case "rooms":
+		slices.SortFunc(nodes, func(a, b *livekit.Node) int {
+			return utils.Signum(a.Stats.NumRooms - b.Stats.NumRooms)
+		})
+		return nodes[0], nil
+	case "clients":
+		slices.SortFunc(nodes, func(a, b *livekit.Node) int {
+			return utils.Signum(a.Stats.NumClients - b.Stats.NumClients)
+		})
+		return nodes[0], nil
+	case "tracks":
+		slices.SortFunc(nodes, func(a, b *livekit.Node) int {
+			return utils.Signum((a.Stats.NumTracksIn + a.Stats.NumTracksOut) - (b.Stats.NumTracksIn + b.Stats.NumTracksOut))
+		})
+		return nodes[0], nil
+	case "bytespersec":
+		slices.SortFunc(nodes, func(a, b *livekit.Node) int {
+			ratea := &livekit.NodeStatsRate{}
+			if len(a.Stats.Rates) > 0 {
+				ratea = a.Stats.Rates[0]
+			}
+
+			rateb := &livekit.NodeStatsRate{}
+			if len(b.Stats.Rates) > 0 {
+				rateb = b.Stats.Rates[0]
+			}
+			return utils.Signum((ratea.BytesIn + ratea.BytesOut) - (rateb.BytesIn + rateb.BytesOut))
+		})
+		return nodes[0], nil
+	default:
+		return nil, ErrSortByUnknown
+	}
+}
+
+func selectTwoRandomNodes(nodes []*livekit.Node) (*livekit.Node, *livekit.Node, error) {
+	if len(nodes) < 2 {
+		return nil, nil, ErrNoAvailableNodes
+	}
+
+	shuffledIndices := rand.Perm(len(nodes))
+
+	return nodes[shuffledIndices[0]], nodes[shuffledIndices[1]], nil
+}

pkg/routing/selector/utils_test.go

@@ -0,0 +1,46 @@
+// Copyright 2023 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package selector_test
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/livekit/protocol/livekit"
+
+	"github.com/livekit/livekit-server/pkg/routing/selector"
+)
+
+func TestIsAvailable(t *testing.T) {
+	t.Run("still available", func(t *testing.T) {
+		n := &livekit.Node{
+			Stats: &livekit.NodeStats{
+				UpdatedAt: time.Now().Unix() - 3,
+			},
+		}
+		require.True(t, selector.IsAvailable(n))
+	})
+
+	t.Run("expired", func(t *testing.T) {
+		n := &livekit.Node{
+			Stats: &livekit.NodeStats{
+				UpdatedAt: time.Now().Unix() - 20,
+			},
+		}
+		require.False(t, selector.IsAvailable(n))
+	})
+}