Wang1rrr opened a new pull request, #4863:
URL: https://github.com/apache/rocketmq-dashboard/pull/4863
<!-- Make sure the base branch is `rocketmq-studio`: that is the RocketMQ
Studio trunk. -->
### Which Issue(s) This PR Fixes
- Fixes #4862
### Brief Description
`rg -i litetopic docs/api-spec.md` returned zero hits. LiteTopic is the one
RocketMQ 5.0 feature with a dedicated console page
(`web/src/pages/studio/LiteTopic.tsx`, its own `liteTopic.*` i18n namespace)
whose five endpoints were entirely undocumented.
This adds **搂17 杞婚噺涓婚 LiteTopic** plus five 搂鎺ュ彛閫熸煡 rows:
| section | endpoint | response contract now written down |
| --- | --- | --- |
| 搂17.1 | `GET /api/liteTopic/list` | `#### LiteTopicItem`, and how
`ttlStatus` is derived |
| 搂17.2 | `GET /api/liteTopic/session/{sessionId}` | `#### LiteTopicSession`
+ `#### SessionLiteTopic` |
| 搂17.3 | `POST /api/liteTopic/extendTTL` | request body, what the write
actually touches, `400`/`404` |
| 搂17.4 | `GET /api/liteTopic/quota` | `#### LiteTopicQuota`, including the
two structurally-empty fields |
| 搂17.5 | `GET /api/liteTopic/capability` | `#### LiteTopicCapability` and
why it never 5xxs |
A section preamble carries the four rules that cut across all five, because
each of them is a trap for anyone following the pattern of 搂5 or 搂9:
- **No `instanceId`.** These endpoints resolve against the server's own
`studio.rocketmq.namesrvAddr`, not the console's selected instance. Every other
resource section is instance-scoped.
- **Milliseconds at the API, minutes at the broker.** `extendTTL` converts
with `Math.round(ttlMillis / 60000.0)` clamped to `[1, 43200]` minutes, and
answers `Result<Void>` - so `newTTL=1` applies a 60 000 ms TTL and 90 days
applies as 30, with no way for the caller to read the effective value back. The
clamp itself is deliberate
(`RocketMQLiteTopicProviderTest.extendTtlClampsToTheProtocolMaximum`);
documenting it is the only place it can be surfaced.
- **Capability-first, fail-closed.** `/capability` folds "no namesrv", "no
broker master" and "broker too old for the lite RPC" into `supported=false` and
never throws, while the other four raise `501` / `503`. That asymmetry is why
the page probes first.
- **Silent scan caps** of 200 parent topics / 500 sessions per parent / 200
offset lookups per session, which truncate with only a server-side log line.
Two field-level clarifications that would otherwise read as bugs:
- `usageRate` and `sessionUsageRate` are **0-1 ratios**, not percentages
(`LiteTopic.tsx:472` multiplies by 100).
- `currentCreationRate` / `maxCreationRate` are hard-zero because no
broker-side creation-rate quota exists, and `defaultTTL` is never set because
the effective TTL lives on each parent topic.
`popProgress` is documented as nullable with the console hiding the bar -
which is what the UI does - and the issue records that the field is in fact
never populated end to end (`LiteTopicService.toSessionVO` skips it and
`RocketMQLiteTopicProvider.buildSession` never sets the domain field, and
rocketmq-remoting 5.5.0's lite response bodies carry no pop data). Fixing that
needs either a broker data source or a decision to delete the chain, so it is
deliberately not bundled into a documentation change.
Formatting follows the file's existing conventions: `#### TypeName` for
response shapes (as 搂4.1 and 搂8.1 do), 鏄?鍚?parameter tables, 閿欒鍝嶅簲 tables, and
index rows appended at the end of 搂鎺ュ彛閫熸煡 - the table already appends rather
than renumbers, which is why rows 90-98 are out of section order.
One coordination note for the maintainer: #4859 (also mine, also docs-only)
appends four DLQ rows at the same position in 搂鎺ュ彛閫熸煡 and therefore also uses
99-102. Whichever of the two merges second needs its five/four rows renumbered
- a mechanical one-line-per-row edit, no content change. The section bodies do
not overlap.
### How Did You Test This Change?
Documentation only - no code, no behaviour change. Verified by re-reading
the rendered section and cross-checking every claim against the sources at
`4c697f07`:
```
git diff --numstat
180 0 docs/api-spec.md
```
- **additive only**: 180 insertions, 0 deletions, so no existing section,
anchor or row number is disturbed
- **Markdown well-formed**: a script walks the new 搂17 and checks every
table's column count against its own header row and that the code fences
balance - `section lines 2850-3024 fences=10 bad tables=0`
- **CRLF preserved**: the file's existing line endings are unchanged, so the
diff carries no whitespace churn
- **endpoint coverage**: `rg '@(Get|Post)Mapping' LiteTopicController.java`
returns 5 mappings; 搂17 documents 5
- **every value traced to source**: `ttlStatus` vocabulary to
`LiteTopicSummary.getTTLStatus`, session `status` to
`RocketMQLiteTopicProvider.applyTtlState`, the TTL conversion and 30-day cap to
`:342` and `:99`, the scan caps to `:90`-`:96`, the quota zeroes to
`:438`-`:442`, the `501`/`503` messages to `LiteTopicProvider.UNSUPPORTED` and
`:132`, the capability fold-to-false to `:107`-`:122`, the
read-all-then-write-all ordering to `:344`-`:369`
- **line references in the issue re-checked** against the committed files
rather than a license-header offset
### Checklist
- [x] One coherent change; unrelated modifications are not bundled in
- [x] Commit subject follows Conventional Commits (`feat:` / `fix:` /
`refactor:` / `chore:` / `docs:` / `perf:`)
- [x] Tests added or updated for non-trivial changes, test methods named
`...Test` (documentation only - no behaviour changes)
- [x] New UI text has both Chinese and English entries under `web/src/i18n/`
(no UI text; the new section follows the document's existing Chinese style)
- [x] Architecture constraints stay green (`mvn test` runs the ArchUnit
checks) - no Java changed
- [x] New source files carry the ASF license header (no new source files)
- [x] Documentation touched where behaviour changed (README / `docs/` /
in-app help) - this *is* the documentation change; `rg -i litetopic README.md
README_zh.md` returns nothing, so neither README lists these endpoints and
there is nothing to keep in sync
--
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]
