Class Node

Namespace

Nyra

Assembly

Nyra.dll

A connection to a Lavalink v4.2+ or NodeLink v3.9+ server. The kind is detected at connect (GET /v4/info) and probed again by the first query after a disconnect drops the detection. A server below the floors throws IncompatibleServerException from the query surface.

public sealed class Node : IAsyncDisposable, IDisposable

Inheritance

object

Node

Implements

IAsyncDisposable

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

Extension Methods

NodeExtensions.ConnectAsync(Node, DiscordChannel, CancellationToken)

NodeExtensions.ConnectAsync(Node, IVoiceChannel, CancellationToken)

NodeExtensions.ConnectAsync(Node, IVoiceGuildChannel, CancellationToken)

Remarks

Owns the websocket, the REST client, the voice handshake and the guild connections created through it.

Constructors

Node(Endpoint, NodeOptions?)

Creates a node for an endpoint.

public Node(Endpoint endpoint, NodeOptions? options = null)

Parameters

endpoint Endpoint

The endpoint of the server.

options NodeOptions

The behavioral options, null uses the defaults.

Properties

ConnectionStatus

Last reported outbound connection status, or null before the first event.

public ConnectionStatus? ConnectionStatus { get; }

Property Value

ConnectionStatus

Remarks

NodeLink only, and only while the node's session holds at least one player, a playerless session receives no pushes, GetConnectionStatusAsync(CancellationToken) works without one.

Endpoint

The endpoint the node connects to.

public Endpoint Endpoint { get; }

Property Value

Endpoint

Groups

The player groups of the node, NodeLink only.

public NodeGroups Groups { get; }

Property Value

NodeGroups

IsConnected

Whether the websocket to the server is open, wait for IsReady before issuing requests.

public bool IsConnected { get; }

Property Value

bool

IsNodeLink

Detected at connect, true when the server is NodeLink, false when it is Lavalink or no detection is held.

public bool IsNodeLink { get; }

Property Value

bool

IsReady

Whether the node received the ready operation and can serve requests.

public bool IsReady { get; }

Property Value

bool

Lyrics

Lyrics, chapters and meanings of the tracks of the node.

public NodeLyrics Lyrics { get; }

Property Value

NodeLyrics

Name

The node's display name, used in logs and error messages, must not be blank.

public string Name { get; }

Property Value

string

RoutePlanner

The IP route planner of the node.

public NodeRoutePlanner RoutePlanner { get; }

Property Value

NodeRoutePlanner

SessionId

The node session id of the current connection, null before the node first became ready.

public string? SessionId { get; }

Property Value

string

Remarks

Kept across disconnects so a resuming connection can replay it. Not a Discord voice session id.

Stats

The last statistics reported by the server, or null before the first stats operation.

public Stats? Stats { get; }

Property Value

Stats

Tracks

Decoding, encoding and streaming of the tracks of the node.

public NodeTracks Tracks { get; }

Property Value

NodeTracks

Version

Server-reported version, e.g. 3.9.0.

public NodeVersion? Version { get; }

Property Value

NodeVersion?

Remarks

Null while no detection is held (before the first connect, and after a disconnect until a query re-probes the server) and on Lavalink dev builds (commit hash, not semver). NodeLink dev pre-release tags parse as their base version.

Null means always current by policy (dev builds skip the version floors), so write node.Version is { } v and compare the bound variable, a lifted relational operator on the null answers false and would invert the meaning.

YouTube

The YouTube source configuration of the node.

public NodeYouTube YouTube { get; }

Property Value

NodeYouTube

Methods

ConnectAsync(ulong, ulong, CancellationToken)

Connects the bot to the voice channel and creates a guild connection on this node, forwarding the voice credentials.

public Task<GuildConnection> ConnectAsync(ulong guildId, ulong channelId, CancellationToken cancellationToken = default)

Parameters

guildId ulong

The guild to connect.

channelId ulong

The voice channel to join.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<GuildConnection>

The guild connection created by the join.

Remarks

Validating the channel kind is up to the adapters, the core only sees ids.

Exceptions

ArgumentOutOfRangeException

