bmad-method-quarkus 1.0.2 → 1.0.3

package/src/bmm-skills/agents/bmad-quarkus-dev/skills/quarkus-grpc-services/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: quarkus-grpc-services
-description: Standard for internal microservice-to-microservice communication using gRPC in Quarkus native services — proto conventions, Mutiny services, clients, deadlines, error mapping to domain exceptions, health checks, and native-image setup. Use this skill whenever the user mentions gRPC, protobuf, .proto files, internal service calls, synchronous inter-service communication, service clients, or "call service X from service Y" — internal synchronous calls are ALWAYS gRPC, never internal REST. Includes proto and gRPC adapter/client/mapper naming conventions.
+description: Standard for internal microservice-to-microservice communication using gRPC in Quarkus native services — proto conventions, Mutiny services, clients, deadlines, error mapping to BusinessException codes, health checks, and native-image setup. Use this skill whenever the user mentions gRPC, protobuf, .proto files, internal service calls, synchronous inter-service communication, service clients, or "call service X from service Y" — internal synchronous calls are ALWAYS gRPC, never internal REST. Includes proto and gRPC adapter/client naming conventions for the vertical-slice layout (the GrpcService lives in the slice folder and delegates to the slice Handler; outbound stubs are wrapped by capability-named beans in common/client).
 ---
 
 # gRPC Standard for Inter-Service Communication (Quarkus)
