CommandLineSwitchServer.cs

using Microsoft.Extensions.Logging;
using System;
using System.IO;
using System.IO.Pipes;
using System.Net;
using System.Net.Sockets;
using System.Runtime.ExceptionServices;
using System.Runtime.InteropServices;
using System.Runtime.Versioning;
using System.Security.AccessControl;
using System.Security.Cryptography;
using System.Security.Principal;
using System.Text;
using System.Threading;
using System.Threading.Tasks;

namespace CommandLineSwitchPipe;

/// <summary>
/// Manages a named-pipe connection to send command-line switches to a running instance, or
/// if this is the only instance, to receive command-line switches after processing starts.
/// </summary>
public static class CommandLineSwitchServer
{
    /// <summary>
    /// The defaults are appropriate for most needs, but can also be created or modified through code,
    /// or populated from any of the standard .NET configuration extension packages.
    /// </summary>
    public static CommandLinePipeOptions Options { get; set; } = new CommandLinePipeOptions();

    /// <summary>
    /// Populated when TrySendArgs is invoked with the waitForReply flag set to true.
    /// </summary>
    public static string QueryResponse = string.Empty;

    /// <summary>
    /// Populated when TrySendArgs or TryConnect results in an exception.
    /// </summary>
    public static Exception TryException = null;

    /// <summary>
    /// DO NOT USE THIS DIRECTLY.
    /// It is created and used by the Log methods if Options.LoggerFactory is provided.
    /// </summary>
    private static ILogger Logger;

    /// <summary>
    /// Returns true if another instance is already running.
    /// </summary>
    public static async Task<bool> TryConnect(string server = null, int port = 0)
    {
        LogTrace($"{nameof(TryConnect)} starting for PID {Environment.ProcessId}");
        TryException = null;
        try
        {
            ValidateNetworkArgs(server, port);

            return (string.IsNullOrWhiteSpace(server))
                ? await TryConnectLocalNamedPipe().ConfigureAwait(false)
                : await TryConnectNetworkPort(server, port).ConfigureAwait(false);
        }
        catch (Exception ex)
        {
            LogException(ex);
            TryException = ex;
            return false;
        }
    }

    /// <summary>
    /// Attempt to send any command-line switches to an already-running instance. If another
    /// instance is found but this instance was started without switches, the application will
    /// terminate. Leave the argument list null unless Program.Main needs to pre-process that
    /// data. When null, the command line will be retrieved from the system environment.
    /// </summary>
    public static async Task<bool> TrySendArgs(string[] args = null, string server = null, int port = 0)
    {
        LogTrace($"{nameof(TrySendArgs)} starting for PID {Environment.ProcessId}");
        TryException = null;
        try
        {
            if (Options == null || Options.Advanced == null)
                throw new ArgumentNullException($"{nameof(CommandLineSwitchServer)}.{nameof(Options)} property must be configured before invoking {nameof(TrySendArgs)}");

            ValidateNetworkArgs(server, port);

            QueryResponse = string.Empty;

            // Use the provided arguments, or environment array 1+ (array 0 is the program name and/or pathname)
            var arguments = args ?? Environment.GetCommandLineArgs();
            if (args == null)
                arguments = arguments.Length == 1 ? new string[0] : arguments[1..];

            LogTrace($"Switch list has {arguments.Length} elements");

            // Send argument list with control-code separators
            var message = string.Empty;
            foreach (var arg in arguments) message += arg + Options.Advanced.SeparatorControlCode;

            return (string.IsNullOrWhiteSpace(server))
                ? await TrySendLocalNamedPipe(message).ConfigureAwait(false)
                : await TrySendNetworkPort(message, server, port).ConfigureAwait(false);
        }
        catch(Exception ex)
        {
            LogException(ex);
            TryException = ex;
            return false;
        }
    }

