Reusable containers (stage1, alpha) (#1781)

* Simplify Kafka container by deferring the Kafka command

* WIP: reusable containers based on labels

* do not call `newInstance` from `newInstanceFromConnectionUrl`

* disable the port forwarding in `ReusabilityUnitTests`

* Simplify the startup sequence

* speed up port detection by running the checks as a single command

* Separate "environment" and "classpath" properties (for global things)

* Update TestcontainersConfiguration.java

* Add test for the reuse env property

* Add `@UnstableAPI` annotation

* Add `VisibleForTesting` on `findContainerForReuse`

Author: bsideup

core/src/main/java/org/testcontainers/UnstableAPI.java

@@ -0,0 +1,21 @@
+package org.testcontainers;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks that the annotated API is a subject to change and SHOULD NOT be considered
+ * a stable API.
+ */
+@Retention(RetentionPolicy.SOURCE)
+@Target({
+    ElementType.TYPE,
+    ElementType.METHOD,
+    ElementType.FIELD,
+})
+@Documented
+public @interface UnstableAPI {
+}

core/src/main/java/org/testcontainers/containers/GenericContainer.java

@@ -1,5 +1,9 @@
 package org.testcontainers.containers;
 
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.MapperFeature;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.SerializationFeature;
 import com.github.dockerjava.api.DockerClient;
 import com.github.dockerjava.api.command.CreateContainerCmd;
 import com.github.dockerjava.api.command.InspectContainerResponse;
@@ -12,13 +16,15 @@
 import com.github.dockerjava.api.model.PortBinding;
 import com.github.dockerjava.api.model.Volume;
 import com.github.dockerjava.api.model.VolumesFrom;
+import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.Strings;
+import com.google.common.collect.ImmutableMap;
 import lombok.AccessLevel;
 import lombok.Data;
-import lombok.EqualsAndHashCode;
 import lombok.NonNull;
 import lombok.Setter;
 import lombok.SneakyThrows;
+import org.apache.commons.codec.digest.DigestUtils;
 import org.apache.commons.compress.archivers.tar.TarArchiveInputStream;
 import org.apache.commons.compress.archivers.tar.TarArchiveOutputStream;
 import org.apache.commons.compress.utils.IOUtils;
@@ -33,6 +39,7 @@
 import org.rnorth.visibleassertions.VisibleAssertions;
 import org.slf4j.Logger;
 import org.testcontainers.DockerClientFactory;
+import org.testcontainers.UnstableAPI;
 import org.testcontainers.containers.output.OutputFrame;
 import org.testcontainers.containers.startupcheck.IsRunningStartupCheckStrategy;
 import org.testcontainers.containers.startupcheck.MinimumDurationRunningStartupCheckStrategy;
@@ -62,11 +69,14 @@
 import java.io.FileOutputStream;
 import java.io.IOException;
 import java.io.InputStream;
+import java.lang.reflect.Method;
 import java.nio.charset.Charset;
 import java.nio.file.Path;
 import java.time.Duration;
+import java.time.Instant;
 import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.Collection;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.HashSet;
@@ -100,6 +110,8 @@ public class GenericContainer<SELF extends GenericContainer<SELF>>
 
     public static final String INTERNAL_HOST_HOSTNAME = "host.testcontainers.internal";
 
+    static final String HASH_LABEL = "org.testcontainers.hash";
+
     /*
      * Default settings
      */
@@ -168,11 +180,12 @@ public class GenericContainer<SELF extends GenericContainer<SELF>>
 
     protected final Set<Startable> dependencies = new HashSet<>();
 
-    /*
+    /**
      * Unique instance of DockerClient for use by this container object.
+     * We use {@link LazyDockerClient} here to avoid eager client creation
      */
     @Setter(AccessLevel.NONE)
-    protected DockerClient dockerClient = DockerClientFactory.instance().client();
+    protected DockerClient dockerClient = LazyDockerClient.INSTANCE;
 
     /*
      * Info about the Docker server; lazily fetched.
@@ -222,6 +235,8 @@ public class GenericContainer<SELF extends GenericContainer<SELF>>
     @Nullable
     private Map<String, String> tmpFsMapping;
 
+    @Setter(AccessLevel.NONE)
+    private boolean shouldBeReused = false;
 
     public GenericContainer() {
         this(TestcontainersConfiguration.getInstance().getTinyImage());
@@ -276,13 +291,15 @@ protected void doStart() {
         try {
             configure();
 
+            Instant startedAt = Instant.now();
+
             logger().debug("Starting container: {}", getDockerImageName());
             logger().debug("Trying to start container: {}", image.get());
 
             AtomicInteger attempt = new AtomicInteger(0);
             Unreliables.retryUntilSuccess(startupAttempts, () -> {
                 logger().debug("Trying to start container: {} (attempt {}/{})", image.get(), attempt.incrementAndGet(), startupAttempts);
-                tryStart();
+                tryStart(startedAt);
                 return true;
             });
 
@@ -291,7 +308,25 @@ protected void doStart() {
         }
     }
 
-    private void tryStart() {
+    @UnstableAPI
+    @SneakyThrows
+    protected boolean canBeReused() {
+        for (Class<?> type = getClass(); type != GenericContainer.class; type = type.getSuperclass()) {
+            try {
+                Method method = type.getDeclaredMethod("containerIsCreated", String.class);
+                if (method.getDeclaringClass() != GenericContainer.class) {
+                    logger().warn("{} can't be reused because it overrides {}", getClass(), method.getName());
+                    return false;
+                }
+            } catch (NoSuchMethodException e) {
+                // ignore
+            }
+        }
+
+        return true;
+    }
+
+    private void tryStart(Instant startedAt) {
         try {
             String dockerImageName = image.get();
             logger().debug("Starting container: {}", dockerImageName);
@@ -300,16 +335,49 @@ private void tryStart() {
             CreateContainerCmd createCommand = dockerClient.createContainerCmd(dockerImageName);
             applyConfiguration(createCommand);
 
-            containerId = createCommand.exec().getId();
+            createCommand.getLabels().put(DockerClientFactory.TESTCONTAINERS_LABEL, "true");
 
-            connectToPortForwardingNetwork(createCommand.getNetworkMode());
+            boolean reused = false;
+            if (shouldBeReused) {
+                if (!canBeReused()) {
+                    throw new IllegalStateException("This container does not support reuse");
+                }
 
-            copyToFileContainerPathMap.forEach(this::copyFileToContainer);
+                if (TestcontainersConfiguration.getInstance().environmentSupportsReuse()) {
+                    String hash = hash(createCommand);
 
-            containerIsCreated(containerId);
+                    containerId = findContainerForReuse(hash).orElse(null);
 
-            logger().info("Starting container with ID: {}", containerId);
-            dockerClient.startContainerCmd(containerId).exec();
+                    if (containerId != null) {
+                        logger().info("Reusing container with ID: {} and hash: {}", containerId, hash);
+                        reused = true;
+                    } else {
+                        logger().debug("Can't find a reusable running container with hash: {}", hash);
+
+                        createCommand.getLabels().put(HASH_LABEL, hash);
+                    }
+                } else {
+                    logger().info("Reuse was requested but the environment does not support the reuse of containers");
+                }
+            } else {
+                createCommand.getLabels().put(DockerClientFactory.TESTCONTAINERS_SESSION_ID_LABEL, DockerClientFactory.SESSION_ID);
+            }
+
+            if (!reused) {
+                containerId = createCommand.exec().getId();
+
+                // TODO add to the hash
+                copyToFileContainerPathMap.forEach(this::copyFileToContainer);
+            }
+
+            connectToPortForwardingNetwork(createCommand.getNetworkMode());
+
+            if (!reused) {
+                containerIsCreated(containerId);
+
+                logger().info("Starting container with ID: {}", containerId);
+                dockerClient.startContainerCmd(containerId).exec();
+            }
 
             logger().info("Container {} is starting: {}", dockerImageName, containerId);
 
@@ -331,7 +399,7 @@ private void tryStart() {
             // Wait until the process within the container has become ready for use (e.g. listening on network, log message emitted, etc).
             waitUntilContainerStarted();
 
-            logger().info("Container {} started", dockerImageName);
+            logger().info("Container {} started in {}", dockerImageName, Duration.between(startedAt, Instant.now()));
             containerIsStarted(containerInfo);
         } catch (Exception e) {
             logger().error("Could not start container", e);
@@ -351,6 +419,31 @@ private void tryStart() {
         }
     }
 
+    @UnstableAPI
+    @SneakyThrows(JsonProcessingException.class)
+    final String hash(CreateContainerCmd createCommand) {
+        // TODO add Testcontainers' version to the hash
+        String commandJson = new ObjectMapper()
+            .enable(MapperFeature.SORT_PROPERTIES_ALPHABETICALLY)
+            .enable(SerializationFeature.ORDER_MAP_ENTRIES_BY_KEYS)
+            .writeValueAsString(createCommand);
+
+        return DigestUtils.sha1Hex(commandJson);
+    }
+
+    @VisibleForTesting
+    Optional<String> findContainerForReuse(String hash) {
+        // TODO locking
+        return dockerClient.listContainersCmd()
+            .withLabelFilter(ImmutableMap.of(HASH_LABEL, hash))
+            .withLimit(1)
+            .withStatusFilter(Arrays.asList("running"))
+            .exec()
+            .stream()
+            .findAny()
+            .map(it -> it.getId());
+    }
+
     /**
      * Set any custom settings for the create command such as shared memory size.
      */
@@ -613,7 +706,6 @@ private void applyConfiguration(CreateContainerCmd createCommand) {
         if (createCommand.getLabels() != null) {
             combinedLabels.putAll(createCommand.getLabels());
         }
-        combinedLabels.putAll(DockerClientFactory.DEFAULT_LABELS);
 
         createCommand.withLabels(combinedLabels);
     }
@@ -1215,7 +1307,7 @@ public SELF withStartupAttempts(int attempts) {
     }
 
     /**
-     * Allow low level modifications of {@link CreateContainerCmd} after it was pre-configured in {@link #tryStart()}.
+     * Allow low level modifications of {@link CreateContainerCmd} after it was pre-configured in {@link #tryStart(Instant)}.
      * Invocation happens eagerly on a moment when container is created.
      * Warning: this does expose the underlying docker-java API so might change outside of our control.
      *
@@ -1247,6 +1339,12 @@ public SELF withTmpFs(Map<String, String> mapping) {
         return self();
     }
 
+    @UnstableAPI
+    public SELF withReuse(boolean reusable) {
+        this.shouldBeReused = reusable;
+        return self();
+    }
+
     @Override
     public boolean equals(Object o) {
         return this == o;

core/src/main/java/org/testcontainers/containers/LazyDockerClient.java

@@ -0,0 +1,15 @@
+package org.testcontainers.containers;
+
+import com.github.dockerjava.api.DockerClient;
+import lombok.experimental.Delegate;
+import org.testcontainers.DockerClientFactory;
+
+enum LazyDockerClient implements DockerClient {
+
+    INSTANCE;
+
+    @Delegate
+    final DockerClient getDockerClient() {
+        return DockerClientFactory.instance().client();
+    }
+}

core/src/main/java/org/testcontainers/utility/TestcontainersConfiguration.java

@@ -2,6 +2,7 @@
 
 import lombok.*;
 import lombok.extern.slf4j.Slf4j;
+import org.testcontainers.UnstableAPI;
 
 import java.io.*;
 import java.net.MalformedURLException;
@@ -89,12 +90,17 @@ public boolean isDisableChecks() {
         return Boolean.parseBoolean((String) environmentProperties.getOrDefault("checks.disable", "false"));
     }
 
+    @UnstableAPI
+    public boolean environmentSupportsReuse() {
+        return Boolean.parseBoolean((String) environmentProperties.getOrDefault("testcontainers.reuse.enable", "false"));
+    }
+
     public String getDockerClientStrategyClassName() {
         return (String) environmentProperties.get("docker.client.strategy");
     }
 
     /**
-     * 
+     *
      * @deprecated we no longer have different transport types
      */
     @Deprecated