apizit-cli 0.2.0b1__py3-none-any.whl

apizit_cli/commands.py

@@ -0,0 +1,337 @@
+"""Customer command definitions, shared by argparse and the published reference."""
+
+from dataclasses import asdict, dataclass, replace
+
+
+@dataclass(frozen=True)
+class Option:
+    flags: tuple[str, ...]
+    help: str
+    action: str | None = None
+    choices: tuple[str, ...] | None = None
+    value_type: str = "str"
+    default: object = None
+    nargs: str | None = None
+
+
+@dataclass(frozen=True)
+class Command:
+    path: str
+    summary: str
+    permission: str
+    options: tuple[Option, ...] = ()
+    example: str = ""
+
+
+def argument(name, help, *, optional=False):
+    return Option((name,), help, nargs="?" if optional else None)
+
+
+def flag(name, help, **kwargs):
+    return Option((name,), help, **kwargs)
+
+
+GLOBAL_OPTIONS = (
+    flag("--json", "Write one versioned JSON result to stdout.", action="store_true"),
+    flag("--workspace", "Workspace ID; overrides environment and saved context."),
+    flag("--endpoint", "APIZIT HTTPS endpoint; defaults to the development beta."),
+    flag("--non-interactive", "Never prompt or open a browser.", action="store_true"),
+    flag("--token-stdin", "Read a CI token from stdin without saving it.", action="store_true"),
+)
+WAIT_OPTIONS = (
+    flag("--wait", "Wait for completion (default for interactive sessions).", action="store_true"),
+    flag("--no-wait", "Return identifiers immediately after submission.", action="store_true"),
+    flag("--timeout", "Maximum local wait in seconds; default 600.", value_type="positive_float"),
+)
+WRITE_OPTIONS = (
+    flag(
+        "--idempotency-key", "Stable operation key; reuse the same key after uncertain submission."
+    ),
+)
+YES = flag("--yes", "Confirm this deletion or traffic change.", action="store_true")
+FORMAT = flag(
+    "--format", "Launch format.", choices=("automatic", "standard", "expanded", "max_power")
+)
+REGION = flag("--region", "Logical region, as returned by apizit regions.")
+API = flag("--api", "API ID; defaults to the API linked to this local project.")
+REF = flag("--ref", "Git branch, tag or exact revision to verify on the server.")
+SOURCE = argument("source", "HTTPS Git URL or local folder.", optional=True)
+SCAN_OPTIONS = (REF, FORMAT, REGION) + WAIT_OPTIONS + WRITE_OPTIONS
+
+COMMANDS = (
+    Command(
+        "login",
+        "Connect securely through your browser.",
+        "human",
+        (flag("--timeout", "Login timeout in seconds; default 180.", value_type="positive_float"),),
+    ),
+    Command("logout", "Revoke the saved session and clear the system vault.", "human"),
+    Command("whoami", "Show the current identity.", "read"),
+    Command("workspace list", "List accessible workspaces.", "read"),
+    Command(
+        "workspace use",
+        "Select and verify a workspace.",
+        "read",
+        (argument("id", "Workspace ID."),),
+    ),
+    Command("workspace show", "Show the selected workspace and its current capabilities.", "read"),
+    Command(
+        "workspace create",
+        "Create a workspace within your account's allowances.",
+        "human",
+        (argument("name", "Workspace name."),),
+    ),
+    Command(
+        "init",
+        "Create a version 2 deployment configuration.",
+        "local",
+        (
+            argument(
+                "directory", "Project folder; defaults to the current directory.", optional=True
+            ),
+            flag("--name", "Project name; defaults to the folder name."),
+        ),
+    ),
+    Command(
+        "config validate",
+        "Validate the single deployment configuration.",
+        "local",
+        (argument("directory", "Project folder.", optional=True),),
+    ),
+    Command(
+        "config show",
+        "Resolve configuration and show the origin of each value.",
+        "read",
+        (argument("directory", "Project folder.", optional=True), API, FORMAT, REGION),
+    ),
+    Command("config schema", "Print the version 2 JSON schema.", "local"),
+    Command(
+        "scan",
+        "Analyze a Git URL or folder; use scan show/wait to resume.",
+        "scan",
+        (
+            argument("source", "Source, or the action show/wait."),
+            argument("id", "Scan ID for show/wait.", optional=True),
+        )
+        + SCAN_OPTIONS,
+        "apizit scan . --wait",
+    ),
+    Command(
+        "deploy",
+        "Launch an API or prepare a release of --api.",
+        "deploy",
+        (
+            SOURCE,
+            API,
+            REF,
+            FORMAT,
+            REGION,
+            flag("--from-scan", "Reuse the exact source and configuration of a successful scan."),
+            flag("--strategy", "Release strategy.", choices=("direct", "blue_green")),
+            flag("--name", "API name; overrides project.name."),
+            flag("--api-key-required", "Protect calls with an API key.", action="store_true"),
+            flag("--no-api-key", "Explicitly allow calls without an API key.", action="store_true"),
+            YES,
+        )
+        + WAIT_OPTIONS
+        + WRITE_OPTIONS,
+        "apizit deploy . --wait",
+    ),
+    Command("api list", "List APIs in the workspace.", "read"),
+    Command(
+        "api show",
+        "Show an API, its live URL and releases.",
+        "read",
+        (argument("id", "API ID; defaults to the linked API.", optional=True),),
+    ),
+    Command(
+        "api logs",
+        "Read a bounded page of redacted API logs.",
+        "logs",
+        (
+            argument("id", "API ID; defaults to the linked API.", optional=True),
+            flag("--from", "Inclusive start time in ISO 8601 with timezone."),
+            flag("--to", "Inclusive end time in ISO 8601 with timezone."),
+            flag("--level", "Log level.", choices=("all", "error", "warning", "info")),
+            flag("--query", "Search text, without control characters."),
+            flag("--limit", "Page size; the server applies workspace limits.", value_type="int"),
+            flag("--cursor", "Opaque next-page cursor returned by the previous request."),
+            flag("--release", "Release ID; otherwise uses the current release."),
+        ),
+    ),
+    Command(
+        "api usage",
+        "Show API consumption and current release usage.",
+        "read",
+        (argument("id", "API ID; defaults to the linked API.", optional=True),),
+    ),
+    Command(
+        "api openapi",
+        "Export the current release's OpenAPI document.",
+        "read",
+        (
+            argument("id", "API ID; defaults to the linked API.", optional=True),
+            flag("--output", "New output file; otherwise returns the parsed document."),
+        ),
+    ),
+    Command(
+        "api key",
+        "Explicitly retrieve a protected API's call key.",
+        "credentials:read",
+        (
+            argument("id", "API ID; defaults to the linked API.", optional=True),
+            flag("--release", "Release ID; defaults to the current release."),
+        ),
+    ),
+    Command(
+        "api delete",
+        "Delete an API and its releases after confirmation.",
+        "delete",
+        (argument("id", "API ID."), YES) + WAIT_OPTIONS + WRITE_OPTIONS,
+    ),
+    Command(
+        "release list", "List retained releases and the current traffic workflow.", "read", (API,)
+    ),
+    Command("release show", "Show a release.", "read", (argument("id", "Release ID."),)),
+    Command(
+        "release promote",
+        "Send traffic to the ready candidate release.",
+        "traffic",
+        (argument("id", "Candidate release ID."), API, YES) + WAIT_OPTIONS + WRITE_OPTIONS,
+    ),
+    Command(
+        "release rollback",
+        "Restore the existing compatible rollback release without a build.",
+        "traffic",
+        (API, YES) + WAIT_OPTIONS + WRITE_OPTIONS,
+    ),
+    Command(
+        "release discard",
+        "Delete a release that is no longer serving traffic.",
+        "delete",
+        (argument("id", "Release ID."), YES) + WAIT_OPTIONS + WRITE_OPTIONS,
+    ),
+    Command("job show", "Show a remote operation.", "read", (argument("id", "Job ID."),)),
+    Command(
+        "job wait",
+        "Resume observing a remote operation without restarting it.",
+        "read",
+        (argument("id", "Job ID."),) + WAIT_OPTIONS,
+    ),
+    Command(
+        "job cancel",
+        "Request cancellation only when the server permits it.",
+        "deploy",
+        (argument("id", "Job ID."), YES) + WAIT_OPTIONS + WRITE_OPTIONS,
+    ),
+    Command(
+        "regions",
+        "Show available regions for this workspace and launch format.",
+        "read",
+        (FORMAT, API),
+    ),
+    Command("plans", "Read the current public plans from APIZIT.", "public"),
+    Command("usage", "Show the workspace's current consumption.", "read"),
+    Command("capabilities", "Read current platform capabilities and defaults.", "read"),
+    Command(
+        "token create",
+        "Create a limited, expiring workspace token; displayed once.",
+        "human",
+        (
+            argument("name", "Token name."),
+            flag("--scope", "Permission; repeat to grant several.", action="append"),
+            flag("--expires-days", "Lifetime in days; default 30, maximum 90.", value_type="int"),
+        ),
+    ),
+    Command("token list", "List workspace tokens without their values.", "human"),
+    Command(
+        "token revoke", "Revoke a token immediately.", "human", (argument("id", "Token ID."), YES)
+    ),
+    Command(
+        "secret set",
+        "Store a new secret version without echoing its value.",
+        "secrets:write",
+        (
+            argument("name", "Workspace secret name."),
+            flag("--stdin", "Read the exact UTF-8 secret value from stdin.", action="store_true"),
+            flag("--from-env", "Read the value from a local environment variable."),
+        )
+        + WRITE_OPTIONS,
+    ),
+    Command("secret list", "List secret names and versions without reading values.", "read"),
+    Command(
+        "secret delete",
+        "Delete an unreferenced workspace secret.",
+        "secrets:write",
+        (argument("name", "Workspace secret name."), YES) + WRITE_OPTIONS,
+    ),
+    Command(
+        "docs",
+        "Get or open the public CLI documentation.",
+        "public",
+        (
+            argument("topic", "Documentation section or quoted command name.", optional=True),
+            flag("--open", "Open the documentation in your browser.", action="store_true"),
+        ),
+    ),
+    Command(
+        "doctor", "Check client installation, connectivity and secure credential storage.", "local"
+    ),
+)
+
+
+_EXAMPLES = {
+    "login": "apizit login",
+    "logout": "apizit logout",
+    "whoami": "apizit whoami --json",
+    "workspace list": "apizit workspace list --json",
+    "workspace use": "apizit workspace use ws_YOUR_WORKSPACE",
+    "workspace show": "apizit workspace show --json",
+    "workspace create": 'apizit workspace create "Weather APIs"',
+    "init": "apizit init . --name weather-api",
+    "config validate": "apizit config validate . --json",
+    "config show": "apizit config show . --region europe --json",
+    "config schema": "apizit config schema --json",
+    "api list": "apizit api list --json",
+    "api show": "apizit api show api_YOUR_API --json",
+    "api logs": "apizit api logs api_YOUR_API --level error --limit 50 --json",
+    "api usage": "apizit api usage api_YOUR_API --json",
+    "api openapi": "apizit api openapi api_YOUR_API --output openapi.json",
+    "api key": "apizit api key api_YOUR_API --json",
+    "api delete": "apizit api delete api_YOUR_API --yes --wait --json",
+    "release list": "apizit release list --api api_YOUR_API --json",
+    "release show": "apizit release show dep_YOUR_RELEASE --json",
+    "release promote": "apizit release promote dep_YOUR_CANDIDATE --api api_YOUR_API --idempotency-key promote-release-001 --yes --json",
+    "release rollback": "apizit release rollback --api api_YOUR_API --idempotency-key rollback-release-001 --yes --json",
+    "release discard": "apizit release discard dep_YOUR_OLD_RELEASE --yes --wait --json",
+    "job show": "apizit job show job_YOUR_JOB --json",
+    "job wait": "apizit job wait job_YOUR_JOB --timeout 900 --json",
+    "job cancel": "apizit job cancel job_YOUR_JOB --yes --json",
+    "regions": "apizit regions --format standard --json",
+    "plans": "apizit plans --json",
+    "usage": "apizit usage --json",
+    "capabilities": "apizit capabilities --json",
+    "token create": 'apizit token create "Release CI" --scope read --scope scan --scope deploy --expires-days 30',
+    "token list": "apizit token list --json",
+    "token revoke": "apizit token revoke YOUR_TOKEN_ID --yes",
+    "secret set": "apizit secret set weather_api_key --from-env WEATHER_API_KEY",
+    "secret list": "apizit secret list --json",
+    "secret delete": "apizit secret delete weather_api_key --yes",
+    "docs": 'apizit docs "release promote"',
+    "doctor": "apizit doctor --json",
+}
+COMMANDS = tuple(
+    replace(command, example=command.example or _EXAMPLES[command.path]) for command in COMMANDS
+)
+
+
+def reference():
+    return {
+        "schema_version": 1,
+        "global_options": [asdict(option) for option in GLOBAL_OPTIONS],
+        "commands": [asdict(command) for command in COMMANDS],
+        "scan_actions": {
+            "scan show": "apizit scan show <id>",
+            "scan wait": "apizit scan wait <id> [--timeout SECONDS]",
+        },
+    }

