Verbara.Sdk.Ari 2.9.0

Verbara.Sdk.Ari

Asterisk REST Interface (ARI) client for .NET 10 with Native AOT support.

Features

• REST client for all 8 ARI resources (Channels, Bridges, Playbacks, Recordings, Endpoints, Applications, Sounds, DeviceStates)
• WebSocket event streaming with 46 event types
• AOT-safe JSON serialization via System.Text.Json source generation
• Automatic reconnection with exponential backoff
• AudioSocket server for real-time audio streaming
• System.Diagnostics.Metrics for observability

Quick Start

var client = new AriClient(Options.Create(new AriClientOptions
{
    BaseUrl = "http://pbx.example.com:8088",
    Username = "admin",
    Password = "secret",
    Application = "myapp"
}), logger);

await client.ConnectAsync();

// Subscribe to events
client.Subscribe(Observer.Create<AriEvent>(evt =>
{
    if (evt is StasisStartEvent start)
        Console.WriteLine($"Channel entered Stasis: {start.Channel?.Name}");
}));

// REST operations
var channels = await client.Channels.ListAsync();
var bridge = await client.Bridges.CreateAsync("mixing", "mybridge");
await client.Bridges.AddChannelAsync(bridge.Id!, channels[0].Id!);

The token you hand ConnectAsync bounds the dial only: cancelling it once the connect has returned (a host's start or stopping token, a request token) does not end the connection, its events or a reconnect. End the connection with DisconnectAsync or by disposing the client.

Closing

Every ending the SDK starts on an open WebSocket sends a close frame first, and every close Asterisk sends is answered:

• DisconnectAsync sends its close before the events loop stops reading, then waits for Asterisk's answering close up to the existing 5-second bound, or until the token you passed is cancelled, whichever comes first. The token never suppresses the frame: a disconnect whose token is already cancelled (a host's stopping token in a finally) still sends it, then lets the connection go without waiting. A disconnect does not start a reconnect, even with AutoReconnect on.
• A close Asterisk sends is answered with one close before the socket is released and before any reconnect the AutoReconnect policy allows. With AutoReconnect off the client then reads Disconnected.
• Disposing the client while it reconnects (in its backoff, or in a dial the far end holds) ends with Disconnected, as a disposal of a connected client does.
• AriOutboundListener.StopAsync stops accepting, sends every open connection its close at the same time and waits for the answers under one shared one-second bound; the stop's token can end that wait but never suppresses a frame. A connection that has not answered by then is aborted before it is released. Every connection's end logs Connection closed (Debug); an idle timeout also logs Idle timeout (Warning); a stop, or a close bound that runs out during a stop or the connection's own disconnect, logs no error. Only a transport failure logs Connection error (Error).

What this costs, measured on Asterisk 22.12.0-rc2, 23.6.0-rc2 and 24.0.0-rc2 against the full functional test stack:

The bounds are there for an Asterisk, proxy or network that does not answer; none of these runs came near them.

Connection attempts

One ConnectAsync call or automatic reconnect attempt can open more than one TCP connection within the existing five-second connect bound. The .NET HTTP transport can retry a connection that closes before an upgrade response; these transport retries are separate from the ARI client's automatic reconnect policy.

With .NET SDK 10.0.402 and runtime 10.0.13, twenty independent failed caller dials per loopback-peer shape recorded:

These are measured framework-specific counts, pinned by AriDialConnectionCountTests; a framework upgrade may change them. They are not a runtime-independent limit for every network. Measurements against Asterisk on the same framework also found one TCP connection for a wrong password or direct refusal, and one to four when a proxy accepted and closed while Asterisk was stopped. Additional starts matched HTTP transport retry events; no extra SDK retry layer was observed. The client does not suppress or replace the runtime's transport retries.

Documentation

• High-Load Tuning Guide
• Asterisk Version Compatibility