Make port descriptors caller-owned

[bneradt]

Marking as a draft pending community approval from a dev@trafficserver.apache.org email.

---

TSPortDescriptorParse allocates an HttpProxyPort that plugins cannot
release, so every parsed descriptor leaks for the lifetime of Traffic
Server. The API also lacks end-to-end coverage for accepting
connections on a parsed port.

This patch replaces the pointer handle with caller-owned opaque storage
whose size and alignment are checked against HttpProxyPort. It updates
API users and adds an AuTest plugin that listens on a dynamically
selected port.

Fixes: #6894

[Copilot]

Pull request overview

This PR addresses a long-standing leak in the TSPortDescriptor API by changing the API from returning an unfreeable heap-allocated handle to using caller-owned opaque storage, and adds end-to-end coverage to verify a plugin can actually listen on a parsed descriptor.

Changes:

• Redesign TSPortDescriptor to be caller-owned opaque storage; update TSPortDescriptorParse / TSPortDescriptorAccept signatures and all in-tree call sites.
• Add an AuTest plugin + gold test that parses a dynamically selected port descriptor and successfully accepts a connection.
• Remove the TSPortDescriptor regression-test leak suppression now that the leak is fixed.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
include/ts/apidefs.h.in	Redefines TSPortDescriptor as caller-owned opaque storage.
include/ts/ts.h	Updates API declarations and docs for the new parse/accept signatures and ownership model.
src/api/InkAPI.cc	Implements storage-backed parsing (placement-new) and updates accept to use the new descriptor representation.
src/api/InkAPITest.cc	Updates the regression test to use the new parse/accept API shape.
example/plugins/c-api/passthru/passthru.cc	Updates example plugin to use the new parse/accept signatures.
tests/tools/plugins/port_descriptor.cc	Adds an autest plugin that parses/accepts a descriptor and closes accepted connections.
tests/tools/plugins/CMakeLists.txt	Builds the new port_descriptor autest plugin.
tests/gold_tests/pluginTest/port_descriptor/port_descriptor.test.py	Adds a gold test that connects to the dynamically chosen descriptor port (via nc).
ci/asan_leak_suppression/regression.txt	Drops the suppression for the previously-leaking regression test.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.

Suppressed comments (2)

src/api/InkAPI.cc:27

• InkAPI.cc now uses std::is_trivially_destructible_v but does not include <type_traits> directly, relying on transitive includes. Add the header here to keep dependencies explicit and avoid build breaks if include graphs change.

#include <tuple>

include/ts/apidefs.h.in:1155

• TSPortDescriptor’s opaque storage is hard-coded to 216 bytes with 8-byte alignment, while the implementation enforces exact size/alignment equality with HttpProxyPort. This is brittle across platform/compiler/flag variations and requires manual updates whenever HttpProxyPort layout changes. Consider generating the size/alignment into apidefs.h from the build (or providing headroom and using >= static_asserts) to reduce churn and portability risk.

class alignas(std::uint64_t) TSPortDescriptor
{
  friend TSReturnCode TSPortDescriptorParse(const char *, TSPortDescriptor *);
  friend TSReturnCode TSPortDescriptorAccept(const TSPortDescriptor *, struct tsapi_cont *);

private:
  std::byte _opaque[216];
};

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.

Suppressed comments (1)

include/ts/apidefs.h.in:1156

• TSPortDescriptorParse() placement-news HttpProxyPort into result->_opaque. Right now _opaque itself has alignment 1 (std::byte), so correct alignment relies on _opaque staying the first member and the class-level alignas not changing. If a future change adds a member before _opaque, the placement-new could become misaligned and trigger UB. Align _opaque itself so its address is always sufficiently aligned regardless of member ordering.

private:
  std::byte _opaque[216];
  bool      _is_valid{false};
};

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.