chore: add skip_pull_image support to emulator image + support using local image if remote image pull fails

Author: hsilan

samcli/commands/local/cli_common/durable_context.py

@@ -18,18 +18,24 @@ class DurableContext:
     Automatically reuses existing running containers when possible.
     """
 
-    def __init__(self):
+    def __init__(self, skip_pull_image=False):
         """
         Initialize the durable context.
+
+        Parameters
+        ----------
+        skip_pull_image : bool
+            If True, skip pulling the emulator container image
         """
         self._emulator: Optional[DurableFunctionsEmulatorContainer] = None
         self._reused_container = False
+        self._skip_pull_image = skip_pull_image
 
     def __enter__(self) -> "DurableContext":
         """
         Start the emulator container or attach to an already running one
         """
-        self._emulator = DurableFunctionsEmulatorContainer()
+        self._emulator = DurableFunctionsEmulatorContainer(skip_pull_image=self._skip_pull_image)
         self._reused_container = self._emulator.start_or_attach()
         return self
 

samcli/local/docker/durable_functions_emulator_container.py

@@ -80,11 +80,12 @@ class DurableFunctionsEmulatorContainer:
     """
     ENV_EMULATOR_IMAGE_TAG = "DURABLE_EXECUTIONS_EMULATOR_IMAGE_TAG"
 
-    def __init__(self, container_client=None, existing_container=None):
+    def __init__(self, container_client=None, existing_container=None, skip_pull_image=False):
         self._docker_client_param = container_client
         self._validated_docker_client: Optional[docker.DockerClient] = None
         self.container = existing_container
         self.lambda_client: Optional[DurableFunctionsClient] = None
+        self._skip_pull_image = skip_pull_image
 
         self.port = self._get_emulator_port()
 
@@ -200,11 +201,12 @@ def _get_emulator_binary_name(self):
         return f"aws-durable-execution-emulator-{arch}"
 
     def _pull_image_if_needed(self):
+        local_image_exists = False
         """Pull the emulator image if it doesn't exist locally or is out of date."""
         try:
             self._docker_client.images.get(self._get_emulator_image())
+            local_image_exists = True
             LOG.debug(f"Emulator image {self._get_emulator_image()} exists locally")
-
             if is_image_current(self._docker_client, self._get_emulator_image()):
                 LOG.debug("Local emulator image is up-to-date")
                 return
@@ -214,10 +216,19 @@ def _pull_image_if_needed(self):
             LOG.debug(f"Pulling emulator image {self._get_emulator_image()}...")
 
         try:
+            if self._skip_pull_image and local_image_exists:
+                LOG.debug("Skipping pulling new emulator image")
+                return
             self._docker_client.images.pull(self._get_emulator_image())
             LOG.info(f"Successfully pulled image {self._get_emulator_image()}")
         except Exception as e:
-            raise ClickException(f"Failed to pull emulator image {self._get_emulator_image()}: {e}")
+            if local_image_exists:
+                LOG.debug(
+                    f"Using existing local emulator image since we failed to pull emulator image "
+                    f"{self._get_emulator_image()}: {e}"
+                )
+            else:
+                raise ClickException(f"Failed to pull emulator image {self._get_emulator_image()}: {e}")
 
     def start(self):
         """Start the emulator container."""

samcli/local/lambdafn/runtime.py

@@ -477,7 +477,9 @@ def get_or_create_emulator_container(self):
             DurableFunctionsEmulatorContainer: The singleton emulator container
         """
         if self._durable_execution_emulator_container is None:
-            self._durable_execution_emulator_container = DurableFunctionsEmulatorContainer()
+            self._durable_execution_emulator_container = DurableFunctionsEmulatorContainer(
+                skip_pull_image=self._container_manager.skip_pull_image,
+            )
             self._durable_execution_emulator_container.start_or_attach()
             LOG.debug("Created and started durable functions emulator container")
         return self._durable_execution_emulator_container

tests/unit/local/docker/test_durable_functions_emulator_container.py

@@ -421,6 +421,20 @@ def test_image_pull_failure_raises_click_exception(self):
             container._pull_image_if_needed()
         self.assertIn("Failed to pull emulator image", str(context.exception))
 
+    @patch("samcli.local.docker.durable_functions_emulator_container.is_image_current")
+    def test_image_pull_failure_with_existing_local_image_logs_debug_message(self, mock_is_current):
+        """Test that image pull failure with existing local image logs debug message before raising exception"""
+        container = self._create_container()
+        mock_image = Mock()
+        self.mock_docker_client.images.get.return_value = mock_image
+        mock_is_current.return_value = False
+        self.mock_docker_client.images.pull.side_effect = Exception("Network timeout")
+
+        with (self.assertLogs("samcli.local.docker.durable_functions_emulator_container", level="DEBUG") as log,):
+            container._pull_image_if_needed()
+
+        self.assertTrue(any("Using existing local emulator image since we failed to pull" in msg for msg in log.output))
+
     @patch("samcli.local.docker.durable_functions_emulator_container.requests")
     def test_start_durable_execution_success(self, mock_requests):
         """Test that start_durable_execution() posts correct payload and returns response json"""
@@ -690,3 +704,18 @@ def test_stop_captures_logs_before_stopping(self):
 
             container._capture_emulator_logs.assert_called_once()
             self.mock_container.stop.assert_called_once()
+
+    @patch("samcli.local.docker.durable_functions_emulator_container.is_image_current")
+    def test_skip_pull_image_with_existing_local_image_logs_debug_and_returns_early(self, mock_is_current):
+        """Test that _skip_pull_image=True with existing local image logs debug message and returns early"""
+        container = self._create_container()
+        container._skip_pull_image = True
+        mock_image = Mock()
+        mock_is_current.return_value = False
+        self.mock_docker_client.images.get.return_value = mock_image
+
+        with self.assertLogs("samcli.local.docker.durable_functions_emulator_container", level="DEBUG") as log:
+            container._pull_image_if_needed()
+
+        self.assertTrue(any("Skipping pulling new emulator image" in msg for msg in log.output))
+        self.mock_docker_client.images.pull.assert_not_called()