Add discovery port name helper

Author: vitkyrka

datadog_checks_base/changelog.d/24555.added

@@ -0,0 +1 @@
+Add a discovery helper for selecting service ports by name.

datadog_checks_base/datadog_checks/base/utils/discovery/__init__.pyi

@@ -1,7 +1,7 @@
 # (C) Datadog, Inc. 2025-present
 # All rights reserved
 # Licensed under a 3-clause BSD style license (see LICENSE)
-from .discovery import Discovery, Port, Service, candidate_ports
+from .discovery import Discovery, Port, Service, candidate_ports, candidate_ports_by_name
 from .strategies import discovery_strategy
 
-__all__ = ['Discovery', 'Port', 'Service', 'candidate_ports', 'discovery_strategy']
+__all__ = ['Discovery', 'Port', 'Service', 'candidate_ports', 'candidate_ports_by_name', 'discovery_strategy']

datadog_checks_base/datadog_checks/base/utils/discovery/discovery.py

@@ -60,3 +60,14 @@ def candidate_ports(service: Service, hints: Iterable[int]) -> Iterator[Port]:
         if port.number not in seen:
             seen.add(port.number)
             yield port
+
+
+def candidate_ports_by_name(service: Service, names: Iterable[str]) -> Iterator[Port]:
+    """Yield service ports matching one of the provided names."""
+    seen: set[int] = set()
+
+    for name in dict.fromkeys(names):
+        for port in service.ports:
+            if port.name == name and port.number not in seen:
+                seen.add(port.number)
+                yield port

datadog_checks_base/tests/base/utils/discovery/test_discovery.py

@@ -6,7 +6,7 @@
 import mock
 import pytest
 
-from datadog_checks.base.utils.discovery import Discovery, Port, Service, candidate_ports
+from datadog_checks.base.utils.discovery import Discovery, Port, Service, candidate_ports, candidate_ports_by_name
 
 
 def test_include_empty():
@@ -209,6 +209,70 @@ def test_candidate_ports_prefers_hints_and_deduplicates():
     ]
 
 
+def test_candidate_ports_by_name_only_yields_matching_ports():
+    service = Service(
+        id='svc',
+        host='127.0.0.1',
+        ports=(
+            Port(number=8080, name='http'),
+            Port(number=9090, name='metrics'),
+            Port(number=8081, name='admin'),
+        ),
+    )
+
+    assert list(candidate_ports_by_name(service, ['metrics', 'http-prom'])) == [Port(number=9090, name='metrics')]
+
+
+def test_candidate_ports_by_name_respects_name_priority():
+    service = Service(
+        id='svc',
+        host='127.0.0.1',
+        ports=(
+            Port(number=8080, name='bar'),
+            Port(number=9090, name='foo'),
+            Port(number=8081, name='bar'),
+            Port(number=9091, name='foo'),
+        ),
+    )
+
+    assert list(candidate_ports_by_name(service, ['foo', 'bar'])) == [
+        Port(number=9090, name='foo'),
+        Port(number=9091, name='foo'),
+        Port(number=8080, name='bar'),
+        Port(number=8081, name='bar'),
+    ]
+
+
+def test_candidate_ports_by_name_does_not_fallback_to_other_ports():
+    service = Service(
+        id='svc',
+        host='127.0.0.1',
+        ports=(
+            Port(number=8080, name='http'),
+            Port(number=8081, name='admin'),
+        ),
+    )
+
+    assert list(candidate_ports_by_name(service, ['metrics'])) == []
+
+
+def test_candidate_ports_by_name_deduplicates_matching_port_numbers():
+    service = Service(
+        id='svc',
+        host='127.0.0.1',
+        ports=(
+            Port(number=8443, name='metrics'),
+            Port(number=8443, name='http-metrics'),
+            Port(number=9443, name='metrics'),
+        ),
+    )
+
+    assert list(candidate_ports_by_name(service, ['http-metrics', 'metrics'])) == [
+        Port(number=8443, name='http-metrics'),
+        Port(number=9443, name='metrics'),
+    ]
+
+
 def test_dev_placeholder_field_constants_match_models():
     """Guard the one fact datadog_checks_dev must hand-copy from base.