clabgen 0.3.0__py3-none-any.whl

clabgen/__init__.py

@@ -0,0 +1,18 @@
+"""Python client for clabgen agents, with helpers for pytest.
+
+    from clabgen import Lab
+
+    lab = Lab.from_docker("b2b")
+    with lab.measure() as m:
+        lab["gen2"].port_down("eth1")
+        ...
+    m.assert_pass()
+"""
+
+from ._connect import ClabgenError
+from .agent import Agent, merge, pcap_data, wait_until
+from .lab import FlowResult, FlowsFailed, Lab, Measurement
+
+__version__ = "0.3.0"
+
+__all__ = ["Agent", "ClabgenError", "FlowResult", "FlowsFailed", "Lab", "Measurement", "merge", "pcap_data", "wait_until", "__version__"]

clabgen/_connect.py

@@ -0,0 +1,136 @@
+"""Connect protocol (JSON encoding) over plain HTTP, standard library only.
+
+Unary calls are a POST of the request as JSON. Server-streaming calls send
+and receive enveloped messages: a flags byte, a 4-byte big-endian length,
+then the JSON; the end-of-stream message (flag 0x02) carries any error.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import struct
+import urllib.error
+import urllib.request
+from datetime import datetime
+from typing import Any, Iterator
+
+SERVICE = "clabgen.v1.AgentService"
+
+# Fields holding free-form JSON (google.protobuf.Struct): their keys are the
+# protocols' own and are left alone.
+_STRUCT_FIELDS = {"config", "status", "stats", "args", "result", "data", "spec"}
+# 64-bit integers, which protobuf's JSON mapping sends as strings.
+_INT64_FIELDS = {"rx_frames", "rx_bytes", "tx_frames", "tx_bytes", "tx_errors", "rx_unmatched", "age_ms", "rtt_us"}
+_TIME_FIELDS = {"start_time", "time"}
+
+
+class ClabgenError(Exception):
+    """An error from an agent: code is Connect's ("not_found", "invalid_argument", …)."""
+
+    def __init__(self, code: str, message: str, method: str = ""):
+        super().__init__(f"{method}: {code}: {message}" if method else f"{code}: {message}")
+        self.code = code
+        self.message = message
+        self.method = method
+
+
+def _snake(name: str) -> str:
+    return re.sub(r"(?<=[a-z0-9])([A-Z])", r"_\1", name).lower()
+
+
+def _time(s: str) -> datetime:
+    # Python before 3.11 can't parse "Z" or more than 6 fraction digits.
+    s = s.replace("Z", "+00:00")
+    s = re.sub(r"(\.\d{6})\d+", r"\1", s)
+    return datetime.fromisoformat(s)
+
+
+def from_wire(v: Any) -> Any:
+    """Convert a decoded response: snake_case field names, ints and datetimes."""
+    if isinstance(v, list):
+        return [from_wire(x) for x in v]
+    if not isinstance(v, dict):
+        return v
+    out = {}
+    for k, x in v.items():
+        k = _snake(k)
+        if k in _STRUCT_FIELDS:
+            out[k] = x
+        elif k == "counters" and isinstance(x, dict):
+            # Port counters (a message) and device IP counters (a map): all uint64.
+            out[k] = {_snake(ck): int(cv) if isinstance(cv, str) and cv.isdigit() else cv for ck, cv in x.items()}
+        elif k in _INT64_FIELDS and isinstance(x, str):
+            out[k] = int(x)
+        elif k in _TIME_FIELDS and isinstance(x, str):
+            out[k] = _time(x)
+        else:
+            out[k] = from_wire(x)
+    return out
+
+
+def _error(method: str, body: bytes, status: int) -> ClabgenError:
+    try:
+        e = json.loads(body)
+        return ClabgenError(e.get("code", "unknown"), e.get("message", ""), method)
+    except ValueError:
+        return ClabgenError("unknown", f"HTTP {status}: {body[:200].decode(errors='replace')}", method)
+
+
+class Transport:
+    """Calls one agent's AgentService at base_url (http://host:8080, or a
+    clabgen-ui proxy path like http://host:8090/agents/clab-b2b-gen1)."""
+
+    def __init__(self, base_url: str, timeout: float = 10.0):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _url(self, method: str) -> str:
+        return f"{self.base_url}/{SERVICE}/{method}"
+
+    def call(self, method: str, request: dict | None = None, timeout: float | None = None) -> dict:
+        data = json.dumps(request or {}).encode()
+        req = urllib.request.Request(
+            self._url(method), data=data, method="POST",
+            headers={"Content-Type": "application/json", "Connect-Protocol-Version": "1"},
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=timeout or self.timeout) as r:
+                return from_wire(json.loads(r.read() or b"{}"))
+        except urllib.error.HTTPError as e:
+            raise _error(method, e.read(), e.code) from None
+        except urllib.error.URLError as e:
+            raise ClabgenError("unavailable", str(e.reason), method) from None
+
+    def stream(self, method: str, request: dict | None = None, timeout: float | None = None) -> Iterator[dict]:
+        """Server-streaming call; timeout is per read (None: wait forever).
+        The call is made before this returns, so nothing sent after it is
+        missed; the messages come from the returned iterator."""
+        payload = json.dumps(request or {}).encode()
+        req = urllib.request.Request(
+            self._url(method), data=struct.pack(">BI", 0, len(payload)) + payload, method="POST",
+            headers={"Content-Type": "application/connect+json", "Connect-Protocol-Version": "1"},
+        )
+        try:
+            r = urllib.request.urlopen(req, timeout=timeout)
+        except urllib.error.HTTPError as e:
+            raise _error(method, e.read(), e.code) from None
+        except urllib.error.URLError as e:
+            raise ClabgenError("unavailable", str(e.reason), method) from None
+        return self._messages(method, r)
+
+    @staticmethod
+    def _messages(method: str, r: Any) -> Iterator[dict]:
+        with r:
+            while True:
+                head = r.read(5)
+                if len(head) < 5:
+                    return
+                flags, n = struct.unpack(">BI", head)
+                msg = json.loads(r.read(n) or b"{}")
+                if flags & 0x02:
+                    if "error" in msg:
+                        e = msg["error"]
+                        raise ClabgenError(e.get("code", "unknown"), e.get("message", ""), method)
+                    return
+                yield from_wire(msg)

