Give every stack an icon, and put the status on it (0.51.0)

Stacks were a name and a coloured dot. The dot carried the status but nothing
carried identity, so a list of twenty stacks read as twenty identical rows.
This gives each one an icon in front of its name and moves the status onto that
icon as a halo in the status colour, which is the thing the eye lands on anyway.

The constraint that shaped the design: people already have stacks. Asking them
to pick an icon for each one before the feature does anything would mean it
never gets used, so the icon is *derived* from the stack's name and the column
stays empty until somebody overrides it. ~700 keywords in 79 groups cover the
self-hosted long tail (jellyfin -> clapperboard, vaultwarden -> key,
home-assistant -> house) plus generic English and German terms; the longest
match wins, so photoprism beats a bare photo, and short keywords like "tv" only
match as whole words. No backfill, no migration, and a rename moves the icon
with it.

That is also why the catalog and the matcher live in the frontend. It is the
only place that can render an icon, so a copy in the backend would be a list to
keep in sync and nothing else. The server validates the shape of the stored
value and stores uploads; it never needs to know what "lucide:database" looks
like. An icon name that later leaves the catalog falls back to the derived one
rather than blanking the row.

Overriding happens in two places, because there are two moments: the editor
(holding a chosen file until the stack exists, since uploading needs an id) and
a click on the icon on the detail page, which is how a stack that has existed
for a year gets one without a trip through the editor.

Uploads are classified by their bytes, not by the filename or Content-Type the
browser claims, and land in ${DATA_DIR}/stack-icons/ under the stack id. SVG is
allowed — <img> does not execute it — but the endpoint serves every icon as an
attachment so one can never be opened as a document in the API's own origin. A
client-supplied "custom:" value is refused: the server mints those, so a stack
cannot be pointed at a file it does not own. Files follow the stack: replaced on
re-upload (including across formats, or the old one orphans), copied on clone,
removed on delete.

The one piece of plumbing worth knowing about: the icon endpoint needs the
bearer token like everything else, and an <img src> would not carry it. So
StackIcon fetches the bytes through the API client and renders the blob, keyed
on the stored value — which carries an upload timestamp precisely so a re-upload
changes the key and retires the cached image.

Covered by 22 backend tests (the value rules, byte-sniffing, the file lifecycle,
the API round-trip, and that the read-only role cannot change an icon) and 29
frontend ones for the matcher. The schema change was verified against a
hand-built pre-0.51 database: the column is added on start and existing rows
come back NULL, i.e. automatic. Not click-tested in a browser — no Docker in
this environment — so the row height the taller icon produces is unverified.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

backend/tests/test_route_authorization.py

