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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
