agentcore-cli 0.31.1__py3-none-any.whl

agentcore/primitives/gateway.py

@@ -0,0 +1,496 @@
+"""Gateway add/remove (port of src/cli/primitives/GatewayPrimitive.ts).
+
+The project spec is handled as its camelCase JSON form and validated on write by ``ConfigIO``.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+import typer
+
+from agentcore.cli import interactive
+from agentcore.cli.constants import MAX_GATEWAY_NAME_LENGTH
+from agentcore.cli.errors import get_error_message
+from agentcore.cli.run_command import run_cli_command
+from agentcore.lib.errors.types import ResourceNotFoundError, ValidationError, to_error
+from agentcore.lib.result import Err, Ok, serialize_result
+from agentcore.lib.schemas.io.config_io import to_jsonable
+from agentcore.lib.schemas.io.path_resolver import find_config_root
+from agentcore.primitives._gateway_validation import validate_add_gateway_options
+from agentcore.primitives.auth_utils import (
+    JwtConfigOptions,
+    build_authorizer_config_from_jwt_config,
+    create_managed_oauth_credential,
+)
+from agentcore.primitives.base import BasePrimitive, RemovableResource, RemovalPreview, SchemaChange, emit_json
+from agentcore.primitives.credential_utils import compute_managed_oauth_credential_name
+from agentcore.schema import POLICY_ENGINE_MODES
+
+
+@dataclass
+class AddGatewayOptions:
+    name: str
+    authorizer_type: str = "NONE"
+    description: str | None = None
+    protocol_type: str | None = None
+    discovery_url: str | None = None
+    allowed_audience: str | None = None
+    allowed_clients: str | None = None
+    allowed_scopes: str | None = None
+    custom_claims: list[Any] | None = None
+    client_id: str | None = None
+    client_secret: str | None = None
+    runtimes: str | None = None
+    enable_semantic_search: bool | None = None
+    exception_level: str | None = None
+    policy_engine: str | None = None
+    policy_engine_mode: str | None = None
+
+
+@dataclass
+class AddGatewayConfig:
+    """Port of tui/screens/mcp/types.ts AddGatewayConfig."""
+
+    name: str
+    description: str
+    authorizer_type: str
+    protocol_type: str | None = None
+    jwt_config: JwtConfigOptions | None = None
+    selected_targets: list[str] = field(default_factory=list)
+    enable_semantic_search: bool = True
+    exception_level: str = "NONE"
+    policy_engine_configuration: dict[str, str] | None = None
+
+
+def _csv(value: str | None) -> list[str] | None:
+    return [s.strip() for s in value.split(",") if s.strip()] if value else None
+
+
+def _parse_policy_engine_mode(value: str) -> str:
+    if value not in POLICY_ENGINE_MODES:
+        expected = "|".join(f'"{v}"' for v in POLICY_ENGINE_MODES)
+        raise ValueError(f"Invalid option: expected one of {expected}")
+    return value
+
+
+def compute_default_gateway_env_var_name(gateway_name: str) -> str:
+    return f"AGENTCORE_GATEWAY_{gateway_name.upper().replace('-', '_')}_URL"
+
+
+def _mcp_fields(project: dict[str, Any]) -> dict[str, Any]:
+    """extractMcpSpec: the MCP-related fields of a project."""
+    spec = {"agentCoreGateways": project.get("agentCoreGateways", [])}
+    for key in ("mcpRuntimeTools", "unassignedTargets"):
+        if key in project:
+            spec[key] = project[key]
+    return spec
+
+
+class GatewayPrimitive(BasePrimitive):
+    kind = "gateway"
+    label = "Gateway"
+
+    compute_default_gateway_env_var_name = staticmethod(compute_default_gateway_env_var_name)
+
+    def _project(self) -> dict[str, Any]:
+        return to_jsonable(self.read_project_spec())
+
+    # --- add ----------------------------------------------------------------------------
+
+    def add(self, options: AddGatewayOptions) -> Ok[dict[str, Any]] | Err[Exception]:
+        try:
+            config = self._build_gateway_config(options)
+            return Ok({"gatewayName": self.create_gateway_from_wizard(config)})
+        except Exception as exc:  # noqa: BLE001
+            return Err(to_error(exc))
+
+    @staticmethod
+    def _build_gateway_config(options: AddGatewayOptions) -> AddGatewayConfig:
+        config = AddGatewayConfig(
+            name=options.name,
+            description=options.description if options.description is not None else f"Gateway for {options.name}",
+            protocol_type=options.protocol_type,
+            authorizer_type=options.authorizer_type,
+            enable_semantic_search=True if options.enable_semantic_search is None else options.enable_semantic_search,
+            exception_level="DEBUG" if options.exception_level == "DEBUG" else "NONE",
+            policy_engine_configuration=(
+                {
+                    "policyEngineName": options.policy_engine,
+                    "mode": _parse_policy_engine_mode(options.policy_engine_mode),
+                }
+                if options.policy_engine and options.policy_engine_mode
+                else None
+            ),
+        )
+        if options.authorizer_type == "CUSTOM_JWT" and options.discovery_url:
+            config.jwt_config = JwtConfigOptions(
+                discovery_url=options.discovery_url,
+                allowed_audience=_csv(options.allowed_audience) or None,
+                allowed_clients=_csv(options.allowed_clients) or None,
+                allowed_scopes=_csv(options.allowed_scopes) or None,
+                custom_claims=options.custom_claims or None,
+                client_id=options.client_id or None,
+                client_secret=options.client_secret or None,
+            )
+        return config
+
+    def create_gateway_from_wizard(self, config: AddGatewayConfig) -> str:
+        project = self._project()
+        gateways = project.setdefault("agentCoreGateways", [])
+        if any(g["name"] == config.name for g in gateways):
+            raise ValueError(f'Gateway "{config.name}" already exists.')
+
+        # AWS names the deployed gateway `${projectName}-${gatewayName}` and rejects long names at
+        # CreateGateway; fail now rather than mid-deploy.
+        combined = f"{project['name']}-{config.name}"
+        if len(combined) > MAX_GATEWAY_NAME_LENGTH:
+            raise ValidationError(
+                f'Gateway name too long: "{combined}" ({len(combined)} chars). '
+                f"AWS limits gateway names to {MAX_GATEWAY_NAME_LENGTH} characters. "
+                "Shorten the project name or gateway name."
+            )
+
+        selected = set(config.selected_targets or [])
+        moved: list[dict[str, Any]] = []
+        if selected and project.get("unassignedTargets"):
+            remaining = []
+            for target in project["unassignedTargets"]:
+                (moved if target["name"] in selected else remaining).append(target)
+            if remaining:
+                project["unassignedTargets"] = remaining
+            else:
+                project.pop("unassignedTargets", None)
+
+        gateway: dict[str, Any] = {
+            "name": config.name,
+            "protocolType": config.protocol_type or "None",
+            "description": config.description,
+            "targets": moved,
+            "authorizerType": config.authorizer_type,
+        }
+        if config.authorizer_type == "CUSTOM_JWT" and config.jwt_config:
+            gateway["authorizerConfiguration"] = build_authorizer_config_from_jwt_config(config.jwt_config)
+        gateway["enableSemanticSearch"] = config.enable_semantic_search
+        gateway["exceptionLevel"] = config.exception_level
+        if config.policy_engine_configuration:
+            gateway["policyEngineConfiguration"] = config.policy_engine_configuration
+
+        gateways.append(gateway)
+        self.write_project_spec(project)
+
+        if config.jwt_config and config.jwt_config.client_id and config.jwt_config.client_secret:
+            create_managed_oauth_credential(
+                config.name,
+                config.jwt_config,
+                self.write_project_spec,
+                self.read_project_spec,
+                self.config_io.get_config_root(),
+            )
+        return config.name
+
+    # --- remove -------------------------------------------------------------------------
+
+    @staticmethod
+    def _compute_removed_gateway_mcp_spec(mcp_spec: dict[str, Any], gateway_name: str) -> dict[str, Any]:
+        """Remove the gateway; its targets move to ``unassignedTargets`` so they are preserved."""
+        gateway = next((g for g in mcp_spec["agentCoreGateways"] if g["name"] == gateway_name), None)
+        orphaned = (gateway or {}).get("targets") or []
+        merged = [*(mcp_spec.get("unassignedTargets") or []), *orphaned]
+        result = {
+            **mcp_spec,
+            "agentCoreGateways": [g for g in mcp_spec["agentCoreGateways"] if g["name"] != gateway_name],
+        }
+        if merged:
+            result["unassignedTargets"] = merged
+        return result
+
+    def remove(self, name: str) -> Ok[None] | Err[Exception]:
+        try:
+            project = self._project()
+            mcp_spec = _mcp_fields(project)
+            if not any(g["name"] == name for g in mcp_spec["agentCoreGateways"]):
+                return Err(ResourceNotFoundError(f'Gateway "{name}" not found.'))
+            self.write_project_spec({**project, **self._compute_removed_gateway_mcp_spec(mcp_spec, name)})
+            return Ok(None)
+        except Exception as exc:  # noqa: BLE001
+            return Err(to_error(exc))
+
+    def preview_remove(self, name: str) -> RemovalPreview:
+        project = self._project()
+        mcp_spec = _mcp_fields(project)
+        gateway = next((g for g in mcp_spec["agentCoreGateways"] if g["name"] == name), None)
+        if gateway is None:
+            raise Exception(f'Gateway "{name}" not found.')
+        summary = [f"Removing gateway: {name}"]
+        if gateway.get("targets"):
+            summary.append(f"Note: {len(gateway['targets'])} target(s) behind this gateway will become unassigned")
+        after = {**copy.deepcopy(project), **self._compute_removed_gateway_mcp_spec(copy.deepcopy(mcp_spec), name)}
+        return RemovalPreview(summary, [], [SchemaChange("agentcore/agentcore.json", project, after)])
+
+    def get_removable(self) -> list[RemovableResource]:
+        try:
+            return [RemovableResource(g["name"]) for g in self._project().get("agentCoreGateways", [])]
+        except Exception:  # noqa: BLE001
+            return []
+
+    # --- queries ------------------------------------------------------------------------
+
+    def get_existing_gateways(self) -> list[str]:
+        return [r.name for r in self.get_removable()]
+
+    def get_mcp_gateway_names(self) -> list[str]:
+        try:
+            return [g["name"] for g in self._project().get("agentCoreGateways", []) if g.get("protocolType") != "None"]
+        except Exception:  # noqa: BLE001
+            return []
+
+    def get_runtime_names(self) -> list[str]:
+        try:
+            return [r["name"] for r in self._project().get("runtimes", [])]
+        except Exception:  # noqa: BLE001
+            return []
+
+    def get_runtime_endpoints(self, runtime_name: str) -> list[dict[str, Any]]:
+        try:
+            runtime = next((r for r in self._project().get("runtimes", []) if r["name"] == runtime_name), None)
+            if not runtime or not runtime.get("endpoints"):
+                return []
+            return [{"name": n, "version": ep["version"]} for n, ep in runtime["endpoints"].items()]
+        except Exception:  # noqa: BLE001
+            return []
+
+    def get_unassigned_targets(self) -> list[dict[str, Any]]:
+        try:
+            return self._project().get("unassignedTargets") or []
+        except Exception:  # noqa: BLE001
+            return []
+
+    # --- CLI ----------------------------------------------------------------------------
+
+    def register_commands(self, add_app: typer.Typer, remove_app: typer.Typer) -> None:
+        @add_app.command("gateway", help="Add an API gateway that routes requests to agent targets")
+        def add_command(
+            name: str | None = typer.Option(None, "--name", help="Gateway name [non-interactive]"),
+            description: str | None = typer.Option(None, "--description", help="Gateway description [non-interactive]"),
+            protocol_type: str | None = typer.Option(
+                None, "--protocol-type", help="Protocol type: MCP or None (default: None) [non-interactive]"
+            ),
+            runtimes: str | None = typer.Option(
+                None,
+                "--runtimes",
+                help="Comma-separated runtime names to expose through this gateway [non-interactive]",
+            ),
+            authorizer_type: str | None = typer.Option(
+                None, "--authorizer-type", help="Authorizer type: NONE, AWS_IAM, or CUSTOM_JWT [non-interactive]"
+            ),
+            discovery_url: str | None = typer.Option(
+                None, "--discovery-url", help="OIDC discovery URL (for CUSTOM_JWT) [non-interactive]"
+            ),
+            allowed_audience: str | None = typer.Option(
+                None, "--allowed-audience", help="Comma-separated allowed audiences (for CUSTOM_JWT) [non-interactive]"
+            ),
+            allowed_clients: str | None = typer.Option(
+                None, "--allowed-clients", help="Comma-separated allowed client IDs (for CUSTOM_JWT) [non-interactive]"
+            ),
+            allowed_scopes: str | None = typer.Option(
+                None, "--allowed-scopes", help="Comma-separated allowed scopes (for CUSTOM_JWT) [non-interactive]"
+            ),
+            custom_claims: str | None = typer.Option(
+                None,
+                "--custom-claims",
+                help="Custom claim validations as JSON array (for CUSTOM_JWT) [non-interactive]",
+            ),
+            client_id: str | None = typer.Option(
+                None, "--client-id", help="OAuth client ID for fetching gateway bearer tokens [non-interactive]"
+            ),
+            client_secret: str | None = typer.Option(
+                None, "--client-secret", help="OAuth client secret for fetching gateway bearer tokens [non-interactive]"
+            ),
+            semantic_search: bool = typer.Option(
+                True,
+                " /--no-semantic-search",
+                help="Disable semantic search for gateway target tool discovery [non-interactive]",
+            ),
+            exception_level: str = typer.Option(
+                "NONE",
+                "--exception-level",
+                help="Exception detail level in error responses: NONE, ALL [non-interactive]",
+            ),
+            policy_engine: str | None = typer.Option(
+                None, "--policy-engine", help="Policy engine name for Cedar-based authorization [non-interactive]"
+            ),
+            policy_engine_mode: str | None = typer.Option(
+                None, "--policy-engine-mode", help="Policy engine mode: LOG_ONLY or ENFORCE [non-interactive]"
+            ),
+            as_json: bool = typer.Option(False, "--json", help="Output as JSON [non-interactive]"),
+        ) -> None:
+            if not find_config_root():
+                typer.echo("No agentcore project found. Run `agentcore create` first.", err=True)
+                raise typer.Exit(1)
+
+            cli_options: dict[str, Any] = {
+                "name": name,
+                "description": description,
+                "protocolType": protocol_type,
+                "runtimes": runtimes,
+                "authorizerType": authorizer_type,
+                "discoveryUrl": discovery_url,
+                "allowedAudience": allowed_audience,
+                "allowedClients": allowed_clients,
+                "allowedScopes": allowed_scopes,
+                "customClaims": custom_claims,
+                "clientId": client_id,
+                "clientSecret": client_secret,
+                "semanticSearch": semantic_search,
+                "exceptionLevel": exception_level,
+                "policyEngine": policy_engine,
+                "policyEngineMode": policy_engine_mode,
+            }
+
+            def action() -> None:
+                validation = validate_add_gateway_options(cli_options)
+                if not validation.valid:
+                    raise ValidationError(validation.error or "")
+                result = self.add(
+                    AddGatewayOptions(
+                        name=name or "",
+                        description=description,
+                        protocol_type=protocol_type,
+                        authorizer_type=authorizer_type or "NONE",
+                        discovery_url=discovery_url,
+                        allowed_audience=allowed_audience,
+                        allowed_clients=allowed_clients,
+                        allowed_scopes=allowed_scopes,
+                        custom_claims=json.loads(custom_claims) if custom_claims else None,
+                        client_id=client_id,
+                        client_secret=client_secret,
+                        runtimes=runtimes,
+                        enable_semantic_search=semantic_search is not False,
+                        exception_level=exception_level,
+                        policy_engine=policy_engine,
+                        policy_engine_mode=policy_engine_mode,
+                    )
+                )
+                if not result.success:
+                    raise result.error
+                if as_json:
+                    emit_json(serialize_result(result))
+                else:
+                    typer.echo(f"Added gateway '{result.value['gatewayName']}'")
+
+            run_cli_command(as_json, action)
+
+        self.register_remove_subcommand(remove_app)
+
+    # --- interactive (port of tui/screens/mcp AddGatewayScreen + AddGatewayFlow) --------------
+
+    def add_interactive(self) -> None:
+        from agentcore.cli.commands.add._common import first_issue
+        from agentcore.cli.naming import generate_unique_name
+        from agentcore.schema import GatewayName
+
+        existing = self.get_existing_gateways()
+        unassigned = [t["name"] for t in self.get_unassigned_targets()]
+        try:
+            engines = [e["name"] for e in self._project().get("policyEngines", [])]
+        except Exception:  # noqa: BLE001
+            engines = []
+
+        name = interactive.text(
+            "Name",
+            default=generate_unique_name("my-gateway", existing, "-"),
+            validate=lambda v: (
+                first_issue(GatewayName, v) or ("Gateway name already exists" if v in existing else None)
+            ),
+        )
+        authorizer = interactive.select(
+            "Select authorizer type (How will clients authenticate to this gateway?)",
+            [
+                interactive.Choice("AWS IAM", "AWS_IAM", "AWS Identity and Access Management authorization"),
+                interactive.Choice("Custom JWT", "CUSTOM_JWT", "JWT-based authorization via OIDC provider"),
+                interactive.Choice("None", "NONE", "No authorization required — gateway is publicly accessible"),
+            ],
+        )
+        from agentcore.cli.commands.add.agent_wizard import prompt_jwt_config  # shared JWT flow, as upstream
+
+        jwt_config = prompt_jwt_config() if authorizer == "CUSTOM_JWT" else None
+        selected_targets: list[str] = []
+        if unassigned:
+            selected_targets = interactive.checkbox(
+                "Select unassigned targets to include in this gateway",
+                [interactive.Choice(t, t) for t in unassigned],
+            )
+        policy_engine_configuration = None
+        if engines:
+            engine = interactive.select(
+                "Select a policy engine (Attach a Cedar policy engine to authorize tool calls on this gateway)",
+                [
+                    interactive.Choice("None", "__none__", "No policy engine"),
+                    *[interactive.Choice(e, e) for e in engines],
+                ],
+            )
+            if engine != "__none__":
+                mode = interactive.select(
+                    f"Select enforcement mode (Policy engine: {engine})",
+                    [
+                        interactive.Choice("Log Only", "LOG_ONLY", "Log policy decisions without enforcing"),
+                        interactive.Choice(
+                            "Enforce", "ENFORCE", "Enforce policy decisions and block unauthorized actions"
+                        ),
+                    ],
+                )
+                policy_engine_configuration = {"policyEngineName": engine, "mode": mode}
+        advanced = interactive.checkbox(
+            "Advanced configuration",
+            [
+                interactive.Choice("Semantic Search", "semantic-search"),
+                interactive.Choice("Debug Exception Level", "exception-level"),
+            ],
+            checked=["semantic-search"],
+        )
+        config = AddGatewayConfig(
+            name=name,
+            description=f"Gateway for {name}",
+            authorizer_type=authorizer,
+            jwt_config=jwt_config,
+            selected_targets=selected_targets,
+            enable_semantic_search="semantic-search" in advanced,
+            exception_level="DEBUG" if "exception-level" in advanced else "NONE",
+            policy_engine_configuration=policy_engine_configuration,
+        )
+
+        typer.echo(f"  Name: {config.name}")
+        typer.echo(f"  Description: {config.description}")
+        typer.echo(f"  Authorizer: {authorizer}")
+        if jwt_config:
+            typer.echo(f"  Discovery URL: {jwt_config.discovery_url}")
+            for label, values in (
+                ("Allowed Audience", jwt_config.allowed_audience),
+                ("Allowed Clients", jwt_config.allowed_clients),
+                ("Allowed Scopes", jwt_config.allowed_scopes),
+            ):
+                if values:
+                    typer.echo(f"  {label}: {', '.join(values)}")
+            if jwt_config.client_id:
+                typer.echo(f"  Gateway Credential: {compute_managed_oauth_credential_name(name)}")
+        typer.echo(f"  Targets: {', '.join(selected_targets) if selected_targets else '(none)'}")
+        typer.echo(f"  Semantic Search: {'Enabled' if config.enable_semantic_search else 'Disabled'}")
+        typer.echo(f"  Exception Level: {'Debug' if config.exception_level == 'DEBUG' else 'None'}")
+        if policy_engine_configuration:
+            typer.echo(f"  Policy Engine: {policy_engine_configuration['policyEngineName']}")
+            typer.echo(f"  Enforcement Mode: {policy_engine_configuration['mode']}")
+        if not interactive.confirm("Create this gateway?", default=True):
+            return
+        try:
+            self.create_gateway_from_wizard(config)
+        except Exception as exc:  # noqa: BLE001
+            typer.echo(f"Error: {get_error_message(exc)}", err=True)
+            raise typer.Exit(1) from None
+        typer.echo(f"Added gateway '{name}'")
+
+
+PRIMITIVE = GatewayPrimitive()