Brief overview
Make restheart-stripe work in the GraalVM native image build.
Rationale
RESTHeart ships native executables, and a module that only works on the JVM is a module the native distribution silently lacks. stripe-java is a reflection-heavy library — it deserialises every API object through Gson — so it will not work under native-image without configuration.
Detailed documentation
1. Reflection
stripe-java maps JSON to model classes (Event, Session, Customer, Subscription, Invoice, and the nested objects each of them carries) via Gson, which instantiates and populates them reflectively. Under native-image these classes are unreachable through static analysis: the failure is a runtime deserialisation error on the first webhook or API response, not a build failure.
Register the reflectively-used classes in reflect-config.json. Rather than enumerating them by hand, generate with the tracing agent:
java -agentlib:native-image-agent=config-output-dir=...
driving the module through a full exercise — every webhook event type, a checkout session, a portal session, a customer creation — since the agent only sees what actually runs. This is the reason the multi-tenant and event-coverage tests from #678 matter here.
2. Where the configuration goes
Follow the pattern already used for the other modules under core/src/main/resources/META-INF/native-image/org.restheart/. Recent work in this area (native image resource extraction and indexing) sets the precedent for how module resources are handled; align with it rather than adding a parallel mechanism.
3. Other native-image concerns
- HTTPS — the module makes outbound TLS calls to
api.stripe.com; the native image needs the security providers and trust store available at runtime
- Resources — check whether
stripe-java loads anything from the classpath at runtime (version properties, CA bundles) and add resource configuration accordingly
- Initialisation — if any Stripe class is initialised at build time it may capture state that must be runtime-initialised instead; the API key handling in particular must not be frozen into the image
4. Verification
The native build must be exercised, not merely built: a native image that starts and fails on the first webhook is the expected failure mode here. At minimum run the locally-signed webhook test (which needs no Stripe connection) against the native executable.
Depends on: #667 #668 #669 #670 #671 #672 #673 #674 #675 #676 #677 #681 #682 #683 #684
Brief overview
Make
restheart-stripework in the GraalVM native image build.Rationale
RESTHeart ships native executables, and a module that only works on the JVM is a module the native distribution silently lacks.
stripe-javais a reflection-heavy library — it deserialises every API object through Gson — so it will not work undernative-imagewithout configuration.Detailed documentation
1. Reflection
stripe-javamaps JSON to model classes (Event,Session,Customer,Subscription,Invoice, and the nested objects each of them carries) via Gson, which instantiates and populates them reflectively. Undernative-imagethese classes are unreachable through static analysis: the failure is a runtime deserialisation error on the first webhook or API response, not a build failure.Register the reflectively-used classes in
reflect-config.json. Rather than enumerating them by hand, generate with the tracing agent:driving the module through a full exercise — every webhook event type, a checkout session, a portal session, a customer creation — since the agent only sees what actually runs. This is the reason the multi-tenant and event-coverage tests from #678 matter here.
2. Where the configuration goes
Follow the pattern already used for the other modules under
core/src/main/resources/META-INF/native-image/org.restheart/. Recent work in this area (native image resource extraction and indexing) sets the precedent for how module resources are handled; align with it rather than adding a parallel mechanism.3. Other native-image concerns
api.stripe.com; the native image needs the security providers and trust store available at runtimestripe-javaloads anything from the classpath at runtime (version properties, CA bundles) and add resource configuration accordingly4. Verification
The native build must be exercised, not merely built: a native image that starts and fails on the first webhook is the expected failure mode here. At minimum run the locally-signed webhook test (which needs no Stripe connection) against the native executable.
Depends on: #667 #668 #669 #670 #671 #672 #673 #674 #675 #676 #677 #681 #682 #683 #684