clabgen/agent.py

@@ -0,0 +1,321 @@
+"""One clabgen agent: everything clabgenctl and the web UI can do."""
+
+from __future__ import annotations
+
+import base64
+import copy
+import time
+from pathlib import Path
+from typing import Any, Callable, Iterable, Iterator
+
+from ._connect import ClabgenError, Transport
+
+
+def _base_url(address: str) -> str:
+    if "://" in address:
+        return address
+    host, sep, port = address.rpartition(":")
+    if not sep or not port.isdigit() or host.endswith(":"):  # no port, or a bare IPv6 address
+        host, port = address, "8080"
+    if ":" in host and not host.startswith("["):
+        host = f"[{host}]"
+    return f"http://{host}:{port}"
+
+
+def _vlan(v: Any) -> dict:
+    """A VLAN tag from 100, "100", "100.5" (PCP), "0x88a8:200" or a dict."""
+    if isinstance(v, dict):
+        return v
+    if isinstance(v, int):
+        return {"vid": v}
+    s, tag = str(v), {}
+    if ":" in s:
+        tpid, s = s.split(":", 1)
+        tag["tpid"] = int(tpid, 0)
+    if "." in s:
+        s, pcp = s.split(".", 1)
+        tag["pcp"] = int(pcp)
+    tag["vid"] = int(s)
+    return tag
+
+
+def pcap_data(capture: str | Path | bytes) -> str:
+    """A capture (a pcap or pcapng file's path, or its bytes) as the packet
+    type's pcap.data: add_protocol("r", "packet", "d1", pcap={"data": pcap_data("x.pcap")})."""
+    raw = capture if isinstance(capture, bytes) else Path(capture).read_bytes()
+    return base64.b64encode(raw).decode()
+
+
+def merge(dst: dict, src: dict) -> dict:
+    """Deep-merge src onto dst (nested dicts merged, everything else replaced)."""
+    for k, v in src.items():
+        if isinstance(v, dict) and isinstance(dst.get(k), dict):
+            merge(dst[k], v)
+        else:
+            dst[k] = v
+    return dst
+
+
+def wait_until(check: Callable[[], Any], timeout: float = 30, interval: float = 0.5, what: str = "condition") -> Any:
+    """Call check until it returns something truthy (returned), or raise
+    TimeoutError after timeout seconds. Errors from check propagate."""
+    end = time.monotonic() + timeout
+    while True:
+        v = check()
+        if v:
+            return v
+        if time.monotonic() >= end:
+            raise TimeoutError(f"timed out after {timeout:g}s waiting for {what}")
+        time.sleep(interval)
+
+
+class Agent:
+    """A clabgen agent's API.
+
+    address is host[:port] (port 8080 by default), e.g. "clab-b2b-gen1", or a
+    URL: "http://172.20.20.2:8080", or an agent behind clabgen-ui,
+    "http://host:8090/agents/clab-b2b-gen1".
+
+    Methods return the API's objects as dicts with snake_case keys. Protocol
+    configs and statuses are as each protocol type defines them (see
+    `types()` or `clabgenctl types TYPE`).
+    """
+
+    def __init__(self, address: str, timeout: float = 10.0, name: str | None = None):
+        self.url = _base_url(address)
+        self.name = name or address
+        self._t = Transport(self.url, timeout)
+        self._traffic: set[str] | None = None
+
+    def __repr__(self) -> str:
+        return f"Agent({self.name!r}, url={self.url!r})"
+
+    def call(self, method: str, request: dict | None = None, **kw: Any) -> dict:
+        """Any AgentService method by name, e.g. call("ListPorts")."""
+        return self._t.call(method, request, **kw)
+
+    # Agent and ports.
+
+    def info(self) -> dict:
+        """hostname, version and start_time."""
+        return self.call("GetInfo")
+
+    def ports(self) -> list[dict]:
+        return self.call("ListPorts").get("ports", [])
+
+    def port(self, name: str) -> dict:
+        for p in self.ports():
+            if p["name"] == name:
+                return p
+        raise ClabgenError("not_found", f"port {name}", "ListPorts")
+
+    def set_port(self, name: str, up: bool) -> dict:
+        return self.call("SetPortAdmin", {"name": name, "up": up})["port"]
+
+    def port_down(self, name: str) -> dict:
+        return self.set_port(name, False)
+
+    def port_up(self, name: str) -> dict:
+        return self.set_port(name, True)
+
+    # Devices.
+
+    def devices(self) -> list[dict]:
+        return self.call("ListDevices").get("devices", [])
+
+    def device(self, name: str) -> dict:
+        for d in self.devices():
+            if d["name"] == name:
+                return d
+        raise ClabgenError("not_found", f"device {name}", "ListDevices")
+
+    def add_device(self, name: str, port: str = "eth1", *, vlans: Iterable[Any] = (), mac: str = "",
+                   addresses: Iterable[str] = (), gateway4: str = "", gateway6: str = "") -> dict:
+        """Create a device. vlans are outermost first: 100, "100.5" (with PCP),
+        "0x88a8:200" or {"tpid":…, "vid":…, "pcp":…}. An empty mac is derived."""
+        d = {"name": name, "port": port, "mac": mac, "vlans": [_vlan(v) for v in vlans],
+             "addresses": list(addresses), "gateway4": gateway4, "gateway6": gateway6}
+        return self.call("CreateDevice", {"device": d})["device"]
+
+    def update_device(self, name: str, **changes: Any) -> dict:
+        """Change some of a device's fields (port, mac, vlans, addresses,
+        gateway4, gateway6); the rest stay as they are."""
+        d = self.device(name)
+        if "vlans" in changes:
+            changes["vlans"] = [_vlan(v) for v in changes["vlans"]]
+        d.update(changes)
+        for k in ("mac_derived", "group"):
+            d.pop(k, None)
+        return self.call("UpdateDevice", {"device": d})["device"]
+
+    def delete_device(self, name: str) -> None:
+        self.call("DeleteDevice", {"name": name})
+
+    def device_ip(self, name: str) -> dict:
+        """Effective addresses, gateways, neighbors and IP counters."""
+        return self.call("GetDeviceIP", {"name": name})
+
+    def resolve(self, device: str, ip: str) -> dict:
+        """ARP/ND for ip (or its gateway): next_hop, mac, cached, rtt_us."""
+        return self.call("ResolveNeighbor", {"device": device, "ip": ip})
+
+    def clear_neighbors(self, device: str) -> None:
+        self.call("ClearNeighbors", {"device": device})
+
+    # Protocols (including traffic flows).
+
+    def types(self) -> list[dict]:
+        """Protocol types with their config and action schemas (JSON strings)."""
+        return self.call("ListProtocolTypes").get("types", [])
+
+    def protocols(self, type: str | None = None, *, status: bool = True, brief: bool = False,
+                  group_members: bool = True) -> list[dict]:
+        r = self.call("ListProtocols", {"with_status": status, "brief": brief, "no_group_members": not group_members})
+        ps = r.get("protocols", [])
+        return [p for p in ps if p["type"] == type] if type else ps
+
+    def protocol(self, name: str) -> dict:
+        return self.call("GetProtocol", {"name": name})["protocol"]
+
+    def status(self, name: str) -> dict:
+        """A protocol's live status."""
+        return self.protocol(name).get("status", {})
+
+    def add_protocol(self, name: str, type: str, device: str = "", config: dict | None = None, **fields: Any) -> dict:
+        """Create a protocol instance; keyword arguments are config fields
+        (merged onto config), e.g. add_protocol("p", "icmp", "d1", destination="10.0.0.2", rate=50)."""
+        cfg = merge(copy.deepcopy(config or {}), fields)
+        return self.call("CreateProtocol", {"protocol": {"name": name, "type": type, "device": device, "config": cfg}})["protocol"]
+
+    def update_protocol(self, name: str, config: dict | None = None, *, replace: bool = False, **fields: Any) -> dict:
+        """Change a protocol's config and restart it. By default config and the
+        keyword fields are merged onto the current config (like clabgenctl
+        proto set); replace=True sends them as the whole config."""
+        changes = merge(copy.deepcopy(config or {}), fields)
+        cfg = changes if replace else merge(copy.deepcopy(self.protocol(name).get("config", {})), changes)
+        return self.call("UpdateProtocol", {"name": name, "config": cfg})["protocol"]
+
+    def preview(self, device: str, config: dict | None = None, *, type: str = "packet", index: int = 0,
+                pcap: str | Path | bytes | None = None, **fields: Any) -> dict:
+        """What a config would send from device, without creating anything
+        (the packet builder's preview): hex, summary, and layers with their
+        fields. index picks the packet (modifiers change fields per packet)
+        or the captured frame; pcap is a capture to replay (a path or bytes)."""
+        cfg = merge(copy.deepcopy(config or {}), fields)
+        if pcap is not None:
+            merge(cfg, {"pcap": {"data": pcap_data(pcap)}})
+        r = self.call("PreviewProtocol", {"type": type, "device": device, "config": cfg, "args": {"index": index}})
+        return r.get("result", {})
+
+    def delete_protocol(self, name: str) -> None:
+        self.call("DeleteProtocol", {"name": name})
+
+    def disable(self, name: str) -> dict:
+        """Stop a protocol but keep its config (state "disabled")."""
+        return self.call("SetProtocolDisabled", {"name": name, "disabled": True})["protocol"]
+
+    def enable(self, name: str) -> dict:
+        return self.call("SetProtocolDisabled", {"name": name, "disabled": False})["protocol"]
+
+    def run(self, name: str, action: str, args: dict | None = None, **fields: Any) -> dict:
+        """Run a protocol action, e.g. run("mep1", "loopback", target_mep_id=2, count=5)."""
+        a = merge(copy.deepcopy(args or {}), fields)
+        return self.call("RunProtocolAction", {"name": name, "action": action, "args": a}).get("result", {})
+
+    # Traffic flows.
+
+    def traffic_types(self) -> set[str]:
+        """Names of the protocol types that are traffic flows (icmp, udp, l2, …)."""
+        if self._traffic is None:
+            self._traffic = {t["name"] for t in self.types() if t.get("category") == "traffic"}
+        return self._traffic
+
+    def flows(self) -> list[dict]:
+        """Traffic flow instances with their statuses."""
+        traffic = self.traffic_types()
+        return [p for p in self.protocols(group_members=False) if p["type"] in traffic]
+
+    def start(self, *flows: str) -> None:
+        for f in flows:
+            self.run(f, "start")
+
+    def stop(self, *flows: str) -> None:
+        for f in flows:
+            self.run(f, "stop")
+
+    def received(self, device: str = "") -> list[dict]:
+        """Flows received by this agent's devices: one dict per flow and
+        device, with "device" and the one-way statistics (rx, lost, loss_pct,
+        reordered, duplicate, latency_*_us, outages, outage_max_ms, …)."""
+        flows = self.call("ListReceivedFlows", {"device": device}).get("flows", [])
+        return [{"device": f["device"], **f.get("stats", {})} for f in flows]
+
+    def clear_received(self, device: str = "", flow_id: str = "") -> None:
+        self.call("ClearReceivedFlows", {"device": device, "flow_id": flow_id})
+
+    # Device groups.
+
+    def groups(self) -> list[dict]:
+        return self.call("ListDeviceGroups").get("groups", [])
+
+    def group(self, name: str, members: bool = True) -> dict:
+        return self.call("GetDeviceGroup", {"name": name, "summary_only": not members})["group"]
+
+    def add_group(self, spec: dict | str) -> dict:
+        """Create a device group from a spec dict or its YAML."""
+        g = {"yaml": spec} if isinstance(spec, str) else {"name": spec["name"], "spec": spec}
+        return self.call("CreateDeviceGroup", {"group": g})["group"]
+
+    def update_group(self, spec: dict | str) -> dict:
+        g = {"yaml": spec} if isinstance(spec, str) else {"name": spec["name"], "spec": spec}
+        return self.call("UpdateDeviceGroup", {"group": g})["group"]
+
+    def delete_group(self, name: str) -> None:
+        self.call("DeleteDeviceGroup", {"name": name})
+
+    def run_group(self, group: str, action: str, args: dict | None = None, *, protocol: str = "",
+                  members: str = "", random: int = 0, **fields: Any) -> list[dict]:
+        """Run an action on a group protocol's members: members is "" (all) or
+        1-based indices and ranges like "1-10,15"; random picks that many of them."""
+        a = merge(copy.deepcopy(args or {}), fields)
+        r = self.call("RunGroupAction", {"group": group, "protocol": protocol, "action": action, "args": a,
+                                         "members": members, "random": random})
+        return r.get("results", [])
+
+    def set_group_disabled(self, group: str, disabled: bool, *, protocol: str = "", members: str = "",
+                           random: int = 0) -> list[dict]:
+        r = self.call("SetGroupDisabled", {"group": group, "protocol": protocol, "members": members,
+                                           "random": random, "disabled": disabled})
+        return r.get("results", [])
+
+    # Scenario and events.
+
+    def scenario(self) -> str:
+        """The whole config as YAML."""
+        return self.call("GetScenario").get("yaml", "")
+
+    def apply_scenario(self, scenario: str | Path, replace: bool = False) -> None:
+        """Apply a scenario: YAML text, or a Path to a YAML file. replace=True
+        removes existing devices and protocols first. Without it, items that
+        already exist fail: everything else is applied, then ClabgenError
+        lists what failed."""
+        if isinstance(scenario, Path):
+            scenario = scenario.read_text()
+        self.call("ApplyScenario", {"yaml": scenario, "replace": replace}, timeout=60)
+
+    def events(self, replay: bool = False, timeout: float | None = None) -> Iterator[dict]:
+        """Stream events (time, source, kind, message, data) as they happen;
+        replay=True starts with the buffered recent ones. timeout bounds each
+        wait for the next event (TimeoutError / socket.timeout when it passes)."""
+        return self._t.stream("WatchEvents", {"replay": replay}, timeout=timeout)
+
+    # Waiting.
+
+    def wait_protocol(self, name: str, check: Callable[[dict], Any], timeout: float = 30,
+                      interval: float = 0.5, what: str = "") -> dict:
+        """Poll a protocol until check(protocol) is truthy; returns the protocol.
+        E.g. wait_protocol("bgp1", lambda p: p["status"]["peers"][0]["state"] == "established")."""
+        def once() -> dict | None:
+            p = self.protocol(name)
+            return p if check(p) else None
+        return wait_until(once, timeout, interval, what or f"{self.name}/{name}")

