[Bug]: SDK ships no native-image reachability metadata, breaking GraalVM builds

Offen
  • Stimmt etwas nicht?
#1,032 3 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Anfängerfreundlichkeit
35/100
Issue-Typ
Bug
Klarheit
Klar beschrieben
Aktivitätsstatus
Ruhig
Bereich
backend, build-system, devtools

Rechercherichtung

Bei diesem Issue geht es um fehlende GraalVM native-image-Metadaten im SDK. Suche im Codebestand nach Verzeichnissen META-INF/native-image/ und @RegisterForReflection-Annotationen. Der Reporter nennt sechs konkrete Blocker; beginne damit, die genannten Klassen und Pakete zu untersuchen (z. B. org.a2aproject.sdk.spec.util.ErrorDetail, org.a2aproject.sdk.grpc.SendMessageRequest, com.google.protobuf.Struct, META-INF/a2a-defaults.properties). Prüfe die Quarkus-Referenzmodule auf MainEventBusProcessorInitializer und dessen Observer. Eine Behebung umfasst das Erstellen von Reachability-Metadatendateien und möglicherweise die Änderung eines Observers zur Verwendung von StartupEvent. Für die Tests muss ein natives Image mit dem SDK erstellt werden.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

What happened?

I hit six distinct blockers building a GraalVM native image of an application that uses the SDK's Quarkus reference server. Each one was only visible after the previous had been fixed, and none of them produced a useful error message at runtime: the application answers HTTP 500 and logs nothing.

Context: I am building an A2A server extension for Quarkus LangChain4j, which exposes a LangChain4j AI service as an A2A agent. It started from a stalled PR by another contributor, who is not involved in this work; that PR predates the 1.x SDK, and most of the current code is my own, bringing it to 1.2.0.Final and to GraalVM native image, which is a first-class target for Quarkus applications. The goal is to land the extension in quarkus-langchain4j proper, so this SDK would ship inside a released Quarkus extension.

# Symptom Root cause My workaround
1 Detected a started Thread in the image heap. Thread name: MainEventBusProcessor MainEventBusProcessorInitializer observes @Initialized(ApplicationScoped.class), which Quarkus fires during static initialization veto the initializer, start the processor on StartupEvent instead
2 AgentCard specifies transport interfaces for unavailable transports: [JSONRPC]. Available transports: [] transports are discovered with ServiceLoader, and Quarkus builds native images with -H:-UseServiceLoaderFeature register the providers at build time
3 every error response becomes HTTP 500 Gson reflects over ErrorDetail register the spec packages for reflection
4 Generated message class "org.a2aproject.sdk.grpc.SendMessageRequest" missing method "getTenant" protobuf reflects over the generated messages when parsing a request register the generated messages for reflection
5 Generated message class "com.google.protobuf.Struct" missing method "newBuilder" the generated messages are built out of protobuf's own well-known types register com.google.protobuf too
6 No default configuration value found for: a2a.blocking.agent.timeout.seconds META-INF/a2a-defaults.properties is not included in the image register the resource

Worth noting for #4: this one is not gRPC-specific. I initially assumed a request is only parsed into a protobuf message when gRPC is the transport serving it, and made the registration conditional on gRPC being present. That broke every JSON-RPC-only native image, because the JSON-RPC path converts to protobuf internally as well.

The request

Would you consider shipping native-image reachability metadata (reachability-metadata.json, or reflect-config.json + resource-config.json) in the SDK jars? That would fix #3–#6 for every consumer, not just Quarkus ones, since GraalVM picks the metadata up automatically from META-INF/native-image/.

Blockers #1 and #2 are Quarkus-specific, but the SDK ships Quarkus reference modules, so they arguably belong to it too. For #1 in particular: starting a thread from an @Initialized(ApplicationScoped.class) observer is questionable in any mode, not only native. Quarkus fires that event during static init, which is the one place a live thread must not be created. Observing StartupEvent instead would be a one-line change.

Why consumer-side registration is fragile: a concrete case from this week

Because consumers have to name the SDK's packages themselves, the metadata silently drifts out of sync with the SDK.

Upgrading my extension from 1.1.0.Final to 1.2.0.Final, #987 (refactor!: resolve all split packages) moved ErrorDetail:

org.a2aproject.sdk.util  →  org.a2aproject.sdk.spec.util

My reflection registration still named the old package, which no longer exists, so blocker #3 came straight back: every error response returned HTTP 500 again. All 41 of my JVM unit tests passed against 1.2.0. The failure only appeared in the native integration tests, and only on the two tests that assert an error response. Had the metadata lived in the SDK jars, it would have moved along with the class and nobody downstream would have noticed.

Verified against 1.2.0.Final

There is no reachability-metadata.json, reflect-config.json, native-image.properties, @RegisterForReflection or GraalVM substitution anywhere under src/main in the repository, and blockers #1, #2 and #6 still reproduce as described. MainEventBusProcessorInitializer still observes @Initialized(ApplicationScoped.class).

I would be glad to prepare a PR for the metadata, and separately for the StartupEvent change, if you agree with the direction, though I would rather confirm the shape you prefer before writing it.

Relevant log output
# 1: build time
Error: Detected a started Thread in the image heap. Thread name: MainEventBusProcessor

# 2: startup
java.lang.IllegalStateException: AgentCard specifies transport interfaces for unavailable
transports: [JSONRPC]. Available transports: []

# 4: request time, HTTP 500
Invalid request content: Generated message class
"org.a2aproject.sdk.grpc.SendMessageRequest" missing method "getTenant"

# 5: request time, HTTP 500
Generated message class "com.google.protobuf.Struct" missing method "newBuilder"

# 6: startup
java.util.NoSuchElementException: No default configuration value found for:
a2a.blocking.agent.timeout.seconds
Environment
  • a2a-java 1.2.0.Final (originally found on 1.1.0.Final)
  • Quarkus 3.33.2, Mandrel 25.0.2
Code of Conduct
  • I agree to follow this project's Code of Conduct
Vorherrschende Sprache
Java
Sterne
510
Forks
196
Ø Merge
2 T. 9 Std.
Gemergte PRs (30 T.)
50

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus a2aproject/a2a-java

Alle Issues in a2aproject/a2a-java

Ähnliche Issues

Weitere Issues zu Java

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.