oed-cli 0.1.0__py3-none-any.whl

oed_cli/http.py

@@ -0,0 +1,187 @@
+"""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.
+
+Note on ``Referer``: openEuler APIG rejects requests that carry a
+``Referer: https://api-gateway.osinfra.cn/`` header with HTTP 401 on at
+least one production path (``easysearch`` / ``sigsearch/docs``). The
+``/discovery/apis`` feed does not need Referer to pass the CloudWAF
+either — empirically verified 2026-07-28. So ``_headers()`` does NOT
+emit a default Referer. Callers can still pass one explicitly via the
+``headers=`` argument to :func:`get_request` if a future endpoint
+demands it.
+"""
+
+from __future__ import annotations
+
+import os
+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
+DEFAULT_USER_AGENT = f"oed/{__version__} (+https://atomgit.com/openeuler/oed-cli)"
+
+
+def _resolve_user_agent(user_agent: str | None) -> str:
+    """Resolve the User-Agent: explicit arg > ``OED_USER_AGENT`` env > default.
+
+    An empty string falls through to the next source — passing ``--user-agent ""``
+    is treated the same as not passing it.
+    """
+
+    if user_agent:
+        return user_agent
+    env = os.environ.get("OED_USER_AGENT")
+    if env:
+        return env
+    return DEFAULT_USER_AGENT
+
+
+def _headers(
+    extra: dict[str, str] | None = None, *, user_agent: str | None = None
+) -> dict[str, str]:
+    h = {
+        "User-Agent": _resolve_user_agent(user_agent),
+        "Accept": "application/json, text/plain, */*",
+        "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
+    }
+    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,
+    user_agent: str | None = None,
+) -> 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`.
+
+    ``user_agent`` overrides the default User-Agent header — useful when a
+    specific APIG backend's WAF rejects the default ``oed/x.y.z`` UA with a
+    misleading 401 (e.g. ``easysearch``). Falls back to ``OED_USER_AGENT`` env,
+    then the bundled default.
+    """
+
+    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, user_agent=user_agent),
+            )
+    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=(
+                "Some APIG backends reject the bundled oed/x.y.z User-Agent. "
+                "Retry with `--user-agent 'Mozilla/5.0 ...'` or set "
+                "OED_USER_AGENT in the environment."
+            ),
+        )
+
+    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)

oed_cli/invoke.py

@@ -0,0 +1,319 @@
+"""Run a real :class:`Operation` against its backend.
+
+This module is what the CLI dispatches to when a user runs
+``oed <service> <method> --params ... --json ...``. It fills path/query
+params on the OpenAPI ``paths`` template, attaches the JSON body, and
+sends the request through the production gateway via
+``oed_cli.http.get_request``.
+
+URL construction note: the spec's ``x-apigateway-backend.httpEndpoints``
+block is parsed for ``method`` / ``scheme`` but **not** trusted for the
+host — those ``address`` values are routinely staging hosts
+(``*.test.osinfra.cn``) that CloudWAF blocks. The runtime URL is built
+as ``op.base_url + op.path``, where ``op.base_url`` was filled in by
+:func:`oed_cli.dynamic.resolve_runtime_gateway` from the discovery feed
+(``ServiceMeta.base_url``). ``op.path`` is the OpenAPI ``paths`` key
+(e.g. ``/cve-security-notice-server/securitynotice/getByCveId``).
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+from typing import Any
+
+import httpx
+
+from . import http as http_mod
+from .dynamic import Operation, coerce_param_types, to_flag
+from .errors import NetworkError, UserError
+from .http import _is_waf_block, _resolve_user_agent
+
+
+def _fill_path(template: str, params: dict[str, Any]) -> tuple[str, list[str]]:
+    """Substitute ``{name}`` placeholders in ``template`` from ``params``.
+
+    Returns the rendered path and the list of placeholder names that were
+    not provided, so the caller can raise a precise error.
+    """
+
+    missing: list[str] = []
+    parts: list[str] = []
+    rest = template
+    while True:
+        head, sep, chunk = rest.partition("{")
+        if not sep:
+            parts.append(head)
+            break
+        name_end = chunk.find("}")
+        if name_end == -1:
+            parts.append(head + sep + chunk)
+            break
+        name = chunk[:name_end]
+        parts.append(head)
+        if name in params:
+            parts.append(str(params[name]))
+        else:
+            missing.append(name)
+            parts.append("{" + name + "}")
+        rest = chunk[name_end + 1 :]
+    return "".join(parts), missing
+
+
+def _select_params(
+    op: Operation, raw: dict[str, Any] | None
+) -> tuple[dict, dict, list[str]]:
+    """Split ``raw`` into (path_params, query_params, unused_keys)."""
+
+    raw = raw or {}
+    path_names = {p["name"] for p in op.path_params}
+    query_names = {p.get("name") for p in op.query_params}
+    declared = path_names | query_names
+
+    path_params = {k: raw[k] for k in path_names if k in raw}
+    query_params = {k: raw[k] for k in raw if k in query_names and k not in path_params}
+    unused = sorted(k for k in raw if k not in declared)
+    return path_params, query_params, unused
+
+
+def _render_response(resp: httpx.Response) -> Any:
+    """Parse the JSON body of ``resp``, returning a wrapped string for non-JSON."""
+
+    if not resp.content:
+        return None
+    try:
+        return resp.json()
+    except Exception:
+        return {
+            "_non_json_body": resp.text[:8192],
+            "_content_type": resp.headers.get("content-type", ""),
+        }
+
+
+def call_operation(
+    op: Operation,
+    *,
+    params: dict[str, Any] | None = None,
+    body: Any = None,
+    dry_run: bool = False,
+    timeout: float = 30.0,
+    include_request: bool = False,
+    user_agent: str | None = None,
+) -> dict[str, Any]:
+    """Invoke ``op`` and return a structured JSON dict suitable for stdout.
+
+    ``ok`` is ``True`` for any 2xx/3xx response. Non-success still surfaces
+    the body and status under ``response`` / ``status``; the caller is
+    responsible for the exit code.
+
+    ``user_agent`` overrides the default User-Agent header; falls back to
+    ``OED_USER_AGENT`` env, then the bundled default.
+    """
+
+    path_params, query_params, unused = _select_params(op, params)
+    query_params = coerce_param_types(op, query_params)
+
+    filled_path, missing = _fill_path(op.path, path_params)
+    if missing:
+        raise UserError(
+            f"missing path params: {missing}",
+            kind="missing_path_param",
+            hint=f"Provide them via --params: {', '.join(missing)}",
+        )
+
+    query_params = {k: v for k, v in query_params.items() if v is not None}
+    url = f"{op.base_url}{filled_path}"
+
+    request_headers: dict[str, str] = {"User-Agent": _resolve_user_agent(user_agent)}
+    if body is not None:
+        request_headers["Content-Type"] = "application/json"
+    request_view: dict[str, Any] = {
+        "method": op.backend.method,
+        "url": url,
+        "query": query_params,
+        "headers": request_headers,
+        "body": body,
+    }
+
+    if dry_run:
+        out = {
+            "ok": True,
+            "dry_run": True,
+            "service": op.service_name,
+            "operation": op.display_name,
+            "method": op.backend.method,
+            "url": url,
+            "request": request_view,
+            "note": "request was not sent.",
+        }
+        if op.display_name != op.operation_id:
+            out["operation_id_raw"] = op.operation_id
+        return out
+
+    resp = http_mod.get_request(
+        op.backend.method,
+        url,
+        params=query_params if query_params else None,
+        body=body,
+        timeout=timeout,
+        user_agent=user_agent,
+    )
+
+    if _is_waf_block(resp.text):
+        raise NetworkError(
+            f"Backend WAF blocked {op.backend.method} {url}",
+            kind="waf_block",
+            hint=(
+                "Some APIG backends reject the bundled oed/x.y.z User-Agent. "
+                "Retry with `--user-agent 'Mozilla/5.0 ...'` or set "
+                "OED_USER_AGENT in the environment."
+            ),
+        )
+
+    out = {
+        "ok": 200 <= resp.status_code < 400,
+        "service": op.service_name,
+        "operation": op.display_name,
+        "method": op.backend.method,
+        "url": url,
+        "status": resp.status_code,
+        "response": _render_response(resp),
+    }
+    if include_request:
+        out["request"] = request_view
+    if op.display_name != op.operation_id:
+        out["operation_id_raw"] = op.operation_id
+    if unused:
+        out["unused_params"] = unused
+    return out
+
+
+def describe_operation(op: Operation) -> dict[str, Any]:
+    """Render a single :class:`Operation` for ``oed <service>`` listing."""
+
+    rendered, _missing = _fill_path(op.path, {})
+    out: dict[str, Any] = {
+        "operation_id": op.display_name,
+        "method": op.http_method,
+        "path": op.path,
+        "url": f"{op.base_url}{rendered}",
+        "backend_declared": (
+            f"{op.backend.scheme}://{op.backend.address}{op.backend.path}"
+            if op.backend.address
+            else None
+        ),
+        "summary": op.summary,
+        "description": op.description,
+        "path_params": [p["name"] for p in op.path_params],
+        "query_params": [p["name"] for p in op.query_params],
+        "body_required": op.body_required,
+    }
+    if op.display_name != op.operation_id:
+        out["operation_id_raw"] = op.operation_id
+    return out
+
+
+def describe_service(service, ops: list) -> dict[str, Any]:
+    """Bundle service metadata + operations into one JSON document."""
+
+    return {
+        "service": {
+            "name": service.name,
+            "service_name": service.service_name,
+            "community": service.community,
+            "title": service.title,
+            "version": service.version,
+            "base_url": service.base_url,
+        },
+        "operations": [describe_operation(op) for op in ops],
+        "generated_at": _dt.datetime.now(_dt.timezone.utc).isoformat(),
+    }
+
+
+def describe_operation_help(op: Operation, service) -> dict[str, Any]:
+    """Render ``oed <service> <operation> --help``: every per-parameter flag
+    plus a copy-pasteable usage example."""
+
+    rendered, _missing = _fill_path(op.path, {})
+    params: list[dict[str, Any]] = []
+    for p in op.parameters:
+        if p.get("in") not in {"query", "path"}:
+            continue
+        flag_stem = to_flag(p["name"])
+        schema = p.get("schema") or {}
+        entry: dict[str, Any] = {
+            "name": p["name"],
+            "in": p["in"],
+            "required": bool(p.get("required")),
+            "flag": f"--{flag_stem}",
+            "alt_flag": f"--{p['name']}",
+            "type": schema.get("type", "string"),
+        }
+        if p.get("description"):
+            entry["description"] = p["description"]
+        params.append(entry)
+
+    name = op.display_name
+    out: dict[str, Any] = {
+        "ok": True,
+        "help_for": name,
+        "service": {
+            "name": service.name,
+            "service_name": service.service_name,
+            "title": service.title,
+        },
+        "method": op.http_method,
+        "path": op.path,
+        "url": f"{op.base_url}{rendered}",
+        "summary": op.summary,
+        "description": op.description,
+        "body_required": op.body_required,
+        "parameters": params,
+        "usage": _usage_example(op),
+        "examples": _usage_examples(op),
+    }
+    if name != op.operation_id:
+        out["operation_id_raw"] = op.operation_id
+    return out
+
+
+def _usage_example(op: Operation) -> str:
+    """Single-line copy-pasteable invocation string."""
+
+    parts = [f"oed <service> {op.display_name}"]
+    for p in op.parameters:
+        if p.get("in") not in {"query", "path"}:
+            continue
+        flag = f"--{to_flag(p['name'])} <value>"
+        parts.append(flag if p.get("required") else f"[{flag}]")
+    if op.body_required:
+        parts.append("--json '{...}'")
+    parts.append("[--dry-run]")
+    return " ".join(parts)
+
+
+def _usage_examples(op: Operation) -> list[str]:
+    """A couple of ready-to-paste example commands."""
+
+    name = op.display_name
+    examples: list[str] = []
+    required = [
+        p
+        for p in op.parameters
+        if p.get("in") in {"query", "path"} and p.get("required")
+    ]
+
+    if required:
+        cmd = f"oed <service> {name}"
+        cmd += "".join(f" --{to_flag(p['name'])} <value>" for p in required)
+        cmd += " [--dry-run]"
+        examples.append(cmd)
+    examples.append(f"oed <service> {name} --params '{name}_PARAMS_JSON'")
+    return examples
+
+
+__all__ = [
+    "call_operation",
+    "describe_operation",
+    "describe_operation_help",
+    "describe_service",
+]