playground-ls-cli 4.14.1.dev8__py3-none-any.whl

localstack_cli/pro/core/plugins.py

@@ -0,0 +1,169 @@
+"""
+Pro plugin hooks for the LocalStack CLI.
+
+These hooks are executed on the host machine when running CLI commands like `localstack start`.
+They handle license activation, container configuration, and extension developer mode.
+
+Note: This file was extracted from localstack-pro-core/localstack/pro/core/plugins.py
+and rewritten to contain only CLI-relevant functionality.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+import requests
+from localstack_cli import config as localstack_config
+from localstack_cli.config import HostAndPort
+from localstack_cli.constants import API_ENDPOINT
+from localstack_cli.pro.core import config as pro_config
+from localstack_cli.pro.core.bootstrap import licensingv2
+from localstack_cli.runtime import hooks
+from localstack_cli.runtime.exceptions import LocalstackExit
+from localstack_cli.utils.bootstrap import Container
+
+LOG = logging.getLogger(__name__)
+
+
+def modify_gateway_listen_config(cfg):
+    """
+    Modifies the localstack config to additionally listen to port 443.
+    Needs to be called before any edge URLs are resolved using the config.
+    """
+    if os.getenv("GATEWAY_LISTEN") is None:
+        host = "0.0.0.0" if localstack_config.in_docker() else "127.0.0.1"
+        cfg.GATEWAY_LISTEN.append(HostAndPort(host=host, port=443))
+
+
+@hooks.prepare_host(priority=200)
+def patch_community_pro_detection():
+    """This is currently needed to make localstack core aware of the `localstack auth set-token`
+    functionality, where we set the key into the ``~/.localstack/auth.json`` file that community does not
+    yet know about. ``is_api_key_configured`` is used in the LocalStack CLI to determine whether to start
+    the localstack or localstack-pro container image."""
+    from localstack_cli.utils import bootstrap
+
+    bootstrap.is_auth_token_configured = pro_config.is_auth_token_configured
+
+
+## ---------------------------------------------------------------------------
+## Grace period helpers (temporary, to be removed once grace period expires)
+## ---------------------------------------------------------------------------
+
+GRACE_PERIOD_ENDPOINT_PATH = "/license/grace-period-check"
+
+LICENSE_ERROR_MESSAGE = """\
+===============================================
+LocalStack requires an account to run.
+
+==> Have an account? Learn how to set LOCALSTACK_AUTH_TOKEN: https://app.localstack.cloud/settings/auth-tokens
+==> Need an account? Get started: https://www.localstack.cloud/pricing
+==> Want more time? Snooze until April 6, 2026 by setting LOCALSTACK_ACKNOWLEDGE_ACCOUNT_REQUIREMENT=1
+"""
+
+GRACE_PERIOD_EXPIRED_MESSAGE = """\
+===============================================
+LocalStack requires an account to run.
+
+==> Have an account? Learn how to set LOCALSTACK_AUTH_TOKEN: https://app.localstack.cloud/settings/auth-tokens
+==> Need an account? Get started: https://www.localstack.cloud/pricing
+"""
+
+
+def _check_grace_period_active(ack: bool) -> bool:
+    """Call the platform grace period endpoint.
+
+    Returns True if the grace period is active (200 response).
+    Returns False for any other response (including 404 when the endpoint is removed).
+    """
+    from localstack_cli.pro.core.bootstrap.licensingv2 import get_system_information_summary
+    from localstack_cli.pro.core.constants import VERSION
+    from localstack_cli.utils.analytics.metadata import get_client_metadata
+    from localstack_cli.utils.http import get_proxies
+
+    metadata = get_client_metadata()
+    payload = {
+        "machine": {
+            "id": metadata.machine_id,
+            "ci": metadata.is_ci,
+            "system": get_system_information_summary(),
+        },
+        "version": VERSION,
+        "requesting_grace": ack,
+    }
+
+    url = f"{API_ENDPOINT}{GRACE_PERIOD_ENDPOINT_PATH}"
+    proxies = get_proxies()
+
+    try:
+        response = requests.post(
+            url,
+            json=payload,
+            verify=not localstack_config.is_env_true("SSL_NO_VERIFY"),
+            proxies=proxies,
+            timeout=10,
+        )
+        return response.ok
+    except requests.exceptions.RequestException:
+        LOG.debug("Failed to reach grace period endpoint at %s", url)
+        return False
+
+
+## ---------------------------------------------------------------------------
+
+
+@hooks.prepare_host(priority=100, should_load=pro_config.ACTIVATE_PRO)
+def activate_pro_key_on_host():
+    """Activate license on host (needed for DNS forward and EC2 daemon)."""
+    try:
+        licensingv2.get_licensed_environment().activate()
+    except licensingv2.LicensingError as e:
+        # license activation was unsuccessful (this can also be because no auth token was set)
+        # defensively set pro to False so that we don't load pro plugins
+        pro_config.ACTIVATE_PRO = False
+
+        # check also with LOCALSTACK_ prefix here because we don't have the handling from the docker entrypoint on the host
+        ack = localstack_config.is_env_true(
+            "LOCALSTACK_ACKNOWLEDGE_ACCOUNT_REQUIREMENT") or localstack_config.is_env_true(
+            "ACKNOWLEDGE_ACCOUNT_REQUIREMENT")
+        # Note: this can also fail because they've got their connection set up wrong.
+        active = _check_grace_period_active(ack)
+        if not ack and active:
+            # Grace period is active but unused. Prompt user to set up account or snooze.
+            raise LocalstackExit(reason=LICENSE_ERROR_MESSAGE, code=55)
+        if ack and active:
+            # Grace period is active, start in community mode (no pro features).
+            LOG.info("Grace period active: starting LocalStack in community mode")
+            return
+        if ack and not active:
+            # Grace period expired or endpoint unreachable
+            raise LocalstackExit(reason=GRACE_PERIOD_EXPIRED_MESSAGE, code=55)
+        raise LocalstackExit(reason=e.get_user_friendly(), code=55)
+
+
+@hooks.configure_localstack_container(priority=10, should_load=pro_config.ACTIVATE_PRO)
+def configure_pro_container(container: Container):
+    """Configure the LocalStack container for pro features."""
+    modify_gateway_listen_config(localstack_config)
+    container.configure(licensingv2.configure_container_licensing)
+
+
+@hooks.prepare_host(should_load=pro_config.ACTIVATE_PRO and pro_config.EXTENSION_DEV_MODE)
+def configure_extensions_dev_host():
+    """Load extension directories from ~/.localstack/extensions-dev.json."""
+    from localstack_cli.pro.core.bootstrap.extensions.bootstrap import run_on_configure_host_hook
+
+    run_on_configure_host_hook()
+
+
+@hooks.configure_localstack_container(
+    should_load=pro_config.ACTIVATE_PRO and pro_config.EXTENSION_DEV_MODE
+)
+def configure_extensions_dev_container(container: Container):
+    """Configure container for extension developer mode."""
+    from localstack_cli.pro.core.bootstrap.extensions.bootstrap import (
+        run_on_configure_localstack_container_hook,
+    )
+
+    run_on_configure_localstack_container_hook(container)

localstack_cli/runtime/__init__.py

@@ -0,0 +1,6 @@
+"""Runtime utilities for the LocalStack CLI."""
+
+from localstack_cli.runtime import hooks  # noqa: F401
+
+# get_current_runtime is not available in the standalone CLI - only in the full LocalStack runtime
+get_current_runtime = None

localstack_cli/runtime/exceptions.py

@@ -0,0 +1,7 @@
+class LocalstackExit(Exception):
+    """Raised to gracefully exit LocalStack."""
+
+    def __init__(self, reason: str = None, code: int = 1):
+        self.reason = reason
+        self.code = code
+        super().__init__(reason)

localstack_cli/runtime/hooks.py

@@ -0,0 +1,73 @@
+import functools
+
+from plux import PluginManager, plugin
+
+# plugin namespace constants
+HOOKS_CONFIGURE_LOCALSTACK_CONTAINER = "localstack_cli.hooks.configure_localstack_container"
+HOOKS_PREPARE_HOST = "localstack_cli.hooks.prepare_host"
+
+
+def hook(namespace: str, priority: int = 0, **kwargs):
+    """
+    Decorator for creating functional plugins that have a hook_priority attribute. Hooks with a higher priority value
+    will be executed earlier.
+    """
+
+    def wrapper(fn):
+        fn.hook_priority = priority
+        return plugin(namespace=namespace, **kwargs)(fn)
+
+    return wrapper
+
+
+def hook_spec(namespace: str):
+    """
+    Creates a new hook decorator bound to a namespace.
+
+    on_infra_start = hook_spec("localstack.hooks.on_infra_start")
+
+    @on_infra_start()
+    def foo():
+        pass
+
+    # run all hooks in order
+    on_infra_start.run()
+    """
+    fn = functools.partial(hook, namespace=namespace)
+    # attach hook manager and run method to decorator for convenience calls
+    fn.manager = HookManager(namespace)
+    fn.run = fn.manager.run_in_order
+    return fn
+
+
+class HookManager(PluginManager):
+    def load_all_sorted(self, propagate_exceptions=False):
+        """
+        Loads all hook plugins and sorts them by their hook_priority attribute.
+        """
+        plugins = self.load_all(propagate_exceptions)
+        # the hook_priority attribute is part of the function wrapped in the FunctionPlugin
+        plugins.sort(
+            key=lambda _fn_plugin: getattr(_fn_plugin.fn, "hook_priority", 0), reverse=True
+        )
+        return plugins
+
+    def run_in_order(self, *args, **kwargs):
+        """
+        Loads and runs all plugins in order them with the given arguments.
+        """
+        for fn_plugin in self.load_all_sorted():
+            fn_plugin(*args, **kwargs)
+
+    def __str__(self):
+        return f"HookManager({self.namespace})"
+
+    def __repr__(self):
+        return self.__str__()
+
+
+configure_localstack_container = hook_spec(HOOKS_CONFIGURE_LOCALSTACK_CONTAINER)
+"""Hooks to configure the LocalStack container before it starts. Executed on the host when invoking the CLI."""
+
+prepare_host = hook_spec(HOOKS_PREPARE_HOST)
+"""Hooks to prepare the host that's starting LocalStack. Executed on the host when invoking the CLI."""

