localstack-core 4.6.1.dev30__tar.gz → 4.6.1.dev31__tar.gz

{localstack_core-4.6.1.dev30 → localstack_core-4.6.1.dev31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: localstack-core
-Version: 4.6.1.dev30
+Version: 4.6.1.dev31
 Summary: The core library and runtime of LocalStack
 Author-email: LocalStack Contributors <info@localstack.cloud>
 License-Expression: Apache-2.0

{localstack_core-4.6.1.dev30 → localstack_core-4.6.1.dev31}/localstack-core/localstack/services/lambda_/event_source_mapping/esm_worker_factory.py

@@ -37,12 +37,12 @@ from localstack.services.lambda_.event_source_mapping.pollers.sqs_poller import
     SqsPoller,
 )
 from localstack.services.lambda_.event_source_mapping.senders.lambda_sender import LambdaSender
-from localstack.utils.aws.arns import parse_arn
-from localstack.utils.aws.client_types import ServicePrincipal
-from localstack.utils.lambda_debug_mode.lambda_debug_mode import (
+from localstack.services.lambda_.lambda_debug_mode.ldm import (
     DEFAULT_LAMBDA_DEBUG_MODE_TIMEOUT_SECONDS,
-    is_lambda_debug_mode,
+    LDM,
 )
+from localstack.utils.aws.arns import parse_arn
+from localstack.utils.aws.client_types import ServicePrincipal
 
 
 class PollerHolder:
@@ -65,7 +65,7 @@ class EsmWorkerFactory:
         # Sender (always Lambda)
         function_arn = self.esm_config["FunctionArn"]
 
-        if is_lambda_debug_mode():
+        if LDM.is_enabled():
             timeout_seconds = DEFAULT_LAMBDA_DEBUG_MODE_TIMEOUT_SECONDS
         else:
             # 900s is the maximum amount of time a Lambda can run for.

{localstack_core-4.6.1.dev30 → localstack_core-4.6.1.dev31}/localstack-core/localstack/services/lambda_/invocation/assignment.py

@@ -15,10 +15,6 @@ from localstack.services.lambda_.invocation.lambda_models import (
     InitializationType,
     OtherServiceEndpoint,
 )
-from localstack.utils.lambda_debug_mode.lambda_debug_mode import (
-    is_lambda_debug_enabled_for,
-    is_lambda_debug_timeout_enabled_for,
-)
 
 LOG = logging.getLogger(__name__)
 
@@ -79,10 +75,7 @@ class AssignmentService(OtherServiceEndpoint):
 
         try:
             yield execution_environment
-            if is_lambda_debug_timeout_enabled_for(lambda_arn=function_version.qualified_arn):
-                self.stop_environment(execution_environment)
-            else:
-                execution_environment.release()
+            execution_environment.release()
         except InvalidStatusException as invalid_e:
             LOG.error("InvalidStatusException: %s", invalid_e)
         except Exception as e:
@@ -143,21 +136,6 @@ class AssignmentService(OtherServiceEndpoint):
         function_version: FunctionVersion,
         target_provisioned_environments: int,
     ) -> list[Future[None]]:
