javi-forge 1.2.0 → 1.3.0

package/ai-config/skills/backend/grpc-spring/SKILL.md

@@ -1,445 +0,0 @@
----
-name: grpc-spring
-description: >
-  Spring Boot gRPC. grpc-spring-boot-starter, service implementation, interceptors.
-  Trigger: apigen-grpc, @GrpcService, GrpcServerInterceptor, Protobuf, gRPC Java
-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Grep
-metadata:
-  author: apigen-team
-  version: "1.0"
-  tags: [grpc, spring-boot, protobuf, java]
-  scope: ["apigen-grpc/**"]
----
-
-# gRPC Spring Boot (apigen-grpc)
-
-## Configuration
-
-```yaml
-grpc:
-  server:
-    port: 9090
-    in-process-name: apigen-grpc
-    reflection-service-enabled: true
-    max-inbound-message-size: 10MB
-
-apigen:
-  grpc:
-    enabled: true
-    interceptors:
-      logging: true
-      metrics: true
-      authentication: true
-```
-
-## Gradle Configuration
-
-```groovy
-plugins {
-    id 'com.google.protobuf' version '0.9.4'
-}
-
-dependencies {
-    implementation 'io.grpc:grpc-netty-shaded:1.72.0'
-    implementation 'io.grpc:grpc-protobuf:1.72.0'
-    implementation 'io.grpc:grpc-stub:1.72.0'
-    implementation 'net.devh:grpc-spring-boot-starter:3.4.0'
-
-    // For well-known types
-    implementation 'com.google.protobuf:protobuf-java-util:4.29.3'
-}
-
-protobuf {
-    protoc {
-        artifact = 'com.google.protobuf:protoc:4.29.3'
-    }
-    plugins {
-        grpc {
-            artifact = 'io.grpc:protoc-gen-grpc-java:1.72.0'
-        }
-    }
-    generateProtoTasks {
-        all()*.plugins {
-            grpc {}
-        }
-    }
-}
-```
-
-## Proto Definition
-
-```protobuf
-// src/main/proto/user_service.proto
-syntax = "proto3";
-
-package com.jnzader.apigen.grpc;
-
-option java_package = "com.jnzader.apigen.grpc.proto";
-option java_multiple_files = true;
-
-import "google/protobuf/timestamp.proto";
-import "google/protobuf/empty.proto";
-import "google/protobuf/wrappers.proto";
-
-service UserService {
-  rpc GetUser(GetUserRequest) returns (UserResponse);
-  rpc CreateUser(CreateUserRequest) returns (UserResponse);
-  rpc UpdateUser(UpdateUserRequest) returns (UserResponse);
-  rpc DeleteUser(DeleteUserRequest) returns (google.protobuf.Empty);
-  rpc ListUsers(ListUsersRequest) returns (stream UserResponse);
-  rpc BatchCreateUsers(stream CreateUserRequest) returns (BatchCreateResponse);
-}
-
-message GetUserRequest {
-  string user_id = 1;
-}
-
-message CreateUserRequest {
-  string email = 1;
-  string name = 2;
-  string password = 3;
-}
-
-message UpdateUserRequest {
-  string user_id = 1;
-  google.protobuf.StringValue name = 2;
-  google.protobuf.StringValue email = 3;
-}
-
-message DeleteUserRequest {
-  string user_id = 1;
-}
-
-message ListUsersRequest {
-  int32 page_size = 1;
-  string page_token = 2;
-}
-
-message UserResponse {
-  string id = 1;
-  string email = 2;
-  string name = 3;
-  UserStatus status = 4;
-  google.protobuf.Timestamp created_at = 5;
-}
-
-message BatchCreateResponse {
-  int32 created_count = 1;
-  repeated string created_ids = 2;
-  repeated CreateError errors = 3;
-}
-
-message CreateError {
-  int32 index = 1;
-  string message = 2;
-}
-
-enum UserStatus {
-  USER_STATUS_UNSPECIFIED = 0;
-  USER_STATUS_ACTIVE = 1;
-  USER_STATUS_INACTIVE = 2;
-}
-```
-
-## Service Implementation
-
-```java
-@GrpcService
-@RequiredArgsConstructor
-public class UserGrpcService extends UserServiceGrpc.UserServiceImplBase {
-
-    private final UserService userService;
-    private final UserMapper userMapper;
-
-    @Override
-    public void getUser(GetUserRequest request,
-                        StreamObserver<UserResponse> responseObserver) {
-        try {
-            UUID userId = UUID.fromString(request.getUserId());
-            User user = userService.findById(userId)
-                .orElseThrow(() -> new StatusRuntimeException(
-                    Status.NOT_FOUND.withDescription("User not found")));
-
-            responseObserver.onNext(userMapper.toProto(user));
-            responseObserver.onCompleted();
-        } catch (IllegalArgumentException e) {
-            responseObserver.onError(Status.INVALID_ARGUMENT
-                .withDescription("Invalid user ID format")
-                .asRuntimeException());
-        }
-    }
-
-    @Override
-    public void createUser(CreateUserRequest request,
-                           StreamObserver<UserResponse> responseObserver) {
-        try {
-            CreateUserDTO dto = new CreateUserDTO(
-                request.getEmail(),
-                request.getName(),
-                request.getPassword()
-            );
-
-            User user = userService.create(dto);
-            responseObserver.onNext(userMapper.toProto(user));
-            responseObserver.onCompleted();
-        } catch (DuplicateEmailException e) {
-            responseObserver.onError(Status.ALREADY_EXISTS
-                .withDescription("Email already registered")
-                .asRuntimeException());
-        } catch (ValidationException e) {
-            responseObserver.onError(Status.INVALID_ARGUMENT
-                .withDescription(e.getMessage())
-                .asRuntimeException());
-        }
-    }
-
-    @Override
-    public void listUsers(ListUsersRequest request,
-                          StreamObserver<UserResponse> responseObserver) {
-        int pageSize = request.getPageSize() > 0 ? request.getPageSize() : 20;
-        String pageToken = request.getPageToken();
-
-        userService.streamAll(pageSize, pageToken)
-            .map(userMapper::toProto)
-            .forEach(responseObserver::onNext);
-
-        responseObserver.onCompleted();
-    }
-
-    @Override
-    public StreamObserver<CreateUserRequest> batchCreateUsers(
-            StreamObserver<BatchCreateResponse> responseObserver) {
-
-        List<String> createdIds = new ArrayList<>();
-        List<CreateError> errors = new ArrayList<>();
-        AtomicInteger index = new AtomicInteger(0);
-
-        return new StreamObserver<>() {
-            @Override
-            public void onNext(CreateUserRequest request) {
-                int currentIndex = index.getAndIncrement();
-                try {
-                    CreateUserDTO dto = new CreateUserDTO(
-                        request.getEmail(), request.getName(), request.getPassword());
-                    User user = userService.create(dto);
-                    createdIds.add(user.getId().toString());
-                } catch (Exception e) {
-                    errors.add(CreateError.newBuilder()
-                        .setIndex(currentIndex)
-                        .setMessage(e.getMessage())
-                        .build());
-                }
-            }
-
-            @Override
-            public void onError(Throwable t) {
-                responseObserver.onError(t);
-            }
-
-            @Override
-            public void onCompleted() {
-                responseObserver.onNext(BatchCreateResponse.newBuilder()
-                    .setCreatedCount(createdIds.size())
-                    .addAllCreatedIds(createdIds)
-                    .addAllErrors(errors)
-                    .build());
-                responseObserver.onCompleted();
-            }
-        };
-    }
-}
-```
-
-## Mapper
-
-```java
-@Mapper(componentModel = "spring")
-public interface UserMapper {
-
-    @Mapping(target = "id", source = "id", qualifiedByName = "uuidToString")
-    @Mapping(target = "createdAt", source = "createdAt", qualifiedByName = "instantToTimestamp")
-    @Mapping(target = "status", source = "status", qualifiedByName = "statusToProto")
-    UserResponse toProto(User user);
-
-    @Named("uuidToString")
-    default String uuidToString(UUID uuid) {
-        return uuid != null ? uuid.toString() : "";
-    }
-
-    @Named("instantToTimestamp")
-    default Timestamp instantToTimestamp(Instant instant) {
-        if (instant == null) return Timestamp.getDefaultInstance();
-        return Timestamp.newBuilder()
-            .setSeconds(instant.getEpochSecond())
-            .setNanos(instant.getNano())
-            .build();
-    }
-
-    @Named("statusToProto")
-    default UserStatus statusToProto(com.jnzader.apigen.domain.UserStatus status) {
-        return switch (status) {
-            case ACTIVE -> UserStatus.USER_STATUS_ACTIVE;
-            case INACTIVE -> UserStatus.USER_STATUS_INACTIVE;
-            default -> UserStatus.USER_STATUS_UNSPECIFIED;
-        };
-    }
-}
-```
-
-## Interceptors
-
-### Authentication Interceptor
-
-```java
-@GrpcGlobalServerInterceptor
-@RequiredArgsConstructor
-public class AuthenticationInterceptor implements ServerInterceptor {
-
-    private final JwtService jwtService;
-    public static final Context.Key<String> USER_ID_KEY = Context.key("userId");
-
-    @Override
-    public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(
-            ServerCall<ReqT, RespT> call,
-            Metadata headers,
-            ServerCallHandler<ReqT, RespT> next) {
-
-        String token = headers.get(Metadata.Key.of("authorization", ASCII_STRING_MARSHALLER));
-
-        if (token == null || !token.startsWith("Bearer ")) {
-            call.close(Status.UNAUTHENTICATED.withDescription("Missing token"), new Metadata());
-            return new ServerCall.Listener<>() {};
-        }
-
-        try {
-            String userId = jwtService.validateAndGetUserId(token.substring(7));
-            Context context = Context.current().withValue(USER_ID_KEY, userId);
-            return Contexts.interceptCall(context, call, headers, next);
-        } catch (Exception e) {
-            call.close(Status.UNAUTHENTICATED.withDescription("Invalid token"), new Metadata());
-            return new ServerCall.Listener<>() {};
-        }
-    }
-}
-```
-
-### Logging Interceptor
-
-```java
-@GrpcGlobalServerInterceptor
-@Slf4j
-public class LoggingInterceptor implements ServerInterceptor {
-
-    @Override
-    public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(
-            ServerCall<ReqT, RespT> call,
-            Metadata headers,
-            ServerCallHandler<ReqT, RespT> next) {
-
-        String methodName = call.getMethodDescriptor().getFullMethodName();
-        long startTime = System.currentTimeMillis();
-
-        log.info("gRPC request: {}", methodName);
-
-        return new ForwardingServerCallListener.SimpleForwardingServerCallListener<>(
-                next.startCall(call, headers)) {
-
-            @Override
-            public void onComplete() {
-                long duration = System.currentTimeMillis() - startTime;
-                log.info("gRPC response: {} completed in {}ms", methodName, duration);
-                super.onComplete();
-            }
-        };
-    }
-}
-```
-
-## gRPC Client
-
-```java
-@Service
-public class UserGrpcClient {
-
-    private final UserServiceGrpc.UserServiceBlockingStub blockingStub;
-    private final UserServiceGrpc.UserServiceStub asyncStub;
-
-    public UserGrpcClient(@GrpcClient("user-service") ManagedChannel channel) {
-        this.blockingStub = UserServiceGrpc.newBlockingStub(channel);
-        this.asyncStub = UserServiceGrpc.newStub(channel);
-    }
-
-    public UserResponse getUser(String userId) {
-        return blockingStub.getUser(GetUserRequest.newBuilder()
-            .setUserId(userId)
-            .build());
-    }
-
-    public void listUsersAsync(Consumer<UserResponse> consumer) {
-        asyncStub.listUsers(
-            ListUsersRequest.newBuilder().setPageSize(100).build(),
-            new StreamObserver<>() {
-                @Override
-                public void onNext(UserResponse value) {
-                    consumer.accept(value);
-                }
-
-                @Override
-                public void onError(Throwable t) {
-                    log.error("Error streaming users", t);
-                }
-
-                @Override
-                public void onCompleted() {
-                    log.info("User stream completed");
-                }
-            }
-        );
-    }
-}
-```
-
-## Testing
-
-```java
-@SpringBootTest
-@DirtiesContext
-class UserGrpcServiceTest {
-
-    @Autowired
-    private UserGrpcService userGrpcService;
-
-    @MockBean
-    private UserService userService;
-
-    @Test
-    void shouldGetUser() {
-        User user = new User(UUID.randomUUID(), "test@example.com", "Test");
-        when(userService.findById(user.getId())).thenReturn(Optional.of(user));
-
-        StreamRecorder<UserResponse> responseObserver = StreamRecorder.create();
-        userGrpcService.getUser(
-            GetUserRequest.newBuilder().setUserId(user.getId().toString()).build(),
-            responseObserver
-        );
-
-        assertThat(responseObserver.getError()).isNull();
-        assertThat(responseObserver.getValues()).hasSize(1);
-        assertThat(responseObserver.getValues().get(0).getEmail())
-            .isEqualTo("test@example.com");
-    }
-}
-```
-
-## Related Skills
-
-- `grpc-concepts`: gRPC concepts
-- `spring-boot-4`: Spring Boot 4.0 patterns
-- `apigen-architecture`: Overall system architecture
-
-