    /// <summary>
    /// Creates a named-pipe server that waits to receive command-line switches from another
    /// running instance. These are sent to the switchHandler delegate as they're received.
    /// </summary>
    public static async Task StartServer(Func<string[], string> switchHandler, CancellationToken cancellationToken, int port = 0)
    {
        // Cancelled by the caller for a normal shutdown, or by either listener when it fails terminally
        using CancellationTokenSource ctsListeners = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);

        ExceptionDispatchInfo failure = null;
        Task tcpListener = null;

        // Whichever listener fails first is the one reported; the other is stopped by the cancellation
        void ReportTerminalFailure(Exception ex)
        {
            Interlocked.CompareExchange(ref failure, ExceptionDispatchInfo.Capture(ex), null);
            ctsListeners.Cancel();
        }

        try
        {
            if (Options == null || Options.Advanced == null)
                throw new ArgumentNullException($"{nameof(CommandLineSwitchServer)}.{nameof(Options)} property must be configured before invoking {nameof(StartServer)}");

            if (switchHandler == null)
                throw new ArgumentNullException(paramName: nameof(switchHandler));

            if (port != 0)
            {
                ValidatePortArgs(port);
                tcpListener = Task.Run(() => StartTCPServer(switchHandler, ctsListeners.Token, port, ReportTerminalFailure), ctsListeners.Token);
            }

            await ListenOnNamedPipe(switchHandler, ctsListeners.Token).ConfigureAwait(false);
        }
        catch (OperationCanceledException)
        {
            Log(LogLevel.Trace, "Switch server namedpipe listener caught OperationCanceledException");
        }
        catch (Exception ex)
        {
            LogException(ex);
            ReportTerminalFailure(ex);
        }
        finally
        {
            ctsListeners.Cancel();

            if (tcpListener != null)
            {
                try
                {
                    await tcpListener.ConfigureAwait(false);
                }
                catch (OperationCanceledException)
                { }
                catch (Exception ex)
                {
                    LogException(ex);
                }
            }

            LogTrace("Switch server has stopped listening on namedpipe");
        }

