[Studio] feat: Feature/rip 2 pr1 proto serialization

[zhaohai666]

RIP-2 Proxy Admin Interface — PR#1 Foundation: gRPC Proto, Domain Models & Serialization

Background

This PR delivers the foundational protocol definition, domain-model layer, and serialization infrastructure for the Proxy Admin gRPC service under RIP-2 (Proxy Admin Interface). It is the first atomic PR of a six-PR sequence that fully implements the Proxy Admin capability suite.

Scope note: this PR establishes the contract and data structures only. The gRPC service handlers, the auth/authorization interceptor, and the domain↔proto converter (ProxyAdminProtoConverter) are delivered in subsequent PRs (PR2 / PR3 / PR4).

Design Overview

1. gRPC Protocol Definition (proxy_admin.proto)

A new gRPC service ProxyClientAdminService (not ProxyAdminService) is defined, exposing 10 RPC endpoints:

• Client inspection (read-only): ListClients, DescribeClient, ListClientsByGroup, ListClientsByTopic
• Consumer / receipt diagnostics (read-only): DescribePopReceiptHandles, DescribeBatchConsumeDiagnostics
• Config management (read + write): GetConfig, UpdateConfig ⚠️ mutating
• Client control (mutating): DisconnectClient ⚠️ mutating — force-disconnects a client
• Streaming: SubscribeRouteEvents — server-streaming, pushes incremental route change events

UpdateConfig and DisconnectClient are write/mutating operations. Their authorization lands in PR3 — until then the service must not be exposed on a reachable production port (see Follow-ups).

2. Domain Model Layer

Internal models decouple handlers from raw protobuf and isolate schema changes:

• proxy/common/: ProxyContext, ContextVariable, PopReceiptHandleInfo, PopReceiptHandleGroupSummary, BatchConsumeClientDiagnostics, BatchConsumeGroupSummary
• proxy/grpc/admin/model/: ClientDetailInfo, ClientInstanceInfo, ListClientsFilter, RouteChangeEvent, RouteChangeEventType, TopicRouteSnapshot

3. Serialization & Error Code

• ProxyAdminMarshaller — custom gRPC Marshaller handling nullable fields and unrecognized/unknown enum values.
• AdminCode — global standardized error-code enum unifying error responses across Proxy Admin APIs.

(The bidirectional converter ProxyAdminProtoConverter is intentionally not in this PR; it lands in PR4 with the service handlers.)

4. Configuration Scaffolding (ProxyConfig)

8 new proxyAdmin* fields — proxyAdminEnabled (default true), proxyAdminServerPort (8082), proxyAdminThreadPoolNums (4), proxyAdminMaxPageSize (100), proxyAdminDescribeClientConcurrencyLimit (8), proxyAdminSamplingRateUnderLoad (0.5), proxyAdminHeartbeatHistorySize (10), proxyAdminSamplingThreshold (100000).

5. Build & Code Style

• proxy/pom.xml — add protobuf-maven-plugin + os-maven-plugin + maven-checkstyle-plugin config (no new <dependency>).
• proxy/BUILD.bazel — add java_proto_library target for the admin proto.
• WORKSPACE — add rules_proto external repository (+16 lines).
• style/rmq_checkstyle.xml + style/rmq_checkstyle_suppressions.xml — extend checkstyle rules.

Modified & New File Scope

Protocol / serialization / models (new)

