You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@rocketmq.apache.org by "Wang1rrr (via GitHub)" <gi...@apache.org> on 2026/09/22 05:12:46 UTC
[PR] docs: correct the proxy restart contract and document the other five [rocketmq-dashboard]
Wang1rrr opened a new pull request, #4865:
URL: https://github.com/apache/rocketmq-dashboard/pull/4865
### Which Issue(s) This PR Fixes
- Fixes #4864
### Brief Description
`docs/api-spec.md` documents one of the six `/api/proxies` endpoints and gets that one wrong. This corrects 4.11 and documents the other five.
**4.11 重启 Proxy** was describing a contract the code does not have:
- the request body is `RestartProxyDTO`, whose `clusterId` **and** `addr` are both `@NotBlank`; the documented one-field body is rejected with `400 clusterId is required`
- the response is `Result<Void>`, so `data` is `null` - there is no `{ success: boolean }` to read
- `ClusterService.restartProxy` (`:626`) validates the cluster and the address and then unconditionally throws `unsupportedOperation("Proxy restart")` (`:654`), i.e. `501 ... not implemented by the current cluster provider`. That is now stated explicitly with a 400/404/501 error table, because the console still shows a success toast (`web/src/pages/cluster/index.tsx:1722`) and the spec is the only place a reader can learn the truth.
**New 4.12-4.16** cover `GET /api/proxies`, `GET /api/proxies/topology`, `POST /api/proxies/addresses`, `DELETE /api/proxies/addresses` and `POST /api/proxies/config/reload`, in the format the document already uses. Each section pins the behaviour that is not guessable from the path:
- two unrelated notions of "proxy": `GET /api/proxies` returns the cluster-registered list (`ClusterVO.proxies`, no probing), while topology/address/reload operate on Studio's own in-memory address list seeded with `127.0.0.1:8081`. `/topology` takes no `clusterId` and ignores cluster registration.
- two status vocabularies for the same concept: `ClusterStatus` (`healthy`/`warning`/`error`/`offline`) on `ProxyVO` versus the probe outcome (`UP`/`PARTIAL`/`DOWN`) on `ProxyTopologyVO`.
- the probe budget: 2 s per port, parallel on a bounded pool, 10 s overall; probes that overrun are reported unreachable, so dead nodes yield `DOWN` rows instead of a 5xx or a hung request.
- `remotingPort` is derived (`8081 -> 8080`, `8080 -> 8081`, otherwise `null`, in which case `remotingReachable` is hard-`false`), and `latencyMs` is `-1` when gRPC is unreachable.
- malformed registered addresses are skipped with only a server-side log line, so `/topology` can return fewer rows than the address list.
- address mutation is validated (`host:port` / `[ipv6]:port`, ports 1-65535), idempotent on duplicates, audited (`ADD_PROXY_ADDRESS` / `REMOVE_PROXY_ADDRESS`, plus a `FAILED` row on a 404 delete), and **not persisted** - a Studio restart drops every address an operator added.
- `/config/reload` requires the address to be registered under `clusterId`, POSTs to `http://{addr}/admin/reloadConfig`, maps non-2xx and connection failures to `502` and everything else to `500`, and never answers `success: false`.
The K8s certificate sections move from 4.12-4.15 to 4.17-4.20 so the proxy endpoints stay grouped next to 重启 Proxy. Nothing else references those numbers: `rg -n "4\.1[2-5]" --glob '*.md'` matches only the four headings themselves.
Scope notes - deliberately left out so this stays one coherent change:
- `ProxyCompatController` (`/api/proxy/homePage.query`, `addProxyAddr.do`, `removeProxyAddr.do`) is undocumented too; it is the v2.1.0 compatibility surface and reads better as its own subsection.
- 4.4 重启 Broker has the same defect (`{ success: boolean, message: string }` documented, only `message` returned, `ClusterService.restartBroker` always throws `501`).
- The dead `if (!success)` branch in `ProxyController.restartProxy` (`:74`) and its `boolean` service return are a code change, not a documentation one.
Coordination note for the maintainer: #4859 and #4863 (also mine, also docs-only) append rows at the same tail position in 接口速查 and therefore also use 99+. Whichever of the three merges later needs its rows renumbered - a mechanical one-line-per-row edit with no content change. The section bodies do not overlap.
### How Did You Test This Change?
Documentation only - no code, no behaviour change. Every claim was traced to the sources at `4c697f07` and the file was re-checked mechanically after the edit:
```
git diff --numstat
151 5 docs/api-spec.md
```
- **the five deletions are the 4.11 body/response lines being corrected plus the four renumbered K8s headings** - no other existing text is disturbed
- **Markdown well-formed**: a script walks the whole file and compares each table's column count against its own header row and checks fence balance - `fences: 222 balanced: true badTables: 0` for the new and changed sections (the three tables it flags elsewhere are pre-existing `string \| null` cells whose escaped pipe the counter splits on; they are untouched by this diff)
- **section numbering**: `### 4.x` headings now run 4.1 ... 4.20 with no gaps and no duplicates
- **index integrity**: 103 rows, 103 distinct row numbers, appended at the tail as rows 99-103
- **CRLF preserved, no BOM**: `bom: false crlf: true`, so the diff carries no whitespace churn
- **endpoint coverage**: `rg '@(Get|Post|Delete)Mapping' ProxyController.java` returns 6 mappings; section 4 documents 6
- **values traced to source**: the 501 to `ClusterService:654`, the two `@NotBlank` fields to `RestartProxyDTO`, the 2 s / 10 s budgets to `ProxyAddressService:68` and `:77`, the port pairing to `:267`, the address pattern and port range to `:59`-`:63`, the reload path to `:65`, the 502/500 split to `reloadValidatedProxy`, the audit constants to `OperationAuditConstants:37`-`:39`, and the default `127.0.0.1:8081` seed to `:83`
### 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 sections follow 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; neither README lists these endpoints, so 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: commits-unsubscribe@rocketmq.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: correct the proxy restart contract and document the other five [rocketmq-dashboard]
Posted by "lizhimins (via GitHub)" <gi...@apache.org>.
lizhimins merged PR #4865:
URL: https://github.com/apache/rocketmq-dashboard/pull/4865
--
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: commits-unsubscribe@rocketmq.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org