Adds 'requiredPorts' functionality

I find people often have processes running locally which have port usages similar to those that we wish to spin-up via this library. E.g. a local proxy to a cloud instance of the DB which their app uses. This leads to annoyance and hunting through sometimes cryptic docker compose log lines to discover a simple problem which could have been proactively checked for (fast-fail) prior to docker compose up being invoked.

This PR introduces an optional property 'RequiredPorts' which will be checked for before running docker compose up. If any ports are found to be in use, a custom exception is raised and the clashing ports are surfaced on the 'Ports' property of this exception instance.

Author: christophergunn

DockerComposeFixture.Tests/DockerFixtureTests.cs

@@ -125,7 +125,7 @@ public void Init_Throws_IfTestIsNeverTrue()
         [Fact]
         public void Init_MonitorsServices_WhenTheyStartSlowly()
         {
-            Stopwatch stopwatch = new Stopwatch();
+            var stopwatch = new Stopwatch();
             var compose = new Mock<IDockerCompose>();
             compose.Setup(c => c.PauseMs).Returns(100);
             compose.Setup(c => c.Up())
@@ -158,7 +158,7 @@ public void Init_Throws_WhenServicesFailToStart()
         {
             var compose = new Mock<IDockerCompose>();
             compose.Setup(c => c.PauseMs).Returns(NumberOfMsInOneSec);
-            bool firstTime = true;
+            var firstTime = true;
             compose.Setup(c => c.PsWithJsonFormat())
                 .Returns(() =>
                 {
@@ -191,7 +191,7 @@ public void Init_Throws_WhenYmlFileDoesntExist()
             compose.Setup(c => c.PsWithJsonFormat())
                 .Returns(new[] { "non-json-message", "{ \"Status\": \"Up 3 seconds\" }", "{ \"Status\": \"Up 15 seconds\" }" });
 
-            string fileDoesntExist = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString());
+            var fileDoesntExist = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString());
             Assert.Throws<ArgumentException>(() =>
                 new DockerFixture(null).Init(new[] { fileDoesntExist }, "up", "down", 120, null, compose.Object));
         }

DockerComposeFixture.Tests/Utils/ObservableCounter.cs

@@ -16,7 +16,7 @@ public IDisposable Subscribe(IObserver<string> observer)
 
         public void Count(int min = 1, int max = 10, int delay = 10)
         {
-            for (int i = min; i <= max; i++)
+            for (var i = min; i <= max; i++)
             {
                 this.observalbes.ForEach(o => o.OnNext(i.ToString()));
                 Thread.Sleep(delay);

DockerComposeFixture/DockerFixture.cs

@@ -21,6 +21,7 @@ public class DockerFixture : IDisposable
         private ILogger[] loggers;
         private int startupTimeoutSecs;
         private readonly IMessageSink output;
+        private ushort[] requiredPorts;
 
         public DockerFixture(IMessageSink output)
         {
@@ -31,7 +32,7 @@ public DockerFixture(IMessageSink output)
         /// Initialize docker compose services from file(s) but only once.
         /// If you call this multiple times on the same DockerFixture then it will be ignored.
         /// </summary>
-        /// <param name="setupOptions">Options that control how docker-compose is executed.</param>
+        /// <param name="setupOptions">Options that control how docker compose is executed.</param>
         public void InitOnce(Func<IDockerFixtureOptions> setupOptions)
         {
             InitOnce(setupOptions, null);
@@ -41,7 +42,7 @@ public void InitOnce(Func<IDockerFixtureOptions> setupOptions)
         /// Initialize docker compose services from file(s) but only once.
         /// If you call this multiple times on the same DockerFixture then it will be ignored.
         /// </summary>
-        /// <param name="setupOptions">Options that control how docker-compose is executed.</param>
+        /// <param name="setupOptions">Options that control how docker compose is executed.</param>
         /// <param name="dockerCompose"></param>
         public void InitOnce(Func<IDockerFixtureOptions> setupOptions, IDockerCompose dockerCompose)
         {
@@ -56,7 +57,7 @@ public void InitOnce(Func<IDockerFixtureOptions> setupOptions, IDockerCompose do
         /// <summary>
         /// Initialize docker compose services from file(s).
         /// </summary>
-        /// <param name="setupOptions">Options that control how docker-compose is executed</param>
+        /// <param name="setupOptions">Options that control how docker compose is executed</param>
         public void Init(Func<IDockerFixtureOptions> setupOptions)
         {
             Init(setupOptions, null);
@@ -65,18 +66,25 @@ public void Init(Func<IDockerFixtureOptions> setupOptions)
         /// <summary>
         /// Initialize docker compose services from file(s).
         /// </summary>
-        /// <param name="setupOptions">Options that control how docker-compose is executed</param>
+        /// <param name="setupOptions">Options that control how docker compose is executed</param>
         /// <param name="compose"></param>
         public void Init(Func<IDockerFixtureOptions> setupOptions, IDockerCompose compose)
         {
             var options = setupOptions();
             options.Validate();
-            string logFile = options.DebugLog
+            var logFile = options.DebugLog
                 ? Path.Combine(Path.GetTempPath(), $"docker-compose-{DateTime.Now.Ticks}.log")
                 : null;
 
-            this.Init(options.DockerComposeFiles, options.DockerComposeUpArgs, options.DockerComposeDownArgs,
-                options.StartupTimeoutSecs, options.CustomUpTest, compose, this.GetLoggers(logFile).ToArray());
+            this.Init(
+                options.DockerComposeFiles, 
+                options.DockerComposeUpArgs,
+                options.DockerComposeDownArgs,
+                options.StartupTimeoutSecs,
+                options.CustomUpTest,
+                compose, 
+                this.GetLoggers(logFile).ToArray(), 
+                options.RequiredPorts);
         }
 
         private IEnumerable<ILogger> GetLoggers(string file)
@@ -97,22 +105,24 @@ private IEnumerable<ILogger> GetLoggers(string file)
         /// Initialize docker compose services from file(s).
         /// </summary>
         /// <param name="dockerComposeFiles">Array of docker compose files</param>
-        /// <param name="dockerComposeUpArgs">Arguments to append after 'docker-compose -f file.yml up'</param>
-        /// <param name="dockerComposeDownArgs">Arguments to append after 'docker-compose -f file.yml down'</param>
+        /// <param name="dockerComposeUpArgs">Arguments to append after 'docker compose -f file.yml up'</param>
+        /// <param name="dockerComposeDownArgs">Arguments to append after 'docker compose -f file.yml down'</param>
         /// <param name="startupTimeoutSecs">How long to wait for the application to start before giving up</param>
-        /// <param name="customUpTest">Checks whether the docker-compose services have come up correctly based upon the output of docker-compose</param>
+        /// <param name="customUpTest">Checks whether the docker compose services have come up correctly based upon the output of docker compose</param>
         /// <param name="dockerCompose"></param>
         /// <param name="logger"></param>
+        /// <param name="requiredPorts">Checks that these ports are available on the host network (not in use by other processes)</param>
         public void Init(string[] dockerComposeFiles, string dockerComposeUpArgs, string dockerComposeDownArgs,
             int startupTimeoutSecs, Func<string[], bool> customUpTest = null,
-            IDockerCompose dockerCompose = null, ILogger[] logger = null)
+            IDockerCompose dockerCompose = null, ILogger[] logger = null, ushort[] requiredPorts = null)
         {
             this.loggers = logger ?? GetLoggers(null).ToArray();
 
             var dockerComposeFilePaths = dockerComposeFiles.Select(this.GetComposeFilePath);
             this.dockerCompose = dockerCompose ?? new DockerCompose(this.loggers);
             this.customUpTest = customUpTest;
             this.startupTimeoutSecs = startupTimeoutSecs;
+            this.requiredPorts = requiredPorts;
 
             this.dockerCompose.Init(
                 string.Join(" ",
@@ -129,7 +139,7 @@ private string GetComposeFilePath(string file)
                 return file;
             }
 
-            DirectoryInfo curDir = new DirectoryInfo(AppDomain.CurrentDomain.BaseDirectory);
+            var curDir = new DirectoryInfo(AppDomain.CurrentDomain.BaseDirectory);
             if (File.Exists(Path.Combine(curDir.FullName, file)))
             {
                 return Path.Combine(curDir.FullName, file);
@@ -139,7 +149,7 @@ private string GetComposeFilePath(string file)
             {
                 while (curDir != null)
                 {
-                    string curFile = Path.Combine(curDir.FullName, file);
+                    var curFile = Path.Combine(curDir.FullName, file);
                     if (File.Exists(curFile))
                     {
                         return curFile;
@@ -169,7 +179,7 @@ public static async Task Kill(string applicationName, bool killEverything = fals
         /// <returns></returns>
         public static async Task Kill(Regex filterRx, bool killEverything = false)
         {
-            Process ps = Process.Start(new ProcessStartInfo("docker", "ps")
+            var ps = Process.Start(new ProcessStartInfo("docker", "ps")
             {
                 UseShellExecute = false,
                 RedirectStandardOutput = true
@@ -187,7 +197,6 @@ public static async Task Kill(Regex filterRx, bool killEverything = false)
             {
                 Process.Start("docker", $"kill {id}").WaitForExit();
             }
-
         }
 
         public virtual void Dispose()
@@ -203,14 +212,21 @@ private void Start()
                 this.Stop();
             }
 
+            if (requiredPorts != null && requiredPorts.Length > 0)
+            {
+                this.loggers.Log("---- checking for port availability ----");
+                this.CheckForRequiredPorts();
+                this.loggers.Log("---- all required host ports are available ----");
+            }
+
             this.loggers.Log("---- starting docker services ----");
             var upTask = this.dockerCompose.Up();
 
-            for (int i = 0; i < this.startupTimeoutSecs; i++)
+            for (var i = 0; i < this.startupTimeoutSecs; i++)
             {
                 if (upTask.IsCompleted)
                 {
-                    this.loggers.Log("docker-compose exited prematurely");
+                    this.loggers.Log("docker compose exited prematurely");
                     break;
                 }
                 this.loggers.Log($"---- checking docker services ({i + 1}/{this.startupTimeoutSecs}) ----");
@@ -235,7 +251,16 @@ private void Start()
             }
             throw new DockerComposeException(this.loggers.GetLoggedLines());
         }
-        
+
+        private void CheckForRequiredPorts()
+        {
+            var usedPorts = Ports.DetermineUtilizedPorts(requiredPorts);
+            if (usedPorts.Any())
+            {
+                throw new PortsUnavailableException(this.loggers.GetLoggedLines(), usedPorts);
+            }
+        }
+
         private (bool hasContainers, bool containersAreUp) CheckIfRunning()
         {
             var lines = dockerCompose.PsWithJsonFormat()

DockerComposeFixture/DockerFixtureOptions.cs

@@ -3,12 +3,21 @@
 namespace DockerComposeFixture
 {
     /// <summary>
-    /// Options that control how docker-compose is executed
+    /// Options that control how docker compose is executed
     /// </summary>
     public class DockerFixtureOptions : IDockerFixtureOptions
     {
         /// <summary>
-        /// Checks whether the docker-compose services have come up correctly based upon the output of docker-compose
+        /// An array of ports required to be available on the host in order for the docker compose services
+        /// to start. Provides a fail-fast check along with aiding developers to easier debug issues related
+        /// to running other programs locally with clashing ports.
+        /// If null or empty - no ports are checked.
+        /// If any required ports are reserved by other processes - throws an 'PortsUnavailableException'.
+        /// </summary>
+        public ushort[] RequiredPorts { get; set; }
+
+        /// <summary>
+        /// Checks whether the docker compose services have come up correctly based upon the output of docker compose
         /// </summary>
         public Func<string[], bool> CustomUpTest { get; set; }
 
@@ -19,17 +28,17 @@ public class DockerFixtureOptions : IDockerFixtureOptions
         /// </summary>
         public string[] DockerComposeFiles { get; set; } = new[] { "docker-compose.yml" };
         /// <summary>
-        /// When true this logs docker-compose output to %temp%\docker-compose-*.log
+        /// When true this logs docker compose output to %temp%\docker-compose-*.log
         /// </summary>
         public bool DebugLog { get; set; }
         /// <summary>
-        /// Arguments to append after 'docker-compose -f file.yml up'
-        /// Default is 'docker-compose -f file.yml up' you can append '--build' if you want it to always build
+        /// Arguments to append after 'docker compose -f file.yml up'
+        /// Default is 'docker compose -f file.yml up' you can append '--build' if you want it to always build
         /// </summary>
         public string DockerComposeUpArgs { get; set; } = "";
         /// <summary>
-        /// Arguments to append after 'docker-compose -f file.yml down'
-        /// Default is 'docker-compose -f file.yml down --remove-orphans' you can add '--rmi all' if you want to guarantee a fresh build on each test
+        /// Arguments to append after 'docker compose -f file.yml down'
+        /// Default is 'docker compose -f file.yml down --remove-orphans' you can add '--rmi all' if you want to guarantee a fresh build on each test
         /// </summary>
         public string DockerComposeDownArgs { get; set; } = "--remove-orphans";
 

DockerComposeFixture/Exceptions/DockerComposeException.cs

@@ -2,9 +2,10 @@
 
 namespace DockerComposeFixture.Exceptions
 {
-    public class DockerComposeException:Exception
+    public class DockerComposeException : Exception
     {
-        public DockerComposeException(string[] loggedLines):base($"docker-compose failed - see {nameof(DockerComposeOutput)} property")
+        public DockerComposeException(string[] loggedLines)
+            : base($"docker compose failed - see {nameof(DockerComposeOutput)} property")
         {
             this.DockerComposeOutput = loggedLines;
         }

DockerComposeFixture/Exceptions/PortsUnavailableException.cs

@@ -0,0 +1,14 @@
+using System;
+
+namespace DockerComposeFixture.Exceptions
+{
+    public class PortsUnavailableException : DockerComposeException
+    {
+        public PortsUnavailableException(string[] loggedLines, ushort[] ports) : base(loggedLines)
+        {
+            Ports = ports;
+        }
+
+        public ushort[] Ports { get; set; }
+    }
+}

DockerComposeFixture/IDockerFixtureOptions.cs

@@ -4,6 +4,7 @@ namespace DockerComposeFixture
 {
     public interface IDockerFixtureOptions
     {
+        UInt16[] RequiredPorts { get; set; }
         Func<string[], bool> CustomUpTest { get; set; }
         string[] DockerComposeFiles { get; set; }
         bool DebugLog { get; set; }

DockerComposeFixture/Ports.cs

@@ -0,0 +1,31 @@
+using System;
+using System.Linq;
+using System.Net.NetworkInformation;
+
+namespace DockerComposeFixture
+{
+    public static class Ports
+    {
+        // check if network port is open
+        public static ushort[] DetermineUtilizedPorts(ushort[] ports)
+        {
+            return ports.Where(p => !IsPortAvailable(p)).ToArray();
+        }
+
+        private static bool IsPortAvailable(UInt16 port)
+        {
+            var isAvailable = true;
+            var ipGlobalProperties = IPGlobalProperties.GetIPGlobalProperties();
+            var tcpConnInfoArray = ipGlobalProperties.GetActiveTcpListeners();
+
+            foreach (var endpoint in tcpConnInfoArray) {
+                if (endpoint.Port == port) {
+                    isAvailable = false;
+                    break;
+                }
+            }
+
+            return isAvailable;
+        }
+    }
+}