nextmv 0.39.0.dev1__py3-none-any.whl → 1.0.0__py3-none-any.whl

nextmv/cloud/application/_secrets.py

@@ -0,0 +1,294 @@
+"""
+Application mixin for managing app secrets.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from nextmv.cloud.secrets import Secret, SecretsCollection, SecretsCollectionSummary
+from nextmv.safe import safe_id
+
+if TYPE_CHECKING:
+    from . import Application
+
+
+class ApplicationSecretsMixin:
+    """
+    Mixin class for managing app secrets within an application.
+    """
+
+    def delete_secrets_collection(self: "Application", secrets_collection_id: str) -> None:
+        """
+        Delete a secrets collection.
+
+        Parameters
+        ----------
+        secrets_collection_id : str
+            ID of the secrets collection to delete.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> app.delete_secrets_collection("secrets-123")
+        """
+
+        _ = self.client.request(
+            method="DELETE",
+            endpoint=f"{self.endpoint}/secrets/{secrets_collection_id}",
+        )
+
+    def list_secrets_collections(self: "Application") -> list[SecretsCollectionSummary]:
+        """
+        List all secrets collections.
+
+        Returns
+        -------
+        list[SecretsCollectionSummary]
+            List of all secrets collections associated with this application.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> collections = app.list_secrets_collections()
+        >>> for collection in collections:
+        ...     print(collection.name)
+        'API Keys'
+        'Database Credentials'
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.endpoint}/secrets",
+        )
+
+        return [SecretsCollectionSummary.from_dict(secrets) for secrets in response.json()["items"]]
+
+    def new_secrets_collection(
+        self: "Application",
+        secrets: list[Secret],
+        id: str | None = None,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> SecretsCollectionSummary:
+        """
+        Create a new secrets collection.
+
+        This method creates a new secrets collection with the provided secrets.
+        A secrets collection is a group of key-value pairs that can be used by
+        your application instances during execution. If no secrets are
+        provided, a ValueError is raised. If the `id` or `name` parameters are
+        not provided, they will be generated based on a unique ID.
+
+        Parameters
+        ----------
+        secrets : list[Secret]
+            List of secrets to use for the secrets collection. Each secret
+            should be an instance of the Secret class containing a key and
+            value.
+        id : str | None, default=None
+            ID of the secrets collection. If not provided, a unique ID will be
+            generated.
+        name : str | None, default=None
+            Name of the secrets collection. If not provided, the ID will be
+            used.
+        description : Optional[str], default=None
+            Description of the secrets collection.
+
+        Returns
+        -------
+        SecretsCollectionSummary
+            Summary of the secrets collection including its metadata.
+
+        Raises
+        ------
+        ValueError
+            If no secrets are provided.
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> # Create a new secrets collection with API keys
+        >>> from nextmv.cloud import Secret
+        >>> secrets = [
+        ...     Secret(
+        ...          location="API_KEY",
+        ...          value="your-api-key",
+        ...          secret_type=SecretType.ENV,
+        ...     ),
+        ...     Secret(
+        ...          location="DATABASE_URL",
+        ...          value="your-database-url",
+        ...          secret_type=SecretType.ENV,
+        ...     ),
+        ... ]
+        >>> collection = app.new_secrets_collection(
+        ...     secrets=secrets,
+        ...     id="api-secrets",
+        ...     name="API Secrets",
+        ...     description="Collection of API secrets for external services"
+        ... )
+        >>> print(collection.id)
+        'api-secrets'
+        """
+
+        if len(secrets) == 0:
+            raise ValueError("secrets must be provided")
+
+        if id is None or id == "":
+            id = safe_id(prefix="secrets")
+        if name is None or name == "":
+            name = id
+
+        payload = {
+            "id": id,
+            "name": name,
+            "secrets": [secret.to_dict() for secret in secrets],
+        }
+
+        if description is not None:
+            payload["description"] = description
+
+        response = self.client.request(
+            method="POST",
+            endpoint=f"{self.endpoint}/secrets",
+            payload=payload,
+        )
+
+        return SecretsCollectionSummary.from_dict(response.json())
+
+    def secrets_collection(self: "Application", secrets_collection_id: str) -> SecretsCollection:
+        """
+        Get a secrets collection.
+
+        This method retrieves a secrets collection by its ID. A secrets collection
+        is a group of key-value pairs that can be used by your application
+        instances during execution.
+
+        Parameters
+        ----------
+        secrets_collection_id : str
+            ID of the secrets collection to retrieve.
+
+        Returns
+        -------
+        SecretsCollection
+            The requested secrets collection, including all secret values
+            and metadata.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> # Retrieve a secrets collection
+        >>> collection = app.secrets_collection("api-secrets")
+        >>> print(collection.name)
+        'API Secrets'
+        >>> print(len(collection.secrets))
+        2
+        >>> for secret in collection.secrets:
+        ...     print(secret.location)
+        'API_KEY'
+        'DATABASE_URL'
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.endpoint}/secrets/{secrets_collection_id}",
+        )
+
+        return SecretsCollection.from_dict(response.json())
+
+    def update_secrets_collection(
+        self: "Application",
+        secrets_collection_id: str,
+        name: str | None = None,
+        description: str | None = None,
+        secrets: list[Secret | dict[str, Any]] | None = None,
+    ) -> SecretsCollectionSummary:
+        """
+        Update a secrets collection.
+
+        This method updates an existing secrets collection with new values for name,
+        description, and secrets. A secrets collection is a group of key-value pairs
+        that can be used by your application instances during execution.
+
+        Parameters
+        ----------
+        secrets_collection_id : str
+            ID of the secrets collection to update.
+        name : Optional[str], default=None
+            Optional new name for the secrets collection.
+        description : Optional[str], default=None
+            Optional new description for the secrets collection.
+        secrets : Optional[list[Secret | dict[str, Any]]], default=None
+            Optional list of secrets to update. Each secret should be an
+            instance of the Secret class containing a key and value.
+
+        Returns
+        -------
+        SecretsCollectionSummary
+            Summary of the updated secrets collection including its metadata.
+
+        Raises
+        ------
+        ValueError
+            If no secrets are provided.
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> # Update an existing secrets collection
+        >>> from nextmv.cloud import Secret
+        >>> updated_secrets = [
+        ...     Secret(key="API_KEY", value="new-api-key"),
+        ...     Secret(key="DATABASE_URL", value="new-database-url")
+        ... ]
+        >>> updated_collection = app.update_secrets_collection(
+        ...     secrets_collection_id="api-secrets",
+        ...     name="Updated API Secrets",
+        ...     description="Updated collection of API secrets",
+        ...     secrets=updated_secrets
+        ... )
+        >>> print(updated_collection.id)
+        'api-secrets'
+        """
+
+        collection = self.secrets_collection(secrets_collection_id)
+        collection_dict = collection.to_dict()
+        payload = collection_dict.copy()
+
+        if name is not None:
+            payload["name"] = name
+        if description is not None:
+            payload["description"] = description
+        if secrets is not None and len(secrets) > 0:
+            secrets_dicts = []
+            for ix, secret in enumerate(secrets):
+                if isinstance(secret, dict):
+                    secrets_dicts.append(secret)
+                elif isinstance(secret, Secret):
+                    secrets_dicts.append(secret.to_dict())
+                else:
+                    raise ValueError(f"secret at index {ix} must be either a Secret or dict object")
+
+            payload["secrets"] = secrets_dicts
+
+        response = self.client.request(
+            method="PUT",
+            endpoint=f"{self.endpoint}/secrets/{secrets_collection_id}",
+            payload=payload,
+        )
+
+        return SecretsCollectionSummary.from_dict(response.json())

nextmv/cloud/application/_shadow.py

@@ -0,0 +1,320 @@
+"""
+Application mixin for managing shadow tests.
+"""
+
+from typing import TYPE_CHECKING
+
+from nextmv.cloud.shadow import ShadowTest, ShadowTestMetadata, StartEvents, StopIntent, TerminationEvents
+from nextmv.run import Run
+from nextmv.safe import safe_id
+
+if TYPE_CHECKING:
+    from . import Application
+
+
+class ApplicationShadowMixin:
+    """
+    Mixin class for managing shadow tests within an application.
+    """
+
+    def shadow_test(self: "Application", shadow_test_id: str) -> ShadowTest:
+        """
+        Get a shadow test. This method also returns the runs of the shadow
+        test under the `.runs` attribute.
+
+        Parameters
+        ----------
+        shadow_test_id : str
+            ID of the shadow test.
+
+        Returns
+        -------
+        ShadowTest
+            The requested shadow test details.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> shadow_test = app.shadow_test("shadow-123")
+        >>> print(shadow_test.name)
+        'My Shadow Test'
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.experiments_endpoint}/shadow/{shadow_test_id}",
+        )
+
+        exp = ShadowTest.from_dict(response.json())
+
+        runs_response = self.client.request(
+            method="GET",
+            endpoint=f"{self.experiments_endpoint}/shadow/{shadow_test_id}/runs",
+        )
+
+        runs = [Run.from_dict(run) for run in runs_response.json().get("runs", [])]
+        exp.runs = runs
+
+        return exp
+
+    def shadow_test_metadata(self: "Application", shadow_test_id: str) -> ShadowTestMetadata:
+        """
+        Get metadata for a shadow test.
+
+        Parameters
+        ----------
+        shadow_test_id : str
+            ID of the shadow test.
+
+        Returns
+        -------
+        ShadowTestMetadata
+            The requested shadow test metadata.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> metadata = app.shadow_test_metadata("shadow-123")
+        >>> print(metadata.name)
+        'My Shadow Test'
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.experiments_endpoint}/shadow/{shadow_test_id}/metadata",
+        )
+
+        return ShadowTestMetadata.from_dict(response.json())
+
+    def delete_shadow_test(self: "Application", shadow_test_id: str) -> None:
+        """
+        Delete a shadow test.
+
+        Deletes a shadow test along with all the associated information,
+        such as its runs.
+
+        Parameters
+        ----------
+        shadow_test_id : str
+            ID of the shadow test to delete.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> app.delete_shadow_test("shadow-123")
+        """
+
+        _ = self.client.request(
+            method="DELETE",
+            endpoint=f"{self.experiments_endpoint}/shadow/{shadow_test_id}",
+        )
+
+    def list_shadow_tests(self: "Application") -> list[ShadowTest]:
+        """
+        List all shadow tests.
+
+        Returns
+        -------
+        list[ShadowTest]
+            List of shadow tests.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.experiments_endpoint}/shadow",
+        )
+
+        return [ShadowTest.from_dict(shadow_test) for shadow_test in response.json()]
+
+    def new_shadow_test(
+        self: "Application",
+        comparisons: dict[str, list[str]],
+        termination_events: TerminationEvents,
+        shadow_test_id: str | None = None,
+        name: str | None = None,
+        description: str | None = None,
+        start_events: StartEvents | None = None,
+    ) -> ShadowTest:
+        """
+        Create a new shadow test in draft mode. Shadow tests are experiments
+        that run instances in parallel to compare their results.
+
+        Use the `comparisons` parameter to define how to set up instance
+        comparisons. The keys of the `comparisons` dictionary are the baseline
+        instance IDs, and the values are the candidate lists of instance IDs to
+        compare against the respective baseline.
+
+        You may specify `start_events` to make the shadow test start at a
+        specific time. Alternatively, you may use the `start_shadow_test`
+        method to start the test.
+
+        The `termination_events` parameter is required and provides control
+        over when the shadow test should terminate. Alternatively, you may use
+        the `stop_shadow_test` method to stop the test.
+
+        Parameters
+        ----------
+        comparisons : dict[str, list[str]]
+            Dictionary defining the baseline and candidate instance IDs for
+            comparison. The keys are baseline instance IDs, and the values are
+            lists of candidate instance IDs to compare against the respective
+            baseline.
+        termination_events : TerminationEvents
+            Termination events for the shadow test.
+        shadow_test_id : Optional[str]
+            ID of the shadow test. Will be generated if not provided.
+        name : Optional[str]
+            Name of the shadow test. If not provided, the ID will be used as
+            the name.
+        description : Optional[str]
+            Optional description of the shadow test.
+        start_events : Optional[StartEvents]
+            Start events for the shadow test.
+
+        Returns
+        -------
+        ShadowTest
+            The created shadow test.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        # Generate ID if not provided
+        if shadow_test_id is None:
+            shadow_test_id = safe_id("shadow")
+
+        # Use ID as name if name not provided
+        if name is None or name == "":
+            name = shadow_test_id
+
+        payload = {
+            "id": shadow_test_id,
+            "name": name,
+            "comparisons": comparisons,
+            "termination_events": termination_events.to_dict(),
+        }
+
+        if description is not None:
+            payload["description"] = description
+        if start_events is not None:
+            payload["start_events"] = start_events.to_dict()
+
+        response = self.client.request(
+            method="POST",
+            endpoint=f"{self.experiments_endpoint}/shadow",
+            payload=payload,
+        )
+
+        return ShadowTest.from_dict(response.json())
+
+    def start_shadow_test(self: "Application", shadow_test_id: str) -> None:
+        """
+        Start a shadow test. Create a shadow test in draft mode using the
+        `new_shadow_test` method, then use this method to start the test.
+
+        Parameters
+        ----------
+        shadow_test_id : str
+            ID of the shadow test to start.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        _ = self.client.request(
+            method="PUT",
+            endpoint=f"{self.experiments_endpoint}/shadow/{shadow_test_id}/start",
+        )
+
+    def stop_shadow_test(self: "Application", shadow_test_id: str, intent: StopIntent) -> None:
+        """
+        Stop a shadow test. The test should already have started before using
+        this method.
+
+        Parameters
+        ----------
+        shadow_test_id : str
+            ID of the shadow test to stop.
+        intent : StopIntent
+            Intent for stopping the shadow test.
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        payload = {
+            "intent": intent.value,
+        }
+
+        _ = self.client.request(
+            method="PUT",
+            endpoint=f"{self.experiments_endpoint}/shadow/{shadow_test_id}/stop",
+            payload=payload,
+        )
+
+    def update_shadow_test(
+        self: "Application",
+        shadow_test_id: str,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> ShadowTest:
+        """
+        Update a shadow test.
+
+        Parameters
+        ----------
+        shadow_test_id : str
+            ID of the shadow test to update.
+        name : Optional[str], default=None
+            Optional name of the shadow test.
+        description : Optional[str], default=None
+            Optional description of the shadow test.
+
+        Returns
+        -------
+        ShadowTest
+            The information with the updated shadow test.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        payload = {}
+
+        if name is not None:
+            payload["name"] = name
+        if description is not None:
+            payload["description"] = description
+
+        response = self.client.request(
+            method="PATCH",
+            endpoint=f"{self.experiments_endpoint}/shadow/{shadow_test_id}",
+            payload=payload,
+        )
+
+        return ShadowTest.from_dict(response.json())