pilichoumao opened a new pull request, #4771:
URL: https://github.com/apache/rocketmq-dashboard/pull/4771
### Which Issue(s) This PR Fixes
No tracking issue. Closes a tool-coverage gap for a headline 5.0 capability:
the AI-01 coverage requirement (tools/CLI for the A–K capabilities) has no
LiteTopic entry today, although the Studio backend already serves pattern
aggregates, session views and quota watermarks from the broker lite admin API
(#4220) and META-01 M4 treats LiteTopic as a first-class resource domain.
### Brief Description
Add three L1 read-only tools over the existing `LiteTopicService` — no new
endpoint, service, dependency or configuration:
- **`rmq.litetopic.list`** (`rmqctl litetopic list`) — pattern-level
aggregates (topic count, consumer count, backlog, average TTL, TTL status, last
active time, session ids) with optional `pattern` prefix and `namespace`
filters; table view.
- **`rmq.litetopic.session`** (`rmqctl litetopic session`) — one session:
owning client, parent topic, consumer group, create/last-active time, TTL and
remaining TTL, message/Pop progress counters, and the session's individual lite
topics.
- **`rmq.litetopic.quota`** (`rmqctl litetopic quota`) — quota watermark:
current/max topic, session and creation-rate counts, usage rates, default/max
TTL, remaining quota, consumer density.
Design notes:
- **No invented data.** Outputs are dedicated `@JsonInclude(NON_NULL)`
contract records mapped from the existing VOs: statistics a broker cannot
report stay absent instead of being zero-filled (an unknown backlog is not a
zero backlog). A cluster without lite support surfaces the provider's `501
LiteTopic is not supported` unchanged.
- **Platform-level scoping, honestly declared.** `LiteTopicService` reads
the configured default cluster (`studio.rocketmq.namesrv-addr`), not an
arbitrary instance — so the three tools join the existing
`INSTANCE_ID_EXEMPT_TOOLS` set (Java) and `platformToolNames` (rmqctl), like
the nameserver/broker/proxy tools, instead of pretending to be instance-scoped.
The catalog descriptions state the data source.
- **`extendTTL` deliberately excluded**: it is the first LiteTopic mutation
and deserves its own reviewed slice with dry-run/apply + confirmation
semantics. This PR is read-only.
- The three tools are one coherent capability ("an LLM can read LiteTopic
state"); the bulk of the diff is the catalog YAML schemas and tests. rmqctl
support comes from the regenerated catalog (`make catalog-generate` /
`catalog-verify`).
### How Did You Test This Change?
- **Unit:** `LiteTopicListToolHandlerTest` (filter pass-through; sparse rows
keep unreportable statistics absent), `LiteTopicSessionToolHandlerTest` (full
mapping incl. nested entries; sparse session stays partial),
`LiteTopicQuotaToolHandlerTest` (full watermark; partial watermark stays
partial).
- **Contract:** samples for all three tools added to
`ToolOutputSchemaContractTest` (it enforces every catalog tool having a
schema-valid output sample); the new shard validates against
`rmq-tools.schema.json` on every catalog load, and the rmqctl generator
enforces the platform-tool `instanceId` convention on both sides.
- **Build:** Java 21, `mvn -B -ntp -Dspring.profiles.active=dev package` —
**3,150 tests passed**, 0 failures, **0 Checkstyle violations**, packaged
(clean local repository). `cd rmqctl && make catalog-verify && go test ./... &&
gofmt -l . && go vet ./...` — all clean.
- **End-to-end against a real local Apache RocketMQ 5.5.0
NameServer/Broker** with this branch's jar and `studio.rocketmq.namesrv-addr`
pointed at it, calling the real `POST /api/ai/tools/{name}/execute` API:
- `rmq.litetopic.quota` (with and without a namespace filter) returned
`200` with the broker's real watermark — `maxTopicCount=20000`,
`maxSessionCount=100000`, `maxTTL=2592000000`, zeroed current counts;
- `rmq.litetopic.list` (unfiltered and `pattern=chat/`) returned `200`
with an honest empty list — no lite topic existed on the cluster (they are
SDK-auto-created);
- `rmq.litetopic.session` with a malformed id returned a distinguishable
`400` ("Malformed LiteTopic session id");
- audit recorded `LIST_LITETOPIC ... SUCCESS` and `SESSION_LITETOPIC ...
FAILED` correctly.
- All temporary JVMs were shut down afterwards.
Not exercised: a cluster with live lite-topic sessions (requires a
lite-capable gRPC SDK session; the list/session positive paths with real rows
are covered by the handler/contract tests), CLOUD instances, ACL/TLS clusters.
### CI Status
The repository's Actions policy still rejects action versions referenced by
the existing workflow (`docker/setup-buildx-action@v3`,
`docker/build-push-action@v6`), so GitHub-hosted runs end in `startup_failure`
before any job starts (same as #4550/#4665/#4769). This PR does not change the
workflow; all results above are local.
### Checklist
- [x] One coherent capability; no unrelated modifications
- [x] Conventional commit subject; regression tests use `...Test`
- [x] Tool schemas validate; output contract samples included for every new
tool
- [x] No invented metadata; unreportable statistics stay absent; unsupported
clusters keep their 501
- [x] Architecture and formatting checks pass (0 Checkstyle violations;
gofmt/vet clean)
- [x] rmqctl catalog regenerated and verified; no new dependency, port or
configuration
🤖 Generated with [Claude Code](https://claude.com/claude-code)
--
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]
