nso-adapter 0.3.0__tar.gz

nso_adapter-0.3.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: nso-adapter
+Version: 0.3.0
+Summary: Middleware adapter between Cisco NSO and NetBox
+License: Apache-2.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.141.1
+Requires-Dist: uvicorn[standard]>=0.52.1
+Requires-Dist: httpx>=0.28
+Requires-Dist: sqlalchemy[asyncio]>=2.0.51
+Requires-Dist: asyncpg>=0.30
+Requires-Dist: psycopg2-binary>=2.9
+Requires-Dist: alembic>=1.18.5
+Requires-Dist: apscheduler>=3.11.3
+Requires-Dist: hvac>=2.3
+Requires-Dist: pydantic-settings>=2.7
+Requires-Dist: structlog>=26.1.0
+Requires-Dist: python-dotenv>=1.1
+Requires-Dist: pyyaml>=6.0
+
+# nso-adapter
+
+Middleware service between Cisco NSO and consumers (NetBox first). Speaks NSO
+RESTCONF; exposes a consumer-agnostic northbound REST API. Internally split
+into a generic NSO core and pluggable consumer bindings; a NetBox binding ships
+with it.
+
+## Documentation
+
+- [`docs/00-plan.md`](docs/00-plan.md) — overall plan for the NSO ↔ NetBox
+  integration (cross-cutting; lives here because the adapter implements the
+  contract).
+- [`docs/api-contract.md`](docs/api-contract.md) — canonical northbound REST
+  API contract. The NetBox plugin builds against this.
+- [`docs/nso-adapter.md`](docs/nso-adapter.md) — adapter design (this repo).
+
+Companion repos: **[`netbox-nso-plugin`](../netbox-nso-plugin)** — the NetBox
+plugin that consumes this adapter; **`nso-packages`** — the NSO-side YANG
+service packages (`network-state-export` read exports + the `*-reconciler`
+write services) the adapter drives over RESTCONF.
+
+## Status
+
+In active development (Phase 2, 2026-06). The northbound API serves ~57
+endpoints across 16 config families (interfaces/IPs/MTU, VLAN/switchport,
+SVI, subinterfaces, L2 services, LAG, IS-IS, OSPF, BGP, route-policy,
+redistribution, static routes, BFD, SNMP, logging) — read mirrors plus a
+full-replace intent store with a durable apply worker, post-apply dry-run
+verification, periodic + SSE-triggered sync, and an intent-summary endpoint
+for split-brain detection. `docs/api-contract.md` is kept in lock-step with
+the implemented surface; `docs/00-plan.md` §6/§7 records the original
+Phase 1 plan.

nso_adapter-0.3.0/README.md

@@ -0,0 +1,32 @@
+# nso-adapter
+
+Middleware service between Cisco NSO and consumers (NetBox first). Speaks NSO
+RESTCONF; exposes a consumer-agnostic northbound REST API. Internally split
+into a generic NSO core and pluggable consumer bindings; a NetBox binding ships
+with it.
+
+## Documentation
+
+- [`docs/00-plan.md`](docs/00-plan.md) — overall plan for the NSO ↔ NetBox
+  integration (cross-cutting; lives here because the adapter implements the
+  contract).
+- [`docs/api-contract.md`](docs/api-contract.md) — canonical northbound REST
+  API contract. The NetBox plugin builds against this.
+- [`docs/nso-adapter.md`](docs/nso-adapter.md) — adapter design (this repo).
+
+Companion repos: **[`netbox-nso-plugin`](../netbox-nso-plugin)** — the NetBox
+plugin that consumes this adapter; **`nso-packages`** — the NSO-side YANG
+service packages (`network-state-export` read exports + the `*-reconciler`
+write services) the adapter drives over RESTCONF.
+
+## Status
+
+In active development (Phase 2, 2026-06). The northbound API serves ~57
+endpoints across 16 config families (interfaces/IPs/MTU, VLAN/switchport,
+SVI, subinterfaces, L2 services, LAG, IS-IS, OSPF, BGP, route-policy,
+redistribution, static routes, BFD, SNMP, logging) — read mirrors plus a
+full-replace intent store with a durable apply worker, post-apply dry-run
+verification, periodic + SSE-triggered sync, and an intent-summary endpoint
+for split-brain detection. `docs/api-contract.md` is kept in lock-step with
+the implemented surface; `docs/00-plan.md` §6/§7 records the original
+Phase 1 plan.

