Add quarkus-smithy extension and Smithy Vert.x server

Smithy services run inside Quarkus applications via a new extension that
mounts every CDI-discovered Service bean on Quarkus's main HTTP router.
Smithy operations share the Quarkus HTTP server's port — no separate
Smithy listener.

## Customer-facing surface

Users produce a `@Produces Service` bean (the generated service stub):

    @ApplicationScoped
    public class CoffeeShopServerConfig {
        @produces @singleton
        Service coffeeShop() {
            return CoffeeShop.builder()
                    .addCreateOrderOperation(new CreateOrder())
                    .addGetMenuOperation(new GetMenu())
                    .addGetOrderOperation(new GetOrder())
                    .build();
        }
    }

The extension mounts a `SmithyVertxServer` on Quarkus's `Router` as a
single catch-all route. Per-request, a `ProtocolResolver` iterates a
precision-ordered list of `ServerProtocol`s and returns one of three
outcomes:

  - claim       -> dispatch to the operation
  - no-claim    -> ctx.next() (delegate to a sibling handler)
  - claim-and-reject -> 404 directly (request is Smithy's but malformed)

This implements the Smithy 2.0 Wire-protocol-selection guide.

End-to-end CoffeeShop example at `examples/quarkus-server/`. Standalone
Gradle build that consumes smithy-java via mavenLocal — required because
including it as a subproject causes Quarkus dev-mode workspace discovery
to substitute sibling raw `build/classes` for the published jars,
splitting classloaders in ways that break `:codecs:json-codec`'s
shadowJar.

## Modules

  - `:server:server-vertx` — `SmithyVertxServer implements
    Handler<RoutingContext>`, `ServerOptions`, `VertxRequestHeaders`.
    18 integration tests against a real Vert.x HTTP server.
  - `:quarkus-smithy` (runtime) — `SmithyVertxRecorder` and
    `SmithyServerConfig` (`@ConfigMapping` for
    `quarkus.smithy.server.{path-prefix, workers, shutdown-grace}`).
    The recorder collects `Service` beans from Arc, walks
    TCCL+own-loader for `ServerProtocolProvider`s (required because
    `ProtocolResolver`'s static SPI cache can't see runtime jars under
    `QuarkusClassLoader`), constructs the server, mounts it on the
    main router, and registers ordered shutdown tasks.
  - `:quarkus-smithy-deployment` (build-time) — `SmithyProcessor`
    `@BuildStep`s and `SmithyCodeGenProvider` that hooks Smithy
    code generation into `quarkusGenerateCode` (no `smithy-base`
    Gradle plugin needed).
  - `:quarkus-smithy-integration-tests` — `SmithyCodeGenProviderTest`.

## Cross-module changes

  - `:server:server-core`
      - `ProtocolResolver` gains `resolveOrEmpty(...)` returning
        `Optional<ServiceProtocolResolutionResult>` and a second ctor
        accepting a pre-loaded protocol list (for callers like the
        Quarkus recorder where the static SPI cache is blind).
      - `HttpResponseSerializer` is new: status + header-copy +
        content-type/length logic shared between Netty and the Vert.x
        server. Body exposed as the underlying `DataStream` so Netty
        preserves zero-copy via `Unpooled.wrappedBuffer(ByteBuffer)`.
      - `ServerProtocolProvider.precision()` Javadoc documents the AWS
        service-protocol scale (rpcv2Cbor=1 ... restXml=8).
  - `:server:server-netty` — `HttpRequestHandler.writeResponse` adopts
    `HttpResponseSerializer`. Behavior unchanged.
  - Provider precision values: `RpcV2CborProtocolProvider` -> 1,
    `RpcV2JsonProtocolProvider` -> 2, `AwsRestJson1ProtocolProvider`
    -> 7. Previously all 0 (precision sort was a no-op against
    classpath order).
  - `:aws:server:aws-server-restjson` — drops dead `routes` field and
    `smithyToVertxPath` helper (the Vert.x server no longer enumerates
    per-operation routes).

## Verification

  - `./gradlew :server:server-vertx:check` green. 19 integration tests
    against a real Vert.x HTTP server: protocol resolution outcomes,
    HTTP/2 round-trip, lifecycle, options, precision regression.
  - `./gradlew :server:server-core:check` green. New tests:
    `HttpResponseSerializerTest` (6) and `ProtocolResolverTest` (7).
  - `./gradlew :quarkus-smithy:build :quarkus-smithy-deployment:build`
    green (with `--no-configuration-cache` to work around a pre-existing
    Quarkus extension-validation gradle-plugin issue).
  - `examples/quarkus-server` end-to-end (`quarkusDev`):
    `GET /menu`, `PUT /order`, `GET /order/<id>` all 200 under
    restJson1; CoffeeShop also reachable via `POST
    /service/CoffeeShop/operation/<Op>` with `smithy-protocol:
    rpc-v2-cbor` and `smithy-protocol: rpc-v2-json` headers; rpcv2
    path with no header -> Quarkus default 404 via ctx.next(); rpcv2
    path with header but malformed URI -> server 404 with empty body
    (claim-and-reject). The empty-body 404 vs Quarkus's default-page
    404 confirms the resolution-outcome distinctions are observable.

## Known limitations (deferred)

  - `@streaming Blob` operations not supported. The recorder installs
    Vert.x's `BodyHandler` upstream of the server, fully buffering
    request bodies before resolution runs.
  - Native-image support is out of scope for this cut.
  - CORS support on the Vert.x server (Netty has it).
  - Cross-service `@http(uri)` collisions are silent at construction
    time — the matcher's tie-break wins.

Author: Peter Liu

aws/server/aws-server-restjson/src/main/java/software/amazon/smithy/java/aws/server/restjson/AwsRestJson1ProtocolProvider.java

@@ -25,6 +25,6 @@ public ShapeId getProtocolId() {
 
     @Override
     public int precision() {
-        return 0;
+        return 7;
     }
 }

examples/quarkus-server/README.md

@@ -0,0 +1,234 @@
+## Example: Quarkus Server
+
+A Smithy-Java service running inside a Quarkus application via the
+[`quarkus-smithy` extension](../../quarkus-smithy/README.md). Smithy
+operations share Quarkus's HTTP port — no separate Smithy listener.
+
+### Run it
+
+This example is a standalone Gradle build (see "Why a standalone
+Gradle build" below). Drive it from the smithy-java root with the
+repo's wrapper:
+
+```console
+# from smithy-java/ — publishes the smithy-java jars to your local repo
+./gradlew publishToMavenLocal
+
+# still from smithy-java/ — runs the example's standalone build
+./gradlew --project-dir examples/quarkus-server quarkusDev
+```
+
+The server listens on `http://localhost:8080`. Watch the boot log for
+the recorder's mount line (`Smithy mounted at /* with N service(s)`)
+and the server's own construction line (`Smithy server constructed
+with N service(s), M operation(s); protocols (precision order): […]`).
+
+Re-run `publishToMavenLocal` whenever you change smithy-java sources.
+
+### Curl the operations
+
+The CoffeeShop service declares `@restJson1 @rpcv2Cbor @rpcv2Json`, so
+each operation is reachable via any of three on-the-wire shapes. The
+server picks one per request in protocol-precision order
+(rpcv2Cbor → rpcv2Json → restJson1).
+
+#### restJson1 — HTTP routes via `@http(method, uri)`
+
+```console
+curl http://localhost:8080/menu
+curl -X PUT http://localhost:8080/order -H 'Content-Type: application/json' \
+     -d '{"coffeeType":"LATTE"}'
+curl http://localhost:8080/order/<id-from-PUT-response>
+```
+
+#### rpcv2Cbor — `/service/CoffeeShop/operation/<Op>` + `smithy-protocol` header
+
+```console
+# GetMenu — empty input is the CBOR empty map (0xa0)
+printf '\xa0' > /tmp/empty.cbor
+curl -X POST http://localhost:8080/service/CoffeeShop/operation/GetMenu \
+     -H 'smithy-protocol: rpc-v2-cbor' -H 'content-type: application/cbor' \
+     --data-binary @/tmp/empty.cbor
+
+# CreateOrder — {"coffeeType":"LATTE"}
+python3 -c 'import sys; sys.stdout.buffer.write(bytes([0xa1, 0x6a]) + b"coffeeType" + bytes([0x65]) + b"LATTE")' \
+     > /tmp/createorder.cbor
+curl -X POST http://localhost:8080/service/CoffeeShop/operation/CreateOrder \
+     -H 'smithy-protocol: rpc-v2-cbor' -H 'content-type: application/cbor' \
+     --data-binary @/tmp/createorder.cbor
+```
+
+The response body is CBOR; pipe through `xxd` or a CBOR diagnostic tool
+to read it.
+
+#### rpcv2Json — same URI scheme, JSON body
+
+```console
+curl -X POST http://localhost:8080/service/CoffeeShop/operation/GetMenu \
+     -H 'smithy-protocol: rpc-v2-json' -H 'content-type: application/json' -d '{}'
+
+curl -X POST http://localhost:8080/service/CoffeeShop/operation/CreateOrder \
+     -H 'smithy-protocol: rpc-v2-json' -H 'content-type: application/json' \
+     -d '{"coffeeType":"ESPRESSO"}'
+
+curl -X POST http://localhost:8080/service/CoffeeShop/operation/GetOrder \
+     -H 'smithy-protocol: rpc-v2-json' -H 'content-type: application/json' \
+     -d '{"id":"<id-from-CreateOrder>"}'
+```
+
+#### Fall-through behavior
+
+The server distinguishes three outcomes per request, observable as
+distinct 404 shapes:
+
+```console
+# no-claim → ctx.next() → Quarkus default 404 (text/plain ~358B page)
+curl -i -X POST http://localhost:8080/service/CoffeeShop/operation/GetMenu
+
+# claim-and-reject → server 404 with empty body
+curl -i -X POST http://localhost:8080/service/CoffeeShop/operation/ \
+     -H 'smithy-protocol: rpc-v2-cbor' -H 'content-type: application/cbor' \
+     --data-binary @/tmp/empty.cbor
+
+# unrelated path → ctx.next() → Quarkus (or your own sibling handler)
+curl -i http://localhost:8080/q/notreal
+```
+
+The empty-body 404 (claim-and-reject) vs the Quarkus default-page 404
+(no-claim) is the observable signal for routing correctness. A request
+that *claimed* the rpcv2-cbor protocol but failed URI parsing is
+intercepted before `ctx.next()`, so a sibling handler can't
+misinterpret it. A request that no protocol claimed falls through, so
+Quarkus (or any other Vert.x handler on the same router) gets a chance
+to serve it.
+
+### Hot reload
+
+While `quarkusDev` is running:
+
+- Edit `CreateOrder.java` (e.g., change a status string), save → re-curl
+  `PUT /order`. The response reflects the change without a restart.
+- Edit `src/main/smithy/coffee.smithy` (e.g., add a member), save → the
+  `CodeGenProvider` regenerates the stub and the recorder removes the
+  previous Vert.x route before installing the new one.
+
+### Path-prefix mode
+
+To put Smithy operations under `/api/smithy/...` (so REST endpoints can
+own the root), set in `src/main/resources/application.properties`:
+
+```properties
+quarkus.smithy.server.path-prefix=/api/smithy
+```
+
+`@http(uri:"/menu")` then becomes reachable at `/api/smithy/menu`. Verify:
+
+```console
+curl -i http://localhost:8080/api/smithy/menu   # 200
+curl -i http://localhost:8080/menu              # 404
+```
+
+In dev mode you can also live-edit this from the Dev UI Configuration
+tile — see below.
+
+### Packaged jar (prod profile)
+
+```console
+# from smithy-java/
+./gradlew --project-dir examples/quarkus-server quarkusBuild
+java -jar examples/quarkus-server/build/quarkus-app/quarkus-run.jar
+```
+
+Run the same curl probes against this — they should all 200, boot is
+sub-2s.
+
+### Dev UI
+
+While `quarkusDev` is running, open `http://localhost:8080/q/dev-ui`.
+
+There is no Smithy-specific Dev UI card today (none of the extension's
+build steps emit a `CardPageBuildItem`), so use the standard tiles:
+
+- **Endpoints** — confirms the Smithy server's catch-all route
+  alongside Quarkus's own routes.
+- **Configuration** — search for `quarkus.smithy.server` to live-edit
+  `path-prefix`, `workers`, and `shutdown-grace`.
+- **ArC** — confirms the `@Produces Service` bean is present and
+  unremovable (the extension marks it via `UnremovableBeanBuildItem`).
+- **Build Steps** — confirms `SmithyProcessor` ran and which build
+  items it produced.
+- **Continuous Testing** — press `r` in the dev terminal (or open the
+  tile) to re-run tests on save.
+
+---
+
+### How it's wired
+
+The user produces a `@Produces Service` bean (the generated `CoffeeShop`
+stub) and the extension mounts a `SmithyVertxServer` from the upstream
+`:server:server-vertx` module on Quarkus's main HTTP router:
+
+```java
+@ApplicationScoped
+public class CoffeeShopServerConfig {
+
+    @Produces
+    @Singleton
+    Service coffeeShop() {
+        return CoffeeShop.builder()
+                .addCreateOrderOperation(new CreateOrder())
+                .addGetMenuOperation(new GetMenu())
+                .addGetOrderOperation(new GetOrder())
+                .build();
+    }
+}
+```
+
+#### Project layout
+
+```
+.
+├── build.gradle.kts                  ← apply io.quarkus, depend on quarkus-smithy
+├── settings.gradle.kts
+├── gradle.properties
+├── smithy-build.json                 ← project root, configures java-codegen
+├── src/main/smithy/                  ← .smithy models (Quarkus convention)
+│   ├── coffee.smithy
+│   ├── main.smithy
+│   └── order.smithy
+├── src/main/java/.../CoffeeShopServerConfig.java
+├── src/main/java/.../CreateOrder.java
+├── src/main/java/.../GetMenu.java
+├── src/main/java/.../GetOrder.java
+└── src/main/resources/application.properties
+```
+
+No `afterEvaluate { ... srcDir(...) }` wiring. No
+`compileJava.dependsOn(smithyBuild)`. The `quarkus-smithy` extension's
+`CodeGenProvider` runs as part of `quarkusGenerateCode`, generates Java
+sources directly into Quarkus's
+`build/classes/java/quarkus-generated-sources/smithy/` output directory,
+and `compileJava` picks them up automatically.
+
+#### Why a standalone Gradle build
+
+This example is intentionally not included in `smithy-java`'s root
+`settings.gradle.kts`. Quarkus dev-mode workspace discovery would
+otherwise substitute sibling smithy-java projects' raw `build/classes`
+directories for their published jars — bypassing
+`:codecs:json-codec`'s shadowJar (which relocates Jackson 3) and
+splitting the classloader graph in ways that break the
+`SchemaExtensionProvider` SPI lookup. Running standalone, against the
+locally-published jars, makes the example behave exactly the way a
+real customer's project would.
+
+### Running the extension's tests
+
+These live in the parent smithy-java build, not in this example:
+
+```console
+# from smithy-java/
+./gradlew :server:server-vertx:test                 # Smithy Vert.x server tests
+./gradlew :quarkus-smithy-integration-tests:test    # extension integ
+./gradlew :aws:server:aws-server-restjson:integ     # protocol integ
+```

examples/quarkus-server/build.gradle.kts

@@ -0,0 +1,57 @@
+plugins {
+    `java-library`
+    id("io.quarkus") version "3.35.3"
+}
+
+// This example is a standalone Gradle build (it is *not* included in
+// smithy-java's root settings.gradle.kts). All smithy-java dependencies
+// are resolved from mavenLocal, the same way a real customer would
+// consume them. To rebuild after changing smithy-java sources, run
+// `gradle publishToMavenLocal` from the smithy-java root first.
+repositories {
+    mavenLocal()
+    mavenCentral()
+}
+
+val quarkusPlatformGroupId: String by project
+val quarkusPlatformArtifactId: String by project
+val quarkusPlatformVersion: String by project
+val smithyJavaVersion: String by project
+
+dependencies {
+    // The quarkus-smithy extension. Brings in:
+    //   - SmithyVertxRecorder (mounts services on Quarkus's HTTP router)
+    //   - the deployment-time CodeGenProvider that runs Smithy code generation
+    //     during quarkusGenerateCode (no smithy-base Gradle plugin needed)
+    //   - quarkus-vertx-http transitively (Smithy operations share the
+    //     Quarkus HTTP server's port, per ADR-0003)
+    //   - the upstream :server:server-vertx module
+    implementation("software.amazon.smithy.java:quarkus-smithy:$smithyJavaVersion")
+
+    // Quarkus runtime
+    implementation(enforcedPlatform("$quarkusPlatformGroupId:$quarkusPlatformArtifactId:$quarkusPlatformVersion"))
+    implementation("io.quarkus:quarkus-arc")
+
+    // Server-side protocol implementations. The bridge looks for
+    // ServerProtocol providers via ServiceLoader; the user adds
+    // whichever protocol jar(s) their .smithy services declare. The
+    // CoffeeShop service in this example declares all three:
+    // @restJson1 + @rpcv2Cbor + @rpcv2Json. Each request resolves to
+    // exactly one protocol per the precision-ordered list (rpcv2Cbor
+    // first, then rpcv2Json, then restJson1).
+    implementation("software.amazon.smithy.java:aws-server-restjson:$smithyJavaVersion")
+    implementation("software.amazon.smithy.java:server-rpcv2-cbor:$smithyJavaVersion")
+    implementation("software.amazon.smithy.java:server-rpcv2-json:$smithyJavaVersion")
+}
+
+java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(25)
+    }
+    sourceCompatibility = JavaVersion.VERSION_25
+    targetCompatibility = JavaVersion.VERSION_25
+}
+
+// .smithy files live under src/main/smithy/ — Quarkus's CodeGenProvider
+// finds them automatically and IntelliJ's Gradle import surfaces them
+// without extra source-set wiring.

