netbox-super-cli 1.0.0__py3-none-any.whl

nsc/http/audit.py

@@ -0,0 +1,183 @@
+"""Audit log writers (Phase 3a).
+
+Two files under `~/.nsc/logs/`:
+  - `last-request.json`  — single-exchange ephemeral, overwritten on every call.
+  - `audit.jsonl`        — append-only, write attempts only (POST/PATCH/PUT/DELETE).
+
+Header redaction is centralized; body redaction is opt-in via `sensitive_paths`
+threaded from the schema's `RequestBodyShape.sensitive_paths` field.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import sys
+import tempfile
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from nsc.model.command_model import HttpMethod
+from nsc.output.headers import SENSITIVE_HEADERS
+
+DEFAULT_BODY_CAP_BYTES = 256 * 1024
+DEFAULT_ROTATE_BYTES = 10 * 1024 * 1024
+SCHEMA_VERSION = 1
+
+
+class _Frozen(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class AuditEntry(_Frozen):
+    timestamp: str
+    operation_id: str | None = None
+    method: HttpMethod
+    url: str
+    request_headers: dict[str, str] = Field(default_factory=dict)
+    request_query: dict[str, Any] = Field(default_factory=dict)
+    request_body: Any = None
+    sensitive_paths: tuple[str, ...] = ()
+    response_status_code: int | None = None
+    response_headers: dict[str, str] = Field(default_factory=dict)
+    response_body: Any = None
+    duration_ms: int | None = None
+    attempt_n: int = 1
+    final_attempt: bool = True
+    error_kind: str | None = None
+    dry_run: bool = False
+    preflight_blocked: bool = False
+    record_indices: list[int] = Field(default_factory=list)
+    applied: bool = False
+    explain: bool = False
+
+
+def redact_headers(headers: dict[str, str]) -> dict[str, str]:
+    return {k: ("<redacted>" if k.lower() in SENSITIVE_HEADERS else v) for k, v in headers.items()}
+
+
+def redact_body(body: Any, sensitive_paths: Sequence[str]) -> Any:
+    """Return a deep-copy of `body` with all `sensitive_paths` rewritten to `"<redacted>"`.
+
+    Path semantics:
+      - Each path is a dotted string (e.g., "auth.password"). Empty paths are ignored.
+      - The walker descends into dicts by key.
+      - When it encounters a list, it applies the remainder of the path to every element.
+      - A missing key on the walk is a no-op (the schema may declare optional fields).
+      - A non-mapping/non-list intermediate aborts that path safely.
+    """
+    if body is None or not sensitive_paths:
+        return body
+    out = copy.deepcopy(body)
+    for path in sensitive_paths:
+        if not path:
+            continue
+        _apply_redaction(out, path.split("."))
+    return out
+
+
+def _apply_redaction(node: Any, parts: list[str]) -> None:
+    if not parts:
+        return
+    head, *tail = parts
+    if isinstance(node, list):
+        for item in node:
+            _apply_redaction(item, parts)
+        return
+    if not isinstance(node, dict):
+        return
+    if head not in node:
+        return
+    if not tail:
+        node[head] = "<redacted>"
+        return
+    _apply_redaction(node[head], tail)
+
+
+def truncate_body(body: Any, *, cap_bytes: int = DEFAULT_BODY_CAP_BYTES) -> tuple[Any, bool]:
+    """Return (possibly-truncated body, was_truncated)."""
+    if body is None:
+        return None, False
+    serialized = json.dumps(body, default=str).encode("utf-8")
+    if len(serialized) <= cap_bytes:
+        return body, False
+    return {"_truncated": True, "_size_bytes": len(serialized)}, True
+
+
+def _to_dict(entry: AuditEntry) -> dict[str, Any]:
+    """Serialize to the wire shape documented in spec §4.3."""
+    req_body, req_trunc = truncate_body(redact_body(entry.request_body, entry.sensitive_paths))
+    resp_body, resp_trunc = truncate_body(entry.response_body)
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "timestamp": entry.timestamp,
+        "operation_id": entry.operation_id,
+        "method": entry.method.value,
+        "url": entry.url,
+        "request": {
+            "headers": redact_headers(entry.request_headers),
+            "query": entry.request_query,
+            "body": req_body,
+            "body_truncated": req_trunc,
+        },
+        "response": (
+            None
+            if entry.response_status_code is None
+            else {
+                "status_code": entry.response_status_code,
+                "headers": dict(entry.response_headers),
+                "body": resp_body,
+                "body_truncated": resp_trunc,
+            }
+        ),
+        "duration_ms": entry.duration_ms,
+        "attempt_n": entry.attempt_n,
+        "final_attempt": entry.final_attempt,
+        "error_kind": entry.error_kind,
+        "dry_run": entry.dry_run,
+        "preflight_blocked": entry.preflight_blocked,
+        "record_indices": entry.record_indices,
+        "applied": entry.applied,
+        "explain": entry.explain,
+    }
+
+
+def _warn(msg: str) -> None:
+    print(f"warning: {msg}", file=sys.stderr)
+
+
+def write_last_request(entry: AuditEntry, *, path: Path) -> None:
+    """Atomically overwrite `path` with the entry. Failures emit a stderr warning."""
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile(
+            "w", encoding="utf-8", dir=path.parent, delete=False
+        ) as tmp:
+            json.dump(_to_dict(entry), tmp)
+            tmp_path = Path(tmp.name)
+        os.replace(tmp_path, path)
+    except OSError as exc:
+        _warn(f"could not write audit log {path}: {exc}")
+
+
+def append_audit_jsonl(
+    entry: AuditEntry,
+    *,
+    path: Path,
+    rotate_bytes: int = DEFAULT_ROTATE_BYTES,
+) -> None:
+    """Append the entry as a single line. Rotate to `path.1` when over the threshold."""
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        if path.exists() and path.stat().st_size > rotate_bytes:
+            rolled = path.with_suffix(path.suffix + ".1")
+            os.replace(path, rolled)
+        with path.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(_to_dict(entry)))
+            fh.write("\n")
+    except OSError as exc:
+        _warn(f"could not append audit log {path}: {exc}")

nsc/http/client.py

@@ -0,0 +1,365 @@
+"""Sync httpx-based NetBox client (Phase 3a: reads + retry + audit)."""
+
+from __future__ import annotations
+
+import sys
+import time
+from collections.abc import Iterator
+from datetime import UTC, datetime
+from types import TracebackType
+from typing import Any, Protocol, cast
+from urllib.parse import parse_qs, urlsplit
+
+import httpx
+
+from nsc.config.settings import default_paths
+from nsc.http.audit import (
+    AuditEntry,
+    append_audit_jsonl,
+    write_last_request,
+)
+from nsc.http.errors import NetBoxAPIError, NetBoxClientError
+from nsc.http.retry import (
+    ErrorClass,
+    backoff_delay,
+    classify_error,
+    policy_for_method,
+    should_retry,
+)
+from nsc.model.command_model import HttpMethod
+
+_BODY_SNIPPET_BYTES = 2048
+_HTTP_5XX_MIN = 500
+_HTTP_4XX_MIN = 400
+
+
+class _ProfileLike(Protocol):
+    url: Any
+    token: str | None
+    verify_ssl: bool
+    timeout: float
+
+
+class NetBoxClient:
+    def __init__(self, profile: _ProfileLike, *, debug: bool = False) -> None:
+        if profile.token is None:
+            raise ValueError("NetBoxClient requires a non-None token on the profile")
+        self._url = str(profile.url).rstrip("/")
+        self._debug = debug
+        self._client = httpx.Client(
+            base_url=self._url,
+            headers={
+                "Authorization": f"Token {profile.token}",
+                "Accept": "application/json",
+            },
+            verify=profile.verify_ssl,
+            timeout=profile.timeout,
+            event_hooks=self._event_hooks() if debug else {},
+        )
+
+    def __enter__(self) -> NetBoxClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        response = self._send_with_retry(HttpMethod.GET, path, params=params)
+        return _parse_json(response)
+
+    def post(
+        self,
+        path: str,
+        *,
+        json: Any | None = None,
+        operation_id: str | None = None,
+        record_indices: list[int] | None = None,
+        sensitive_paths: tuple[str, ...] = (),
+    ) -> dict[str, Any]:
+        response = self._send_with_retry(
+            HttpMethod.POST,
+            path,
+            json_body=json,
+            operation_id=operation_id,
+            record_indices=record_indices,
+            sensitive_paths=sensitive_paths,
+        )
+        return _parse_json(response)
+
+    def patch(
+        self,
+        path: str,
+        *,
+        json: Any | None = None,
+        operation_id: str | None = None,
+        record_indices: list[int] | None = None,
+        sensitive_paths: tuple[str, ...] = (),
+    ) -> dict[str, Any]:
+        response = self._send_with_retry(
+            HttpMethod.PATCH,
+            path,
+            json_body=json,
+            operation_id=operation_id,
+            record_indices=record_indices,
+            sensitive_paths=sensitive_paths,
+        )
+        return _parse_json(response)
+
+    def put(
+        self,
+        path: str,
+        *,
+        json: Any | None = None,
+        operation_id: str | None = None,
+        record_indices: list[int] | None = None,
+        sensitive_paths: tuple[str, ...] = (),
+    ) -> dict[str, Any]:
+        response = self._send_with_retry(
+            HttpMethod.PUT,
+            path,
+            json_body=json,
+            operation_id=operation_id,
+            record_indices=record_indices,
+            sensitive_paths=sensitive_paths,
+        )
+        return _parse_json(response)
+
+    def delete(
+        self,
+        path: str,
+        *,
+        operation_id: str | None = None,
+        record_indices: list[int] | None = None,
+        sensitive_paths: tuple[str, ...] = (),
+    ) -> dict[str, Any]:
+        response = self._send_with_retry(
+            HttpMethod.DELETE,
+            path,
+            operation_id=operation_id,
+            record_indices=record_indices,
+            sensitive_paths=sensitive_paths,
+        )
+        return _parse_json(response)
+
+    def paginate(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        *,
+        limit: int | None = None,
+    ) -> Iterator[dict[str, Any]]:
+        url: str | None = path
+        first = True
+        emitted = 0
+        while url is not None:
+            if first:
+                req_path, req_params = url, params
+            else:
+                # next URLs are absolute; split them so respx (and httpx) can
+                # match on path + params independently rather than a raw string.
+                parsed = urlsplit(url)
+                req_path = parsed.path
+                qs = parse_qs(parsed.query, keep_blank_values=True)
+                req_params = {k: v[0] for k, v in qs.items()} if qs else None
+            response = self._send_with_retry(HttpMethod.GET, req_path, params=req_params)
+            payload = _parse_json(response)
+            for record in payload.get("results", []):
+                yield record
+                emitted += 1
+                if limit is not None and emitted >= limit:
+                    return
+            url = payload.get("next")
+            first = False
+
+    def _send_with_retry(
+        self,
+        method: HttpMethod,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: Any | None = None,
+        operation_id: str | None = None,
+        record_indices: list[int] | None = None,
+        sensitive_paths: tuple[str, ...] = (),
+    ) -> httpx.Response:
+        policy = policy_for_method(method)
+        attempt = 0
+        is_write = method not in {HttpMethod.GET, HttpMethod.HEAD, HttpMethod.OPTIONS}
+        indices: list[int] = list(record_indices) if record_indices is not None else []
+        while True:
+            attempt += 1
+            started = time.monotonic()
+            try:
+                response = self._client.request(method.value, path, params=params, json=json_body)
+            except httpx.RequestError as exc:
+                error_class: ErrorClass | None = classify_error(exc)
+                duration_ms = int((time.monotonic() - started) * 1000)
+                retry = should_retry(
+                    policy, attempt=attempt, status_code=None, error_class=error_class
+                )
+                self._record_attempt(
+                    method=method,
+                    path=path,
+                    params=params,
+                    request_body=json_body,
+                    response=None,
+                    duration_ms=duration_ms,
+                    attempt=attempt,
+                    final=not retry,
+                    operation_id=operation_id,
+                    is_write=is_write,
+                    record_indices=indices,
+                    sensitive_paths=sensitive_paths,
+                )
+                if not retry:
+                    raise NetBoxClientError(url=self._absolute(path, params), cause=exc) from exc
+                time.sleep(backoff_delay(policy, attempt=attempt))
+                continue
+            duration_ms = int((time.monotonic() - started) * 1000)
+            retry = should_retry(
+                policy,
+                attempt=attempt,
+                status_code=response.status_code,
+                error_class=None,
+            )
+            self._record_attempt(
+                method=method,
+                path=path,
+                params=params,
+                request_body=json_body,
+                response=response,
+                duration_ms=duration_ms,
+                attempt=attempt,
+                final=not retry,
+                operation_id=operation_id,
+                is_write=is_write,
+                record_indices=indices,
+                sensitive_paths=sensitive_paths,
+            )
+            if not retry:
+                if response.is_success:
+                    return response
+                self._raise_for_status(response)
+            time.sleep(backoff_delay(policy, attempt=attempt))
+
+    def _absolute(self, path: str, params: dict[str, Any] | None) -> str:
+        request = self._client.build_request("GET", path, params=params)
+        return str(request.url)
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        if response.is_success:
+            return
+        try:
+            body = response.text[:_BODY_SNIPPET_BYTES]
+        except Exception:  # pragma: no cover
+            body = ""
+        raise NetBoxAPIError(
+            status_code=response.status_code,
+            url=str(response.request.url),
+            body_snippet=body,
+            headers=dict(response.headers),
+        )
+
+    def _record_attempt(
+        self,
+        *,
+        method: HttpMethod,
+        path: str,
+        params: dict[str, Any] | None,
+        request_body: Any | None,
+        response: httpx.Response | None,
+        duration_ms: int,
+        attempt: int,
+        final: bool,
+        operation_id: str | None,
+        is_write: bool,
+        record_indices: list[int],
+        sensitive_paths: tuple[str, ...] = (),
+    ) -> None:
+        url = self._absolute(path, params)
+        # httpx lowercases all header names; title-case them so the audit log
+        # uses the conventional HTTP capitalisation (e.g. "Authorization").
+        request_headers = {k.title(): v for k, v in self._client.headers.items()}
+        if response is not None:
+            status_code: int = response.status_code
+            response_headers = dict(response.headers)
+            try:
+                response_body: Any = response.json() if response.content else None
+            except ValueError:
+                response_body = response.text[:_BODY_SNIPPET_BYTES]
+            if status_code >= _HTTP_5XX_MIN:
+                error_kind: str | None = "5xx"
+            elif status_code >= _HTTP_4XX_MIN:
+                error_kind = "4xx"
+            else:
+                error_kind = None
+            audit_status: int | None = status_code
+        else:
+            audit_status = None
+            response_headers = {}
+            response_body = None
+            error_kind = "transport"
+
+        entry = AuditEntry(
+            timestamp=_now_iso(),
+            operation_id=operation_id,
+            method=method,
+            url=url,
+            request_headers=request_headers,
+            request_query=dict(params or {}),
+            request_body=request_body,
+            sensitive_paths=sensitive_paths,
+            response_status_code=audit_status,
+            response_headers=response_headers,
+            response_body=response_body,
+            duration_ms=duration_ms,
+            attempt_n=attempt,
+            final_attempt=final,
+            error_kind=error_kind,
+            dry_run=False,
+            preflight_blocked=False,
+            record_indices=list(record_indices),
+            applied=is_write,
+            explain=False,
+        )
+        log_dir = default_paths().logs_dir
+        write_last_request(entry, path=log_dir / "last-request.json")
+        if is_write or self._debug:
+            append_audit_jsonl(entry, path=log_dir / "audit.jsonl")
+
+    def _event_hooks(self) -> dict[str, list[Any]]:
+        # Phase 2 stderr streaming — keep alongside Phase 3a audit.jsonl writes.
+        def on_request(request: httpx.Request) -> None:
+            print(f">>> {request.method} {request.url}", file=sys.stderr)
+            for k, v in request.headers.items():
+                masked = "<redacted>" if k.lower() == "authorization" else v
+                print(f">>> {k}: {masked}", file=sys.stderr)
+
+        def on_response(response: httpx.Response) -> None:
+            response.read()
+            print(f"<<< {response.status_code} {response.reason_phrase}", file=sys.stderr)
+            for k, v in response.headers.items():
+                print(f"<<< {k}: {v}", file=sys.stderr)
+            body = response.text[:_BODY_SNIPPET_BYTES]
+            if body:
+                print(f"<<< {body}", file=sys.stderr)
+
+        return {"request": [on_request], "response": [on_response]}
+
+
+def _now_iso() -> str:
+    return datetime.now(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+def _parse_json(response: httpx.Response) -> dict[str, Any]:
+    if not response.content:
+        return {}
+    return cast(dict[str, Any], response.json())

nsc/http/errors.py

@@ -0,0 +1,35 @@
+"""HTTP error types raised by NetBoxClient."""
+
+from __future__ import annotations
+
+
+class NetBoxAPIError(Exception):
+    """A non-2xx response from NetBox."""
+
+    def __init__(
+        self,
+        status_code: int,
+        url: str,
+        body_snippet: str,
+        headers: dict[str, str],
+    ) -> None:
+        super().__init__(f"NetBox API {status_code} on {url}")
+        self.status_code = status_code
+        self.url = url
+        self.body_snippet = body_snippet
+        self.headers = headers
+
+    def render_for_cli(self) -> str:
+        return f"NetBox API {self.status_code} on {self.url}: {self.body_snippet}"
+
+
+class NetBoxClientError(Exception):
+    """A transport-level failure reaching NetBox (DNS, TCP, TLS, timeout)."""
+
+    def __init__(self, url: str, cause: BaseException) -> None:
+        super().__init__(f"NetBox transport error on {url}: {cause}")
+        self.url = url
+        self.cause = cause
+
+    def render_for_cli(self) -> str:
+        return f"NetBox transport error on {self.url}: {self.cause}"

nsc/http/retry.py

@@ -0,0 +1,90 @@
+"""Per-method retry policy + error classification (Phase 3a).
+
+Pure functions only. The retry *loop* lives in `NetBoxClient`; this module
+decides whether to keep going.
+"""
+
+from __future__ import annotations
+
+import random
+from enum import Enum
+
+import httpx
+from pydantic import BaseModel, ConfigDict
+
+from nsc.model.command_model import HttpMethod
+
+
+class _Frozen(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class RetryPolicy(_Frozen):
+    max_attempts: int = 3
+    base_delay: float = 0.5
+    jitter: float = 0.25
+    retry_on_5xx: bool
+    retry_on_connect: bool
+
+
+class ErrorClass(Enum):
+    """Classification of a transport-layer exception."""
+
+    CONNECT = "connect"  # provably no-op (request never sent)
+    READ_TIMEOUT = "read_timeout"  # bytes sent, server may have processed
+    TRANSPORT_AMBIGUOUS = "transport_ambig"  # could be either; treat as may-have-sent
+
+
+_READ_METHODS = {HttpMethod.GET, HttpMethod.HEAD, HttpMethod.OPTIONS}
+
+_5XX_MIN = 500
+_5XX_MAX = 600
+
+
+def policy_for_method(method: HttpMethod) -> RetryPolicy:
+    if method in _READ_METHODS:
+        return RetryPolicy(retry_on_5xx=True, retry_on_connect=True)
+    return RetryPolicy(retry_on_5xx=False, retry_on_connect=True)
+
+
+def classify_error(exc: BaseException) -> ErrorClass:
+    """Map an httpx transport exception to a retry-relevant class."""
+    if isinstance(exc, (httpx.ConnectError, httpx.ConnectTimeout)):
+        return ErrorClass.CONNECT
+    if isinstance(exc, httpx.ReadTimeout):
+        return ErrorClass.READ_TIMEOUT
+    return ErrorClass.TRANSPORT_AMBIGUOUS
+
+
+def should_retry(
+    policy: RetryPolicy,
+    *,
+    attempt: int,
+    status_code: int | None,
+    error_class: ErrorClass | None,
+) -> bool:
+    """Should we attempt request `attempt + 1`?
+
+    Args:
+        attempt: The 1-indexed attempt that just finished.
+        status_code: HTTP status from the response, or None if no response.
+        error_class: The transport classification, or None if a response arrived.
+    """
+    if attempt >= policy.max_attempts:
+        return False
+    if error_class is ErrorClass.CONNECT:
+        return policy.retry_on_connect
+    if error_class in (ErrorClass.READ_TIMEOUT, ErrorClass.TRANSPORT_AMBIGUOUS):
+        return False  # never retry possibly-already-sent writes; reads don't either (safety)
+    if status_code is not None and _5XX_MIN <= status_code < _5XX_MAX:
+        return policy.retry_on_5xx
+    return False
+
+
+def backoff_delay(policy: RetryPolicy, *, attempt: int) -> float:
+    """Exponential backoff with ± jitter%, in seconds."""
+    base: float = policy.base_delay * (2 ** (attempt - 1))
+    if policy.jitter == 0.0:
+        return base
+    span: float = base * policy.jitter
+    return float(base + random.uniform(-span, span))

nsc/model/__init__.py

@@ -0,0 +1,23 @@
+"""Framework-free command-model: the normalized command tree."""
+
+from nsc.model.command_model import (
+    CommandModel,
+    HttpMethod,
+    Operation,
+    Parameter,
+    ParameterLocation,
+    PrimitiveType,
+    Resource,
+    Tag,
+)
+
+__all__ = [
+    "CommandModel",
+    "HttpMethod",
+    "Operation",
+    "Parameter",
+    "ParameterLocation",
+    "PrimitiveType",
+    "Resource",
+    "Tag",
+]