oed-cli 0.2.0__py3-none-any.whl

oed_cli/invoke.py

@@ -0,0 +1,305 @@
+"""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. We always build the
+runtime URL as ``RUNTIME_GATEWAY + op.path``, where ``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 RUNTIME_GATEWAY, Operation, coerce_param_types, to_flag
+from .errors import NetworkError, UserError
+from .http import _is_waf_block
+
+
+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,
+) -> 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.
+    """
+
+    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"{RUNTIME_GATEWAY}{filled_path}"
+
+    request_view: dict[str, Any] = {
+        "method": op.backend.method,
+        "url": url,
+        "query": query_params,
+        "headers": {"Content-Type": "application/json"} if body is not None else {},
+        "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,
+    )
+
+    if _is_waf_block(resp.text):
+        raise NetworkError(
+            f"Backend WAF blocked {op.backend.method} {url}",
+            kind="waf_block",
+            hint="Try OED_EXTRA_HEADERS_JSON env var to send custom headers.",
+        )
+
+    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"{RUNTIME_GATEWAY}{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"{RUNTIME_GATEWAY}{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",
+]