Wang1rrr opened a new issue, #4862: URL: https://github.com/apache/rocketmq-dashboard/issues/4862
### Before Creating the Doc Report - [x] I have searched the [open issues](https://github.com/apache/rocketmq-dashboard/issues) and found no similar issue. ### Which Documentation `docs/api-spec.md` - the whole document. `rg -i litetopic docs/api-spec.md` returns **0 hits** on `rocketmq-studio` @ `4c697f07`. ### What Is Wrong LiteTopic is the one RocketMQ 5.0 feature the console has a dedicated page for (`web/src/pages/studio/LiteTopic.tsx`, 900+ lines, with its own `liteTopic.*` i18n namespace) and `docs/api-spec.md` does not mention it at all. `LiteTopicController` (`server/src/main/java/org/apache/rocketmq/studio/instance/topic/LiteTopicController.java`) exposes five endpoints, none of them documented and none of them in the §接口速查 index: | endpoint | source | | --- | --- | | `GET /api/liteTopic/list` | `:40` | | `GET /api/liteTopic/session/{sessionId}` | `:47` | | `POST /api/liteTopic/extendTTL` | `:52` | | `GET /api/liteTopic/quota` | `:58` | | `GET /api/liteTopic/capability` | `:63` | That leaves five response contracts (`LiteTopicItemVO`, `LiteTopicSessionVO` + its nested `SessionLiteTopic`, `LiteTopicQuotaVO`, `LiteTopicCapabilityVO`, `LiteTopicTTLUpdateDTO`) with no written shape, and a set of behaviours that are only discoverable by reading three layers of Java: - **These endpoints take no `instanceId`.** Every other resource section in the spec is instance-scoped; LiteTopic resolves against the server's own `studio.rocketmq.namesrvAddr` (`RocketMQLiteTopicProvider.execute`, `:468`). An integrator following the pattern of §5 or §9 will look for an `instanceId` parameter that does not exist. - **The TTL unit changes across the boundary.** The API speaks milliseconds, the broker's `lite.topic.expiration` speaks minutes, and `extendTTL` converts with `Math.round(ttlMillis / 60000.0)` clamped to `[1, 43200]` minutes (`RocketMQLiteTopicProvider:342`). So `newTTL=1` is accepted by `@Positive` and applies a 60 000 ms TTL, and 90 days is applied as 30 days. The clamp is deliberate and pinned by `RocketMQLiteTopicProviderTest.extendTtlClampsToTheProtocolMaximum`, but the response is `Result<Void>`, so the caller has no way to learn the effective value - the spec is the only place it can be written down. - **`usageRate` / `sessionUsageRate` are 0-1 ratios, not percentages.** `LiteTopicQuota.getUsageRate` returns `currentTopicCount / maxTopicCount`; the console multiplies by 100 (`LiteTopic.tsx:472`, `:478`). Nothing says so. - **Two quota fields are structurally always empty**: `currentCreationRate` / `maxCreationRate` are hard-set to `0.0` because no broker-side creation-rate quota exists (`:439`-`:442`), and `defaultTTL` is never set because the effective TTL lives on each parent topic. A reader will otherwise assume both are broken. - **`ttlStatus` is a computed value with its own vocabulary** - `ACTIVE` / `EXPIRING_SOON` / `EXPIRED` / `UNKNOWN` - derived in `LiteTopicSummary.getTTLStatus` from elapsed-since-last-active against `averageTTL` (80% threshold), and `EXPIRED` must be tested before `EXPIRING_SOON` or it is unreachable. - **`/capability` never returns 5xx.** It folds "no namesrv configured", "no broker master" and "broker too old to answer the lite RPC" all into `supported=false` (`:107`-`:122`), and the console fails closed on it. The other four endpoints do throw `501 LiteTopic is not supported by this provider` / `503 No broker master is available for LiteTopic queries`. That split is the reason the page calls `/capability` first and it is invisible today. - **Silent scan caps**: 200 parent topics per list call, 500 sessions per parent topic, 200 per-lite-topic offset lookups per session detail (`MAX_LITE_TOPIC_SCAN` / `MAX_LITE_SESSION_SCAN` / `MAX_SESSION_LITE_TOPIC_SCAN`, `:90`-`:96`). Results truncate with only a server-side log line. - **`extendTTL` writes to every master that holds the parent topic**, reading all of their configs before writing any, so a partial failure cannot leave the cluster with mixed TTL attributes while the console reports success (`:344`-`:369`). It also uses the broker's `+key=value` attribute-change protocol and deliberately does not re-send the immutable `message.type`. - **`sessionId` is opaque** - `LiteTopicProvider.getSession`'s javadoc says it is "an opaque token produced by listLiteTopics", and it internally encodes parent topic / group / clientId. A malformed one is `400`, a well-formed but vanished one is `404`. ### Suggested Change Add a new top-level section to `docs/api-spec.md` (LiteTopic is a broker-side 5.0 feature with its own controller, so it reads better as its own section than as §5.x under Topic 管理), covering the five endpoints in the format the document already uses - parameter tables, `#### TypeName` blocks for the response shapes, and 错误响应 tables - plus a section preamble for the four cross-cutting rules (no `instanceId`, ms-vs-minutes TTL, capability-first degradation, scan caps) and index rows in §接口速查. One field deserves an honest note rather than an invented contract: `LiteTopicSessionVO.popProgress` (`:43`) is declared, rendered by `LiteTopic.tsx:696`-`:705` as a purple progress bar, translated in both languages (`liteTopic.popProgress`), and asserted in `LiteTopicControllerTest:119` - but `LiteTopicService.toSessionVO` never sets it and `RocketMQLiteTopicProvider.buildSession` (`:256`-`:293`) never populates the domain field either, so it is always `null` in a real response. `GetLiteGroupInfoResponseBody` / `GetLiteClientInfoResponseBody` / `GetBrokerLiteInfoResponseBody` in rocketmq-remoting 5.5.0 carry no pop-progress data, so there is no obvious source to fill it from. The spec should describe it as nullable-with-the-bar-hidden (which is what the UI does), and the dead chain is worth its own issue - fixing it needs either a broker data source or a decision to remove it. ### Are You Willing to Submit a Pull Request? - [x] Yes, I am willing to submit a pull request. -- 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]
