pixie-lab 0.3.2__py3-none-any.whl → 0.4.1__py3-none-any.whl

pixie/deploy/_main.py

@@ -311,10 +311,32 @@ def _cmd_purge(args: argparse.Namespace) -> int:
         shutil.rmtree(data_dir)
         print(f"pixie-lab purge: removed {data_dir}", file=sys.stderr)
 
-    # 4. Delete the deploy directory itself.
+    # 4. Delete the deploy directory itself. ``dest`` often sits under a
+    #    root-owned parent (e.g. /opt), where an unprivileged operator can
+    #    empty the dir but can't rmdir it -- rmtree clears the contents,
+    #    then raises on the final rmdir. Report that plainly instead of
+    #    dumping a traceback; the state is gone either way, so it's a
+    #    caveat, not a failure.
     if remove_dir and dest.exists():
-        shutil.rmtree(dest)
-        print(f"pixie-lab purge: removed {dest}", file=sys.stderr)
+        try:
+            shutil.rmtree(dest)
+            print(f"pixie-lab purge: removed {dest}", file=sys.stderr)
+        except OSError as exc:
+            leftover = sorted(p.name for p in dest.iterdir()) if dest.is_dir() else []
+            if not leftover:
+                print(
+                    f"pixie-lab purge: emptied {dest}, but could not remove the "
+                    f"directory itself ({exc.strerror or exc}) -- its parent is not "
+                    f"writable (a root-owned /opt, say). The empty dir is harmless; "
+                    f"you can redeploy into it or 'sudo rmdir' it.",
+                    file=sys.stderr,
+                )
+            else:
+                print(
+                    f"pixie-lab purge: could not fully remove {dest} "
+                    f"({exc.strerror or exc}); leftover: {', '.join(leftover)}",
+                    file=sys.stderr,
+                )
 
     return 0
 

pixie/events/_kinds.py

@@ -21,7 +21,9 @@ from __future__ import annotations
 # ---------- catalog + fetch pipeline ---------------------------------
 #
 # Every catalog-store mutation emits one of these. ``subject_kind`` is
-# always ``"entry"``; ``subject_id`` is the catalog entry name.
+# ``"entry"`` (``subject_id`` = the catalog entry name) for the per-row
+# kinds; the ``catalog.import.*`` pair is catalog-scoped instead
+# (``subject_kind = "catalog"``) since one import touches many entries.
 
 CATALOG_ENTRY_ADDED = "catalog.entry.added"
 """A new row landed via POST /catalog/entries, POST /ui/catalog/add,
@@ -95,36 +97,37 @@ EXPORT_NBDKIT_EXITED = "export.nbdkit.exited"
 (``_refresh_row`` noticed no live proc for a ``running`` row).
 ``details.previous_port`` + ``details.error`` explain."""
 
-# ---------- persistent overlays (per-machine qcow2) -----------------
+# ---------- persistent overlays (alias-keyed volumes) ---------------
 #
-# ``subject_kind`` is always ``"machine"``; ``subject_id`` is the
-# canonical MAC. ``details`` names the (image_sha, profile) triple.
+# ``subject_kind`` is always ``"overlay"``; ``subject_id`` is the
+# globally-unique ``alias`` (``""`` for a fleet-wide bulk action). An
+# overlay is a single-writer qcow2 volume over one base image, not a
+# per-machine file; ``details`` carries ``alias`` / ``image_sha`` /
+# ``qcow2_path`` as relevant.
 
 OVERLAY_CREATED = "overlay.created"
-"""A per-machine qcow2 overlay was materialised for the first time
-for a ``(mac, image_sha, profile)`` triple. ``details`` carries
-``image_sha``, ``profile``, and ``qcow2_path``."""
+"""An alias-keyed qcow2 overlay was materialised for the first time
+(lazy-created on the first nbdboot render, or after a Reset).
+``details`` carries ``alias``, ``image_sha``, and ``qcow2_path``."""
 
 OVERLAY_RESET = "overlay.reset"
