oed-cli 0.2.0__py3-none-any.whl

oed_cli/dynamic.py

@@ -0,0 +1,473 @@
+"""Dynamic OpenAPI → operation-table mapping.
+
+Each operation in an openEuler-gateway OpenAPI doc lives under
+``spec.paths[path][verb]`` with an optional
+``x-apigateway-backend.httpEndpoints`` block describing the upstream
+backend (scheme/address/path/method). :func:`collect_operations` walks
+the spec and exposes each (path, verb) pair as a :class:`Operation` so
+the dispatcher can build URLs without hand-written client code.
+
+URL construction:
+
+The ``x-apigateway-backend.httpEndpoints.address`` field often points to
+a staging / test backend (e.g. ``cvesa.test.osinfra.cn``) that the
+gateway's CloudWAF blocks — even with browser-style headers. The
+production gateway at ``https://apig.osinfra.cn`` proxies every
+service reliably, so :mod:`oed_cli.invoke` always builds the runtime
+URL as ``RUNTIME_GATEWAY + spec.paths[key]``. The backend block is
+parsed for diagnostics (method, scheme) only and never trusted for the
+host.
+
+CLI surface:
+
+Each declared ``query`` / ``path`` parameter on an operation is exposed
+as its own ``--<kebab-case>`` flag by :func:`to_flag` / :func:`param_flag_index`,
+so users can run ``oed <service> <op> --cve-id CVE-2024-1234`` instead
+of stuffing JSON into ``--params``. The legacy ``--params '{...}'``
+form is preserved as an escape hatch and is overridden by per-param
+flags when both are present.
+
+The most common backend block we still see in specs:
+
+    "x-apigateway-backend": {
+        "type": "HTTP",
+        "httpEndpoints": {
+            "address": "software-pkg.openeuler.org",
+            "scheme":  "https",
+            "method":  "GET",
+            "path":    "/api/v1/cla",
+        }
+    }
+
+Specs that omit this block still work — we just lose the explicit
+method/scheme hints and fall back to ``GET``/``https``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .discovery import (
+    DEFAULT_GATEWAY,
+    ServiceMeta,
+    current_community,
+    fetch_discovery,
+)
+from .errors import NotFoundError, UserError
+from .http import request_json
+
+SPEC_CACHE_TTL_SECONDS = 600  # 10 min, mirrors the discovery feed TTL
+SPEC_URL_TEMPLATE = f"{DEFAULT_GATEWAY}/discovery/apis/{{community}}/{{service_name}}"
+
+# Runtime gateway — every dynamic call goes through here, regardless of
+# what ``x-apigateway-backend.httpEndpoints.address`` says. Specs often
+# point to staging hosts (``*.test.osinfra.cn``) whose CloudWAF blocks
+# browser-style traffic, so we route via the production gateway instead.
+RUNTIME_GATEWAY = "https://apig.osinfra.cn"
+
+_HTTP_VERBS = {"get", "post", "put", "patch", "delete", "head", "options"}
+
+# Flag-name derivation -------------------------------------------------- #
+
+
+def to_flag(name: str) -> str:
+    """Convert a spec parameter name to a kebab-case CLI flag stem.
+
+    Examples:
+        ``cveId``        → ``cve-id``
+        ``pageNum``      → ``page-num``
+        ``count_per_page`` → ``count-per-page``
+        ``id``           → ``id``
+    """
+
+    s = re.sub(r"(?<=[a-z0-9])(?=[A-Z])", "-", name)
+    s = s.replace("_", "-")
+    return s.lower()
+
+
+def param_flag_index(op: Operation) -> dict[str, dict[str, Any]]:
+    """Map CLI flag stems to declared query / path parameter defs.
+
+    Each declared parameter is registered twice — once under its
+    kebab-case stem (``--cve-id``) and once under the raw spec name
+    (``--cveId``) — so users can pick whichever form reads better.
+    """
+
+    out: dict[str, dict[str, Any]] = {}
+    for p in op.parameters:
+        if p.get("in") not in {"query", "path"}:
+            continue
+        out[to_flag(p["name"])] = p
+        out[p["name"]] = p
+    return out
+
+
+@dataclass(frozen=True)
+class Backend:
+    """The real upstream service backing one OpenAPI operation."""
+
+    scheme: str
+    address: str
+    path: str
+    method: str
+
+
+@dataclass(frozen=True)
+class Operation:
+    """One callable API operation, derived from a (path, verb) OpenAPI pair."""
+
+    service_name: str
+    path: str
+    http_method: str
+    backend: Backend
+    summary: str = ""
+    description: str = ""
+    parameters: tuple[dict[str, Any], ...] = field(default_factory=tuple)
+    body_required: bool = False
+    operation_id: str = ""
+
+    @classmethod
+    def from_openapi(
+        cls,
+        *,
+        service_name: str,
+        path: str,
+        verb: str,
+        op: dict[str, Any],
+        backend: Backend,
+    ) -> Operation:
+        return cls(
+            service_name=service_name,
+            path=path,
+            http_method=verb.upper(),
+            backend=backend,
+            summary=op.get("summary", ""),
+            description=op.get("description", ""),
+            parameters=tuple(op.get("parameters", []) or ()),
+            body_required=bool(op.get("requestBody", {}).get("required")),
+            operation_id=op.get("operationId") or f"{verb.upper()} {path}",
+        )
+
+    @property
+    def path_params(self) -> list[dict[str, Any]]:
+        return [p for p in self.parameters if p.get("in") == "path"]
+
+    @property
+    def query_params(self) -> list[dict[str, Any]]:
+        return [p for p in self.parameters if p.get("in") == "query"]
+
+    @property
+    def display_name(self) -> str:
+        """User-facing operation name. Strips the ``API_`` prefix that
+        Huawei APIG auto-appends to every operationId on services like
+        ``software-package-server`` — see ``operations_table`` for the
+        lookup alias that keeps the raw form working too."""
+
+        if self.operation_id.startswith("API_") and len(self.operation_id) > 4:
+            return self.operation_id[4:]
+        return self.operation_id
+
+
+def _parse_backend(op: dict[str, Any]) -> Backend | None:
+    """Return the :class:`Backend` for an operation, or ``None`` if not HTTP-typed."""
+
+    raw = op.get("x-apigateway-backend")
+    if not isinstance(raw, dict) or raw.get("type") != "HTTP":
+        return None
+    eps = raw.get("httpEndpoints") or {}
+    return Backend(
+        scheme=eps.get("scheme", "https"),
+        address=eps.get("address", ""),
+        path=eps.get("path", "/"),
+        method=(eps.get("method") or "GET").upper(),
+    )
+
+
+def collect_operations(spec: dict[str, Any], service_name: str) -> list[Operation]:
+    """Walk ``spec.paths`` and return every HTTP-typed operation."""
+
+    out: list[Operation] = []
+    paths = spec.get("paths") or {}
+    for path, item in paths.items():
+        if not isinstance(item, dict):
+            continue
+        for verb, op in item.items():
+            if verb.lower() not in _HTTP_VERBS or not isinstance(op, dict):
+                continue
+            backend = _parse_backend(op)
+            if backend is None:
+                continue
+            out.append(
+                Operation.from_openapi(
+                    service_name=service_name, path=path, verb=verb, op=op, backend=backend
+                )
+            )
+    return out
+
+
+def operations_table(spec: dict[str, Any], service_name: str) -> dict[str, Operation]:
+    """Build a name → :class:`Operation` lookup. Each operationId is the primary
+    key; secondary aliases are ``"<VERB> <path>"`` (e.g. ``"GET /v1/cla"``)
+    and — for specs whose operationIds carry an APIG-generated ``API_``
+    prefix — the prefix-stripped form (``API_listFoo`` → ``listFoo``)."""
+
+    table: dict[str, Operation] = {}
+    for op in collect_operations(spec, service_name):
+        primary = op.operation_id
+        table[primary] = op
+        table[f"{op.http_method} {op.path}"] = op
+        stripped = op.display_name
+        if stripped != primary and stripped not in table:
+            table[stripped] = op
+    return table
+
+
+def resolve_operation(table: dict[str, Operation], name: str) -> Operation:
+    """Look up an operation by ``name`` (case-insensitive), with helpful errors."""
+
+    if name in table:
+        return table[name]
+    lowered = name.lower()
+    for key, op in table.items():
+        if key.lower() == lowered:
+            return op
+    raise NotFoundError(
+        f"no operation matches '{name}'",
+        kind="method_not_found",
+        hint="Run `oed <service>` to list every operationId for this service.",
+    )
+
+
+def parse_json_arg(blob: str | None, *, flag: str) -> dict[str, Any] | None:
+    """Parse a JSON flag with a precise error pointing at the flag name."""
+
+    if blob is None or blob == "":
+        return None
+    try:
+        obj = json.loads(blob)
+    except json.JSONDecodeError as exc:
+        raise UserError(
+            f"--{flag} is not valid JSON: {exc.msg} (line {exc.lineno}, col {exc.colno})",
+            kind="invalid_json",
+        ) from exc
+    if not isinstance(obj, dict):
+        raise UserError(
+            f"--{flag} must decode to a JSON object, got {type(obj).__name__}",
+            kind="invalid_json",
+        )
+    return obj
+
+
+def coerce_param_types(op: Operation, params: dict[str, Any]) -> dict[str, Any]:
+    """Cast well-known string params to int/float based on the OpenAPI schema.
+
+    openEuler specs declare ``schema.type: integer`` for fields like
+    ``page_num``/``count_per_page``; many callers pass them as strings.
+    Without coercion the backend rejects them. We only convert ints the
+    spec actually declares, so we never mis-cast user data.
+    """
+
+    out: dict[str, Any] = {}
+    declared_ints = {
+        p["name"]
+        for p in op.parameters
+        if p.get("schema", {}).get("type") == "integer" and p.get("name") in params
+    }
+    declared_numbers = {
+        p["name"]
+        for p in op.parameters
+        if p.get("schema", {}).get("type") == "number" and p.get("name") in params
+    }
+    for k, v in params.items():
+        if k in declared_ints and isinstance(v, str) and v.lstrip("-").isdigit():
+            out[k] = int(v)
+        elif k in declared_numbers and isinstance(v, str):
+            try:
+                out[k] = float(v)
+            except ValueError:
+                out[k] = v
+        else:
+            out[k] = v
+    return out
+
+
+def coerce_flag_value(param_def: dict[str, Any], value: str) -> Any:
+    """Coerce one CLI string flag to the spec-declared type.
+
+    CLI flags arrive as strings (``--page-num 3`` → ``"3"``), but the
+    OpenAPI schema often declares ``integer``. Callers can also pass
+    already-typed values via ``--params '{...}'``; those bypass this
+    helper and go through :func:`coerce_param_types` instead.
+    """
+
+    schema_type = (param_def.get("schema") or {}).get("type", "string")
+    if schema_type == "integer":
+        stripped = value.lstrip("-")
+        if stripped.isdigit():
+            return int(value)
+        return value
+    if schema_type == "number":
+        try:
+            return float(value)
+        except ValueError:
+            return value
+    if schema_type == "boolean":
+        lowered = value.lower()
+        if lowered in {"true", "1", "yes", "on"}:
+            return True
+        if lowered in {"false", "0", "no", "off"}:
+            return False
+    return value
+
+
+# --------------------------------------------------------------------------- #
+# Local spec cache (per-service file, mirrors discovery.py layout)
+# --------------------------------------------------------------------------- #
+
+
+def _spec_cache_path(community: str, service_name: str) -> Path:
+    from .discovery import _cache_dir  # reuse the XDG resolver
+
+    return _cache_dir() / "specs" / community / f"{service_name}.json"
+
+
+def _read_spec_cache(path: Path) -> dict[str, Any] | None:
+    if not path.is_file():
+        return None
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    age = time.time() - float(raw.get("__oed_fetched_at", 0))
+    if age >= SPEC_CACHE_TTL_SECONDS:
+        return None
+    spec = raw.get("spec")
+    return spec if isinstance(spec, dict) else None
+
+
+def _write_spec_cache(path: Path, spec: dict[str, Any]) -> None:
+    payload = {
+        "__oed_fetched_at": time.time(),
+        "spec": spec,
+    }
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(payload, ensure_ascii=False), encoding="utf-8")
+    except OSError:
+        return  # best-effort
+
+
+def fetch_service_spec(
+    service: ServiceMeta, *, force_refresh: bool = False
+) -> dict[str, Any]:
+    """Load one service's OpenAPI, using a file cache when fresh."""
+
+    if not force_refresh:
+        cached = _read_spec_cache(_spec_cache_path(service.community, service.service_name))
+        if cached is not None:
+            return cached
+
+    url = SPEC_URL_TEMPLATE.format(community=service.community, service_name=service.service_name)
+    spec = request_json("GET", url)
+    if not isinstance(spec, dict) or "openapi" not in spec:
+        raise NotFoundError(
+            f"GET {url} did not return an OpenAPI document",
+            kind="spec_missing",
+            hint="The discovery feed lists this service but its OpenAPI spec is not available.",
+        )
+    _write_spec_cache(_spec_cache_path(service.community, service.service_name), spec)
+    return spec
+
+
+def resolve_service(community: str | None = None, force_refresh: bool = False) -> ServiceMeta:
+    """Find the service named by the ``OED_SERVICE`` env var (used in tests).
+
+    Real CLI dispatch uses :func:`resolve_service_by_name`. This helper exists
+    so that scripts / tests can still drive ``invoke.call_operation`` without
+    going through the full dispatch table.
+    """
+
+    name = os.environ.get("OED_SERVICE")
+    if not name:
+        raise UserError(
+            "OED_SERVICE env var is not set; pass service_name explicitly.",
+            kind="missing_service",
+        )
+    return resolve_service_by_name(name, community=community, force_refresh=force_refresh)
+
+
+def resolve_service_by_name(
+    service_name: str,
+    *,
+    community: str | None = None,
+    force_refresh: bool = False,
+) -> ServiceMeta:
+    """Locate a :class:`ServiceMeta` by ``service_name`` in the given/active community."""
+
+    feed = fetch_discovery(force_refresh=force_refresh)
+    target_community = community or current_community()
+    matches = [s for s in feed.services if s.service_name == service_name]
+    if not matches:
+        other = sorted({s.community for s in feed.services})
+        raise NotFoundError(
+            f"service '{service_name}' is not registered",
+            kind="service_not_found",
+            hint=(
+                f"Available communities: {other}. "
+                "Run `oed services` to list registered services."
+            ),
+        )
+    if len(matches) == 1:
+        return matches[0]
+    for s in matches:
+        if s.community == target_community:
+            return s
+    other_communities = sorted({s.community for s in matches})
+    raise UserError(
+        f"service '{service_name}' is registered in multiple communities {other_communities}; "
+        f"set OED_COMMUNITY to pick one (current: {target_community}).",
+        kind="ambiguous_service",
+    )
+
+
+def operations_for(
+    service_name: str,
+    *,
+    community: str | None = None,
+    force_refresh: bool = False,
+) -> tuple[ServiceMeta, dict[str, Operation], dict[str, Any]]:
+    """One-shot helper: resolve a service, fetch its spec, build the table.
+
+    Returns ``(service_meta, operations_table, raw_spec)`` so callers can
+    inspect both the structured view and the raw OpenAPI doc.
+    """
+
+    service = resolve_service_by_name(
+        service_name, community=community, force_refresh=force_refresh
+    )
+    spec = fetch_service_spec(service, force_refresh=force_refresh)
+    return service, operations_table(spec, service.service_name), spec
+
+
+__all__ = [
+    "Backend",
+    "Operation",
+    "RUNTIME_GATEWAY",
+    "collect_operations",
+    "coerce_flag_value",
+    "coerce_param_types",
+    "fetch_service_spec",
+    "operations_for",
+    "operations_table",
+    "param_flag_index",
+    "parse_json_arg",
+    "resolve_operation",
+    "resolve_service_by_name",
+    "to_flag",
+]

