Add trace level enumeration and session tracing support in SshSession

Introduce `SshTraceLevel` enumeration to manage libssh2 debugging trace levels. Extend `SshSession` with `SetTrace` method for enabling and handling session trace output. Add tests for trace handler functionality and update native libraries.

Author: 0x25CBFC4F

src/NullOpsDevs.LibSsh.Test/Program.cs

@@ -228,6 +228,7 @@ private static async Task RunCommandTests()
         await RunTest("Streaming command exit code", TestStreamingCommandExitCode);
         await RunTest("Streaming async command", TestStreamingCommandAsync);
         await RunTest("Streaming incremental output", TestStreamingIncrementalOutput);
+        await RunTest("Streaming long output (2 min wait)", TestStreamingLongOutputWithTimeout);
     }
 
     private static Task<bool> TestSimpleCommand()
@@ -500,6 +501,77 @@ private static async Task<bool> TestStreamingIncrementalOutput()
         return result.ExitCode == 0;
     }
 
+    private static async Task<bool> TestStreamingLongOutputWithTimeout()
+    {
+        // This is an optional long-running test, skip unless explicitly enabled
+        if (Environment.GetEnvironmentVariable("LONG_RUNNING_STREAM_TEST") == null)
+        {
+            AnsiConsole.MarkupLine("[yellow]       Skipped (set LONG_RUNNING_STREAM_TEST=1 to enable)[/]");
+            skippedTests++;
+            return true;
+        }
+
+        AnsiConsole.MarkupLine("[dim]       Starting long output streaming test (2 min timeout)...[/]");
+
+        using var session = TestHelper.CreateConnectAndAuthenticate();
+        AnsiConsole.MarkupLine("[dim]       Session authenticated, executing streaming command...[/]");
+
+        // Execute a command that produces output over 2 minutes (24 lines, 5 seconds apart)
+        using var stream = await session.ExecuteCommandStreamingAsync(
+            "for i in $(seq 1 24); do echo \"Line $i at $(date +%H:%M:%S)\"; sleep 5; done");
+        AnsiConsole.MarkupLine("[dim]       Command started, reading stdout with StreamReader (~2 min output, 3 min timeout)...[/]");
+
+        var lines = new List<string>();
+        var stopwatch = Stopwatch.StartNew();
+
+        using var reader = new StreamReader(stream.Stdout);
+        var lineNum = 0;
+
+        while (await reader.ReadLineAsync() is { } line)
+        {
+            lineNum++;
+            lines.Add(line);
+            var escapedLine = Markup.Escape(line);
+            if (escapedLine.Length > 60) escapedLine = escapedLine[..57] + "...";
+            AnsiConsole.MarkupLine($"[dim]       Line #{lineNum}: \"{escapedLine}\" at {stopwatch.ElapsedMilliseconds}ms[/]");
+        }
+
+        stopwatch.Stop();
+        AnsiConsole.MarkupLine($"[dim]       Stream reading complete. Total lines: {lines.Count}, Total time: {stopwatch.ElapsedMilliseconds}ms[/]");
+
+        var result = stream.WaitForExit();
+        AnsiConsole.MarkupLine($"[dim]       Command exited with code: {result.ExitCode}[/]");
+
+        // Verify we received all 24 lines
+        if (lines.Count != 24)
+        {
+            AnsiConsole.MarkupLine($"[red]       FAILED: Expected 24 lines, got {lines.Count}[/]");
+            return false;
+        }
+
+        // Verify the content contains expected line markers
+        for (int i = 1; i <= 24; i++)
+        {
+            if (!lines.Any(l => l.Contains($"Line {i} at")))
+            {
+                AnsiConsole.MarkupLine($"[red]       FAILED: Missing 'Line {i}' in output[/]");
+                return false;
+            }
+        }
+
+        // Verify timing: total time should be at least 115 seconds (24 lines with 5 second delay each = ~120s)
+        if (stopwatch.Elapsed < TimeSpan.FromSeconds(115))
+        {
+            AnsiConsole.MarkupLine($"[red]       FAILED: Total time ({stopwatch.ElapsedMilliseconds}ms) too short, expected at least 115000ms[/]");
+            return false;
+        }
+
+        AnsiConsole.MarkupLine($"[green]  -> [/] Received {lines.Count} lines in {stopwatch.Elapsed.TotalSeconds:F1}s (~2 min)");
+        AnsiConsole.MarkupLine($"[green]  -> [/] All output received successfully");
+
+        return result.ExitCode == 0;
+    }
+
     #endregion
 
     #region File Transfer Tests
