Utils

class lava_lyra.utils.ConnectionQualityTracker(max_latency_samples: int = 10)

Bases: object

Tracks connection quality metrics for a node to help make better failover and load balancing decisions.

property average_latency: float

Get average latency from recent samples.

property consecutive_failures: int

Get consecutive failure count.

property is_stable: bool

Determine if connection is considered stable.

property reconnection_count: int

Get total reconnection count.

record_connection_failure() → None

Record a connection failure.

record_connection_success() → None

Record a successful connection.

record_latency(latency: float) → None

Record a latency sample.

record_reconnection() → None

Record a reconnection event.

property uptime_percentage: float

Calculate uptime percentage.

class lava_lyra.utils.ExponentialBackoff(base: int = 1, *, integral: bool = False)

Bases: object

The MIT License (MIT) Copyright (c) 2015-present Rapptz Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

delay() → float

class lava_lyra.utils.FailingIPBlock(data: dict[str, Any])

Bases: object

The base class for the failing IP block object from the route planner stats. Gives critical information about any failing addresses on the block and the time they failed.

address

failing_time

class lava_lyra.utils.LavalinkVersion(major, minor, fix)

Bases: NamedTuple

fix: int

Alias for field number 2

major: int

Alias for field number 0

minor: int

Alias for field number 1

class lava_lyra.utils.NodeHealthMonitor(circuit_breaker_threshold: int = 5, circuit_timeout: float = 60.0)

Bases: object

Monitors node health and provides a health score for intelligent node selection and failover decisions.

check_circuit_breaker() → None

Open the circuit breaker if consecutive failures reached the threshold.

This can only open the circuit, never close it — closing happens via record_success(), or lazily the next time is_circuit_open is read after circuit_timeout has elapsed.

get_health_score(current_latency: float, player_count: int) → float

Calculate a health score from 0.0 (worst) to 100.0 (best).

Factors: - Latency (40% weight) - Uptime (30% weight) - Player load (20% weight) - Connection stability (10% weight)

property is_circuit_open: bool

Check if circuit breaker is open.

property quality_tracker: ConnectionQualityTracker

Get the connection quality tracker.

record_failure() → None

Record a failed operation.

record_reconnection() → None

Record a reconnection event.

record_success() → None

Record a successful operation.

class lava_lyra.utils.NodeStats(data: dict[str, Any])

Bases: object

The base class for the node stats object. Gives critical information on the node, which is updated every 60 seconds on Lavalink or every 30 seconds on NodeLink.

allocated

cpu_cores

cpu_process_load

cpu_system_load

free

players_active

players_total

reservable

uptime

used

class lava_lyra.utils.Ping(host: str, port: int, timeout: int = 5)

Bases: object

class Socket(family: int, type_: int, timeout: float | None)

Bases: object

close() → None

connect(host: str, port: int) → None

shutdown() → None

class Timer

Bases: object

cost(funcs: Iterable[Callable[[...], Any]], args: Any) → float

start() → None

stop() → None

get_ping() → float

Get ping latency in milliseconds. Returns -1.0 if the connection fails (node is unreachable).

class lava_lyra.utils.RouteStats(data: dict[str, Any])

Bases: object

The base class for the route planner stats object. Gives critical information about the route planner strategy on the node.

address_index

block_index

failing_addresses

ip_block_size

ip_block_type: RouteIPType | None

strategy: RouteStrategy | None

lava_lyra.utils.voice_field(data: Any, key: str) → Any