oed_cli/errors.py

@@ -0,0 +1,45 @@
+"""Exit codes and exception hierarchy for ``oed``."""
+
+from __future__ import annotations
+
+
+class ExitCode:
+    OK = 0
+    USER_ERROR = 1
+    NETWORK_ERROR = 2
+    UPSTREAM_ERROR = 3
+    NOT_FOUND = 4
+
+
+class OedError(Exception):
+    """Base for all ``oed`` runtime errors."""
+
+    code: int = ExitCode.USER_ERROR
+
+    def __init__(self, message: str, *, kind: str | None = None, hint: str | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.kind = kind or self.__class__.__name__
+        self.hint = hint
+
+    def to_dict(self) -> dict:
+        d: dict = {"ok": False, "code": self.code, "error": self.kind, "message": self.message}
+        if self.hint:
+            d["hint"] = self.hint
+        return d
+
+
+class UserError(OedError):
+    code = ExitCode.USER_ERROR
+
+
+class NetworkError(OedError):
+    code = ExitCode.NETWORK_ERROR
+
+
+class UpstreamError(OedError):
+    code = ExitCode.UPSTREAM_ERROR
+
+
+class NotFoundError(OedError):
+    code = ExitCode.NOT_FOUND

oed_cli/http.py

@@ -0,0 +1,150 @@
+"""WAF-safe HTTP client for the openEuler Infra gateway.
+
+The gateway sits behind a CloudWAF that returns a Chinese-language HTML block
+page when the request lacks browser-style headers (see ``context/discoverAPI.md``
+section "注意事项 & 已知限制"). This module bakes those headers in so every call
+made by ``oed`` succeeds without users tweaking curl flags.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from . import __version__
+from .errors import NetworkError, NotFoundError, UpstreamError
+
+DEFAULT_GATEWAY = "https://api-gateway.osinfra.cn"
+_TIMEOUT_SECONDS = 30.0
+
+
+def _headers(extra: dict[str, str] | None = None) -> dict[str, str]:
+    h = {
+        "User-Agent": f"oed/{__version__} (+https://gitee.com/openeuler/oed-cli)",
+        "Accept": "application/json, text/plain, */*",
+        "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
+        "Referer": f"{DEFAULT_GATEWAY}/",
+    }
+    if extra:
+        h.update(extra)
+    return h
+
+
+def _is_waf_block(html: str) -> bool:
+    lowered = html[:512].lower()
+    return (
+        "<!doctype html" in lowered
+        and ("cloudwaf" in lowered or "访问被拦截" in html or "requestid" in lowered)
+    )
+
+
+def get_json(url: str, *, params: dict | None = None, headers: dict | None = None) -> Any:
+    """GET ``url`` and return parsed JSON.
+
+    Raises:
+
+      - :class:`NetworkError` (exit 2) for connectivity / WAF failures
+      - :class:`UpstreamError` (exit 3) for genuine 5xx / unexpected payloads
+      - :class:`NotFoundError` (exit 4) when the upstream reports an empty spec
+    """
+
+    return _decode(get_request("GET", url, params=params, headers=headers), spec_endpoint=True)
+
+
+def get_request(
+    method: str,
+    url: str,
+    *,
+    params: dict | None = None,
+    body: Any = None,
+    headers: dict | None = None,
+    timeout: float = _TIMEOUT_SECONDS,
+) -> httpx.Response:
+    """Run an arbitrary HTTP request and return the raw :class:`httpx.Response`.
+
+    Adds the WAF-safe browser headers; auto-declares ``Content-Type: application/json``
+    when ``body`` is set and the caller has not overridden it. Surfaces
+    connectivity failures as :class:`NetworkError`; WAF blocks as
+    :class:`NetworkError` (kind ``waf_block``); 5xx as :class:`UpstreamError`.
+    """
+
+    method = method.upper()
+    extra = dict(headers or {})
+    if body is not None and not any(h.lower() == "content-type" for h in extra):
+        extra["Content-Type"] = "application/json"
+
+    try:
+        with httpx.Client(timeout=timeout, follow_redirects=True) as client:
+            return client.request(
+                method,
+                url,
+                params=params if params else None,
+                json=body if body is not None else None,
+                headers=_headers(extra),
+            )
+    except httpx.HTTPError as exc:
+        raise NetworkError(f"{method} {url} failed: {exc}", kind="network_error") from exc
+
+
+def _decode(
+    resp: httpx.Response,
+    *,
+    spec_endpoint: bool = False,
+) -> Any:
+    """Validate ``resp`` and return parsed JSON.
+
+    ``spec_endpoint=True`` treats an empty body as :class:`NotFoundError`
+    (used for spec discovery). For runtime service calls an empty body is
+    considered a successful empty payload (``null``).
+    """
+
+    if resp.status_code >= 500:
+        raise UpstreamError(
+            f"{resp.request.method} {resp.url} returned {resp.status_code}",
+            kind="upstream_error",
+            hint="Check gateway status; retry shortly.",
+        )
+
+    if _is_waf_block(resp.text):
+        raise NetworkError(
+            f"Gateway WAF blocked the request to {resp.url}",
+            kind="waf_block",
+            hint="This is unexpected — file an issue with the URL you tried.",
+        )
+
+    if not resp.content:
+        if spec_endpoint:
+            raise NotFoundError(
+                f"{resp.request.method} {resp.url} "
+                f"returned an empty body (HTTP {resp.status_code})",
+                kind="spec_missing",
+                hint=(
+                    "The discovery feed lists this service but its OpenAPI "
+                    "spec has not been published yet."
+                ),
+            )
+        return None
+
+    try:
+        return resp.json()
+    except Exception as exc:
+        raise UpstreamError(
+            f"{resp.request.method} {resp.url} returned non-JSON body (HTTP {resp.status_code})",
+            kind="upstream_error",
+        ) from exc
+
+
+def request_json(
+    method: str,
+    url: str,
+    *,
+    params: dict | None = None,
+    body: Any = None,
+    headers: dict | None = None,
+    timeout: float = _TIMEOUT_SECONDS,
+) -> Any:
+    """Run a request and return parsed JSON (empty body → ``None``)."""
+
+    resp = get_request(method, url, params=params, body=body, headers=headers, timeout=timeout)
+    return _decode(resp)