@@ -756,6 +828,7 @@ private static async Task RunEdgeCaseTests()
         await RunTest("Timeout test", TimeoutTest);
         await RunTest("Won't connect with deprecated methods", WontConnectWithDeprecatedMethods);
         await RunTest("Parallel sessions test", ParallelSessionsTest);
+        await RunTest("Trace handler test", TestTraceHandler);
     }
 
     private static Task<bool> ParallelSessionsTest()
@@ -879,6 +952,62 @@ private static Task<bool> TestMultipleOperations()
         return Task.FromResult(true);
     }
 
+    private static Task<bool> TestTraceHandler()
+    {
+        var traceMessages = new List<string>();
+
+        using var session = TestHelper.CreateAndConnect();
+
+        // Enable tracing with our handler
+        session.SetTrace(
+            SshTraceLevel.Authentication | SshTraceLevel.Error | SshTraceLevel.KeyExchange,
+            message => traceMessages.Add(message));
+
+        // Authenticate - this should generate trace messages
+        var credential = SshCredential.FromPassword(TestConfig.Username, TestConfig.Password);
+        var authResult = session.Authenticate(credential);
+
+        if (!authResult)
+        {
+            AnsiConsole.MarkupLine("[red]       Authentication failed[/]");
+            return Task.FromResult(false);
+        }
+
+        // Run a simple command
+        var result = session.ExecuteCommand("echo 'trace test'");
+
+        if (!result.Successful)
+        {
+            AnsiConsole.MarkupLine("[red]       Command execution failed[/]");
+            return Task.FromResult(false);
+        }
+
+        // Disable tracing
+        session.SetTrace(SshTraceLevel.None, null);
+
+        AnsiConsole.MarkupLine($"[green]  -> [/] Captured {traceMessages.Count} trace messages");
+
+        // We should have received some trace messages during auth
+        if (traceMessages.Count == 0)
+        {
+            AnsiConsole.MarkupLine("[red]       No trace messages received[/]");
+            return Task.FromResult(false);
+        }
+
+        // Print first few trace messages for debugging
+        foreach (var msg in traceMessages.Take(5))
+        {
+            var escaped = Markup.Escape(msg.Trim());
+            if (escaped.Length > 70) escaped = escaped[..67] + "...";
+            AnsiConsole.MarkupLine($"[dim]       {escaped}[/]");
+        }
+
+        if (traceMessages.Count > 5)
+            AnsiConsole.MarkupLine($"[dim]       ... and {traceMessages.Count - 5} more[/]");
+
+        return Task.FromResult(true);
+    }
+
     #endregion
 
     #region Test Infrastructure

src/NullOpsDevs.LibSsh/Core/SshTraceLevel.cs

@@ -0,0 +1,68 @@
+using JetBrains.Annotations;
+using NullOpsDevs.LibSsh.Generated;
+
+namespace NullOpsDevs.LibSsh.Core;
+
+/// <summary>
+/// Specifies the trace levels for libssh2 debugging output.
+/// These values can be combined using bitwise OR to enable multiple trace categories.
+/// </summary>
+[Flags]
+[PublicAPI]
+public enum SshTraceLevel
+{
+    /// <summary>
+    /// No tracing enabled.
+    /// </summary>
+    None = 0,
+
+    /// <summary>
+    /// Trace transport layer operations.
+    /// </summary>
+    Transport = LibSshNative.LIBSSH2_TRACE_TRANS,
+
+    /// <summary>
+    /// Trace key exchange operations.
+    /// </summary>
+    KeyExchange = LibSshNative.LIBSSH2_TRACE_KEX,
+
+    /// <summary>
+    /// Trace authentication operations.
+    /// </summary>
+    Authentication = LibSshNative.LIBSSH2_TRACE_AUTH,
+
+    /// <summary>
+    /// Trace connection layer operations.
+    /// </summary>
+    Connection = LibSshNative.LIBSSH2_TRACE_CONN,
+
+    /// <summary>
+    /// Trace SCP operations.
+    /// </summary>
+    Scp = LibSshNative.LIBSSH2_TRACE_SCP,
+
+    /// <summary>
+    /// Trace SFTP operations.
+    /// </summary>
+    Sftp = LibSshNative.LIBSSH2_TRACE_SFTP,
+
+    /// <summary>
+    /// Trace error messages.
+    /// </summary>
+    Error = LibSshNative.LIBSSH2_TRACE_ERROR,
+
+    /// <summary>
+    /// Trace public key operations.
+    /// </summary>
+    PublicKey = LibSshNative.LIBSSH2_TRACE_PUBLICKEY,
+
+    /// <summary>
+    /// Trace socket operations.
+    /// </summary>
+    Socket = LibSshNative.LIBSSH2_TRACE_SOCKET,
+
+    /// <summary>
+    /// Enable all trace levels.
+    /// </summary>
+    All = Transport | KeyExchange | Authentication | Connection | Scp | Sftp | Error | PublicKey | Socket
+}