@@ -63,6 +63,9 @@ USER_READABLE = {
     "GET /api/stacks/updates",
     "GET /api/stacks/{stack_id}",
     "GET /api/stacks/{stack_id}/auto-update",
+    # The stack's uploaded icon — an image the user already sees next to the
+    # stack's name in the list. Uploading and resetting it stay admin-only.
+    "GET /api/stacks/{stack_id}/icon",
     "GET /api/stacks/{stack_id}/logs",
     "GET /api/stacks/{stack_id}/services/{service}/logs",
     "POST /api/stacks/convert",

backend/tests/test_stack_icons.py

@@ -0,0 +1,219 @@
+"""Stack icons: what the server accepts, stores and hands back.
+
+The interesting part is not "does a column round-trip" — it is the three rules
+that keep the feature from becoming a liability:
+
+* an icon value can only ever be the automatic one or a built-in name; a
+  ``custom:`` value is minted by the server, so a stack can never be pointed at
+  another stack's uploaded file,
+* an upload is classified by its bytes, not by what the client claims it is, and
+* files follow the stack: replaced, cloned and deleted along with it, so the
+  data directory does not fill up with icons of stacks that are long gone.
+"""
+from __future__ import annotations
+
+import os
+
+import pytest
+
+PNG = (
+    b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01"
+    b"\x08\x06\x00\x00\x00\x1f\x15\xc4\x89\x00\x00\x00\nIDAT\x78\x9cc\x00"
+    b"\x01\x00\x00\x05\x00\x01\x0d\n-\xb4\x00\x00\x00\x00IEND\xaeB`\x82"
+)
+SVG = b'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"></svg>'
+
+
+@pytest.fixture
+def svc(db):
+    from services import icon_service
+
+    return icon_service
+
+
+@pytest.fixture
+def stack(db):
+    """A bare stack row to hang icons off, cleaned up afterwards."""
+    from sqlmodel import Session
+
+    from database import engine
+    from models.stack import Stack
+    from services import icon_service
+
+    stack_id = "icon-test-stack"
+    with Session(engine) as session:
+        if (existing := session.get(Stack, stack_id)) is not None:
+            session.delete(existing)
+            session.commit()
+        session.add(Stack(id=stack_id, name="Icon Test Stack"))
+        session.commit()
+    yield stack_id
+    icon_service.remove(stack_id)
+    with Session(engine) as session:
+        if (row := session.get(Stack, stack_id)) is not None:
+            session.delete(row)
+            session.commit()
+
+
+# --------------------------------------------------------------------------- #
+# The stored value
+# --------------------------------------------------------------------------- #
+
+
+def test_a_builtin_choice_is_stored_as_given(svc):
+    assert svc.normalize_choice("lucide:database") == "lucide:database"
+
+
+def test_an_empty_choice_means_automatic(svc):
+    assert svc.normalize_choice("") is None
+    assert svc.normalize_choice("   ") is None
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        # A client-supplied custom value would name a file: that is how one
+        # stack would end up serving another's icon.
+        "custom:png:1",
+        "custom:../other:1",
+        "lucide:../../etc/passwd",
+        "lucide:Database",  # the catalog is lower-kebab; anything else is a typo
+        "https://example.com/logo.png",
+        "<script>alert(1)</script>",
+    ],
+)
+def test_anything_else_is_refused(svc, value):
+    with pytest.raises(svc.IconError):
+        svc.normalize_choice(value)
+
+
+# --------------------------------------------------------------------------- #
+# Uploads
+# --------------------------------------------------------------------------- #
+
+
+def test_an_upload_is_typed_by_its_bytes(svc, stack):
+    assert svc.store_upload(stack, PNG).startswith("custom:png:")
+    assert svc.store_upload(stack, SVG).startswith("custom:svg:")
+
+
+def test_a_file_that_is_not_an_image_is_refused(svc, stack):
+    with pytest.raises(svc.IconError):
+        svc.store_upload(stack, b"#!/bin/sh\nrm -rf /\n")
+
+
+def test_an_oversized_image_is_refused(svc, stack):
+    payload = PNG + b"\x00" * svc.MAX_ICON_BYTES
+    with pytest.raises(svc.IconError):
+        svc.store_upload(stack, payload)
+
+
+def test_reuploading_in_another_format_leaves_no_orphan(svc, stack):
+    svc.store_upload(stack, PNG)
+    assert os.path.isfile(svc.custom_path(stack, "png"))
+    value = svc.store_upload(stack, SVG)
+    assert not os.path.exists(svc.custom_path(stack, "png"))
+    assert svc.file_for(stack, value) == svc.custom_path(stack, "svg")
+
+
+def test_the_value_changes_on_every_upload(svc, stack, monkeypatch):
+    """Otherwise a browser keeps showing the image it already cached."""
+    monkeypatch.setattr("services.icon_service.time.time", lambda: 1000)
+    first = svc.store_upload(stack, PNG)
+    monkeypatch.setattr("services.icon_service.time.time", lambda: 2000)
+    assert svc.store_upload(stack, PNG) != first
+
+
+def test_removing_clears_the_file(svc, stack):
+    value = svc.store_upload(stack, PNG)
+    svc.remove(stack)
+    assert svc.file_for(stack, value) is None
+
+
+def test_a_clone_gets_its_own_copy(svc, stack):
+    value = svc.store_upload(stack, PNG)
+    copied = svc.copy(stack, "icon-test-clone", value)
+    try:
+        assert copied is not None and copied.startswith("custom:png:")
+        assert os.path.isfile(svc.custom_path("icon-test-clone", "png"))
+        # Deleting the source must not take the clone's icon with it.
+        svc.remove(stack)
+        assert svc.file_for("icon-test-clone", copied)
+    finally:
+        svc.remove("icon-test-clone")
+
+
+def test_cloning_a_builtin_choice_carries_the_name_over(svc):
+    assert svc.copy("a", "b", "lucide:database") == "lucide:database"
+    assert svc.copy("a", "b", None) is None
+
+
+# --------------------------------------------------------------------------- #
+# Through the API
+# --------------------------------------------------------------------------- #
+
+
+def test_the_list_row_carries_the_icon(as_admin, stack, svc):
+    from sqlmodel import Session
+
+    from database import engine
+    from models.stack import Stack
+
+    with Session(engine) as session:
+        row = session.get(Stack, stack)
+        row.icon = "lucide:database"
+        session.add(row)
+        session.commit()
+
+    body = as_admin.get(f"/api/stacks/{stack}").json()
+    assert body["icon"] == "lucide:database"
+
+
+def test_upload_download_and_reset_round_trip(as_admin, stack):
+    uploaded = as_admin.post(
+        f"/api/stacks/{stack}/icon",
+        files={"file": ("logo.png", PNG, "image/png")},
+    )
+    assert uploaded.status_code == 200, uploaded.text
+    assert uploaded.json()["icon"].startswith("custom:png:")
+
+    served = as_admin.get(f"/api/stacks/{stack}/icon")
+    assert served.status_code == 200
+    assert served.content == PNG
+    assert served.headers["content-type"] == "image/png"
+    # An SVG icon must never be openable as a document in the API's own origin.
+    assert served.headers["content-disposition"].startswith("attachment")
+
+    assert as_admin.delete(f"/api/stacks/{stack}/icon").json()["icon"] is None
+    assert as_admin.get(f"/api/stacks/{stack}/icon").status_code == 404
+
+
+def test_a_lying_content_type_does_not_get_through(as_admin, stack):
+    response = as_admin.post(
+        f"/api/stacks/{stack}/icon",
+        files={"file": ("logo.png", b"not an image at all", "image/png")},
+    )
+    assert response.status_code == 400
+
+
+def test_switching_to_a_builtin_icon_drops_the_uploaded_file(as_admin, stack, svc):
+    as_admin.post(
+        f"/api/stacks/{stack}/icon", files={"file": ("logo.png", PNG, "image/png")}
+    )
+    as_admin.put(f"/api/stacks/{stack}", json={"icon": "lucide:database"})
+    assert not os.path.exists(svc.custom_path(stack, "png"))
+
+
+def test_an_invalid_icon_on_update_is_a_400(as_admin, stack):
+    response = as_admin.put(f"/api/stacks/{stack}", json={"icon": "custom:png:1"})
+    assert response.status_code == 400
+
+
+def test_the_read_only_role_cannot_change_an_icon(as_user, stack):
+    assert (
+        as_user.post(
+            f"/api/stacks/{stack}/icon", files={"file": ("l.png", PNG, "image/png")}
+        ).status_code
+        == 403
+    )
+    assert as_user.delete(f"/api/stacks/{stack}/icon").status_code == 403