gini-toolkit 6.0.1.dev0__py3-none-any.whl

gini/services/boardsetup.py

@@ -0,0 +1,374 @@
+"""Set up a GINI32 board over USB, from inside gBuilder.
+
+A board needs exactly one thing it cannot get over the air: the lab Wi-Fi
+credentials. Everything else — its address, gateway, hotspot SSID, physical
+subnet — comes from the canvas once it is online. So this module exists to carry
+that one secret across the wire, and then get out of the way: a student touches
+USB once per board, ever.
+
+The transport is the board's own serial console (`gini> `), driven exactly as a
+human would drive it. That means no second protocol to keep in sync with the
+firmware — if a command works when typed, it works here.
+
+Standard library only. `pyserial` is used *if* it happens to be importable
+because it enumerates ports more informatively, but it is not required and is
+not a declared dependency: gBuilder is installed by students, and this must work
+on a machine with nothing extra on it.
+"""
+from __future__ import annotations
+
+import glob
+import os
+import re
+import sys
+import time
+from dataclasses import dataclass, field
+
+BAUD = 115200
+PROMPT = "gini> "
+BANNER = "gBridge console"
+
+# How long to wait for the prompt after opening. Opening the port pulls DTR/RTS,
+# which on most dev boards is wired to EN/BOOT and reboots the ESP32 — so the
+# first thing we see is a boot log, and the prompt only arrives after it.
+BOOT_WAIT = 6.0
+CMD_WAIT = 3.0
+
+# Serial devices that are worth *asking* whether they are a board. On macOS we
+# must use the `cu.*` ("call-up") node: opening `tty.*` blocks until carrier
+# detect, which for a USB adapter never comes, and the app would hang on open.
+_PATTERNS = (
+    "/dev/cu.usbserial*",      # FTDI
+    "/dev/cu.SLAB_USBtoUART*", # CP210x (many ESP32 devkits)
+    "/dev/cu.wchusbserial*",   # CH340 (very common on cheap boards)
+    "/dev/cu.usbmodem*",       # native USB-JTAG (ESP32-S3/C3)
+    "/dev/ttyUSB*",            # Linux
+    "/dev/ttyACM*",            # Linux
+)
+
+# Never a board, and present in numbers: macOS ships Bluetooth/debug nodes, and a
+# Linux box typically exposes 32 legacy motherboard UARTs (/dev/ttyS0..31). Listing
+# those would bury the one device the student actually plugged in.
+_NOISE = re.compile(r"(Bluetooth|debug-console|wlan-debug)", re.I)
+_NEVER = re.compile(r"^/dev/ttyS\d+$")
+
+
+def _plausible(device: str) -> bool:
+    """Could this device be a board? Cheap name test, before we try talking to it."""
+    import fnmatch
+    if _NOISE.search(device) or _NEVER.match(device):
+        return False
+    return any(fnmatch.fnmatch(device, pat) for pat in _PATTERNS)
+
+
+@dataclass
+class PortInfo:
+    device: str
+    description: str = ""
+
+    @property
+    def label(self) -> str:
+        return f"{self.device}  —  {self.description}" if self.description else self.device
+
+
+@dataclass
+class BoardInfo:
+    """What a board says about itself, from `show`."""
+    port: str
+    board_id: str = ""
+    ssid: str = ""
+    has_password: bool = False
+    server: str = ""
+    ap_ssid: str = ""
+    # The laptop holding this board's claim, "" if unclaimed. Comes from `status`, not
+    # `show` — the claim is link state, not a setting — but it is read on the same open,
+    # because opening the port reboots the board and doing it twice is a wasted six
+    # seconds per board.
+    owner: str = ""
+    extra: dict = field(default_factory=dict)
+
+    @property
+    def configured(self) -> bool:
+        """Has this board been set up before? (A fresh one still has the default.)"""
+        return bool(self.ssid) and self.has_password
+
+
+def list_ports() -> list[PortInfo]:
+    """Serial devices that could plausibly be a board, best-effort and never raising.
+
+    Uses pyserial when available (it knows the USB descriptor strings, which make
+    the picker much friendlier); otherwise falls back to globbing the device names.
+    """
+    try:
+        from serial.tools import list_ports as _lp        # type: ignore
+        out = []
+        for p in _lp.comports():
+            if sys.platform == "darwin" and "/tty." in p.device:
+                continue                                   # prefer the cu.* twin
+            if not _plausible(p.device):
+                continue                                   # ttyS0..31, Bluetooth, …
+            out.append(PortInfo(p.device, (p.description or "").strip()))
+        if out:
+            return sorted(out, key=lambda p: p.device)
+    except Exception:
+        pass                                               # fall through to globbing
+
+    seen: list[PortInfo] = []
+    for pat in _PATTERNS:
+        for dev in glob.glob(pat):
+            if _plausible(dev):
+                seen.append(PortInfo(dev))
+    return sorted({p.device: p for p in seen}.values(), key=lambda p: p.device)
+
+
+class BoardConsole:
+    """A conversation with one board over its serial console.
+
+    Deliberately dumb: write a line, read until the prompt comes back. The board
+    echoes what it receives, so every reply contains the command itself; callers
+    get the text with that echo stripped.
+    """
+
+    def __init__(self, port: str, baud: int = BAUD) -> None:
+        self.port = port
+        self.baud = baud
+        self.fd = -1
+        self.transcript = ""       # everything read, for diagnostics
+
+    # -- lifecycle -- #
+
+    def open(self) -> None:
+        # O_NONBLOCK so the open itself cannot hang even on a misbehaving device;
+        # O_NOCTTY so this never becomes our controlling terminal.
+        self.fd = os.open(self.port, os.O_RDWR | os.O_NOCTTY | os.O_NONBLOCK)
+        try:
+            self._configure()
+        except Exception:
+            self.close()
+            raise
+
+    def _configure(self) -> None:
+        """Raw mode at the board's baud rate: no echo, no line editing, 8N1."""
+        import termios
+        attrs = termios.tcgetattr(self.fd)
+        iflag, oflag, cflag, lflag, ispeed, ospeed, cc = attrs
+        # no translation, no flow control, no parity/canonical/echo
+        iflag &= ~(termios.IXON | termios.IXOFF | termios.IXANY | termios.ICRNL
+                   | termios.INLCR | termios.IGNCR | termios.ISTRIP | termios.INPCK)
+        oflag &= ~termios.OPOST
+        lflag &= ~(termios.ECHO | termios.ECHOE | termios.ECHONL
+                   | termios.ICANON | termios.ISIG | termios.IEXTEN)
+        cflag &= ~(termios.PARENB | termios.CSTOPB | termios.CSIZE)
+        cflag |= termios.CS8 | termios.CREAD | termios.CLOCAL   # CLOCAL: ignore carrier
+        speed = getattr(termios, f"B{self.baud}", termios.B115200)
+        cc = list(cc)
+        cc[termios.VMIN] = 0
+        cc[termios.VTIME] = 0
+        termios.tcsetattr(self.fd, termios.TCSANOW,
+                          [iflag, oflag, cflag, lflag, speed, speed, cc])
+
+    def close(self) -> None:
+        if self.fd >= 0:
+            try:
+                os.close(self.fd)
+            except OSError:
+                pass
+            self.fd = -1
+
+    def __enter__(self) -> "BoardConsole":
+        self.open()
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    # -- raw io -- #
+
+    def _read(self, timeout: float) -> str:
+        import select
+        try:
+            r, _, _ = select.select([self.fd], [], [], timeout)
+        except (OSError, ValueError):
+            return ""
+        if not r:
+            return ""
+        try:
+            data = os.read(self.fd, 4096)
+        except (BlockingIOError, OSError):
+            return ""
+        text = data.decode("utf-8", "replace")
+        self.transcript += text
+        return text
+
+    def _write(self, text: str) -> None:
+        data = text.encode("utf-8")
+        while data:
+            try:
+                n = os.write(self.fd, data)
+                data = data[n:]
+            except BlockingIOError:
+                time.sleep(0.01)
+
+    def read_until(self, needle: str, timeout: float) -> str:
+        """Accumulate until `needle` appears. Returns what was read (may lack it)."""
+        buf = ""
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            buf += self._read(min(0.25, max(0.01, deadline - time.monotonic())))
+            if needle in buf:
+                break
+        return buf
+
+    # -- protocol -- #
+
+    def wait_for_prompt(self, timeout: float = BOOT_WAIT) -> bool:
+        """Get the board to a prompt.
+
+        Opening the port usually reset it, so first just listen for the banner;
+        if the board was already up (no reset) a bare newline draws the prompt.
+        """
+        if PROMPT in self.read_until(PROMPT, min(2.0, timeout)):
+            return True
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            self._write("\r\n")
+            if PROMPT in self.read_until(PROMPT, 1.0):
+                return True
+        return False
+
+    def command(self, line: str, timeout: float = CMD_WAIT) -> str:
+        """Send one command; return its output without the echo or the next prompt."""
+        self._write(line + "\r\n")
+        out = self.read_until(PROMPT, timeout)
+        # the board echoes what we typed; drop that first line
+        if line in out:
+            out = out.split(line, 1)[1]
+        return out.replace(PROMPT, "").strip("\r\n \t")
+
+    def identify(self) -> BoardInfo | None:
+        """Confirm this really is a GINI32 board and read its current settings.
+
+        Returns None for anything that does not answer like one — a USB-serial
+        adapter is not evidence of firmware, so we ask rather than assume.
+        """
+        if not self.wait_for_prompt():
+            return None
+        out = self.command("show")
+        if not out:
+            return None
+        info = BoardInfo(port=self.port)
+        found = 0
+        for raw in out.splitlines():
+            parts = raw.strip().split(None, 1)
+            if len(parts) != 2:
+                continue
+            key, val = parts[0].strip(), parts[1].strip()
+            found += 1
+            if key == "id":
+                info.board_id = val
+            elif key == "ssid":
+                info.ssid = val
+            elif key == "pass":
+                info.has_password = val != "(empty)"
+            elif key == "server":
+                info.server = val
+            elif key == "apssid":
+                info.ap_ssid = val
+            else:
+                info.extra[key] = val
+        # `show` always prints several keys; anything less is not our console
+        if found < 3 or (not info.board_id and not info.ssid):
+            return None
+        # Who owns it. Best-effort: an older firmware has no `claim:` line, and not
+        # knowing the owner must never make a board look unidentifiable.
+        try:
+            st = self.command("status")
+            m = re.search(r"^claim:\s*(.+)$", st, re.M)
+            if m:
+                claim = m.group(1).strip()
+                info.owner = "" if claim.lower().startswith("unclaimed") else claim
+        except OSError:
+            pass
+        return info
+
+    def apply(self, ssid: str, password: str, board_id: str,
+              server: str = "auto", reboot: bool = True) -> tuple[bool, str]:
+        """Write the settings a board cannot discover, persist them, and restart.
+
+        Returns (ok, message). Every step is checked: a `set` that the firmware
+        rejected must not be reported as success, or a student ends up hunting a
+        network fault that is really a typo.
+        """
+        steps = [("ssid", ssid), ("pass", password), ("id", board_id)]
+        if server:
+            steps.append(("server", server))
+        for key, val in steps:
+            if val is None:
+                continue
+            out = self.command(f"set {key} {val}")
+            if "ok" not in out.lower():
+                return False, f"the board did not accept `set {key}`: {out.strip()[:120]}"
+        out = self.command("save", timeout=5.0)
+        if "saved" not in out.lower():
+            return False, f"the board did not save its settings: {out.strip()[:120]}"
+        if reboot:
+            self._write("reboot\r\n")
+            time.sleep(0.3)          # it is going away; nothing useful to read back
+        return True, f"'{board_id}' set up for network '{ssid}'"
+
+
+    def unpair(self) -> tuple[bool, str]:
+        """Release this board's claim, so another laptop can adopt it.
+
+        This is the deliberate counterpart to there being NO automatic release: a claimed
+        board must never re-open itself while its owner is away from the bench, so the
+        only way back is physical possession — and USB is what "physical possession"
+        means in software. It is also the honest recovery path for the classroom failure
+        the claim mechanism exists to prevent: a board adopted by the wrong laptop, which
+        from the student's side looks like a board that simply refuses to appear.
+        """
+        out = self.command("unpair", timeout=5.0)
+        low = out.lower()
+        if "already unclaimed" in low:
+            return True, "this board was not claimed by anyone — nothing to release"
+        if "released" in low:
+            # Echo the previous owner back: in a lab it matters WHOSE board you just took.
+            m = re.search(r"released from '([^']*)'", out)
+            who = m.group(1) if m else ""
+            return True, (f"released from {who} — any gBuilder may now claim it" if who
+                          else "released — any gBuilder may now claim it")
+        return False, f"the board did not confirm the release: {out.strip()[:120]}"
+
+
+def detect_boards(ports: list[PortInfo] | None = None) -> tuple[list[BoardInfo], list[PortInfo]]:
+    """Ask every candidate port whether it is a board.
+
+    Returns (boards, others) so the UI can both offer the real boards and say
+    something useful about the serial devices that did not answer.
+    """
+    boards: list[BoardInfo] = []
+    others: list[PortInfo] = []
+    for p in (ports if ports is not None else list_ports()):
+        try:
+            with BoardConsole(p.device) as con:
+                info = con.identify()
+        except (OSError, ImportError):
+            info = None
+        if info is not None:
+            boards.append(info)
+        else:
+            others.append(p)
+    return boards, others
+
+
+def suggest_board_id(existing: list[str]) -> str:
+    """Next free `gini-N`, so a TA setting up a stack of boards never repeats one."""
+    used = set()
+    for e in existing:
+        m = re.fullmatch(r"gini-(\d+)", (e or "").strip())
+        if m:
+            used.add(int(m.group(1)))
+    n = 1
+    while n in used:
+        n += 1
+    return f"gini-{n}"