localstack_cli/testing/__init__.py

@@ -0,0 +1 @@
+"""Testing utilities for the LocalStack CLI."""

localstack_cli/testing/config.py

@@ -0,0 +1,4 @@
+"""Testing configuration constants."""
+
+# Secondary test account ID for multi-account testing scenarios
+SECONDARY_TEST_AWS_ACCOUNT_ID = "886468871268"

localstack_cli/utils/analytics/__init__.py

@@ -0,0 +1,12 @@
+from .logger import EventLogger
+from .metadata import get_session_id
+from .publisher import GlobalAnalyticsBus
+
+name = "analytics"
+
+
+def _create_global_analytics_bus():
+    return GlobalAnalyticsBus()
+
+
+log = EventLogger(handler=_create_global_analytics_bus(), session_id=get_session_id())

localstack_cli/utils/analytics/cli.py

@@ -0,0 +1,67 @@
+import datetime
+import functools
+from multiprocessing import Process
+
+import click
+
+from localstack_cli import config
+
+from .client import AnalyticsClient
+from .events import Event, EventMetadata
+from .metadata import get_session_id
+from .publisher import AnalyticsClientPublisher
+
+ANALYTICS_API_RESPONSE_TIMEOUT_SECS = 0.5
+
+
+def _publish_cmd_as_analytics_event(command_name: str, params: list[str]):
+    event = Event(
+        name="cli_cmd",
+        payload={"cmd": command_name, "params": params},
+        metadata=EventMetadata(
+            session_id=get_session_id(),
+            client_time=str(datetime.datetime.now()),  # TODO: consider using utcnow()
+        ),
+    )
+    publisher = AnalyticsClientPublisher(AnalyticsClient())
+    publisher.publish([event])
+
+
+def _get_parent_commands(ctx: click.Context) -> list[str]:
+    parent_commands = []
+    parent = ctx.parent
+    while parent is not None:
+        parent_commands.insert(0, parent.command.name)
+        parent = parent.parent
+    return parent_commands
+
+
+def publish_invocation(fn):
+    """
+    Decorator for capturing CLI commands from Click and publishing them to the backend as analytics events.
+    This decorator should only be used on outermost subcommands, e.g. "localstack status docker" not "localstack status"
+    otherwise it may publish multiple events for a single invocation.
+    If DISABLE_EVENTS is set then nothing is collected.
+    For performance reasons, the API call to the backend runs on a separate process and is killed if it takes longer
+    than ANALYTICS_API_RESPONSE_TIMEOUT_SECS.
+    The emitted event contains the invoked command, plus any parameter names if their associated values are truthy (but
+    not the values themselves).
+    """
+
+    @functools.wraps(fn)
+    def publisher_wrapper(*args, **kwargs):
+        if config.DISABLE_EVENTS:
+            return fn(*args, **kwargs)
+
+        ctx = click.get_current_context()
+        full_command = " ".join(_get_parent_commands(ctx) + [ctx.command.name])
+        publish_cmd_process = Process(
+            target=_publish_cmd_as_analytics_event,
+            args=(full_command, [k for k, v in ctx.params.items() if v]),
+        )
+        publish_cmd_process.start()
+        publish_cmd_process.join(ANALYTICS_API_RESPONSE_TIMEOUT_SECS)
+        publish_cmd_process.terminate()
+        return fn(*args, **kwargs)
+
+    return publisher_wrapper

