ob-metaflow-extensions 1.1.151__py2.py3-none-any.whl → 1.6.2__py2.py3-none-any.whl

metaflow_extensions/outerbounds/plugins/apps/core/secrets.py

@@ -0,0 +1,164 @@
+from typing import Dict
+
+import base64
+import json
+import requests
+import random
+import time
+import sys
+
+from .utils import safe_requests_wrapper, TODOException
+
+
+class OuterboundsSecretsException(Exception):
+    pass
+
+
+class SecretNotFound(OuterboundsSecretsException):
+    pass
+
+
+class OuterboundsSecretsApiResponse:
+    def __init__(self, response):
+        self.response = response
+
+    @property
+    def secret_resource_id(self):
+        return self.response["secret_resource_id"]
+
+    @property
+    def secret_backend_type(self):
+        return self.response["secret_backend_type"]
+
+
+class SecretRetriever:
+    def get_secret_as_dict(self, secret_id, options={}, role=None):
+        """
+        Supports a special way of specifying secrets sources in outerbounds using the format:
+            @secrets(sources=["outerbounds.<integrations_name>"])
+
+        When invoked it makes a requests to the integrations secrets metadata endpoint on the
+        keywest server to get the cloud resource id for a secret. It then uses that to invoke
+        secrets manager on the core oss and returns the secrets.
+        """
+        headers = {"Content-Type": "application/json", "Connection": "keep-alive"}
+        perimeter, integrations_url = self._get_secret_configs()
+        integration_name = secret_id
+        request_payload = {
+            "perimeter_name": perimeter,
+            "integration_name": integration_name,
+        }
+        response = self._make_request(integrations_url, headers, request_payload)
+        secret_resource_id = response.secret_resource_id
+        secret_backend_type = response.secret_backend_type
+
+        from metaflow.plugins.secrets.secrets_decorator import (
+            get_secrets_backend_provider,
+        )
+
+        secrets_provider = get_secrets_backend_provider(secret_backend_type)
+        secret_dict = secrets_provider.get_secret_as_dict(
+            secret_resource_id, options={}, role=role
+        )
+
+        # Outerbounds stores secrets as binaries. Hence we expect the returned secret to be
+        # {<cloud-secret-name>: <base64 encoded full secret>}. We decode the secret here like:
+        # 1. decode the base64 encoded full secret
+        # 2. load the decoded secret as a json
+        # 3. decode the base64 encoded values in the dict
+        # 4. return the decoded dict
+        binary_secret = next(iter(secret_dict.values()))
+        return self._decode_secret(binary_secret)
+
+    def _is_base64_encoded(self, data):
+        try:
+            if isinstance(data, str):
+                # Check if the string can be base64 decoded
+                base64.b64decode(data).decode("utf-8")
+                return True
+            return False
+        except Exception:
+            return False
+
+    def _decode_secret(self, secret):
+        try:
+            result = {}
+            secret_str = secret
+            if self._is_base64_encoded(secret):
+                # we check if the secret string is base64 encoded because the returned secret from
+                # AWS secret manager is base64 encoded while the secret from GCP is not
+                secret_str = base64.b64decode(secret).decode("utf-8")
+
+            secret_dict = json.loads(secret_str)
+            for key, value in secret_dict.items():
+                result[key] = base64.b64decode(value).decode("utf-8")
+
+            return result
+        except Exception as e:
+            raise OuterboundsSecretsException(f"Error decoding secret: {e}")
+
+    def _get_secret_configs(self):
+        from metaflow_extensions.outerbounds.remote_config import init_config  # type: ignore
+        from os import environ
+
+        conf = init_config()
+        if "OBP_PERIMETER" in conf:
+            perimeter = conf["OBP_PERIMETER"]
+        else:
+            # if the perimeter is not in metaflow config, try to get it from the environment
+            perimeter = environ.get("OBP_PERIMETER", "")
+
+        if "OBP_INTEGRATIONS_URL" in conf:
+            integrations_url = conf["OBP_INTEGRATIONS_URL"]
+        else:
+            # if the integrations is not in metaflow config, try to get it from the environment
+            integrations_url = environ.get("OBP_INTEGRATIONS_URL", "")
+
+        if not perimeter:
+            raise OuterboundsSecretsException(
+                "No perimeter set. Please make sure to run `outerbounds configure <...>` command which can be found on the Outerbounds UI or reach out to your Outerbounds support team."
+            )
+
+        if not integrations_url:
+            raise OuterboundsSecretsException(
+                "No integrations url set. Please notify your Outerbounds support team about this issue."
+            )
+
+        integrations_secrets_metadata_url = f"{integrations_url}/secrets/metadata"
+        return perimeter, integrations_secrets_metadata_url
+
+    def _make_request(self, url, headers: Dict, payload: Dict):
+        try:
+            from metaflow.metaflow_config import SERVICE_HEADERS
+
+            request_headers = {**headers, **(SERVICE_HEADERS or {})}
+        except ImportError:
+            raise OuterboundsSecretsException(
+                "Failed to create app: No Metaflow service headers found"
+            )
+
+        response = safe_requests_wrapper(
+            requests.get,
+            url,
+            data=json.dumps(payload),
+            headers=request_headers,
+            conn_error_retries=5,
+            retryable_status_codes=[409],
+        )
+        self._handle_error_response(response)
+        return OuterboundsSecretsApiResponse(response.json())
+
+    @staticmethod
+    def _handle_error_response(response: requests.Response):
+        if response.status_code >= 500:
+            raise OuterboundsSecretsException(
+                f"Server error: {response.text}. Please reach out to your Outerbounds support team."
+            )
+        status_code = response.status_code
+        if status_code == 404:
+            raise SecretNotFound(f"Secret not found: {response.text}")
+
+        if status_code >= 400:
+            raise OuterboundsSecretsException(
+                f"status_code={status_code}\t\n\t\t{response.text}"
+            )