src/NullOpsDevs.LibSsh/SshSession.cs

@@ -1,4 +1,5 @@
 using System.Net.Sockets;
+using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 using JetBrains.Annotations;
 using Microsoft.Extensions.Logging;
@@ -39,6 +40,12 @@ public sealed class SshSession(ILogger? logger = null) : IDisposable
 
     private readonly Dictionary<SshMethod, string> methodPreferences = new();
 
+#if NET5_0_OR_GREATER
+    // Trace handler support - maps session pointers to handlers
+    private static readonly Dictionary<nint, Action<string>> TraceHandlers = new();
+    private static readonly object TraceHandlersLock = new();
+#endif
+
     private void EnsureInitialized()
     {
         lock (LibSsh2.GlobalLock)
@@ -904,6 +911,69 @@ public Task<bool> AuthenticateAsync(SshCredential credential, CancellationToken
         return Task.Run(() => Authenticate(credential), cancellationToken);
     }
 
+#if NET5_0_OR_GREATER
+    /// <summary>
+    /// Sets the trace level bitmask and handler for libssh2 debugging output.
+    /// </summary>
+    /// <param name="traceLevel">A combination of <see cref="SshTraceLevel"/> flags indicating which categories to trace.</param>
+    /// <param name="handler">A callback function that receives trace messages. Pass null to disable tracing.</param>
+    /// <remarks>
+    /// <para>The session must be in <see cref="SshConnectionStatus.Connected"/> or <see cref="SshConnectionStatus.LoggedIn"/> status.</para>
+    /// <para>This method is only available on .NET 5.0 or later.</para>
+    /// </remarks>
+    /// <example>
+    /// <code>
+    /// session.SetTrace(SshTraceLevel.Authentication | SshTraceLevel.Error,
+    ///     message => Console.WriteLine($"[SSH] {message}"));
+    /// </code>
+    /// </example>
+    public unsafe void SetTrace(SshTraceLevel traceLevel, Action<string>? handler)
+    {
+        EnsureInitialized();
+        EnsureInStatuses(SshConnectionStatus.Connected, SshConnectionStatus.LoggedIn);
+
+        var sessionKey = (nint)SessionPtr;
+
+        lock (TraceHandlersLock)
+        {
+            if (handler == null || traceLevel == SshTraceLevel.None)
+            {
+                TraceHandlers.Remove(sessionKey);
+                libssh2_trace(SessionPtr, 0);
+                libssh2_trace_sethandler(SessionPtr, null, null);
+            }
+            else
+            {
+                TraceHandlers[sessionKey] = handler;
+                libssh2_trace(SessionPtr, (int)traceLevel);
+                libssh2_trace_sethandler(SessionPtr, (void*)sessionKey, &NativeTraceCallback);
+            }
+        }
+    }
+
+    [UnmanagedCallersOnly(CallConvs = [typeof(CallConvCdecl)])]
+    private static unsafe void NativeTraceCallback(_LIBSSH2_SESSION* session, void* context, sbyte* message, nuint length)
+    {
+        Action<string>? handler;
+        lock (TraceHandlersLock)
+        {
+            TraceHandlers.TryGetValue((nint)context, out handler);
+        }
+
+        if (handler == null) return;
+
+        try
+        {
+            var msg = length > 0 ? Marshal.PtrToStringUTF8((IntPtr)message, (int)length) : string.Empty;
+            handler(msg ?? string.Empty);
+        }
+        catch
+        {
+            // Swallow exceptions to prevent crashes in native code
+        }
+    }
+#endif
+
     /// <summary>
     /// Gets the last error message from the libssh2 session (for debugging).
     /// </summary>
@@ -930,6 +1000,14 @@ public unsafe void Dispose()
 
         if (SessionPtr != null)
         {
+#if NET5_0_OR_GREATER
+            // Clean up trace handler
+            lock (TraceHandlersLock)
+            {
+                TraceHandlers.Remove((nint)SessionPtr);
+            }
+#endif
+
             _ = libssh2_session_disconnect_ex(SessionPtr, SSH_DISCONNECT_BY_APPLICATION, StringPointers.SessionDisposed, null);
             _ = libssh2_session_free(SessionPtr);
             SessionPtr = null;