upstream: add per-host preconnect eligibility policy

[vilieva]

Commit Message: upstream: add per-host preconnect eligibility policy

Additional Description:
Adds an optional MetadataMatcher, Cluster.PreconnectPolicy.preconnect_enabled_metadata,
that gates anticipatory upstream connections per host. Non-matching hosts are never
preconnected but still get connections on demand when serving requests. Suppressed
preconnects increment the new upstream_cx_preconnect_skipped counter. With no matcher
configured, all hosts stay eligible, preserving backwards compatibility.

Portions of the implementation and tests were developed with generative-AI assistance; I
fully understand and take ownership of the code.

Risk Level: Low; new behavior is opt-in. The only always-on change is that
shouldCreateNewConnection consults per-host eligibility, which is empty for clusters that
have not opted in.

Testing:

• Unit: //test/common/conn_pool:conn_pool_base_test (eligible/ineligible preconnect,
  explicit preconnect, and skip accounting).
• Unit: //test/common/upstream:cluster_manager_misc_test (shouldPreconnect with and
  without a configured matcher).
• Integration: //test/integration:integration_test (skips ineligible host, allows
  eligible host, verifies no over-count of the skip counter when no preconnect is wanted).

Docs Changes:

• Inline API documentation on the new preconnect_enabled_metadata field.
• New upstream_cx_preconnect_skipped counter documented in the cluster stats reference.

Release Notes:

• changelogs/current/new_features/upstream__added-preconnect-eligibility-matcher.rst

Platform Specific Features: None.

[Optional Runtime guard:] None. The change is opt-in and default behavior is unchanged; I
can add a runtime guard for the shouldCreateNewConnection path if a reviewer prefers.

[Optional Fixes #Issue:] Fixes #46151

[Optional API Considerations:] This PR modifies the api/ tree; the API Review Checklist
(https://github.com/envoyproxy/envoy/blob/main/api/review_checklist.md) is addressed in
the linked issue. Summary: opt-in with backwards-compatible default, reuses the common
type.matcher.v3.MetadataMatcher, added as a first-class PreconnectPolicy field rather
than an extension point (the matcher already provides the needed flexibility), failure
mode falls back to on-demand connections, and per-decision cost is limited to clusters
that configure a matcher.

[repokitteh-read-only]

Hi @vilieva, welcome and thank you for your contribution.

We will try to review your Pull Request as quickly as possible.

In the meantime, please take a look at the contribution guidelines if you have not done so already.

🐱

Caused by: #46153 was opened by vilieva.

see: more, trace.

[repokitteh-read-only]

CC @envoyproxy/api-shepherds: Your approval is needed for changes made to (api/envoy/|docs/root/api-docs/).
envoyproxy/api-shepherds assignee is @adisuissa
CC @envoyproxy/api-watchers: FYI only for changes made to (api/envoy/|docs/root/api-docs/).

🐱

Caused by: #46153 was opened by vilieva.

see: more, trace.

[yanavlasov]

@vilieva please merge main to resolve conflicts, so CI can run.

[yanavlasov]

/wait

[vilieva]

main is merged, thanks for taking a look!

[yanavlasov]

Looks good. Will wait for @adisuissa to LGTM API.

/wait-any

[vilieva]

Thanks! I used this field as inspiration for the API change

envoy/api/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto

Line 197 in 3909067

type.matcher.v3.MetadataMatcher filter_enabled_metadata = 14;

- I hope my usage is consistent.

Need to think a bit here.

[adisuissa]

/lgtm api

[vilieva]

Any other context I can provide to help sus this out? Or any use cases I can investigate?

[mathetake]

gently ping @yanavlasov

[agrawroh]

LGTM, Thanks!

[agrawroh]

Since @yanavlasov previously approved and it was only blocked on the API review, I think it should be okay to merge.