-"""Operator hit Reset on the machine detail page: the qemu-nbd was
-terminated, the qcow2 was unlinked, the overlays row was deleted.
+"""Operator hit Reset (one alias) or Prune (bulk) on the Overlays
+page: the qemu-nbd was terminated, the qcow2 unlinked, the overlays
+row deleted. ``subject_id`` is the alias for a single Reset, ``""``
+for a bulk Prune (``details.pruned`` counts the reclaimed volumes).
 Next plan render lazily creates a fresh overlay from the base."""
 
-OVERLAY_BOOTED = "overlay.booted"
-"""Plan render for an already-existing overlay row (heartbeat).
-Emitted on every persistent nbdboot render so an operator can grep
-the events log for "which overlays am I actually using?"."""
-
 # ---------- machines + PXE ------------------------------------------
 #
 # ``subject_kind`` is always ``"machine"``; ``subject_id`` is the
 # canonical MAC address.
 
 MACHINE_DISCOVERED = "machine.discovered"
-"""First-ever GET /pxe/<mac> for a MAC pixie has not seen before.
-Emitted from ``machines_store.touch_seen`` when a new row is
-created; subsequent hits do NOT emit (they update ``last_seen_at``
-via the ``pxe.plan.rendered`` event instead)."""
+"""First-ever GET /pxe/<mac> for a MAC pixie has not seen before. The
+``/pxe/<mac>`` route detects the absent row before ``touch_seen``
+auto-registers it and emits this once; subsequent hits do NOT emit
+(they update ``last_seen_at`` via the ``pxe.plan.rendered`` event
+instead). ``details.boot_mode`` is the auto-registered default."""
 
 MACHINE_BOUND = "machine.bound"
 """First bind for a MAC: PUT /machines/<mac> or POST
