feat: remove custom port allocators and add clean up on shutdown

Author: eznix86

CONTRIBUTING.md

@@ -37,6 +37,7 @@ Or run everything:
 composer test
 ```
 
+
 ## Pre-commit hook
 
 The pre-commit hook runs these checks (in this order):

src/Autoload.php

@@ -7,6 +7,8 @@
 require_once __DIR__.'/Foundation/Bootstrap/Helpers.php';
 require_once __DIR__.'/Foundation/Bootstrap/Plugin.php';
 require_once __DIR__.'/Foundation/Bootstrap/Expectations.php';
+require_once __DIR__.'/Foundation/Bootstrap/Cleanup.php';
 
 registerPluginUses();
 registerStorageExpectations();
+registerManagedContainersShutdownCleanup();

src/Container/ContainerBuilder.php

@@ -6,16 +6,10 @@
 
 use Closure;
 use Eznix86\PestPluginTestContainers\Container\PortMapping\FixedPortSequenceGenerator;
-use Eznix86\PestPluginTestContainers\Container\PortMapping\PortAllocator;
-use Eznix86\PestPluginTestContainers\Container\PortMapping\ProtocolAwareRandomUniquePortAllocator;
-use Eznix86\PestPluginTestContainers\Container\PortMapping\SaferRandomUniquePortGenerator;
-use Eznix86\PestPluginTestContainers\Container\PortMapping\WorkerPortAllocator;
-use Eznix86\PestPluginTestContainers\Container\PortMapping\WorkerPortGenerator;
 use Eznix86\PestPluginTestContainers\Container\Reuse\ReusableContainerResolver;
 use Eznix86\PestPluginTestContainers\Container\Reuse\ReuseOptions;
 use Eznix86\PestPluginTestContainers\Container\Reuse\WorkerTokenResolver;
 use InvalidArgumentException;
-use RuntimeException;
 use Testcontainers\Container\GenericContainer;
 use Testcontainers\Container\HttpMethod;
 use Testcontainers\ContainerClient\DockerContainerClient;
@@ -26,23 +20,18 @@
 
 final readonly class ContainerBuilder
 {
+    private const string MANAGED_BY_LABEL_KEY = 'pest-plugin-testcontainers.managed';
+
+    private const string MANAGED_BY_LABEL_VALUE = '1';
+
     private const int START_MAX_ATTEMPTS = 6;
 
     private const int START_RETRY_BASE_DELAY_MICROSECONDS = 500_000;
 
     private const int START_RETRY_MAX_DELAY_MICROSECONDS = 5_000_000;
 
-    /**
-     * @var list<string>
-     */
-    private const array TRANSIENT_DOCKER_START_ERROR_MARKERS = [
-        'server error',
-    ];
-
     private GenericContainer $container;
 
-    private PortAllocator $portAllocator;
-
     private ReuseOptions $reuseOptions;
 
     private ReusableContainerResolver $reusableContainerResolver;
@@ -68,15 +57,10 @@ public function __construct(
         callable $registerContainer,
         callable $skipTest,
     ) {
-        $this->container = new GenericContainer($image);
-
-        if ($this->isRunningInParallel()) {
-            $this->container->withPortGenerator(new WorkerPortGenerator);
-            $this->portAllocator = new WorkerPortAllocator;
-        } else {
-            $this->container->withPortGenerator(new SaferRandomUniquePortGenerator);
-            $this->portAllocator = new ProtocolAwareRandomUniquePortAllocator;
-        }
+        $this->container = (new GenericContainer($image))
+            ->withLabels([
+                self::MANAGED_BY_LABEL_KEY => self::MANAGED_BY_LABEL_VALUE,
+            ]);
 
         $this->reuseOptions = new ReuseOptions;
         $this->reusableContainerResolver = new ReusableContainerResolver;
@@ -85,11 +69,6 @@ public function __construct(
         $this->skipTest = Closure::fromCallable($skipTest);
     }
 
-    private function isRunningInParallel(): bool
-    {
-        return ($_SERVER['PEST_PARALLEL'] ?? $_ENV['PEST_PARALLEL'] ?? '0') === '1';
-    }
-
     /**
      * @param  list<int|string>|array<int|string, int|string>  $ports
      */
@@ -98,10 +77,8 @@ public function ports(array $ports): self
         if (array_is_list($ports)) {
             /** @var list<int|string> $containerPorts */
             $containerPorts = array_map($this->normalizeContainerPort(...), $ports);
-            /** @var list<int> $hostPorts */
-            $hostPorts = array_map($this->portAllocator->allocateForContainerPort(...), $containerPorts);
 
-            $this->configurePortMapping($containerPorts, $hostPorts);
+            $this->container->withExposedPorts(...$containerPorts);
 
             return $this;
         }
@@ -329,9 +306,18 @@ public function start(): StartedContainer
                 if ($reusedContainer instanceof StartedContainer) {
                     return ($this->registerContainer)($reusedContainer);
                 }
+
+                try {
+                    $recreatedContainer = $this->startContainerWithRetry();
+                    $recreatedContainer->skipAutoCleanup();
+
+                    return ($this->registerContainer)($recreatedContainer);
+                } catch (Throwable $recreateException) {
+                    $exception = $recreateException;
+                }
             }
 
-            ($this->skipTest)('Container startup issue: '.$exception->getMessage());
+            ($this->skipTest)('Container startup issue: '.$this->describeThrowable($exception));
         }
     }
 
@@ -343,38 +329,54 @@ private function startContainerWithRetry(): StartedContainer
             try {
                 return new StartedContainer($this->container->start());
             } catch (Throwable $exception) {
-                if (! $this->isTransientDockerStartError($exception)) {
-                    throw $exception;
-                }
-
-                $this->cleanupFailedContainerAfterTransientStartError();
+                $this->cleanupFailedContainerAfterStartError();
                 $lastException = $exception;
 
                 if ($attempt < self::START_MAX_ATTEMPTS - 1) {
                     usleep($this->startRetryDelayForAttempt($attempt));
                 }
             }
         }
-
-        throw new RuntimeException(
-            'Container failed to start after retrying transient Docker errors.',
-            previous: $lastException,
-        );
+        throw $lastException;
     }
 
-    private function isTransientDockerStartError(Throwable $exception): bool
+    private function describeThrowable(Throwable $exception): string
     {
+        $descriptions = [];
+
         for ($current = $exception; $current instanceof Throwable; $current = $current->getPrevious()) {
-            $message = strtolower($current->getMessage());
+            $message = trim($current->getMessage());
+
+            if (method_exists($current, 'getErrorResponse')) {
+                $errorResponse = $current->getErrorResponse();
+
+                if (is_object($errorResponse) && method_exists($errorResponse, 'getMessage')) {
+                    $dockerMessage = $errorResponse->getMessage();
 
-            foreach (self::TRANSIENT_DOCKER_START_ERROR_MARKERS as $marker) {
-                if (str_contains($message, $marker)) {
-                    return true;
+                    if (is_string($dockerMessage) && $dockerMessage !== '' && ! str_contains($message, $dockerMessage)) {
+                        $message = trim($message.' | docker: '.$dockerMessage);
+                    }
                 }
             }
+
+            if (method_exists($current, 'getResponse')) {
+                $response = $current->getResponse();
+
+                if (is_object($response) && method_exists($response, 'getStatusCode')) {
+                    $statusCode = $response->getStatusCode();
+                    $reason = method_exists($response, 'getReasonPhrase') ? $response->getReasonPhrase() : '';
+
+                    if (is_int($statusCode)) {
+                        $httpPart = sprintf('HTTP %d%s', $statusCode, is_string($reason) && $reason !== '' ? ' '.$reason : '');
+                        $message = trim($message.' | '.$httpPart);
+                    }
+                }
+            }
+
+            $descriptions[] = sprintf('%s: %s', $current::class, $message === '' ? '(empty message)' : $message);
         }
 
-        return false;
+        return implode(' <- ', $descriptions);
     }
 
     private function startRetryDelayForAttempt(int $attempt): int
@@ -384,7 +386,7 @@ private function startRetryDelayForAttempt(int $attempt): int
         return min($delay, self::START_RETRY_MAX_DELAY_MICROSECONDS);
     }
 
-    private function cleanupFailedContainerAfterTransientStartError(): void
+    private function cleanupFailedContainerAfterStartError(): void
     {
         try {
             $containerId = $this->container->getId();