apache / apache/rocketmq-dashboard

[Studio][Bug] rmq.message.query/trace pass the cluster input where an instance identifier is expected, so manual tool runs always 404

Open
#4,256 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Java
Stars
1.4k
Forks
683
Avg merge
2d 14h
Merged PRs (30d)
58

Description

## Problem

The `rmq.message.query` and `rmq.message.trace` tools read their `cluster` input into the instance-id slot: `MessageQueryToolHandler.java:48` and `MessageTraceToolHandler.java:47` assign `String instanceId = (String) input.get("cluster")` and pass it to `MessageService.queryMessages(instanceId, ...)` / `getMessageTrace(instanceId, ...)`, which resolve a registered instance via `providerRegistry.byInstanceId` → `RuntimeAdminClientResolver.resolveInstance` → `instanceRepository.findByIdentifier` (unique instance name or numeric id, `RuntimeAdminClientResolver.java:31-37`).

Meanwhile the consumers of these tools supply a **cluster** id, not an instance identifier:

- The AI page's tool dialog prefills every field named `cluster` with the selected cluster id (`web/src/pages/ai/index.tsx`, `buildToolInputTemplate` ← `listClusters()` → `cluster.id`).
- `rmq.cluster.list` and every other catalog surface exposes cluster ids only; no tool output contains an instance id.
- The catalog declares no `description` for the `cluster` property, so the model gets no guidance either.
- `requiredCapabilities: []` means `ToolGatewayService.enforceCapabilities` skips validation of the value entirely for these two tools.

## Evidence

1. Open the AI page, select a cluster and open the tool dialog for `rmq.message.query`: the JSON template is pre-filled with `"cluster": ""`.
2. Fill a topic and execute: the handler passes the cluster id where `findByIdentifier` expects an instance name → `404 Instance not found: `.
3. The same routing failure for the two list tools was fixed in commit 206314b9 (#4115), whose description records the exact failure mode ("404 Instance not found: DefaultCluster on every call") — the two message handlers kept the pre-fix pattern.

A second data point: the handlers' own unit tests (`MessageQueryToolHandlerTest`) pin instance-identifier semantics (`"cluster": "instance-a"`), so the field name, the tool description ("Query messages in a RocketMQ instance…") and the runtime resolution disagree.

## Impact

Both message tools are unusable from the manual tool dialog (every run fails with a misleading 404 naming a cluster id), and chat runs fail whenever the model follows the field name instead of guessing an instance identifier. No silent wrong-instance queries occur — the failure is always loud.

## Expected behavior / acceptance criteria

Executing `rmq.message.query` (or `rmq.message.trace`) with a valid target identifier returns the queried messages (or trace timeline) instead of `404 Instance not found: `. The input contract must make unambiguous which entity each tool is addressed by, and the AI page's tool dialog must not pre-fill a value of the wrong kind into that field. A regression test at the catalog/gateway layer pins the contract.

## Possible directions (need a maintainer decision)

1. Make the two runtime tools instance-addressed: rename the input to `instance` and relax `ToolCatalog.validateClusterConvention` (ToolCatalog.java:141-146) to accept `cluster` or `instance` as the declared target field. Note `enforceCapabilities` hardcodes `input.get("cluster")` and would need to read the declared field if `requiredCapabilities` is ever added to these tools.
2. Keep `cluster` and resolve it to an instance server-side — needs a resolution policy (metadata-DB lookup by `rmq_topic.cluster_id`/`rmq_consumer_group.cluster_id` with silent gaps for unsynchronized inventory; default-instance assumption; per-instance `discoverClusters` probing).
3. Minimal documentation stopgap: describe the field as an instance identifier in the catalog and stop the UI from blanket-prefilling it.

## Related work

- #4115 (merged) fixed the identical routing defect for `rmq.topic.list` / `rmq.group.list` by routing into their cluster-scoped branches; the message tools have no cluster-scoped branch to route into.
- Open PR #4148 adds paging/`includeBody`/`traceTopic` to these same two tools but does not touch the target-id routing.
- The framework currently has no cluster→instance resolution mechanism; `ClusterVO` carries no instance id.

## PR

Fix: #4257. (Implements direction 1: the two runtime tools become instance-addressed; the framework target-field invariant is relaxed accordingly. The chat-mode instance-identifier source remains an open design point, stated in the PR.)

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with MessageQueryToolHandler.java:48, MessageTraceToolHandler.java:47, ToolCatalog.java:141-146, and web/src/pages/ai/index.tsx to trace the target-field contract from the dialog through runtime resolution. Review MessageQueryToolHandlerTest and add or run catalog/gateway coverage; done means both tools accept the intended target identifier without the cluster-to-instance 404 and the UI no longer supplies the wrong value.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, typescript
Domain
backend-api-design, frontend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.