[feat][client] Embed GraalVM native image config

[david-streamlio]

Main Issue: quarkusio/quarkus#48776

Motivation

Applications using pulsar-client-original in GraalVM native-image builds currently fail unless the consuming framework (Quarkus, Micronaut, Spring Native, etc.) provides its own reflection and class initialization metadata for Pulsar client internals. This forces every framework to independently reverse-engineer and maintain configuration that tracks Pulsar's internal class layout — and when it drifts, native builds break silently.

A concrete example: Quarkus's Pulsar extension registered org.apache.pulsar.client.util.WithSNISslEngineFactory for runtime initialization, but that class was removed in Pulsar 4.x. Because the configuration lived downstream instead of in the client itself, the breakage went unnoticed for a year (quarkusio/quarkus#48776).

Embedding the configuration directly in pulsar-client-original following
the GraalVM embedded configuration convention means the native-image tool picks it up automatically from the classpath, keeping the config in sync with the code that owns the classes.

Modifications

Added three GraalVM native-image configuration files under
pulsar-client/src/main/resources/META-INF/native-image/org.apache.pulsar/pulsar-client-original/:

• reflect-config.json — Registers 20 classes for reflective access:
  the three ConfigurationData classes (deserialized by Jackson), all six
  Authentication implementations (instantiated by name via
  AuthenticationUtil.create()), the OAuth2 protocol model classes, schema
  internals (ProtoBufParsingInfo, ProtobufNativeSchemaData, KeyValue),
  DataURLStreamHandler, and SecretsSerializer.

• native-image.properties — Marks eight classes for runtime
  initialization that would otherwise fail during native-image build due to
  eager static initialization of Netty allocators, thread pools, or HTTP
  clients: PulsarByteBufAllocator, Commands, Backoff, TokenClient,
  GenericProtobufNativeSchema, ConnectionPool,
  ControlledClusterFailover, and HttpClient.

• resource-config.json — Includes the async-http-client default
  properties files that are loaded via classloader at runtime.

Added NativeImageConfigTest that validates:

• All classes referenced in reflect-config.json exist on the classpath
• All classes referenced in native-image.properties exist on the classpath
• All Authentication implementations shipped with the client are registered
• Both JSON config files are well-formed

This test catches configuration drift early — if a class is renamed, removed, or a new Authentication plugin is added without updating the config, the test fails with a descriptive message.

Note: the shaded pulsar-client JAR intentionally strips
META-INF/native-image/** in its shade plugin filters, which is correct since shading relocates packages and invalidates the original class names. Users building native images should depend on pulsar-client-original.

Verifying this change

This change added tests and can be verified as follows:

• Added NativeImageConfigTest that validates all 20 reflection entries and
  8 runtime-initialized classes resolve on the classpath, and that all
  Authentication implementations are registered.
• Every class in the configuration was verified against the Pulsar 4.2.1
  source tree.
• The equivalent configuration (derived from Quarkus's
  SmallRyeReactiveMessagingPulsarProcessor) was validated by successfully
  compiling six native-image integration tests in the Quarkus
  integration-tests/reactive-messaging-pulsar module against Pulsar 4.2.1.

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

• Dependencies (add or upgrade a dependency)
• The public API
• 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-not-needed

[lhotari]

The changes look good so far. However, we'd need an integration test to verify that a Pulsar client application can be compiled to a native image. Besides this, I'd assume that there would have to be a smoke test to cover at least basic functionality (produce/consume).

Would it be possible to add the integration test to tests/pulsar-client-native-image directory? It would be great if the test could be written in TestNG and call the native application with java.lang.ProcessBuilder or similar. The native application could have different cli options to perform the actual logic of each test case. I guess there could also be other ways to add test coverage. Perhaps the TestNG class could be directly native compiled without the need for a separate native application, at least junit is supported in the Gradle GraalVM plugin, however TestNG support is most likely missing. We could add Junit Jupiter dependencies to Pulsar alongside TestNG if that makes things easier. There has been plans to start migrating to Junit Jupiter in Pulsar anyways.

GraalVM Gradle plugin docs: https://graalvm.github.io/native-build-tools/latest/gradle-plugin.html

[david-streamlio]

Thanks for the review, @lhotari! I've added the integration test coverage you asked for. It follows the approach you suggested exactly.

New module: tests/pulsar-client-native-image

• NativeImageTesterApp — a small CLI application (the "native application") with subcommands that perform the actual logic of each test case (e.g. produce, consume, produce-consume). It's the binary that gets compiled to a native image via the native-maven-plugin.
• NativeImageSmokeTest — a TestNG driver that invokes the compiled native binary through java.lang.ProcessBuilder, passing the relevant CLI options per case. It first verifies the client compiles to a native image, then runs a basic produce/consume smoke test against a Pulsar broker started with Testcontainers (PulsarContainer).
• Wired into tests/pom.xml behind a nativeImageTests profile so it's opt-in and doesn't slow the default build. Added a nightly + workflow_dispatch GitHub Actions workflow (ci-pulsar-native-image.yaml) that runs it on a GraalVM community JDK.

I went with the separate-native-application + ProcessBuilder design rather than native-compiling the TestNG class directly, since (as you noted) TestNG native support is missing today. Happy to revisit that toward JUnit Jupiter if/when the migration lands.

I also added native-image metadata for pulsar-client-admin (reflect-config.json / resource-config.json / native-image.properties) covering the Jackson-serialized admin model classes and the runtime-initialized AsyncHttpConnector, with a static validator test — so admin-based client apps compile too.

Let me know if you'd like any changes to the test structure or CLI surface.

[lhotari]

LGTM