clabgen/lab.py

@@ -0,0 +1,306 @@
+"""A lab: several agents, and traffic flows judged across all of them."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Iterator, Mapping
+
+from ._connect import ClabgenError
+from .agent import Agent, wait_until
+
+
+@dataclass
+class FlowResult:
+    """One traffic flow's measurement.
+
+    verdict is "pass", "fail" or "pending" (nothing measured yet), or None
+    when the flow has no checks. failed names the failed checks, e.g.
+    "loss_pct 2.6 > 1, outage_ms 2030 > 50". For one-way flows (no replies)
+    the agent can't judge loss, so rx, lost and loss_pct are the receivers'
+    totals and the verdict stays "pending".
+    """
+
+    agent: str
+    name: str
+    type: str
+    device: str
+    state: str
+    flow_id: str
+    one_way: bool
+    verdict: str | None
+    failed: str
+    tx: int
+    rx: int
+    lost: int
+    loss_pct: float
+    outage_max_ms: float
+    rtt_avg_ms: float | None
+    status: dict = field(repr=False)
+    received: list[dict] = field(default_factory=list, repr=False)
+
+    @property
+    def id(self) -> str:
+        return f"{self.agent}/{self.name}"
+
+    @property
+    def passed(self) -> bool:
+        return self.verdict == "pass"
+
+    def summary(self) -> str:
+        rtt = f" rtt {self.rtt_avg_ms:.2f} ms" if self.rtt_avg_ms is not None else ""
+        v = self.verdict or "no checks"
+        if self.failed:
+            v += f" ({self.failed})"
+        way = " one way" if self.one_way else ""
+        return (f"{self.id}: {v}; tx {self.tx} rx {self.rx} lost {self.lost} ({self.loss_pct:.2f}%)"
+                f" outage {self.outage_max_ms:g} ms{rtt}{way}")
+
+
+def _result(agent: str, p: dict, received: list[dict]) -> FlowResult:
+    s = p.get("status") or {}
+    v = s.get("verdict") or {}
+    one_way = s.get("tracks_replies") is False
+    rx, lost, loss_pct = s.get("rx", 0), s.get("lost", 0), s.get("loss_pct", 0.0)
+    outage = s.get("outage_max_ms", 0.0)
+    if one_way:
+        rx = sum(r.get("rx", 0) for r in received)
+        lost = sum(r.get("lost", 0) for r in received)
+        loss_pct = 100.0 * lost / (rx + lost) if rx + lost else 0.0
+        outage = max([r.get("outage_max_ms", 0.0) for r in received], default=0.0)
+    rtt = s.get("rtt") or {}
+    return FlowResult(
+        agent=agent, name=p["name"], type=p["type"], device=p.get("device", ""), state=s.get("state", p.get("state", "")),
+        flow_id=s.get("flow_id", ""), one_way=one_way, verdict=v.get("result"), failed=v.get("failed", ""),
+        tx=s.get("tx", 0), rx=rx, lost=lost, loss_pct=loss_pct, outage_max_ms=outage,
+        rtt_avg_ms=rtt["avg_us"] / 1000 if "avg_us" in rtt else None, status=s, received=received,
+    )
+
+
+class FlowsFailed(AssertionError):
+    def __init__(self, failed: list[FlowResult], results: list[FlowResult]):
+        lines = [f"{len(failed)} of {len(results)} flows failed:"] + ["  " + r.summary() for r in failed]
+        super().__init__("\n".join(lines))
+        self.failed = failed
+        self.results = results
+
+
+class Measurement:
+    """What Lab.measure() measured; results is set when the with block ends."""
+
+    def __init__(self, lab: "Lab", flows: list[tuple[str, str]]):
+        self.lab = lab
+        self.flows = flows
+        self.started = time.time()
+        self.results: list[FlowResult] = []
+
+    def __getitem__(self, flow: str) -> FlowResult:
+        matches = [r for r in self.results if flow in (r.id, r.name)]
+        if len(matches) != 1:
+            raise KeyError(f"{flow!r}: {'no flow' if not matches else 'ambiguous, use agent/name'}")
+        return matches[0]
+
+    @property
+    def failed(self) -> list[FlowResult]:
+        return _failures(self.results, False)
+
+    def assert_pass(self, require_checks: bool = False) -> None:
+        """Raise FlowsFailed (an AssertionError) if a flow failed its checks,
+        or an echo flow with checks measured nothing; require_checks=True
+        also fails flows without checks."""
+        failed = _failures(self.results, require_checks)
+        if failed:
+            raise FlowsFailed(failed, self.results)
+
+
+def _failures(results: list[FlowResult], require_checks: bool) -> list[FlowResult]:
+    out = []
+    for r in results:
+        if r.verdict == "fail" or (r.verdict == "pending" and not r.one_way) or (r.verdict is None and require_checks):
+            out.append(r)
+    return out
+
+
+def _docker_agents(lab: str) -> dict[str, str]:
+    ids = subprocess.run(["docker", "ps", "-q", "--filter", f"label=containerlab={lab}"],
+                         check=True, capture_output=True, text=True).stdout.split()
+    if not ids:
+        return {}
+    out = {}
+    for c in json.loads(subprocess.run(["docker", "inspect", *ids], check=True, capture_output=True, text=True).stdout):
+        name = c["Config"]["Labels"].get("clab-node-name") or c["Name"].lstrip("/")
+        ips = [n.get("IPAddress") for n in c["NetworkSettings"]["Networks"].values() if n.get("IPAddress")]
+        if ips:
+            out[name] = ips[0]
+    return out
+
+
+class Lab(Mapping[str, Agent]):
+    """Agents by name. Build one from a containerlab lab on this host
+    (Lab.from_docker("b2b")), from a clabgen-ui (Lab.from_ui(url, "b2b")),
+    or from agents: Lab({"gen1": Agent("clab-b2b-gen1"), …})."""
+
+    def __init__(self, agents: Mapping[str, Agent] | Iterable[Agent]):
+        if isinstance(agents, Mapping):
+            self.agents = dict(agents)
+        else:
+            self.agents = {a.name: a for a in agents}
+        for name, a in self.agents.items():
+            a.name = name
+
+    @classmethod
+    def from_docker(cls, lab: str, timeout: float = 10.0) -> "Lab":
+        """The clabgen agents of a running containerlab lab, by node name
+        (nodes that don't answer the agent API are left out)."""
+        nodes = _docker_agents(lab)
+
+        def probe(item: tuple[str, str]) -> Agent | None:
+            a = Agent(item[1], timeout=timeout, name=item[0])
+            try:
+                a.call("GetInfo", timeout=2)
+                return a
+            except ClabgenError:
+                return None
+
+        with ThreadPoolExecutor(max_workers=16) as ex:
+            found = [a for a in ex.map(probe, sorted(nodes.items())) if a]
+        if not found:
+            raise ClabgenError("not_found", f"no clabgen agents in lab {lab!r}")
+        return cls(found)
+
+    @classmethod
+    def from_ui(cls, url: str, lab: str | None = None, timeout: float = 10.0) -> "Lab":
+        """Agents known to a clabgen-ui (e.g. http://host:8090), reached
+        through its proxy; lab picks one lab's. Names are node names, or
+        agent IDs when that would be ambiguous."""
+        url = url.rstrip("/")
+        with urllib.request.urlopen(f"{url}/api/agents", timeout=timeout) as r:
+            agents = [a for a in json.load(r).get("agents", []) if lab is None or a.get("lab") == lab]
+        if not agents:
+            raise ClabgenError("not_found", f"no agents{f' in lab {lab!r}' if lab else ''} at {url}")
+        names = [a.get("name") or a["id"] for a in agents]
+        unique = len(set(names)) == len(names)
+        return cls({(n if unique else a["id"]): Agent(f"{url}/agents/{a['id']}", timeout=timeout)
+                    for n, a in zip(names, agents)})
+
+    def __getitem__(self, name: str) -> Agent:
+        return self.agents[name]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self.agents)
+
+    def __len__(self) -> int:
+        return len(self.agents)
+
+    def __repr__(self) -> str:
+        return f"Lab({list(self.agents)})"
+
+    def _each(self, fn: Any) -> dict[str, Any]:
+        with ThreadPoolExecutor(max_workers=max(1, len(self.agents))) as ex:
+            futs = {n: ex.submit(fn, a) for n, a in self.agents.items()}
+            return {n: f.result() for n, f in futs.items()}
+
+    # Flows.
+
+    def _select(self, flows: Iterable[str] | None) -> list[tuple[str, str]]:
+        all_flows = [(n, p["name"]) for n, ps in self._each(lambda a: a.flows()).items() for p in ps]
+        if flows is None:
+            return all_flows
+        out = []
+        for f in [flows] if isinstance(flows, str) else flows:
+            m = [x for x in all_flows if f in (f"{x[0]}/{x[1]}", x[1])]
+            if len(m) != 1:
+                raise KeyError(f"{f!r}: {'no such flow' if not m else 'ambiguous, use agent/name'}")
+            out.append(m[0])
+        return out
+
+    def flow_results(self, flows: Iterable[str] | None = None) -> list[FlowResult]:
+        """Every flow (or the ones named "agent/name" or "name"), with what
+        it measured since its start or last clear."""
+        sel = set(self._select(flows))
+        protos = self._each(lambda a: a.flows())
+        received: dict[str, list[dict]] = {}
+        for n, rs in self._each(lambda a: a.received()).items():
+            for r in rs:
+                received.setdefault(r.get("flow_id", ""), []).append({"agent": n, **r})
+        out = []
+        for n, ps in protos.items():
+            for p in ps:
+                if (n, p["name"]) in sel:
+                    fid = (p.get("status") or {}).get("flow_id", "")
+                    out.append(_result(n, p, received.get(fid, []) if fid else []))
+        return out
+
+    def clear_flows(self, flows: Iterable[str] | None = None) -> None:
+        """Reset flows' statistics at the senders and at every receiver."""
+        sel = set(self._select(flows))
+        ids = set()
+        for n, ps in self._each(lambda a: a.flows()).items():
+            for p in ps:
+                if (n, p["name"]) in sel:
+                    self.agents[n].run(p["name"], "clear")
+                    ids.add((p.get("status") or {}).get("flow_id", ""))
+        for fid in ids - {""}:
+            self._each(lambda a, fid=fid: a.clear_received(flow_id=fid))
+
+    def start_flows(self, flows: Iterable[str] | None = None) -> None:
+        for n, name in self._select(flows):
+            try:
+                self.agents[n].run(name, "start")
+            except ClabgenError as e:
+                if "already running" not in e.message:
+                    raise
+
+    def stop_flows(self, flows: Iterable[str] | None = None) -> None:
+        for n, name in self._select(flows):
+            try:
+                self.agents[n].run(name, "stop")
+            except ClabgenError as e:
+                if "not running" not in e.message:
+                    raise
+
+    @contextmanager
+    def measure(self, flows: Iterable[str] | None = None, settle: float = 2.0) -> Iterator[Measurement]:
+        """Clear flows, run the with block (the test: flap a link, fail a
+        node, …), wait settle seconds for packets in flight to be answered or
+        time out, then collect the results:
+
+            with lab.measure() as m:
+                lab["gen2"].port_down("eth1"); time.sleep(2); lab["gen2"].port_up("eth1")
+            m.assert_pass()
+
+        settle should be at least the flows' reply timeout (1 s by default).
+        """
+        sel = self._select(flows)
+        names = [f"{n}/{f}" for n, f in sel]
+        if sel:
+            self.clear_flows(names)
+        m = Measurement(self, sel)
+        yield m
+        time.sleep(settle)
+        m.results = self.flow_results(names) if sel else []
+
+    def wait_flows_pass(self, flows: Iterable[str] | None = None, timeout: float = 60, interval: float = 1) -> list[FlowResult]:
+        """Wait until every flow with checks passes, e.g. while a lab
+        converges after deploying. A failed verdict stays until the flow is
+        cleared, so failed flows are cleared each round: this returns once
+        all of them have passed since their last failure."""
+        last: list[FlowResult] = []
+
+        def ok() -> bool:
+            nonlocal last
+            last = self.flow_results(flows)
+            if failed := [r.id for r in last if r.verdict == "fail"]:
+                self.clear_flows(failed)
+            return not [r for r in last if r.verdict is not None and r.verdict != "pass" and not r.one_way]
+        try:
+            wait_until(ok, timeout, interval, "flows to pass")
+        except TimeoutError as e:
+            bad = [r for r in last if r.verdict is not None and r.verdict != "pass" and not r.one_way]
+            raise TimeoutError(f"{e}:\n" + "\n".join("  " + r.summary() for r in bad)) from None
+        return last