        if (failure != null)
        {
            // Advanced options can be missing here, and the pre-v2.2.0 behavior was to terminate
            if (Options?.Advanced?.ExitOnServerFailure ?? true)
            {
                Log(LogLevel.Critical, $"Switch server forcibly terminating process in {nameof(StartServer)}");
                Environment.Exit(-1);
            }

            failure.Throw();
        }
    }

    private static async Task ListenOnNamedPipe(Func<string[], string> switchHandler, CancellationToken cancellationToken)
    {
        RestartTracker tracker = new();

        while (!cancellationToken.IsCancellationRequested)
        {
            try
            {
                using var server = CreatePipeServer();
                tracker.Established = true;

                LogTrace($"Switch server waiting for connection on namedpipe \"{PipeName()}\"");
                await server.WaitForConnectionAsync(cancellationToken).ConfigureAwait(false);
                Log(LogLevel.Trace, $"Switch server exited namedpipe {nameof(server.WaitForConnectionAsync)}");
                cancellationToken.ThrowIfCancellationRequested();
                LogTrace("Switch client has connected to namedpipe server");
                tracker.Restarts = 0;

                var message = await ReadStringFromPipe(server);

                if (!string.IsNullOrWhiteSpace(message))
                {
                    // Split into original arg array
                    var args = message.Split(Options.Advanced.SeparatorControlCode, StringSplitOptions.RemoveEmptyEntries);

                    // Process the switches, but prevent any handler exceptions from bringing down the server
                    LogTrace($"Invoking switch handler for {args.Length} switches");
                    try
                    {
                        var response = switchHandler.Invoke(args) ?? string.Empty;
                        await WriteStringToPipe(server, response);
                    }
                    catch (Exception ex)
                    {
                        Log(LogLevel.Warning, $"{ex.GetType().Name} trapped from switch handler");
                    }

                    try
                    {
                        // Goodbye, client
                        if(server.IsConnected)
                        {
                            server.Disconnect();
                            LogTrace("Switch server terminated client namedpipe connection");
                        }
                        else
                        {
                            LogTrace("Switch server connection was terminated by namedpipe client");
                        }
                    }
                    catch (Exception ex)
                    {
                        Log(LogLevel.Warning, $"{ex.GetType().Name} while trying to disconnect from namedpipe client");
                    }
                }
            }
            catch (OperationCanceledException)
            {
                // Shutdown is not a restartable failure
                throw;
            }
            catch (Exception ex)
            {
                if (await TryRestartListener("namedpipe", ex, tracker, cancellationToken).ConfigureAwait(false)) continue;
                if (cancellationToken.IsCancellationRequested) return;
                throw;
            }
        }
    }

    private static async Task StartTCPServer(Func<string[], string> switchHandler, CancellationToken cancellationToken, int port, Action<Exception> reportTerminalFailure)
    {
        RestartTracker tracker = new();

        try
        {
            while (!cancellationToken.IsCancellationRequested)
            {
                TcpListener server = null;

                try
                {
                    server = new TcpListener(IPAddress.Any, port);
                    server.Start(); // This merely queues connection requests
                    tracker.Established = true;

                    while (!cancellationToken.IsCancellationRequested)
                    {
                        LogTrace($"Switch server waiting for connection on TCP port {port}");
                        using var client = await server.AcceptTcpClientAsync(cancellationToken).ConfigureAwait(false);
                        Log(LogLevel.Trace, $"Switch server exited TCP {nameof(server.AcceptTcpClientAsync)}");
                        cancellationToken.ThrowIfCancellationRequested();
                        LogTrace("Switch client has connected to TCP port");
                        tracker.Restarts = 0;

                        string activity = string.Empty;
                        try
                        {
                            activity = "reading data from TCP client";
                            var message = await ReadStringFromNetworkPort(client);

                            if (!string.IsNullOrWhiteSpace(message))
                            {
                                // Split into original arg array
                                var args = message.Split(Options.Advanced.SeparatorControlCode, StringSplitOptions.RemoveEmptyEntries);

                                // Process the switches
                                LogTrace($"Invoking switch handler for {args.Length} switches");
                                activity = "invoking switch handler";
                                var response = switchHandler.Invoke(args) ?? string.Empty;

                                // Can't rely on client.Connected since TCP is stateless
                                activity = "sending response to TCP client";
                                await WriteStringToNetworkPort(client, response).ConfigureAwait(false);
                            }
                        }
                        catch (Exception ex)
                        {
                            Log(LogLevel.Warning, $"{ex.GetType().Name} trapped {activity}");
                        }
                        finally
                        {
                            // Close is handled by Dispose
                            client.Dispose();
                        }
                    }
                }
                catch (OperationCanceledException)
                {
                    Log(LogLevel.Trace, "Switch server TCP listener caught OperationCanceledException");
                    return;
                }
                catch (Exception ex)
                {
                    if (await TryRestartListener("TCP", ex, tracker, cancellationToken).ConfigureAwait(false)) continue;
                    if (cancellationToken.IsCancellationRequested) return;

                    // StartServer decides whether this terminates the process or is re-thrown
                    LogException(ex);
                    reportTerminalFailure.Invoke(ex);
                    return;
                }
                finally
                {
                    server?.Stop();
                }
            }
        }
        finally
        {
            LogTrace("Switch server has stopped listening on TCP");
        }
    }

    /// <summary>
    /// Returns true if the caller should re-establish the listener. A false return means the failure is
    /// terminal, unless the cancellation token indicates the server is shutting down.
    /// </summary>
    private static async Task<bool> TryRestartListener(string listener, Exception ex, RestartTracker tracker, CancellationToken cancellationToken)
    {
        if (cancellationToken.IsCancellationRequested) return false;

        // Auto-restart does not apply until the listener has been established at least once
        if (!tracker.Established || !Options.Advanced.AutoRestartServer) return false;

        tracker.Restarts++;
        if (Options.Advanced.AutoRestartAttempts > 0 && tracker.Restarts > Options.Advanced.AutoRestartAttempts)
        {
            Log(LogLevel.Warning, $"Switch server {listener} listener failed after {Options.Advanced.AutoRestartAttempts} restart attempts");
            return false;
        }

        LogException(ex);
        Log(LogLevel.Warning, $"Restarting switch server {listener} listener in {Options.Advanced.AutoRestartDelay}ms (attempt {tracker.Restarts})");

        try
        {
            await Task.Delay(Options.Advanced.AutoRestartDelay, cancellationToken).ConfigureAwait(false);
        }
        catch (OperationCanceledException)
        {
            return false;
        }

        return true;
    }

    private static async Task<bool> TryConnectLocalNamedPipe()
    {
        Log(LogLevel.Trace, $"{nameof(TryConnectLocalNamedPipe)} invoked");

        using var client = new NamedPipeClientStream(".", PipeName(), PipeDirection.InOut);

        try
        {
            await client.ConnectAsync(Options.Advanced.PipeConnectionTimeout).ConfigureAwait(false);
        }
        catch (TimeoutException)
        {
            LogTrace($"{nameof(TryConnectLocalNamedPipe)}: No running instance found");
            return false;
        }

        LogTrace($"{nameof(TryConnectLocalNamedPipe)}: Running instance found");
        return true;
    }

    private static async Task<bool> TryConnectNetworkPort(string server, int port)
    {
        Log(LogLevel.Trace, $"{nameof(TryConnectNetworkPort)}(server:{server}, port:{port}) invoked");

        var addresses = await Dns.GetHostAddressesAsync(server, (AddressFamily)Options.Advanced.DnsAddressFamily, CancellationToken.None);
        if (addresses.Length == 0) throw new ArgumentException("Could not resolve address for host name");

        using TcpClient client = new();
        try
        {
            await client.ConnectAsync(addresses, port).ConfigureAwait(false);
        }
        catch (SocketException ex)
        {
            if(ex.SocketErrorCode == SocketError.ConnectionRefused)
            {
                LogTrace($"{nameof(TryConnectNetworkPort)}: No running instance found");
                return false;
            }
            throw;
        }

        LogTrace($"{nameof(TryConnectNetworkPort)}: Running instance found");
        return client.Connected;
    }

    private static async Task<bool> TrySendLocalNamedPipe(string message)
    {
        Log(LogLevel.Trace, $"{nameof(TrySendLocalNamedPipe)} invoked");

        LogTrace($"Checking for a running instance on pipe \"{PipeName()}\"");

        using var client = new NamedPipeClientStream(".", PipeName(), PipeDirection.InOut);

        try
        {
            await client.ConnectAsync(Options.Advanced.PipeConnectionTimeout).ConfigureAwait(false);
        }
        catch (TimeoutException)
        {
            LogTrace($"No running instance found");
            return false;
        }

        LogTrace($"Connected to switch pipe server");

        // Connected, abort if we don't have arguments to pass
        if (string.IsNullOrEmpty(message))
        {
            LogTrace("No arguments to pass to the running instance.");

            if(Options.Advanced.ThrowIfRunning)
                throw new ArgumentException("No arguments were provided to pass to the already-running instance");

            LogTrace("Not configured to throw an exception; forcing an exit");
            Environment.Exit(-1);
        }

        LogTrace("Sending switches to running instance");
        await WriteStringToPipe(client, message).ConfigureAwait(false);

        LogTrace("Waiting for reply");
        QueryResponse = await ReadStringFromPipe(client).ConfigureAwait(false);
        Log(LogLevel.Debug, $"Received:\n{QueryResponse}");

        LogTrace($"Switches sent, PID {Environment.ProcessId} can terminate normally");
        return true;
    }

    private static async Task<bool> TrySendNetworkPort(string message, string server, int port)
    {
        Log(LogLevel.Trace, $"{nameof(TrySendNetworkPort)} invoked");

        LogTrace($"Checking for a running instance on server {server}:{port}");

        var addresses = await Dns.GetHostAddressesAsync(server, (AddressFamily)Options.Advanced.DnsAddressFamily, CancellationToken.None);
        if (addresses.Length == 0) throw new ArgumentException("Could not resolve address for host name");
        LogTrace($"Resolved {addresses.Length} addresses for server {server}");

        using TcpClient client = new();
        try
        {
            await client.ConnectAsync(addresses, port).ConfigureAwait(false);
        }
        catch (SocketException ex)
        {
            if (ex.SocketErrorCode == SocketError.ConnectionRefused)
            {
                LogTrace($"{nameof(TryConnectNetworkPort)}: No running instance found");
                return false;
            }
            throw;
        }
        if (!client.Connected) throw new Exception("Failed to connect, but no framework exception was thrown");

        LogTrace($"Connected to switch pipe server");

        // Connected, abort if we don't have arguments to pass
        if (string.IsNullOrEmpty(message))
        {
            LogTrace("No arguments to pass to the running instance.");

            if (Options.Advanced.ThrowIfRunning)
                throw new ArgumentException("No arguments were provided to pass to the already-running instance");

            LogTrace("Not configured to throw an exception; forcing an exit");
            Environment.Exit(-1);
        }

        LogTrace("Sending switches to running instance");
        await WriteStringToNetworkPort(client, message).ConfigureAwait(false);

        LogTrace("Waiting for reply");
        QueryResponse = await ReadStringFromNetworkPort(client).ConfigureAwait(false);
        Log(LogLevel.Debug, $"Received:\n{QueryResponse}");

        LogTrace($"Switches sent, PID {Environment.ProcessId} can terminate normally");
        return true;
    }

    private static async Task WriteStringToPipe(PipeStream stream, string message)
    {
        Log(LogLevel.Trace, $"{nameof(WriteStringToPipe)} invoked");

        if (message.Length == 0) return;

        try
        {
            var messageBuffer = Options.Advanced.Encoding.GetBytes(message);
            LogTrace($"Sending {messageBuffer.Length} bytes");

            var sizeBuffer = BitConverter.GetBytes(messageBuffer.Length);
            await stream.WriteAsync(sizeBuffer, 0, sizeBuffer.Length).ConfigureAwait(false);

            await stream.WriteAsync(messageBuffer, 0, messageBuffer.Length).ConfigureAwait(false);

            await stream.FlushAsync().ConfigureAwait(false);

            if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
            {
                stream.WaitForPipeDrain();
            }
            else
            {
                await Task.Delay(Options.Advanced.LinuxWaitAfterWriteMS).ConfigureAwait(false);
            }
        }
        catch (Exception ex)
        {
            Log(LogLevel.Warning, $"{ex.GetType().Name} while writing to PipeStream");
        }
    }

    private static async Task<string> ReadStringFromPipe(PipeStream stream)
    {
        Log(LogLevel.Trace, $"{nameof(ReadStringFromPipe)} invoked");

        string response = string.Empty;

        try
        {
            using var reader = new BinaryReader(stream, Options.Advanced.Encoding, leaveOpen: true);

            // Read the length of the message, then the message itself
            var size = reader.ReadInt32();
            LogTrace($"Receiving {size} bytes");

            if (size > 0)
            {
                var buffer = reader.ReadBytes(size);
                response = Options.Advanced.Encoding.GetString(buffer);
            }

            await stream.FlushAsync().ConfigureAwait(false);
        }
        catch(EndOfStreamException)
        { } // normal, disregard
        catch (Exception ex)
        {
            Log(LogLevel.Warning, $"{ex.GetType().Name} while reading from PipeStream");
        }

        return response;
    }

    private static async Task WriteStringToNetworkPort(TcpClient client, string message)
    {
        Log(LogLevel.Trace, $"{nameof(WriteStringToNetworkPort)} invoked");

        if (string.IsNullOrEmpty(message)) return;

        try
        {
            var stream = client.GetStream();

            var messageBuffer = Options.Advanced.Encoding.GetBytes(message);
            var minBuff = Math.Min(client.SendBufferSize, client.ReceiveBufferSize);
            if (messageBuffer.Length > minBuff) throw new ArgumentException($"Message with delimiters exceeds {minBuff} byte buffer size");

            LogTrace($"Sending {messageBuffer.Length} bytes");
            await stream.WriteAsync(messageBuffer, 0, messageBuffer.Length).ConfigureAwait(false);
            await stream.FlushAsync().ConfigureAwait(false);
        }
        catch (Exception ex)
        {
            Log(LogLevel.Warning, $"{ex.GetType().Name} while writing to NetworkStream");
        }
    }

    private static async Task<string> ReadStringFromNetworkPort(TcpClient client)
    {
        Log(LogLevel.Trace, $"{nameof(ReadStringFromNetworkPort)} invoked");

        string response = string.Empty;

        try
        {
            var stream = client.GetStream();

            var maxBuff = Math.Max(client.SendBufferSize, client.ReceiveBufferSize);
            var messageBuffer = new byte[maxBuff];
            var bytes = await stream.ReadAsync(messageBuffer, 0, maxBuff).ConfigureAwait(false);
            await stream.FlushAsync().ConfigureAwait(false);
            LogTrace($"Received {bytes} bytes");

            response = Options.Advanced.Encoding.GetString(messageBuffer, 0, bytes);
        }
        catch (EndOfStreamException)
        { } // normal, disregard
        catch (Exception ex)
        {
            Log(LogLevel.Warning, $"{ex.GetType().Name} while reading from NetworkStream");
        }

        return response;
    }

    // The library deliberately imposes no access control -- any local user can connect and send
    // switches, and the receiving application decides whether to honor them. That intent is not
    // what either OS does by default. Windows gives the pipe the creating token's default DACL,
    // which excludes ordinary users when the server runs as a service, and .NET on Linux and MacOS
    // creates the underlying socket subject to the process umask. Both are opened up here so that
    // the documented behavior is the actual behavior.
    private static NamedPipeServerStream CreatePipeServer()
    {
        if (OperatingSystem.IsWindows()) return CreateWindowsPipeServer();

        var server = new NamedPipeServerStream(PipeName(), PipeDirection.InOut, 1, PipeTransmissionMode.Byte, PipeOptions.Asynchronous);

        // Named pipes are Unix domain sockets here, and connecting to one requires write permission.
        // The socket pathname is an implementation detail of the runtime, but a stable one -- the
        // runtime cannot change it without breaking version-to-version connectivity.
        try
        {
            var pathname = Path.IsPathRooted(PipeName())
                ? PipeName()
                : Path.Combine(Path.GetTempPath(), $"CoreFxPipe_{PipeName()}");

            File.SetUnixFileMode(pathname,
                UnixFileMode.UserRead | UnixFileMode.UserWrite | UnixFileMode.UserExecute
                | UnixFileMode.GroupRead | UnixFileMode.GroupWrite | UnixFileMode.GroupExecute
                | UnixFileMode.OtherRead | UnixFileMode.OtherWrite | UnixFileMode.OtherExecute);

            LogTrace($"Namedpipe socket \"{pathname}\" opened to all users");
        }
        catch (Exception ex)
        {
            // Not fatal, the pipe still works -- it may just be unreachable by other users
            Log(LogLevel.Warning, $"{ex.GetType().Name} setting namedpipe socket permissions, other users may be unable to connect");
        }

        return server;
    }

    [SupportedOSPlatform("windows")]
    private static NamedPipeServerStream CreateWindowsPipeServer()
    {
        var security = new PipeSecurity();

        // An explicit DACL replaces the token default entirely, so the owner has to be re-granted
        // the rights it would otherwise have had, including creating further pipe instances
        using (var identity = WindowsIdentity.GetCurrent())
            security.AddAccessRule(new PipeAccessRule(identity.Owner, PipeAccessRights.FullControl, AccessControlType.Allow));

        security.AddAccessRule(new PipeAccessRule(
            new SecurityIdentifier(WellKnownSidType.WorldSid, null), PipeAccessRights.ReadWrite, AccessControlType.Allow));

        LogTrace("Namedpipe opened to all users");

        return NamedPipeServerStreamAcl.Create(PipeName(), PipeDirection.InOut, 1, PipeTransmissionMode.Byte, PipeOptions.Asynchronous, 0, 0, security);
    }

    private static string PipeName()
        => string.IsNullOrWhiteSpace(Options.PipeName) ? DefaultPipeName() : Options.PipeName;

    // The default is the application filename plus a short hash of the full pathname. Prior to
    // v2.0.2 the raw pathname was used, which is destructive on Linux and MacOS: .NET backs named
    // pipes with Unix domain sockets, a rooted pipe name is used verbatim as the socket pathname,
    // and the runtime unlinks whatever is already there -- silently deleting the application's own
    // assembly. Hashing the pathname retains its uniqueness, so that separate installations of the
    // same program (production and staging, for example) still get separate pipes.
    private static string DefaultPipeName()
    {
        var pathname = Environment.GetCommandLineArgs()[0];
        if (string.IsNullOrWhiteSpace(pathname)) pathname = nameof(CommandLineSwitchPipe);

        // Windows pathnames are case-insensitive, Linux and MacOS pathnames are not
        var hashable = RuntimeInformation.IsOSPlatform(OSPlatform.Windows) ? pathname.ToLowerInvariant() : pathname;

        // Not string.GetHashCode, which is randomized per-process, meaning the client and the
        // server would derive different names. This only has to be stable and short, not secure.
        var hash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(hashable)), 0, 4);

        // Truncated because Unix domain socket pathnames are limited to about 100 characters
        var filename = Path.GetFileName(pathname);
        if (filename.Length > 32) filename = filename[..32];

        return $"{filename}_{hash}";
    }

    private static void ValidateNetworkArgs(string server, int port)
    {
        // local named pipe
        if (string.IsNullOrWhiteSpace(server))
        {
            if (port != 0) throw new ArgumentException("Local servers do not use a TCP port assignment");
        }
        // remote server
        else
        {
            ValidatePortArgs(port);
        }
    }

    private static void ValidatePortArgs(int port)
    {
        if (port < 1 || port > 65536) throw new ArgumentException("Invalid TCP port number");
        if (port < 49151) Log(LogLevel.Warning, "TCP port numbers below 49152 may be reserved");
    }

    private static void Log(LogLevel logLevel, string message)
    {
        if (Options.LoggerFactory is null) return;
        if (Logger is null) Logger = Options.LoggerFactory.CreateLogger(nameof(CommandLineSwitchPipe));
        Logger.Log(logLevel, message);
    }

    private static void LogTrace(string message)
    {
        Log(LogLevel.Trace, message);
    }

    /// <summary>
    /// Auto-restart state. The named pipe server and the optional TCP listener track this independently.
    /// </summary>
    private sealed class RestartTracker
    {
        /// <summary>
        /// True once the listener has been established at least once. Auto-restart does not apply
        /// until the initial attempt succeeds.
        /// </summary>
        public bool Established = false;

        /// <summary>
        /// Restart attempts, reset whenever the listener accepts a connection.
        /// </summary>
        public int Restarts = 0;
    }

    private static void LogException(Exception ex)
    {
        Log(LogLevel.Error, $"Exception {ex.GetType().Name}: {ex.Message}");
        Log(LogLevel.Error, ex.StackTrace);

        var inner = ex.InnerException;
        while(inner is not null)
        {
            Log(LogLevel.Error, $"Inner exception {ex.InnerException.GetType().Name}: {ex.InnerException.Message}");
            inner = ex.InnerException;
        }
    }
}