guildId or channelId is zero, a join that could only ever fail as a handshake timeout with no reason.

InvalidOperationException

The guild is already connected through a different node (one guild plays on one node at a time) or to a different channel on this node, disconnect it before connecting again. Also thrown when the node is not attached to a Discord client or not ready.

VoiceHandshakeException

The voice handshake of the join failed, see its message for the cause.

NodeUnreachableException

The node became unreachable between the handshake and the player registration.

TimeoutException

The node's REST endpoint did not answer the player registration within its bound.

RestException

The node rejected the player registration, see its message for the reply.

OperationCanceledException

The join was cancelled through the token.

DisconnectAsync(CancellationToken)

Stops the websocket connection, active guild connections are left untouched.

public Task DisconnectAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task

A task that completes when the websocket was stopped.

Remarks

The Discord events are unwired by the stop, so the guild connections left behind lose the Discord-side tracking (a kick, a move, a voice server re-target) until the node is connected again, a removal that lands during the dormancy finds no subscriber and the connection stays registered until then.

Dispose()

Stops the node synchronously, the guild connections are torn down over the network.

public void Dispose()

Remarks

Blocks on every guild teardown roundtrip, each bounded by the HTTP timeout, prefer DisposeAsync() wherever the caller can await.

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

public ValueTask DisposeAsync()

Returns

ValueTask

A task that represents the asynchronous dispose operation.

GetConnection(ulong)

The guild connection playing on this node, or null when the guild is not connected here.

public GuildConnection? GetConnection(ulong guildId)

Parameters

guildId ulong

The guild to get the connection of.

Returns

GuildConnection

The guild's connection, null when it is not connected here.

GetConnectionStatusAsync(CancellationToken)

Fetches the node's outbound connection health over REST, also pushed over the websocket (ConnectionStatusUpdated, ConnectionStatus).

public Task<ConnectionStatus> GetConnectionStatusAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<ConnectionStatus>

The outbound connection health of the node.

Remarks

NodeLink only.

Exceptions

NotSupportedException

The node is not NodeLink.

IncompatibleServerException

The server's /v4/info version is not supported.

GetNodeInfoAsync(CancellationToken)

Fetches the node's descriptive info over REST, version, build time, git revision, runtime, enabled sources/filters/plugins.

public Task<NodeInfo> GetNodeInfoAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<NodeInfo>

The descriptive info of the node.

Remarks

Served by both, server-specific members null on the other kind. This read is strict, the connect probe that admitted the node is not, a server whose info carries a member in an unexpected shape (a stringified boolean, a fractional build time) can be connected and playing while this call fails.

Exceptions

RestException

The response body does not deserialize into NodeInfo, the status still reports OK.

IncompatibleServerException

The server's /v4/info version is not supported.

GetStatsAsync(CancellationToken)

Fetches statistics over REST.

public Task<Stats> GetStatsAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<Stats>

The stats of the node.

Remarks

CPU, memory, uptime, per-frame loss counts, also pushed over the websocket (StatsUpdated, Stats).

Exceptions

IncompatibleServerException

The server's /v4/info version is not supported.

GetVersionAsync(CancellationToken)

Probes the server version if it was not detected yet, null on dev builds without a parseable semver.

public Task<NodeVersion?> GetVersionAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<NodeVersion?>

The detected version, null on dev builds.

Remarks

Like Version, null means always current by policy, see its remarks for how to compare it.

Exceptions

IncompatibleServerException

The server's /v4/info version is not supported.

HasPlugin(string)

Detected at connect, true when the server reports the given plugin as loaded, Lavalink and NodeLink alike.

public bool HasPlugin(string name)

Parameters

name string

The plugin to check for, for example lavasrc-plugin, matched case-insensitively.

Returns

bool

Whether the plugin is loaded, false until the first connect and while no detection is held.

Exceptions

ArgumentNullException

name is null.

ListPlayersAsync(CancellationToken)

Lists every player of this node's session, including guilds this client is not connected to (useful after a resume).

public Task<IReadOnlyList<Player>> ListPlayersAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<IReadOnlyList<Player>>

Every player of the node's session.

Exceptions

IncompatibleServerException