gini/services/cloud_catalog.py

@@ -0,0 +1,143 @@
+"""Cloud service catalog — maps a palette element to a real, off-the-shelf container.
+
+The cloud-course half of GINI: instead of simulating these on the custom UDP/tun
+fabric (that's for the networking course), each managed-cloud element runs as a normal
+container from a public image on the shared `gini` Docker network, reachable by its
+service name — just like real cloud service discovery. Students draw the architecture
+in gBuilder, press Run, and get actual services they can inspect, drive, and visualise.
+
+Each `Port(container, label, web)` with web=True is an HTTP console worth opening in a
+browser; the compiler assigns a unique host port so several services don't collide.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Port:
+    container: int
+    label: str
+    web: bool = False          # True => an HTTP console to open in the browser
+    path: str = ""             # console URL path (some UIs aren't at the root, e.g. Fortio)
+
+
+@dataclass(frozen=True)
+class CloudService:
+    image: str
+    summary: str               # one line shown in the inspector / to GINI
+    command: tuple[str, ...] = ()
+    env: dict[str, str] = field(default_factory=dict)
+    ports: tuple[Port, ...] = ()
+
+
+# element type_key -> the container that backs it
+CATALOG: dict[str, CloudService] = {
+    "object_store": CloudService(
+        image="minio/minio:RELEASE.2024-10-13T13-34-11Z",
+        summary="MinIO — an S3-compatible object store. Use the AWS CLI or `mc`.",
+        command=("server", "/data", "--console-address", ":9001"),
+        env={"MINIO_ROOT_USER": "minioadmin", "MINIO_ROOT_PASSWORD": "minioadmin"},
+        ports=(Port(9001, "console", web=True), Port(9000, "s3"))),
+    "database": CloudService(
+        image="postgres:16-alpine",
+        summary="PostgreSQL managed database. Connect with psql on port 5432.",
+        env={"POSTGRES_USER": "gini", "POSTGRES_PASSWORD": "gini", "POSTGRES_DB": "app"},
+        ports=(Port(5432, "postgres"),)),
+    "queue": CloudService(
+        image="rabbitmq:3-management-alpine",
+        summary="RabbitMQ message broker with a management console.",
+        ports=(Port(15672, "console", web=True), Port(5672, "amqp"))),
+    "load_balancer": CloudService(
+        image="nginx:alpine",
+        summary="nginx reverse proxy / load balancer fronting backend targets.",
+        ports=(Port(80, "http", web=True),)),
+    "registry": CloudService(
+        image="registry:2",
+        summary="Docker/OCI image registry serving container images on port 5000.",
+        ports=(Port(5000, "registry"),)),
+
+    # --- serverless front door ---
+    "api_gateway": CloudService(
+        image="traefik:v3.1",
+        summary="API Gateway (Traefik) — maps a URL path to each connected serverless "
+                "Function. Open the dashboard to watch routing live.",
+        command=("--api.insecure=true", "--entrypoints.web.address=:80",
+                 "--metrics.prometheus=true"),
+        ports=(Port(8080, "dashboard", web=True, path="/dashboard/"), Port(80, "http"))),
+
+    # --- edge & traffic ---
+    "proxy": CloudService(
+        image="traefik:v3.1",
+        summary="Traefik reverse proxy / edge router. Dashboard shows routing live.",
+        command=("--api.insecure=true", "--entrypoints.web.address=:80",
+                 "--metrics.prometheus=true"),   # exposes /metrics for the cloud fabric
+        ports=(Port(8080, "dashboard", web=True, path="/dashboard/"), Port(80, "http"))),
+    "web_app": CloudService(
+        image="nginxdemos/hello:plain-text",
+        summary="A demo web backend that displays its hostname/IP — put several behind "
+                "a load balancer to see requests spread across them.",
+        ports=(Port(80, "http", web=True),)),
+
+    # --- streaming & messaging ---
+    "stream": CloudService(
+        image="redpandadata/redpanda:v24.2.7",
+        summary="Redpanda — a Kafka-API event streaming log. Produce/consume with any "
+                "Kafka client against port 9092.",
+        command=("redpanda", "start", "--mode", "dev-container", "--smp", "1",
+                 "--advertise-kafka-addr", "{svc}"),
+        ports=(Port(9092, "kafka"), Port(9644, "admin"))),
+    "messaging": CloudService(
+        image="nats:2.10-alpine",
+        summary="NATS pub/sub messaging. Clients connect on 4222; monitoring on 8222.",
+        command=("-m", "8222"),
+        ports=(Port(8222, "monitor", web=True), Port(4222, "nats"))),
+
+    # --- cache & NoSQL ---
+    "cache": CloudService(
+        image="redis:7-alpine",
+        summary="Redis in-memory store. `redis-cli -h <name>` to set/get keys.",
+        ports=(Port(6379, "redis"),)),
+    "nosql": CloudService(
+        image="mongo:7.0",
+        summary="MongoDB document database (user/pass gini). Connect with mongosh.",
+        env={"MONGO_INITDB_ROOT_USERNAME": "gini", "MONGO_INITDB_ROOT_PASSWORD": "gini"},
+        ports=(Port(27017, "mongo"),)),
+
+    # --- observability ---
+    "metrics": CloudService(
+        image="prom/prometheus:v2.54.1",
+        summary="Prometheus — scrapes and stores metrics; query them in PromQL.",
+        ports=(Port(9090, "console", web=True),)),
+    "dashboard": CloudService(
+        image="grafana/grafana:11.2.2",
+        summary="Grafana dashboards — opens straight to a live view (no login in the lab).",
+        # No-login teaching setup: anonymous Admin + skip the login form. The home-dashboard
+        # path is set by the compiler's observability auto-wiring ONLY once the dashboard is
+        # actually provisioned (otherwise Grafana errors on a missing home dashboard).
+        # admin/admin still works if you want to edit/save.
+        env={"GF_SECURITY_ADMIN_USER": "admin", "GF_SECURITY_ADMIN_PASSWORD": "admin",
+             "GF_AUTH_ANONYMOUS_ENABLED": "true", "GF_AUTH_ANONYMOUS_ORG_ROLE": "Admin",
+             "GF_AUTH_DISABLE_LOGIN_FORM": "true"},
+        ports=(Port(3000, "console", web=True),)),
+    "tracing": CloudService(
+        image="jaegertracing/all-in-one:1.62.0",
+        summary="Jaeger — view distributed request traces across services.",
+        ports=(Port(16686, "console", web=True),)),
+
+    # --- workload & testing ---
+    "load_generator": CloudService(
+        image="fortio/fortio:1.68.0",
+        summary="Fortio load generator. Open the UI to fire HTTP/gRPC load at a target "
+                "and watch QPS and latency histograms.",
+        command=("server",),
+        ports=(Port(8080, "console", web=True, path="/fortio/"),)),
+}
+
+
+def is_service(type_key: str) -> bool:
+    return type_key in CATALOG
+
+
+def service_for(type_key: str) -> CloudService | None:
+    return CATALOG.get(type_key)