vcf-super-cli 0.2.0__py3-none-any.whl

vsc/gen/discover.py

@@ -0,0 +1,221 @@
+"""Enumerate vAPI service classes and their operations, fully offline.
+
+Every service is a ``VapiInterface`` subclass; instantiating it with a
+``StubConfiguration`` built on a no-op connector populates the generated
+``_<Name>Stub`` (``service._api_interface``) whose ``_operations`` and
+``_rest_metadata`` dicts carry everything we need — no server required.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+import structlog
+from vmware.vapi.bindings.stub import StubConfiguration
+from vmware.vapi.protocol.client.connector import Connector
+
+from vsc.gen.model import Operation
+from vsc.gen.params import param_from_type
+
+log = structlog.get_logger(__name__)
+
+# Canonical read verbs; anything else keeps its operation id as the command name.
+_KNOWN_VERBS = frozenset({"get", "list", "create", "delete", "update"})
+
+# Mutating HTTP method -> base CLI verb. ``force`` variants are prefixed so they
+# stay distinct from their non-force siblings within a service group.
+_METHOD_VERB = {"PUT": "set", "PATCH": "patch", "DELETE": "delete"}
+
+
+class _OfflineConnector(Connector):  # type: ignore[misc]
+    """A connector with no API provider — enough to read embedded metadata."""
+
+    def __init__(self) -> None:
+        super().__init__(api_provider=None, provider_filter_chain=[])
+
+    def connect(self) -> None:  # pragma: no cover - never called offline
+        pass
+
+    def disconnect(self) -> None:  # pragma: no cover - never called offline
+        pass
+
+
+def introspect_stub(service_cls: type) -> Any:
+    """Return the generated ``_<Name>Stub`` (ApiInterfaceStub) for a service."""
+    service = service_cls(StubConfiguration(_OfflineConnector()))
+    return service._api_interface
+
+
+def _action_from_url(url_template: str) -> str | None:
+    """Return the ``?action=<value>`` verb from a REST URL template, if present."""
+    if "?" not in url_template:
+        return None
+    query = url_template.split("?", 1)[1]
+    for part in query.split("&"):
+        key, _, value = part.partition("=")
+        if key == "action" and value:
+            return value
+    return None
+
+
+def _cli_verb(op_id: str, http_method: str, url_template: str = "") -> str:
+    if op_id in _KNOWN_VERBS:
+        return op_id
+    low = op_id.lower()
+    # Reads: keep v0.1 behaviour exactly (these branches run before any write logic).
+    if "list" in low:
+        return "list"
+    if low.startswith("read") or "_read_" in low or "{" in low:
+        return "get"
+    if http_method == "GET":
+        return "get"
+    # Writes: prefer an explicit ``?action=`` verb, then the HTTP method, keeping
+    # ``force`` variants distinct. POST without an action falls back to its op id.
+    action = _action_from_url(url_template)
+    if action is not None:
+        return action.replace("_", "-")
+    base = _METHOD_VERB.get(http_method)
+    if base is not None:
+        return f"force-{base}" if "force" in low else base
+    return op_id.replace("$", "-").replace("_", "-")
+
+
+def discover_operations(
+    service_cls: type, backend: str, *, read_only: bool = False
+) -> list[Operation]:
+    """Introspect ``service_cls`` into a list of :class:`Operation`.
+
+    With ``read_only=True`` only ``GET`` operations are emitted (the v0.1 surface);
+    the v0.2 default emits writes as well.
+    """
+    stub = introspect_stub(service_cls)
+    iface_id = stub._iface_id.get_name()
+    operations: dict[str, dict[str, Any]] = stub._operations
+    rest_metadata: dict[str, Any] = stub._rest_metadata
+
+    ops: list[Operation] = []
+    for op_id in sorted(set(operations) & set(rest_metadata)):
+        rest = rest_metadata[op_id]
+        http_method = rest.http_method
+        if read_only and http_method != "GET":
+            continue
+        input_type = operations[op_id]["input_type"]
+        path_vars = tuple(rest.get_path_variable_field_names())
+        # field name -> URL template variable (the two differ, e.g.
+        # 'resource_pool' -> 'resource-pool', 'segment_id' -> 'segmentId').
+        path_var_map = dict(getattr(rest, "_path_variables", None) or {})
+        query_vars = frozenset(rest.get_query_parameter_field_names())
+        body_param = rest.request_body_parameter
+        params = [
+            param_from_type(
+                fname,
+                input_type.get_field(fname),
+                path_vars=path_vars,
+                query_vars=query_vars,
+                body_param=body_param,
+            )
+            for fname in input_type.get_field_names()
+        ]
+        ops.append(
+            Operation(
+                backend=backend,
+                service_cls=service_cls,
+                iface_id=iface_id,
+                op_id=op_id,
+                method_name=op_id,
+                cli_verb=_cli_verb(op_id, http_method, rest._url_template),
+                http_method=http_method,
+                url_template=rest._url_template,
+                path_vars=list(path_vars),
+                path_var_map=path_var_map,
+                params=params,
+                output_type=operations[op_id].get("output_type"),
+                error_types=operations[op_id].get("errors", []),
+            )
+        )
+    return ops
+
+
+# --------------------------------------------------------------------------- #
+# Curated service catalogs (read + write surface)
+# --------------------------------------------------------------------------- #
+
+
+def _load_services(backend: str, specs: tuple[tuple[str, tuple[str, ...]], ...]) -> list[type]:
+    """Resolve ``(module, names)`` specs into classes, skipping any that moved.
+
+    A missing module or symbol is logged and skipped so one relocated class can
+    never break a whole backend's command surface.
+    """
+    services: list[type] = []
+    for module_path, names in specs:
+        try:
+            module = importlib.import_module(module_path)
+        except ImportError as exc:
+            log.warning(
+                "service.module_import_failed", backend=backend, module=module_path, error=str(exc)
+            )
+            continue
+        for name in names:
+            cls = getattr(module, name, None)
+            if cls is None:
+                log.warning("service.missing", backend=backend, module=module_path, name=name)
+                continue
+            services.append(cls)
+    return services
+
+
+# vCenter services. Core inventory lives in ``vcenter_client``; v0.2 adds VM power,
+# VM hardware (cpu/memory/disk/ethernet) and resource pools for the write surface.
+_VSPHERE_SERVICE_SPECS: tuple[tuple[str, tuple[str, ...]], ...] = (
+    (
+        "com.vmware.vcenter_client",
+        ("VM", "Host", "Cluster", "Datacenter", "Datastore", "Folder", "Network", "ResourcePool"),
+    ),
+    ("com.vmware.vcenter.vm_client", ("Power",)),
+    ("com.vmware.vcenter.vm.hardware_client", ("Cpu", "Memory", "Disk", "Ethernet")),
+)
+
+
+def vsphere_services() -> list[type]:
+    """vCenter service classes exposed under ``vsc vsphere``."""
+    return _load_services("vsphere", _VSPHERE_SERVICE_SPECS)
+
+
+# NSX Policy services. Imported defensively so a single moved symbol cannot break
+# the whole NSX surface. v0.2 adds IP pools, DHCP configs and Tier-1 locale services.
+_NSX_SERVICE_SPECS: tuple[tuple[str, tuple[str, ...]], ...] = (
+    (
+        "vcf.nsx.policy.api.v1.infra_client",
+        (
+            "Segments",
+            "Tier0s",
+            "Tier1s",
+            "Services",
+            "IpPools",
+            "DhcpServerConfigs",
+            "DhcpRelayConfigs",
+        ),
+    ),
+    (
+        "vcf.nsx.policy.api.v1.infra.domains_client",
+        ("Groups", "SecurityPolicies", "GatewayPolicies"),
+    ),
+    ("vcf.nsx.policy.api.v1.infra.tier_1s_client", ("LocaleServices",)),
+)
+
+
+def nsx_services() -> list[type]:
+    """NSX Policy service classes exposed under ``vsc nsx``."""
+    return _load_services("nsx", _NSX_SERVICE_SPECS)
+
+
+def discover_all(*, read_only: bool = False) -> list[Operation]:
+    """Discover every operation across both backends (writes included by default)."""
+    ops: list[Operation] = []
+    for cls in vsphere_services():
+        ops.extend(discover_operations(cls, "vsphere", read_only=read_only))
+    for cls in nsx_services():
+        ops.extend(discover_operations(cls, "nsx", read_only=read_only))
+    return ops

vsc/gen/model.py

@@ -0,0 +1,104 @@
+"""Introspected command model: :class:`Operation` and :class:`Param`.
+
+These dataclasses are the generator's intermediate representation. ``discover``
+populates them from the SDK's vAPI metadata; ``params`` and ``builder`` consume
+them. They carry plain Python data plus opaque references to the original vAPI
+type objects (``raw_type``) and binding classes (``struct_class``) used at
+invocation time.
+
+A few fields are captured now but consumed later: ``is_body`` / ``in_query`` feed
+HTTP request routing for the v0.2 write surface, and ``output_type`` /
+``error_types`` are reserved for richer table/error rendering. They are populated
+eagerly so discovery stays the single source of truth.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class ParamKind(str, Enum):
+    """The unwrapped, concrete kind of a parameter's vAPI type."""
+
+    STRING = "string"
+    INTEGER = "integer"
+    DOUBLE = "double"
+    BOOLEAN = "boolean"
+    ENUM = "enum"
+    ID = "id"
+    SECRET = "secret"
+    DATETIME = "datetime"
+    URI = "uri"
+    LIST = "list"
+    SET = "set"
+    MAP = "map"
+    STRUCT = "struct"
+    DYNAMIC = "dynamic"
+    BLOB = "blob"
+
+
+# Scalar kinds that map to a single CLI value (no JSON / container handling).
+SCALAR_KINDS: frozenset[ParamKind] = frozenset(
+    {
+        ParamKind.STRING,
+        ParamKind.INTEGER,
+        ParamKind.DOUBLE,
+        ParamKind.BOOLEAN,
+        ParamKind.ENUM,
+        ParamKind.ID,
+        ParamKind.SECRET,
+        ParamKind.DATETIME,
+        ParamKind.URI,
+    }
+)
+
+
+@dataclass
+class Param:
+    """A single operation parameter, unwrapped from its vAPI ``Type``."""
+
+    name: str
+    kind: ParamKind
+    required: bool
+    in_path: bool = False
+    in_query: bool = False
+    is_body: bool = False
+    resource_types: str | None = None
+    enum_values: list[str] = field(default_factory=list)
+    element: Param | None = None
+    key_kind: ParamKind | None = None
+    value_kind: ParamKind | None = None
+    struct_name: str | None = None
+    struct_class: type | None = None
+    raw_type: Any = None
+
+
+@dataclass
+class Operation:
+    """A single introspected, invokable operation on a service class."""
+
+    backend: str  # 'vsphere' | 'nsx'
+    service_cls: type
+    iface_id: str
+    op_id: str
+    method_name: str
+    cli_verb: str
+    http_method: str
+    url_template: str
+    path_vars: list[str] = field(default_factory=list)
+    path_var_map: dict[str, str] = field(default_factory=dict)
+    params: list[Param] = field(default_factory=list)
+    output_type: Any = None
+    error_types: list[Any] = field(default_factory=list)
+
+    @property
+    def service_short(self) -> str:
+        """The last segment of the vAPI interface id, e.g. ``VM`` -> ``vm``."""
+        return self.iface_id.split(".")[-1].lower()
+
+    @property
+    def is_write(self) -> bool:
+        """True for mutating operations (anything other than ``GET``)."""
+        return self.http_method != "GET"

