zhaohai666 opened a new pull request, #117:
URL: https://github.com/apache/rocketmq-apis/pull/117
# RIP-2: Add `ProxyAdminService` gRPC interface surface to `admin.proto`
## Summary
This PR implements the **RIP-2 (Proxy Admin gRPC Interface Surface)**
control-plane
contract for the RocketMQ Proxy, expressed at the **protocol-definition
layer**
(`rocketmq-apis`). It adds a new, independent gRPC service
`ProxyAdminService` to `apache/rocketmq/v2/admin.proto`, covering online
client
query, runtime configuration, connection control, rate-limit/quota
observation,
POP/batch consumption diagnostics, and a server-streaming route-event
subscription.
The service is intentionally **separate** from the data-plane
`MessagingService`
and from the existing broker-facing `Admin` service, and it covers **both
gRPC
and Remoting clients** connected to the Proxy. This PR is the API contract
only
(message/service definitions); the server-side binding lives in the Proxy
implementation repo (e.g. `rocketmq-proxy`).
## Background
RIP-2 introduces a dedicated administrative interface for the Proxy over
gRPC so
that operators and consoles can inspect and manage the clients/state
attached to
a Proxy at runtime, without overloading the data plane. It complements —
rather
than extends — the existing `Admin` service, which targets the broker control
plane.
## Design Decisions (RIP-2)
- **D1 — Service placement (Option B):** a dedicated `ProxyAdminService`,
kept
separate from `MessagingService` and the broker-facing `Admin`.
- **D2 — Authorization (ACL 2.0):** least-privilege resource types under
`proxy.admin.*`, one per sub-module:
- `proxy.admin.client` — `ListClients` / `DescribeClient` /
`ListClientsByGroup` / `ListClientsByTopic`
- `proxy.admin.config` — `DescribeProxyConfig` / `UpdateProxyConfig`
- `proxy.admin.connection` (high privilege) — `KickClient` /
`DisconnectChannel`
- `proxy.admin.quota` (high privilege) — `DescribeQuota` / `UpdateQuota`
- `proxy.admin.route` — `DescribeRouteTopology` / `SubscribeRouteEvents`
- Credentials are carried in the **gRPC request metadata** (`Authorization`
header via the RIP-1 AUTH-01 `AuthCallCredentials` mechanism), **not**
in the
request message body — auth stays decoupled from the data plane and
reuses the
5.0 ACL 2.0 baseline. A global `proxyAdminEnable` kill switch disables
the
whole surface.
- **D3 — Multi-proxy semantics:** each Proxy returns its **local** view,
tagged
with `proxy_endpoint` + `epoch` so a dashboard/CLI can deduplicate across a
Proxy cluster. `ProxyScope` (LOCAL / CLUSTER / PROXY_ID) is wired into the
aggregate queries.
- **D4 — Pagination:** cursor-based (`next_token`) pagination for the highly
dynamic client lists; offset-based (`page_num`/`page_size`) for diagnostic
snapshots (M3/M4). No full unpaginated dumps.
- **D5 — Dual-protocol coverage:** both gRPC and Remoting clients are
included,
distinguished by the `protocol` field of `ClientInstance`.
## Added RPCs (14 total)
| Milestone | RPC | Purpose |
|-----------|-----|---------|
| **M1 — Online client query** | `ListClients` | Filter + paginate all
connected clients (by role/group/topic time window). |
| | `DescribeClient` | Full detail of a single client: settings,
subscriptions, publish settings, recent heartbeats, auth status, consume
progress, network info. |
| | `ListClientsByGroup` | Clients belonging to a consumer/producer group. |
| | `ListClientsByTopic` | Clients attached to a topic. |
| **M2 — Config & connection** | `DescribeProxyConfig` | Read the Proxy
runtime config (`ProxyRuntimeConfig`). |
| | `UpdateProxyConfig` | Controlled runtime config update (ACL
`proxy.admin.config`). |
| | `KickClient` | Force-disconnect a client by `client_id` (ACL
`proxy.admin.connection`). |
| | `DisconnectChannel` | Force-disconnect a transport channel by
`channel_id`. |
| | `DescribeQuota` | Rate-limit/quota policy visualization by
namespace/topic/group. |
| | `UpdateQuota` | Controlled quota adjustment (ACL `proxy.admin.quota`). |
| **M3 — POP diagnostics** | `DescribePopReceiptHandles` | POP
receipt-handle diagnostics incl. lock view, ACK/NACK counters, NOT_CONSUME_YET
reasons. |
| **M4 — Batch diagnostics** | `DescribeBatchConsumeDiagnostics` |
Batch-consumption diagnostics incl. pull-window state. |
| **Stream** | `SubscribeRouteEvents` | Server-streaming Proxy→Broker
route-change events. |
| **M2 — Route observation** | `DescribeRouteTopology` | Static snapshot:
Proxy→Broker links, failover state, load distribution, region-affinity. |
## Key new message/enum types
- `ClientInstance`, `ClientDetail`, `ClientFilter`, `PublishSettings`,
`HeartbeatRecord`, `AuthStatus`, `ClientConsumeProgress`, `NetworkInfo`
- `ProxyRuntimeConfig`, `ProxyScope`, `ProxyClientIdentity`
- `QuotaPolicy`, `QuotaDimension`
- `PopReceiptHandleGroupSummary`, `PopReceiptHandleInfo`, `PopLockView`
- `BatchConsumeGroupSummary`, `BatchConsumeClientDiagnostics`,
`BatchPullWindowState`
- `RouteChangeEvent`, `ProxyBrokerLink`, `LoadBalanceInfo`
- Enums: `ClientRole` (PRODUCER/PUSH_CONSUMER/SIMPLE_CONSUMER),
`ClientProtocol` (GRPC/REMOTING), `RouteChangeEventType`
Existing `apache.rocketmq.v2` types (`Status`, `Resource`, `Settings`,
`SubscriptionEntry`, `Language`, `Permission`, `MessageModel`) from
`definition.proto` are reused to stay consistent with the rest of the API.
## Validation
- `protoc 25.3` compiles `apache/rocketmq/v2/admin.proto` cleanly (with
`definition.proto` and the well-known types `Timestamp`/`Duration`).
- No conflicts with the existing `Admin` service.
## Versioning & Changelog
- Bumped protocol version: `java/VERSION` `2.2.0` → **`2.3.0`**
(backward-compatible minor).
- Added entry **15** to `ChangeLog.md` documenting the RIP-2 addition.
## Commits on this branch
- `60cafc1` RIP-2: add `ProxyAdminService` gRPC interface surface to
`admin.proto`
- `976b7e2` RIP-2: align `ProxyAdminService` with competition spec (gap
fixes)
- `15183c4` RIP-2: align `ProxyAdminService` with review feedback
- `2cd7e56` RIP-2: revert items not required by the competition spec
## Notes / Follow-ups
- This repository is the **protocol contract**; the actual service binding
and
`ProxyStartup` wiring must be implemented in the Proxy implementation repo.
- OTel self-monitoring metrics and the ACL 2.0 enforcement hook are
implementation
concerns; the contract already documents the `proxy.admin.*` resource
vocabulary
for those integrations.
- A bespoke `ProxyAdminErrorCode` taxonomy and a concrete
`page_num`/`page_size`
+ max-100 form were explored but **reverted**, as the competition spec
does not
mandate them (standard gRPC status codes + `Status.message` are used for
errors;
cursor pagination is used per D4).
--
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]