The server's /v4/info version is not supported.

LoadTracksAsync(string, SearchType, CancellationToken)

Loads tracks for a query, direct http(s) and ftts URLs are sent as-is, plain terms resolve per searchType (Auto searches YouTube).

public Task<LoadResult> LoadTracksAsync(string query, SearchType searchType = SearchType.Auto, CancellationToken cancellationToken = default)

Parameters

query string

What to load, a raw identifier or a search query.

searchType SearchType

How to treat the query, Auto detects it.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<LoadResult>

The load result of the query.

Remarks

A URL's t/start parameter carries over to StartPosition.

Exceptions

IncompatibleServerException

The server's /v4/info version is not supported.

ToString()

Returns the node as its name and endpoint.

public override string ToString()

Returns

string

The name and endpoint of the node.

UpdateSessionAsync(bool, TimeSpan, CancellationToken)

Changes the session's resuming behavior at runtime, whether the server keeps the session's players through a disconnect, and how long it holds them.

public Task<SessionConfig> UpdateSessionAsync(bool resuming, TimeSpan timeout, CancellationToken cancellationToken = default)

Parameters

resuming bool

Whether the session resumes its players after a reconnect.

timeout TimeSpan

How long a disconnected resumable session is kept alive, the server counts it in whole seconds.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<SessionConfig>

The session state the server stored.

Remarks

Both values are sent together, the server applies them as a pair. They last as long as the session, a resumed session keeps them, a new session starts from Resuming and ResumeTimeout again.

Exceptions

ArgumentOutOfRangeException

timeout is negative or exceeds MaxValue seconds, the limits the constructor enforces on NodeOptions.ResumeTimeout.

Events

Connected

The websocket connection was established, the node is not ready yet, wait for Ready.

public event AsyncEventHandler<NodeConnectedEventArgs>? Connected

Event Type

AsyncEventHandler<NodeConnectedEventArgs>

ConnectionStatusUpdated

Raised on every ConnectionStatusEvent.

public event AsyncEventHandler<NodeConnectionStatusEventArgs>? ConnectionStatusUpdated

Event Type

AsyncEventHandler<NodeConnectionStatusEventArgs>

Remarks

The args carry the snapshot ConnectionStatus held when the raise was queued, a newer push may have replaced the property by handler time. NodeLink only. The event's guildId is node-wide data delivered inside a guild-scoped payload, not exposed here.

An update queued before a stop or a disconnect can still run after it returns, a slow handler ahead of it in the queue holds it back. The dispose drains what is left with a bounded wait.

Disconnected

The websocket connection was lost, reconnection attempts follow.

public event AsyncEventHandler<NodeDisconnectedEventArgs>? Disconnected

Event Type

AsyncEventHandler<NodeDisconnectedEventArgs>

Remarks

Final marks the last one.

Error

Raised for internal client errors, see NodeErrorEventArgs for the categories.

public event AsyncEventHandler<NodeErrorEventArgs>? Error

Event Type

AsyncEventHandler<NodeErrorEventArgs>

Remarks

Reconnect failures log separately, playback errors surface through the guild connection, a throwing handler is caught and logged. Errors of the same kind are reported five times per thirty seconds, the rest of the window is counted in one log line, so a malformed frame repeated for every player cannot flood the log or the event queue.

Ready

Raised once per connection when the server sent its ready operation.

public event AsyncEventHandler<NodeReadyEventArgs>? Ready

Event Type

AsyncEventHandler<NodeReadyEventArgs>

StatsUpdated

Raised when the server reports its statistics, the latest report is also Stats.

public event AsyncEventHandler<NodeStatsEventArgs>? StatsUpdated

Event Type

AsyncEventHandler<NodeStatsEventArgs>

Remarks

Frames landing while a ready's final phase runs collapse into the one raise after Ready.

WorkerFailed

A NodeLink cluster worker crashed and the affected guilds' players died with it, raised after the connections were invalidated.

public event AsyncEventHandler<WorkerFailedEventArgs>? WorkerFailed

Event Type

AsyncEventHandler<WorkerFailedEventArgs>

Remarks

NodeLink only.