vsc/gen/params.py

@@ -0,0 +1,232 @@
+"""Map vAPI binding ``Type`` objects to the :class:`Param` model and coerce CLI
+input back into the values the SDK call expects.
+
+The vAPI runtime performs *no* string coercion: integers, booleans, datetimes,
+and ``set`` vs ``list`` must already be the right Python type when handed to a
+generated operation method. This module owns that conversion.
+
+Key rules (verified against the installed SDK):
+
+* ``OptionalType`` wraps optional fields — unwrap and treat as not-required.
+* ``ReferenceType`` is lazy — always resolve via ``.resolved_type`` *before*
+  classifying; enums and nested structs hide behind it.
+* ``SetType`` needs a real ``set``; ``ListType`` a ``list`` — not interchangeable.
+* ``datetime`` must be timezone-aware.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json
+from typing import Any
+
+import vmware.vapi.bindings.type as bt
+
+from vsc.gen.model import SCALAR_KINDS, Param, ParamKind
+
+
+class CoercionError(ValueError):
+    """Raised when a CLI value cannot be coerced to the SDK type."""
+
+
+def _unwrap(ftype: Any) -> tuple[bool, Any]:
+    """Return ``(required, core_type)`` with Optional/Reference unwrapped."""
+    required = not isinstance(ftype, bt.OptionalType)
+    core = ftype.element_type if isinstance(ftype, bt.OptionalType) else ftype
+    if isinstance(core, bt.ReferenceType):
+        core = core.resolved_type
+    return required, core
+
+
+def _enum_values(core: Any) -> list[str]:
+    # vAPI EnumType has no ``.values``; the members live on the binding class.
+    binding_class = getattr(core, "binding_class", None)
+    if binding_class is None or not hasattr(binding_class, "get_values"):
+        return []
+    return [str(v) for v in binding_class.get_values()]
+
+
+def _loads_object(param_name: str, value: Any) -> Any:
+    """Parse a JSON value, raising :class:`CoercionError` on malformed input."""
+    if isinstance(value, (dict, list)):
+        return value
+    try:
+        return json.loads(str(value))
+    except (ValueError, TypeError) as exc:
+        raise CoercionError(f"{param_name!r}: invalid JSON ({exc})") from exc
+
+
+def _kind_of(core: Any) -> ParamKind:
+    """Classify an already-unwrapped core vAPI type into a :class:`ParamKind`."""
+    # Order matters: more specific subclasses first.
+    if isinstance(core, bt.SecretType):
+        return ParamKind.SECRET
+    if isinstance(core, bt.IdType):
+        return ParamKind.ID
+    if isinstance(core, bt.URIType):
+        return ParamKind.URI
+    if isinstance(core, bt.EnumType):
+        return ParamKind.ENUM
+    if isinstance(core, bt.StringType):
+        return ParamKind.STRING
+    if isinstance(core, bt.IntegerType):
+        return ParamKind.INTEGER
+    if isinstance(core, bt.DoubleType):
+        return ParamKind.DOUBLE
+    if isinstance(core, bt.BooleanType):
+        return ParamKind.BOOLEAN
+    if isinstance(core, bt.DateTimeType):
+        return ParamKind.DATETIME
+    if isinstance(core, bt.SetType):
+        return ParamKind.SET
+    if isinstance(core, bt.ListType):
+        return ParamKind.LIST
+    if isinstance(core, bt.MapType):
+        return ParamKind.MAP
+    if isinstance(core, bt.BlobType):
+        return ParamKind.BLOB
+    if isinstance(core, bt.StructType):
+        return ParamKind.STRUCT
+    # DynamicStructType, OpaqueType, AnyType, etc.
+    return ParamKind.DYNAMIC
+
+
+def param_from_type(
+    name: str,
+    ftype: Any,
+    *,
+    path_vars: tuple[str, ...] = (),
+    query_vars: frozenset[str] = frozenset(),
+    body_param: str | None = None,
+) -> Param:
+    """Build a :class:`Param` from a vAPI field ``Type`` (recursively)."""
+    required, core = _unwrap(ftype)
+    kind = _kind_of(core)
+    p = Param(
+        name=name,
+        kind=kind,
+        required=required,
+        in_path=name in path_vars,
+        in_query=name in query_vars,
+        is_body=(name == body_param),
+        raw_type=core,
+    )
+    if kind is ParamKind.ENUM:
+        p.enum_values = _enum_values(core)
+    elif kind is ParamKind.ID:
+        p.resource_types = _first_resource_type(core)
+    elif kind in (ParamKind.LIST, ParamKind.SET):
+        p.element = param_from_type("", core.element_type)
+    elif kind is ParamKind.MAP:
+        p.key_kind = _kind_of(_unwrap(core.key_type)[1])
+        p.value_kind = _kind_of(_unwrap(core.value_type)[1])
+    elif kind is ParamKind.STRUCT:
+        p.struct_name = getattr(core, "name", None)
+        p.struct_class = getattr(core, "binding_class", None)
+    return p
+
+
+def _first_resource_type(core: Any) -> str | None:
+    rt = getattr(core, "resource_types", None)
+    if isinstance(rt, str):
+        return rt
+    if isinstance(rt, (list, tuple)) and rt:
+        return str(rt[0])
+    return None
+
+
+# --------------------------------------------------------------------------- #
+# Coercion: CLI value -> SDK value
+# --------------------------------------------------------------------------- #
+
+
+def coerce_scalar(kind: ParamKind, value: Any) -> Any:
+    """Coerce a single scalar CLI value to the SDK-expected Python type."""
+    if value is None:
+        return None
+    if kind in (
+        ParamKind.STRING,
+        ParamKind.ID,
+        ParamKind.SECRET,
+        ParamKind.URI,
+        ParamKind.ENUM,
+    ):
+        return str(value)
+    if kind is ParamKind.INTEGER:
+        return value if isinstance(value, int) else int(str(value))
+    if kind is ParamKind.DOUBLE:
+        return value if isinstance(value, float) else float(str(value))
+    if kind is ParamKind.BOOLEAN:
+        if isinstance(value, bool):
+            return value
+        return str(value).strip().lower() in ("1", "true", "yes", "on")
+    if kind is ParamKind.DATETIME:
+        dt = value if isinstance(value, _dt.datetime) else _dt.datetime.fromisoformat(str(value))
+        return dt if dt.tzinfo else dt.replace(tzinfo=_dt.UTC)
+    return value
+
+
+def coerce_value(param: Param, value: Any) -> Any:
+    """Coerce a CLI value into the SDK value for ``param`` (recursive)."""
+    if value is None:
+        return None
+    kind = param.kind
+    if kind in SCALAR_KINDS:
+        return coerce_scalar(kind, value)
+    if kind in (ParamKind.LIST, ParamKind.SET):
+        items = _as_sequence(value)
+        element = param.element
+        coerced = [coerce_value(element, v) if element else v for v in items]
+        return set(coerced) if kind is ParamKind.SET else coerced
+    if kind is ParamKind.MAP:
+        obj = _loads_object(param.name, value)
+        if not isinstance(obj, dict):
+            raise CoercionError(f"{param.name!r}: expected a JSON object")
+        return {
+            coerce_scalar(param.key_kind or ParamKind.STRING, k): coerce_scalar(
+                param.value_kind or ParamKind.STRING, v
+            )
+            for k, v in obj.items()
+        }
+    if kind is ParamKind.STRUCT:
+        obj = _loads_object(param.name, value)
+        if not isinstance(obj, dict):
+            raise CoercionError(f"{param.name!r}: expected a JSON object")
+        return coerce_struct(param, obj)
+    # DYNAMIC / BLOB: parse JSON if it looks like JSON, else pass through.
+    if isinstance(value, (dict, list)):
+        return value
+    try:
+        return json.loads(str(value))
+    except (ValueError, TypeError):
+        return value
+
+
+def coerce_struct(param: Param, obj: dict[str, Any]) -> Any:
+    """Build the struct's ``binding_class`` from a JSON object, coercing fields."""
+    struct_type = param.raw_type
+    struct_class = param.struct_class
+    if struct_class is None or struct_type is None:
+        # No binding class resolved — hand the dict to the runtime as-is.
+        return obj
+    field_names = set(struct_type.get_field_names())
+    kwargs: dict[str, Any] = {}
+    for key, raw_value in obj.items():
+        if key not in field_names:
+            raise CoercionError(f"{param.name!r}: unknown field {key!r}")
+        field_param = param_from_type(key, struct_type.get_field(key))
+        kwargs[key] = coerce_value(field_param, raw_value)
+    return struct_class(**kwargs)
+
+
+def _as_sequence(value: Any) -> list[Any]:
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return list(value)
+    if isinstance(value, str):
+        stripped = value.strip()
+        if stripped.startswith("["):
+            parsed = json.loads(stripped)
+            if isinstance(parsed, list):
+                return parsed
+        return [value]
+    return [value]

