# Tasks

## 1. entrypoint: Erkennung von DNS-SD-Namenskollisionen

- [ ] 1.1 `entrypoint.sh`: Funktion `check_dnssd_name_collisions` ergänzen,
      aufgerufen nach dem TCP-631-Check und vor
      `log "ready: CUPS on 631/tcp, mDNS on 5353/udp"`. Queue-Namen und
      Descriptions via `LC_ALL=C lpstat -l -p` lesen (Locale-fest, live aus
      cupsd), Shared-Flag je Queue aus `/etc/cups/printers.conf`
      (`<Printer …>`-Block, `Shared yes`); unbekannter Shared-Status zählt als
      geteilt. Pro Queue den Anzeigenamen ableiten: Description, sonst
      Queue-Name.
      Verifikation: `sh -n entrypoint.sh` läuft fehlerfrei,
      `grep -n 'check_dnssd_name_collisions' entrypoint.sh` zeigt Definition
      und Aufruf an der vorgesehenen Stelle.
- [ ] 1.2 Bei gleichen abgeleiteten Namen pro Kollisionsgruppe über den
      bestehenden `log()`-Stil warnen (Mehrzeiler, analog zum TCP-631-Block):
      kollidierender Anzeigename `<basis> @ <host>`, betroffene Queue-Namen,
      Abhilfe (einzigartige Description je Queue per `lpadmin -D` oder
      redundante Queue entfernen per `lpadmin -x`, danach Client-Queue auf dem
      Mac entfernen und neu hinzufügen — Details im README). Bei eindeutigen
      Namen keine Warnung ausgeben.
      Verifikation: `grep -n 'warning:' entrypoint.sh` findet die neuen
      Warnzeilen inkl. `lpadmin -D`-Remedies; das Verhalten selbst prüfen die
      Aufgaben 3.2 (Kollision) und 3.3 (keine Kollision).
- [ ] 1.3 Alle Parseschritte abfangen, ohne dass `set -eu` den Start abbricht
      (`|| true` / geblockte Substitutionen): fehlendes oder unlesbares
      `printers.conf`,
      fehlerhaftes `lpstat` → Prüfung still überspringen oder als geteilt
      annehmen, niemals `exit` und niemals Abbruch der Queue-Einrichtung.
      Verifikation: `sh -n entrypoint.sh` fehlerfrei; Startverhalten mit
      fehlendem `printers.conf` ist in 3.4 abgedeckt.

## 2. README: Troubleshooting und PRINTER_NAME-Korrektur

- [ ] 2.1 `README.md`: neuen Troubleshooting-Abschnitt
      „macOS shows the printer offline after some time" (englisch, Stil der
      bestehenden `###`-Abschnitte) einfügen: Symptom (Queue existiert,
      Status offline, erst nach Stunden/Wechseln sichtbar), Ursache
      (macOS pinnt den exakten DNS-SD-Instanznamen `"<Description> @ <host>"`
      in die `dnssd://`-Device-URI; zwei Queues mit gleicher Description
      kollidieren, Avahi registriert nur eine, CUPS 2.4 benennt nicht um),
      Diagnose-Befehle (`podman logs` Warnung, `dns-sd -B _ipp._tcp`,
      `avahi-browse -rt _ipp._tcp`, `lpstat -l -p`, `ipptool -tv`), Heilung
      (eindeutige Description bzw. `-x`, dann Remove/Re-add auf macOS — mit dem
      Hinweis, warum Restart allein nicht hilft: Kollision ist deterministisch).
      Verifikation: jeder im Abschnitt stehende Befehl läuft unverändert gegen
      den laufenden Container (lokal aus 3.1 bzw. gegen podp).
- [ ] 2.2 `PRINTER_NAME`-Wording korrigieren: README-Tabelle („Also used as
      the name advertised via AirPrint/DNS-SD") und Fließtext unter
      *Environment variables* sowie die Kopfkommentarzeile in
      `entrypoint.sh` („advertised (DNS-SD) name") präzisieren: Der
      Queue-Name ist nur die Basis, solange keine Description gesetzt ist —
      `PRINTER_DESCRIPTION` (bzw. `-D`) hat Vorrang für den Anzeigenamen.
      Verifikation: `grep -n 'PRINTER_NAME' README.md entrypoint.sh` zeigt an
      allen drei Stellen die korrigierte Formulierung mit Description-Vorrang.

## 3. Integrationstests (podman, lokal)

- [ ] 3.1 Image bauen und ohne Kollision starten.
      Verifikation: `podman build -t printserver:latest .` endet ohne Fehler;
      `podman run …` erreicht „ready: CUPS on 631/tcp, mDNS on 5353/udp";
      `podman logs` enthält KEINE Kollisions-Warnung (falls 631 nicht bindet:
      `podman machine ssh -- sudo sysctl -w net.ipv4.ip_unprivileged_port_start=631`
      wie bei der Vorgängeränderung).
- [ ] 3.2 Kollision erzeugen und Warnung nachweisen.
      Verifikation: zweite Queue mit der Description des ersten Queues anlegen
      (`podman exec printserver lpadmin -p dup -E -v socket://192.0.2.1:9100
      -D "<identische Description>"`), danach `podman restart printserver`:
      `podman logs` enthält die Warnung mit Anzeigename, beiden Queue-Namen und
      Remedie, und der Start endet trotzdem mit „ready" (Warnung nicht fatal).
- [ ] 3.3 Kollision beheben → Warnung verschwindet.
      Verifikation: `podman exec printserver lpadmin -p dup -D "Dup Queue"`
      (eindeutige Description), `podman restart printserver`: das Log enthält
      keine Kollisions-Warnung mehr und endet mit „ready".
- [ ] 3.4 Fehlendes `printers.conf` darf den Start nicht brechen.
      Verifikation: `podman exec printserver sh -c 'cp /etc/cups/printers.conf /tmp/pc.bak && rm /etc/cups/printers.conf'`
      danach `podman restart printserver`: der Container erreicht „ready";
      anschließend Status wiederherstellen
      (`podman exec … cp /tmp/pc.bak /etc/cups/printers.conf`) bzw. den
      Testcontainer verwerfen.

## Workflow follow-up

- README-Abschnitt und Warnung gegen die echte Konstellation auf `podp`
  prüfen: nach Deploy (Image neu bauen, Quadlet-Restart) muss die Warnung für
  `laser`/`laserdrucker-im-buero` erscheinen, bis die Descriptions eindeutig
  gemacht oder die redundante Queue entfernt ist — danach muss sie weg sein.
- Nach Review und grünem Durchlauf die Änderung mit `/opsx-archive`
  archivieren und das Ergebnis prüfen.