File	Type	Desc
proxy/src/main/proto/proxy_admin.proto	Proto	ProxyClientAdminService + 10 RPCs, 605 lines
proxy/.../grpc/admin/ProxyAdminMarshaller.java	Java	Custom marshaller
proxy/.../grpc/admin/AdminCode.java	Java	Error-code enum
proxy/.../grpc/admin/model/*.java (6 files)	Java	Domain models
proxy/.../common/*.java (6 files)	Java	Context + diagnostics models

Config / build / style

File	Type	Desc
proxy/.../config/ProxyConfig.java	Java	+8 proxyAdmin* fields
proxy/.../grpc/v2/client/ClientActivity.java	Java	Minor refactor (+13)
proxy/pom.xml, proxy/BUILD.bazel, WORKSPACE	Build	proto/grpc toolchain
style/rmq_checkstyle.xml, style/rmq_checkstyle_suppressions.xml	Style	checkstyle

Tests (16 new/modified) — ProxyAdminMarshallerTest (288 lines, round-trip + nullable + unknown-enum), AdminCodeTest, all 6 admin/model/*Test, 5 proxy/common/*Test, ProxyConfigTest, ClientActivityTest.

Unrelated (recommend splitting out) — common/.../ServiceThreadTest.java, remoting/.../TlsTest.java (flaky-test fixes, not Proxy Admin).

Total: 38 files (+3,399 / −19), of which 36 are PR1 content and 2 are unrelated.

Dependencies

No new Maven <dependency>. Adds rules_proto (Bazel) and protobuf/grpc build plugins that generate stubs at compile time.

Test Coverage & Validation

Marshaller round-trip + nullable/unknown-enum edge cases; AdminCode mapping; full coverage for all domain models; ProxyConfig defaults; adjusted ClientActivityTest.

Follow-ups / Reviewer Notes (must address)

1. Service name & RPC count — it is ProxyClientAdminService with 10 RPCs, not ProxyAdminService with 6. The write operations (UpdateConfig, DisconnectClient) were omitted from the original draft and are called out here.
2. proxyAdminEnabled defaults to true — risky with no auth yet (PR3). Recommend defaulting to false.
3. gRPC stub generation — BUILD.bazel has only java_proto_library (no java_grpc_library), and protobuf-maven-plugin is not configured with the compile-custom goal + protoc-gen-grpc-java. ProxyClientAdminServiceGrpc will not be generated for PR2 — verify/fix.
4. AdminCode proto/Java drift — AdminCode.java goes to code 8; proto's AdminCode enum tops out at 7 (ADMIN_CODE_TOO_MANY_REQUESTS). Align before PR4 converter.
5. Checkstyle suppression file is dead — rmq_checkstyle_suppressions.xml is referenced by no pom (suppressionsLocation missing). Wire it up or drop it.
6. Unrelated commits — split ServiceThreadTest / TlsTest into their own PR.

Development Branch

feature/rip-2-pr1-proto-serialization

Related Tracking

RIP-2: Proxy Admin Interface — Step 1 / 6.

[RockteMQ-AI]

Review by github-manager-bot

Summary

This PR establishes the foundational proto schema and serialization layer for the RIP-2 Proxy Admin gRPC service (PR#1 of a 6-PR sequence). It introduces proxy_admin.proto (606 lines, 10 RPCs), ProxyAdminMarshaller, ProxyAdminProtoConverter, and AdminCode — along with Maven/Bazel build integration and comprehensive unit tests.

Overall the design is clean and well-structured. Below are observations for the author's consideration.

Findings

• [Warning] proxy_admin.proto — Missing newline at end of file. The diff shows \ No newline at end of file. Most editors and CI lint checks expect a trailing newline.

• [Warning] proxy_admin.proto (UpdateConfigRequest) — The comment acknowledges proto3 default-value semantics prevent toggling booleans OFF (true→false). Consider using google.protobuf.BoolValue (wrapper type) for boolean config fields, or google.protobuf.FieldMask to explicitly specify which fields to update. This avoids a surprising limitation for API consumers.

• [Warning] proxy_admin.proto (ProxyRuntimeConfig) — Field numbers go up to 102 with intentional gaps (1-12, 20-29, 30-39, 40-49, 50-53, 60-70, 80-82, 90-92, 100-102). If the gaps are reserved for future use, consider adding // Reserved for future: 13-19, 54-59, ... comments to make the intent explicit and prevent accidental reuse.

• [Warning] proxy_admin.proto (SubscribeRouteEvents) — Server-streaming RPC with no documented keepalive, deadline, or reconnection strategy. If the proxy stops sending events, the stream could hang indefinitely. Consider documenting expected keepalive behavior or adding a heartbeat_interval_seconds field to SubscribeRouteEventsRequest.

• [Info] ProxyAdminProtoConverter.java — At 1016 lines, this class is quite large. Consider splitting into focused converters (e.g., ClientProtoConverter, RouteProtoConverter, ReceiptHandleProtoConverter, ConfigProtoConverter) as subsequent PRs add more RPC implementations. Not blocking for this PR.

• [Info] ProxyAdminMarshaller.java:parse() — When typeUrl doesn't match any known message, the method logs a warning and returns null. Callers must null-check every parse() result. Consider throwing InvalidProtocolBufferException instead, which is more idiomatic for protobuf deserialization and forces explicit error handling.

• [Info] AdminCode.java vs proxy_admin.proto AdminCode enum — Both define an AdminCode concept at different levels (Java error code vs proto enum). The naming overlap could cause confusion during development. Consider renaming the Java class to AdminErrorCode or AdminResponseCode to differentiate.

Positive Observations

• ✅ Proto schema follows proto3 best practices: UNSPECIFIED = 0 for all enums, java_multiple_files = true, proper package naming
• ✅ Null-safe conversion pattern consistently applied (field != null ? field : "")
• ✅ Good test coverage: AdminCodeTest, ProxyAdminMarshallerTest, ProxyAdminProtoConverterTest cover edge cases including null inputs, empty lists, and round-trip serialization
• ✅ Checkstyle suppressions properly scoped to generated code only
• ✅ Both Maven and Bazel build paths covered

Cross-repo Note

This PR defines the proto schema under apache.rocketmq.proxy.admin.v1. When the client-side admin SDK is implemented, apache/rocketmq-clients may need corresponding proto definitions or a shared proto artifact.

---

Automated review by github-manager-bot

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 48.43%. Comparing base (00e45b8) to head (9a06710).

Additional details and impacted files

@@              Coverage Diff              @@
##             develop   #10702      +/-   ##
=============================================
+ Coverage      48.31%   48.43%   +0.11%     
- Complexity     13511    13650     +139     
=============================================
  Files           1380     1392      +12     
  Lines         101091   101465     +374     
  Branches       13101    13102       +1     
=============================================
+ Hits           48844    49144     +300     
- Misses         46285    46345      +60     
- Partials        5962     5976      +14     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[RockteMQ-AI]

Review by github-manager-bot

Summary

This PR introduces the Proxy Admin gRPC protocol definition, serialization layer, and domain models for RIP-2 (RocketMQ Studio/Admin). It adds proxy_admin.proto (606 lines), domain models, and a custom ProxyAdminMarshaller.

Findings

[Positive] proxy_admin.proto — Well-structured proto definition with clear message types for admin operations (client queries, diagnostics, config management). Good use of enums for admin codes.

[Positive] ProxyAdminMarshaller.java — Custom gRPC marshaller using JSON serialization. Clean implementation with proper charset handling (StandardCharsets.UTF_8).

[Positive] Domain models — ClientDetailInfo, ClientInstanceInfo, RouteChangeEvent, TopicRouteSnapshot etc. are well-structured with proper builders and toString methods.

[Positive] Test coverage — Good unit tests for BatchConsumeClientDiagnostics, BatchConsumeGroupSummary, PopReceiptHandleGroupSummary, and PopReceiptHandleInfo.

[Warning] WORKSPACE:161-175 — Adding rules_proto 5.3.0-21.7 via http_archive. The comment mentions avoiding Bzlmod requirement from 6.0.0 — this is fine, but consider pinning the exact version in a comment for future maintainers.

[Info] ProxyConfig.java — Adding 98 lines of new config fields. Consider grouping related admin config fields with comments for readability.

Suggestions

• The proto file is large (606 lines). Consider splitting into multiple .proto files by domain (e.g., admin_client.proto, admin_config.proto) if it continues to grow.
• Ensure ProxyAdminMarshaller handles deserialization errors gracefully (currently uses ObjectMapper.readValue which can throw).

Cross-repo Note

This PR adds proto definitions that may require corresponding updates in apache/rocketmq-clients if the admin API needs to be consumed by external tools.

---

Automated review by github-manager-bot