outerbounds 0.3.174__py3-none-any.whl → 0.3.175rc0__py3-none-any.whl

outerbounds/apps/app_config.py

@@ -0,0 +1,293 @@
+import json
+import os
+from outerbounds._vendor import yaml
+from typing import Dict, Any
+from .cli_to_config import build_config_from_options
+
+CODE_PACKAGE_PREFIX = "mf.obp-apps"
+
+CAPSULE_DEBUG = os.environ.get("OUTERBOUNDS_CAPSULE_DEBUG", False)
+
+
+class classproperty(property):
+    def __get__(self, owner_self, owner_cls):
+        return self.fget(owner_cls)
+
+
+class AppConfigError(Exception):
+    """Exception raised when app configuration is invalid."""
+
+    pass
+
+
+class AuthType:
+    BROWSER = "Browser"
+    API = "API"
+
+    @classmethod
+    def enums(cls):
+        return [cls.BROWSER, cls.API]
+
+    @classproperty
+    def default(cls):
+        return cls.BROWSER
+
+
+class AppConfig:
+    """Class representing an Outerbounds App configuration."""
+
+    def __init__(self, config_dict: Dict[str, Any]):
+        """Initialize configuration from a dictionary."""
+        self.config = config_dict or {}
+        self.schema = self._load_schema()
+        self._final_state = {}
+
+    def set_state(self, key, value):
+        self._final_state[key] = value
+        return self
+
+    def get_state(self, key, default=None):
+        return self._final_state.get(key, self.config.get(key, default))
+
+    def dump_state(self):
+        x = {k: v for k, v in self.config.items()}
+        for k, v in self._final_state.items():
+            x[k] = v
+        return x
+
+    @staticmethod
+    def _load_schema():
+        """Load the configuration schema from the YAML file."""
+        schema_path = os.path.join(os.path.dirname(__file__), "config_schema.yaml")
+        with open(schema_path, "r") as f:
+            return yaml.safe_load(f)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a configuration value by key."""
+        return self.config.get(key, default)
+
+    def validate(self) -> None:
+        """Validate the configuration against the schema."""
+        self._validate_required_fields()
+        self._validate_field_types()
+        self._validate_field_constraints()
+
+    def set_deploy_defaults(self, packaging_directory: str) -> None:
+        """Set default values for fields that are not provided."""
+        if not self.config.get("auth"):
+            self.config["auth"] = {}
+        if not self.config["auth"].get("public"):
+            self.config["auth"]["public"] = True
+        if not self.config["auth"].get("type"):
+            self.config["auth"]["type"] = AuthType.BROWSER
+
+        if not self.config.get("health_check"):
+            self.config["health_check"] = {}
+        if not self.config["health_check"].get("enabled"):
+            self.config["health_check"]["enabled"] = False
+
+        if not self.config.get("resources"):
+            self.config["resources"] = {}
+        if not self.config["resources"].get("cpu"):
+            self.config["resources"]["cpu"] = 1
+        if not self.config["resources"].get("memory"):
+            self.config["resources"]["memory"] = "4096Mi"
+        if not self.config["resources"].get("disk"):
+            self.config["resources"]["disk"] = "20Gi"
+
+        if not self.config.get("replicas", None):
+            self.config["replicas"] = {
+                "min": 1,
+                "max": 1,
+            }
+        else:
+            max_is_set = self.config["replicas"].get("max", None) is not None
+            min_is_set = self.config["replicas"].get("min", None) is not None
+            if max_is_set and not min_is_set:
+                # If users want to set 0 replicas for min,
+                # then they need explicitly specify min to 0
+                self.config["replicas"]["min"] = 1  # Atleast set 1 replica
+            if min_is_set and not max_is_set:
+                # In the situations where we dont have min/max replicas, we can
+                # set max to min.
+                self.config["replicas"]["max"] = self.config["replicas"].get("min")
+
+    def _validate_required_fields(self) -> None:
+        """Validate that all required fields are present."""
+        required_fields = self.schema.get("required", [])
+        for field in required_fields:
+            if field not in self.config:
+                raise AppConfigError(
+                    f"Required field '{field}' is missing from the configuration."
+                )
+
+    def _validate_field_types(self) -> None:
+        """Validate that fields have correct types."""
+        properties = self.schema.get("properties", {})
+
+        for field, value in self.config.items():
+            if field not in properties:
+                raise AppConfigError(f"Unknown field '{field}' in configuration.")
+
+            field_schema = properties[field]
+            field_type = field_schema.get("type")
+
+            if field_type == "string" and not isinstance(value, str):
+                raise AppConfigError(f"Field '{field}' must be a string.")
+
+            elif field_type == "integer" and not isinstance(value, int):
+                raise AppConfigError(f"Field '{field}' must be an integer.")
+
+            elif field_type == "boolean" and not isinstance(value, bool):
+                raise AppConfigError(f"Field '{field}' must be a boolean.")
+
+            elif field_type == "array" and not isinstance(value, list):
+                raise AppConfigError(f"Field '{field}' must be an array.")
+
+            elif field_type == "object" and not isinstance(value, dict):
+                raise AppConfigError(f"Field '{field}' must be an object.")
+
+    def _validate_field_constraints(self) -> None:
+        """Validate field-specific constraints."""
+        properties = self.schema.get("properties", {})
+
+        # Validate name
+        if "name" in self.config:
+            name = self.config["name"]
+            max_length = properties["name"].get("maxLength", 20)
+            if len(name) > max_length:
+                raise AppConfigError(
+                    f"App name '{name}' exceeds maximum length of {max_length} characters."
+                )
+
+        # Validate port
+        if "port" in self.config:
+            port = self.config["port"]
+            min_port = properties["port"].get("minimum", 1)
+            max_port = properties["port"].get("maximum", 65535)
+            if port < min_port or port > max_port:
+                raise AppConfigError(
+                    f"Port number {port} is outside valid range ({min_port}-{max_port})."
+                )
+
+        # Validate dependencies (only one type allowed)
+        if "dependencies" in self.config:
+            deps = self.config["dependencies"]
+            if not isinstance(deps, dict):
+                raise AppConfigError("Dependencies must be an object.")
+
+            valid_dep_types = [
+                "from_requirements_file",
+                "from_pyproject_toml",
+            ]
+
+            found_types = [dep_type for dep_type in valid_dep_types if dep_type in deps]
+
+            if len(found_types) > 1:
+                raise AppConfigError(
+                    f"You can only specify one mode of specifying dependencies. You have specified : {found_types} . Please only set one."
+                )
+
+        # Validate that each tag has exactly one key
+        if "tags" in self.config:
+            tags = self.config["tags"]
+            for tag in tags:
+                if not isinstance(tag, dict):
+                    raise AppConfigError(
+                        "Each tag must be a dictionary. %s is of type %s"
+                        % (str(tag), type(tag))
+                    )
+                if len(tag.keys()) != 1:
+                    raise AppConfigError(
+                        "Each tag must have exactly one key-value pair. Tag %s has %d key-value pairs."
+                        % (str(tag), len(tag.keys()))
+                    )
+        if "replicas" in self.config:
+            replicas = self.config["replicas"]
+            if not isinstance(replicas, dict):
+                raise AppConfigError("Replicas must be an object.")
+            max_is_set = self.config["replicas"].get("max", None) is not None
+            if max_is_set:
+                if replicas.get("max") == 0:
+                    raise AppConfigError("Max replicas must be greater than 0.")
+
+                if replicas.get("min", 1) > replicas.get("max"):
+                    raise AppConfigError(
+                        "Min replicas must be less than max replicas. %s > %s"
+                        % (replicas.get("min", 1), replicas.get("max", 1))
+                    )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the configuration as a dictionary."""
+        return self.config
+
+    def to_yaml(self) -> str:
+        """Return the configuration as a YAML string."""
+        return yaml.dump(self.config, default_flow_style=False)
+
+    def to_json(self) -> str:
+        """Return the configuration as a JSON string."""
+        return json.dumps(self.config, indent=2)
+
+    @classmethod
+    def from_file(cls, file_path: str) -> "AppConfig":
+        """Create a configuration from a file."""
+        if not os.path.exists(file_path):
+            raise AppConfigError(f"Configuration file '{file_path}' does not exist.")
+
+        with open(file_path, "r") as f:
+            try:
+                config_dict = yaml.safe_load(f)
+            except Exception as e:
+                raise AppConfigError(f"Failed to parse configuration file: {e}")
+
+        return cls(config_dict)
+
+    def update_from_cli_options(self, options):
+        """
+        Update configuration from CLI options using the same logic as build_config_from_options.
+        This ensures consistent handling of CLI options whether they come from a config file
+        or direct CLI input.
+        """
+        cli_config = build_config_from_options(options)
+
+        # Process each field using allow_union property
+        for key, value in cli_config.items():
+            if key in self.schema.get("properties", {}):
+                self._update_field(key, value)
+
+        return self
+
+    def _update_field(self, field_name, new_value):
+        """Update a field based on its allow_union property."""
+        properties = self.schema.get("properties", {})
+
+        # Skip if field doesn't exist in schema
+        if field_name not in properties:
+            return
+
+        field_schema = properties[field_name]
+        allow_union = field_schema.get("allow_union", False)
+
+        # If field doesn't exist in config, just set it
+        if field_name not in self.config:
+            self.config[field_name] = new_value
+            return
+
+        # If allow_union is True, merge values based on type
+        if allow_union:
+            current_value = self.config[field_name]
+
+            if isinstance(current_value, list) and isinstance(new_value, list):
+                # For lists, append new items
+                self.config[field_name].extend(new_value)
+            elif isinstance(current_value, dict) and isinstance(new_value, dict):
+                # For dicts, update with new values
+                self.config[field_name].update(new_value)
+            else:
+                # For other types, replace with new value
+                self.config[field_name] = new_value
+        else:
+            raise AppConfigError(
+                f"Field '{field_name}' does not allow union. Current value: {self.config[field_name]}, new value: {new_value}"
+            )

