[feat][misc] PIP-478: dedicated pulsar-tls-factory-api and pulsar-http-client-api SPI modules

[lhotari]

PIP: #25890

Motivation

This is the first implementation PR for PIP-478. The implementation is split into a series of PRs submitted one at a time; this one lands only the foundation the rest of the PIP builds on: two small, dependency-light SPI modules. Nothing consumes them yet, so there is no behavioural change to any existing module.

• pulsar-tls-factory-api — the purpose-driven PulsarTlsFactory TLS SPI that replaces PIP-337. A factory is asked only for a ready-built TLS object for a given TlsPurpose, with rotation confined to a reload callback (rebuild-not-mutate) and key material never crossing a Pulsar API — so KMS/HSM and workload-identity integrations become first-class instead of requiring a fork of the SSL layer. The flat TlsPolicy value type carries cert/key/trust material (PEM or keystore), ciphers/protocols, hostname verification, and three orthogonal provider axes: the TLS engine (JDK vs native OpenSSL), the JSSE (SSLContext) provider (jsseProvider), and the JCA crypto provider that parses key material (jcaProvider).
• pulsar-http-client-api — the framework-managed PulsarHttpClient SPI, so authentication plugins share the client's HTTP runtime (event loops, timers, DNS caches, TLS-material refresh) instead of spinning up private AsyncHttpClient instances.

They live in their own modules — rather than inside a client artifact — so the sibling broker-side PIP can depend on them without importing a client jar.

Modifications

• New module pulsar-tls-factory-api: PulsarTlsFactory, TlsPolicy, TlsPurpose, TlsFactoryInitContext, TlsHandle, TlsEndpoint.
• New module pulsar-http-client-api (depends on the former): PulsarHttpClient, PulsarHttpClientFactory, PulsarHttpClientConfig, HttpRequest, HttpResponse.
• Build wiring: settings.gradle.kts, pulsar-bom, the pulsar-common test dependency on the SPI types, and the binary-license check.
• Unit tests for TlsPolicy validation and TlsPurpose.

Both modules compile standalone against master; no existing code references them.

Verifying this change

This change added tests and can be verified as follows:

• TlsPolicyValidationTest — TlsPolicy builder validation (PEM vs keystore, required fields).
• TlsPurposeTest — TlsPurpose identity, role, and equality.
• The two modules build and pass check standalone (./gradlew :pulsar-tls-factory-api:build :pulsar-http-client-api:build), and ./gradlew quickCheck (license headers + checkstyle) passes over the tree.

Does this pull request potentially affect one of the following parts:

If the box was checked, please highlight the changes

• Dependencies (add or upgrade a dependency) — adds two new modules to settings.gradle.kts and pulsar-bom; no third-party dependencies added.
• The public API — introduces the org.apache.pulsar.tls and org.apache.pulsar.http SPI packages as new public API. They are additive and unreferenced by existing code in this PR.
• The schema
• The default values of configurations
• The threading model
• The binary protocol
• The REST endpoints
• The admin CLI options
• The metrics
• Anything that affects deployment

Documentation

• doc-required
• doc-not-needed — SPI modules with no user-facing surface yet; the PIP-478 design document ([feat][pip] PIP-478: Asynchronous v5 client auth plugin interfaces and TLS material provider plugin interface #25890) covers the design.
• doc
• doc-complete

Matching PR in forked repository

PR in forked repository: lhotari/pulsar (Personal CI)

_{This PR was prepared with the assistance of Claude Code (Opus 4.8); the change was reviewed and is submitted by a human contributor who takes responsibility for it, per the ASF Generative Tooling guidance.}

[void-ptr974]

I noticed that pulsar-common declares api(project(":pulsar-tls-factory-api")), while this PR does not add any main-source usage of the TLS SPI in pulsar-common (only tests use it). This makes the new TLS SPI, and its transitive OpenTelemetry API dependency, part of the published dependency graph of pulsar-common. Is that intentional at this stage?

[lhotari]

I noticed that pulsar-common declares api(project(":pulsar-tls-factory-api")), while this PR does not add any main-source usage of the TLS SPI in pulsar-common (only tests use it). This makes the new TLS SPI, and its transitive OpenTelemetry API dependency, part of the published dependency graph of pulsar-common. Is that intentional at this stage?

there will be 4 more PRs for PIP-478 implementation. The dependency will get used in future PRs.