printserver/openspec/changes/warn-on-dnssd-name-collisions/proposal.md

Proposal

Why

On the live deployment (podp), two queues ended up with the identical CUPS Description, so both derived the same DNS-SD instance name ("<Description> @ <host>"). Avahi can register only one of them and CUPS 2.4 never resolves the collision (upstream scheduler/dnssd.c still has /* TODO: Handle collisions with avahi_alternate_service_name */), so one queue showed printer-is-shared=true but was never advertised. macOS pins the exact instance name into the queue's dnssd:// device URI; when the pinned name stops being announced, the Mac reports the printer offline. Because the collision is deterministic, container restarts never helped and only remove/re-add on the client fixed it — hours of debugging with no server-side signal pointing at the cause.

What Changes

• entrypoint.sh: after cupsd is up, derive the DNS-SD instance name of every shared queue (Description if set, otherwise the queue name, plus @ <host>) and log a prominent, non-fatal warning when two or more queues derive the same instance name — naming the affected queues and the fix (give each queue a unique Description, or delete the redundant queue).
• README.md: new Troubleshooting entry "macOS shows the printer offline after some time" documenting the symptom, root cause (client-side instance name pinning + duplicate-Description collision), verification commands (dns-sd -B, lpstat -l -p, ipptool), and the fix including the remove/re-add step on macOS.
• Docs correction: the PRINTER_NAME description in the entrypoint.sh header and in the README currently claims it is the "advertised (DNS-SD) name" — that is only true while no Description is set; the Description overrides it. Correct both places, and clarify the matching requirement in the printserver/cups spec (same claim).

Out of scope: changing how queues are configured (no automatic renaming or de-duplication), and avoiding the lpadmin re-registration churn on restart.

Capabilities

New Capabilities

(none)

Modified Capabilities

• printserver/cups: adds a requirement that the container detects DNS-SD instance-name collisions between shared queues at startup and reports them in the container log, so a queue that silently loses its advertisement is visible to the operator instead of surfacing as an "offline" client hours later.

Impact

• entrypoint.sh — one additional startup diagnostic block (log output only; no change to queue creation, advertisement, or exit behaviour).
• README.md — one new Troubleshooting section; correction of the PRINTER_NAME wording.
• No changes to cupsd.conf, the Containerfile, or runtime behaviour seen by clients; the fix for an existing collision is still a manual operator action (documented in the README).