Add discovery port name helper (DataDog#24555)

* Add discovery port name helper

* Skip empty names when matching ports by name in discovery helper

An empty string in `names` would otherwise match every unnamed port
(Port.name defaults to ""), which is the opposite of the intended
match-by-name semantics.

Environment: Datadog workspace

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

* Document ordering and no-fallback contract on candidate_ports_by_name

The one-liner omitted the name-priority ordering and no-fallback
behavior that the existing tests already assert, matching the sibling
candidate_ports docstring's existing standard.

Environment: Datadog workspace

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

* Parametrize candidate_ports_by_name tests

Folds the five standalone tests into one pytest.mark.parametrize table,
keeping the scenario names as ids so they stay visually aligned and
distinguishable.

Environment: Datadog workspace

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

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

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,16 @@ 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 ports matching each name in order, with no fallback to unmatched ports."""
+    seen: set[int] = set()
+
+    for name in dict.fromkeys(names):
+        if not name:
+            continue
+        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():
     ]
 
 
+@pytest.mark.parametrize(
+    "ports, names, expected",
+    [
+        pytest.param(
+            (
+                Port(number=8080, name='http'),
+                Port(number=9090, name='metrics'),
+                Port(number=8081, name='admin'),
+            ),
+            ['metrics', 'http-prom'],
+            [Port(number=9090, name='metrics')],
+            id="only_yields_matching_ports",
+        ),
+        pytest.param(
+            (
+                Port(number=8080, name='bar'),
+                Port(number=9090, name='foo'),
+                Port(number=8081, name='bar'),
+                Port(number=9091, name='foo'),
+            ),
+            ['foo', 'bar'],
+            [
+                Port(number=9090, name='foo'),
+                Port(number=9091, name='foo'),
+                Port(number=8080, name='bar'),
+                Port(number=8081, name='bar'),
+            ],
+            id="respects_name_priority",
+        ),
+        pytest.param(
+            (
+                Port(number=8080, name='http'),
+                Port(number=8081, name='admin'),
+            ),
+            ['metrics'],
+            [],
+            id="does_not_fallback_to_other_ports",
+        ),
+        pytest.param(
+            (
+                Port(number=8443, name='metrics'),
+                Port(number=8443, name='http-metrics'),
+                Port(number=9443, name='metrics'),
+            ),
+            ['http-metrics', 'metrics'],
+            [
+                Port(number=8443, name='http-metrics'),
+                Port(number=9443, name='metrics'),
+            ],
+            id="deduplicates_matching_port_numbers",
+        ),
+        pytest.param(
+            (Port(number=8080, name=''),),
+            [''],
+            [],
+            id="ignores_empty_names",
+        ),
+    ],
+)
+def test_candidate_ports_by_name(ports, names, expected):
+    service = Service(id='svc', host='127.0.0.1', ports=ports)
+    assert list(candidate_ports_by_name(service, names)) == expected
+
+
 def test_dev_placeholder_field_constants_match_models():
     """Guard the one fact datadog_checks_dev must hand-copy from base.