@@ -11,12 +11,12 @@ Extension: `quarkus-grpc` (fully native-compatible; code generation is build-tim
 
 ## Proto conventions
 
-Location: `src/main/proto/`. One package per service/module + major version (the module segment is the BC code in DDD projects, the service name otherwise):
+Location: `src/main/proto/<module>/v<major>/`, one file per capability group, published to the monorepo `contracts/` folder. One proto package per service/module + major version (the module segment is the module's semantic name — `iam`, `customer` — see quarkus-hexagonal-core skill, or the service name):
 
 ```protobuf
 syntax = "proto3";
-package alva.bc05.v1;
-option java_package = "com.alva.bc05.grpc.v1";
+package alva.iam.v1;
+option java_package = "com.alva.iam.grpc.v1";
 option java_multiple_files = true;
 
 service UserService {
@@ -36,27 +36,32 @@ Rules:
 - Proto files are contracts: keep them in a shared `contracts/` module (or a dedicated repo) consumed by both sides; do NOT copy-paste protos between services.
 - Streaming RPCs only with a justified use case (bulk export, watch); default is unary.
 
-## Server (inbound adapter, `infrastructure/grpc`)
+## Server (inbound adapter, in the slice folder)
 
 ```java
 @GrpcService
 public class UserGrpcService implements UserService {   // Mutiny-generated interface
 
-    private final GetUserUseCase getUser;   // inbound port from application layer
-
-    public UserGrpcService(GetUserUseCase getUser) { this.getUser = getUser; }
+    @Inject FindUserHandler findUser;      // the slice's Handler, blocking
 
     @Override
     public Uni<GetUserResponse> getUser(GetUserRequest req) {
-        return Uni.createFrom().item(() -> getUser.byId(new UserId(UUID.fromString(req.getUserId()))))
-            .runSubscriptionOn(Infrastructure.getDefaultWorkerPool())  // JDBC below → worker thread
-            .map(UserGrpcMapper::toResponse);
+        return Uni.createFrom().item(() -> {
+                var request = FindUserRequestDto.builder().userId(req.getUserId()).build();
+                var result = findUser.process(request);           // blocking JDBC
+                return GetUserResponse.newBuilder()
+                    .setUser(User.newBuilder().setId(result.getId()).setEmail(result.getEmail()))
+                    .build();
+            })
+            .runSubscriptionOn(Infrastructure.getDefaultWorkerPool());  // JDBC → worker thread
     }
 }
 ```
 
-- gRPC service = thin adapter: map proto ↔ command/result, delegate to the use case. No business logic.
-- Blocking work (JDBC) either `@Blocking` on the method or explicit worker pool as above.
+- gRPC service = thin adapter: convert proto ↔ DTO, delegate to the slice `Handler`. No business logic, no JDBC, no `Connection`.
+- **Proto ↔ DTO conversion happens inline, inside the `item(() -> ...)` lambda.** There is no `*GrpcMapper` class — `*Mapper` is a banned suffix (see quarkus-hexagonal-core skill).
+- This class and the integration beans in `common/client` are the **only** two places Mutiny is allowed; the ArchUnit rule `reactiveIsQuarantined` enforces it. Never let `Uni`/`Multi` reach a `Handler` or `Sql`.
+- Blocking work (JDBC) either `@Blocking` on the method or the explicit worker pool as above.
 
 ### Naming
 
@@ -68,60 +73,73 @@ Canonical rules in the quarkus-hexagonal-core skill; gRPC specifics:
 | Proto RPC | `<Verb><Entity>` | `GetUser`, `ValidateCredentials` |
 | Proto messages | `<Rpc>Request` / `<Rpc>Response`, one pair per RPC | `GetUserRequest` |
 | Proto fields | `snake_case` | `user_id` |
-| Server adapter | `<ProtoService>GrpcService` | `UserGrpcService` |
-| Client adapter | `Grpc<Port>` — port name from `application/port/out` | `GrpcCredentialsValidator` |
-| Proto ↔ domain mapper | `<Entity>GrpcMapper` | `UserGrpcMapper` |
-| Global error interceptor | `GrpcExceptionInterceptor` | |
-| Client config key | `<module>-<entity>` kebab-case, matching `@GrpcClient` | `bc05-users` |
+| Server adapter | `<ProtoService>GrpcService`, in the slice folder | `UserGrpcService` |
+| Outbound integration bean | capability noun, **no technology**, in `common/client` | `CredentialsValidator` |
+| Global error interceptor | `GrpcExceptionInterceptor`, in `common/error` | |
+| Client config key | `<module>-<entity>` kebab-case, matching `@GrpcClient` | `iam-users` |
+
+`*GrpcService` is the **only** class allowed to end in `Service` under the slice standard — it mirrors the proto service name, which is not ours to rename (ArchUnit rule `serviceSuffixIsReserved`). There is no `Grpc<Port>` client adapter and no `*GrpcMapper`: the outbound bean is named after the capability it provides, and only its internals reveal that gRPC is the transport.
 
-`*GrpcService` is the one place outside `application/usecase` where the `*Service` suffix is allowed — it mirrors the proto service name, which is not ours to rename. The client adapter is never called `UserServiceClient`: it implements a domain-named port, and only the `Grpc` prefix reveals the transport.
-- Separate gRPC server port (default `9000`) or unified with HTTP via `quarkus.grpc.server.use-separate-server=false` — pick one per platform and keep it consistent.
+Separate gRPC server port (default `9000`) or unified with HTTP via `quarkus.grpc.server.use-separate-server=false` — pick one per platform and keep it consistent.
 
-## Error mapping (domain exception → gRPC status)
+## Error mapping (`BusinessException` → gRPC status)
 
-One `ExceptionHandlerProvider`-style mapping, symmetric to the REST unified handler:
+One `ExceptionHandlerProvider`-style mapping, symmetric to the REST unified handler. The status is derived from the code's entry in `ErrorCatalog`, not from the exception class:
 
-| Domain situation | gRPC status |
+| Situation (per `ErrorCatalog`) | gRPC status |
 |---|---|
 | Not found | `NOT_FOUND` |
 | Validation / bad argument | `INVALID_ARGUMENT` |
 | Business rule conflict | `FAILED_PRECONDITION` |
-| Duplicate / concurrency | `ALREADY_EXISTS` / `ABORTED` |
+| Duplicate | `ALREADY_EXISTS` |
+| Stale version / concurrency (`StaleVersionException`) | `ABORTED` |
 | Auth | `UNAUTHENTICATED` / `PERMISSION_DENIED` |
 | Anything unexpected | `INTERNAL` (no details leaked) |
 
-Attach the stable error code in trailers metadata key `error-code` so callers can map back to their own domain exceptions. Implement once as a global gRPC exception interceptor (`GrpcExceptionInterceptor`, the counterpart of `GlobalExceptionHandler` — see quarkus-error-handling-i18n skill); individual services never build `StatusRuntimeException` by hand.
+Attach the stable error code in trailers metadata key `error-code` so callers can map it back through their own `ErrorCatalog`. Implement once as a global gRPC exception interceptor (`GrpcExceptionInterceptor` in `common/error`, the counterpart of `GlobalExceptionHandler` — see quarkus-error-handling-i18n skill); it resolves the localized message the same way, from the request's locale metadata. Individual services never build `StatusRuntimeException` by hand, and no `GrpcService` catches `BusinessException`.
 
-## Client (outbound adapter)
+## Client (outbound integration bean, `common/client`)
 
-Define an outbound port in `application/port/out` (e.g., `CredentialsValidator`); the gRPC client is its adapter:
+A slice `Handler` must never hold a `@GrpcClient` stub: the generated stub returns `Uni`, which would drag Mutiny into the business logic and break the `reactiveIsQuarantined` rule. Wrap it in a capability-named bean that `await()`s internally and exposes plain types:
 
 ```java
+// common/client — named for what it provides, not for how
 @ApplicationScoped
-public class GrpcCredentialsValidator implements CredentialsValidator {
+public class CredentialsValidator {
 
-    @GrpcClient("bc05-users") UserService client;   // Mutiny stub
+    @GrpcClient("iam-users") UserService client;   // Mutiny stub, contained here
 
-    @Override
-    public boolean validate(Credentials c) {
-        return client.validateCredentials(toRequest(c))
+    public boolean validate(String username, String password) {
+        return client.validateCredentials(
+                ValidateCredentialsRequest.newBuilder()
+                    .setUsername(username).setPassword(password).build())
             .map(ValidateCredentialsResponse::getValid)
-            .await().atMost(Duration.ofSeconds(2));
+            .await().atMost(Duration.ofSeconds(2));   // deadline also set in config
     }
 }
 ```
 
+The `Handler` then injects it like any other collaborator:
+
+```java
+@Inject CredentialsValidator credentials;   // returns boolean, knows nothing about gRPC
+```
+
+The bean always lives in `common/client`, even when only one slice calls it today — that is the package the `reactiveIsQuarantined` ArchUnit rule exempts (see quarkus-hexagonal-core skill), and it saves relocating the bean the day a second slice needs it. It is mocked in `HandlerTest` exactly like the `Sql` class.
+
+An interface is warranted only under the core skill's "when to add an interface back" rule — a second real implementation, a cross-module boundary, or a `common/` consumer that must not see the slice.
+
 ```properties
-quarkus.grpc.clients.bc05-users.host=bc05-users.internal
-quarkus.grpc.clients.bc05-users.port=9000
-quarkus.grpc.clients.bc05-users.deadline=2s
+quarkus.grpc.clients.iam-users.host=iam-users.internal
+quarkus.grpc.clients.iam-users.port=9000
+quarkus.grpc.clients.iam-users.deadline=2s
 ```
 
 Rules:
 - **Deadline on every client** (config `deadline` or per-call). No unbounded internal calls, ever — cascading hangs kill native pods just as well.
 - Retries only for idempotent RPCs and only `UNAVAILABLE`/`DEADLINE_EXCEEDED`, with budget — prefer platform/mesh retry policy over hand-rolled loops.
 - TLS/mTLS per platform standard (`quarkus.grpc.clients.*.ssl.*` / mesh-provided).
-- Translate `StatusRuntimeException` back into the caller's domain exceptions at the adapter — gRPC types never cross into application/domain.
+- Translate `StatusRuntimeException` into a `BusinessException` carrying the caller's own error code, inside the integration bean — gRPC types (and `Uni`) never reach a `Handler`. Read the upstream code from the `error-code` trailer and map it through the caller's `ErrorCatalog`.
 
 ## Health & reflection
 
@@ -134,8 +152,9 @@ Tracing is automatic when `quarkus-opentelemetry` is present — `traceparent` p
 
 ## Checklist for a new RPC
 
-1. Proto in shared contracts module, package `vN`, dedicated Request/Response.
-2. Server adapter delegating to a use case; blocking handled explicitly.
-3. Client behind an outbound port, deadline configured.
-4. Error mapping covered by the global interceptor (add new code if needed).
+1. Proto in `src/main/proto/<module>/v<major>/`, published to `contracts/`, dedicated Request/Response pair.
+2. `<ProtoService>GrpcService` in the slice folder delegating to the slice `Handler`; proto ↔ DTO conversion inline; blocking handled by `runSubscriptionOn` or `@Blocking`.
+3. Outbound calls wrapped in a capability-named bean in `common/client` that `await()`s and returns plain types; deadline configured.
+4. Error mapping covered by the global interceptor (register any new code in `ErrorCatalog` + all locale bundles).
 5. Contract check in CI (buf breaking-change detection or equivalent).
+6. No `Uni` outside the `GrpcService` and the integration bean — `reactiveIsQuarantined` proves it.