tangle-cli 0.0.1a1__py3-none-any.whl

tangle_cli/api_transport.py

@@ -0,0 +1,461 @@
+"""HTTP transport helpers shared by the OpenAPI CLI and programmatic client."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import urllib.parse
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+DEFAULT_API_URL = "http://localhost:8000"
+DEFAULT_TIMEOUT_SECONDS = 30.0
+_HEADER_NAME_RE = re.compile(r"^[!#$%&'*+.^_`|~0-9A-Za-z-]+$")
+_MISSING = object()
+_SENSITIVE_HEADER_NAMES = {"authorization", "cloud-auth", "cookie", "x-api-key"}
+_SENSITIVE_KEY_RE = re.compile(
+    r"(authorization|authentication|(^|[-_])auth($|[-_])|cloud[-_]?auth|cookie|x[-_]?api[-_]?key|token|secret|password|credential|pre[-_]?signed[-_]?url|signed[-_]?url)",
+    re.IGNORECASE,
+)
+_REDACTED = "<redacted>"
+_REDACTED_DOCUMENT = "<redacted document>"
+_OPAQUE_DOCUMENT_KEY_NAMES = {
+    "component_yaml",
+    "dockerfile",
+    "manifest",
+    "pipeline_yaml",
+    "text",
+    "yaml",
+}
+
+
+def tangle_verbose_enabled() -> bool:
+    value = os.environ.get("TANGLE_VERBOSE")
+    if value is None:
+        return False
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _redact_headers(headers: dict[str, Any] | None) -> dict[str, Any]:
+    redacted: dict[str, Any] = {}
+    for name, value in (headers or {}).items():
+        normalized_name = name.lower()
+        redacted[name] = (
+            _REDACTED
+            if normalized_name in _SENSITIVE_HEADER_NAMES or _SENSITIVE_KEY_RE.search(name)
+            else value
+        )
+    return redacted
+
+
+def _redact_sensitive_values(value: Any, key: str | None = None) -> Any:
+    if key and _SENSITIVE_KEY_RE.search(key):
+        return _REDACTED
+    if key and key.lower() in _OPAQUE_DOCUMENT_KEY_NAMES and isinstance(value, str) and value:
+        return _REDACTED_DOCUMENT
+    if isinstance(value, dict):
+        return {str(k): _redact_sensitive_values(v, str(k)) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_redact_sensitive_values(item) for item in value]
+    return value
+
+
+def _safe_json_text(value: Any) -> str:
+    redacted = _redact_sensitive_values(value)
+    try:
+        return json.dumps(redacted, indent=2, sort_keys=True, default=str)
+    except TypeError:
+        return str(redacted)
+
+
+def _content_to_text(content: bytes | str | None) -> str:
+    if content is None:
+        return "<empty>"
+    if isinstance(content, bytes):
+        if not content:
+            return "<empty>"
+        text = content.decode("utf-8", errors="replace")
+    else:
+        text = content
+    if not text:
+        return "<empty>"
+    try:
+        parsed = json.loads(text)
+    except Exception:
+        return text
+    return _safe_json_text(parsed)
+
+
+def log_http_exchange(
+    logger: Any,
+    *,
+    method: str,
+    url: str,
+    request_headers: dict[str, Any] | None = None,
+    request_body: Any = None,
+    response_status: int | None = None,
+    response_headers: dict[str, Any] | None = None,
+    response_body: bytes | str | None = None,
+) -> None:
+    """Log a redacted HTTP exchange for TANGLE_VERBOSE diagnostics."""
+
+    emit = getattr(logger, "info", None)
+    if not callable(emit):
+        emit = lambda message: print(message, file=sys.stderr, flush=True)
+    emit(f"[tangle-api] request: {method} {url}")
+    emit(f"[tangle-api] request headers: {_safe_json_text(_redact_headers(request_headers))}")
+    if isinstance(request_body, (bytes, str)) or request_body is None:
+        request_body_text = _content_to_text(request_body)
+    else:
+        request_body_text = _safe_json_text(request_body)
+    emit(f"[tangle-api] request body: {request_body_text}")
+    if response_status is not None:
+        emit(f"[tangle-api] response status: {response_status}")
+    if response_headers is not None:
+        emit(f"[tangle-api] response headers: {_safe_json_text(_redact_headers(response_headers))}")
+    if response_body is not None:
+        emit(f"[tangle-api] response body: {_content_to_text(response_body)}")
+
+
+def default_base_url() -> str:
+    configured_url = os.environ.get("TANGLE_API_URL")
+    if configured_url:
+        return _normalize_base_url(configured_url)
+    if _ambient_auth_env_present():
+        raise SystemExit(
+            "TANGLE_API_URL is required when Tangle auth environment variables "
+            f"are set; refusing to send credentials to default {DEFAULT_API_URL}"
+        )
+    return _normalize_base_url(DEFAULT_API_URL)
+
+
+def _ambient_auth_env_present() -> bool:
+    return any(
+        os.environ.get(name)
+        for name in (
+            "TANGLE_API_AUTH_HEADER",
+            "TANGLE_AUTH_HEADER",
+            "TANGLE_API_HEADERS",
+            "TANGLE_API_TOKEN",
+        )
+    )
+
+
+def default_token() -> str | None:
+    return os.environ.get("TANGLE_API_TOKEN") or None
+
+
+def default_auth_header() -> str | None:
+    return os.environ.get("TANGLE_API_AUTH_HEADER") or os.environ.get("TANGLE_AUTH_HEADER") or None
+
+
+def _normalize_base_url(base_url: str) -> str:
+    base_url = base_url.strip().rstrip("/")
+    if base_url.endswith("/openapi.json"):
+        base_url = base_url[: -len("/openapi.json")]
+    return base_url.rstrip("/")
+
+
+def _openapi_url(base_url: str) -> str:
+    base_url = base_url.strip().rstrip("/")
+    if base_url.endswith("/openapi.json"):
+        return base_url
+    return urllib.parse.urljoin(base_url + "/", "openapi.json")
+
+
+def _request_headers(
+    token: str | None,
+    cli_header_entries: list[str] | str | None,
+    cli_auth_header: str | None,
+    extra_headers: dict[str, str] | None = None,
+    *,
+    include_env_credentials: bool = True,
+) -> dict[str, str]:
+    """Build request headers without printing or otherwise exposing secrets.
+
+    Precedence, lowest to highest:
+    default Accept header, ``TANGLE_API_HEADERS``, auth env vars,
+    bearer token, explicit auth header, CLI/header entries, explicit mapping.
+    """
+
+    headers = {"Accept": "application/json"}
+    if include_env_credentials:
+        headers.update(_headers_from_env())
+        env_auth_header = default_auth_header()
+        if env_auth_header:
+            headers["Authorization"] = _normalize_auth_header(
+                env_auth_header, "TANGLE_API_AUTH_HEADER"
+            )
+        token = token or default_token()
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    if cli_auth_header:
+        headers["Authorization"] = _normalize_auth_header(cli_auth_header, "--auth-header")
+    headers.update(_parse_header_entries(_header_entries(cli_header_entries), "--header"))
+    if extra_headers:
+        for name, value in extra_headers.items():
+            _validate_header(name, str(value), "headers")
+            headers[name] = str(value)
+    return headers
+
+
+def _normalize_auth_header(raw: str, source: str) -> str:
+    """Accept either an Authorization value or ``Authorization: value``."""
+
+    value = raw.strip()
+    if value.lower().startswith("authorization:"):
+        value = value.split(":", 1)[1].strip()
+    if not value or "\n" in value or "\r" in value:
+        raise SystemExit(f"Invalid {source}; expected an authorization header value")
+    return value
+
+
+def _headers_from_env() -> dict[str, str]:
+    raw = os.environ.get("TANGLE_API_HEADERS")
+    if not raw or not raw.strip():
+        return {}
+    return _parse_header_entries(_env_header_entries(raw), "TANGLE_API_HEADERS")
+
+
+def _env_header_entries(raw: str) -> list[str]:
+    """Parse env headers as JSON object/list or newline-separated entries."""
+
+    raw = raw.strip()
+    if raw[0] in "[{":
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise SystemExit("Invalid TANGLE_API_HEADERS JSON") from exc
+        if isinstance(parsed, dict):
+            return [f"{name}: {value}" for name, value in parsed.items()]
+        if isinstance(parsed, list) and all(isinstance(item, str) for item in parsed):
+            return parsed
+        raise SystemExit("TANGLE_API_HEADERS must be a JSON object or string list")
+    return [line.strip() for line in raw.splitlines() if line.strip()]
+
+
+def _header_entries(entries: list[str] | str | None) -> list[str]:
+    if entries is None:
+        return []
+    if isinstance(entries, str):
+        return [entries]
+    return list(entries)
+
+
+def _parse_header_entries(entries: list[str], source: str) -> dict[str, str]:
+    headers: dict[str, str] = {}
+    for entry in entries:
+        if ":" in entry:
+            name, value = entry.split(":", 1)
+        elif "=" in entry:
+            name, value = entry.split("=", 1)
+        else:
+            raise SystemExit(f"Invalid {source} entry; expected 'Name: value'")
+        name = name.strip()
+        value = value.strip()
+        _validate_header(name, value, source)
+        headers[name] = value
+    return headers
+
+
+def _validate_header(name: str, value: str, source: str) -> None:
+    if not name or not _HEADER_NAME_RE.fullmatch(name) or "\n" in value or "\r" in value:
+        raise SystemExit(f"Invalid {source} header name or value")
+
+
+def request_operation(
+    operation: Any,
+    values: dict[str, Any],
+    *,
+    base_url: str | None = None,
+    token: str | None = None,
+    auth_header: str | None = None,
+    header_entries: list[str] | str | None = None,
+    headers: dict[str, str] | None = None,
+    body: Any = _MISSING,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    allow_body_file_references: bool = False,
+    include_env_credentials: bool = True,
+) -> httpx.Response:
+    """Dispatch one normalized OpenAPI operation as an HTTP request.
+
+    ``values`` contains operation params using either generated Python names or
+    original OpenAPI names. The returned response has already had
+    ``raise_for_status()`` applied, matching the generated CLI behavior.
+    """
+
+    method, url, request_headers, content = build_operation_request(
+        operation,
+        values,
+        base_url=base_url,
+        token=token,
+        auth_header=auth_header,
+        header_entries=header_entries,
+        headers=headers,
+        body=body,
+        allow_body_file_references=allow_body_file_references,
+        include_env_credentials=include_env_credentials,
+    )
+    response = httpx.request(
+        method,
+        url,
+        content=content,
+        headers=request_headers,
+        timeout=timeout,
+    )
+    if tangle_verbose_enabled():
+        log_http_exchange(
+            None,
+            method=method,
+            url=url,
+            request_headers=request_headers,
+            request_body=content,
+            response_status=response.status_code,
+            response_headers=dict(response.headers),
+            response_body=response.text,
+        )
+    response.raise_for_status()
+    return response
+
+
+def build_operation_request(
+    operation: Any,
+    values: dict[str, Any],
+    *,
+    base_url: str | None = None,
+    token: str | None = None,
+    auth_header: str | None = None,
+    header_entries: list[str] | str | None = None,
+    headers: dict[str, str] | None = None,
+    body: Any = _MISSING,
+    allow_body_file_references: bool = False,
+    include_env_credentials: bool = True,
+) -> tuple[str, str, dict[str, str], bytes | None]:
+    """Build method, URL, headers, and body bytes for an operation."""
+
+    base_url = _normalize_base_url(base_url or default_base_url())
+    path = operation.path
+    query: dict[str, Any] = {}
+    body_fields: dict[str, Any] = {}
+    remaining = dict(values)
+
+    for parameter in operation.parameters:
+        if parameter.local_name in remaining:
+            value = remaining.pop(parameter.local_name)
+        elif parameter.original_name in remaining:
+            value = remaining.pop(parameter.original_name)
+        else:
+            if parameter.location == "path" and parameter.required:
+                raise TypeError(f"Missing required path parameter: {parameter.local_name}")
+            if parameter.location in {"query", "body"} and parameter.required:
+                # A required body field can also be satisfied by the generic body.
+                if parameter.location == "body" and body is not _MISSING and body is not None:
+                    continue
+                raise TypeError(f"Missing required parameter: {parameter.local_name}")
+            continue
+        if value is None:
+            continue
+        if parameter.location == "path":
+            path = path.replace(
+                "{" + parameter.original_name + "}",
+                urllib.parse.quote(str(value), safe=""),
+            )
+        elif parameter.location == "query":
+            query[parameter.original_name] = value
+        elif parameter.location == "body":
+            body_fields[parameter.original_name] = value
+
+    if remaining:
+        names = ", ".join(sorted(remaining))
+        raise TypeError(f"Unexpected parameter(s) for {operation.group_name}.{operation.command_name}: {names}")
+
+    url = _join_operation_url(base_url, path)
+    if query:
+        url = f"{url}?{_urlencode_query(query)}"
+
+    request_body = None
+    if operation.has_request_body:
+        if body is _MISSING:
+            body = None
+        request_body = (
+            _coerce_body_argument(
+                body, allow_file_references=allow_body_file_references
+            )
+            if body is not None
+            else None
+        )
+    if body_fields:
+        if request_body is None:
+            request_body = {}
+        if not isinstance(request_body, dict):
+            raise TypeError("body must be a JSON object when body field parameters are used")
+        request_body.update(body_fields)
+
+    request_headers = _request_headers(
+        token,
+        header_entries,
+        auth_header,
+        headers,
+        include_env_credentials=include_env_credentials,
+    )
+    content = _body_to_content(request_body)
+    if content is not None and "Content-Type" not in request_headers:
+        request_headers["Content-Type"] = "application/json"
+    return operation.method, url, request_headers, content
+
+
+def _join_operation_url(base_url: str, path: str) -> str:
+    """Join a schema path to ``base_url`` without allowing origin changes."""
+
+    parsed_path = urllib.parse.urlparse(path)
+    if parsed_path.scheme or parsed_path.netloc:
+        raise ValueError(f"OpenAPI operation path must be relative: {path!r}")
+    return urllib.parse.urljoin(base_url.rstrip("/") + "/", path.lstrip("/"))
+
+
+def _urlencode_query(query: dict[str, Any]) -> str:
+    """Encode query params, preserving repeated values for list options."""
+
+    items: list[tuple[str, Any]] = []
+    for key, value in query.items():
+        if isinstance(value, (list, tuple)):
+            items.extend((key, item) for item in value)
+        else:
+            items.append((key, value))
+    return urllib.parse.urlencode(items, doseq=True)
+
+
+def _load_body_argument(body: str) -> Any:
+    """Parse a CLI ``--body`` value; leading ``@`` reads JSON from a file."""
+
+    if body.startswith("@"):
+        body = Path(body[1:]).expanduser().read_text(encoding="utf-8")
+    try:
+        return json.loads(body)
+    except json.JSONDecodeError as exc:
+        raise SystemExit(f"Invalid JSON body: {exc}") from exc
+
+
+def _coerce_body_argument(body: Any, *, allow_file_references: bool = False) -> Any:
+    if not isinstance(body, str):
+        return body
+    if allow_file_references:
+        return _load_body_argument(body)
+    try:
+        return json.loads(body)
+    except json.JSONDecodeError:
+        return body
+
+
+def _body_to_content(request_body: Any) -> bytes | None:
+    if request_body is None:
+        return None
+    if isinstance(request_body, bytes):
+        return request_body
+    if isinstance(request_body, bytearray):
+        return bytes(request_body)
+    return json.dumps(request_body).encode("utf-8")

tangle_cli/args_container.py

@@ -0,0 +1,244 @@
+"""CLI argument resolution with optional YAML/JSON config files.
+
+This module provides generic config-file behavior shared by Tangle CLI
+commands: load one or more config objects, merge each with parsed CLI
+arguments, and keep explicit CLI values higher precedence than config values.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from enum import Enum
+from pathlib import Path
+from typing import Any, cast
+
+import yaml
+
+from tangle_cli.logger import Logger, get_default_logger
+from tangle_cli.utils import apply_defaults
+
+
+class ConfigFileError(Exception):
+    """Raised when there is an error loading or resolving a config file."""
+
+
+class ArgsContainer:
+    """Container for resolved CLI arguments with config-file defaults."""
+
+    def __init__(self, resolved: dict[str, Any], raw_config: dict[str, Any]):
+        self._config = raw_config
+        for key, value in resolved.items():
+            setattr(self, key, value)
+
+    def __getattr__(self, name: str) -> Any:
+        raise AttributeError(f"'{type(self).__name__}' has no attribute '{name}'")
+
+    def get(self, key: str, cli_value: Any = None, cli_default: Any = None) -> Any:
+        """Return a resolved value while preserving explicit CLI precedence."""
+
+        if cli_value != cli_default:
+            return cli_value
+        if key in self._config:
+            return self._config[key]
+        return cli_value
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return resolved public values as a dictionary."""
+
+        return {key: value for key, value in vars(self).items() if key != "_config"}
+
+    @staticmethod
+    def _load_config_file(
+        config_path: str | Path | None,
+        logger: Logger | None = None,
+    ) -> list[dict[str, Any]]:
+        """Load a YAML/JSON config file as a list of config dictionaries.
+
+        Supported shapes are a single object, a list of objects, or an object
+        with ``_defaults`` and ``configs`` where defaults are applied to each
+        config entry. Other top-level keys are ignored, which lets YAML files
+        use anchors/shared helper sections.
+        """
+
+        log = logger or get_default_logger()
+        if config_path is None:
+            return [{}]
+
+        path = Path(config_path)
+        if not path.exists():
+            raise ConfigFileError(f"Config file not found: {config_path}")
+
+        try:
+            with path.open(encoding="utf-8") as f:
+                if path.suffix in (".yaml", ".yml"):
+                    parsed = yaml.safe_load(f)
+                    if parsed is None:
+                        return [{}]
+                else:
+                    parsed = json.load(f)
+        except (OSError, json.JSONDecodeError, yaml.YAMLError) as exc:
+            raise ConfigFileError(f"Error loading config file: {exc}") from exc
+
+        if isinstance(parsed, dict):
+            parsed_dict = cast(dict[str, Any], parsed)
+            if "configs" in parsed_dict:
+                defaults = parsed_dict.get("_defaults", {})
+                configs_list = parsed_dict.get("configs", [])
+                if not isinstance(defaults, dict):
+                    raise ConfigFileError(
+                        f"_defaults must be an object, got {type(defaults).__name__}"
+                    )
+                if not isinstance(configs_list, list):
+                    raise ConfigFileError(
+                        f"configs must be a list, got {type(configs_list).__name__}"
+                    )
+                for index, item in enumerate(configs_list):
+                    if not isinstance(item, dict):
+                        raise ConfigFileError(
+                            "configs entry "
+                            f"{index} must be an object, got {type(item).__name__}"
+                        )
+                merged = apply_defaults(configs_list, defaults)
+                assert isinstance(merged, list)
+                log.info(f"Loaded config: {path} ({len(merged)} configs with defaults)")
+                return merged
+            log.info(f"Loaded config: {path} (1 config)")
+            return [parsed_dict]
+
+        if isinstance(parsed, list):
+            for index, item in enumerate(cast(list[Any], parsed)):
+                if not isinstance(item, dict):
+                    raise ConfigFileError(
+                        "Config file entry "
+                        f"{index} must be an object, got {type(item).__name__}"
+                    )
+            configs = cast(list[dict[str, Any]], parsed)
+            log.info(f"Loaded config: {path} ({len(configs)} configs)")
+            return configs
+
+        raise ConfigFileError(
+            "Config file must contain an object or list of objects, "
+            f"got {type(parsed).__name__}"
+        )
+
+    @staticmethod
+    def _make_json_converter(field_name: str) -> Callable[[Any], Any]:
+        """Create a converter that accepts parsed JSON or JSON text."""
+
+        def convert(value: Any) -> Any:
+            if value is None:
+                return None
+            if isinstance(value, (dict, list)):
+                return cast(Any, value)
+            if isinstance(value, str):
+                if value in ("", "{}", "[]", "null"):
+                    return None
+                try:
+                    return json.loads(value)
+                except json.JSONDecodeError as exc:
+                    raise ConfigFileError(f"Invalid JSON for {field_name}: {exc}") from exc
+            raise ConfigFileError(
+                f"{field_name} must be a dict, list, or JSON string, "
+                f"got {type(value).__name__}"
+            )
+
+        return convert
+
+    @staticmethod
+    def _make_enum_converter(field_name: str, enum_type: type[Enum]) -> Callable[[Any], Any]:
+        """Create a converter that accepts enum values by string."""
+
+        def convert(value: Any) -> Any:
+            if isinstance(value, str):
+                try:
+                    return enum_type(value)
+                except ValueError as exc:
+                    valid_values = [member.value for member in enum_type]
+                    raise ConfigFileError(
+                        f"Invalid value '{value}' for {field_name}. "
+                        f"Valid values: {valid_values}"
+                    ) from exc
+            return value
+
+        return convert
+
+    @staticmethod
+    def _resolve(config: dict[str, Any], **kwargs: Any) -> ArgsContainer:
+        """Resolve CLI args against a single config dict.
+
+        Field specs can be:
+        - ``(cli_value,)``: required field, config key is parameter name;
+        - ``(cli_value, default)``: optional field;
+        - ``(cli_value, default, converter)``: optional with converter;
+        - ``(config_key, cli_value, default, is_json)``: explicit key;
+        - ``(config_key, cli_value, default, is_json, required)``;
+        - ``(config_key, cli_value, default, is_json, required, converter)``.
+        """
+
+        resolved: dict[str, Any] = {}
+        required_fields: list[str] = []
+
+        for param_name, spec in kwargs.items():
+            converter = None
+            default_value = None
+            if len(spec) == 1:
+                (cli_value,) = spec
+                config_key = param_name
+                required_fields.append(param_name)
+            elif len(spec) == 2:
+                cli_value, default_value = spec
+                config_key = param_name
+            elif len(spec) == 3:
+                cli_value, default_value, converter = spec
+                config_key = param_name
+            elif len(spec) == 4:
+                config_key, cli_value, default_value, is_json = spec
+                if is_json:
+                    converter = ArgsContainer._make_json_converter(param_name)
+            elif len(spec) == 5:
+                config_key, cli_value, default_value, is_json, required = spec
+                if is_json:
+                    converter = ArgsContainer._make_json_converter(param_name)
+                if required:
+                    required_fields.append(param_name)
+            else:
+                config_key, cli_value, default_value, is_json, required, converter = spec
+                if is_json:
+                    converter = ArgsContainer._make_json_converter(param_name)
+                if required:
+                    required_fields.append(param_name)
+
+            if converter is None and isinstance(default_value, Enum):
+                converter = ArgsContainer._make_enum_converter(param_name, type(default_value))
+
+            if cli_value is not None and cli_value != default_value:
+                value = cli_value
+            elif config_key in config:
+                value = config[config_key]
+            else:
+                value = cli_value
+
+            resolved[param_name] = converter(value) if converter and value is not None else value
+
+        for field_name in required_fields:
+            if resolved.get(field_name) is None:
+                raise ConfigFileError(
+                    f"{field_name} is required (via CLI argument or config file)"
+                )
+
+        return ArgsContainer(resolved, config)
+
+    @staticmethod
+    def load(
+        config_path: str | Path | None,
+        logger: Logger | None = None,
+        **kwargs: Any,
+    ) -> list[ArgsContainer]:
+        """Load a config file and resolve CLI args against each config entry."""
+
+        configs = ArgsContainer._load_config_file(config_path, logger=logger)
+        return [ArgsContainer._resolve(config, **kwargs) for config in configs]
+
+
+__all__ = ["ArgsContainer", "ConfigFileError"]