apizit_cli/configuration.py

@@ -0,0 +1,246 @@
+"""Public, provider-independent deployment configuration contract."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator, model_validator
+
+CONFIG_FILES = ("apizit_config.yaml", "apizit_config.yml", "apizit_config.json")
+MAX_CONFIG_BYTES = 64 * 1024
+FORMAT_OPTIONS = {
+    "automatic": ("auto", "automatic"),
+    "standard": ("lambda_zip", "automatic"),
+    "expanded": ("lambda_ecr", "automatic"),
+    "max_power": ("lambda_ecr", "max_power"),
+}
+
+
+class ConfigurationError(ValueError):
+    """A safe, field-oriented error, without the submitted value."""
+
+
+class StrictModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True, validate_assignment=True)
+
+
+class ProjectConfiguration(StrictModel):
+    name: str | None = Field(default=None, min_length=1, max_length=120)
+
+
+class LaunchConfiguration(StrictModel):
+    format: Literal["automatic", "standard", "expanded", "max_power"] = "automatic"
+
+
+class ApiConfiguration(StrictModel):
+    api_key_required: bool = False
+
+
+class HealthCheckConfiguration(StrictModel):
+    mode: Literal["auto", "custom", "disabled"] = "auto"
+    path: str | None = Field(default=None, max_length=1024)
+
+    @model_validator(mode="after")
+    def valid_path(self):
+        path = self.path
+        if self.mode == "custom" and not path:
+            raise ValueError("custom health check requires path")
+        if path is not None and (
+            not path.startswith("/")
+            or path.startswith("//")
+            or any(ord(char) < 32 for char in path)
+            or any(char in path for char in ("\\", "?", "#"))
+        ):
+            raise ValueError("path must be an absolute API path without query or fragment")
+        return self
+
+
+class DeploymentConfiguration(StrictModel):
+    version: Literal[2] = 2
+    project: ProjectConfiguration = Field(default_factory=ProjectConfiguration)
+    region: Literal["europe", "asia", "africa", "north_america", "south_america"] | None = None
+    launch: LaunchConfiguration = Field(default_factory=LaunchConfiguration)
+    api: ApiConfiguration = Field(default_factory=ApiConfiguration)
+    health_check: HealthCheckConfiguration = Field(default_factory=HealthCheckConfiguration)
+    environment: dict[str, str] = Field(default_factory=dict)
+    secrets: dict[str, str] = Field(default_factory=dict)
+
+    @field_validator("version", mode="before")
+    @classmethod
+    def strict_version(cls, value):
+        if type(value) is not int or value != 2:
+            raise ValueError("version must be the integer 2")
+        return value
+
+    @field_validator("environment", "secrets")
+    @classmethod
+    def validate_names(cls, values):
+        import re
+        import unicodedata
+
+        reserved = {
+            "_HANDLER",
+            "_X_AMZN_TRACE_ID",
+            "LAMBDA_RUNTIME_DIR",
+            "LAMBDA_TASK_ROOT",
+        }
+        if len(values) > 100:
+            raise ValueError("at most 100 variables are supported")
+        for name, value in values.items():
+            if (
+                not re.fullmatch(r"[A-Za-z][A-Za-z0-9_]+", name)
+                or name.startswith(("APIZIT_", "AWS_", "LAMBDA_"))
+                or name in reserved
+            ):
+                raise ValueError("variable names must be valid and not platform-reserved")
+            if len(value.encode("utf-8")) > 2048 or "\x00" in value:
+                raise ValueError("variable values must be text of at most 2048 UTF-8 bytes")
+            if any(
+                unicodedata.category(character) in {"Cc", "Cs", "Zl", "Zp"} for character in value
+            ):
+                raise ValueError(
+                    "environment values cannot contain line breaks or control characters"
+                )
+            if "{{resolve:" in value:
+                raise ValueError("provider references are managed exclusively by APIZIT")
+        return values
+
+    @field_validator("secrets")
+    @classmethod
+    def validate_secret_references(cls, values):
+        import re
+
+        if len(values) > 32:
+            raise ValueError("a release supports at most 32 secret variables")
+
+        if any(
+            not re.fullmatch(r"[A-Za-z][A-Za-z0-9_-]{0,63}", value) for value in values.values()
+        ):
+            raise ValueError("secret references must be names, not values or provider identifiers")
+        return values
+
+    @model_validator(mode="after")
+    def validate_environment(self):
+        if self.environment.keys() & self.secrets.keys():
+            raise ValueError("a variable cannot be both an environment value and a secret")
+        if sum(len(k.encode()) + len(v.encode()) for k, v in self.environment.items()) > 4096:
+            raise ValueError("environment exceeds the 4096-byte runtime limit")
+        if (
+            len(json.dumps(self.model_dump(mode="json"), separators=(",", ":")).encode())
+            > MAX_CONFIG_BYTES
+        ):
+            raise ValueError("configuration exceeds 64 KiB")
+        return self
+
+    def explicit_options(self) -> dict:
+        """Only explicit choices may override repository or server defaults."""
+        return self.model_dump(exclude_unset=True, exclude={"version"}, mode="json")
+
+
+class _StrictLoader(yaml.SafeLoader):
+    def construct_mapping(self, node, deep=False):
+        if not isinstance(node, yaml.MappingNode):
+            raise ConfigurationError("Expected a YAML object.")
+        pairs = []
+        for key, value in node.value:
+            pairs.append(
+                (self.construct_object(key, deep=deep), self.construct_object(value, deep=deep))
+            )
+        return _unique_object(pairs)
+
+
+def _unique_object(pairs):
+    result = {}
+    for key, value in pairs:
+        if not isinstance(key, str) or key in result:
+            raise ConfigurationError("Configuration keys must be unique text names.")
+        result[key] = value
+    return result
+
+
+def parse_configuration(text: str, *, json_format: bool = False) -> DeploymentConfiguration:
+    if len(text.encode("utf-8")) > MAX_CONFIG_BYTES:
+        raise ConfigurationError("Configuration exceeds 64 KiB.")
+    try:
+        if json_format:
+            raw = json.loads(text, object_pairs_hook=_unique_object)
+        else:
+            if any(
+                isinstance(token, (yaml.AliasToken, yaml.AnchorToken)) for token in yaml.scan(text)
+            ):
+                raise ConfigurationError("YAML anchors and aliases are not supported.")
+            raw = yaml.load(text, Loader=_StrictLoader)
+        if not isinstance(raw, dict) or "version" not in raw:
+            raise ConfigurationError("Configuration must be an object with version: 2.")
+        return DeploymentConfiguration.model_validate(raw)
+    except (yaml.YAMLError, json.JSONDecodeError, UnicodeError, RecursionError):
+        raise ConfigurationError("Configuration is not valid UTF-8 YAML or JSON.") from None
+    except ValidationError as error:
+        details = "; ".join(
+            f"{'.'.join(str(part) for part in item['loc']) or 'configuration'}: {item['msg']}"
+            for item in error.errors(include_input=False, include_url=False)
+        )
+        raise ConfigurationError(details) from None
+
+
+def load_configuration(root: Path) -> tuple[DeploymentConfiguration, Path | None]:
+    root = Path(root).resolve(strict=True)
+    candidates = [
+        root / name for name in CONFIG_FILES if (root / name).exists() or (root / name).is_symlink()
+    ]
+    if len(candidates) > 1:
+        raise ConfigurationError("Keep exactly one apizit_config.yaml, .yml or .json file.")
+    if not candidates:
+        return DeploymentConfiguration(), None
+    path = candidates[0]
+    if path.is_symlink() or not path.is_file() or path.stat().st_size > MAX_CONFIG_BYTES:
+        raise ConfigurationError("Configuration must be a regular file of at most 64 KiB.")
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeError):
+        raise ConfigurationError("Configuration could not be read as UTF-8.") from None
+    return parse_configuration(text, json_format=path.suffix == ".json"), path
+
+
+def resolve_configuration(*, configuration: dict, overrides: dict, defaults: dict) -> dict:
+    """Resolve explicit fields only; callers supply the current server defaults."""
+    import hashlib
+
+    origins = {}
+    merged = {}
+
+    def apply(target, values, origin, prefix=""):
+        for key, value in values.items():
+            path = f"{prefix}.{key}" if prefix else key
+            if isinstance(value, dict) and key not in {"environment", "secrets"}:
+                child = target.setdefault(key, {})
+                apply(child, value, origin, path)
+            else:
+                target[key] = value
+                for previous in list(origins):
+                    if previous.startswith(path + "."):
+                        del origins[previous]
+                origins[path] = origin
+                if isinstance(value, dict):
+                    origins.update({f"{path}.{name}": origin for name in value})
+
+    for values, origin in (
+        (defaults, "server_default"),
+        (configuration, "configuration"),
+        (overrides, "explicit_option"),
+    ):
+        # Validation must not turn omitted options into client-side defaults.
+        validated = parse_configuration(json.dumps({"version": 2, **values}), json_format=True)
+        apply(merged, validated.explicit_options(), origin)
+    resolved = parse_configuration(json.dumps({"version": 2, **merged}), json_format=True)
+    document = resolved.model_dump(mode="json")
+    canonical = json.dumps(document, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+    return {
+        "configuration": document,
+        "origins": origins,
+        "configuration_digest_sha256": hashlib.sha256(canonical.encode()).hexdigest(),
+        "configuration_contract_version": 2,
+    }