@@ -232,7 +235,6 @@ KNOWN_EVENT_KINDS: frozenset[str] = frozenset(
         EXPORT_NBDKIT_EXITED,
         OVERLAY_CREATED,
         OVERLAY_RESET,
-        OVERLAY_BOOTED,
         MACHINE_DISCOVERED,
         MACHINE_BOUND,
         MACHINE_BINDING_CHANGED,

pixie/exports/_store.py

@@ -33,33 +33,80 @@ CREATE TABLE IF NOT EXISTS exports (
 
 CREATE INDEX IF NOT EXISTS idx_exports_content_sha
     ON exports(content_sha256);
+"""
 
--- One row per (mac, image_sha, profile) triple; the qcow2 file at
--- ``qcow2_path`` has ``backing_file`` pointing at the catalog blob
--- for ``image_sha`` and holds every write the machine has made under
--- that profile. Separate from the ``exports`` table above because the
--- ephemeral (nbdkit) and persistent (qemu-nbd) paths have different
--- identity (per-content vs per-triple) and lifecycle (respawn on
--- restart vs create-on-first-bind).
+# An overlay is a globally-named writable volume over ONE base image.
+# Identity is its ``alias`` (globally unique), NOT the machine: the
+# qcow2 at ``qcow2_path`` has ``backing_file`` pointing at the catalog
+# blob for ``image_sha`` and holds every write made through it. Exactly
+# one machine may hold exclusive write at a time -- ``attached_mac``
+# (empty = free) records which; qemu-nbd's qcow2 image-lock is the
+# backstop. Separate table from ``exports`` because the ephemeral
+# (nbdkit, per-content) and persistent (qemu-nbd, per-alias) paths have
+# different identity + lifecycle.
+_OVERLAYS_SCHEMA = """
 CREATE TABLE IF NOT EXISTS overlays (
-    mac           TEXT NOT NULL,
+    alias         TEXT PRIMARY KEY,
     image_sha     TEXT NOT NULL,
-    profile       TEXT NOT NULL,
     qcow2_path    TEXT NOT NULL,
+    attached_mac  TEXT NOT NULL DEFAULT '',
     nbd_port      INTEGER NOT NULL DEFAULT 0,
     status        TEXT NOT NULL DEFAULT 'idle',
     error         TEXT NOT NULL DEFAULT '',
     created_at    TEXT NOT NULL,
-    last_boot_at  TEXT NOT NULL DEFAULT '',
-    PRIMARY KEY (mac, image_sha, profile)
+    last_boot_at  TEXT NOT NULL DEFAULT ''
 );
-CREATE INDEX IF NOT EXISTS idx_overlays_mac
-    ON overlays(mac);
 CREATE INDEX IF NOT EXISTS idx_overlays_image_sha
     ON overlays(image_sha);
+CREATE INDEX IF NOT EXISTS idx_overlays_attached_mac
+    ON overlays(attached_mac);
 """
 
 
+def _migrate_overlays_schema(conn: sqlite3.Connection) -> None:
+    """Re-key the pre-alias ``overlays`` table (PK
+    ``(mac, image_sha, profile)``) to the alias-keyed shape. For each
+    old row a globally-unique ``alias = <profile>-<mac_slug>`` is minted
+    (dedup on the rare collision) and ``attached_mac`` is seeded with the
+    row's old ``mac`` so the machine that owned it keeps its exclusive
+    hold. The qcow2 ``qcow2_path`` is left untouched -- no large files
+    move during migration. Idempotent: a table that already has an
+    ``alias`` column, or no overlays table at all, is left alone."""
+    cols = {row[1] for row in conn.execute("PRAGMA table_info(overlays)").fetchall()}
+    if not cols or "alias" in cols:
+        return
+    old_rows = conn.execute("SELECT * FROM overlays").fetchall()
+    conn.execute("ALTER TABLE overlays RENAME TO overlays_pre_alias")
+    conn.executescript(_OVERLAYS_SCHEMA)
+    seen: set[str] = set()
+    for r in old_rows:
+        mac_slug = str(r["mac"]).replace(":", "-")
+        base = f"{r['profile']}-{mac_slug}"
+        alias = base
+        n = 1
+        while alias in seen:
+            n += 1
+            alias = f"{base}-{n}"
+        seen.add(alias)
+        conn.execute(
+            """
+            INSERT INTO overlays (
+                alias, image_sha, qcow2_path, attached_mac,
+                nbd_port, status, error, created_at, last_boot_at
+            ) VALUES (?, ?, ?, ?, 0, 'idle', '', ?, ?)
+            """,
+            (
+                alias,
+                r["image_sha"],
+                r["qcow2_path"],
+                r["mac"],
+                r["created_at"],
+                r["last_boot_at"],
+            ),
+        )
+    conn.execute("DROP TABLE overlays_pre_alias")
+
+
 @dataclass
 class Export:
     """One registered NBD export."""
@@ -99,6 +146,8 @@ class ExportsStore:
     def _ensure_schema(self) -> None:
         with self._conn() as conn:
             conn.executescript(_SCHEMA)
+            _migrate_overlays_schema(conn)
+            conn.executescript(_OVERLAYS_SCHEMA)
 
     @contextlib.contextmanager
     def _conn(self) -> Generator[sqlite3.Connection]:
@@ -182,18 +231,20 @@ def _row_to_export(row: sqlite3.Row) -> Export:
 
 @dataclass
 class Overlay:
-    """One persistent per-machine qcow2 overlay for ``boot_mode=nbdboot``.
+    """A globally-named writable volume over one base image.
 
-    Identity is the ``(mac, image_sha, profile)`` triple. The qcow2 at
-    ``qcow2_path`` has ``backing_file`` pointing at the catalog blob
-    for ``image_sha``; a qemu-nbd subprocess serves it while the row's
-    ``status == 'running'``. Deleting the row is the operator's
-    "Reset overlay" action -- the caller unlinks the qcow2 too."""
+    Identity is the ``alias`` (globally unique), not a machine: the
+    qcow2 at ``qcow2_path`` has ``backing_file`` pointing at the catalog
+    blob for ``image_sha`` and holds every write made through it.
+    ``attached_mac`` records the single machine currently holding
+    exclusive write ("" = free); a qemu-nbd subprocess serves it while
+    ``status == 'running'``. Deleting the row is the operator's "Reset"
+    action -- the caller unlinks the qcow2 too."""
 
-    mac: str
+    alias: str
     image_sha: str
-    profile: str
     qcow2_path: str
+    attached_mac: str = ""
     nbd_port: int = 0
     status: str = "idle"  # "idle" | "running" | "error"
     error: str = ""
@@ -202,10 +253,10 @@ class Overlay:
 
     def to_dict(self) -> dict[str, Any]:
         out: dict[str, Any] = {
-            "mac": self.mac,
+            "alias": self.alias,
             "image_sha": self.image_sha,
-            "profile": self.profile,
             "qcow2_path": self.qcow2_path,
+            "attached_mac": self.attached_mac,
             "status": self.status,
             "created_at": self.created_at,
         }
@@ -219,12 +270,12 @@ class Overlay:
 
 
 class OverlaysStore:
-    """Repository over the ``overlays`` table on the shared state.db.
+    """Repository over the alias-keyed ``overlays`` table.
 
-    Same DB path as :class:`ExportsStore` + :class:`CatalogStore`.
-    Kept as a sibling class rather than a method-set on ExportsStore
-    so the ephemeral vs persistent lifecycles read as distinct
-    concerns at the call site."""
+    Same DB path as :class:`ExportsStore` + :class:`CatalogStore`. The
+    table is created + migrated by :meth:`ExportsStore._ensure_schema`
+    (constructed first at startup), so this is a thin data-access
+    sibling."""
 
     def __init__(self, db_path: Path) -> None:
         self.db_path = Path(db_path)
@@ -240,31 +291,21 @@ class OverlaysStore:
             conn.close()
 
     def list_all(self) -> list[Overlay]:
-        """Every overlay row across every (mac, image, profile) triple.
-        Named ``list_all`` (not ``list``) so ``list[Overlay]`` in
-        sibling method signatures below resolves to the built-in
-        rather than the shadowed method."""
         with self._conn() as conn:
-            rows = conn.execute(
-                "SELECT * FROM overlays ORDER BY mac, image_sha, profile"
-            ).fetchall()
+            rows = conn.execute("SELECT * FROM overlays ORDER BY alias").fetchall()
         return [_row_to_overlay(r) for r in rows]
 
-    def get(self, mac: str, image_sha: str, profile: str) -> Overlay | None:
+    def get(self, alias: str) -> Overlay | None:
         with self._conn() as conn:
-            row = conn.execute(
-                "SELECT * FROM overlays WHERE mac = ? AND image_sha = ? AND profile = ?",
-                (mac, image_sha, profile),
-            ).fetchone()
+            row = conn.execute("SELECT * FROM overlays WHERE alias = ?", (alias,)).fetchone()
         return _row_to_overlay(row) if row else None
 
-    def list_for_machine_and_image(self, mac: str, image_sha: str) -> list[Overlay]:
-        """Every profile this ``(mac, image_sha)`` combo has ever created.
-        Drives the bind-form overlay picker."""
+    def list_for_image(self, image_sha: str) -> list[Overlay]:
+        """Every overlay over this base image. Drives the bind-form
+        picker (which aliases a machine could attach for this image)."""
         with self._conn() as conn:
             rows = conn.execute(
-                "SELECT * FROM overlays WHERE mac = ? AND image_sha = ? ORDER BY profile",
-                (mac, image_sha),
+                "SELECT * FROM overlays WHERE image_sha = ? ORDER BY alias", (image_sha,)
             ).fetchall()
         return [_row_to_overlay(r) for r in rows]
 
@@ -273,15 +314,15 @@ class OverlaysStore:
             conn.execute(
                 """
                 INSERT OR REPLACE INTO overlays (
-                    mac, image_sha, profile, qcow2_path,
+                    alias, image_sha, qcow2_path, attached_mac,
                     nbd_port, status, error, created_at, last_boot_at
                 ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
                 """,
                 (
-                    ov.mac,
+                    ov.alias,
                     ov.image_sha,
-                    ov.profile,
                     ov.qcow2_path,
+                    ov.attached_mac,
                     ov.nbd_port,
                     ov.status,
                     ov.error,
@@ -290,55 +331,52 @@ class OverlaysStore:
                 ),
             )
 
-    def delete(self, mac: str, image_sha: str, profile: str) -> bool:
+    def delete(self, alias: str) -> bool:
         with _DB_WRITE_LOCK, self._conn() as conn:
-            cur = conn.execute(
-                "DELETE FROM overlays WHERE mac = ? AND image_sha = ? AND profile = ?",
-                (mac, image_sha, profile),
-            )
+            cur = conn.execute("DELETE FROM overlays WHERE alias = ?", (alias,))
             return cur.rowcount > 0
 
-    def update_runtime(
-        self,
-        mac: str,
-        image_sha: str,
-        profile: str,
-        *,
-        nbd_port: int,
-        status: str,
-        error: str = "",
-    ) -> None:
+    def update_runtime(self, alias: str, *, nbd_port: int, status: str, error: str = "") -> None:
         """Refresh transient port + status after a qemu-nbd spawn."""
         with _DB_WRITE_LOCK, self._conn() as conn:
             conn.execute(
-                """
-                UPDATE overlays
-                SET nbd_port = ?, status = ?, error = ?
-                WHERE mac = ? AND image_sha = ? AND profile = ?
-                """,
-                (nbd_port, status, error, mac, image_sha, profile),
+                "UPDATE overlays SET nbd_port = ?, status = ?, error = ? WHERE alias = ?",
+                (nbd_port, status, error, alias),
             )
 
-    def touch_last_boot(self, mac: str, image_sha: str, profile: str) -> None:
-        """Record the timestamp of the most recent plan render for this
-        overlay. Used by the UI's "last used" column + future auto-GC."""
+    def touch_last_boot(self, alias: str) -> None:
+        with _DB_WRITE_LOCK, self._conn() as conn:
+            conn.execute("UPDATE overlays SET last_boot_at = ? WHERE alias = ?", (now_iso(), alias))
+
+    def attach(self, alias: str, mac: str) -> None:
+        """Record ``mac`` as the exclusive writer of ``alias``.
+        Single-writer is enforced at the call site (bind route + renderer
+        refuse a hand-off to a different mac); this just records it."""
+        with _DB_WRITE_LOCK, self._conn() as conn:
+            conn.execute("UPDATE overlays SET attached_mac = ? WHERE alias = ?", (mac, alias))
+
+    def detach(self, alias: str) -> None:
+        """Release the writer hold on ``alias`` (attached_mac -> '')."""
+        with _DB_WRITE_LOCK, self._conn() as conn:
+            conn.execute("UPDATE overlays SET attached_mac = '' WHERE alias = ?", (alias,))
+
+    def detach_mac(self, mac: str, *, keep: str = "") -> None:
+        """Release every alias ``mac`` holds except ``keep`` -- called
+        when a machine rebinds away so a stale hold can't block another
+        machine from attaching."""
         with _DB_WRITE_LOCK, self._conn() as conn:
             conn.execute(
-                """
-                UPDATE overlays
-                SET last_boot_at = ?
-                WHERE mac = ? AND image_sha = ? AND profile = ?
-                """,
-                (now_iso(), mac, image_sha, profile),
+                "UPDATE overlays SET attached_mac = '' WHERE attached_mac = ? AND alias != ?",
+                (mac, keep),
             )
 
 
 def _row_to_overlay(row: sqlite3.Row) -> Overlay:
     return Overlay(
-        mac=row["mac"],
+        alias=row["alias"],
         image_sha=row["image_sha"],
-        profile=row["profile"],
         qcow2_path=row["qcow2_path"],
+        attached_mac=row["attached_mac"],
         nbd_port=row["nbd_port"] or 0,
         status=row["status"],
         error=row["error"],

pixie/machines/_routes.py

@@ -20,7 +20,7 @@ from pydantic import BaseModel, Field
 from pixie.events._kinds import MACHINE_BINDING_CHANGED, MACHINE_BOUND, MACHINE_DELETED
 from pixie.machines._store import (
     BOOT_MODES,
-    DEFAULT_BOOT_MODE,
+    UNCOMMITTED_BOOT_MODES,
     BadMac,
     MachinesStore,
     normalise_mac,
@@ -66,13 +66,15 @@ class BindBody(BaseModel):
             "the global PIXIE_LIVE_ENV_EXTRA_CMDLINE. Single line."
         ),
     )
-    overlay_profile: str = Field(
+    overlay_alias: str = Field(
         default="",
         description=(
-            "Persistent-overlay profile name for nbdboot. Blank means "
-            "ephemeral tmpfs (writes vanish on reboot); non-blank names a "
-            "qcow2 overlay that persists on pixie's data volume. "
-            "Alphanumeric-leading; a-z / A-Z / 0-9 / . _ - (max 64 chars)."
+            "Globally-unique persistent-overlay alias for nbdboot. Blank "
+            "means ephemeral tmpfs (writes vanish on reboot); non-blank "
+            "attaches a named writable volume (qcow2 over a base image) "
+            "that persists on pixie's data volume. Single-writer: one "
+            "machine per alias. Alphanumeric-leading; a-z / A-Z / 0-9 / "
+            ". _ - (max 64 chars)."
         ),
     )
 
@@ -133,14 +135,28 @@ def upsert_machine(
         # not supply any new ones -- honours a partial-update PUT
         # without needing PATCH.
         labels_arg = labels if labels else (list(previous.labels) if previous else [])
+        # Single-writer + alias-implies-image resolution is shared with
+        # the UI bind route (see pixie.web._overlay_bind): attaching an
+        # alias held by another machine raises ValueError -> 422 here.
+        from pixie.web._overlay_bind import overlay_state, resolve_overlay_bind
+
+        overlays, overlays_dir = overlay_state(request.app.state)
+        image_sha, resolved_alias = resolve_overlay_bind(
+            overlays=overlays,
+            overlays_dir=overlays_dir,
+            mac=canon,
+            boot_mode=body.boot_mode,
+            image_sha=body.image_content_sha256.strip().lower(),
+            alias=body.overlay_alias,
+        )
         row = _get_machines(request).upsert_binding(
             canon,
             boot_mode=body.boot_mode,
-            image_content_sha256=body.image_content_sha256.strip().lower(),
+            image_content_sha256=image_sha,
             labels=labels_arg,
             target_disk_serial=body.target_disk_serial,
             extra_cmdline=body.extra_cmdline,
-            overlay_profile=body.overlay_profile,
+            overlay_alias=resolved_alias,
         )
     except ValueError as exc:
         raise HTTPException(status_code=422, detail=str(exc)) from exc
@@ -149,12 +165,14 @@ def upsert_machine(
         details: dict[str, Any] = {"boot_mode": row.boot_mode}
         if row.image_content_sha256:
             details["image_content_sha256"] = row.image_content_sha256
-        # ``machine.bound`` on a fresh MAC or on a row that was
-        # discovered-only (previous.boot_mode default with no bound
-        # image); ``machine.binding.changed`` when the mode or image
-        # actually shifted between the previous state and the new one.
+        # ``machine.bound`` on a fresh MAC or on a row that was only
+        # auto-registered (an uncommitted mode -- ipxe-exit or
+        # pixie-inventory -- with no bound image, including a machine
+        # that auto-inventoried then flipped back to ipxe-exit);
+        # ``machine.binding.changed`` when the mode or image actually
+        # shifted from a real prior operator bind.
         was_bound = previous is not None and (
-            bool(previous.image_content_sha256) or previous.boot_mode != DEFAULT_BOOT_MODE
+            bool(previous.image_content_sha256) or previous.boot_mode not in UNCOMMITTED_BOOT_MODES
         )
         changed = previous is not None and (
             previous.boot_mode != row.boot_mode