zhaohai666 opened a new pull request, #10706:
URL: https://github.com/apache/rocketmq/pull/10706
## [Studio] feat: Proxy Admin Client Service and Data Models
**Issue:** #10636
**Branch:** `feature/rip-2-pr5-admin-client-service`
---
### Overview
This PR implements the admin client query service and its associated data
models for the RIP-2 Proxy Admin Interface. It provides the core business logic
for online client discovery, detail inspection, force disconnection, and
consumption diagnostics.
### Key Changes
**ProxyAdminClientService Interface** -- Defines the admin client query
contract (202 lines) with 8 methods:
- `listClients(ListClientsFilter, pageNum, pageSize)` -- Paginated client
listing with filter pushdown.
- `describeClient(String clientId)` -- Single-client detail query returning
full `ClientDetailInfo`.
- `listClientsByGroup(String group, pageNum, pageSize)` -- Shortcut query
filtered by consumer group.
- `listClientsByTopic(String topic, pageNum, pageSize)` -- Shortcut query
filtered by subscribed topic.
- `recordHeartbeat(String clientId)` -- Heartbeat tracking hook called from
the data plane.
- `forceDisconnectClient(String clientId, String reason)` -- Admin-initiated
client disconnect.
- `describePopReceiptHandles(String group, String topic, pageNum, pageSize)`
-- POP consumption diagnostics (RIP-2 M3).
- `describeBatchConsumeDiagnostics(String group, String topic, clientId,
pageNum, pageSize)` -- Batch consumption diagnostics (RIP-2 M4).
Contains two inner result classes: `ListClientsResult` and
`BatchConsumeDiagnosticResult`.
**DefaultProxyAdminClientService** -- Full implementation (932 lines) backed
by `GrpcChannelManager` and `GrpcClientSettingsManager`.
- **Filter pushdown** (RIP-2 section 8.1): Single-pass iteration over
`clientIdChannelMap` with early filtering by group, topic, clientIdPrefix,
language, and connectTime range. Avoids materializing the full client list
before filtering.
- **Client detail construction**: Builds comprehensive `ClientDetailInfo`
from channel + settings data, including:
- `ClientInstanceInfo`: clientId, language, clientVersion, protocol,
accessPoint, connectTime, lastActiveTime, role, group, topics.
- `ClientSettingsInfo`: subscriptionMode, receiveBatchSize,
longPollingTimeoutMs, fifo, subscriptionTopics, publishingTopics.
- `HeartbeatRecordInfo`: Bounded heartbeat history from
`ConcurrentLinkedDeque<HeartbeatRecord>` with synthetic fallback.
- `AuthStatusInfo`: 3-priority username resolution (auth metadata > UA
platform > clientId convention).
- `ConsumeProgressInfo`: M1 stub (lag/latency = -1, topic list from
subscription).
- `NetworkInfoInfo`: local/remote address, RTT, SSL detection
(per-connection then global TLS fallback).
- **Sampling**: `shouldSample()` returns true when client count exceeds
100,000, enabling load-aware degradation.
- **Force disconnect**: Closes gRPC stream via
`GrpcClientChannel.forceClose()`, removes channel and settings entries.
- **POP diagnostics**: Delegates to `ReceiptHandleManager` for receipt
handle scanning.
- **Batch diagnostics**: Enriches raw `ChannelBatchConsumeData` with gRPC
channel/settings info, re-paginates, recalculates group summary.
**Data Models** (7 new model classes):
| Model | Location | Description |
|-------|----------|-------------|
| `ClientInstanceInfo` | `proxy/.../grpc/admin/model/` | Client identity:
clientId, language, version, protocol, accessPoint, connectTime,
lastActiveTime, role, group, topics |
| `ClientDetailInfo` | `proxy/.../grpc/admin/model/` | Aggregate detail:
clientInstance + settings + heartbeatHistory + authStatus + consumeProgress +
networkInfo (5 inner model classes) |
| `ListClientsFilter` | `proxy/.../grpc/admin/model/` | Filter criteria:
group, topic, clientIdPrefix, language, connectTimeStart, connectTimeEnd;
`hasFilter()` method |
| `BatchConsumeClientDiagnostics` | `proxy/.../common/` | Per-client
diagnostic data: unacked counts, renew stats, expired handles, topic
distribution, consume type, message model |
| `BatchConsumeGroupSummary` | `proxy/.../common/` | Aggregated group stats:
totalClients, totalUnackedMessages, totalUnackedHandles, totalExpiredHandles,
totalRenewTimes |
| `PopReceiptHandleGroupSummary` | `proxy/.../common/` | POP handle group
stats: totalHandles, totalMessages, totalRenewTimes, totalRenewRetryTimes,
expiredHandles |
| `PopReceiptHandleInfo` | `proxy/.../common/` | Single POP handle
diagnostic: group, topic, queueId, messageId, queueOffset, reconsumeTimes,
renewTimes, receiptHandle, nextVisibleTime, expired |
### Test Coverage
| Test File | Lines | Coverage |
|-----------|-------|----------|
| `DefaultProxyAdminClientServiceTest.java` | 934 | Language conversion (all
11 enum values), pagination, filter pushdown, describeClient (success/not
found/auth/network/heartbeat/consume progress), sampling threshold, heartbeat
recording, force disconnect, POP/batch diagnostics |
| `DefaultProxyAdminClientServiceUnitTest.java` | 405 | Mockito-based tests:
empty channels, pageNum/pageSize normalization, null filter safety, pagination,
describeClient edge cases |
| `AdminModelTest.java` | 178 | ListClientsFilter, PopReceiptHandleInfo,
BatchConsumeGroupSummary model tests |
### Files Changed
| File | Description |
|------|-------------|
| `proxy/src/main/java/.../service/admin/ProxyAdminClientService.java` |
Service interface (new, 202 lines) |
|
`proxy/src/main/java/.../service/admin/DefaultProxyAdminClientService.java` |
Full implementation (new, 932 lines) |
| `proxy/src/main/java/.../grpc/admin/model/ClientInstanceInfo.java` |
Client identity model (new, 136 lines) |
| `proxy/src/main/java/.../grpc/admin/model/ClientDetailInfo.java` | Client
detail aggregate (new, 196 lines) |
| `proxy/src/main/java/.../grpc/admin/model/ListClientsFilter.java` | Filter
criteria (new, 92 lines) |
| `proxy/src/main/java/.../common/BatchConsumeClientDiagnostics.java` |
Per-client diagnostics (new, 87 lines) |
| `proxy/src/main/java/.../common/BatchConsumeGroupSummary.java` | Group
summary (new, 55 lines) |
| `proxy/src/main/java/.../common/PopReceiptHandleGroupSummary.java` | POP
handle summary (new, 51 lines) |
| `proxy/src/main/java/.../common/PopReceiptHandleInfo.java` | Single handle
diagnostic (new, 79 lines) |
|
`proxy/src/test/java/.../service/admin/DefaultProxyAdminClientServiceTest.java`
| Service tests (new, 934 lines) |
|
`proxy/src/test/java/.../service/admin/DefaultProxyAdminClientServiceUnitTest.java`
| Mockito tests (new, 405 lines) |
| `proxy/src/test/java/.../grpc/admin/model/AdminModelTest.java` | Model
tests (new, 178 lines) |
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
