using DodoSSH.Client.Ssh;

namespace DodoSSH.Client.Session;

/// <summary>
/// A way to a host that is not a dial: one connection long, handed to SSH.NET as a loopback proxy.
/// </summary>
/// <remarks>
/// <para>
/// Two things answer to this — the server relay (<see cref="RelayRoute"/>) and a Spelunk tunnel
/// (<see cref="SpelunkTunnelRoute"/>) — and both are the same shape underneath: a WebSocket carrying the
/// SSH bytes, and a <see cref="RelayBridge"/> that turns it into an address SSH.NET can be given. What the
/// connect path needs from either is exactly that address, the reason the far end gave if it hung up, and a
/// way to let go of it when the connect never got as far as handing it over.
/// </para>
/// <para>
/// Handing <see cref="Proxy"/> to a connection hands the bridge over with it, so the connection's own
/// disposal is what closes the route. <see cref="IAsyncDisposable.DisposeAsync"/> is for a caller that ends
/// up not connecting; after a hand-over it does nothing, because the bridge's disposal is idempotent.
/// </para>
/// </remarks>
public interface IConnectionRoute : IAsyncDisposable
{
    /// <summary>The loopback proxy to connect through, which owns the route from then on.</summary>
    SshLoopbackProxy Proxy { get; }

    /// <summary>
    /// What the far end said when it closed, in words a user can act on; null when it has not closed, or
    /// closed with nothing to say.
    /// </summary>
    /// <remarks>
    /// For a connect that failed. SSH.NET reports a route that hung up as a stream that ended, which reads
    /// exactly like the direct connection the route was chosen to get around — so the route's own reason,
    /// when it gave one, replaces it.
    /// </remarks>
    string? Failure { get; }
}