nso_adapter-0.3.0/nso_adapter/__init__.py

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+"""NSO Adapter package.
+
+Single source for the version string — FastAPI(version=...) and the /healthz
+payload both import it; a test pins it against pyproject.toml.
+"""
+
+__version__ = "0.3.0"

nso_adapter-0.3.0/nso_adapter/api/actions.py

@@ -0,0 +1,233 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Actions API — async device actions (sync, check-sync_state, connect, apply, sync-notify).
+
+All actions return 202 with {job_id}.
+409 is returned if a job is already queued/running for the device.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from nso_adapter.api.deps import get_db, verify_token
+from nso_adapter.api.errors import (
+    RESP_400,
+    RESP_401,
+    RESP_404_DEVICE,
+    RESP_409_ACTIVE_JOB,
+    RESP_422_VALIDATION,
+    api_error,
+)
+from nso_adapter.core.jobs import enqueue_job
+from nso_adapter.store.models import Device, JobType
+
+router = APIRouter(prefix="/api/v1/devices", tags=["actions"])
+
+# All action endpoints emit 401 (token) + 422 (device_id path); the responses fragments
+# below add the ones each endpoint actually raises. The trigger POSTs go through
+# _trigger (404 + 409-active-job); force-removal / apply-diff raise 400 bad_request.
+_TRIGGER_ERRORS = {**RESP_401, **RESP_404_DEVICE, **RESP_409_ACTIVE_JOB, **RESP_422_VALIDATION}
+
+
+class JobTriggerOut(BaseModel):
+    """The async-action envelope: the id of the enqueued job (202)."""
+
+    job_id: int
+
+
+class ApplyDiffOut(BaseModel):
+    """apply-diff preview — {scope: native_delta} for scopes with a non-empty change."""
+
+    device_id: int
+    outformat: str
+    diffs: dict[str, str]
+
+
+async def _trigger(
+    device_id: int,
+    job_type: JobType,
+    db: AsyncSession,
+) -> dict:
+    device = await db.get(Device, device_id)
+    if not device:
+        raise api_error(404, "not_found", "Device not found")
+
+    job, created = await enqueue_job(device_id, job_type, db)
+    if not created:
+        raise api_error(409, "conflict", "A job is already running for this device", {"job_id": job.id})
+    return {"job_id": job.id}
+
+
+class ForceRemovalBody(BaseModel):
+    scope: str
+    interfaces: list[str] | None = None
+
+
+@router.post(
+    "/{device_id}/actions/force-removal",
+    status_code=202,
+    dependencies=[Depends(verify_token)],
+    response_model=JobTriggerOut,
+    responses={**RESP_401, **RESP_404_DEVICE, **RESP_400, **RESP_422_VALIDATION},
+)
+async def action_force_removal(
+    device_id: int,
+    body: ForceRemovalBody,
+    db: AsyncSession = Depends(get_db),
+):
+    """Re-run a scope's removal with the collateral guard DISABLED.
+
+    The operator override for a ``removal_blocked_collateral`` failure: after
+    reviewing the blocked job's orphan list + dry-run preview, this deliberately
+    flushes the orphaned service rows (PUT-replace with only the remaining intent).
+
+    ``interface_config`` is per-instance (interface-reconciler is keyed by
+    ``(device, interface-name)``), so its removal job flushes exactly the interfaces named
+    in *interfaces* — with none, ``_replace_interface_config`` iterates an empty list and
+    the job succeeds having pushed NOTHING, telling the operator their orphaned addresses
+    were flushed while the config is still live on the device. Reject that rather than
+    succeed at nothing.
+    """
+    from nso_adapter.core.removal import VALID_REMOVAL_SCOPES, enqueue_removal
+
+    device = await db.get(Device, device_id)
+    if not device:
+        raise api_error(404, "not_found", "Device not found")
+    if body.scope not in VALID_REMOVAL_SCOPES:
+        raise api_error(400, "bad_request", f"Unknown removal scope {body.scope!r}")
+    if body.scope == "interface_config" and not body.interfaces:
+        raise api_error(
+            400,
+            "bad_request",
+            "force-removal of interface_config requires 'interfaces': the interface-reconciler "
+            "is keyed per interface, so with none named the job would flush nothing.",
+        )
+    job = await enqueue_removal(db, device_id, body.scope, interfaces=body.interfaces, force=True)
+    await db.commit()
+    return {"job_id": job.id}
+
+
+@router.post(
+    "/{device_id}/actions/sync",
+    status_code=202,
+    dependencies=[Depends(verify_token)],
+    response_model=JobTriggerOut,
+    responses=_TRIGGER_ERRORS,
+)
+async def action_sync(
+    device_id: int,
+    db: AsyncSession = Depends(get_db),
+):
+    # Operator Sync-Now = READSEM grain c: the mirror fan-out reads ONE atomic
+    # device-state-read build. The plugin's sync-notify below stays grain b (automatic,
+    # frequent - the record-served projection).
+    return await _trigger(device_id, JobType.sync_now, db)
+
+
+@router.post(
+    "/{device_id}/actions/sync-from-nso",
+    status_code=202,
+    dependencies=[Depends(verify_token)],
+    response_model=JobTriggerOut,
+    responses=_TRIGGER_ERRORS,
+)
+async def action_sync_from_nso(
+    device_id: int,
+    db: AsyncSession = Depends(get_db),
+):
+    # Operator "Sync from NSO" (S5a): comprehensive CDB-only mirror read — every surface
+    # from ONE atomic device-state-read, NO device round-trip (Sync Now above runs the
+    # device sync-from first; this re-reads what NSO already knows).
+    return await _trigger(device_id, JobType.sync_from_nso, db)
+
+
+@router.post(
+    "/{device_id}/actions/detect-drift",
+    status_code=202,
+    dependencies=[Depends(verify_token)],
+    response_model=JobTriggerOut,
+    responses=_TRIGGER_ERRORS,
+)
+async def action_detect_drift(
+    device_id: int,
+    db: AsyncSession = Depends(get_db),
+):
+    return await _trigger(device_id, JobType.detect_drift, db)
+
+
+@router.post(
+    "/{device_id}/actions/connect",
+    status_code=202,
+    dependencies=[Depends(verify_token)],
+    response_model=JobTriggerOut,
+    responses=_TRIGGER_ERRORS,
+)
+async def action_connect(
+    device_id: int,
+    db: AsyncSession = Depends(get_db),
+):
+    return await _trigger(device_id, JobType.connect, db)
+
+
+@router.post(
+    "/{device_id}/sync-notify",
+    status_code=202,
+    dependencies=[Depends(verify_token)],
+    response_model=JobTriggerOut,
+    responses=_TRIGGER_ERRORS,
+)
+async def sync_notify(
+    device_id: int,
+    db: AsyncSession = Depends(get_db),
+):
+    """Handle the NetBox plugin's notification that scope or intent changed for this device.
+
+    Triggers an immediate sync job. If a job is already running, returns 409 with
+    the existing job_id so the plugin can poll for the result.
+    """
+    return await _trigger(device_id, JobType.sync, db)
+
+
+@router.post(
+    "/{device_id}/actions/apply",
+    status_code=202,
+    dependencies=[Depends(verify_token)],
+    response_model=JobTriggerOut,
+    responses=_TRIGGER_ERRORS,
+)
+async def action_apply(
+    device_id: int,
+    db: AsyncSession = Depends(get_db),
+):
+    """Phase 2 — push accepted NetBox intent to NSO via reconcile-commit service."""
+    return await _trigger(device_id, JobType.apply, db)
+
+
+@router.get(
+    "/{device_id}/actions/apply-diff",
+    dependencies=[Depends(verify_token)],
+    response_model=ApplyDiffOut,
+    responses={**RESP_401, **RESP_404_DEVICE, **RESP_400, **RESP_422_VALIDATION},
+)
+async def action_apply_diff(
+    device_id: int,
+    outformat: str = "native",
+    db: AsyncSession = Depends(get_db),
+):
+    """Preview the per-scope diff the next Apply would push (NSO dry-run, no commit).
+
+    ``outformat=native`` (default): device-native rendering (CLI lines for cli NEDs,
+    edit-config XML for netconf NEDs). ``outformat=cli``: NSO's NED-uniform ``+``/``-``
+    tree diff — the "diff -u" style the preview panel renders.
+    """
+    from nso_adapter.core.apply import collect_apply_diff
+
+    if outformat not in ("native", "cli"):
+        raise api_error(400, "bad_request", f"Unknown outformat {outformat!r} (native|cli)")
+    device = await db.get(Device, device_id)
+    if not device:
+        raise api_error(404, "not_found", "Device not found")
+    diffs = await collect_apply_diff(db, device_id, outformat=outformat)
+    return {"device_id": device_id, "outformat": outformat, "diffs": diffs}