clabgen/pytest_plugin.py

@@ -0,0 +1,40 @@
+"""pytest fixtures for clabgen labs (loaded automatically once installed).
+
+    pytest --clabgen-lab b2b                      # a containerlab lab on this host
+    pytest --clabgen-lab b2b --clabgen-ui http://host:8090   # through a clabgen-ui
+
+    def test_failover(clabgen_lab):
+        with clabgen_lab.measure() as m:
+            clabgen_lab["gen2"].port_down("eth1")
+            ...
+        m.assert_pass()
+
+Tests using clabgen_lab are skipped when no lab is given.
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+from .lab import Lab
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    g = parser.getgroup("clabgen")
+    g.addoption("--clabgen-lab", default=None, help="containerlab lab whose clabgen agents tests use (env CLABGEN_LAB)")
+    g.addoption("--clabgen-ui", default=None, help="reach the agents through this clabgen-ui, e.g. http://host:8090 (env CLABGEN_UI)")
+
+
+def _opt(config: pytest.Config, name: str) -> str | None:
+    return config.getoption(name) or os.environ.get(name.lstrip("-").replace("-", "_").upper())
+
+
+@pytest.fixture(scope="session")
+def clabgen_lab(pytestconfig: pytest.Config) -> Lab:
+    """The lab's agents (clabgen.Lab), by node name."""
+    lab, ui = _opt(pytestconfig, "--clabgen-lab"), _opt(pytestconfig, "--clabgen-ui")
+    if not lab and not ui:
+        pytest.skip("no clabgen lab (--clabgen-lab or CLABGEN_LAB)")
+    return Lab.from_ui(ui, lab) if ui else Lab.from_docker(lab)

