Skip to content
Meshline
SDK 1.6.0 · GuideView source on GitHub

Lifecycle and ownership

Guide index · Accounts and devices

Session order

Construction performs no I/O. Create the database directory and call MeshlineDatabase.MigrateAsync, construct the pool and client, attach event handlers, and call InitializeAsync. Then establish or recover authorization if needed, call StartAsync, run the application, and call StopAsync before asynchronous disposal.

Use one active MeshlineClient per database, including across processes. Concurrent calls to that client use its component coordination. Await the old client's DisposeAsync before handing the database to a replacement; stopping background work alone does not end its foreground operations. Independently composed components follow the same single-owner rule. The SDK does not enforce exclusive database ownership.

Operation Meaning
InitializeAsync Load local state once. A failed initialization leaves the component uninitialized so its cause can be corrected before retrying.
StartAsync Start component background work after authorization checks. Completion does not wait for WebSocket readiness or prove that all history has synchronized.
StopAsync Stop background processing and drain pending refreshes, including those triggered by reads before start or after a previous stop. It drains runtime device sessions and preserves the database for a later session.
DisposeAsync End the component lifetime, release owned resources, and drain active work. A disposed component cannot be reused.

Observe LifecycleState and StateChanged for lifecycle changes. Pass cancellation tokens to awaited operations. Shutdown itself must still be awaited when the application's ordinary operation token is canceled; the examples call StopAsync without that canceled token.

Verified local-device removal, rejected local authentication, or an own-state query still denied after device-session renewal suspends the coordinated runtime. Observe BackgroundError for the cause and StateChanged for completed shutdown. Suspension preserves the last verified state and readable local history. Network failures, certificate expiry and peer/recipient authorization errors do not establish revocation. Background reads never request wallet signatures; deliberate reauthorization belongs to EstablishAccountAsync.

Normal stop and authentication suspension drain device sessions across all relays, including notifications, reconnects and renewal tasks. Account sessions and verified relay metadata remain cached. A later start authenticates a fresh device session; no device authentication continues in the stopped runtime. Stopping before runtime attachment leaves setup sessions alone.

Shutdown attempts every child and releases its subscriptions and sessions even if another cleanup task fails. It raises the completed running-to-stopped transition before reporting errors to the explicit caller, or through BackgroundError for automatic suspension. Multiple failures are retained in AggregateException. If storage prevented saving an interrupted send's status, correct the problem and reopen the client to reconcile its retained message ID and ciphertext.

Disposal requests lifetime cancellation before waiting for initialization/startup, including startup waiting for account establishment. Concurrent disposals share cancellation and serialize cleanup. Always await disposal: cancellation alone does not mean active work has drained. After an error, Disposed is terminal and repeated disposal is harmless; if resource cleanup failed before reaching that state, correct the cause and retry disposal. New tracked operations remain blocked.

Reopen an authorized device

Use the existing database, matching account/network options, and the same protection keys. This method intentionally has no account signer and performs no account-establishment or recovery write:

Initialization makes local history available without a connection. Start the application immediately after initialization; start the connection independently. StartAsync still awaits required relay authentication and may fail offline. The example retries transient network failures with capped backoff, reports every failure, and stops retrying on authorization, key, or storage errors. Replace its console diagnostic with the application's connection/error presentation. It never uses establishment as an automatic error fallback, and does not restart a runtime after a confirmed revocation. Canceling the session drains pending startup/retry work before disposing the client.

public static async Task RunExistingDeviceAsync(
    ClientOptions options,
    DatabaseOptions database,
    IRelayRegistry registry,
    ISecretProtector protector,
    Func<MeshlineClient, CancellationToken, Task> runApplication,
    CancellationToken cancellationToken = default)
{
    await MeshlineDatabase.MigrateAsync(database, cancellationToken);
    await using var pool = new RelayClientPool(options, registry);
    await using var client = new MeshlineClient(options, database, pool, protector);
    client.BackgroundError += (_, error) =>
        Console.Error.WriteLine($"{error.Operation}: {error.Error}");

    await client.InitializeAsync(cancellationToken);
    using var session = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
    var connection = StartConnectionAsync();
    try
    {
        // Local history is available while connection/startup is still pending.
        await runApplication(client, session.Token);
    }
    finally
    {
        await session.CancelAsync();
        try { await connection; }
        catch (OperationCanceledException) when (session.IsCancellationRequested) { }
        finally { await client.StopAsync(); }
    }

    async Task StartConnectionAsync()
    {
        var delay = TimeSpan.FromSeconds(1);
        while (true)
        {
            try
            {
                await client.StartAsync(session.Token);
                return;
            }
            catch (OperationCanceledException) when (session.IsCancellationRequested) { throw; }
            catch (Exception error)
            {
                // Replace this diagnostic with the application's connection/error UI.
                Console.Error.WriteLine($"Startup: {error}");
                if (error is not (HttpRequestException or TimeoutException)
                    && error is not RelayException { Error.Code: "temporarily_unavailable" or "bad_gateway" or "rate_limited" })
                    return;
            }
            // Retry only transient startup failures. Authorization/key failures
            // need explicit user action; never call establishment from this loop.
            await Task.Delay(delay, session.Token);
            delay = TimeSpan.FromSeconds(Math.Min(delay.TotalSeconds * 2, 30));
        }
    }
}

Source: Sessions.cs. The database's parent directory must exist. If startup fails, inspect the actual error and authorization state before deciding whether recovery is appropriate.

Resource ownership

MeshlineClient owns its six managers. Dispose the client before the application-owned RelayClientPool, and dispose a caller-supplied HttpClient after that pool. Readers from local queries own SQLite snapshot transactions and must also be disposed promptly. The signer, registry, and protector remain application-owned.

Independently composed components follow their constructor dependencies. Initialize and start dependencies before dependents; stop and dispose dependents first. The coordinated client's order is account, device, profile, messages, channels, then groups; shutdown reverses that order. Prefer the coordinated client unless the application needs to manage these relationships explicitly.

Starting activates background work; it does not wait for resources to catch up. See synchronization for foreground refreshes, polling, notifications, and progress snapshots.

MeshlineClient.StartAsync waits for an executing EstablishAccountAsync before starting its children. Once startup begins, establishment that would change authorization requires stopping synchronization, even before the facade reports Running. Canceling a startup wait does not cancel the establishment operation.

During runtime, a verified complete device list which removes the local device causes MeshlineClient to stop all six managers asynchronously. Observe StateChanged for the transition to Stopped. Local history remains readable after that transition. Failed queries, unknown authorization and certificate expiry alone do not trigger this removal policy. Explicit establishment and account signing are required to reauthorize; StartAsync never republishes device authorization. Applications using standalone managers own the coordination of their runtime shutdown.

API reference

ClientComponent · ComponentState · MeshlineClient · RelayClientPool