metaflow_extensions/outerbounds/plugins/apps/core/utils.py

@@ -0,0 +1,233 @@
+import random
+import time
+import sys
+import json
+import requests
+from typing import Optional
+
+# This click import is not used to construct any ob
+# package cli. Its used only for printing stuff.
+# So we can use the static metaflow._vendor import path
+from metaflow._vendor import click
+from .app_config import CAPSULE_DEBUG
+import sys
+import threading
+import time
+import logging
+import itertools
+from typing import Union, Callable, Any, List
+
+from ._vendor.spinner import (
+    Spinners,
+)
+
+
+class MultiStepSpinner:
+    """
+    A spinner that supports multi-step progress and configurable alignment.
+
+    Parameters
+    ----------
+    spinner : Spinners
+        Which spinner frames/interval to use.
+    text : str
+        Static text to display beside the spinner.
+    color : str, optional
+        Click color name.
+    align : {'left','right'}
+        Whether to render the spinner to the left (default) or right of the text.
+    """
+
+    def __init__(
+        self,
+        spinner: Spinners = Spinners.dots,
+        text: str = "",
+        color: Optional[str] = None,
+        align: str = "right",
+        file=sys.stdout,
+    ):
+        cfg = spinner.value
+        self.frames = cfg["frames"]
+        self.interval = float(cfg["interval"]) / 1000.0  # type: ignore
+        self.text = text
+        self.color = color
+        if align not in ("left", "right"):
+            raise ValueError("align must be 'left' or 'right'")
+        self.align = align
+        self._write_file = file
+        # precompute clear length: max frame width + space + text length
+        max_frame = max(self.frames, key=lambda x: len(x))  # type: ignore
+        self.clear_len = len(self.main_text) + len(max_frame) + 1
+
+        self._stop_evt = threading.Event()
+        self._pause_evt = threading.Event()
+        self._thread = None
+        self._write_lock = threading.Lock()
+
+    @property
+    def main_text(self):
+        # if self.text is a callable then call it
+        if callable(self.text):
+            return self.text()
+        return self.text
+
+    def _spin(self):
+        for frame in itertools.cycle(self.frames):
+            if self._stop_evt.is_set():
+                break
+            if self._pause_evt.is_set():
+                time.sleep(0.05)
+                continue
+
+            # ---- Core logging critical section ----
+            with self._write_lock:
+                symbol = click.style(frame, fg=self.color) if self.color else frame
+                if self.align == "left":
+                    msg = f"{symbol} {self.main_text}"
+                else:
+                    msg = f"{self.main_text} {symbol}"
+
+                click.echo(msg, nl=False, file=self._write_file)
+                click.echo("\r", nl=False, file=self._write_file)
+                self._write_file.flush()
+            # ---- End of critical section ----
+            time.sleep(self.interval)
+        # clear the line when done
+        self._clear_line()
+
+    def _clear_line(self):
+        with self._write_lock:
+            click.echo(" " * self.clear_len, nl=False, file=self._write_file)
+            click.echo("\r", nl=False, file=self._write_file)
+            self._write_file.flush()
+
+    def start(self):
+        if self._thread and self._thread.is_alive():
+            return
+        self._stop_evt.clear()
+        self._pause_evt.clear()
+        self._thread = threading.Thread(target=self._spin, daemon=True)
+        self._thread.start()
+
+    def stop(self):
+        self._stop_evt.set()
+        if self._thread:
+            self._thread.join()
+
+    def log(self, *messages: str):
+        """Pause the spinner, emit a ✔ + message, then resume."""
+        self._pause_evt.set()
+        self._clear_line()
+        # ---- Core logging critical section ----
+        with self._write_lock:
+            self._write_file.flush()
+            for message in messages:
+                click.echo(f"{message}", file=self._write_file, nl=True)
+            self._write_file.flush()
+        # ---- End of critical section ----
+        self._pause_evt.clear()
+
+    def __enter__(self):
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.stop()
+
+
+class SpinnerLogHandler(logging.Handler):
+    def __init__(self, spinner: MultiStepSpinner, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.spinner = spinner
+
+    def emit(self, record):
+        msg = self.format(record)
+        self.spinner.log(msg)
+
+
+class MaximumRetriesExceeded(Exception):
+    def __init__(self, url, method, status_code, text):
+        self.url = url
+        self.method = method
+        self.status_code = status_code
+        self.text = text
+
+    def __str__(self):
+        return f"Maximum retries exceeded for {self.url}[{self.method}] {self.status_code} {self.text}"
+
+
+class TODOException(Exception):
+    pass
+
+
+requests_funcs = [
+    requests.get,
+    requests.post,
+    requests.put,
+    requests.delete,
+    requests.patch,
+    requests.head,
+    requests.options,
+]
+
+
+def safe_requests_wrapper(
+    requests_module_fn,
+    *args,
+    conn_error_retries=2,
+    retryable_status_codes=[409],
+    logger_fn=None,
+    **kwargs,
+):
+    """
+    There are two categories of errors that we need to handle when dealing with any API server.
+    1. HTTP errors. These are are errors that are returned from the API server.
+        - How to handle retries for this case will be application specific.
+    2. Errors when the API server may not be reachable (DNS resolution / network issues)
+        - In this scenario, we know that something external to the API server is going wrong causing the issue.
+        - Failing prematurely in the case might not be the best course of action since critical user jobs might crash on intermittent issues.
+        - So in this case, we can just plainly retry the request.
+
+    This function handles the second case. It's a simple wrapper to handle the retry logic for connection errors.
+    If this function is provided a `conn_error_retries` of 5, then the last retry will have waited 32 seconds.
+    Generally this is a safe enough number of retries after which we can assume that something is really broken. Until then,
+    there can be intermittent issues that would resolve themselves if we retry gracefully.
+    """
+    if requests_module_fn not in requests_funcs:
+        raise ValueError(
+            f"safe_requests_wrapper doesn't support {requests_module_fn.__name__}. You can only use the following functions: {requests_funcs}"
+        )
+
+    _num_retries = 0
+    noise = random.uniform(-0.5, 0.5)
+    response = None
+    while _num_retries < conn_error_retries:
+        try:
+            response = requests_module_fn(*args, **kwargs)
+            if response.status_code not in retryable_status_codes:
+                return response
+            if CAPSULE_DEBUG:
+                if logger_fn:
+                    logger_fn(
+                        f"[outerbounds-debug] safe_requests_wrapper: {response.url}[{requests_module_fn.__name__}] {response.status_code} {response.text}",
+                    )
+                else:
+                    print(
+                        f"[outerbounds-debug] safe_requests_wrapper: {response.url}[{requests_module_fn.__name__}] {response.status_code} {response.text}",
+                        file=sys.stderr,
+                    )
+            _num_retries += 1
+            time.sleep((2 ** (_num_retries + 1)) + noise)
+        except requests.exceptions.ConnectionError:
+            if _num_retries <= conn_error_retries - 1:
+                # Exponential backoff with 2^(_num_retries+1) seconds
+                time.sleep((2 ** (_num_retries + 1)) + noise)
+                _num_retries += 1
+            else:
+                raise
+    raise MaximumRetriesExceeded(
+        response.url,
+        requests_module_fn.__name__,
+        response.status_code,
+        response.text,
+    )

metaflow_extensions/outerbounds/plugins/apps/core/validations.py

@@ -0,0 +1,17 @@
+import os
+from typing import List
+from .app_config import AppConfig, AppConfigError
+from .secrets import SecretRetriever, SecretNotFound
+
+
+def secrets_validator(secrets: List[str]):
+    secret_retriever = SecretRetriever()
+    for secret in secrets:
+        try:
+            secret_retriever.get_secret_as_dict(secret)
+        except SecretNotFound:
+            raise Exception(f"Secret named `{secret}` not found")
+
+
+def run_validations(app_config: AppConfig):
+    pass

metaflow_extensions/outerbounds/plugins/aws/__init__.py

@@ -0,0 +1,4 @@
+from .assume_role_decorator import assume_role
+from .assume_role import OBP_ASSUME_ROLE_ARN_ENV_VAR
+
+__mf_promote_submodules__ = ["plugins.aws"]

metaflow_extensions/outerbounds/plugins/aws/assume_role.py

@@ -0,0 +1,3 @@
+# Environment variable name used by the assume_role decorator to pass
+# the role ARN to AWS client functions
+OBP_ASSUME_ROLE_ARN_ENV_VAR = "OBP_ASSUME_ROLE_ARN"

metaflow_extensions/outerbounds/plugins/aws/assume_role_decorator.py

@@ -0,0 +1,118 @@
+from metaflow.user_decorators.mutable_flow import MutableFlow
+from metaflow.user_decorators.mutable_step import MutableStep
+from metaflow.user_decorators.user_flow_decorator import FlowMutator
+from .assume_role import OBP_ASSUME_ROLE_ARN_ENV_VAR
+
+
+class assume_role(FlowMutator):
+    """
+    Flow-level decorator for assuming AWS IAM roles.
+
+    When applied to a flow, all steps in the flow will automatically use the specified IAM role-arn
+    as their source principal.
+
+    Usage:
+    ------
+    @assume_role(role_arn="arn:aws:iam::123456789012:role/my-iam-role")
+    class MyFlow(FlowSpec):
+        @step
+        def start(self):
+            import boto3
+            client = boto3.client("dynamodb")  # Automatically uses the role in the flow decorator
+            self.next(self.end)
+
+        @step
+        def end(self):
+            from metaflow import get_aws_client
+            client = get_aws_client("dynamodb")  # Automatically uses the role in the flow decorator
+
+    You can also filter which steps should use the role:
+    @assume_role(role_arn="arn:aws:iam::123456789012:role/my-iam-role", steps=["start", "process"])
+    class MyFlow(FlowSpec):
+        @step
+        def start(self):
+            # user code in this step will use the assumed role
+            pass
+
+        @step
+        def process(self):
+            # user code in this step will use the assumed role
+            pass
+
+        @step
+        def end(self):
+            # user code in this step will NOT use the assumed role
+            pass
+    """
+
+    def init(self, *args, **kwargs):
+        self.role_arn = kwargs.get("role_arn", None)
+        self.steps = kwargs.get("steps", None)
+
+        if self.role_arn is None:
+            raise ValueError(
+                "`role_arn` keyword argument is required for the assume_role decorator"
+            )
+
+        if not self.role_arn.startswith("arn:aws:iam::"):
+            raise ValueError(
+                "`role_arn` must be a valid AWS IAM role ARN starting with 'arn:aws:iam::'"
+            )
+
+        # Validate steps parameter
+        if self.steps is not None:
+            if not isinstance(self.steps, (list, tuple)):
+                raise ValueError("`steps` must be a list or tuple of step names")
+            if not all(isinstance(s, str) for s in self.steps):
+                raise ValueError("All step names in `steps` must be strings")
+
+    def pre_mutate(self, mutable_flow: MutableFlow) -> None:
+        """
+        This method is called by Metaflow to apply the decorator to the flow.
+        It sets up environment variables that will be used by the AWS client
+        to automatically assume the specified role.
+        """
+        # Import environment decorator at runtime to avoid circular imports
+        from metaflow import environment
+
+        # Validate that all specified steps exist in the flow
+        if self.steps is not None:
+            flow_step_names = {step_name for step_name, _ in mutable_flow.steps}
+            specified_steps = set(self.steps)
+            missing_steps = specified_steps - flow_step_names
+
+            if missing_steps:
+                raise ValueError(
+                    f"Step(s) {sorted(missing_steps)} specified in `steps` parameter "
+                    f"do not exist in the flow. Available steps: {sorted(flow_step_names)}"
+                )
+
+        def _swap_environment_variables(step: MutableStep, role_arn: str) -> None:
+            _step_has_env_set = True
+            _env_kwargs = {OBP_ASSUME_ROLE_ARN_ENV_VAR: role_arn}
+            for d in step.decorator_specs:
+                name, _, _, deco_kwargs = d
+                if name == "environment":
+                    _env_kwargs.update(deco_kwargs["vars"])
+                    _step_has_env_set = True
+
+            if _step_has_env_set:
+                # remove the environment decorator
+                step.remove_decorator("environment")
+
+            # add the environment decorator
+            step.add_decorator(
+                environment,
+                deco_kwargs=dict(vars=_env_kwargs),
+            )
+
+        # Set the role ARN as an environment variable that will be picked up
+        # by the get_aws_client function
+        def _setup_role_assumption(step: MutableStep) -> None:
+            _swap_environment_variables(step, self.role_arn)
+
+        # Apply the role assumption setup to all steps in the flow (or filtered steps)
+        for step_name, step in mutable_flow.steps:
+            # If steps filter is specified, only apply to those steps
+            if self.steps is None or step_name in self.steps:
+                _setup_role_assumption(step)

metaflow_extensions/outerbounds/plugins/checkpoint_datastores/coreweave.py

@@ -1,12 +1,11 @@
-from metaflow.user_configs.config_decorators import (
-    MutableFlow,
-    MutableStep,
-    CustomFlowDecorator,
-)
+from metaflow.user_decorators.user_flow_decorator import FlowMutator
+from metaflow.user_decorators.mutable_flow import MutableFlow
+from metaflow.user_decorators.mutable_step import MutableStep
+from .external_chckpt import _ExternalCheckpointFlowDeco
 import os
 
 
-class coreweave_checkpoints(CustomFlowDecorator):
+class coreweave_checkpoints(_ExternalCheckpointFlowDeco):
 
     """
 
@@ -46,78 +45,14 @@ class coreweave_checkpoints(CustomFlowDecorator):
         super().__init__(*args, **kwargs)
 
     def init(self, *args, **kwargs):
-        self.bucket_path = kwargs.get("bucket_path", None)
-
-        self.secrets = kwargs.get("secrets", [])
-        if self.bucket_path is None:
-            raise ValueError(
-                "`bucket_path` keyword argument is required for the coreweave_datastore"
-            )
-        if not self.bucket_path.startswith("s3://"):
-            raise ValueError(
-                "`bucket_path` must start with `s3://` for the coreweave_datastore"
-            )
-
+        super().init(*args, **kwargs)
         self.coreweave_endpoint_url = f"https://cwobject.com"
-        if self.secrets is None:
-            raise ValueError(
-                "`secrets` keyword argument is required for the coreweave_datastore"
-            )
 
-    def evaluate(self, mutable_flow: MutableFlow) -> None:
+    def pre_mutate(self, mutable_flow: MutableFlow) -> None:
         from metaflow import (
-            checkpoint,
-            model,
-            huggingface_hub,
-            secrets,
             with_artifact_store,
         )
 
-        def _add_secrets(step: MutableStep) -> None:
-            decos_to_add = []
-            swapping_decos = {
-                "huggingface_hub": huggingface_hub,
-                "model": model,
-                "checkpoint": checkpoint,
-            }
-            already_has_secrets = False
-            secrets_present_in_deco = []
-            for d in step.decorators:
-                if d.name in swapping_decos:
-                    decos_to_add.append((d.name, d.attributes))
-                elif d.name == "secrets":
-                    already_has_secrets = True
-                    secrets_present_in_deco.extend(d.attributes["sources"])
-
-            # If the step aleady has secrets then take all the sources in
-            # the secrets and add the addtional secrets to the existing secrets
-            secrets_to_add = self.secrets
-            if already_has_secrets:
-                secrets_to_add.extend(secrets_present_in_deco)
-
-            secrets_to_add = list(set(secrets_to_add))
-
-            if len(decos_to_add) == 0:
-                if already_has_secrets:
-                    step.remove_decorator("secrets")
-
-                step.add_decorator(
-                    secrets,
-                    sources=secrets_to_add,
-                )
-                return
-
-            for d, _ in decos_to_add:
-                step.remove_decorator(d)
-
-            step.add_decorator(
-                secrets,
-                sources=secrets_to_add,
-            )
-            for d, attrs in decos_to_add:
-                _deco_to_add = swapping_decos[d]
-                step.add_decorator(_deco_to_add, **attrs)
-
         def _coreweave_config():
             return {
                 "root": self.bucket_path,
@@ -131,9 +66,6 @@ class coreweave_checkpoints(CustomFlowDecorator):
 
         mutable_flow.add_decorator(
             with_artifact_store,
-            type="coreweave",
-            config=_coreweave_config,
+            deco_kwargs=dict(type="coreweave", config=_coreweave_config),
         )
-
-        for step_name, step in mutable_flow.steps:
-            _add_secrets(step)
+        self._swap_secrets(mutable_flow)