feat(service-catalog): split printer-device access and LAN discovery lane (closes #67)

[clubanderson]

Summary

Defines the printer-device access and LAN mDNS discovery validation lane as a standalone split from the base print-service lane (#64). Closes #67.

Dependency chain (made explicit by this PR)

#54 substrate (USB device passthrough + LAN network policy on ghost)
    → #67 this lane (USB access + mDNS discovery contract proven)
    → #64 base print lane (already unblocked; this lane extends it)

Acceptance criteria check

• Printer-device access and discovery requirements are split clearly from the base non-media lane — dedicated tests/service_catalog/print_device/ module, separate WorkflowTemplate
• The issue states which assumptions depend on epic: homelab cluster substrate and fleet-client model #54 or other substrate work — module docstring + §7 docs table lists USB and mDNS substrate requirements from epic: homelab cluster substrate and fleet-client model #54 explicitly
• The boundary between base non-media validation and attached-printer follow-up is explicit — §7 boundary table shows what each lane validates
• The issue is linked to epic: homelab service-catalog workload validation #51 and feat: define first non-media homelab workload lane #64 — module docstring, commit, and PR reference all linked issues

What's in this PR

tests/service_catalog/print_device/test_print_device_discovery.py

Two independent test classes with separate skip gates:

TestPrinterDeviceAccessLane (gate: TEST_USB_PRINTER_DEVICE env var)

Test	What it proves
test_usb_device_node_exists_in_container	hostPath device node visible in CUPS container
test_usb_device_node_is_character_device	node is a real character device, not a placeholder
test_cups_can_detect_local_usb_printer	CUPS lpinfo -v reports USB URI
test_cups_accepts_test_print_job	lp submits job without error (cancelled immediately)
test_usb_device_permissions_allow_cups_user	CUPS user can r/w device node
test_kubevirt_usb_passthrough_is_out_of_scope	pytest.skip → #54

TestLanDiscoveryLane (gate: TEST_AVAHI_ENABLED=true)

Test	What it proves
test_ipp_service_exposed_outside_cluster	service type is NodePort or LoadBalancer
test_nodeport_is_reachable_on_node_ip	NodePort reachable from inside cluster using host IP
test_avahi_sidecar_container_is_running	avahi sidecar container is Ready
test_avahi_daemon_process_is_active	avahi-daemon process is alive inside sidecar
test_avahi_daemon_advertises_ipp_service	avahi-browse _ipp._tcp finds the record
test_avahi_service_file_is_present_in_config	.service file present in /etc/avahi/services/
test_auth_gated_cups_ui_is_out_of_scope	pytest.skip → deferred
test_split_horizon_dns_for_cups_is_out_of_scope	pytest.skip → bluespeed

Both classes skip cleanly when their gate condition is not met — non-hardware CI is not broken.

argo/workflow-templates/homelab-print-device.yaml

WorkflowTemplate with parameterized hardware paths:

• usb-device-path: if set, adds hostPath volume + enables USB tests
• avahi-enabled: true: adds avahi sidecar + NodePort service + enables mDNS tests
• check-prerequisites guard step emits informative epic: homelab cluster substrate and fleet-client model #54 instructions without failing the workflow
• Fixture uses lscr.io/linuxserver/cups:latest (real CUPS, not nginx stub — USB tests need lpinfo/lp)
• Avahi sidecar: ubuntu:22.04 + avahi-daemon + ConfigMap-mounted _ipp._tcp service file

docs/homelab-contracts.md

• §6: feat: split printer-device access and LAN discovery from the base non-media lane #67 status updated → ✅ defined
• §7: New section — Printer-Device Access and LAN Discovery Lane with boundary table, substrate assumptions tables (USB + mDNS), behavior tables for both test classes, WorkflowTemplate parameters table

Dependencies

• epic: homelab cluster substrate and fleet-client model #54 homelab substrate (USB device passthrough + LAN network policy) — must be done before tests execute
• feat: define first non-media homelab workload lane #64 base print-service lane (this PR extends it with hardware paths)

[hanthor]

LGTM — well-structured test/infra addition, clean code.

[hanthor]

Service-catalog lane addition. Merge after foundational #202. LGTM.

[hanthor]

Approved via org-wide review.

[hanthor]

Approved via org-wide review.

[hanthor]

Review: Approved ✅

Part of the structured service-catalog project build-up. Conventional Commits format, referenced issues, consistent with related PRs in the series.