localstack_cli/utils/analytics/client.py

@@ -0,0 +1,111 @@
+"""
+Client for the analytics backend.
+"""
+
+import logging
+from typing import Any
+
+import requests
+
+from localstack_cli import config, constants
+from localstack_cli.utils.http import get_proxies
+from localstack_cli.utils.time import now
+
+from .events import Event, EventMetadata
+from .metadata import ClientMetadata, get_session_id
+
+LOG = logging.getLogger(__name__)
+
+
+class SessionResponse:
+    response: dict[str, Any]
+    status: int
+
+    def __init__(self, response: dict[str, Any], status: int = 200):
+        self.response = response
+        self.status = status
+
+    def track_events(self) -> bool:
+        return self.response.get("track_events")
+
+    def __repr__(self):
+        return f"SessionResponse({self.status},{self.response!r})"
+
+
+class AnalyticsClient:
+    api: str
+
+    def __init__(self, api=None):
+        self.api = (api or constants.ANALYTICS_API).rstrip("/")
+        self.debug = config.DEBUG_ANALYTICS
+
+        self.endpoint_session = self.api + "/session"
+        self.endpoint_events = self.api + "/events"
+
+        self.localstack_session_id = get_session_id()
+        self.session = requests.Session()
+
+    def close(self):
+        self.session.close()
+
+    def start_session(self, metadata: ClientMetadata) -> SessionResponse:
+        # FIXME: re-using Event as request object this way is kind of a hack
+        request = Event(
+            "session", EventMetadata(self.localstack_session_id, str(now())), payload=metadata
+        )
+
+        response = self.session.post(
+            self.endpoint_session,
+            headers=self._create_headers(),
+            json=request.asdict(),
+            proxies=get_proxies(),
+        )
+
+        # 403 errors may indicate that track_events=False
+        if response.ok or response.status_code == 403:
+            return SessionResponse(response.json(), status=response.status_code)
+
+        raise ValueError(
+            f"error during session initiation with analytics backend. code: {response.status_code}"
+        )
+
+    # TODO: naming seems confusing since this doesn't actually append, but directly sends all passed events via HTTP
+    def append_events(self, events: list[Event]):
+        # TODO: add compression to append_events
+        #  it would maybe be useful to compress analytics data, but it's unclear how that will
+        #  affect performance and what the benefit is. need to measure first.
+
+        endpoint = self.endpoint_events
+
+        if not events:
+            return
+
+        docs = []
+        for event in events:
+            try:
+                docs.append(event.asdict())
+            except Exception:
+                if self.debug:
+                    LOG.exception("error while recording event %s", event)
+
+        headers = self._create_headers()
+
+        if self.debug:
+            LOG.debug("posting to %s events %s", endpoint, docs)
+
+        # FIXME: fault tolerance/timeouts
+        response = self.session.post(
+            endpoint, json={"events": docs}, headers=headers, proxies=get_proxies()
+        )
+
+        if self.debug:
+            LOG.debug("response from %s was: %s %s", endpoint, response.status_code, response.text)
+
+        # TODO: Add response type to analytics client
+        return response
+
+    def _create_headers(self) -> dict[str, str]:
+        return {
+            "User-Agent": "localstack/" + constants.VERSION,
+            "Localstack-Session-ID": self.localstack_session_id,
+        }

