Quarkus integration via shared transport Vert.x and Smithy Codegen extension

[chenliu0831]

Issue #, if available: N/A, supersede #1196 since we decide to go single/unified server approach with shared transport first.

What

A Smithy-Java server that runs inside Quarkus. Users produce a @produces Service bean; operations mount on Quarkus's HTTP router as a single catch-all Vert.x route. Smithy operations share Quarkus's port.

Customer experience

  @Produces @Singleton
  Service coffeeShop() {
      return CoffeeShop.builder()
              .addGetMenuOperation(new GetMenu())
              .addCreateOrderOperation(new CreateOrder())
              .build();
  }

End-to-end example: examples/quarkus-server/ (CoffeeShop). The README walks through
publishToMavenLocal → quarkusDev → curl probes for restJson1, rpcv2Cbor, and rpcv2Json, plus a fall-through section that demonstrates the three resolution outcomes via observable 404 shapes.

Key abstractions to review

Reviewers can stop after these six classes and have the whole picture. Listed in the order a request flows through them.

:server:server-vertx

SmithyVertxServer (server-vertx/.../SmithyVertxServer.java) — the single public type,
where the whole module's behavior lives.

• Handler<RoutingContext> that owns the ProtocolResolver, orchestrator pool, and dispatch
  loop.
• create(services, protocols, options) constructs; handle(rc) is the route handler.
• shutdown() drains workers — idempotent, returns the cached future.

ServerOptions — two knobs: workerCount and pathPrefix. Intentionally narrow.

• Adding a knob requires an ADR.
• No interceptor field (locked in by a tripwire test); no shutdownGrace (caller-bounded).

VertxRequestHeaders — adapter from Vert.x's MultiMap to Smithy's HttpHeaders.

• The only hand-written adapter we need.
• Review for case-sensitivity correctness and the MultiMap.size() delegation.

:quarkus-smithy (runtime)

SmithyVertxRecorder (quarkus-smithy/.../SmithyVertxRecorder.java) — Quarkus @Recorder
invoked at RUNTIME_INIT.

• Collects @Produces Service beans from Arc, walks TCCL+own-loader for
  ServerProtocolProviders, builds ServerOptions, mounts the catch-all route, registers
  shutdown tasks.
• Shutdown ordering matters: Quarkus's ShutdownContext runs LIFO, so route.remove() is
  registered after server.shutdown() to ensure it runs first.
• Applies quarkus.smithy.server.shutdown-grace as a .get(grace, MS) deadline on the
  otherwise-unbounded server-shutdown future.

SmithyServerConfig — @ConfigMapping for quarkus.smithy.server.*.

• Three keys: path-prefix, workers, shutdown-grace.
• Review for default values and omitted-config behavior.

:quarkus-smithy-deployment (build-time)

SmithyProcessor (quarkus-smithy-deployment/.../SmithyProcessor.java) — the Quarkus
@BuildStep glue.

• Marks Service beans Unremovable so Arc keeps them even without a direct injection point.
• Wires the recorder at RUNTIME_INIT; falls back from mainRouter to httpRouter when
  quarkus.http.root-path=/.
• Companion SmithyCodeGenProvider (worth a glance) hooks Smithy code generation into
  quarkusGenerateCode.

E2E Tests

#	Protocol	Operation	Request	Expected	Result
1	restJson1	GetMenu	GET /menu	200, JSON menu	✅
2	restJson1	CreateOrder	PUT /order body {"coffeeType":"LATTE"}	200, returns id	✅
3	restJson1	GetOrder	GET /order/<id>	200, returns order	✅
4	rpcv2Cbor	GetMenu	POST /service/CoffeeShop/operation/GetMenu + smithy-protocol: rpc-v2-cbor, body 0xa0	200, CBOR menu	✅
5	rpcv2Cbor	CreateOrder	POST .../CreateOrder + cbor header, body {coffeeType:"LATTE"}	200, returns id	✅
6	rpcv2Json	GetMenu	POST .../GetMenu + smithy-protocol: rpc-v2-json, body {}	200, JSON menu	✅
7	rpcv2Json	CreateOrder	POST .../CreateOrder + json header, body {coffeeType:"ESPRESSO"}	200, returns id	✅
8	no-claim	—	POST /service/CoffeeShop/operation/GetMenu without smithy-protocol header	404, Quarkus default page (~358 bytes) — server called next()	✅
9	claim-and-reject	—	POST /service/CoffeeShop/operation/ with smithy-protocol: rpc-v2-cbor (malformed URI)	404, empty body — server intercepted before next()	✅
10	unrelated path	—	GET /q/notreal	404, Quarkus default page (~358 bytes) — fell through to Quarkus	✅

Follow-ups/Caveats

• Streaming-body design: the current implementation read the whole body, we need a streaming based implementation. We need to figure out how can we reuse the Netty server implementation.
• Native-image support.
• @streaming Blob operations.
• CORS support on the Vert.x server (server-netty has it).

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[chenliu0831]

Looks like there might be major flaw with the multi Vert.x routes mount approach which violate https://smithy.io/2.0/guides/wire-protocol-selection.html after chatting with Adwait. Doing another iteration...

This is done now

[chenliu0831]

Not too sure about how Quarkus resolve those jars from extension.