-        # Enforce a single environment per lambda version if this is a target
-        # of an active Lambda Debug Mode.
-        qualified_lambda_version_arn = function_version.qualified_arn
-        if (
-            is_lambda_debug_enabled_for(qualified_lambda_version_arn)
-            and target_provisioned_environments > 0
-        ):
-            LOG.warning(
-                "Environments for '%s' enforced to '1' by Lambda Debug Mode, "
-                "configurations will continue to report the set value '%s'",
-                qualified_lambda_version_arn,
-                target_provisioned_environments,
-            )
-            target_provisioned_environments = 1
-
         current_provisioned_environments = [
             e
             for e in self.environments[version_manager_id].values()

{localstack_core-4.6.1.dev30 → localstack_core-4.6.1.dev31}/localstack-core/localstack/services/lambda_/invocation/counting_service.py

@@ -11,9 +11,6 @@ from localstack.services.lambda_.invocation.lambda_models import (
     InitializationType,
 )
 from localstack.services.lambda_.invocation.models import lambda_stores
-from localstack.utils.lambda_debug_mode.lambda_debug_mode import (
-    is_lambda_debug_enabled_for,
-)
 
 LOG = logging.getLogger(__name__)
 
@@ -130,24 +127,6 @@ class CountingService:
         unqualified_function_arn = function_version.id.unqualified_arn()
         qualified_arn = function_version.id.qualified_arn()
 
-        # Enforce one lease per ARN if the global flag is set
-        if is_lambda_debug_enabled_for(qualified_arn):
-            with provisioned_tracker.lock, on_demand_tracker.lock:
-                on_demand_executions: int = on_demand_tracker.concurrent_executions[
-                    unqualified_function_arn
-                ]
-                provisioned_executions = provisioned_tracker.concurrent_executions[qualified_arn]
-                if on_demand_executions or provisioned_executions:
-                    LOG.warning(
-                        "Concurrent lambda invocations disabled for '%s' by Lambda Debug Mode",
-                        qualified_arn,
-                    )
-                    raise TooManyRequestsException(
-                        "Rate Exceeded.",
-                        Reason="SingleLeaseEnforcement",
-                        Type="User",
-                    )
-
         lease_type = None
         # HACK: skip reserved and provisioned concurrency if function not available (e.g., in Lambda@Edge)
         if function is not None:

{localstack_core-4.6.1.dev30 → localstack_core-4.6.1.dev31}/localstack-core/localstack/services/lambda_/invocation/docker_runtime_executor.py

@@ -23,6 +23,7 @@ from localstack.services.lambda_.invocation.runtime_executor import (
     LambdaRuntimeException,
     RuntimeExecutor,
 )
+from localstack.services.lambda_.lambda_debug_mode.ldm import LDM_ENV_VAR_DEBUG_PORT
 from localstack.services.lambda_.lambda_utils import HINT_LOG
 from localstack.services.lambda_.networking import (
     get_all_container_networks_for_lambda,
@@ -43,7 +44,6 @@ from localstack.utils.container_utils.container_client import (
 )
 from localstack.utils.docker_utils import DOCKER_CLIENT as CONTAINER_CLIENT
 from localstack.utils.files import chmod_r, rm_rf
-from localstack.utils.lambda_debug_mode.lambda_debug_mode import lambda_debug_port_for
 from localstack.utils.net import get_free_tcp_port
 from localstack.utils.strings import short_uid, truncate
 
@@ -321,9 +321,6 @@ class DockerRuntimeExecutor(RuntimeExecutor):
             platform=docker_platform(self.function_version.config.architectures[0]),
             additional_flags=config.LAMBDA_DOCKER_FLAGS,
         )
-        debug_port = lambda_debug_port_for(self.function_version.qualified_arn)
-        if debug_port is not None:
-            container_config.ports.add(debug_port, debug_port)
 
         if self.function_version.config.package_type == PackageType.Zip:
             if self.function_version.config.code.is_hot_reloading():
@@ -379,6 +376,10 @@ class DockerRuntimeExecutor(RuntimeExecutor):
                 container_config.ports = PortMappings()
             container_config.ports.add(config.LAMBDA_INIT_DELVE_PORT, config.LAMBDA_INIT_DELVE_PORT)
 
+        if ldm_debug_port := env_vars.get(LDM_ENV_VAR_DEBUG_PORT):
+            ldm_debug_port = int(ldm_debug_port)
+            container_config.ports.add(ldm_debug_port, ldm_debug_port)
+
         if (
             self.function_version.config.layers
             and not config.LAMBDA_PREBUILD_IMAGES

{localstack_core-4.6.1.dev30 → localstack_core-4.6.1.dev31}/localstack-core/localstack/services/lambda_/invocation/execution_environment.py

@@ -20,10 +20,6 @@ from localstack.services.lambda_.invocation.runtime_executor import (
     RuntimeExecutor,
     get_runtime_executor,
 )
-from localstack.utils.lambda_debug_mode.lambda_debug_mode import (
-    DEFAULT_LAMBDA_DEBUG_MODE_TIMEOUT_SECONDS,
-    is_lambda_debug_timeout_enabled_for,
-)
 from localstack.utils.strings import to_str
 from localstack.utils.xray.trace_header import TraceHeader
 
@@ -139,7 +135,7 @@ class ExecutionEnvironment:
             # AWS_LAMBDA_DOTNET_PREJIT
             "TZ": ":UTC",
             # 2) Public AWS RIE interface: https://github.com/aws/aws-lambda-runtime-interface-emulator
-            "AWS_LAMBDA_FUNCTION_TIMEOUT": self._get_execution_timeout_seconds(),
+            "AWS_LAMBDA_FUNCTION_TIMEOUT": self.function_version.config.timeout,
             # 3) Public LocalStack endpoint
             "LOCALSTACK_HOSTNAME": self.runtime_executor.get_endpoint_from_executor(),
             "EDGE_PORT": str(config.GATEWAY_LISTEN[0].port),
@@ -388,18 +384,5 @@ class ExecutionEnvironment:
             DurationSeconds=43200,
         )["Credentials"]
 
-    def _get_execution_timeout_seconds(self) -> int:
-        # Returns the timeout value in seconds to be enforced during the execution of the
-        # lambda function. This is the configured value or the DEBUG MODE default if this
-        # is enabled.
-        if is_lambda_debug_timeout_enabled_for(self.function_version.qualified_arn):
-            return DEFAULT_LAMBDA_DEBUG_MODE_TIMEOUT_SECONDS
-        return self.function_version.config.timeout
-
     def _get_startup_timeout_seconds(self) -> int:
-        # Returns the timeout value in seconds to be enforced during lambda container startups.
-        # This is the value defined through LAMBDA_RUNTIME_ENVIRONMENT_TIMEOUT or the LAMBDA
-        # DEBUG MODE default if this is enabled.
-        if is_lambda_debug_timeout_enabled_for(self.function_version.qualified_arn):
-            return DEFAULT_LAMBDA_DEBUG_MODE_TIMEOUT_SECONDS
         return STARTUP_TIMEOUT_SEC

{localstack_core-4.6.1.dev30 → localstack_core-4.6.1.dev31}/localstack-core/localstack/services/lambda_/invocation/executor_endpoint.py

@@ -11,11 +11,11 @@ from werkzeug import Request
 from localstack.http import Response, route
 from localstack.services.edge import ROUTER
 from localstack.services.lambda_.invocation.lambda_models import InvocationResult
-from localstack.utils.backoff import ExponentialBackoff
-from localstack.utils.lambda_debug_mode.lambda_debug_mode import (
+from localstack.services.lambda_.lambda_debug_mode.ldm import (
     DEFAULT_LAMBDA_DEBUG_MODE_TIMEOUT_SECONDS,
-    is_lambda_debug_mode,
+    LDM,
 )
+from localstack.utils.backoff import ExponentialBackoff
 from localstack.utils.objects import singleton_factory
 from localstack.utils.strings import to_str
 
@@ -209,7 +209,7 @@ class ExecutorEndpoint(Endpoint):
         # Note that if timeouts are enforced for the lambda function invoked at this endpoint
         # (this is needs to be configured in the Lambda Debug Mode Config file), the lambda
         # function will continue to enforce the expected timeouts.
-        if is_lambda_debug_mode():
+        if LDM.is_enabled():
             # The value is set to a default high value to ensure eventual termination.
             timeout_seconds = DEFAULT_LAMBDA_DEBUG_MODE_TIMEOUT_SECONDS
         else:

{localstack_core-4.6.1.dev30 → localstack_core-4.6.1.dev31}/localstack-core/localstack/services/lambda_/invocation/lambda_models.py

@@ -66,6 +66,7 @@ class Invocation:
     # = invocation_id
     request_id: str
     trace_context: dict
+    user_agent: Optional[str] = None
 
 
 InitializationType = Literal["on-demand", "provisioned-concurrency"]

{localstack_core-4.6.1.dev30 → localstack_core-4.6.1.dev31}/localstack-core/localstack/services/lambda_/invocation/lambda_service.py

@@ -230,6 +230,7 @@ class LambdaService:
         request_id: str,
         payload: bytes | None,
         trace_context: dict | None = None,
+        user_agent: Optional[str] = None,
     ) -> InvocationResult | None:
         """
         Invokes a specific version of a lambda
@@ -352,6 +353,7 @@ class LambdaService:
                     invoke_time=datetime.now(),
                     request_id=request_id,
                     trace_context=trace_context,
+                    user_agent=user_agent,
                 )
             )
 
@@ -364,6 +366,7 @@ class LambdaService:
                 invoke_time=datetime.now(),
                 request_id=request_id,
                 trace_context=trace_context,
+                user_agent=user_agent,
             )
         )
         status = (

{localstack_core-4.6.1.dev30 → localstack_core-4.6.1.dev31}/localstack-core/localstack/services/lambda_/invocation/version_manager.py

@@ -29,6 +29,7 @@ from localstack.services.lambda_.invocation.metrics import (
     record_cw_metric_invocation,
 )
 from localstack.services.lambda_.invocation.runtime_executor import get_runtime_executor
+from localstack.services.lambda_.lambda_debug_mode.ldm import LDM
 from localstack.utils.strings import long_uid, truncate
 from localstack.utils.threads import FuncThread, start_thread
 
@@ -191,6 +192,30 @@ class LambdaVersionManager:
             LOG.warning(message)
             raise ServiceException(message)
 
+        # If the environment has debugging enabled, route the invocation there;
+        # debug environments bypass Lambda service quotas.
+        if debug_execution_environment := LDM.get_execution_environment(
+            qualified_lambda_arn=self.function_version.qualified_arn,
+            user_agent=invocation.user_agent,
+        ):
+            try:
+                invocation_result = debug_execution_environment.invoke(invocation)
+                invocation_result.executed_version = self.function_version.id.qualifier
+                self.store_logs(
+                    invocation_result=invocation_result, execution_env=debug_execution_environment
+                )
+            except StatusErrorException as e:
+                invocation_result = InvocationResult(
+                    request_id="",
+                    payload=e.payload,
+                    is_error=True,
+                    logs="",
+                    executed_version=self.function_version.id.qualifier,
+                )
+            finally:
+                debug_execution_environment.release()
+            return invocation_result
+
         with self.counting_service.get_invocation_lease(
             self.function, self.function_version
         ) as provisioning_type:

localstack_core-4.6.1.dev31/localstack-core/localstack/services/lambda_/lambda_debug_mode/ldm.py

@@ -0,0 +1,375 @@
+from __future__ import annotations
+
+import logging
+import os
+import threading
+import time
+from threading import Event, RLock, Thread
+from typing import Callable, Dict, Final, Optional
+
+from localstack.aws.api.lambda_ import (
+    Arn,
+    FunctionVersion,
+    ResourceNotFoundException,
+    TooManyRequestsException,
+)
+from localstack.config import LAMBDA_DEBUG_MODE, LAMBDA_DEBUG_MODE_CONFIG_PATH
+from localstack.services.lambda_.invocation.execution_environment import (
+    ExecutionEnvironment,
+    InvalidStatusException,
+    RuntimeStatus,
+)
+from localstack.services.lambda_.lambda_debug_mode.ldm_config_file import parse_ldm_config
+from localstack.services.lambda_.provider_utils import get_function_version
+from localstack.utils.aws.arns import parse_arn
+from localstack.utils.objects import singleton_factory
+from localstack.utils.strings import long_uid
+
+LOG = logging.getLogger(__name__)
+
+# Specifies the default timeout value in seconds to be used by time restricted workflows
+# when Debug Mode is enabled. The value is set to one hour to ensure eventual termination
+# of long-running processes.
+DEFAULT_LAMBDA_DEBUG_MODE_TIMEOUT_SECONDS: int = 3_600
+LDM_ENV_VAR_DEBUG_PORT: str = "LDM_DEBUG_PORT"
+
+
+class LambdaFunctionDebugConfig:
+    qualified_lambda_arn: Final[Arn]
+    port: Final[int]
+    enforce_timeouts: Final[bool]
+    user_agent: Final[Optional[str]]
+
+    def __init__(
+        self,
+        qualified_lambda_arn: Arn,
+        port: int,
+        enforce_timeouts: bool = False,
+        user_agent: Optional[str] = None,
+    ):
+        self.qualified_lambda_arn = qualified_lambda_arn
+        self.port = port
+        self.enforce_timeouts = enforce_timeouts
+        self.user_agent = user_agent
+
+
+class DebugEnabledExecutionEnvironment(ExecutionEnvironment):
+    _lambda_function_debug_config: Final[LambdaFunctionDebugConfig]
+
+    def __init__(
+        self,
+        function_version: FunctionVersion,
+        lambda_function_debug_config: LambdaFunctionDebugConfig,
+        on_timeout: Callable[[str, str], None],
+    ):
+        super().__init__(
+            function_version=function_version,
+            version_manager_id=f"debug-enable-{long_uid()}",
+            initialization_type="provisioned-concurrency",
+            on_timeout=on_timeout,
+        )
+        self._lambda_function_debug_config = lambda_function_debug_config
+
+    def get_environment_variables(self) -> Dict[str, str]:
+        environment_variables = super().get_environment_variables()
+        environment_variables[LDM_ENV_VAR_DEBUG_PORT] = str(self._lambda_function_debug_config.port)
+        if not self._lambda_function_debug_config.enforce_timeouts:
+            environment_variables["AWS_LAMBDA_FUNCTION_TIMEOUT"] = str(
+                DEFAULT_LAMBDA_DEBUG_MODE_TIMEOUT_SECONDS
+            )
+        return environment_variables
+
+    def _get_startup_timeout_seconds(self) -> int:
+        return DEFAULT_LAMBDA_DEBUG_MODE_TIMEOUT_SECONDS
+
+
+class LambdaDebugTarget:
+    _mutex: Final[RLock]
+    _lambda_qualified_arn: Final[str]
+    lambda_function_debug_config: Final[LambdaFunctionDebugConfig]
+    _debug_execution_environment: Optional[DebugEnabledExecutionEnvironment]
+
+    def __init__(self, lambda_function_debug_config: LambdaFunctionDebugConfig):
+        self._mutex = RLock()
+        self._lambda_qualified_arn = lambda_function_debug_config.qualified_lambda_arn
+        self.lambda_function_debug_config = lambda_function_debug_config
+        self._debug_execution_environment = None
+
+    def start_debug_enabled_execution_environment(self):
+        # Attempt to create the debug environment now if the function exists.
+        with self._mutex:
+            if self._debug_execution_environment is not None:
+                return
+            self.stop_debug_enabled_execution_environment()
+
+            try:
+                lambda_parsed_arn = parse_arn(self._lambda_qualified_arn)
+                lambda_account_id = lambda_parsed_arn["account"]
+                lambda_region_name = lambda_parsed_arn["region"]
+                _, lambda_function_name, lambda_function_qualifier = lambda_parsed_arn[
+                    "resource"
+                ].split(":")
+                function_version = get_function_version(
+                    function_name=lambda_function_name,
+                    qualifier=lambda_function_qualifier,
+                    account_id=lambda_account_id,
+                    region=lambda_region_name,
+                )
+            except ResourceNotFoundException:
+                # The lambda function has not being created yet.
+                return
+
+            self._debug_execution_environment = DebugEnabledExecutionEnvironment(
+                function_version=function_version,
+                lambda_function_debug_config=self.lambda_function_debug_config,
+                on_timeout=self._on_execution_environment_timeout,
+            )
+            # FIXME: this log should take place after RuntimeStatus.READY, however the debug-enabled
+            #        docker container will not notify LS about it starting up until the user has
+            #        connected a debug client. Future work should resolve this notification issue.
+            LOG.info(
+                "LDM is ready for debugger connections for '%s' on port %i.",
+                self.lambda_function_debug_config.qualified_lambda_arn,
+                self.lambda_function_debug_config.port,
+            )
+            self._debug_execution_environment.start()
+            if self._debug_execution_environment.status != RuntimeStatus.READY:
+                LOG.error(
+                    "LDM could not create a debug environment for '%s'", self._lambda_qualified_arn
+                )
+                self._debug_execution_environment = None
+
+    def stop_debug_enabled_execution_environment(self):
+        with self._mutex:
+            if environment := self._debug_execution_environment:
+                environment.stop()
+            self._debug_execution_environment = None
+
+    def get_execution_environment(self) -> DebugEnabledExecutionEnvironment:
+        # TODO: add support for concurrent invokes, such as invoke object queuing, new container spinup
+        with self._mutex:
+            # TODO: move this start-up logic to lambda function creation.
+            self.start_debug_enabled_execution_environment()
+            try:
+                self._debug_execution_environment.reserve()
+                return self._debug_execution_environment
+            except InvalidStatusException:
+                LOG.warning(
+                    "Concurrent lambda invocations disabled for '%s' by Lambda Debug Mode",
+                    self._lambda_qualified_arn,
+                )
+                raise TooManyRequestsException(
+                    "Rate Exceeded.",
+                    Reason="SingleLeaseEnforcement",
+                    Type="User",
+                )
+
+    def _on_execution_environment_timeout(
+        self, version_manager_id: str, environment_id: str
+    ) -> None:
+        # This function is run by the ExecutionEnvironment when the
+        # release of on-demand container times-out whilst waiting for
+        # invokes. However, DebugEnabledExecutionEnvironment are
+        # provisioned-concurrency ExecutionEnvironments.
+        LOG.warning(
+            "Lambda Debug Mode function '%s' timed out ('%s', '%s')",
+            self._lambda_qualified_arn,
+            version_manager_id,
+            environment_id,
+        )
+        self.stop_debug_enabled_execution_environment()
+
+
+class LDMConfigFileWatch:
+    _mutex: Final[RLock]
+    _stop_event: Final[Event]
+    _watch_thread: Final[Thread]
+
+    def __init__(self):
+        self._mutex = RLock()
+        self._stop_event = Event()
+        self._watch_thread = Thread(
+            target=self._watch_logic, args=(), daemon=True, name="LDMConfigFileWatch"
+        )
+
+    def start(self):
+        with self._mutex:
+            self._stop_event.clear()
+            if not self._watch_thread.is_alive():
+                self._watch_thread.start()
+
+    def stop(self):
+        with self._mutex:
+            self._stop_event.set()
+
+    def _watch_logic(self) -> None:
+        if not LAMBDA_DEBUG_MODE_CONFIG_PATH:
+            LOG.info("LDM: no definitions for LAMBDA_DEBUG_MODE_CONFIG_PATH")
+            return
+
+        # TODO: consider relying on system calls (watchdog lib for cross-platform support)
+        #  instead of monitoring last modified dates.
+        # Run the first load and signal as initialised.
+        epoch_last_loaded: int = self._config_file_epoch_last_modified_or_now()
+        self._update_ldm_from_ldm_config_file()
+
+        # Monitor for file changes whilst the application is running.
+        while not self._stop_event.is_set():
+            time.sleep(1)
+            epoch_last_modified = self._config_file_epoch_last_modified_or_now()
+            if epoch_last_modified > epoch_last_loaded:
+                epoch_last_loaded = epoch_last_modified
+                self._update_ldm_from_ldm_config_file()
+
+    @staticmethod
+    def _update_ldm_from_ldm_config_file() -> None:
+        yaml_configuration_string = None
+        try:
+            with open(LAMBDA_DEBUG_MODE_CONFIG_PATH, "r") as df:
+                yaml_configuration_string = df.read()
+        except FileNotFoundError:
+            LOG.error(
+                "LDM: The file lambda debug config file '%s' was not found.",
+                LAMBDA_DEBUG_MODE_CONFIG_PATH,
+            )
+        except IsADirectoryError:
+            LOG.error(
+                "LDM: Expected a lambda debug config file but found a directory at '%s'.",
+                LAMBDA_DEBUG_MODE_CONFIG_PATH,
+            )
+        except PermissionError:
+            LOG.error(
+                "LDM: Permission denied while trying to read the lambda debug config file '%s'.",
+                LAMBDA_DEBUG_MODE_CONFIG_PATH,
+            )
+        except Exception as ex:
+            LOG.error(
+                "LDM: An unexpected error occurred while reading lambda debug config '%s': '%s'",
+                LAMBDA_DEBUG_MODE_CONFIG_PATH,
+                ex,
+            )
+
+        if not yaml_configuration_string:
+            return
+
+        config = parse_ldm_config(yaml_configuration_string)
+        if config is not None:
+            LDM.remove_all_configurations()
+            for qualified_lambda_arn, ldm_config in config.functions.items():
+                LDM.add_configuration(
+                    config=LambdaFunctionDebugConfig(
+                        qualified_lambda_arn=qualified_lambda_arn,
+                        port=ldm_config.debug_port,
+                        enforce_timeouts=ldm_config.enforce_timeouts,
+                    )
+                )
+                LDM.enable_configuration(qualified_lambda_arn=qualified_lambda_arn)
+            LOG.info(
+                "LDM is now enforcing the latest configuration from the LDM configuration file"
+            )
+        else:
+            LOG.warning(
+                "LDM could not load the latest Lambda debug mode configuration "
+                "due to an error; check logs for more details."
+            )
+
+    @staticmethod
+    def _config_file_epoch_last_modified_or_now() -> int:
+        try:
+            modified_time = os.path.getmtime(LAMBDA_DEBUG_MODE_CONFIG_PATH)
+            return int(modified_time)
+        except Exception as e:
+            LOG.warning("LDM could not access the configuration file: %s", e)
+            epoch_now = int(time.time())
+            return epoch_now
+
+
+class LambdaDebugMode:
+    _mutex: Final[RLock]
+    _is_enabled: bool
+    _debug_targets: Final[dict[str, LambdaDebugTarget]]
+    _config_file_watch: Final[Optional[LDMConfigFileWatch]]
+
+    def __init__(self):
+        self._mutex = RLock()
+        self._is_enabled = bool(LAMBDA_DEBUG_MODE)
+        self._debug_targets = dict()
+        self._config_file_watch = LDMConfigFileWatch() if LAMBDA_DEBUG_MODE_CONFIG_PATH else None
+        if self._is_enabled:
+            self.start_debug_mode()
+
+    @staticmethod
+    @singleton_factory
+    def get() -> LambdaDebugMode:
+        """Returns a singleton instance of the Lambda Debug Mode session."""
+        return LambdaDebugMode()
+
+    def start_debug_mode(self) -> None:
+        with self._mutex:
+            self._is_enabled = True
+            if self._config_file_watch:
+                self._config_file_watch.start()
+
+    def stop_debug_mode(self) -> None:
+        with self._mutex:
+            self._is_enabled = False
+            if self._config_file_watch:
+                self._config_file_watch.stop()
+            self.remove_all_configurations()
+
+    def is_enabled(self) -> bool:
+        return self._is_enabled
+
+    def add_configuration(self, config: LambdaFunctionDebugConfig) -> None:
+        with self._mutex:
+            if not self._is_enabled:
+                return
+
+            arn = config.qualified_lambda_arn
+            if existing_target := self._debug_targets.get(arn):
+                existing_target.stop_debug_enabled_execution_environment()
+
+            target = LambdaDebugTarget(lambda_function_debug_config=config)
+            self._debug_targets[arn] = target
+
+    def enable_configuration(self, qualified_lambda_arn: Arn) -> None:
+        with self._mutex:
+            if not self._is_enabled:
+                return
+
+            if target := self._debug_targets.get(qualified_lambda_arn):
+                threading.Thread(
+                    target=target.start_debug_enabled_execution_environment,
+                    args=(),
+                    name=f"LambdaDebugTarget-start_debug_enabled_execution_environment-{qualified_lambda_arn}",
+                    daemon=True,
+                ).start()
+
+    def remove_configuration(self, qualified_lambda_arn: Arn) -> None:
+        with self._mutex:
+            if not self._is_enabled:
+                return
+
+            if target := self._debug_targets.pop(qualified_lambda_arn, None):
+                target.stop_debug_enabled_execution_environment()
+
+    def remove_all_configurations(self) -> None:
+        with self._mutex:
+            for target in self._debug_targets.values():
+                target.stop_debug_enabled_execution_environment()
+            self._debug_targets.clear()
+
+    def get_execution_environment(
+        self, qualified_lambda_arn: Arn, user_agent: Optional[str]
+    ) -> Optional[DebugEnabledExecutionEnvironment]:
+        if not self._is_enabled:
+            return None
+
+        if target := self._debug_targets.get(qualified_lambda_arn):
+            target_user_agent = target.lambda_function_debug_config.user_agent
+            if target_user_agent is None or target_user_agent == user_agent:
+                return target.get_execution_environment()
+        return None
+
+
+LDM: Final[LambdaDebugMode] = LambdaDebugMode.get()