pixie-lab 0.1.0__py3-none-any.whl

pixie/pxe/_renderer.py

@@ -0,0 +1,244 @@
+"""Plan renderer: machine + catalog -> iPXE script.
+
+Owns the boot-mode dispatch table and the nbdboot resolution:
+
+* ``ipxe-exit``     -> ``ipxe/exit.j2`` unconditionally.
+* ``nbdboot``       -> walk catalog[image_sha] -> netboot_src -> catalog[netboot_src]
+  to find the netboot-bundle catalog entry, use its ``content_sha256``
+  as the artifacts key, ensure an NBD export exists for the disk-image
+  blob, and render ``ipxe/nbdboot.j2`` with the resolved fields. If any
+  step fails (no bound image, netboot bundle not fetched, NBD spawn
+  refused) the renderer emits the ``unavailable.j2`` template with the
+  reason baked into the plan comment.
+
+The renderer is pure (no side effects) apart from the NBD spawn --
+which is idempotent per (name, blob_path), so a spurious render does
+not accumulate exports.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+from pixie.catalog._schema import CatalogEntry
+from pixie.catalog._store import CatalogStore
+from pixie.exports._store import Export, ExportsStore
+from pixie.exports._supervisor import NbdServer
+from pixie.machines._store import LIVE_ENV_MODES, Machine
+
+_log = logging.getLogger(__name__)
+
+_TEMPLATES_DIR = Path(__file__).resolve().parent.parent / "web" / "_templates" / "ipxe"
+
+
+# NBD name = ``pixie-`` + short sha. Short enough to type at a
+# ``nbdinfo`` prompt, unique-per-content across machines.
+def _export_name_for(image_sha: str) -> str:
+    return f"pixie-{image_sha[:12]}.img"
+
+
+DEFAULT_OVERLAY_SIZE = "10G"
+
+# The pixie-* live-env boot modes are the store's
+# :data:`LIVE_ENV_MODES` set; imported rather than re-authored so a
+# new mode added to the store's :data:`BOOT_MODES` frontier can't
+# fall through here silently (which used to render as
+# ``unknown boot_mode``, indistinguishable from an unbounded
+# operator typo).
+
+
+@dataclass
+class RenderContext:
+    """Everything the renderer needs to produce a plan for one MAC."""
+
+    host: str
+    port: int
+    nbd_host: str
+    overlay_size: str = DEFAULT_OVERLAY_SIZE
+    # Extra tokens appended verbatim to the pixie-live-env kernel
+    # cmdline. Operator-set via PIXIE_LIVE_ENV_EXTRA_CMDLINE.
+    # Intended for hardware-specific workarounds -- e.g. the
+    # GIGABYTE MC12-LE0 needs pci=nommconf to bring up its Intel
+    # i210 NICs under kernel 6.12 -- without a live-env rebake.
+    # Empty by default; the template shims it in unconditionally so
+    # no-op is a legal value.
+    extra_cmdline: str = ""
+
+
+class PlanRenderer:
+    """Assemble iPXE plans. Constructed once at app-startup; called
+    per ``GET /pxe/<mac>``."""
+
+    def __init__(
+        self,
+        *,
+        catalog: CatalogStore,
+        exports: ExportsStore,
+        nbd: NbdServer,
+        live_env_dir: Path | None = None,
+    ) -> None:
+        self._catalog = catalog
+        self._exports = exports
+        self._nbd = nbd
+        # Where the netboot-pc bake's vmlinuz + initrd + squashfs are
+        # staged on disk. When set + the three files exist, the
+        # ``pixie-*`` boot modes chain into the live env; otherwise
+        # they fall back to the ``unavailable`` plan so a bound
+        # target does not silently boot nothing.
+        self._live_env_dir = live_env_dir
+        self._env = Environment(
+            loader=FileSystemLoader(str(_TEMPLATES_DIR)),
+            autoescape=select_autoescape(disabled_extensions=("j2",)),
+            keep_trailing_newline=True,
+        )
+
+    def _live_env_ready(self) -> bool:
+        """True iff the netboot-pc artifacts are staged on disk under
+        ``self._live_env_dir``. Called per-render so an operator
+        dropping the files in without a pixie restart takes effect
+        on the next PXE hit."""
+        if self._live_env_dir is None:
+            return False
+        return all(
+            (self._live_env_dir / name).is_file() for name in ("vmlinuz", "initrd", "live.squashfs")
+        )
+
+    def render(self, machine: Machine, ctx: RenderContext) -> str:
+        mode = machine.boot_mode
+        # Per-machine ``extra_cmdline`` fully overrides the deploy-wide
+        # default so an operator can pin a hardware-specific workaround
+        # to ONE quirky target without dragging every other machine's
+        # cmdline along with it. Blank per-machine value falls back to
+        # the ctx-carried (settings-then-env) default.
+        effective_extra = machine.extra_cmdline or ctx.extra_cmdline
+        if mode == "ipxe-exit":
+            return self._env.get_template("exit.j2").render(mac=machine.mac)
+        if mode == "nbdboot":
+            return self._render_nbdboot(machine, ctx, effective_extra)
+        if mode in LIVE_ENV_MODES:
+            if not self._live_env_ready():
+                # netboot-pc bake artifacts have not been staged on
+                # this deploy yet; degrade to the readable
+                # unavailable plan so a bound target lands on a
+                # legible screen instead of a bty-media initrd.
+                return self._unavailable(
+                    machine,
+                    f"boot_mode={mode!r} needs pixie live-env media; "
+                    f"stage vmlinuz+initrd+squashfs under $PIXIE_LIVE_ENV_DIR",
+                )
+            return self._env.get_template("pixie-live-env.j2").render(
+                mac=machine.mac,
+                boot_mode=mode,
+                host=ctx.host,
+                port=ctx.port,
+                extra_cmdline=effective_extra,
+            )
+        # Unknown mode: refuse loudly rather than falling through.
+        return self._env.get_template("unavailable.j2").render(
+            mac=machine.mac,
+            reason=f"unknown boot_mode {mode!r}",
+            reason_slug="unknown-boot-mode",
+        )
+
+    def render_bootstrap(self, ctx: RenderContext) -> str:
+        return self._env.get_template("bootstrap.j2").render(host=ctx.host, port=ctx.port)
+
+    # ---------- nbdboot resolution ---------------------------------
+
+    def _render_nbdboot(self, machine: Machine, ctx: RenderContext, extra_cmdline: str = "") -> str:
+        image_sha = machine.image_content_sha256
+        if not image_sha:
+            return self._unavailable(
+                machine, "no image bound; set image_content_sha256 to a fetched entry"
+            )
+
+        disk_entry = self._catalog_entry_by_sha(image_sha)
+        if disk_entry is None:
+            return self._unavailable(
+                machine,
+                f"no catalog entry with content_sha256={image_sha[:12]}; re-fetch it",
+            )
+        if not disk_entry.netboot_src:
+            return self._unavailable(
+                machine,
+                f"catalog entry {disk_entry.name!r} has no netboot_src; "
+                "advertise a sibling bundle before selecting nbdboot",
+            )
+        bundle_entry = self._catalog.get_entry_by_src(disk_entry.netboot_src)
+        if bundle_entry is None:
+            return self._unavailable(
+                machine,
+                f"netboot_src {disk_entry.netboot_src} has no catalog entry",
+            )
+        if not bundle_entry.content_sha256:
+            return self._unavailable(
+                machine,
+                f"netboot bundle {bundle_entry.name!r} not fetched yet",
+            )
+        artifact_dir = self._catalog.artifact_dir(bundle_entry.content_sha256)
+        if not (artifact_dir / "manifest.json").is_file():
+            return self._unavailable(
+                machine,
+                f"netboot bundle {bundle_entry.name!r} not unpacked "
+                f"(manifest.json missing under artifacts/{bundle_entry.content_sha256[:12]})",
+            )
+
+        # Blob for the disk image must exist too; that's what the NBD
+        # export streams over the wire.
+        blob = self._catalog.blob_path(image_sha)
+        if not blob.is_file():
+            return self._unavailable(
+                machine,
+                f"disk image {disk_entry.name!r} blob missing on disk; re-fetch it",
+            )
+
+        # Ensure an NBD export for this content is running. Idempotent
+        # per name+blob.
+        export_name = _export_name_for(image_sha)
+        try:
+            port = self._ensure_export(export_name, image_sha, blob)
+        except RuntimeError as exc:
+            return self._unavailable(
+                machine, f"nbdkit refused to start for export {export_name!r}: {exc}"
+            )
+
+        return self._env.get_template("nbdboot.j2").render(
+            mac=machine.mac,
+            host=ctx.host,
+            port=ctx.port,
+            nbd_host=ctx.nbd_host,
+            nbd_port=port,
+            nbd_name=export_name,
+            bundle_sha=bundle_entry.content_sha256,
+            overlay_size=ctx.overlay_size,
+            extra_cmdline=extra_cmdline,
+        )
+
+    def _unavailable(self, machine: Machine, reason: str) -> str:
+        _log.info("pxe %s unavailable: %s", machine.mac, reason)
+        slug = reason.split(";", 1)[0].replace(" ", "-").lower()[:60]
+        return self._env.get_template("unavailable.j2").render(
+            mac=machine.mac,
+            reason=reason,
+            reason_slug=slug,
+        )
+
+    def _catalog_entry_by_sha(self, sha: str) -> CatalogEntry | None:
+        for e in self._catalog.list_entries():
+            if e.content_sha256 == sha:
+                return e
+        return None
+
+    def _ensure_export(self, name: str, image_sha: str, blob: Path) -> int:
+        """Idempotent: register an export in the store + spawn nbdkit
+        if not already running; return its port."""
+        row = self._exports.get(name)
+        if row is None:
+            self._exports.upsert(Export(name=name, content_sha256=image_sha))
+        port = self._nbd.spawn(name, blob)
+        self._exports.update_runtime(name, nbd_port=port, status="running", error="")
+        return port

pixie/pxe/_routes.py

@@ -0,0 +1,386 @@
+"""PXE + boot flow routes.
+
+* ``GET /pxe-bootstrap.ipxe``: iPXE bootstrap that chain-loads the
+  per-MAC plan. Fetched over HTTP.
+* ``GET /pxe/{mac}``: per-machine iPXE plan. Discovery-side write:
+  every hit upserts the row (creating on first contact) + refreshes
+  ``last_seen_at``.
+* ``POST /pxe/{mac}/inventory``: accepts a JSON body (``{"lshw":
+  ..., "disks": [...]}``) from a live-env target that has just
+  collected its hardware inventory. Stores the blob on the machine
+  row; ``/ui/machines`` renders it.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import PlainTextResponse
+
+from pixie.events._kinds import (
+    MACHINE_INVENTORY_UPDATED,
+    PXE_PLAN_RENDERED,
+    PXE_PLAN_UNAVAILABLE,
+    PXE_STATUS_RECEIVED,
+)
+from pixie.machines._store import BadMac, MachinesStore, normalise_mac
+from pixie.pxe._renderer import PlanRenderer, RenderContext
+
+_log = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+def _client_ip(request: Request) -> str:
+    """Best-effort client IP for ``last_seen_ip``. Trusts
+    ``X-Forwarded-For`` only when the caller is inside pixie's own
+    process (uvicorn), which is fine for LAN + is what bty did too.
+    """
+    return (request.client.host if request.client else "") or ""
+
+
+def _get_machines(request: Request) -> MachinesStore:
+    store: MachinesStore | None = getattr(request.app.state, "machines_store", None)
+    if store is None:
+        raise HTTPException(status_code=503, detail="machines store not initialised")
+    return store
+
+
+def _get_renderer(request: Request) -> PlanRenderer:
+    r: PlanRenderer | None = getattr(request.app.state, "pxe_renderer", None)
+    if r is None:
+        raise HTTPException(status_code=503, detail="pxe renderer not initialised")
+    return r
+
+
+def _render_context(request: Request) -> RenderContext:
+    """Derive the base URL + NBD-facing host from the incoming request.
+
+    LAN-only trust model: whatever host the target used to reach us
+    is the host we tell it to keep using. Operators who front pixie
+    behind a proxy set ``PIXIE_PUBLIC_HOST`` to override.
+    """
+    import os
+
+    override = (os.environ.get("PIXIE_PUBLIC_HOST") or "").strip()
+    # ``request.url.hostname`` is what iPXE resolved -- either the LAN
+    # IP or a hostname the operator configured DHCP to hand out. Falls
+    # back to 127.0.0.1 for uvicorn edge cases.
+    host = override or (request.url.hostname or "127.0.0.1")
+    port = request.url.port or 8080
+    nbd_host = (os.environ.get("PIXIE_NBD_PUBLIC_HOST") or "").strip() or host
+    # Extra tokens appended verbatim to the pixie-live-env kernel
+    # cmdline. Resolution chain lives on the settings store: /ui/settings
+    # override (persisted in state.db) -> $PIXIE_LIVE_ENV_EXTRA_CMDLINE
+    # (envvars-style pin) -> empty. Known-good values per hardware are
+    # documented in docs/src/hardware-quirks.md.
+    extra_cmdline = ""
+    settings = getattr(request.app.state, "settings_store", None)
+    if settings is not None:
+        extra_cmdline = settings.resolve_live_env_extra_cmdline()
+    return RenderContext(host=host, port=port, nbd_host=nbd_host, extra_cmdline=extra_cmdline)
+
+
+@router.get("/pxe-bootstrap.ipxe", response_class=PlainTextResponse)
+def pxe_bootstrap(request: Request) -> PlainTextResponse:
+    """iPXE fetches this from the TFTP or HTTP chain to reach the
+    per-MAC plan. Deliberately independent of any machine row so a
+    new-to-pixie target never 404s on its first hop."""
+    ctx = _render_context(request)
+    body = _get_renderer(request).render_bootstrap(ctx)
+    return PlainTextResponse(body, media_type="text/plain")
+
+
+@router.post("/pxe/{mac}/inventory", status_code=204)
+async def pxe_inventory(request: Request, mac: str) -> PlainTextResponse:
+    """Accept an inventory JSON body from a live-env target.
+
+    The body shape is what bty-tui (and now pixie-tui) POST after
+    ``lshw -json`` + ``lsblk``: ``{"lshw": <object|list>, "disks":
+    [...]}``. We store the whole thing verbatim; the /ui/machines
+    page renders selected fields, the JSON API returns it as-is."""
+    try:
+        canon = normalise_mac(mac)
+    except BadMac as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    try:
+        payload = await request.json()
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=f"body must be JSON: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise HTTPException(status_code=400, detail="body must be a JSON object")
+
+    machines = _get_machines(request)
+    machines.set_inventory(canon, payload)
+
+    log = getattr(request.app.state, "events_log", None)
+    if log is not None:
+        details: dict[str, Any] = {}
+        disks = payload.get("disks")
+        if isinstance(disks, list):
+            details["disks_count"] = len(disks)
+        details["has_lshw"] = payload.get("lshw") is not None
+        log.emit(
+            MACHINE_INVENTORY_UPDATED,
+            subject_kind="machine",
+            subject_id=canon,
+            summary=f"{canon} posted inventory",
+            details=details,
+        )
+    return PlainTextResponse("", status_code=204)
+
+
+@router.get("/machines/{mac}/inventory")
+def get_inventory(request: Request, mac: str) -> dict[str, Any]:
+    """Return the stored inventory for a machine, or 404 if none has
+    been posted yet."""
+    try:
+        canon = normalise_mac(mac)
+    except BadMac as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    row = _get_machines(request).get(canon)
+    if row is None or not row.inventory:
+        raise HTTPException(status_code=404, detail=f"no inventory for {canon}")
+    return {
+        "mac": row.mac,
+        "inventory_at": row.inventory_at,
+        "inventory": row.inventory,
+    }
+
+
+@router.get("/pxe/{mac}", response_class=PlainTextResponse)
+def pxe_plan(request: Request, mac: str) -> PlainTextResponse:
+    """Discovery + plan render. Every hit upserts the machine (creates
+    on first contact) and refreshes ``last_seen_at``; then the plan
+    is rendered per the current boot_mode."""
+    try:
+        canon = normalise_mac(mac)
+    except BadMac as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    machines = _get_machines(request)
+    row = machines.touch_seen(canon, ip=_client_ip(request))
+
+    ctx = _render_context(request)
+    body = _get_renderer(request).render(row, ctx)
+    # Every plan render emits one event so an operator can grep the
+    # log for "every time this MAC PXE'd + what mode it got". The
+    # unavailable variant is distinguished by the renderer emitting
+    # ``exit`` instead of a real chain -- the plan body carries the
+    # reason as a comment, which we extract for details.
+    log = getattr(request.app.state, "events_log", None)
+    if log is not None:
+        is_unavailable = "\nexit\n" in body and "unavailable" in body.lower()
+        if is_unavailable:
+            log.emit(
+                PXE_PLAN_UNAVAILABLE,
+                subject_kind="machine",
+                subject_id=canon,
+                summary=f"{canon}: boot_mode={row.boot_mode} not renderable",
+                details={"boot_mode": row.boot_mode},
+            )
+        else:
+            log.emit(
+                PXE_PLAN_RENDERED,
+                subject_kind="machine",
+                subject_id=canon,
+                summary=f"{canon}: boot_mode={row.boot_mode}",
+                details={"boot_mode": row.boot_mode},
+            )
+    # Always ``text/plain`` per bty's convention; iPXE parses on
+    # bytes, not on Content-Type.
+    return PlainTextResponse(body, media_type="text/plain")
+
+
+@router.post("/pxe/{mac}/status", status_code=204)
+async def pxe_status(request: Request, mac: str) -> PlainTextResponse:
+    """Accept a status token from the target's initrd or live env.
+
+    Pixie.s ramboot initrd + pixie-tui both fire tokens like
+    ``ramboot.up`` / ``ramboot.nbd_connect_failed`` / ``ramboot.die``
+    so an operator watching /ui/events sees the boot flow land or
+    fail. The body carries either ``status=<token>`` in a form or a
+    JSON object -- normalise both to a string.
+    """
+    try:
+        canon = normalise_mac(mac)
+    except BadMac as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    ctype = (request.headers.get("content-type") or "").lower()
+    status_token = ""
+    if "application/json" in ctype:
+        try:
+            payload = await request.json()
+        except Exception:
+            payload = None
+        if isinstance(payload, dict):
+            status_token = str(payload.get("status") or "").strip()
+    else:
+        form = await request.form()
+        raw = form.get("status")
+        if isinstance(raw, str):
+            status_token = raw.strip()
+    if not status_token:
+        # Fall back to a raw body read for the wget-style
+        # ``--post-data=status=X`` shape busybox uses in the nbdboot
+        # initrd (application/x-www-form-urlencoded handled above,
+        # but old busybox drops the content-type header).
+        raw_body = (await request.body()).decode("utf-8", errors="replace").strip()
+        if raw_body.startswith("status="):
+            status_token = raw_body.split("=", 1)[1]
+    if not status_token:
+        raise HTTPException(status_code=400, detail="missing status token")
+    log = getattr(request.app.state, "events_log", None)
+    if log is not None:
+        log.emit(
+            PXE_STATUS_RECEIVED,
+            subject_kind="machine",
+            subject_id=canon,
+            summary=f"{canon}: {status_token}",
+            details={"status": status_token},
+        )
+    # pixie-flash-once completes -> flip to ipxe-exit so the next PXE
+    # boot loads the disk. pixie-flash-always keeps re-arming; the
+    # operator explicitly picked "flash every boot". Any other status
+    # (started, failed, etc.) or boot_mode is a pure event emit.
+    if status_token == "done":
+        machines = _get_machines(request)
+        row = machines.get(canon)
+        if row is not None and row.boot_mode == "pixie-flash-once":
+            # Guard would trip if inventory is missing on the row
+            # (shouldn't happen; getting here required a flash-once
+            # bind which itself passed the guard). Swallow so the
+            # /done POST still returns 204.
+            with contextlib.suppress(ValueError):
+                machines.upsert_binding(
+                    canon,
+                    boot_mode="ipxe-exit",
+                    image_content_sha256=row.image_content_sha256,
+                    labels=list(row.labels),
+                    target_disk_serial=row.target_disk_serial,
+                )
+    return PlainTextResponse("", status_code=204)
+
+
+@router.get("/pxe/{mac}/plan")
+def pxe_plan_json(request: Request, mac: str) -> dict[str, Any]:
+    """JSON plan the LIVE-ENV pixie CLI GETs after boot.
+
+    Distinct from ``GET /pxe/{mac}`` (which returns iPXE): once the
+    live env has booted and the pixie CLI is up on tty1, it GETs
+    THIS endpoint to figure out what to do:
+
+      ``mode=exit``        -> nothing to do here, exit cleanly.
+      ``mode=inventory``   -> POST /pxe/{mac}/inventory + reboot.
+      ``mode=interactive`` -> drop the operator into the wizard.
+      ``mode=flash``       -> auto-flash the bound image (requires
+                              ``image_content_sha256`` + a target
+                              disk on the machine row).
+
+    The mapping mirrors bty's shape so the ported pixie CLI needs
+    zero cmdline changes. For the minimal live-env slice landing
+    here we only surface ``inventory`` + ``exit`` -- the flash path
+    lands with a follow-up PR that adds the target-disk fields on
+    the machine row + the ``POST /pxe/{mac}/done`` endpoint that
+    flips ``pixie-flash-once`` observers to see the machine as
+    flashed."""
+    try:
+        canon = normalise_mac(mac)
+    except BadMac as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    machines = _get_machines(request)
+    row = machines.get(canon)
+    if row is None:
+        # A GET /plan without a prior discovery hit is unusual (the
+        # target would already have iPXE'd via /pxe/{mac}) but
+        # possible during testing. Fall through to ``exit``: the CLI
+        # will POST inventory anyway (that path does not touch the
+        # machine row).
+        return {"mode": "exit"}
+
+    mode = row.boot_mode
+    if mode == "pixie-inventory":
+        return {"mode": "inventory"}
+    if mode == "pixie-tui":
+        return {"mode": "interactive"}
+    if mode in ("pixie-flash-once", "pixie-flash-always"):
+        # Resolve the bound catalog entry so the live env can fetch
+        # the bytes + know the format. Bind-time validation (see
+        # machines._store.upsert_binding) guarantees both fields are
+        # non-empty for a flash mode; if either goes missing between
+        # bind and here (schema drift, out-of-band DB edit), fall
+        # back to the interactive wizard so the operator can pick.
+        if not (row.image_content_sha256 and row.target_disk_serial):
+            return {"mode": "interactive"}
+        catalog = request.app.state.catalog_store
+        entry = None
+        for e in catalog.list_entries():
+            if e.content_sha256 == row.image_content_sha256:
+                entry = e
+                break
+        if entry is None:
+            return {"mode": "interactive"}
+        ctx = _render_context(request)
+        # URL-quote the entry name for the image URL path segment:
+        # nosi's operator-facing names contain spaces + parens
+        # ("nosi debian-13-headless (x86_64, 2026.W29)") and pushing
+        # them through the client's ``urllib.request.urlopen`` on
+        # the live env drops the path from the URL entirely (parser
+        # rejects raw whitespace in a URL). The blob route serves
+        # by sha only, so the display name is decorative; encode it
+        # for safe transport, leave the top-level ``name`` field
+        # decoded for operator-readable logging on the client side.
+        import urllib.parse as _urlparse
+
+        image_url = (
+            f"http://{ctx.host}:{ctx.port}"
+            f"/b/{row.image_content_sha256}/{_urlparse.quote(entry.name, safe='')}"
+        )
+        # ``entry.format`` in the catalog is the ORIGINAL upstream
+        # format (``img.gz`` / ``img.zst`` / ``img.xz`` / ``img``).
+        # Pixie's fetcher decompresses ``img.gz`` / ``img.zst`` /
+        # ``img.xz`` at fetch time and stores the DECOMPRESSED bytes
+        # in the blob (see catalog._fetcher._COMPRESSED_IMG_FORMATS
+        # + _decompress_to_tmpfile). The blob route serves those
+        # decompressed bytes verbatim, so the flash pipeline in the
+        # live env must NOT try to gunzip/unzstd/unxz the stream --
+        # the bytes on the wire are already raw ``img``.
+        #
+        # Advertise ``format=img`` for any compressed variant whose
+        # bytes are pre-decompressed on disk. Leaves plain ``img``
+        # + ``tar.gz`` (bundle) untouched. Without this, a
+        # ``format=img.gz`` payload from an entry we already
+        # decompressed sends the CLI into gunzip-on-raw-bytes and
+        # the flash never completes.
+        _COMPRESSED_IMG_FORMATS = {"img.gz", "img.zst", "img.xz"}
+        plan_format = "img" if entry.format in _COMPRESSED_IMG_FORMATS else entry.format
+        plan: dict[str, Any] = {
+            "mode": "flash",
+            "image": image_url,
+            "target_disk_serial": row.target_disk_serial,
+            "name": entry.name,
+            "disk_image_sha": row.image_content_sha256,
+        }
+        if plan_format:
+            plan["format"] = plan_format
+        return plan
+    if mode == "nbdboot":
+        # nbdboot targets normally boot the image's own kernel +
+        # initrd -- no pixie CLI in the picture -- so this branch
+        # only fires under the nbdboot chain test, which pivots
+        # through the pixie live env as a stand-in. Return
+        # ``interactive`` (not ``exit``): ``exit`` triggers a
+        # ``sys.exit(0)`` inside the CLI that races the
+        # daemon-thread inventory post, so an ``exit`` here
+        # occasionally kills the CLI before inventory reaches
+        # pixie. ``interactive`` keeps the CLI up (wizard on
+        # tty1) which is harmless in the test and never runs
+        # on a real nbdboot boot.
+        return {"mode": "interactive"}
+    # ipxe-exit / unknown -> nothing to do from the live env's side.
+    return {"mode": "exit"}

pixie/tftp/__init__.py

@@ -0,0 +1,21 @@
+"""TFTP subprocess supervision.
+
+pixie ships an in-container ``in.tftpd`` (from the tftpd-hpa package)
+so a target's BIOS-PXE / UEFI-PXE first hop can chain into pixie's
+HTTP bootstrap without an external TFTP daemon on the LAN.
+
+The supervisor is a thin wrapper around ``subprocess.Popen`` tuned to
+pixie's FastAPI lifespan: start on app boot, poll for early death
+(same 200ms grace as :class:`pixie.exports._supervisor.NbdServer`),
+terminate on shutdown.
+
+Runs OFF by default in unit / dev where udp/69 needs root -- flipped
+on inside the container via ``PIXIE_TFTP_ENABLED=1`` (set by the
+compose file's default env).
+"""
+
+from __future__ import annotations
+
+from pixie.tftp._supervisor import DEFAULT_TFTP_ROOT, TftpServer
+
+__all__ = ["DEFAULT_TFTP_ROOT", "TftpServer"]