examples/quarkus-server/gradle.properties

@@ -0,0 +1,8 @@
+# Pinned to whatever version is in mavenLocal. Before running `quarkusBuild`
+# or `quarkusDev` from this directory, publish the smithy-java artifacts:
+#   (from smithy-java/) gradle :quarkus-smithy:publishToMavenLocal :quarkus-smithy-deployment:publishToMavenLocal
+smithyJavaVersion=1.2.0
+quarkusPluginVersion=3.35.3
+quarkusPlatformGroupId=io.quarkus.platform
+quarkusPlatformArtifactId=quarkus-bom
+quarkusPlatformVersion=3.35.3

examples/quarkus-server/settings.gradle.kts

@@ -0,0 +1,22 @@
+/**
+ * Example showing the user-facing experience for a Smithy-Java server inside
+ * Quarkus, using the experimental `quarkus-smithy` extension. The extension
+ * owns codegen (no smithy-base needed) and the Server lifecycle (no manual
+ * StartupEvent observer needed).
+ */
+
+pluginManagement {
+    val quarkusPluginVersion: String by settings
+
+    plugins {
+        id("io.quarkus").version(quarkusPluginVersion)
+    }
+
+    repositories {
+        mavenLocal()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+
+rootProject.name = "Quarkus-Server"

examples/quarkus-server/smithy-build.json

@@ -0,0 +1,11 @@
+{
+  "version": "1.0",
+  "sources": ["src/main/smithy"],
+  "plugins": {
+    "java-codegen": {
+      "service": "com.example#CoffeeShop",
+      "namespace": "software.amazon.smithy.java.example.quarkus",
+      "modes": ["server"]
+    }
+  }
+}

examples/quarkus-server/src/main/java/software/amazon/smithy/java/example/quarkus/CoffeeShopServerConfig.java

@@ -0,0 +1,39 @@
+/*
+ * Example file license header.
+ * File header line two
+ */
+
+package software.amazon.smithy.java.example.quarkus;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.inject.Produces;
+import jakarta.inject.Singleton;
+import software.amazon.smithy.java.example.quarkus.service.CoffeeShop;
+import software.amazon.smithy.java.server.Service;
+
+/**
+ * The user-facing wiring for a Smithy-Java service inside Quarkus.
+ *
+ * <p>This producer returns a built {@link Service} (the generated
+ * {@code CoffeeShop} stub). The {@code quarkus-smithy} extension
+ * discovers every {@code @Produces Service} bean and mounts the
+ * operations on Quarkus's main HTTP router via the upstream Vert.x
+ * server — see the README for config options.
+ *
+ * <p>There is no user-supplied {@code URI} or port: the service shares
+ * Quarkus's HTTP server, so configure host/port via the standard
+ * {@code quarkus.http.host} / {@code quarkus.http.port} keys.
+ */
+@ApplicationScoped
+public class CoffeeShopServerConfig {
+
+    @Produces
+    @Singleton
+    Service coffeeShop() {
+        return CoffeeShop.builder()
+                .addCreateOrderOperation(new CreateOrder())
+                .addGetMenuOperation(new GetMenu())
+                .addGetOrderOperation(new GetOrder())
+                .build();
+    }
+}