localstack_cli/utils/analytics/events.py

@@ -0,0 +1,30 @@
+import abc
+import dataclasses
+from typing import Any
+
+EventPayload = dict[str, Any] | Any  # FIXME: better typing
+
+
+@dataclasses.dataclass
+class EventMetadata:
+    session_id: str
+    client_time: str
+
+
+@dataclasses.dataclass
+class Event:
+    name: str
+    metadata: EventMetadata = None
+    payload: EventPayload = None
+
+    def asdict(self):
+        return dataclasses.asdict(self)
+
+
+class EventHandler(abc.ABC):
+    """
+    Event handlers dispatch events to specific destinations.
+    """
+
+    def handle(self, event: Event):
+        raise NotImplementedError

localstack_cli/utils/analytics/logger.py

@@ -0,0 +1,48 @@
+import datetime
+import hashlib
+
+from localstack_cli.utils.strings import to_bytes
+
+from .events import Event, EventHandler, EventMetadata, EventPayload
+from .metadata import get_session_id
+
+
+def get_hash(value) -> str:
+    max_length = 10
+    digest = hashlib.sha1()
+    digest.update(to_bytes(str(value)))
+    result = digest.hexdigest()
+    return result[:max_length]
+
+
+class EventLogger:
+    """
+    High-level interface over analytics event abstraction. Expose specific event types as
+    concrete functions to call in the code.
+    """
+
+    def __init__(self, handler: EventHandler, session_id: str = None):
+        self.handler = handler
+        self.session_id = session_id or get_session_id()
+
+    @staticmethod
+    def hash(value):
+        return get_hash(value)
+
+    def event(self, event: str, payload: EventPayload = None, **kwargs):
+        if kwargs:
+            if payload is None:
+                payload = kwargs
+            else:
+                raise ValueError("either use payload or set kwargs, not both")
+
+        self._log(event, payload=payload)
+
+    def _log(self, event: str, payload: EventPayload = None):
+        self.handler.handle(Event(name=event, metadata=self._metadata(), payload=payload))
+
+    def _metadata(self) -> EventMetadata:
+        return EventMetadata(
+            session_id=self.session_id,
+            client_time=str(datetime.datetime.now()),
+        )