vsc/gen/preview.py

@@ -0,0 +1,82 @@
+"""Build a request *plan* for a write operation — the dry-run preview.
+
+This is the heart of the v0.2 safety model: before any write is executed, the CLI
+resolves exactly what would go on the wire (method, URL, query, body) and shows it.
+The function is **pure** — it takes an :class:`Operation` and the (coerced) keyword
+arguments and returns a JSON-able dict. It performs no network or connection work,
+so the dry-run path can never touch the target.
+
+Two body conventions are handled:
+
+* NSX names a single ``request_body_parameter`` (``is_body``) — the body is that
+  parameter's value, unwrapped.
+* vCenter leaves ``request_body_parameter`` unset and serializes every non-path,
+  non-query parameter into the request body — so the body is the collection of
+  those parameters.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from vsc.gen.model import Operation, Param
+from vsc.output.render import jsonable
+
+
+def _resolve_url(op: Operation, kwargs: dict[str, Any]) -> str:
+    """Substitute ``{templateVar}`` placeholders using the path-var map."""
+    url = op.url_template
+    for field, template_var in op.path_var_map.items():
+        if field in kwargs and kwargs[field] is not None:
+            url = url.replace(f"{{{template_var}}}", str(kwargs[field]))
+    return url
+
+
+def _body(op: Operation, present: dict[str, Any]) -> Any:
+    """Compute the request body from the present, coerced kwargs."""
+    body_params = [p for p in op.params if p.is_body]
+    if body_params:
+        # NSX: a single named body parameter; the body is its value directly.
+        name = body_params[0].name
+        return jsonable(present[name]) if name in present else None
+    # vCenter: every non-path, non-query parameter forms the body object.
+    by_name: dict[str, Param] = {p.name: p for p in op.params}
+    body = {
+        name: jsonable(value)
+        for name, value in present.items()
+        if (p := by_name.get(name)) is not None and not p.in_path and not p.in_query
+    }
+    return body or None
+
+
+def build_request_plan(op: Operation, sdk_kwargs: dict[str, Any]) -> dict[str, Any]:
+    """Return a JSON-able plan describing the wire request ``op`` would make.
+
+    ``sdk_kwargs`` are the coerced keyword arguments (path/query/body values) that
+    would be passed to the SDK method. ``None`` values are treated as absent.
+
+    ``url`` is the resolved REST template and may include a literal query string the
+    SDK bakes into the template (e.g. ``?force=true`` on force variants); ``query``
+    holds the *structured* query parameters supplied as arguments. Both together
+    describe the wire request.
+    """
+    present = {k: v for k, v in sdk_kwargs.items() if v is not None}
+    by_name = {p.name: p for p in op.params}
+    path_params = {
+        name: jsonable(value) for name, value in present.items() if name in op.path_var_map
+    }
+    query = {
+        name: jsonable(value)
+        for name, value in present.items()
+        if (p := by_name.get(name)) is not None and p.in_query
+    }
+    return {
+        "method": op.http_method,
+        "url": _resolve_url(op, present),
+        "path_params": path_params,
+        "query": query,
+        "body": _body(op, present),
+        "backend": op.backend,
+        "service": op.service_short,
+        "operation": op.cli_verb,
+    }

vsc/logging_config.py

@@ -0,0 +1,30 @@
+"""Logging configuration.
+
+Logs go to **stderr** so stdout stays clean for machine-readable output, and the
+default level is ``WARNING`` (override with ``VSC_LOG_LEVEL``). This keeps the
+agent-friendly contract: stdout is data, stderr is diagnostics.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+import structlog
+
+_DEFAULT_LEVEL = "WARNING"
+
+
+def _level() -> int:
+    name = os.environ.get("VSC_LOG_LEVEL", _DEFAULT_LEVEL).upper()
+    return logging.getLevelNamesMapping().get(name, logging.WARNING)
+
+
+def configure_logging() -> None:
+    """Send structlog output to stderr at the configured level (idempotent)."""
+    structlog.configure(
+        wrapper_class=structlog.make_filtering_bound_logger(_level()),
+        logger_factory=structlog.PrintLoggerFactory(file=sys.stderr),
+        cache_logger_on_first_use=False,
+    )