Add client CLI for promote (#51577)

GitOrigin-RevId: e8d379d95bf2b726b1bdd017371a609eafcee3b0

Author: thomasjpfan

py/modal/cli/app.py

@@ -351,6 +351,57 @@ async def logs(
             )
 
 
+@app_cli.command("promote", no_args_is_help=True, hidden=True)
+@click.argument("app_identifier")
+@click.argument("version")
+@env_option
+@synchronizer.create_blocking
+async def promote(
+    app_identifier: str,
+    version: str,
+    *,
+    env: str | None = None,
+):
+    """Deploy a staged version from an App's deployment history.
+
+    When a staged version gets promoted, the app is deployed with a new version that
+    refers back to the staged version.
+
+    Examples:
+
+    Promote an App to a specific version:
+
+    ```
+    modal app promote my-app v5
+    ```
+
+    Promote an App using its App ID instead of its name:
+
+    ```
+    modal app promote ap-abcdefghABCDEFGH123456 v5
+    ```
+
+    """
+    if m := re.fullmatch(r"v?([1-9]\d*)", version):
+        version_number = int(m.group(1))
+    else:
+        raise UsageError(f"Invalid version specifier: {version}. Expected a positive version number, e.g. 'v5' or '5'.")
+
+    env = ensure_env(env)
+    client = await _Client.from_env()
+    app_id, environment_name, lifecycle = await resolve_app_identifier(app_identifier, env, client)
+    if lifecycle.app_state != api_pb2.APP_STATE_DEPLOYED:
+        env_suffix = f" in the '{environment_name}' environment" if environment_name else ""
+        raise InvalidError(f"App '{app_identifier}' is not deployed{env_suffix}.")
+
+    resp = await client.stub.AppPromote(api_pb2.AppPromoteRequest(app_id=app_id, version=version_number))
+    print_server_warnings(resp.server_warnings)
+
+    output_mgr = OutputManager.get()
+    output_mgr.print(f"[green]✓[/green] Promoted App to v{version_number}!")
+    output_mgr.print(f"\nView Deployment: [magenta]{resp.url}[/magenta]")
+
+
 @app_cli.command("rollback", no_args_is_help=True, context_settings={"ignore_unknown_options": True})
 @click.argument("app_identifier")
 @click.argument("version", default="")

py/test/cli_test.py

@@ -2496,6 +2496,107 @@ def test_app_rollback(servicer, mock_dir, set_env_client):
     run_cli_command(["app", "rollback", "my_app", "2"], expected_exit_code=2)
 
 
+def _record_future_deployment(servicer, app_id: str, version: int) -> None:
+    """Add a deployment to an App's history that is newer than the currently deployed version."""
+    latest = servicer.app_deployment_history[app_id][-1]
+    servicer.app_deployment_history[app_id].append({**latest, "version": version, "tag": f"deploy{version}"})
+
+
+def test_app_rollback_relative_to_live_version(servicer, mock_dir, set_env_client):
+    with mock_dir({"myapp.py": dummy_app_file, "other_module.py": dummy_other_module_file}):
+        for _ in range(3):
+            run_cli_command(["deploy", "myapp.py", "--name", "my_app"])
+    app_id = servicer.deployed_apps[("main", "my_app")]
+    _record_future_deployment(servicer, app_id, version=5)
+
+    # Relative versions resolve against the live version (v3), not the newest staged row (v5),
+    # but the new deployment still lands above everything in history.
+    run_cli_command(["app", "rollback", "my_app"])
+    assert servicer.app_deployment_history[app_id][-1]["rollback_version"] == 2
+    assert servicer.app_deployment_history[app_id][-1]["version"] == 6
+
+
+@pytest.mark.parametrize("version", ["v5", "5"])
+def test_app_promote(servicer, mock_dir, set_env_client, version):
+    with mock_dir({"myapp.py": dummy_app_file, "other_module.py": dummy_other_module_file}):
+        run_cli_command(["deploy", "myapp.py", "--name", "my_app"])
+    app_id = servicer.deployed_apps[("main", "my_app")]
+    _record_future_deployment(servicer, app_id, version=5)
+
+    with servicer.intercept() as ctx:
+        res = run_cli_command(["app", "promote", "my_app", version])
+
+    (request,) = ctx.get_requests("AppPromote")
+    assert request.app_id == app_id
+    assert request.version == 5
+
+    assert "Promoted App to v5" in res.stdout
+    assert "http://test.modal.com/foo/bar" in res.stdout
+
+    # The promotion is recorded as a new deployment above every version in history
+    assert servicer.app_deployment_history[app_id][-1]["version"] == 6
+    assert servicer.app_deployment_history[app_id][-1]["rollback_version"] == 5
+
+
+@pytest.mark.parametrize("version", ["v0", "0", "v", "latest", "-1", "v5.1", "5x"])
+def test_app_promote_invalid_version(servicer, mock_dir, set_env_client, version):
+    with mock_dir({"myapp.py": dummy_app_file, "other_module.py": dummy_other_module_file}):
+        run_cli_command(["deploy", "myapp.py", "--name", "my_app"])
+
+    with servicer.intercept() as ctx:
+        run_cli_command(["app", "promote", "my_app", version], expected_exit_code=2)
+
+    # Version specifiers are validated before we hit the server
+    assert not ctx.get_requests("AppPromote")
+
+
+def test_app_promote_requires_version(servicer, mock_dir, set_env_client):
+    with mock_dir({"myapp.py": dummy_app_file, "other_module.py": dummy_other_module_file}):
+        run_cli_command(["deploy", "myapp.py", "--name", "my_app"])
+
+    run_cli_command(["app", "promote", "my_app"], expected_exit_code=2)
+
+
+def test_app_promote_not_deployed(servicer, mock_dir, set_env_client):
+    with mock_dir({"myapp.py": dummy_app_file, "other_module.py": dummy_other_module_file}):
+        run_cli_command(["deploy", "myapp.py", "--name", "my_app"])
+    app_id = servicer.deployed_apps[("main", "my_app")]
+    _record_future_deployment(servicer, app_id, version=5)
+    servicer.app_state_history[app_id].append(api_pb2.APP_STATE_STOPPED)
+
+    with servicer.intercept() as ctx:
+        run_cli_command(
+            ["app", "promote", "my_app", "v5"], expected_exit_code=1, expected_error="App .* is not deployed"
+        )
+
+    assert not ctx.get_requests("AppPromote")
+
+
+def test_app_promote_version_not_newer(servicer, mock_dir, set_env_client):
+    with mock_dir({"myapp.py": dummy_app_file, "other_module.py": dummy_other_module_file}):
+        for _ in range(2):
+            run_cli_command(["deploy", "myapp.py", "--name", "my_app"])
+
+    # v1 and v2 exist in the App history, but the App already serves v2
+    for version in ["v1", "v2"]:
+        run_cli_command(
+            ["app", "promote", "my_app", version],
+            expected_exit_code=1,
+            expected_error="must be newer than the current App version",
+        )
+
+
+def test_app_promote_version_not_in_history(servicer, mock_dir, set_env_client):
+    with mock_dir({"myapp.py": dummy_app_file, "other_module.py": dummy_other_module_file}):
+        run_cli_command(["deploy", "myapp.py", "--name", "my_app"])
+
+    run_cli_command(
+        ["app", "promote", "my_app", "v100"],
+        expected_exit_code=1,
+        expected_error="not found in App history",
+    )
+
+
 def test_dict_create_list_delete(servicer, server_url_env, set_env_client):
     run_cli_command(["dict", "create", "foo-dict"])
     run_cli_command(["dict", "create", "bar-dict"])
@@ -3246,6 +3347,8 @@ async def task_list(servicer, stream):
         ctx.set_responder("TaskList", task_list)
 
         with mock_dir({"myapp.py": dummy_app_file, "other_module.py": dummy_other_module_file}):
+            # Deploy twice so that there is an earlier version for `rollback` to target
+            run_cli_command(["deploy", "myapp.py"])
             run_cli_command(["deploy", "myapp.py"])
 
         res = run_cli_command(["app", cmd, "my_app", "--strategy", "recreate"])
@@ -3259,6 +3362,8 @@ async def task_list(servicer, stream):
 @pytest.mark.parametrize("cmd", ["rollover", "rollback"])
 def test_rolling_strategy(cmd, servicer, mock_dir, set_env_client):
     with mock_dir({"myapp.py": dummy_app_file, "other_module.py": dummy_other_module_file}):
+        # Deploy twice so that there is an earlier version for `rollback` to target
+        run_cli_command(["deploy", "myapp.py"])
         run_cli_command(["deploy", "myapp.py"])
 
     res = run_cli_command(["app", cmd, "my_app"])

py/test/conftest.py

@@ -747,6 +747,9 @@ def __init__(self, blob_host, blobs, blocks, files_sha2data, credentials):
         self.deployed_apps: dict[tuple[str, str], str] = {}
         self.app_environments: dict[str, str] = {}
         self.app_deployment_history: defaultdict[str, list[dict[str, Any]]] = defaultdict(list)
+        # The currently live version of each App, which can lag behind the newest version in the
+        # deployment history (e.g. after a rollback, or when a newer version has not been promoted).
+        self.app_live_version: dict[str, int] = {}
         self.app_deployment_history["ap-x"] = [
             {
                 "app_id": "ap-x",
@@ -1234,23 +1237,81 @@ async def AppGetLogs(self, stream):
         await stream.send_message(api_pb2.TaskLogsBatch(entry_id=last_entry_id, items=[log]))
         await stream.send_message(api_pb2.TaskLogsBatch(app_done=True))
 
+    def _max_history_version(self, app_id: str) -> int:
+        return max((h["version"] for h in self.app_deployment_history[app_id]), default=0)
+
+    async def AppPromote(self, stream):
+        request: api_pb2.AppPromoteRequest = await stream.recv_message()
+        history = self.app_deployment_history[request.app_id]
+        current_version = self.app_live_version.get(request.app_id, self._max_history_version(request.app_id))
+
+        if request.version <= 0:
+            raise GRPCError(Status.INVALID_ARGUMENT, "Invalid promote version request.")
+        if request.version <= current_version:
+            raise GRPCError(
+                Status.INVALID_ARGUMENT,
+                f"Promote version must be newer than the current App version ({current_version}).",
+            )
+
+        promote_history = next((h for h in history if h["version"] == request.version), None)
+        if promote_history is None:
+            raise GRPCError(Status.NOT_FOUND, "Promote version not found in App history.")
+
+        # Mirrors the server: the new version clears every row in history, not just the live one,
+        # so promoting the immediately-next version does not reuse its version number.
+        new_version = max(current_version, self._max_history_version(request.app_id)) + 1
+        deployed_at = datetime.datetime.now().timestamp()
+        self.app_deployment_history[request.app_id].append(
+            {
+                "app_id": request.app_id,
+                "deployed_at": deployed_at,
+                "version": new_version,
+                "client_version": promote_history["client_version"],
+                "deployed_by": "foo-user",
+                "tag": promote_history["tag"],
+                "rollback_version": request.version,
+                "definition_ids": promote_history["definition_ids"],
+                "function_ids": promote_history["function_ids"],
+                "commit_info": promote_history.get("commit_info", None),
+            }
+        )
+        self.app_live_version[request.app_id] = new_version
+        self.app_objects[request.app_id] = dict(promote_history["function_ids"])
+        self.app_state_history[request.app_id].append(api_pb2.APP_STATE_DEPLOYED)
+        response = api_pb2.AppPromoteResponse(
+            url="http://test.modal.com/foo/bar",
+            server_warnings=[],
+            deployed_at=deployed_at,
+        )
+        await stream.send_message(response)
+
     async def AppRollback(self, stream):
         request: api_pb2.AppRollbackRequest = await stream.recv_message()
-        history = self.app_deployment_history[request.app_id][-1]
-        current_version = history["version"]
+        history = self.app_deployment_history[request.app_id]
+        # Mirrors the server: relative versions resolve against the App's live version, which can trail
+        # staged rows in history.
+        current_version = self.app_live_version.get(request.app_id, self._max_history_version(request.app_id))
         if request.version < 0:
             rollback_version = current_version + request.version
-        else:
+            if rollback_version <= 0:
+                raise GRPCError(Status.INVALID_ARGUMENT, "Rollback request exceeds number of App deployments.")
+        elif request.version > 0:
             rollback_version = request.version
+        else:
+            raise GRPCError(Status.INVALID_ARGUMENT, "Invalid rollback version request.")
 
-        rollback_history = self.app_deployment_history[request.app_id][rollback_version - 1]
+        rollback_history = next((h for h in history if h["version"] == rollback_version), None)
+        if rollback_history is None:
+            raise GRPCError(Status.NOT_FOUND, "Rollback version not found in App history.")
         rollback_client = rollback_history["client_version"]
+        # Mirrors the server: the new version sits above every row in history, not just the live one.
+        new_version = max(current_version, self._max_history_version(request.app_id)) + 1
         deployed_at = datetime.datetime.now().timestamp()
         self.app_deployment_history[request.app_id].append(
             {
                 "app_id": request.app_id,
                 "deployed_at": deployed_at,
-                "version": current_version + 1,
+                "version": new_version,
                 "client_version": rollback_client,
                 "deployed_by": "foo-user",
                 "tag": "latest",
@@ -1260,6 +1321,7 @@ async def AppRollback(self, stream):
                 "commit_info": rollback_history.get("commit_info", None),
             }
         )
+        self.app_live_version[request.app_id] = new_version
 
         self.app_state_history[request.app_id].append(api_pb2.APP_STATE_DEPLOYED)
         response = api_pb2.AppRollbackResponse(
@@ -1333,10 +1395,7 @@ async def _app_publish(self, request: api_pb2.AppPublishRequest):
 
         self.app_objects[request.app_id] = {**request.function_ids, **request.class_ids}
         self.app_state_history[request.app_id].append(request.app_state)
-        if current_history := self.app_deployment_history[request.app_id]:
-            current_version = current_history[-1]["version"]
-        else:
-            current_version = 0
+        current_version = self._max_history_version(request.app_id)
 
         self.app_deployment_history[request.app_id].append(
             {
@@ -1352,6 +1411,7 @@ async def _app_publish(self, request: api_pb2.AppPublishRequest):
                 "function_ids": dict(request.function_ids),
             }
         )
+        self.app_live_version[request.app_id] = current_version + 1
         return response
 
     async def AppGetByDeploymentName(self, stream):