messere1 opened a new pull request, #111: URL: https://github.com/apache/rocketmq-apis/pull/111
## Motivation As part of [RIP-2: Proxy Admin API](https://github.com/apache/rocketmq/issues/10601), the Proxy needs admin RPCs to query online client connections. Currently there is no gRPC API to list connected clients or inspect their details — operators must rely on CLI tools or logs. This PR adds the proto definitions for two new admin RPCs: - **`ListClients`** — List online client connections on the responding Proxy node with optional filtering and cursor-based pagination. - **`DescribeClient`** — Get detailed information for a specific client by `client_id`, including negotiated Settings, active subscriptions, and recent heartbeat records. ## Design Follows **Option A** from the [DISCUSS email](https://github.com/apache/rocketmq/issues/10601): extend the existing `Admin` service rather than introducing a separate `ProxyAdminService`. This keeps the service surface minimal and avoids naming proliferation. ### Key decisions | Decision | Choice | Rationale | |---|---|---| | Service placement | Extend existing `Admin` | Keeps proto surface minimal (Option A) | | Scope | Per-node local view | Each Proxy reports only its own clients; callers aggregate across nodes for cluster-wide view | | Pagination | Cursor-based (`next_token`) | Connections are dynamic; cursor is weakly-consistent | | Field reuse | `Language`, `ClientType`, `Status`, `Settings`, `SubscriptionEntry` from `definition.proto` | Avoid type duplication | ### New messages ``` ClientFilter — 6 filter fields (group, topic, id_prefix, language, role, time) ListClientsRequest — filter + page_size + next_token ClientInstance — 10 fields (id, language, version, endpoint, times, role, groups, auth, protocol) ListClientsResponse — status + clients + next_token + proxy_endpoint + epoch DescribeClientRequest — client_id HeartbeatRecord — time + groups ClientDetail — instance + settings + subscriptions + heartbeats + auth_status ``` ### `ClientInstance.Protocol` enum ``` PROTOCOL_UNSPECIFIED = 0 GRPC = 1 REMOTING = 2 ``` RocketMQ Proxy accepts both gRPC (v5 SDK) and Remoting (v4 SDK) client connections. The `protocol` field allows operators to distinguish them. ## Example Usage ```python # List all Java consumers subscribed to "order_topic" on a Proxy request = ListClientsRequest( filter=ClientFilter(topic="order_topic", language=LANGUAGE_JAVA, role=PUSH_CONSUMER), page_size=100 ) response = admin.ListClients(request) for client in response.clients: print(f"{client.client_id} @ {client.access_point}") ``` ## Compatibility - **Binary compatible**: Existing `ChangeLogLevel` RPC is unchanged. Field numbers for new messages start fresh; no existing field is renumbered. - **Source compatible**: New messages/RPCs are additive. Clients that don't use the new RPCs are unaffected. ## Follow-up - [ ] Server-side implementation in `apache/rocketmq` (Proxy module) — tracked separately - [ ] `rocketmq-dashboard` integration — consume `ListClients` for client management UI - [ ] Multi-proxy aggregation strategy — a CLI tool or dashboard-level fan-out ## Related - RIP-2 issue: https://github.com/apache/rocketmq/issues/10601 - DISCUSS email: see issue comments -- 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]