nso_adapter-0.3.0/nso_adapter/api/bfd.py

@@ -0,0 +1,195 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>
+"""GET /api/v1/devices/{id}/bfd — per-interface BFD read mirror."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+import structlog
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from nso_adapter.api.deps import get_db, get_read_db, verify_token
+from nso_adapter.api.errors import RESP_401, RESP_404_DEVICE, RESP_422_VALIDATION, IntentApplyResult, api_error
+from nso_adapter.api.read_state import FamilyReadState, read_state_payload
+from nso_adapter.api.timestamps import UtcInstant, iso_z
+from nso_adapter.core.removal import is_cleared
+from nso_adapter.store import outcome_store
+from nso_adapter.store.models import BfdIntent, Device, DeviceBfdInterface, DeviceSettings
+
+logger = structlog.get_logger(__name__)
+
+router = APIRouter(prefix="/api/v1/devices", tags=["bfd"])
+
+
+# ── Read-mirror response models (GET /bfd) ────────────────────────────────────
+# OMIT shape: bound_port/min_tx/min_rx/multiplier omitted when unset ->
+# exclude_unset; micro_bfd/enabled are always-present bools.
+
+
+class BfdInterfaceOut(BaseModel):
+    interface_name: str
+    micro_bfd: bool
+    enabled: bool
+    bound_port: str | None = None
+    min_tx: int | None = None
+    min_rx: int | None = None
+    multiplier: int | None = None
+
+
+class BfdConfigOut(BaseModel):
+    device_id: int
+    last_refreshed_at: str | None = None  # reader formats "<iso>Z"; None when never refreshed
+    refresh_source: str  # legacy freshness (S5 retires it); read_state is the S4 truth
+    read_state: FamilyReadState
+    interfaces: list[BfdInterfaceOut]
+
+
+@router.get(
+    "/{device_id}/bfd",
+    dependencies=[Depends(verify_token)],
+    response_model=BfdConfigOut,
+    response_model_exclude_unset=True,
+    responses={**RESP_401, **RESP_404_DEVICE, **RESP_422_VALIDATION},
+)
+async def get_bfd(device_id: int, db: AsyncSession = Depends(get_read_db)):
+    """Return the per-interface BFD read-mirror for this device."""
+    device = await db.get(Device, device_id)
+    if not device:
+        raise api_error(404, "not_found", "Device not found")
+
+    # Pointer first, rows second, one snapshot (S4 D2 — benign direction).
+    read_state = read_state_payload(
+        await outcome_store.get_current_outcome(db, device_id, "bfd"), source_epoch=device.source_epoch
+    )
+
+    rows = (
+        (
+            await db.execute(
+                select(DeviceBfdInterface)
+                .where(DeviceBfdInterface.device_id == device_id)
+                .order_by(DeviceBfdInterface.interface_name)
+            )
+        )
+        .scalars()
+        .all()
+    )
+
+    latest = max((r.last_refreshed_at for r in rows if r.last_refreshed_at), default=None)
+    interfaces = []
+    for r in rows:
+        entry: dict = {
+            "interface_name": r.interface_name,
+            "micro_bfd": r.micro_bfd,
+            "enabled": r.enabled,
+        }
+        if r.bound_port is not None:
+            entry["bound_port"] = r.bound_port
+        if r.min_tx is not None:
+            entry["min_tx"] = r.min_tx
+        if r.min_rx is not None:
+            entry["min_rx"] = r.min_rx
+        if r.multiplier is not None:
+            entry["multiplier"] = r.multiplier
+        interfaces.append(entry)
+
+    return {
+        "device_id": device_id,
+        "last_refreshed_at": iso_z(latest),
+        "refresh_source": rows[0].refresh_source if rows else "never",
+        "read_state": read_state,
+        "interfaces": interfaces,
+    }
+
+
+# ---------------------------------------------------------------------------
+# PUT /{device_id}/bfd-intent  (BFD write path — deferred apply)
+# ---------------------------------------------------------------------------
+
+
+class BfdEntry(BaseModel):
+    interface_name: str
+    min_tx: int | None = None
+    min_rx: int | None = None
+    multiplier: int | None = None
+    micro_bfd: bool = False
+    accepted_at: UtcInstant | None = None
+
+
+# Scalars the writer emits only when set — `if row.min_tx is not None:` (nso/apply.py)
+# A merge-PATCH apply can never drop one that goes back to unset, so clearing any of
+# them must enqueue a PUT-replace retract. See core.removal.is_cleared.
+_STATE_FIELDS = ("min_tx", "min_rx", "multiplier")
+
+
+class BfdIntentUpdate(BaseModel):
+    interfaces: list[BfdEntry]
+
+
+@router.put(
+    "/{device_id}/bfd-intent",
+    dependencies=[Depends(verify_token)],
+    response_model=IntentApplyResult,
+    responses={**RESP_401, **RESP_404_DEVICE, **RESP_422_VALIDATION},
+)
+async def put_bfd_intent(device_id: int, body: BfdIntentUpdate, db: AsyncSession = Depends(get_db)):
+    """Replace the adapter's per-interface BFD intent mirror for this device atomically.
+
+    Full-replace: rows not in the body are deleted. ``accepted_at`` defaults to now.
+    If ``auto_apply`` is enabled, an apply job is enqueued; the single device Apply
+    commits these via the bfd-reconciler.
+    """
+    device = await db.get(Device, device_id)
+    if device is None:
+        raise api_error(404, "not_found", "Device not found")
+
+    existing = await db.execute(select(BfdIntent).where(BfdIntent.device_id == device_id))
+    existing_rows: dict[str, BfdIntent] = {r.interface_name: r for r in existing.scalars().all()}
+    new_keys = {i.interface_name for i in body.interfaces}
+
+    removed = [name for name in existing_rows if name not in new_keys]
+    for name in removed:
+        await db.delete(existing_rows[name])
+    await db.flush()
+
+    now = datetime.now(UTC)
+    count = 0
+    cleared = False
+    for item in body.interfaces:
+        accepted = item.accepted_at if item.accepted_at else now
+        row = existing_rows.get(item.interface_name)
+        before = {f: getattr(row, f) for f in _STATE_FIELDS} if row is not None else None
+        if row is None:
+            row = BfdIntent(device_id=device_id, interface_name=item.interface_name)
+            db.add(row)
+        row.min_tx = item.min_tx
+        row.min_rx = item.min_rx
+        row.multiplier = item.multiplier
+        row.micro_bfd = item.micro_bfd
+        row.accepted_at = accepted
+        if before is not None and any(is_cleared(before[f], getattr(row, f)) for f in _STATE_FIELDS):
+            cleared = True
+        count += 1
+
+    await db.flush()
+    settings = (
+        await db.execute(select(DeviceSettings).where(DeviceSettings.device_id == device_id))
+    ).scalar_one_or_none()
+    if settings and settings.auto_apply and count > 0:
+        from nso_adapter.core.apply import enqueue_apply
+
+        await enqueue_apply(db, device_id, force=True)
+
+    await db.commit()
+
+    replaced = False
+    if removed or cleared:
+        from nso_adapter.core.removal import replace_on_removal
+        from nso_adapter.nso.apply import apply_bfd_config
+
+        replaced = await replace_on_removal(db, device, removed, BfdIntent, apply_bfd_config, retract=cleared)
+
+    return {"device_id": device_id, "count": count, "removed": len(removed), "replaced": replaced}