outerbounds/apps/capsule.py

@@ -0,0 +1,373 @@
+import json
+import os
+import pathlib
+import requests
+import time
+import shlex
+from typing import Optional
+from .utils import TODOException, safe_requests_wrapper
+from .app_config import AppConfig, CAPSULE_DEBUG, AuthType
+from . import experimental
+
+
+class CapsuleStateMachine:
+    """
+    Since capsules are a kinda newer concept, we will treat the state transitions based on the conditions and the
+    availability of certain fields in the status dictionary.
+    """
+
+    CONDITIONS = ["Ready", "DeploymentReplicasAvailable", "IngressObjectReady"]
+
+    def __init__(self, capsule_id: str):
+        self._capsule_id = capsule_id
+        self._status_trail = []
+
+    def is_completely_new_capsule(self):
+        # This is a heuristic. Not a fully tested.
+        # If we create a completely new capsule then the status
+        # field might be a completely empty dictionary.
+        assert (
+            len(self._status_trail) > 0
+        ), "status_trail cannot be none to infer if its a new capsule"
+        return self._empty_status(self._status_trail[0].get("status"))
+
+    def get_status_trail(self):
+        return self._status_trail
+
+    @staticmethod
+    def _empty_status(status):
+        if json.dumps(status) == "{}":
+            return True
+        return False
+
+    @staticmethod
+    def _parse_conditions(conditions):
+        curr_conditons = {}
+        for condition in conditions:
+            curr_conditons[condition["type"]] = condition["status"]
+        return curr_conditons
+
+    def add_status(self, status: dict):
+        assert type(status) == dict, "TODO: Make this check somewhere else"
+        self._status_trail.append({"timestamp": time.time(), "status": status})
+
+    @staticmethod
+    def _condition_change_emoji(previous_condition_status, current_condition_status):
+        if previous_condition_status == current_condition_status:
+            if previous_condition_status == "True":
+                return "✅"
+            else:
+                return "❌"
+        if previous_condition_status == "True" and current_condition_status == "False":
+            return "🔴 --> 🟢"
+        if previous_condition_status == "False" and current_condition_status == "True":
+            return "🚀"
+        return "🟡"
+
+    @property
+    def current_status(self):
+        return self._status_trail[-1].get("status")
+
+    @property
+    def out_of_cluster_url(self):
+        url = self.current_status.get("accessInfo", {}).get("outOfClusterURL", None)
+        if url is not None:
+            return f"https://{url}"
+        return None
+
+    @property
+    def in_cluster_url(self):
+        url = self.current_status.get("accessInfo", {}).get("inClusterURL", None)
+        if url is not None:
+            return f"https://{url}"
+        return None
+
+    @property
+    def ready_to_serve_traffic(self):
+        if self.current_status.get("readyToServeTraffic", False):
+            return any(
+                i is not None for i in [self.out_of_cluster_url, self.in_cluster_url]
+            )
+        return False
+
+    @property
+    def available_replicas(self):
+        return self.current_status.get("availableReplicas", 0)
+
+    def report_current_status(self, logger):
+        if len(self._status_trail) < 2:
+            return
+        previous_status, current_status = self._status_trail[-2].get(
+            "status"
+        ), self._status_trail[-1].get("status")
+        if self._empty_status(current_status):
+            return
+
+        if self._empty_status(previous_status):
+            logger("💊 %s Deployment has started ... 🚀" % self._capsule_id)
+            return
+
+    def check_for_debug(self, state_dir: str):
+        if CAPSULE_DEBUG:
+            debug_path = os.path.join(
+                state_dir, f"debug_capsule_{self._capsule_id}.json"
+            )
+            with open(debug_path, "w") as f:
+                json.dump(self._status_trail, f, indent=4)
+
+
+class CapsuleInput:
+    @classmethod
+    def construct_exec_command(cls, commands: list[str]):
+        commands = ["set -eEuo pipefail"] + commands
+        command_string = "\n".join(commands)
+        # First constuct a base64 encoded string of the quoted command
+        # One of the reasons we don't directly pass the command string to the backend with a `\n` join
+        # is because the backend controller doesnt play nice when the command can be a multi-line string.
+        # So we encode it to a base64 string and then decode it back to a command string at runtime to provide to
+        # `bash -c`. The ideal thing to have done is to run "bash -c {shlex.quote(command_string)}" and call it a day
+        # but the backend controller yields the following error:
+        # `error parsing template: error converting YAML to JSON: yaml: line 111: mapping values are not allowed in this context`
+        # So we go to great length to ensure the command is provided in base64 to avoid any issues with the backend controller.
+        import base64
+
+        encoded_command = base64.b64encode(command_string.encode()).decode()
+        decode_cmd = f"echo {encoded_command} | base64 -d > ./_ob_app_run.sh"
+        return (
+            f"bash -c '{decode_cmd} && cat ./_ob_app_run.sh && bash ./_ob_app_run.sh'"
+        )
+
+    @classmethod
+    def _marshal_environment_variables(cls, app_config: AppConfig):
+        envs = app_config.get_state("environment", {}).copy()
+        _return = []
+        for k, v in envs.items():
+            _v = v
+            if isinstance(v, dict):
+                _v = json.dumps(v)
+            elif isinstance(v, list):
+                _v = json.dumps(v)
+            else:
+                _v = str(v)
+            _return.append(
+                {
+                    "name": k,
+                    "value": _v,
+                }
+            )
+        return _return
+
+    @classmethod
+    def from_app_config(self, app_config: AppConfig):
+        gpu_resource = app_config.get_state("resources").get("gpu")
+        resources = {}
+        shared_memory = app_config.get_state("resources").get("shared_memory")
+        if gpu_resource:
+            resources["gpu"] = gpu_resource
+        if shared_memory:
+            resources["sharedMemory"] = shared_memory
+
+        _scheduling_config = {}
+        if app_config.get_state("compute_pools", None):
+            _scheduling_config["computePools"] = [
+                {"name": x} for x in app_config.get_state("compute_pools")
+            ]
+
+        return {
+            "perimeter": app_config.get_state("perimeter"),
+            # "environmentPath": "environments/python3.9",
+            "codePackagePath": app_config.get_state("code_package_url"),
+            "image": app_config.get_state("image"),
+            "resourceIntegrations": [
+                {"name": x} for x in app_config.get_state("secrets", [])
+            ],
+            "resourceConfig": {
+                "cpu": str(app_config.get_state("resources").get("cpu")),
+                "memory": str(app_config.get_state("resources").get("memory")),
+                "ephemeralStorage": str(app_config.get_state("resources").get("disk")),
+                **resources,
+            },
+            "autoscalingConfig": {
+                "minReplicas": app_config.get_state("replicas", {}).get("min", 1),
+                "maxReplicas": app_config.get_state("replicas", {}).get("max", 1),
+            },
+            **_scheduling_config,
+            "containerStartupConfig": {
+                "entrypoint": self.construct_exec_command(
+                    app_config.get_state("commands")
+                )
+            },
+            "environmentVariables": self._marshal_environment_variables(app_config),
+            # "assets": [{"name": "startup-script.sh"}],
+            "authConfig": {
+                "authType": app_config.get_state("auth").get("type"),
+                "publicToDeployment": app_config.get_state("auth").get("public"),
+            },
+            "tags": [
+                dict(key=k, value=v)
+                for tag in app_config.get_state("tags", [])
+                for k, v in tag.items()
+            ],
+            "port": app_config.get_state("port"),
+            "displayName": app_config.get_state("name"),
+        }
+
+
+def create_capsule(capsule_input: dict, api_url: str, request_headers: dict):
+    _data = json.dumps(capsule_input)
+    response = safe_requests_wrapper(
+        requests.post,
+        api_url,
+        data=_data,
+        headers=request_headers,
+        conn_error_retries=2,
+        retryable_status_codes=[409],  # todo : verify me
+    )
+
+    if response.status_code > 400:
+        raise TODOException(
+            f"Failed to create capsule: {response.status_code} {response.text}"
+        )
+    return response.json()
+
+
+def list_capsules(api_url: str, request_headers: dict):
+    response = safe_requests_wrapper(
+        requests.get,
+        api_url,
+        headers=request_headers,
+        retryable_status_codes=[409],  # todo : verify me
+        conn_error_retries=3,
+    )
+    if response.status_code > 400:
+        raise TODOException(
+            f"Failed to list capsules: {response.status_code} {response.text}"
+        )
+    return response.json()
+
+
+def get_capsule(capsule_id: str, api_url: str, request_headers: dict):
+    # params = {"instance_id": capsule_id}
+    url = os.path.join(api_url, capsule_id)
+    response = safe_requests_wrapper(
+        requests.get,
+        url,
+        headers=request_headers,
+        retryable_status_codes=[409, 404],  # todo : verify me
+        conn_error_retries=3,
+    )
+    if response.status_code > 400:
+        raise TODOException(
+            f"Failed to get capsule: {response.status_code} {response.text}"
+        )
+    return response.json()
+
+
+def delete_capsule(capsule_id: str, api_url: str, request_headers: dict):
+    response = safe_requests_wrapper(
+        requests.delete,
+        os.path.join(api_url, capsule_id),
+        headers=request_headers,
+        retryable_status_codes=[409],  # todo : verify me
+    )
+    if response.status_code > 400:
+        raise TODOException(
+            f"Failed to delete capsule: {response.status_code} {response.text}"
+        )
+
+    return response.json()
+
+
+class Capsule:
+
+    status: CapsuleStateMachine
+
+    identifier = None
+
+    # TODO: Current default timeout is very large of 5 minutes. Ideally we should have finished the deployed in less than 1 minutes.
+    def __init__(
+        self,
+        app_config: AppConfig,
+        base_url: str,
+        create_timeout: int = 60 * 5,
+        debug_dir: Optional[str] = None,
+    ):
+        self._app_config = app_config
+        self._base_url = os.path.join(
+            base_url,
+            "v1",
+            "perimeters",
+            app_config.get_state("perimeter"),
+            "capsules",
+        )
+        self._create_timeout = create_timeout
+        self._debug_dir = debug_dir
+        from metaflow.metaflow_config import SERVICE_HEADERS
+
+        self._request_headers = {
+            **{"Content-Type": "application/json", "Connection": "keep-alive"},
+            **(SERVICE_HEADERS or {}),
+        }
+
+    @property
+    def capsule_type(self):
+        auth_type = self._app_config.get_state("auth", {}).get("type", AuthType.default)
+        if auth_type == AuthType.BROWSER:
+            return "App"
+        elif auth_type == AuthType.API:
+            return "Endpoint"
+        else:
+            raise TODOException(f"Unknown auth type: {auth_type}")
+
+    @property
+    def name(self):
+        return self._app_config.get_state("name")
+
+    def create_input(self):
+        return experimental.capsule_input_overrides(
+            self._app_config, CapsuleInput.from_app_config(self._app_config)
+        )
+
+    def create(self):
+        capsule_response = create_capsule(
+            self.create_input(), self._base_url, self._request_headers
+        )
+        self.identifier = capsule_response.get("id")
+        return self.identifier
+
+    def get(self):
+        # TODO: [FIX ME]: This need to work in the reverse lookup way too.
+        return get_capsule(self.identifier, self._base_url, self._request_headers)
+
+    def wait_for_terminal_state(self, logger=print):
+        state_machine = CapsuleStateMachine(self.identifier)
+        logger(
+            "💊 Waiting for %s %s to be ready to serve traffic"
+            % (self.capsule_type.lower(), self.identifier)
+        )
+        for i in range(self._create_timeout):
+            capsule_response = self.get()
+            state_machine.add_status(capsule_response.get("status", {}))
+            time.sleep(1)
+            state_machine.report_current_status(logger)
+            if state_machine.ready_to_serve_traffic:
+                logger(
+                    "💊 %s %s is ready to serve traffic on the URL: %s"
+                    % (
+                        self.capsule_type,
+                        self.identifier,
+                        state_machine.out_of_cluster_url,
+                    ),
+                )
+                self.status = state_machine
+                break
+            if self._debug_dir:
+                state_machine.check_for_debug(self._debug_dir)
+
+        return capsule_response
+
+    def list(self):
+        return list_capsules(self._base_url, self._request_headers)
+
+    def delete(self):
+        return delete_capsule(self.identifier, self._base_url, self._request_headers)