clabgen-0.3.0.dist-info/METADATA

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: clabgen
+Version: 0.3.0
+Summary: Python client and pytest helpers for clabgen, the protocol emulator and traffic generator for containerlab
+Author-email: Tom Young <ripnet@gmail.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/ripnet/clabgen
+Classifier: Framework :: Pytest
+Classifier: Topic :: System :: Networking
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# clabgen (Python)
+
+Python client and pytest helpers for
+[clabgen](https://github.com/ripnet/clabgen), the protocol emulator and
+traffic generator for containerlab. Standard library only; Python 3.9+.
+
+```sh
+pip install clabgen
+```
+
+Installing from a checkout or from git builds the package: Ubuntu 22.04's
+own pip 22.0 builds it as `UNKNOWN`, so use a newer pip there (e.g. in a
+virtualenv after `pip install -U pip`).
+
+```python
+def test_failover(clabgen_lab):              # pytest --clabgen-lab b2b
+    with clabgen_lab.measure() as m:
+        clabgen_lab["gen2"].port_down("eth1")
+        time.sleep(2)
+        clabgen_lab["gen2"].port_up("eth1")
+    m.assert_pass()
+```
+
+See [docs/python.md](https://github.com/ripnet/clabgen/blob/main/docs/python.md).
+
+Tests: `pytest` here. The unit tests need nothing; the `agent` tests run
+the agent binary (`make build` at the top, or `CLABGEN_AGENT=path`) in a
+container, so they need docker, and are skipped without it.

clabgen-0.3.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+clabgen/__init__.py,sha256=B5HSlZQoyUID3ODW5RJLORuvy1TuTvU2Bh_Ts7nkGD4,540
+clabgen/_connect.py,sha256=RYroIvCEsvKk1HmI2VjACtN-ML9KcDjXJ0FmnVFqdpA,5469
+clabgen/agent.py,sha256=sSvJjwOGy1EmMjFylKj9kyrZwJULMbZriiVcI1gqQ-o,14345
+clabgen/lab.py,sha256=lEAj24aWMGlZmW-yxHcGwMGjuw4OkZgwgHCnIa95ayM,12459
+clabgen/pytest_plugin.py,sha256=XGAlntf52PZCMoTbpphCbJXNCbfouwSdeteJAq8CbjE,1451
+clabgen-0.3.0.dist-info/licenses/LICENSE,sha256=op4y_Rnf00IsF-ga_reUYyCu071PhbdMrbnNZHYoJzc,1544
+clabgen-0.3.0.dist-info/METADATA,sha256=HKcIoY4UAWyObMAbT7sQp-hub4KH7jnWRROzcn2KUhU,1559
+clabgen-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+clabgen-0.3.0.dist-info/entry_points.txt,sha256=fY7mL_ltmFGkwS_n0VGHGKeFFR2V8FJvdC2FnQ6Jioc,43
+clabgen-0.3.0.dist-info/top_level.txt,sha256=oxx5s9w3VVjy224a6871-r7K4l7-Z4wmPbZDLVvLtW4,8
+clabgen-0.3.0.dist-info/RECORD,,

clabgen-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

clabgen-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+clabgen = clabgen.pytest_plugin

clabgen-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Tom Young <ripnet@gmail.com> and the clabgen contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

clabgen-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+clabgen