You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@rocketmq.apache.org by li...@apache.org on 2026/09/15 03:15:36 UTC
(rocketmq-dashboard) branch rocketmq-studio updated: feat(rmqctl): target instances with an explicit --instance-id (#4310)
This is an automated email from the ASF dual-hosted git repository.
lizhimins pushed a commit to branch rocketmq-studio
in repository https://gitbox.apache.org/repos/asf/rocketmq-dashboard.git
The following commit(s) were added to refs/heads/rocketmq-studio by this push:
new f71dd8d08 feat(rmqctl): target instances with an explicit --instance-id (#4310)
f71dd8d08 is described below
commit f71dd8d082f9fb63a6a23c1e691417dece644733
Author: lizhimins <70...@qq.com>
AuthorDate: Tue Sep 15 11:15:30 2026 +0800
feat(rmqctl): target instances with an explicit --instance-id (#4310)
- replace the context-derived cluster with a required --instance-id flag,
sent as x-rmq-instance-id and passed through to the tool arguments; no
value is injected from the context or config
- regenerate the catalog client for the 40-tool surface and drop
x-target-mode from the generator, so an unknown schema keyword now
fails generation
- fill a required reset-offset timestamp from x-client-default: NOW
- recompute the HMAC golden vectors for the renamed canonical payload
---
rmqctl/cmd/app_test.go | 177 ++++-
rmqctl/cmd/catalog.go | 107 ++-
rmqctl/cmd/catalog_instance_test.go | 211 ++++++
rmqctl/cmd/catalog_test.go | 26 +-
rmqctl/cmd/cmd.go | 3 +
rmqctl/cmd/config.go | 7 +-
rmqctl/cmd/config_test.go | 42 +-
rmqctl/cmd/error.go | 2 +-
rmqctl/cmd/explain.go | 31 +-
rmqctl/cmd/explain_test.go | 36 +
rmqctl/cmd/mcp.go | 3 +
rmqctl/cmd/mcp_stdio_test.go | 28 +
rmqctl/cmd/runtime.go | 14 +-
rmqctl/cmd/testhelpers_test.go | 24 +-
rmqctl/internal/catalog/catalog.go | 61 ++
rmqctl/internal/catalog/catalog_gen.go | 828 ++++++++-------------
rmqctl/internal/catalog/catalog_test.go | 10 +-
rmqctl/internal/catalog/generate/main.go | 84 ++-
rmqctl/internal/catalog/generate/main_test.go | 220 +++++-
rmqctl/internal/config/config.go | 6 +-
rmqctl/internal/config/config_test.go | 3 +-
rmqctl/internal/output/output.go | 10 +-
rmqctl/internal/output/output_test.go | 2 +-
rmqctl/internal/studio/auth.go | 17 +-
rmqctl/internal/studio/auth_test.go | 10 +-
rmqctl/internal/studio/client.go | 6 +-
rmqctl/internal/studio/mcp_http.go | 8 +-
rmqctl/internal/studio/mcp_http_test.go | 2 +-
rmqctl/internal/studio/mcp_message.go | 34 +-
rmqctl/internal/studio/mcp_message_test.go | 125 ++++
.../studio/testdata/auth-hmac-vectors.json | 38 +
rmqctl/internal/studio/tools_test.go | 14 +-
rmqctl/internal/types/types.go | 2 +-
33 files changed, 1475 insertions(+), 716 deletions(-)
diff --git a/rmqctl/cmd/app_test.go b/rmqctl/cmd/app_test.go
index 8d68ac9e0..eed904dc8 100644
--- a/rmqctl/cmd/app_test.go
+++ b/rmqctl/cmd/app_test.go
@@ -17,6 +17,7 @@
package cmd
import (
+ "bytes"
"encoding/json"
"net/http"
"net/http/httptest"
@@ -24,6 +25,7 @@ import (
"strings"
"testing"
+ toolcatalog "github.com/apache/rocketmq-dashboard/rmqctl/internal/catalog"
"github.com/apache/rocketmq-dashboard/rmqctl/internal/types"
)
@@ -36,6 +38,7 @@ type observedToolCall struct {
func TestCatalogMutationRoundTrip(t *testing.T) {
const confirmToken = "confirmation"
+ instanceKey := catalogInstanceArgumentKey(t, "rmq.topic.update")
observed := make(chan observedToolCall, 2)
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
var request types.ToolCallRequest
@@ -46,13 +49,13 @@ func TestCatalogMutationRoundTrip(t *testing.T) {
observed <- observedToolCall{r.Method, r.URL.Path, r.Header.Get("Authorization"), request}
mutation := map[string]any{
"status": "PLANNED",
- "cluster": request.Arguments["cluster"],
+ "instanceId": request.Arguments[instanceKey],
"plan": map[string]any{"summary": "Create topic orders"},
"confirm_token": confirmToken,
}
if dryRun, ok := request.Arguments["dry_run"]; !ok || dryRun != true {
mutation["status"] = "EXECUTED"
- mutation["result"] = map[string]any{"topic": request.Arguments["topic"]}
+ mutation["result"] = map[string]any{"topic": request.Arguments["topicName"]}
}
writeStudioSuccess(t, w, mutation)
}))
@@ -60,14 +63,14 @@ func TestCatalogMutationRoundTrip(t *testing.T) {
stdout, stderr, exitCode := executeTestApp(t, server.Client(), server.URL,
"--output", "json",
- "topic", "create", "--dry-run", "--topic", "orders", "--write-queues", "8",
+ "topic", "update", "--dry-run", "--topic-name", "orders", "--write-queues", "8",
)
if exitCode != 0 {
t.Fatalf("preview failed: %s", stderr)
}
call := <-observed
wantArguments := map[string]any{
- "cluster": "instance-dev", "topic": "orders", "writeQueues": float64(8), "dry_run": true,
+ instanceKey: "instance-dev", "topicName": "orders", "writeQueues": float64(8), "dry_run": true,
}
if call.method != http.MethodPost || call.path != "/api/mcp/tools/call" ||
!strings.HasPrefix(call.authorization, "RMQ-HMAC-SHA256 Credential=test-ak, Signature=") ||
@@ -84,7 +87,7 @@ func TestCatalogMutationRoundTrip(t *testing.T) {
stdout, stderr, exitCode = executeTestApp(t, server.Client(), server.URL,
"--output", "json",
- "topic", "create", "--topic", "orders", "--write-queues", "8",
+ "topic", "update", "--topic-name", "orders", "--write-queues", "8",
"--confirm-token", confirmToken,
"--yes",
)
@@ -101,52 +104,166 @@ func TestCatalogMutationRoundTrip(t *testing.T) {
}
}
-func TestCatalogDefaultsClusterToContextInstance(t *testing.T) {
- observed := make(chan types.ToolCallRequest, 1)
+// TestCatalogYesAutoFetchesConfirmToken verifies that --yes on an L2 mutation
+// without an explicit --confirm-token transparently runs a dry-run preview to
+// obtain the token and then executes, so callers need not script the two-phase
+// handshake manually.
+func TestCatalogYesAutoFetchesConfirmToken(t *testing.T) {
+ const confirmToken = "auto-confirmation"
+ instanceKey := catalogInstanceArgumentKey(t, "rmq.topic.update")
+ observed := make(chan observedToolCall, 2)
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
var request types.ToolCallRequest
if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
- t.Error(err)
+ http.Error(w, err.Error(), http.StatusBadRequest)
+ return
+ }
+ observed <- observedToolCall{r.Method, r.URL.Path, r.Header.Get("Authorization"), request}
+ mutation := map[string]any{
+ "status": "PLANNED",
+ "instanceId": request.Arguments[instanceKey],
+ "plan": map[string]any{"summary": "Create topic orders"},
+ "confirm_token": confirmToken,
}
- if r.Header.Get("X-RMQ-Cluster") != "instance-profile" {
- t.Error("wrong authenticated Instance")
+ if dryRun, ok := request.Arguments["dry_run"]; !ok || dryRun != true {
+ mutation["status"] = "EXECUTED"
+ mutation["result"] = map[string]any{"topic": request.Arguments["topicName"]}
}
- observed <- request
- writeStudioSuccess(t, w, map[string]any{"items": []any{}})
+ writeStudioSuccess(t, w, mutation)
}))
defer server.Close()
- _, stderr, exitCode := executeTestAppWithInstance(t, server.Client(), server.URL, "profile",
- "--output", "json", "topic", "list")
+ stdout, stderr, exitCode := executeTestApp(t, server.Client(), server.URL,
+ "--output", "json",
+ "topic", "update", "--topic-name", "orders", "--write-queues", "8",
+ "--yes",
+ )
if exitCode != 0 {
- t.Fatalf("context default failed: exit=%d stderr=%s", exitCode, stderr)
+ t.Fatalf("apply failed: %s", stderr)
+ }
+
+ preview := <-observed
+ if preview.request.Arguments["dry_run"] != true ||
+ preview.request.Arguments["confirm_token"] != nil {
+ t.Fatalf("expected an auto dry-run preview first: %#v", preview.request)
+ }
+ applyCall := <-observed
+ if applyCall.request.Arguments["dry_run"] != nil ||
+ applyCall.request.Arguments["confirm_token"] != confirmToken {
+ t.Fatalf("expected the apply call to carry the auto-fetched token: %#v", applyCall.request)
}
- if request := <-observed; request.Arguments["cluster"] != "instance-profile" {
- t.Fatalf("cluster = %v, want context Instance", request.Arguments["cluster"])
+ var apply map[string]any
+ if err := json.Unmarshal([]byte(stdout), &apply); err != nil || apply["status"] != "EXECUTED" {
+ t.Fatalf("unexpected apply output: %#v, err=%v", apply, err)
}
}
-func TestCatalogPreservesExplicitCluster(t *testing.T) {
- observed := make(chan types.ToolCallRequest, 1)
+// catalogInstanceArgumentKey returns the arguments key carrying the Studio
+// instance identifier for the named catalog tool ("instanceId" after the
+// catalog regeneration, transitional "cluster" before it).
+func catalogInstanceArgumentKey(t *testing.T, toolName string) string {
+ t.Helper()
+ tool, ok := toolcatalog.LookupTool(toolName)
+ if !ok {
+ t.Fatalf("tool %q is missing from the catalog", toolName)
+ }
+ name, ok := toolcatalog.InstanceFieldName(tool.InputSchema)
+ if !ok {
+ t.Fatalf("tool %q does not declare an instance identifier field", toolName)
+ }
+ return name
+}
+
+// TestCatalogRequiresExplicitInstanceID verifies decision 7: no default
+// injection from the context or config. A tool call without --instance-id
+// fails with INVALID_ARGUMENT before any HTTP request is sent.
+func TestCatalogRequiresExplicitInstanceID(t *testing.T) {
+ requests := make(chan struct{}, 1)
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ requests <- struct{}{}
+ writeStudioSuccess(t, w, map[string]any{"items": []any{}})
+ }))
+ defer server.Close()
+
+ stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+ app := NewApp(stdout, stderr)
+ app.HTTP = server.Client()
+ app.Store.Getenv = testEnv
+ app.confirm = stubConfirmReject
+ configPath := newTestConfigPath(t)
+ if err := app.Store.Save(configPath, newTestConfig(server.URL)); err != nil {
+ t.Fatal(err)
+ }
+ exitCode := app.Execute([]string{"--config", configPath, "topic", "list"})
+ if exitCode != 1 {
+ t.Fatalf("exit code = %d, want 1; stdout=%s stderr=%s", exitCode, stdout, stderr)
+ }
+ if !strings.Contains(stderr.String(), "INVALID_ARGUMENT") ||
+ !strings.Contains(stderr.String(), "--instance-id is required") {
+ t.Fatalf("stderr = %q, want INVALID_ARGUMENT for the missing --instance-id", stderr)
+ }
+ if !strings.Contains(stderr.String(), "explicitly") {
+ t.Fatalf("stderr = %q, want a hint to pass --instance-id explicitly", stderr)
+ }
+ select {
+ case <-requests:
+ t.Fatal("request was sent without --instance-id")
+ default:
+ }
+}
+
+// TestCatalogPassesExplicitInstanceIDToArgumentsAndHeader verifies that the
+// explicit --instance-id value is passed through to the tool arguments (for
+// tools whose schema declares the instance identifier) and used for the
+// x-rmq-instance-id request header/HMAC signing.
+func TestCatalogPassesExplicitInstanceIDToArgumentsAndHeader(t *testing.T) {
+ instanceKey := catalogInstanceArgumentKey(t, "rmq.topic.list")
+ observed := make(chan observedToolCall, 1)
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
var request types.ToolCallRequest
if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
- http.Error(w, err.Error(), http.StatusBadRequest)
- return
+ t.Error(err)
+ }
+ observed <- observedToolCall{
+ method: r.Method, path: r.URL.Path,
+ authorization: r.Header.Get("Authorization"), request: request,
+ }
+ if r.Header.Get("x-rmq-instance-id") != "instance-profile" {
+ t.Error("wrong x-rmq-instance-id header")
}
- observed <- request
writeStudioSuccess(t, w, map[string]any{"items": []any{}})
}))
defer server.Close()
- _, stderr, exitCode := executeTestApp(t, server.Client(), server.URL,
+ _, stderr, exitCode := executeTestAppWithInstance(t, server.Client(), server.URL, "profile",
+ "--output", "json", "topic", "list")
+ if exitCode != 0 {
+ t.Fatalf("explicit instance failed: exit=%d stderr=%s", exitCode, stderr)
+ }
+ call := <-observed
+ if value := call.request.Arguments[instanceKey]; value != "instance-profile" {
+ t.Fatalf("%s = %v, want the explicit --instance-id value", instanceKey, value)
+ }
+ if !strings.HasPrefix(call.authorization, "RMQ-HMAC-SHA256 Credential=test-ak, Signature=") {
+ t.Fatalf("authorization = %q, want HMAC signature", call.authorization)
+ }
+}
+
+// TestCatalogRejectsRemovedPerToolClusterFlag verifies the per-tool --cluster
+// flag is gone: the instance identifier comes exclusively from the global
+// --instance-id flag.
+func TestCatalogRejectsRemovedPerToolClusterFlag(t *testing.T) {
+ _, stderr, exitCode := executeTestApp(t, httptest.NewServer(http.HandlerFunc(
+ func(w http.ResponseWriter, r *http.Request) {
+ writeStudioSuccess(t, w, map[string]any{"items": []any{}})
+ })).Client(), "http://127.0.0.1:1",
"topic", "list", "--cluster", "instance-dev",
)
- if exitCode != 0 {
- t.Fatalf("explicit cluster failed: exit=%d stderr=%s", exitCode, stderr)
+ if exitCode == 0 {
+ t.Fatal("per-tool --cluster flag must no longer exist")
}
- if cluster := (<-observed).Arguments["cluster"]; cluster != "instance-dev" {
- t.Fatalf("cluster = %#v, want explicit value", cluster)
+ if !strings.Contains(stderr, "unknown flag") {
+ t.Fatalf("stderr = %q, want an unknown flag error", stderr)
}
}
@@ -166,7 +283,7 @@ func TestCatalogAllowsL1WithoutYes(t *testing.T) {
defer server.Close()
_, stderr, exitCode := executeTestApp(t, server.Client(), server.URL,
- "topic", "list", "--cluster", "instance-dev",
+ "topic", "list",
)
if exitCode != 0 {
t.Fatalf("L1 without --yes should succeed: exit=%d stderr=%s", exitCode, stderr)
@@ -192,13 +309,13 @@ func TestCatalogInteractiveConfirmAcceptsYes(t *testing.T) {
stdout, stderr, exitCode := executeTestAppWithStdin(t, server.Client(), server.URL, "dev",
"yes\n",
"--output", "json",
- "topic", "create", "--cluster", "instance-dev", "--topic", "orders", "--write-queues", "8",
+ "topic", "update", "--topic-name", "orders", "--write-queues", "8",
"--confirm-token", "confirmation",
)
if exitCode != 0 {
t.Fatalf("interactive yes should proceed: exit=%d stderr=%s", exitCode, stderr)
}
- if call := <-observed; call.Arguments["topic"] != "orders" {
+ if call := <-observed; call.Arguments["topicName"] != "orders" {
t.Fatalf("unexpected request: %#v", call)
}
if !strings.Contains(stderr, "WARNING") || !strings.Contains(stderr, server.URL) ||
diff --git a/rmqctl/cmd/catalog.go b/rmqctl/cmd/catalog.go
index 377c20bc9..c2bcfedf8 100644
--- a/rmqctl/cmd/catalog.go
+++ b/rmqctl/cmd/catalog.go
@@ -22,6 +22,7 @@ import (
"io"
"os"
"strings"
+ "time"
toolcatalog "github.com/apache/rocketmq-dashboard/rmqctl/internal/catalog"
"github.com/apache/rocketmq-dashboard/rmqctl/internal/output"
@@ -93,8 +94,27 @@ func newToolCommand(runtime commandRuntime, tool toolcatalog.Tool) (*cobra.Comma
}
func bindSchemaArguments(cmd *cobra.Command, toolName string, schema toolcatalog.InputSchema) (argumentBinder, error) {
+ return bindSchemaArgumentsAtDepth(cmd, toolName, schema, 0)
+}
+
+// bindSchemaArgumentsAtDepth registers one flag per leaf field. At the top
+// level (depth 0) the instance identifier field (instanceId, or the
+// transitional cluster name in the pre-regeneration catalog) is skipped: its
+// value is supplied exclusively by the global persistent --instance-id flag,
+// which avoids registering a conflicting per-tool flag and keeps a single
+// source of truth for the instance identity.
+func bindSchemaArgumentsAtDepth(cmd *cobra.Command, toolName string, schema toolcatalog.InputSchema, depth int) (argumentBinder, error) {
+ instanceField := ""
+ if depth == 0 {
+ if name, ok := toolcatalog.InstanceFieldName(schema); ok {
+ instanceField = name
+ }
+ }
binder := argumentBinder{bindings: make([]argumentBinding, 0, len(schema.Fields))}
for _, field := range schema.Fields {
+ if field.Name == instanceField {
+ continue
+ }
usage := schemaFlagUsage(field)
binding := argumentBinding{name: field.Name, flag: field.Flag}
switch field.Kind {
@@ -102,7 +122,7 @@ func bindSchemaArguments(cmd *cobra.Command, toolName string, schema toolcatalog
if field.Object == nil {
return argumentBinder{}, fmt.Errorf("missing object schema for field %q in tool %q", field.Name, toolName)
}
- object, err := bindSchemaArguments(cmd, toolName, *field.Object)
+ object, err := bindSchemaArgumentsAtDepth(cmd, toolName, *field.Object, depth+1)
if err != nil {
return argumentBinder{}, err
}
@@ -168,12 +188,16 @@ func runTool(
if err != nil {
return err
}
- if suppliedCluster, supplied := arguments["cluster"]; supplied {
- if err := validateExplicitCluster(suppliedCluster, target.Cluster); err != nil {
- return err
- }
- } else {
- arguments["cluster"] = target.Cluster
+ // Fill client-side defaults (x-client-default: NOW) before required
+ // validation and argument assembly so a schema-required field with a
+ // client default is self-consistent. Explicit flags always win.
+ applyClientDefaults(tool, arguments)
+ // Pass the explicit --instance-id value through to tools whose schema
+ // declares the instance identifier (decision 7: pass-through of the
+ // caller's explicit value, not a default injection). Platform-level
+ // tools have no instance field and only use it for signing/headers.
+ if instanceField, ok := toolcatalog.InstanceFieldName(tool.InputSchema); ok {
+ arguments[instanceField] = target.InstanceID
}
if err := validateSchemaArguments(tool, tool.InputSchema, arguments); err != nil {
return err
@@ -183,6 +207,35 @@ func runTool(
return err
}
+ // L2/L3 mutations require a server-issued confirm_token from a matching
+ // dry-run preview before they execute. When --yes is supplied without an
+ // explicit --confirm-token or --dry-run, transparently run the preview first
+ // to obtain the token so callers need not script the two-phase handshake
+ // manually. L1 tools, explicit dry-runs, and calls that already carry a
+ // confirm_token are left untouched.
+ if tool.RiskLevel != "L1" && runtime.options.yes {
+ if _, hasToken := arguments["confirm_token"]; !hasToken {
+ if dryRun, _ := arguments["dry_run"].(bool); !dryRun {
+ preview := make(map[string]any, len(arguments)+1)
+ for key, value := range arguments {
+ preview[key] = value
+ }
+ preview["dry_run"] = true
+ previewResult, err := runtime.client.CallTool(cmd.Context(), target, tool.Name, preview)
+ if err != nil {
+ return err
+ }
+ mutation, err := types.DecodeMutationOutput(previewResult)
+ if err != nil {
+ return err
+ }
+ if mutation.ConfirmToken != "" {
+ arguments["confirm_token"] = mutation.ConfirmToken
+ }
+ }
+ }
+ }
+
result, err := runtime.client.CallTool(cmd.Context(), target, tool.Name, arguments)
if err != nil {
return err
@@ -197,29 +250,31 @@ func runTool(
return renderTable(out, tool, result)
}
-// validateExplicitCluster rejects a --cluster value that does not match the
-// authenticated context Instance. The server independently enforces the same
-// check, but failing early in the CLI avoids sending credentials to the wrong
-// endpoint and gives the user an actionable message.
-func validateExplicitCluster(supplied any, contextCluster string) error {
- cluster, ok := supplied.(string)
- if !ok || strings.TrimSpace(cluster) == "" {
- return invalidArgument("--cluster must be a non-empty Studio Instance identifier")
- }
- cluster = strings.TrimSpace(cluster)
- if cluster == contextCluster {
- return nil
+// nowMillis returns the current Unix epoch milliseconds. It is a variable so
+// tests can pin the clock when asserting x-client-default: NOW fills.
+var nowMillis = func() int64 { return time.Now().UnixMilli() }
+
+// applyClientDefaults fills top-level fields annotated with the catalog
+// extension x-client-default: NOW when the user did not pass the matching
+// flag. binder.arguments only records flags explicitly set on the command
+// line, so absence from arguments is exactly "not supplied by the user".
+// Filling happens before required validation so required fields with a client
+// default (e.g. group reset-offset --timestamp) validate cleanly. The catalog
+// generator rejects x-client-default on nested properties, so only top-level
+// fields need to be considered.
+func applyClientDefaults(tool toolcatalog.Tool, arguments map[string]any) {
+ for _, field := range tool.InputSchema.Fields {
+ if field.ClientDefault != toolcatalog.ClientDefaultNow {
+ continue
+ }
+ if argumentPresent(arguments, field.Name) {
+ continue
+ }
+ arguments[field.Name] = nowMillis()
}
- return types.NewCLIError(
- types.CodeInvalidArgument,
- fmt.Sprintf("--cluster %q does not match the current context Instance %q", cluster, contextCluster),
- "Switch context with 'config use-context' or omit --cluster to use the current context.")
}
func schemaFlagUsage(field toolcatalog.Field) string {
- if field.Name == "cluster" {
- return "Studio Instance identifier (defaults to the selected context; must identify the same Instance)"
- }
usage := field.Description
if usage == "" {
usage = strings.ReplaceAll(field.Flag, "-", " ")
diff --git a/rmqctl/cmd/catalog_instance_test.go b/rmqctl/cmd/catalog_instance_test.go
new file mode 100644
index 000000000..8fbc3a6ca
--- /dev/null
+++ b/rmqctl/cmd/catalog_instance_test.go
@@ -0,0 +1,211 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package cmd
+
+import (
+ "bytes"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "testing"
+ "time"
+
+ toolcatalog "github.com/apache/rocketmq-dashboard/rmqctl/internal/catalog"
+ "github.com/apache/rocketmq-dashboard/rmqctl/internal/config"
+ "github.com/apache/rocketmq-dashboard/rmqctl/internal/studio"
+ "github.com/apache/rocketmq-dashboard/rmqctl/internal/types"
+ "github.com/spf13/cobra"
+)
+
+// executeSyntheticTool wires a synthetic catalog tool into a root command that
+// mirrors the production global flag set, runs it against a fresh test server,
+// and returns the observed tool call request plus stderr/exit error.
+func executeSyntheticTool(
+ t *testing.T,
+ tool toolcatalog.Tool,
+ args ...string,
+) (types.ToolCallRequest, string, error) {
+ t.Helper()
+ observed := make(chan types.ToolCallRequest, 1)
+ httpServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ var request types.ToolCallRequest
+ if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+ http.Error(w, err.Error(), http.StatusBadRequest)
+ return
+ }
+ if r.Header.Get("x-rmq-instance-id") != "instance-x" {
+ t.Errorf("x-rmq-instance-id = %q, want instance-x", r.Header.Get("x-rmq-instance-id"))
+ }
+ observed <- request
+ writeStudioSuccess(t, w, map[string]any{"items": []any{}})
+ }))
+ defer httpServer.Close()
+
+ opts := &option{output: "json", timeout: time.Second}
+ root := &cobra.Command{Use: "rmqctl", SilenceUsage: true, SilenceErrors: true}
+ root.PersistentFlags().StringVar(&opts.context, "context", "", "")
+ root.PersistentFlags().StringVar(&opts.configPath, "config", "", "")
+ root.PersistentFlags().StringVar(&opts.instanceID, "instance-id", "", "")
+ root.PersistentFlags().DurationVar(&opts.timeout, "timeout", time.Second, "")
+ root.PersistentFlags().BoolVarP(&opts.yes, "yes", "y", false, "")
+
+ configPath := newTestConfigPath(t)
+ store := config.Store{Getenv: testEnv, HomeDir: config.NewStore().HomeDir}
+ if err := store.Save(configPath, newTestConfig(httpServer.URL)); err != nil {
+ t.Fatal(err)
+ }
+ runtime := commandRuntime{
+ client: studio.NewClient(httpServer.Client()),
+ store: store,
+ options: opts,
+ confirm: stubConfirmReject,
+ }
+ toolCmd, err := newToolCommand(runtime, tool)
+ if err != nil {
+ t.Fatal(err)
+ }
+ root.AddCommand(toolCmd)
+ stderr := &bytes.Buffer{}
+ root.SetOut(&bytes.Buffer{})
+ root.SetErr(stderr)
+ root.SetArgs(append([]string{
+ "--config", configPath, "--instance-id", "instance-x",
+ tool.CLI.Verb,
+ }, args...))
+ if err := root.Execute(); err != nil {
+ return types.ToolCallRequest{}, stderr.String(), err
+ }
+ select {
+ case request := <-observed:
+ return request, stderr.String(), nil
+ default:
+ return types.ToolCallRequest{}, stderr.String(), nil
+ }
+}
+
+func syntheticPlatformTool() toolcatalog.Tool {
+ return toolcatalog.Tool{
+ Name: "rmq.synthetic.platform",
+ CLI: toolcatalog.CLI{Resource: "synthetic-platform", Verb: "list"},
+ Description: "Synthetic platform-level tool without an instance field.",
+ RiskLevel: "L1",
+ Permission: "synthetic:read",
+ RequiredCapabilities: []string{},
+ InputSchema: toolcatalog.InputSchema{
+ Fields: []toolcatalog.Field{
+ {Name: "clusterName", Flag: "cluster-name", Kind: toolcatalog.StringField},
+ },
+ },
+ ViewHint: "object",
+ }
+}
+
+func syntheticResetTool() toolcatalog.Tool {
+ return toolcatalog.Tool{
+ Name: "rmq.synthetic.reset",
+ CLI: toolcatalog.CLI{Resource: "synthetic-reset", Verb: "run"},
+ Description: "Synthetic instance-scoped tool with an x-client-default NOW field.",
+ RiskLevel: "L1",
+ Permission: "synthetic:write",
+ RequiredCapabilities: []string{},
+ InputSchema: toolcatalog.InputSchema{
+ Fields: []toolcatalog.Field{
+ {Name: "instanceId", Flag: "instance-id", Kind: toolcatalog.StringField, Required: true, MinLength: 1},
+ {Name: "groupName", Flag: "group-name", Kind: toolcatalog.StringField, Required: true, MinLength: 1},
+ {Name: "timestamp", Flag: "timestamp", Kind: toolcatalog.IntegerField, Required: true, ClientDefault: toolcatalog.ClientDefaultNow},
+ },
+ },
+ ViewHint: "object",
+ }
+}
+
+// TestPlatformLevelToolOmitsInstanceArgument verifies decisions 25/26: for a
+// tool whose schema declares no instance identifier, the explicit
+// --instance-id is used only for HMAC signing and the x-rmq-instance-id
+// header, and is never added to the tool call arguments.
+func TestPlatformLevelToolOmitsInstanceArgument(t *testing.T) {
+ request, stderr, err := executeSyntheticTool(t, syntheticPlatformTool(),
+ "--cluster-name", "physical-cluster")
+ if err != nil {
+ t.Fatalf("platform tool call failed: %v, stderr=%s", err, stderr)
+ }
+ if request.Name != "rmq.synthetic.platform" {
+ t.Fatalf("tool = %q, want the synthetic platform tool", request.Name)
+ }
+ for _, key := range []string{"instanceId", "cluster"} {
+ if value, exists := request.Arguments[key]; exists {
+ t.Fatalf("platform tool arguments must not carry %q, got %#v", key, value)
+ }
+ }
+ if request.Arguments["clusterName"] != "physical-cluster" {
+ t.Fatalf("arguments = %#v, want the explicit clusterName only", request.Arguments)
+ }
+}
+
+// TestClientDefaultNowFillsMissingTimestamp verifies decision 13: a required
+// field annotated with x-client-default: NOW is filled with the current Unix
+// milliseconds before required validation when the user did not pass the flag.
+func TestClientDefaultNowFillsMissingTimestamp(t *testing.T) {
+ const pinnedNow = int64(1757600000000)
+ original := nowMillis
+ nowMillis = func() int64 { return pinnedNow }
+ defer func() { nowMillis = original }()
+
+ request, stderr, err := executeSyntheticTool(t, syntheticResetTool(),
+ "--group-name", "gid-orders")
+ if err != nil {
+ t.Fatalf("reset tool call failed: %v, stderr=%s", err, stderr)
+ }
+ if request.Arguments["instanceId"] != "instance-x" {
+ t.Fatalf("instanceId = %#v, want the explicit --instance-id pass-through", request.Arguments["instanceId"])
+ }
+ // JSON round-trip turns the int64 fill into float64.
+ if timestamp, ok := request.Arguments["timestamp"].(float64); !ok || int64(timestamp) != pinnedNow {
+ t.Fatalf("timestamp = %#v, want the client-default NOW fill %d", request.Arguments["timestamp"], pinnedNow)
+ }
+}
+
+// TestClientDefaultNowKeepsExplicitTimestamp verifies that an explicitly
+// supplied flag value always wins over the client default.
+func TestClientDefaultNowKeepsExplicitTimestamp(t *testing.T) {
+ original := nowMillis
+ nowMillis = func() int64 { return 1 }
+ defer func() { nowMillis = original }()
+
+ request, stderr, err := executeSyntheticTool(t, syntheticResetTool(),
+ "--group-name", "gid-orders", "--timestamp", "42")
+ if err != nil {
+ t.Fatalf("reset tool call failed: %v, stderr=%s", err, stderr)
+ }
+ if timestamp, ok := request.Arguments["timestamp"].(float64); !ok || int64(timestamp) != 42 {
+ t.Fatalf("timestamp = %#v, want the explicit value 42", request.Arguments["timestamp"])
+ }
+}
+
+// TestClientDefaultNowSatisfiesRequiredValidation verifies the fill happens
+// before required validation: a required field with a client default never
+// triggers the "requires --timestamp" INVALID_ARGUMENT error.
+func TestClientDefaultNowSatisfiesRequiredValidation(t *testing.T) {
+ request, stderr, err := executeSyntheticTool(t, syntheticResetTool(),
+ "--group-name", "gid-orders")
+ if err != nil {
+ t.Fatalf("required validation should pass after the NOW fill: %v, stderr=%s", err, stderr)
+ }
+ if _, exists := request.Arguments["timestamp"]; !exists {
+ t.Fatalf("arguments = %#v, want the filled timestamp", request.Arguments)
+ }
+}
diff --git a/rmqctl/cmd/catalog_test.go b/rmqctl/cmd/catalog_test.go
index bf4aa618e..9fc3a7f75 100644
--- a/rmqctl/cmd/catalog_test.go
+++ b/rmqctl/cmd/catalog_test.go
@@ -42,11 +42,27 @@ func TestCatalogRegistersEveryToolAndSchemaFlag(t *testing.T) {
if command.Short != tool.Description {
t.Errorf("tool %q help = %q, want %q", tool.Name, command.Short, tool.Description)
}
- var assertSchemaFlags func(toolcatalog.InputSchema)
- assertSchemaFlags = func(schema toolcatalog.InputSchema) {
+ var assertSchemaFlags func(toolcatalog.InputSchema, int)
+ assertSchemaFlags = func(schema toolcatalog.InputSchema, depth int) {
+ instanceField := ""
+ if depth == 0 {
+ if name, ok := toolcatalog.InstanceFieldName(schema); ok {
+ instanceField = name
+ }
+ }
for _, field := range schema.Fields {
if field.Object != nil {
- assertSchemaFlags(*field.Object)
+ assertSchemaFlags(*field.Object, depth+1)
+ continue
+ }
+ // The instance identifier is fed exclusively by the global
+ // persistent --instance-id flag and must never be registered
+ // as a per-tool flag.
+ if field.Name == instanceField {
+ if flag := command.Flags().Lookup(field.Flag); flag != nil {
+ t.Errorf("tool %q must not register per-tool flag --%s for the instance identifier",
+ tool.Name, field.Flag)
+ }
continue
}
flag := command.Flags().Lookup(field.Flag)
@@ -57,12 +73,12 @@ func TestCatalogRegistersEveryToolAndSchemaFlag(t *testing.T) {
if actual, expected := flag.Value.Type(), cobraFlagType(field.Kind); actual != expected {
t.Errorf("tool %q --%s type = %q, want %q", tool.Name, field.Flag, actual, expected)
}
- if field.Required && field.Name != "cluster" && !strings.Contains(flag.Usage, "(required)") {
+ if field.Required && !strings.Contains(flag.Usage, "(required)") {
t.Errorf("tool %q --%s help does not mark the flag as required", tool.Name, field.Flag)
}
}
}
- assertSchemaFlags(tool.InputSchema)
+ assertSchemaFlags(tool.InputSchema, 0)
}
if command := childCommand(root, "message", "query-by-group"); command != nil {
t.Fatal("removed message query-by-group command is still registered")
diff --git a/rmqctl/cmd/cmd.go b/rmqctl/cmd/cmd.go
index a8da65570..0765e81eb 100644
--- a/rmqctl/cmd/cmd.go
+++ b/rmqctl/cmd/cmd.go
@@ -27,6 +27,7 @@ import (
type option struct {
context string
configPath string
+ instanceID string
output string
timeout time.Duration
yes bool
@@ -44,6 +45,8 @@ func (a *App) newCommand(opts *option) (*cobra.Command, error) {
}
cmd.PersistentFlags().StringVar(&opts.context, "context", "", "config context name")
cmd.PersistentFlags().StringVar(&opts.configPath, "config", "", "config file path")
+ cmd.PersistentFlags().StringVar(&opts.instanceID, "instance-id", "",
+ "Studio Instance identifier for tool calls and request signing (required; never defaulted from the context)")
cmd.PersistentFlags().DurationVar(&opts.timeout, "timeout", studio.DefaultTimeout, "request timeout")
cmd.PersistentFlags().StringVarP(&opts.output, "output", "o", output.FormatTable, "output format: table, json, or yaml")
cmd.PersistentFlags().BoolVarP(&opts.yes, "yes", "y", false, "skip the interactive confirmation prompt for L2/L3 operations")
diff --git a/rmqctl/cmd/config.go b/rmqctl/cmd/config.go
index a184342a4..ab1bf8d0a 100644
--- a/rmqctl/cmd/config.go
+++ b/rmqctl/cmd/config.go
@@ -28,7 +28,6 @@ func newConfigCommand(runtime commandRuntime) *cobra.Command {
func newConfigSetContextCommand(runtime commandRuntime) *cobra.Command {
var server string
- var cluster string
var accessKeyEnv string
var secretKeyEnv string
cmd := &cobra.Command{
@@ -53,9 +52,6 @@ func newConfigSetContextCommand(runtime commandRuntime) *cobra.Command {
if cmd.Flags().Changed("server") {
contextValue.Server = server
}
- if cmd.Flags().Changed("cluster") {
- contextValue.Cluster = cluster
- }
if cmd.Flags().Changed("access-key-env") {
contextValue.Credential.AccessKeyRef = "env:" + accessKeyEnv
}
@@ -75,7 +71,6 @@ func newConfigSetContextCommand(runtime commandRuntime) *cobra.Command {
},
}
cmd.Flags().StringVar(&server, "server", "", "Studio Server URL")
- cmd.Flags().StringVar(&cluster, "cluster", "", "Studio Instance identifier")
cmd.Flags().StringVar(&accessKeyEnv, "access-key-env", "", "environment variable containing the RocketMQ access key")
cmd.Flags().StringVar(&secretKeyEnv, "secret-key-env", "", "environment variable containing the RocketMQ secret key")
return cmd
@@ -186,7 +181,7 @@ func newConfigCurrentContextCommand(runtime commandRuntime) *cobra.Command {
// newContextRequiredFlags lists flags that must all be set when creating a
// brand-new context. Updates to an existing context may set any subset.
var newContextRequiredFlags = []string{
- "server", "cluster", "access-key-env", "secret-key-env",
+ "server", "access-key-env", "secret-key-env",
}
func missingFlags(flags *pflag.FlagSet, required []string) []string {
diff --git a/rmqctl/cmd/config_test.go b/rmqctl/cmd/config_test.go
index b96006e37..155d1f43a 100644
--- a/rmqctl/cmd/config_test.go
+++ b/rmqctl/cmd/config_test.go
@@ -33,7 +33,7 @@ func TestConfigSetContextStoresOnlyEnvironmentReferences(t *testing.T) {
configPath := newTestConfigPath(t)
exitCode := app.Execute([]string{
"--config", configPath, "config", "set-context", "prod",
- "--server", "https://studio.example.com", "--cluster", "instance-prod",
+ "--server", "https://studio.example.com",
"--access-key-env", "RMQ_PROD_AK", "--secret-key-env", "RMQ_PROD_SK",
})
if exitCode != 0 {
@@ -47,6 +47,9 @@ func TestConfigSetContextStoresOnlyEnvironmentReferences(t *testing.T) {
t.Fatal(err)
}
contextValue := cfg.Contexts["prod"]
+ if contextValue.Server != "https://studio.example.com" {
+ t.Fatalf("server = %q, want the configured URL", contextValue.Server)
+ }
if contextValue.Credential.AccessKeyRef != "env:RMQ_PROD_AK" ||
contextValue.Credential.SecretKeyRef != "env:RMQ_PROD_SK" {
t.Fatalf("credential refs = %#v", contextValue.Credential)
@@ -55,11 +58,35 @@ func TestConfigSetContextStoresOnlyEnvironmentReferences(t *testing.T) {
if err != nil {
t.Fatal(err)
}
+ if strings.Contains(string(raw), "cluster") {
+ t.Fatalf("config still stores a cluster key: %s", raw)
+ }
if strings.Contains(string(raw), "token-from-env") || strings.Contains(string(raw), "secret-value") {
t.Fatalf("config contains credential material: %s", raw)
}
}
+// TestConfigSetContextRejectsRemovedClusterFlag verifies the context no longer
+// accepts --cluster: the instance identifier is a per-invocation global flag.
+func TestConfigSetContextRejectsRemovedClusterFlag(t *testing.T) {
+ stdout := &bytes.Buffer{}
+ stderr := &bytes.Buffer{}
+ app := NewApp(stdout, stderr)
+ app.Store.Getenv = emptyEnv
+ configPath := newTestConfigPath(t)
+ exitCode := app.Execute([]string{
+ "--config", configPath, "config", "set-context", "prod",
+ "--server", "https://studio.example.com", "--cluster", "instance-prod",
+ "--access-key-env", "RMQ_PROD_AK", "--secret-key-env", "RMQ_PROD_SK",
+ })
+ if exitCode == 0 {
+ t.Fatal("set-context must reject the removed --cluster flag")
+ }
+ if !strings.Contains(stderr.String(), "unknown flag") {
+ t.Fatalf("stderr = %q, want an unknown flag error", stderr.String())
+ }
+}
+
func TestConfigDeleteContextRemovesContextAndClearsCurrent(t *testing.T) {
stdout := &bytes.Buffer{}
stderr := &bytes.Buffer{}
@@ -70,11 +97,11 @@ func TestConfigDeleteContextRemovesContextAndClearsCurrent(t *testing.T) {
CurrentContext: "prod",
Contexts: map[string]config.Context{
"prod": {
- Server: "https://studio.example.com", Cluster: "instance-prod",
+ Server: "https://studio.example.com",
Credential: config.CredentialRef{AccessKeyRef: "env:RMQ_PROD_AK", SecretKeyRef: "env:RMQ_PROD_SK"},
},
"dev": {
- Server: "https://studio.dev.example.com", Cluster: "instance-dev",
+ Server: "https://studio.dev.example.com",
Credential: config.CredentialRef{AccessKeyRef: "env:RMQ_DEV_AK", SecretKeyRef: "env:RMQ_DEV_SK"},
},
},
@@ -115,11 +142,11 @@ func TestConfigGetContextsListsAllContexts(t *testing.T) {
CurrentContext: "prod",
Contexts: map[string]config.Context{
"prod": {
- Server: "https://studio.example.com", Cluster: "instance-prod",
+ Server: "https://studio.example.com",
Credential: config.CredentialRef{AccessKeyRef: "env:RMQ_PROD_AK", SecretKeyRef: "env:RMQ_PROD_SK"},
},
"dev": {
- Server: "https://studio.dev.example.com", Cluster: "instance-dev",
+ Server: "https://studio.dev.example.com",
Credential: config.CredentialRef{AccessKeyRef: "env:RMQ_DEV_AK", SecretKeyRef: "env:RMQ_DEV_SK"},
},
},
@@ -135,6 +162,9 @@ func TestConfigGetContextsListsAllContexts(t *testing.T) {
if !strings.Contains(output, "prod") || !strings.Contains(output, "dev") {
t.Fatalf("stdout = %q, want both prod and dev contexts listed", output)
}
+ if strings.Contains(output, "CLUSTER") || strings.Contains(output, "instance-prod") {
+ t.Fatalf("stdout = %q, get-contexts must not render a CLUSTER column", output)
+ }
}
func TestConfigCurrentContextJSONOutput(t *testing.T) {
@@ -146,7 +176,7 @@ func TestConfigCurrentContextJSONOutput(t *testing.T) {
if err := app.Store.Save(configPath, config.Config{
CurrentContext: "prod",
Contexts: map[string]config.Context{"prod": {
- Server: "https://studio.example.com", Cluster: "instance-prod",
+ Server: "https://studio.example.com",
Credential: config.CredentialRef{AccessKeyRef: "env:RMQ_PROD_AK", SecretKeyRef: "env:RMQ_PROD_SK"},
}},
}); err != nil {
diff --git a/rmqctl/cmd/error.go b/rmqctl/cmd/error.go
index 5dd6a7f54..9f9821bff 100644
--- a/rmqctl/cmd/error.go
+++ b/rmqctl/cmd/error.go
@@ -129,7 +129,7 @@ func httpErrorDetails(statusCode int) (string, string) {
case 403:
return code, "Check the current credential and required permission."
case 404:
- return code, "Verify the resource name and selected cluster."
+ return code, "Verify the resource name and the --instance-id value."
case 409:
return code, "Refresh the resource state and retry."
case 429:
diff --git a/rmqctl/cmd/explain.go b/rmqctl/cmd/explain.go
index 67877492d..8a2c447ae 100644
--- a/rmqctl/cmd/explain.go
+++ b/rmqctl/cmd/explain.go
@@ -88,14 +88,17 @@ type actionExplanation struct {
}
type fieldExplanation struct {
- Name string `json:"name" yaml:"name"`
- Flag string `json:"flag" yaml:"flag"`
- Type string `json:"type" yaml:"type"`
- Description string `json:"description,omitempty" yaml:"description,omitempty"`
- Required bool `json:"required" yaml:"required"`
- Enum []string `json:"enum,omitempty" yaml:"enum,omitempty"`
- Minimum *float64 `json:"minimum,omitempty" yaml:"minimum,omitempty"`
- MinLength int `json:"minLength,omitempty" yaml:"minLength,omitempty"`
+ Name string `json:"name" yaml:"name"`
+ Flag string `json:"flag" yaml:"flag"`
+ Type string `json:"type" yaml:"type"`
+ Description string `json:"description,omitempty" yaml:"description,omitempty"`
+ Required bool `json:"required" yaml:"required"`
+ // Global marks fields fed by a global persistent flag (--instance-id)
+ // instead of a per-tool flag.
+ Global bool `json:"global,omitempty" yaml:"global,omitempty"`
+ Enum []string `json:"enum,omitempty" yaml:"enum,omitempty"`
+ Minimum *float64 `json:"minimum,omitempty" yaml:"minimum,omitempty"`
+ MinLength int `json:"minLength,omitempty" yaml:"minLength,omitempty"`
}
func explainResource(resource string) (resourceExplanation, error) {
@@ -138,6 +141,7 @@ func explainResource(resource string) (resourceExplanation, error) {
// Explanations list usable flags with their complete JSON property paths.
func explainSchemaFields(schema toolcatalog.InputSchema, prefix string) []fieldExplanation {
fields := make([]fieldExplanation, 0, len(schema.Fields))
+ instanceField, hasInstanceField := toolcatalog.InstanceFieldName(schema)
for _, field := range schema.Fields {
name := prefix + field.Name
if field.Object != nil {
@@ -149,6 +153,12 @@ func explainSchemaFields(schema toolcatalog.InputSchema, prefix string) []fieldE
Description: field.Description, Required: field.Required,
Enum: field.Enum, MinLength: field.MinLength,
}
+ // The instance identifier is fed by the global persistent --instance-id
+ // flag, not by a per-tool flag; keep it visible with the global flag.
+ if prefix == "" && hasInstanceField && field.Name == instanceField {
+ explained.Flag = "--" + toolcatalog.InstanceIDGlobalFlag
+ explained.Global = true
+ }
if field.HasMinimum {
explained.Minimum = new(field.Minimum)
}
@@ -185,7 +195,10 @@ func renderResourceExplanation(out interface{ Write([]byte) (int, error) }, expl
"description": action.Description,
})
for _, field := range action.Fields {
- constraints := make([]string, 0, 3)
+ constraints := make([]string, 0, 4)
+ if field.Global {
+ constraints = append(constraints, "global flag")
+ }
if len(field.Enum) > 0 {
constraints = append(constraints, "enum="+strings.Join(field.Enum, "|"))
}
diff --git a/rmqctl/cmd/explain_test.go b/rmqctl/cmd/explain_test.go
index d776ce3d8..4325053b0 100644
--- a/rmqctl/cmd/explain_test.go
+++ b/rmqctl/cmd/explain_test.go
@@ -59,3 +59,39 @@ func TestExplainResourceJSONComesFromCatalog(t *testing.T) {
}
}
}
+
+// TestExplainMarksInstanceFieldGlobal verifies that the instance identifier
+// field stays visible in explain output even though it is no longer a per-tool
+// flag: it must be presented as the global --instance-id flag.
+func TestExplainMarksInstanceFieldGlobal(t *testing.T) {
+ stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+ exitCode := NewApp(stdout, stderr).Execute([]string{"--output", "json", "explain", "topic"})
+ if exitCode != 0 {
+ t.Fatalf("explain failed: %s", stderr)
+ }
+ var explanation resourceExplanation
+ if err := json.Unmarshal(stdout.Bytes(), &explanation); err != nil {
+ t.Fatalf("decode output: %v", err)
+ }
+ if len(explanation.Actions) == 0 {
+ t.Fatal("no actions explained")
+ }
+ for _, action := range explanation.Actions {
+ var found *fieldExplanation
+ for index := range action.Fields {
+ if action.Fields[index].Global {
+ found = &action.Fields[index]
+ break
+ }
+ }
+ if found == nil {
+ t.Fatalf("action %q does not mark the instance identifier field as global: %#v", action.Verb, action.Fields)
+ }
+ if found.Flag != "--instance-id" {
+ t.Fatalf("action %q instance field flag = %q, want --instance-id", action.Verb, found.Flag)
+ }
+ if !found.Required {
+ t.Fatalf("action %q instance field must stay required", action.Verb)
+ }
+ }
+}
diff --git a/rmqctl/cmd/mcp.go b/rmqctl/cmd/mcp.go
index 920f41b4c..edaf7e8d8 100644
--- a/rmqctl/cmd/mcp.go
+++ b/rmqctl/cmd/mcp.go
@@ -70,6 +70,9 @@ func (a *App) newMCPConfigCommand(runtime commandRuntime) *cobra.Command {
if runtime.options.context != "" {
stdioArgs = append(stdioArgs, "--context", runtime.options.context)
}
+ if runtime.options.instanceID != "" {
+ stdioArgs = append(stdioArgs, "--instance-id", runtime.options.instanceID)
+ }
if runtime.options.timeout != studio.DefaultTimeout {
stdioArgs = append(stdioArgs, "--timeout", runtime.options.timeout.String())
}
diff --git a/rmqctl/cmd/mcp_stdio_test.go b/rmqctl/cmd/mcp_stdio_test.go
index 29fd4ce8e..6f890901a 100644
--- a/rmqctl/cmd/mcp_stdio_test.go
+++ b/rmqctl/cmd/mcp_stdio_test.go
@@ -47,4 +47,32 @@ func TestMCPConfigEmitsOnlyContextAndConfigReferences(t *testing.T) {
strings.Contains(output, "--cluster") || strings.Contains(output, "--server") {
t.Fatalf("config leaked or duplicated context fields: %s", output)
}
+ if strings.Contains(output, "--instance-id") {
+ t.Fatalf("config must not invent --instance-id when it is unset: %s", output)
+ }
+}
+
+// TestMCPConfigCarriesExplicitInstanceID verifies that an explicitly set
+// --instance-id is forwarded into the generated MCP client snippet, since
+// mcp stdio requires it for request signing and the x-rmq-instance-id header.
+func TestMCPConfigCarriesExplicitInstanceID(t *testing.T) {
+ app := &App{}
+ runtime := commandRuntime{options: &option{
+ context: "prod", configPath: "/tmp/rmqctl.yaml", instanceID: "instance-prod",
+ output: "table", timeout: studio.DefaultTimeout,
+ }}
+ cmd := app.newMCPConfigCommand(runtime)
+ stdout := &bytes.Buffer{}
+ cmd.SetOut(stdout)
+ cmd.SetArgs([]string{})
+
+ if err := cmd.Execute(); err != nil {
+ t.Fatal(err)
+ }
+ output := stdout.String()
+ for _, want := range []string{`"--instance-id"`, `"instance-prod"`} {
+ if !strings.Contains(output, want) {
+ t.Fatalf("config missing %s: %s", want, output)
+ }
+ }
}
diff --git a/rmqctl/cmd/runtime.go b/rmqctl/cmd/runtime.go
index 241c10a61..2d65cee43 100644
--- a/rmqctl/cmd/runtime.go
+++ b/rmqctl/cmd/runtime.go
@@ -17,6 +17,8 @@
package cmd
import (
+ "strings"
+
"github.com/apache/rocketmq-dashboard/rmqctl/internal/config"
"github.com/apache/rocketmq-dashboard/rmqctl/internal/studio"
"github.com/apache/rocketmq-dashboard/rmqctl/internal/types"
@@ -30,6 +32,16 @@ type commandRuntime struct {
}
func (r commandRuntime) resolveTarget() (studio.Target, error) {
+ // The instance identifier must be supplied explicitly on every invocation
+ // (decision 7: no default injection from the context or any other config).
+ instanceID := strings.TrimSpace(r.options.instanceID)
+ if instanceID == "" {
+ return studio.Target{}, types.NewCLIError(
+ types.CodeInvalidArgument,
+ "--instance-id is required",
+ "Pass the Studio Instance identifier explicitly, e.g. --instance-id my-instance; "+
+ "rmqctl never defaults it from the context.")
+ }
cfg, err := r.loadConfig()
if err != nil {
return studio.Target{}, err
@@ -48,7 +60,7 @@ func (r commandRuntime) resolveTarget() (studio.Target, error) {
}
return studio.Target{
Server: contextConfig.Server,
- Cluster: contextConfig.Cluster,
+ InstanceID: instanceID,
Credential: studio.Credential{AccessKey: credential.AccessKey, SecretKey: credential.SecretKey},
Timeout: r.options.timeout,
}, nil
diff --git a/rmqctl/cmd/testhelpers_test.go b/rmqctl/cmd/testhelpers_test.go
index bb8e72896..2631529d7 100644
--- a/rmqctl/cmd/testhelpers_test.go
+++ b/rmqctl/cmd/testhelpers_test.go
@@ -71,14 +71,16 @@ func testEnv(name string) string {
// used by config tests that do not need credential resolution.
func emptyEnv(string) string { return "" }
-// newTestConfig builds a single-context config.Config pointing at serverURL
-// with the given instance suffix. The context uses env: credential references that
-// testEnv can resolve.
-func newTestConfig(serverURL, instanceSuffix string) config.Config {
+// newTestConfig builds a single-context config.Config pointing at serverURL.
+// Contexts no longer store a cluster/instance identifier (decision 7); the
+// instance is supplied via the global --instance-id flag that
+// executeTestAppWithInstance prepends to the command arguments. The context
+// uses env: credential references that testEnv can resolve.
+func newTestConfig(serverURL string) config.Config {
return config.Config{
CurrentContext: "test",
Contexts: map[string]config.Context{"test": {
- Server: serverURL, Cluster: "instance-" + instanceSuffix,
+ Server: serverURL,
Credential: config.CredentialRef{
AccessKeyRef: "env:RMQ_TEST_AK", SecretKeyRef: "env:RMQ_TEST_SK",
},
@@ -112,10 +114,12 @@ func executeTestAppWithInstance(t *testing.T, client *http.Client, serverURL, in
app.Store.Getenv = testEnv
app.confirm = stubConfirmReject
configPath := newTestConfigPath(t)
- if err := app.Store.Save(configPath, newTestConfig(serverURL, instanceSuffix)); err != nil {
+ if err := app.Store.Save(configPath, newTestConfig(serverURL)); err != nil {
t.Fatal(err)
}
- arguments = append([]string{"--config", configPath}, arguments...)
+ arguments = append([]string{
+ "--config", configPath, "--instance-id", "instance-" + instanceSuffix,
+ }, arguments...)
exitCode := app.Execute(arguments)
return stdout.String(), stderr.String(), exitCode
}
@@ -147,11 +151,13 @@ func executeTestAppWithStdin(t *testing.T, client *http.Client, serverURL, insta
return nil
}
configPath := newTestConfigPath(t)
- if err := app.Store.Save(configPath, newTestConfig(serverURL, instanceSuffix)); err != nil {
+ if err := app.Store.Save(configPath, newTestConfig(serverURL)); err != nil {
t.Fatal(err)
}
app.In = strings.NewReader(stdinContent)
- arguments = append([]string{"--config", configPath}, arguments...)
+ arguments = append([]string{
+ "--config", configPath, "--instance-id", "instance-" + instanceSuffix,
+ }, arguments...)
exitCode := app.Execute(arguments)
return stdout.String(), stderr.String(), exitCode
}
diff --git a/rmqctl/internal/catalog/catalog.go b/rmqctl/internal/catalog/catalog.go
index 4e5f7b25f..ff42ab2ce 100644
--- a/rmqctl/internal/catalog/catalog.go
+++ b/rmqctl/internal/catalog/catalog.go
@@ -29,6 +29,43 @@ const (
ObjectField FieldKind = "object"
)
+// ClientDefaultNow marks a field whose value rmqctl fills with the current
+// Unix epoch milliseconds when the user did not pass the corresponding flag
+// (catalog extension key x-client-default: NOW). The fill happens before
+// required validation so a schema-required field with a client default is
+// self-consistent.
+const ClientDefaultNow = "NOW"
+
+// InstanceIDGlobalFlag is the global CLI flag that supplies the Studio
+// Instance identifier. The catalog field it feeds is never registered as a
+// per-tool flag; see InstanceFieldName.
+const InstanceIDGlobalFlag = "instance-id"
+
+// platformToolNames lists the platform-level tools whose input schemas do not
+// declare an instance identifier (design decisions 25/26). rmqctl still signs
+// requests and sends the x-rmq-instance-id header for them, but the explicit
+// --instance-id value is not added to their tool call arguments.
+var platformToolNames = map[string]struct{}{
+ "rmq.cluster.list": {},
+ "rmq.dashboard.summary": {},
+ "rmq.audit.list": {},
+ "rmq.alert.rule.list": {},
+ "rmq.nameserver.list": {},
+ "rmq.nameserver.config": {},
+ "rmq.broker.list": {},
+ "rmq.broker.describe": {},
+ "rmq.broker.config": {},
+ "rmq.proxy.list": {},
+ "rmq.proxy.config": {},
+}
+
+// IsPlatformTool reports whether the named tool is exempt from carrying an
+// instanceId argument.
+func IsPlatformTool(name string) bool {
+ _, ok := platformToolNames[name]
+ return ok
+}
+
type Document struct {
Version string
MinimumClientVersion string
@@ -74,6 +111,10 @@ type Field struct {
Minimum float64
HasMinimum bool
MinLength int
+ // ClientDefault records the x-client-default catalog extension. The only
+ // supported value today is ClientDefaultNow ("NOW"): rmqctl fills the
+ // current Unix epoch milliseconds when the user did not pass the flag.
+ ClientDefault string
// Object retains the JSON nesting; only its leaf fields have CLI flags.
Object *InputSchema
}
@@ -88,6 +129,26 @@ func Default() Document {
return defaultDocument
}
+// LookupTool returns the catalog tool registered under the given MCP tool name.
+func LookupTool(name string) (Tool, bool) {
+ for _, tool := range defaultDocument.Tools {
+ if tool.Name == name {
+ return tool, true
+ }
+ }
+ return Tool{}, false
+}
+
+// InstanceFieldName returns the top-level input property that carries the
+// Studio instance identifier, which rmqctl feeds from the global --instance-id
+// flag instead of a per-tool flag. The canonical property name is instanceId.
+func InstanceFieldName(schema InputSchema) (string, bool) {
+ if field, ok := schema.Field("instanceId"); ok && field.Kind == StringField {
+ return "instanceId", true
+ }
+ return "", false
+}
+
func (tool Tool) CommandPath() string {
return tool.CLI.Resource + " " + tool.CLI.Verb
}
diff --git a/rmqctl/internal/catalog/catalog_gen.go b/rmqctl/internal/catalog/catalog_gen.go
index 5e4c8c8c5..0a1531098 100644
--- a/rmqctl/internal/catalog/catalog_gen.go
+++ b/rmqctl/internal/catalog/catalog_gen.go
@@ -21,76 +21,70 @@ package catalog
var defaultDocument = Document{
Version: "2.0.0",
MinimumClientVersion: "2.0.0",
- Digest: "bf09bfadf589d34b0638f012e9f1b7d3300d10372bb73b7ccb07762c99876295",
+ Digest: "bc0da0891d07f943db08439900892d21984c27d873f00bee3cc2923a35a3dd8f",
Tools: []Tool{
{
- Name: "rmq.acl.create",
- CLI: CLI{Resource: "acl", Verb: "create"},
- Description: "Create a RocketMQ ACL rule for a principal on a resource.",
- RiskLevel: "L2",
- Permission: "acl:write",
+ Name: "rmq.acl.list",
+ CLI: CLI{Resource: "acl", Verb: "list"},
+ Description: "List RocketMQ ACL rules in one Studio Instance with optional filters.",
+ RiskLevel: "L1",
+ Permission: "acl:read",
RequiredCapabilities: []string{"ACL_MANAGEMENT"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "principal", Flag: "principal", Kind: StringField, Required: true, MinLength: 1},
- {Name: "resource", Flag: "resource", Kind: StringField, Required: true, MinLength: 1},
- {Name: "resourceType", Flag: "resource-type", Kind: StringField},
- {Name: "resourcePattern", Flag: "resource-pattern", Kind: StringField},
- {Name: "actions", Flag: "actions", Kind: StringSliceField},
- {Name: "decision", Flag: "decision", Kind: StringField},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "principal", Flag: "principal", Kind: StringField},
+ {Name: "resource", Flag: "resource", Kind: StringField},
{Name: "scope", Flag: "scope", Kind: StringField},
- {Name: "aclVersion", Flag: "acl-version", Kind: StringField},
- {Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
- {Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
+ {Name: "decision", Flag: "decision", Kind: StringField},
+ {Name: "page", Kind: ObjectField, Object: &InputSchema{
+ Fields: []Field{
+ {Name: "page", Flag: "page", Kind: IntegerField, Minimum: 1, HasMinimum: true},
+ {Name: "pageSize", Flag: "page-size", Kind: IntegerField, Minimum: 1, HasMinimum: true},
+ },
+ }},
},
},
- ViewHint: "object",
+ ViewHint: "table",
+ TableDataKey: "items",
},
{
- Name: "rmq.acl.delete",
- CLI: CLI{Resource: "acl", Verb: "delete"},
- Description: "Delete a RocketMQ ACL rule by id.",
- RiskLevel: "L3",
- Permission: "acl:delete",
+ Name: "rmq.acl.get",
+ CLI: CLI{Resource: "acl", Verb: "get"},
+ Description: "Get one RocketMQ ACL rule by id.",
+ RiskLevel: "L1",
+ Permission: "acl:read",
RequiredCapabilities: []string{"ACL_MANAGEMENT"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
{Name: "id", Flag: "id", Kind: StringField, Required: true, MinLength: 1},
- {Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
- {Name: "break_glass", Flag: "break-glass", Kind: BooleanField},
- {Name: "reason", Flag: "reason", Kind: StringField, MinLength: 1},
- {Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
},
},
ViewHint: "object",
},
{
- Name: "rmq.acl.list",
- CLI: CLI{Resource: "acl", Verb: "list"},
- Description: "List RocketMQ ACL rules in one Studio cluster with optional filters.",
- RiskLevel: "L1",
- Permission: "acl:read",
- RequiredCapabilities: []string{"ACL_MANAGEMENT"},
+ Name: "rmq.acl.create",
+ CLI: CLI{Resource: "acl", Verb: "create"},
+ Description: "Create a RocketMQ ACL rule for a principal on a resource.",
+ RiskLevel: "L2",
+ Permission: "acl:write",
+ RequiredCapabilities: []string{"ACL_MANAGEMENT", "REMOTING"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "principal", Flag: "principal", Kind: StringField},
- {Name: "resource", Flag: "resource", Kind: StringField},
- {Name: "scope", Flag: "scope", Kind: StringField},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "principal", Flag: "principal", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "resource", Flag: "resource", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "resourceType", Flag: "resource-type", Kind: StringField},
+ {Name: "resourcePattern", Flag: "resource-pattern", Kind: StringField},
+ {Name: "actions", Flag: "actions", Kind: StringSliceField},
{Name: "decision", Flag: "decision", Kind: StringField},
- {Name: "aclVersion", Flag: "acl-version", Kind: StringField},
- {Name: "page", Kind: ObjectField, Object: &InputSchema{
- Fields: []Field{
- {Name: "page", Flag: "page", Kind: IntegerField, Minimum: 1, HasMinimum: true},
- {Name: "pageSize", Flag: "page-size", Kind: IntegerField, Minimum: 1, HasMinimum: true},
- },
- }},
+ {Name: "scope", Flag: "scope", Kind: StringField},
+ {Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
+ {Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
},
},
- ViewHint: "table",
- TableDataKey: "items",
+ ViewHint: "object",
},
{
Name: "rmq.acl.update",
@@ -98,10 +92,10 @@ var defaultDocument = Document{
Description: "Update an existing RocketMQ ACL rule by id.",
RiskLevel: "L2",
Permission: "acl:write",
- RequiredCapabilities: []string{"ACL_MANAGEMENT"},
+ RequiredCapabilities: []string{"ACL_MANAGEMENT", "REMOTING"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
{Name: "id", Flag: "id", Kind: StringField, Required: true, MinLength: 1},
{Name: "principal", Flag: "principal", Kind: StringField},
{Name: "resource", Flag: "resource", Kind: StringField},
@@ -110,9 +104,27 @@ var defaultDocument = Document{
{Name: "actions", Flag: "actions", Kind: StringSliceField},
{Name: "decision", Flag: "decision", Kind: StringField},
{Name: "scope", Flag: "scope", Kind: StringField},
- {Name: "aclVersion", Flag: "acl-version", Kind: StringField},
+ {Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
{Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
+ },
+ },
+ ViewHint: "object",
+ },
+ {
+ Name: "rmq.acl.delete",
+ CLI: CLI{Resource: "acl", Verb: "delete"},
+ Description: "Delete a RocketMQ ACL rule by id.",
+ RiskLevel: "L3",
+ Permission: "acl:delete",
+ RequiredCapabilities: []string{"ACL_MANAGEMENT", "REMOTING"},
+ InputSchema: InputSchema{
+ Fields: []Field{
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "id", Flag: "id", Kind: StringField, Required: true, MinLength: 1},
{Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
+ {Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
+ {Name: "break_glass", Flag: "break-glass", Kind: BooleanField},
+ {Name: "reason", Flag: "reason", Kind: StringField, MinLength: 1},
},
},
ViewHint: "object",
@@ -120,13 +132,12 @@ var defaultDocument = Document{
{
Name: "rmq.alert.rule.list",
CLI: CLI{Resource: "alert-rule", Verb: "list"},
- Description: "List alert rules explicitly bound to the selected Studio Instance; global and other Instance rules are excluded.",
+ Description: "List alert rules across the whole Studio deployment (platform-level, including global rules and rules bound to any Instance).",
RiskLevel: "L1",
Permission: "alert:read",
RequiredCapabilities: []string{},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
{Name: "search", Flag: "search", Kind: StringField, MinLength: 1},
{Name: "enabled", Flag: "enabled", Kind: BooleanField},
},
@@ -137,13 +148,12 @@ var defaultDocument = Document{
{
Name: "rmq.audit.list",
CLI: CLI{Resource: "audit", Verb: "list"},
- Description: "Query audit entries explicitly attributed to the selected Instance; historical unassigned entries are excluded.",
+ Description: "Query audit entries across the whole Studio deployment (platform-level, spanning all Instances).",
RiskLevel: "L1",
Permission: "audit:read",
RequiredCapabilities: []string{},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
{Name: "search", Flag: "search", Kind: StringField},
{Name: "operationType", Flag: "operation-type", Kind: StringField},
{Name: "resourceType", Flag: "resource-type", Kind: StringField},
@@ -161,138 +171,50 @@ var defaultDocument = Document{
ViewHint: "table",
TableDataKey: "items",
},
- {
- Name: "rmq.broker.config",
- CLI: CLI{Resource: "broker-config", Verb: "diff"},
- Description: "Compare configuration across master Brokers in one resolved physical Broker cluster.",
- RiskLevel: "L1",
- Permission: "broker:read",
- RequiredCapabilities: []string{"BROKER_ADMIN"},
- InputSchema: InputSchema{
- Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- },
- },
- ViewHint: "object",
- },
- {
- Name: "rmq.broker.config_update",
- CLI: CLI{Resource: "broker-config", Verb: "update"},
- Description: "Update broker configuration for all brokers in one cluster.",
- RiskLevel: "L3",
- Permission: "broker:write",
- RequiredCapabilities: []string{"BROKER_ADMIN"},
- InputSchema: InputSchema{
- Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "flushDiskType", Flag: "flush-disk-type", Kind: StringField},
- {Name: "autoCreateTopicEnable", Flag: "auto-create-topic-enable", Kind: BooleanField},
- {Name: "autoCreateSubscriptionGroup", Flag: "auto-create-subscription-group", Kind: BooleanField},
- {Name: "maxMessageSize", Flag: "max-message-size", Kind: IntegerField},
- {Name: "fileReservedTime", Flag: "file-reserved-time", Kind: IntegerField},
- {Name: "writeQueueNums", Flag: "write-queue-nums", Kind: IntegerField},
- {Name: "readQueueNums", Flag: "read-queue-nums", Kind: IntegerField},
- {Name: "brokerPermission", Flag: "broker-permission", Kind: IntegerField},
- {Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
- {Name: "break_glass", Flag: "break-glass", Kind: BooleanField},
- {Name: "reason", Flag: "reason", Kind: StringField, MinLength: 1},
- {Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
- },
- },
- ViewHint: "object",
- },
- {
- Name: "rmq.broker.describe",
- CLI: CLI{Resource: "broker", Verb: "describe"},
- Description: "Describe the Broker replica group identified by brokerName within the Instance; read its master or lowest available brokerId.",
- RiskLevel: "L1",
- Permission: "broker:read",
- RequiredCapabilities: []string{"BROKER_ADMIN"},
- InputSchema: InputSchema{
- Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "broker", Flag: "broker", Kind: StringField, Required: true, MinLength: 1},
- },
- },
- ViewHint: "table",
- TableDataKey: "items",
- },
{
Name: "rmq.broker.list",
CLI: CLI{Resource: "broker", Verb: "list"},
- Description: "List Broker replica groups across the selected Instance, including each physical Broker cluster name.",
+ Description: "List Broker replica groups across Studio, optionally filtered by physical cluster name.",
RiskLevel: "L1",
Permission: "broker:read",
RequiredCapabilities: []string{"BROKER_ADMIN"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "clusterName", Flag: "cluster-name", Description: "Physical RocketMQ cluster name.", Kind: StringField, MinLength: 1},
},
},
ViewHint: "table",
TableDataKey: "items",
},
{
- Name: "rmq.broker.runtime_info",
- CLI: CLI{Resource: "broker", Verb: "runtime-info"},
- Description: "Read Broker runtime information across the selected Instance.",
+ Name: "rmq.broker.describe",
+ CLI: CLI{Resource: "broker", Verb: "describe"},
+ Description: "Describe one Broker replica group within a physical cluster, addressed by the clusterName + brokerName pair; merges the replica-group detail with its runtime statistics.",
RiskLevel: "L1",
Permission: "broker:read",
RequiredCapabilities: []string{"BROKER_ADMIN"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "clusterName", Flag: "cluster-name", Description: "Physical RocketMQ cluster name.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "brokerName", Flag: "broker-name", Kind: StringField, Required: true, MinLength: 1},
},
},
ViewHint: "object",
},
{
- Name: "rmq.capabilities",
- CLI: CLI{Resource: "cluster", Verb: "capabilities"},
- Description: "Return the selected cluster's capabilities to determine which tool requirements it satisfies.",
+ Name: "rmq.broker.config",
+ CLI: CLI{Resource: "broker", Verb: "config"},
+ Description: "Read and compare configuration across master Brokers in one resolved physical Broker cluster (read-only; configuration updates are not supported).",
RiskLevel: "L1",
- Permission: "cluster:read",
- RequiredCapabilities: []string{},
+ Permission: "broker:read",
+ RequiredCapabilities: []string{"BROKER_ADMIN"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "clusterName", Flag: "cluster-name", Description: "Physical RocketMQ cluster name.", Kind: StringField, Required: true, MinLength: 1},
},
},
ViewHint: "object",
},
- {
- Name: "rmq.client.describe",
- CLI: CLI{Resource: "client", Verb: "describe"},
- Description: "Describe one RocketMQ client connection by clientId in one cluster.",
- RiskLevel: "L1",
- Permission: "client:read",
- RequiredCapabilities: []string{"REMOTING"},
- InputSchema: InputSchema{
- Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "clientId", Flag: "client-id", Kind: StringField, Required: true, MinLength: 1},
- {Name: "type", Flag: "type", Kind: StringField},
- },
- },
- ViewHint: "table",
- TableDataKey: "items",
- },
- {
- Name: "rmq.client.list",
- CLI: CLI{Resource: "client", Verb: "list"},
- Description: "List RocketMQ client connections in one Studio cluster.",
- RiskLevel: "L1",
- Permission: "client:read",
- RequiredCapabilities: []string{"REMOTING"},
- InputSchema: InputSchema{
- Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "type", Flag: "type", Kind: StringField},
- },
- },
- ViewHint: "table",
- TableDataKey: "items",
- },
{
Name: "rmq.cluster.list",
CLI: CLI{Resource: "cluster", Verb: "list"},
@@ -302,7 +224,6 @@ var defaultDocument = Document{
RequiredCapabilities: []string{"CLUSTER_TOPOLOGY"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
{Name: "status", Flag: "status", Kind: StringField, MinLength: 1},
},
},
@@ -312,210 +233,85 @@ var defaultDocument = Document{
{
Name: "rmq.dashboard.summary",
CLI: CLI{Resource: "dashboard", Verb: "summary"},
- Description: "Summarize the selected Instance, including all its physical Broker cluster overviews.",
+ Description: "Summarize the whole Studio deployment (platform-level, aggregated across Instances), including all physical Broker cluster overviews.",
RiskLevel: "L1",
Permission: "dashboard:read",
RequiredCapabilities: []string{"CLUSTER_TOPOLOGY"},
- InputSchema: InputSchema{
- Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- },
- },
- ViewHint: "object",
- },
- {
- Name: "rmq.dlq.list",
- CLI: CLI{Resource: "dlq", Verb: "list"},
- Description: "List dead-letter groups or dead-letter messages for a group in one cluster.",
- RiskLevel: "L1",
- Permission: "dlq:read",
- RequiredCapabilities: []string{"DLQ_MANAGEMENT"},
- InputSchema: InputSchema{
- Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "group", Flag: "group", Kind: StringField},
- {Name: "search", Flag: "search", Kind: StringField},
- {Name: "time", Kind: ObjectField, Object: &InputSchema{
- Fields: []Field{
- {Name: "startTime", Flag: "start-time", Kind: IntegerField},
- {Name: "endTime", Flag: "end-time", Kind: IntegerField},
- },
- }},
- {Name: "page", Kind: ObjectField, Object: &InputSchema{
- Fields: []Field{
- {Name: "page", Flag: "page", Kind: IntegerField, Minimum: 1, HasMinimum: true},
- {Name: "pageSize", Flag: "page-size", Kind: IntegerField, Minimum: 1, HasMinimum: true},
- },
- }},
- },
- },
- ViewHint: "table",
- TableDataKey: "items",
- },
- {
- Name: "rmq.dlq.resend",
- CLI: CLI{Resource: "dlq", Verb: "resend"},
- Description: "Resend dead-letter messages for a consumer group back to the target topic.",
- RiskLevel: "L2",
- Permission: "dlq:write",
- RequiredCapabilities: []string{"DLQ_MANAGEMENT"},
- InputSchema: InputSchema{
- Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "group", Flag: "group", Kind: StringField, Required: true, MinLength: 1},
- {Name: "time", Kind: ObjectField, Object: &InputSchema{
- Fields: []Field{
- {Name: "startTime", Flag: "start-time", Kind: IntegerField},
- {Name: "endTime", Flag: "end-time", Kind: IntegerField},
- },
- }},
- {Name: "targetTopic", Flag: "target-topic", Kind: StringField},
- {Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
- {Name: "break_glass", Flag: "break-glass", Kind: BooleanField},
- {Name: "reason", Flag: "reason", Kind: StringField, MinLength: 1},
- {Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
- },
- },
- ViewHint: "object",
- },
- {
- Name: "rmq.dlq.clear",
- CLI: CLI{Resource: "dlq", Verb: "clear"},
- Description: "Permanently delete the dead-letter topic for a consumer group.",
- RiskLevel: "L3",
- Permission: "dlq:write",
- RequiredCapabilities: []string{"REMOTING"},
- InputSchema: InputSchema{
- Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "group", Flag: "group", Kind: StringField, Required: true, MinLength: 1},
- {Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
- {Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
- {Name: "break_glass", Flag: "break-glass", Kind: BooleanField},
- {Name: "reason", Flag: "reason", Kind: StringField, MinLength: 1},
- },
- },
- ViewHint: "object",
+ InputSchema: InputSchema{},
+ ViewHint: "object",
},
{
Name: "rmq.group.list",
CLI: CLI{Resource: "group", Verb: "list"},
- Description: "List RocketMQ consumer groups in one Studio cluster.",
+ Description: "List RocketMQ consumer groups in one Studio Instance.",
RiskLevel: "L1",
Permission: "group:read",
RequiredCapabilities: []string{"CONSUMER_GROUP_MANAGEMENT"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "search", Flag: "search", Kind: StringField, MinLength: 1},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "groupName", Flag: "group-name", Description: "Fuzzy consumer group name filter.", Kind: StringField, MinLength: 1},
},
},
ViewHint: "table",
TableDataKey: "items",
},
{
- Name: "rmq.group.describe",
- CLI: CLI{Resource: "group", Verb: "describe"},
- Description: "Describe one RocketMQ consumer group, including subscription summary and health.",
+ Name: "rmq.group.detail",
+ CLI: CLI{Resource: "group", Verb: "detail"},
+ Description: "Show full detail of one RocketMQ consumer group: configurations, health, subscriptions, client instances, queue-level consume progress and online clients. The optional topicName filters the progress and clients blocks; both blocks stay empty (without failing the call) when no consumer is online.",
RiskLevel: "L1",
Permission: "group:read",
RequiredCapabilities: []string{"CONSUMER_GROUP_MANAGEMENT"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "group", Flag: "group", Kind: StringField, Required: true, MinLength: 1},
- {Name: "namespace", Flag: "namespace", Kind: StringField, MinLength: 1},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "groupName", Flag: "group-name", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "topicName", Flag: "topic-name", Description: "Filter the progress and clients blocks by topic name.", Kind: StringField, MinLength: 1},
},
},
ViewHint: "object",
},
{
- Name: "rmq.group.consume_progress",
- CLI: CLI{Resource: "group", Verb: "consume-progress"},
- Description: "Get queue-level consume progress and backlog for one RocketMQ consumer group, optionally filtered by topic.",
- RiskLevel: "L1",
- Permission: "group:read",
- RequiredCapabilities: []string{"CONSUMER_GROUP_MANAGEMENT"},
- InputSchema: InputSchema{
- Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "group", Flag: "group", Kind: StringField, Required: true, MinLength: 1},
- {Name: "topic", Flag: "topic", Kind: StringField, MinLength: 1},
- },
- },
- ViewHint: "table",
- TableDataKey: "queues",
- },
- {
- Name: "rmq.group.clients",
- CLI: CLI{Resource: "group", Verb: "clients"},
- Description: "List online consumer clients for one RocketMQ consumer group.",
- RiskLevel: "L1",
- Permission: "group:read",
- RequiredCapabilities: []string{"CONSUMER_GROUP_MANAGEMENT"},
- InputSchema: InputSchema{
- Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "group", Flag: "group", Kind: StringField, Required: true, MinLength: 1},
- {Name: "topic", Flag: "topic", Kind: StringField, MinLength: 1},
- },
- },
- ViewHint: "table",
- TableDataKey: "clients",
- },
- {
- Name: "rmq.group.create",
- CLI: CLI{Resource: "group", Verb: "create"},
- Description: "Create a RocketMQ consumer group.",
+ Name: "rmq.group.update",
+ CLI: CLI{Resource: "group", Verb: "update"},
+ Description: "Update a RocketMQ consumer group.",
RiskLevel: "L2",
Permission: "group:write",
RequiredCapabilities: []string{"CONSUMER_GROUP_MANAGEMENT"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "group", Flag: "group", Kind: StringField, Required: true, MinLength: 1},
- {Name: "namespace", Flag: "namespace", Kind: StringField, MinLength: 1},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "groupName", Flag: "group-name", Kind: StringField, Required: true, MinLength: 1},
{Name: "subscriptionMode", Flag: "subscription-mode", Kind: StringField, Enum: []string{"Push", "Pop"}},
{Name: "consumeType", Flag: "consume-type", Kind: StringField, Enum: []string{"CLUSTERING", "BROADCASTING"}},
{Name: "subscriptionDataType", Flag: "subscription-data-type", Kind: StringField, MinLength: 1},
{Name: "deliveryOrderType", Flag: "delivery-order-type", Kind: StringField, MinLength: 1},
{Name: "retryMaxTimes", Flag: "retry-max-times", Kind: IntegerField, Minimum: 0, HasMinimum: true},
{Name: "delaySeconds", Flag: "delay-seconds", Kind: IntegerField, Minimum: 0, HasMinimum: true},
- {Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
{Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
+ {Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
},
},
ViewHint: "object",
},
{
- Name: "rmq.group.update",
- CLI: CLI{Resource: "group", Verb: "update"},
- Description: "Update a RocketMQ consumer group.",
+ Name: "rmq.group.reset_offset",
+ CLI: CLI{Resource: "group", Verb: "reset-offset"},
+ Description: "Reset consumer offset for a group on a topic to a timestamp.",
RiskLevel: "L2",
Permission: "group:write",
- RequiredCapabilities: []string{"CONSUMER_GROUP_MANAGEMENT"},
+ RequiredCapabilities: []string{"CONSUMER_GROUP_MANAGEMENT", "REMOTING"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "group", Flag: "group", Kind: StringField, Required: true, MinLength: 1},
- {Name: "namespace", Flag: "namespace", Kind: StringField, MinLength: 1},
- {Name: "subscriptionMode", Flag: "subscription-mode", Kind: StringField, Enum: []string{"Push", "Pop"}},
- {Name: "consumeType", Flag: "consume-type", Kind: StringField, Enum: []string{"CLUSTERING", "BROADCASTING"}},
- {Name: "subscriptionDataType", Flag: "subscription-data-type", Kind: StringField, MinLength: 1},
- {Name: "deliveryOrderType", Flag: "delivery-order-type", Kind: StringField, MinLength: 1},
- {Name: "retryMaxTimes", Flag: "retry-max-times", Kind: IntegerField, Minimum: 0, HasMinimum: true},
- {Name: "delaySeconds", Flag: "delay-seconds", Kind: IntegerField, Minimum: 0, HasMinimum: true},
- {Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "groupName", Flag: "group-name", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "topicName", Flag: "topic-name", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "timestamp", Flag: "timestamp", Description: "Epoch milliseconds to reset to; rmqctl fills in the current time when the flag is not provided.", Kind: IntegerField, Required: true, ClientDefault: "NOW"},
{Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
- },
- AnyOf: []RequiredGroup{
- {Required: []string{"namespace"}},
- {Required: []string{"subscriptionMode"}},
- {Required: []string{"consumeType"}},
- {Required: []string{"subscriptionDataType"}},
- {Required: []string{"deliveryOrderType"}},
- {Required: []string{"retryMaxTimes"}},
- {Required: []string{"delaySeconds"}},
+ {Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
+ {Name: "break_glass", Flag: "break-glass", Kind: BooleanField},
+ {Name: "reason", Flag: "reason", Kind: StringField, MinLength: 1},
},
},
ViewHint: "object",
@@ -523,182 +319,177 @@ var defaultDocument = Document{
{
Name: "rmq.group.delete",
CLI: CLI{Resource: "group", Verb: "delete"},
- Description: "Delete a RocketMQ consumer group.",
+ Description: "Delete a RocketMQ consumer group; the group's dead-letter topic (%DLQ%<group>) is deleted on a best-effort basis.",
RiskLevel: "L3",
Permission: "group:delete",
RequiredCapabilities: []string{"CONSUMER_GROUP_MANAGEMENT"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "group", Flag: "group", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "groupName", Flag: "group-name", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
{Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
{Name: "break_glass", Flag: "break-glass", Kind: BooleanField},
{Name: "reason", Flag: "reason", Kind: StringField, MinLength: 1},
- {Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
},
},
ViewHint: "object",
},
{
- Name: "rmq.group.reset_offset",
- CLI: CLI{Resource: "group", Verb: "reset-offset"},
- Description: "Reset consumer offset for a group on a topic to a timestamp.",
- RiskLevel: "L2",
- Permission: "group:write",
- RequiredCapabilities: []string{"CONSUMER_GROUP_MANAGEMENT", "REMOTING"},
+ Name: "rmq.instance.capabilities",
+ CLI: CLI{Resource: "instance", Verb: "capabilities"},
+ Description: "Return the managed Studio Instance's capabilities to determine which tool requirements it satisfies.",
+ RiskLevel: "L1",
+ Permission: "cluster:read",
+ RequiredCapabilities: []string{},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "group", Flag: "group", Kind: StringField, Required: true, MinLength: 1},
- {Name: "topic", Flag: "topic", Kind: StringField, Required: true, MinLength: 1},
- {Name: "timestamp", Flag: "timestamp", Kind: IntegerField, Required: true},
- {Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
- {Name: "break_glass", Flag: "break-glass", Kind: BooleanField},
- {Name: "reason", Flag: "reason", Kind: StringField, MinLength: 1},
- {Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
},
},
ViewHint: "object",
},
{
- Name: "rmq.group.skip_accumulated",
- CLI: CLI{Resource: "group", Verb: "skip-accumulated"},
- Description: "Skip accumulated messages by moving the actual consumer queues to their ends recorded in preview.",
- RiskLevel: "L2",
- Permission: "group:write",
- RequiredCapabilities: []string{"REMOTING"},
+ Name: "rmq.instance.metrics",
+ CLI: CLI{Resource: "instance", Verb: "metrics"},
+ Description: "Query the dedicated metrics data source explicitly bound only to the selected Instance. Shared or unbound sources are unsupported.",
+ RiskLevel: "L1",
+ Permission: "metrics:read",
+ RequiredCapabilities: []string{},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "group", Flag: "group", Kind: StringField, Required: true, MinLength: 1},
- {Name: "topic", Flag: "topic", Kind: StringField, MinLength: 1},
- {Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
- {Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "metric", Flag: "metric", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "profileId", Flag: "profile-id", Kind: StringField},
+ {Name: "semanticMetric", Flag: "semantic-metric", Kind: StringField},
+ {Name: "start", Flag: "start", Description: "Unix timestamp in seconds (PromQL query_range start).", Kind: IntegerField, Required: true},
+ {Name: "end", Flag: "end", Description: "Unix timestamp in seconds (PromQL query_range end).", Kind: IntegerField, Required: true},
+ {Name: "step", Flag: "step", Description: "PromQL step duration, e.g. \"15s\", \"1m\".", Kind: StringField},
},
},
ViewHint: "object",
},
{
- Name: "rmq.lite_topic.list",
- CLI: CLI{Resource: "lite-topic", Verb: "list"},
- Description: "List RocketMQ 5.x LiteTopics by prefix or pattern.",
+ Name: "rmq.message.query",
+ CLI: CLI{Resource: "message", Verb: "query"},
+ Description: "Query RocketMQ messages by identifier: the first non-empty value among msgId, uniqueKey and key (in this order) selects the query path, and at least one of them must be provided. The startTime/endTime window only applies to the uniqueKey and key paths.",
RiskLevel: "L1",
- Permission: "topic:read",
- RequiredCapabilities: []string{"LITE_TOPIC"},
+ Permission: "message:read",
+ RequiredCapabilities: []string{"MESSAGE_QUERY"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "pattern", Flag: "pattern", Kind: StringField},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "topicName", Flag: "topic-name", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "msgId", Flag: "msg-id", Description: "Message id; highest-priority identifier (direct read, 0..1 message).", Kind: StringField, MinLength: 1},
+ {Name: "uniqueKey", Flag: "unique-key", Description: "Client-generated unique key (UNIQ_KEY index, 0..1 message); defaults to a recent 3-day window when no time range is given.", Kind: StringField, MinLength: 1},
+ {Name: "key", Flag: "key", Description: "Business key (key index, 0..n messages).", Kind: StringField, MinLength: 1},
+ {Name: "startTime", Flag: "start-time", Description: "Epoch milliseconds; only applies to the uniqueKey and key paths.", Kind: IntegerField},
+ {Name: "endTime", Flag: "end-time", Description: "Epoch milliseconds; only applies to the uniqueKey and key paths.", Kind: IntegerField},
},
},
ViewHint: "table",
TableDataKey: "items",
},
{
- Name: "rmq.lite_topic.create",
- CLI: CLI{Resource: "lite-topic", Verb: "create"},
- Description: "Create a RocketMQ 5.x LiteTopic through the standard AdminClient path.",
- RiskLevel: "L2",
- Permission: "topic:write",
- RequiredCapabilities: []string{"LITE_TOPIC"},
- InputSchema: InputSchema{
- Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "topic", Flag: "topic", Kind: StringField, Required: true, MinLength: 1},
- {Name: "namespace", Flag: "namespace", Kind: StringField},
- {Name: "writeQueues", Flag: "write-queues", Kind: IntegerField, Minimum: 1, HasMinimum: true},
- {Name: "readQueues", Flag: "read-queues", Kind: IntegerField, Minimum: 1, HasMinimum: true},
- {Name: "remark", Flag: "remark", Kind: StringField},
- {Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
- {Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
- },
- },
- ViewHint: "object",
- },
- {
- Name: "rmq.message.trace",
- CLI: CLI{Resource: "message", Verb: "trace"},
- Description: "Return the message trace timeline for one message id.",
+ Name: "rmq.message.query_by_topic",
+ CLI: CLI{Resource: "message", Verb: "query-by-topic"},
+ Description: "Query RocketMQ messages by topic and optional time range in one Studio Instance.",
RiskLevel: "L1",
Permission: "message:read",
- RequiredCapabilities: []string{"MESSAGE_TRACE"},
+ RequiredCapabilities: []string{"MESSAGE_QUERY"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "msgId", Flag: "msg-id", Kind: StringField, Required: true, MinLength: 1},
- {Name: "topic", Flag: "topic", Kind: StringField},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "topicName", Flag: "topic-name", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "tag", Flag: "tag", Kind: StringField},
+ {Name: "startTime", Flag: "start-time", Kind: IntegerField},
+ {Name: "endTime", Flag: "end-time", Kind: IntegerField},
},
},
- ViewHint: "object",
+ ViewHint: "table",
+ TableDataKey: "items",
},
{
- Name: "rmq.message.query_by_id",
- CLI: CLI{Resource: "message", Verb: "query-by-id"},
- Description: "Query a single RocketMQ message by its message id within a topic.",
+ Name: "rmq.message.query_by_offset",
+ CLI: CLI{Resource: "message", Verb: "query-by-offset"},
+ Description: "Fetch the message stored at one physical queue offset (admin queryMsgByOffset); returns empty items when the offset is out of range or the CommitLog entry was already cleaned. Pair it with the queueStats block of rmq.topic.detail.",
RiskLevel: "L1",
Permission: "message:read",
RequiredCapabilities: []string{"MESSAGE_QUERY"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "msgId", Flag: "msg-id", Kind: StringField, Required: true, MinLength: 1},
- {Name: "topic", Flag: "topic", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "topicName", Flag: "topic-name", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "brokerName", Flag: "broker-name", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "queueId", Flag: "queue-id", Kind: IntegerField, Required: true, Minimum: 0, HasMinimum: true},
+ {Name: "offset", Flag: "offset", Kind: IntegerField, Required: true, Minimum: 0, HasMinimum: true},
},
},
ViewHint: "table",
TableDataKey: "items",
},
{
- Name: "rmq.message.query_by_key",
- CLI: CLI{Resource: "message", Verb: "query-by-key"},
- Description: "Query RocketMQ messages by business key within a topic.",
+ Name: "rmq.message.query_dlq",
+ CLI: CLI{Resource: "message", Verb: "query-dlq"},
+ Description: "Query dead-letter groups, or the dead-letter messages of one group, in a Studio Instance.",
RiskLevel: "L1",
- Permission: "message:read",
- RequiredCapabilities: []string{"MESSAGE_QUERY"},
+ Permission: "dlq:read",
+ RequiredCapabilities: []string{"DLQ_MANAGEMENT"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "key", Flag: "key", Kind: StringField, Required: true, MinLength: 1},
- {Name: "topic", Flag: "topic", Kind: StringField, Required: true, MinLength: 1},
- {Name: "startTime", Flag: "start-time", Kind: IntegerField},
- {Name: "endTime", Flag: "end-time", Kind: IntegerField},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "groupName", Flag: "group-name", Kind: StringField},
+ {Name: "search", Flag: "search", Kind: StringField},
+ {Name: "time", Kind: ObjectField, Object: &InputSchema{
+ Fields: []Field{
+ {Name: "startTime", Flag: "start-time", Kind: IntegerField},
+ {Name: "endTime", Flag: "end-time", Kind: IntegerField},
+ },
+ }},
+ {Name: "page", Kind: ObjectField, Object: &InputSchema{
+ Fields: []Field{
+ {Name: "page", Flag: "page", Kind: IntegerField, Minimum: 1, HasMinimum: true},
+ {Name: "pageSize", Flag: "page-size", Kind: IntegerField, Minimum: 1, HasMinimum: true},
+ },
+ }},
},
},
ViewHint: "table",
TableDataKey: "items",
},
{
- Name: "rmq.message.query_by_topic",
- CLI: CLI{Resource: "message", Verb: "query-by-topic"},
- Description: "Query RocketMQ messages by topic and optional time range in one cluster.",
+ Name: "rmq.message.trace",
+ CLI: CLI{Resource: "message", Verb: "trace"},
+ Description: "Return the message trace timeline for one message id.",
RiskLevel: "L1",
Permission: "message:read",
- RequiredCapabilities: []string{"MESSAGE_QUERY"},
+ RequiredCapabilities: []string{"MESSAGE_TRACE"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "topic", Flag: "topic", Kind: StringField, Required: true, MinLength: 1},
- {Name: "tag", Flag: "tag", Kind: StringField},
- {Name: "startTime", Flag: "start-time", Kind: IntegerField},
- {Name: "endTime", Flag: "end-time", Kind: IntegerField},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "topicName", Flag: "topic-name", Kind: StringField},
+ {Name: "msgId", Flag: "msg-id", Kind: StringField, Required: true, MinLength: 1},
},
},
- ViewHint: "table",
- TableDataKey: "items",
+ ViewHint: "object",
},
{
- Name: "rmq.message.resend",
- CLI: CLI{Resource: "message", Verb: "resend"},
- Description: "Republish an existing message to its original topic or a selected target topic.",
+ Name: "rmq.message.send",
+ CLI: CLI{Resource: "message", Verb: "send"},
+ Description: "Send one message to a RocketMQ topic; the registered topic type drives dispatch: NORMAL/LITE keep the plain parameters, FIFO topics require messageGroup, DELAY topics require deliveryTimestamp, and TRANSACTION topics are rejected (transaction messages cannot be sent through the ops channel).",
RiskLevel: "L2",
Permission: "message:write",
RequiredCapabilities: []string{"REMOTING"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "msgId", Flag: "msg-id", Kind: StringField, Required: true, MinLength: 1},
- {Name: "sourceTopic", Flag: "source-topic", Kind: StringField, MinLength: 1},
- {Name: "targetTopic", Flag: "target-topic", Kind: StringField, MinLength: 1},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "topicName", Flag: "topic-name", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "body", Flag: "body", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "messageGroup", Flag: "message-group", Description: "Sharding key; required for FIFO topics so messages of the same group land on the same queue.", Kind: StringField, MinLength: 1},
+ {Name: "deliveryTimestamp", Flag: "delivery-timestamp", Description: "Epoch milliseconds for delayed delivery; required for DELAY topics (the server sets TIMER_DELIVER_MS itself, do not pass it via properties).", Kind: IntegerField},
+ {Name: "tag", Flag: "tag", Kind: StringField},
+ {Name: "key", Flag: "key", Kind: StringField},
+ {Name: "properties", Flag: "properties", Description: "JSON object string of message properties, e.g. '{\"key1\":\"value1\"}'.", Kind: StringField},
{Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
{Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
},
@@ -706,35 +497,47 @@ var defaultDocument = Document{
ViewHint: "object",
},
{
- Name: "rmq.metrics.query",
- CLI: CLI{Resource: "metrics", Verb: "query"},
- Description: "Query the dedicated metrics data source explicitly bound only to the selected Instance. Shared or unbound sources are unsupported.",
- RiskLevel: "L1",
- Permission: "metrics:read",
- RequiredCapabilities: []string{},
+ Name: "rmq.message.redelivery",
+ CLI: CLI{Resource: "message", Verb: "redelivery"},
+ Description: "Redeliver an existing message for one consumer group: the copy goes to %RETRY%<groupName> by default so only that group re-consumes it; pass targetTopic explicitly to send it to a specific topic visible to all its subscribers instead.",
+ RiskLevel: "L2",
+ Permission: "message:write",
+ RequiredCapabilities: []string{"REMOTING"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "metric", Flag: "metric", Kind: StringField, Required: true, MinLength: 1},
- {Name: "profileId", Flag: "profile-id", Kind: StringField},
- {Name: "semanticMetric", Flag: "semantic-metric", Kind: StringField},
- {Name: "start", Flag: "start", Description: "Unix timestamp in seconds (PromQL query_range start).", Kind: IntegerField, Required: true},
- {Name: "end", Flag: "end", Description: "Unix timestamp in seconds (PromQL query_range end).", Kind: IntegerField, Required: true},
- {Name: "step", Flag: "step", Description: "PromQL step duration, e.g. \"15s\", \"1m\".", Kind: StringField},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "groupName", Flag: "group-name", Description: "Consumer group receiving the redelivered copy; used for audit and trace correlation when targetTopic is provided.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "msgId", Flag: "msg-id", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "sourceTopic", Flag: "source-topic", Kind: StringField, MinLength: 1},
+ {Name: "targetTopic", Flag: "target-topic", Kind: StringField, MinLength: 1},
+ {Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
+ {Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
},
},
ViewHint: "object",
},
{
- Name: "rmq.nameserver.config.diff",
- CLI: CLI{Resource: "nameserver-config", Verb: "diff"},
- Description: "Compare configuration of the selected Instance management NameServer endpoints.",
- RiskLevel: "L1",
- Permission: "cluster:read",
- RequiredCapabilities: []string{"NAMESERVER_ADMIN"},
+ Name: "rmq.message.redelivery_dlq",
+ CLI: CLI{Resource: "message", Verb: "redelivery-dlq"},
+ Description: "Resend dead-letter messages for a consumer group back to the target topic.",
+ RiskLevel: "L2",
+ Permission: "dlq:write",
+ RequiredCapabilities: []string{"DLQ_MANAGEMENT"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "groupName", Flag: "group-name", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "targetTopic", Flag: "target-topic", Kind: StringField},
+ {Name: "time", Kind: ObjectField, Object: &InputSchema{
+ Fields: []Field{
+ {Name: "startTime", Flag: "start-time", Kind: IntegerField},
+ {Name: "endTime", Flag: "end-time", Kind: IntegerField},
+ },
+ }},
+ {Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
+ {Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
+ {Name: "break_glass", Flag: "break-glass", Kind: BooleanField},
+ {Name: "reason", Flag: "reason", Kind: StringField, MinLength: 1},
},
},
ViewHint: "object",
@@ -742,62 +545,58 @@ var defaultDocument = Document{
{
Name: "rmq.nameserver.list",
CLI: CLI{Resource: "nameserver", Verb: "list"},
- Description: "List the management NameServer endpoints configured for the selected Instance.",
+ Description: "List the management NameServer endpoints, optionally filtered by physical cluster name.",
RiskLevel: "L1",
Permission: "nameserver:read",
RequiredCapabilities: []string{"NAMESERVER_ADMIN"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "clusterName", Flag: "cluster-name", Description: "Physical RocketMQ cluster name.", Kind: StringField, MinLength: 1},
},
},
ViewHint: "table",
TableDataKey: "items",
},
{
- Name: "rmq.proxy.config_update",
- CLI: CLI{Resource: "proxy", Verb: "config-update"},
- Description: "Reload a Proxy configuration through an Instance management adapter; unsupported when no adapter is configured.",
- RiskLevel: "L3",
- Permission: "proxy:write",
- RequiredCapabilities: []string{"PROXY_ADMIN"},
+ Name: "rmq.nameserver.config",
+ CLI: CLI{Resource: "nameserver", Verb: "config"},
+ Description: "Read the configuration of each management NameServer endpoint for one physical cluster (read-only; no diff comparison and no mutation).",
+ RiskLevel: "L1",
+ Permission: "nameserver:read",
+ RequiredCapabilities: []string{"NAMESERVER_ADMIN"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "addr", Flag: "addr", Kind: StringField, Required: true, MinLength: 1},
- {Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
- {Name: "break_glass", Flag: "break-glass", Kind: BooleanField},
- {Name: "reason", Flag: "reason", Kind: StringField, MinLength: 1},
- {Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
+ {Name: "clusterName", Flag: "cluster-name", Description: "Physical RocketMQ cluster name.", Kind: StringField, Required: true, MinLength: 1},
},
},
ViewHint: "object",
},
{
- Name: "rmq.proxy.describe",
- CLI: CLI{Resource: "proxy", Verb: "describe"},
- Description: "Inspect discovered Proxy data endpoints within the selected Instance.",
+ Name: "rmq.proxy.list",
+ CLI: CLI{Resource: "proxy", Verb: "list"},
+ Description: "Discover Proxy data endpoints, optionally filtered by physical cluster name. Discovery does not establish Broker cluster membership or management capability.",
RiskLevel: "L1",
Permission: "proxy:read",
RequiredCapabilities: []string{"PROXY_DISCOVERY"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "clusterName", Flag: "cluster-name", Description: "Physical RocketMQ cluster name.", Kind: StringField, MinLength: 1},
},
},
ViewHint: "table",
TableDataKey: "items",
},
{
- Name: "rmq.proxy.list",
- CLI: CLI{Resource: "proxy", Verb: "list"},
- Description: "Discover Proxy data endpoints from the selected Instance. Discovery does not establish Broker cluster membership or management capability.",
+ Name: "rmq.proxy.config",
+ CLI: CLI{Resource: "proxy", Verb: "config"},
+ Description: "Read the Proxy configuration and reachability snapshot for one physical cluster, with an optional addr filter (read-only; configuration reload is not exposed through MCP).",
RiskLevel: "L1",
Permission: "proxy:read",
RequiredCapabilities: []string{"PROXY_DISCOVERY"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "clusterName", Flag: "cluster-name", Description: "Physical RocketMQ cluster name.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "addr", Flag: "addr", Kind: StringField, MinLength: 1},
},
},
ViewHint: "table",
@@ -806,85 +605,31 @@ var defaultDocument = Document{
{
Name: "rmq.topic.list",
CLI: CLI{Resource: "topic", Verb: "list"},
- Description: "List RocketMQ topics in one Studio cluster.",
+ Description: "List RocketMQ topics in one Studio Instance.",
RiskLevel: "L1",
Permission: "topic:read",
RequiredCapabilities: []string{"TOPIC_MANAGEMENT"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "topicName", Flag: "topic-name", Description: "Fuzzy topic name filter.", Kind: StringField, MinLength: 1},
{Name: "type", Flag: "type", Kind: StringField, Enum: []string{"NORMAL", "FIFO", "DELAY", "TRANSACTION", "LITE"}},
- {Name: "search", Flag: "search", Kind: StringField, MinLength: 1},
},
},
ViewHint: "table",
TableDataKey: "items",
},
{
- Name: "rmq.topic.create",
- CLI: CLI{Resource: "topic", Verb: "create"},
- Description: "Create a RocketMQ topic.",
- RiskLevel: "L2",
- Permission: "topic:write",
- RequiredCapabilities: []string{"TOPIC_MANAGEMENT"},
- InputSchema: InputSchema{
- Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "topic", Flag: "topic", Kind: StringField, Required: true, MinLength: 1},
- {Name: "namespace", Flag: "namespace", Kind: StringField, MinLength: 1},
- {Name: "type", Flag: "type", Kind: StringField, Enum: []string{"NORMAL", "FIFO", "DELAY", "TRANSACTION", "LITE"}},
- {Name: "writeQueues", Flag: "write-queues", Kind: IntegerField, Minimum: 1, HasMinimum: true},
- {Name: "readQueues", Flag: "read-queues", Kind: IntegerField, Minimum: 1, HasMinimum: true},
- {Name: "perm", Flag: "perm", Kind: StringField, Enum: []string{"RW", "RO", "WO"}},
- {Name: "remark", Flag: "remark", Kind: StringField},
- {Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
- {Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
- },
- },
- ViewHint: "object",
- },
- {
- Name: "rmq.topic.update",
- CLI: CLI{Resource: "topic", Verb: "update"},
- Description: "Update a RocketMQ topic.",
- RiskLevel: "L2",
- Permission: "topic:write",
- RequiredCapabilities: []string{"TOPIC_MANAGEMENT"},
- InputSchema: InputSchema{
- Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "topic", Flag: "topic", Kind: StringField, Required: true, MinLength: 1},
- {Name: "namespace", Flag: "namespace", Kind: StringField, MinLength: 1},
- {Name: "type", Flag: "type", Kind: StringField, Enum: []string{"NORMAL", "FIFO", "DELAY", "TRANSACTION", "LITE"}},
- {Name: "writeQueues", Flag: "write-queues", Kind: IntegerField, Minimum: 1, HasMinimum: true},
- {Name: "readQueues", Flag: "read-queues", Kind: IntegerField, Minimum: 1, HasMinimum: true},
- {Name: "perm", Flag: "perm", Kind: StringField, Enum: []string{"RW", "RO", "WO"}},
- {Name: "remark", Flag: "remark", Kind: StringField},
- {Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
- {Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
- },
- AnyOf: []RequiredGroup{
- {Required: []string{"type"}},
- {Required: []string{"writeQueues"}},
- {Required: []string{"readQueues"}},
- {Required: []string{"perm"}},
- {Required: []string{"remark"}},
- },
- },
- ViewHint: "object",
- },
- {
- Name: "rmq.topic.describe",
- CLI: CLI{Resource: "topic", Verb: "describe"},
- Description: "Describe one RocketMQ topic, including configuration, consumer groups and broker routes.",
+ Name: "rmq.topic.detail",
+ CLI: CLI{Resource: "topic", Verb: "detail"},
+ Description: "Show full detail of one RocketMQ topic: configuration, consumer groups, broker routes and per-queue offset stats. queueStats is omitted (without failing the call) when the Instance lacks REMOTING capability or offset stats collection fails.",
RiskLevel: "L1",
Permission: "topic:read",
RequiredCapabilities: []string{"TOPIC_MANAGEMENT"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "topic", Flag: "topic", Kind: StringField, Required: true, MinLength: 1},
- {Name: "namespace", Flag: "namespace", Kind: StringField, MinLength: 1},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "topicName", Flag: "topic-name", Kind: StringField, Required: true, MinLength: 1},
},
},
ViewHint: "object",
@@ -898,31 +643,31 @@ var defaultDocument = Document{
RequiredCapabilities: []string{"TOPIC_MANAGEMENT", "REMOTING"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "topic", Flag: "topic", Kind: StringField, Required: true, MinLength: 1},
- {Name: "namespace", Flag: "namespace", Kind: StringField, MinLength: 1},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "topicName", Flag: "topic-name", Kind: StringField, Required: true, MinLength: 1},
},
},
ViewHint: "table",
TableDataKey: "items",
},
{
- Name: "rmq.topic.send",
- CLI: CLI{Resource: "topic", Verb: "send"},
- Description: "Send one message to a RocketMQ topic.",
+ Name: "rmq.topic.update",
+ CLI: CLI{Resource: "topic", Verb: "update"},
+ Description: "Update a RocketMQ topic.",
RiskLevel: "L2",
Permission: "topic:write",
- RequiredCapabilities: []string{"TOPIC_MANAGEMENT", "REMOTING"},
+ RequiredCapabilities: []string{"TOPIC_MANAGEMENT"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "topic", Flag: "topic", Kind: StringField, Required: true, MinLength: 1},
- {Name: "tag", Flag: "tag", Kind: StringField},
- {Name: "key", Flag: "key", Kind: StringField},
- {Name: "body", Flag: "body", Kind: StringField, Required: true, MinLength: 1},
- {Name: "properties", Flag: "properties", Description: "JSON object string of message properties, e.g. '{\"key1\":\"value1\"}'.", Kind: StringField},
- {Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "topicName", Flag: "topic-name", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "type", Flag: "type", Description: "Only used when the topic does not exist (creation); the topic type cannot be changed after creation.", Kind: StringField, Enum: []string{"NORMAL", "FIFO", "DELAY", "TRANSACTION", "LITE"}},
+ {Name: "writeQueues", Flag: "write-queues", Kind: IntegerField, Minimum: 1, HasMinimum: true},
+ {Name: "readQueues", Flag: "read-queues", Kind: IntegerField, Minimum: 1, HasMinimum: true},
+ {Name: "perm", Flag: "perm", Kind: StringField, Enum: []string{"RW", "RO", "WO"}},
+ {Name: "remark", Flag: "remark", Kind: StringField},
{Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
+ {Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
},
},
ViewHint: "object",
@@ -936,12 +681,12 @@ var defaultDocument = Document{
RequiredCapabilities: []string{"TOPIC_MANAGEMENT"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
- {Name: "topic", Flag: "topic", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "topicName", Flag: "topic-name", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
{Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
{Name: "break_glass", Flag: "break-glass", Kind: BooleanField},
{Name: "reason", Flag: "reason", Kind: StringField, MinLength: 1},
- {Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
},
},
ViewHint: "object",
@@ -955,22 +700,37 @@ var defaultDocument = Document{
RequiredCapabilities: []string{"ACL_MANAGEMENT"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
},
},
ViewHint: "table",
TableDataKey: "items",
},
+ {
+ Name: "rmq.user.get",
+ CLI: CLI{Resource: "user", Verb: "get"},
+ Description: "Get one RocketMQ ACL user by id without exposing credentials.",
+ RiskLevel: "L1",
+ Permission: "acl:read",
+ RequiredCapabilities: []string{"ACL_MANAGEMENT"},
+ InputSchema: InputSchema{
+ Fields: []Field{
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "id", Flag: "id", Kind: StringField, Required: true, MinLength: 1},
+ },
+ },
+ ViewHint: "object",
+ },
{
Name: "rmq.user.create",
CLI: CLI{Resource: "user", Verb: "create"},
Description: "Create a RocketMQ ACL user while keeping generated credentials out of tool output.",
RiskLevel: "L3",
Permission: "acl:write",
- RequiredCapabilities: []string{"ACL_MANAGEMENT"},
+ RequiredCapabilities: []string{"ACL_MANAGEMENT", "REMOTING"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
{Name: "username", Flag: "username", Kind: StringField, Required: true, MinLength: 1},
{Name: "admin", Flag: "admin", Kind: BooleanField},
{Name: "clusters", Flag: "clusters", Kind: StringSliceField},
@@ -988,10 +748,10 @@ var defaultDocument = Document{
Description: "Delete a RocketMQ ACL user by identifier.",
RiskLevel: "L3",
Permission: "acl:write",
- RequiredCapabilities: []string{"ACL_MANAGEMENT"},
+ RequiredCapabilities: []string{"ACL_MANAGEMENT", "REMOTING"},
InputSchema: InputSchema{
Fields: []Field{
- {Name: "cluster", Flag: "cluster", Description: "Studio Instance identifier; rmqctl supplies this from the selected context.", Kind: StringField, Required: true, MinLength: 1},
+ {Name: "instanceId", Flag: "instance-id", Description: "Studio Instance identifier.", Kind: StringField, Required: true, MinLength: 1},
{Name: "id", Flag: "id", Kind: StringField, Required: true, MinLength: 1},
{Name: "dry_run", Flag: "dry-run", Description: "When true, preview the mutation without executing it; omit to apply with a confirm_token.", Kind: BooleanField},
{Name: "confirm_token", Flag: "confirm-token", Kind: StringField, MinLength: 1},
diff --git a/rmqctl/internal/catalog/catalog_test.go b/rmqctl/internal/catalog/catalog_test.go
index f94b318f3..1cebe862f 100644
--- a/rmqctl/internal/catalog/catalog_test.go
+++ b/rmqctl/internal/catalog/catalog_test.go
@@ -81,9 +81,13 @@ func assertToolFields(t *testing.T, tool Tool) {
}
}
assertSchema(tool.InputSchema)
- cluster, ok := tool.InputSchema.Field("cluster")
- if !ok || !cluster.Required || cluster.Kind != StringField {
- t.Errorf("tool %q must require a string cluster field", tool.Name)
+ if instanceField, ok := InstanceFieldName(tool.InputSchema); ok {
+ field, _ := tool.InputSchema.Field(instanceField)
+ if !field.Required || field.Kind != StringField {
+ t.Errorf("tool %q instance field %q must be a required string", tool.Name, instanceField)
+ }
+ } else if !IsPlatformTool(tool.Name) {
+ t.Errorf("tool %q must declare a required instanceId field or be platform-level exempt", tool.Name)
}
}
diff --git a/rmqctl/internal/catalog/generate/main.go b/rmqctl/internal/catalog/generate/main.go
index 940ec9d87..3e209bf87 100644
--- a/rmqctl/internal/catalog/generate/main.go
+++ b/rmqctl/internal/catalog/generate/main.go
@@ -31,6 +31,7 @@ import (
"text/template"
"unicode"
+ toolcatalog "github.com/apache/rocketmq-dashboard/rmqctl/internal/catalog"
"gopkg.in/yaml.v3"
)
@@ -67,8 +68,8 @@ type requiredGroup struct {
}
type property struct {
- TargetMode string `yaml:"x-target-mode,omitempty" json:"x-target-mode,omitempty"`
CLIFlag string `yaml:"x-cli-flag,omitempty" json:"x-cli-flag,omitempty"`
+ ClientDefault string `yaml:"x-client-default,omitempty" json:"x-client-default,omitempty"`
Type string `yaml:"type" json:"type,omitempty"`
Description string `yaml:"description" json:"description,omitempty"`
Enum []string `yaml:"enum" json:"enum,omitempty"`
@@ -121,15 +122,16 @@ type goRequiredGroup struct {
}
type goField struct {
- Name string
- Flag string
- Description string
- Kind string
- Required bool
- Enum []string
- Minimum *float64
- MinLength int
- Object *goInputSchema
+ Name string
+ Flag string
+ Description string
+ Kind string
+ Required bool
+ Enum []string
+ Minimum *float64
+ MinLength int
+ ClientDefault string
+ Object *goInputSchema
}
const goCatalogTemplate = `/*
@@ -195,7 +197,7 @@ var defaultDocument = Document{
{{- end }}
},
}
-{{ define "field" }}{Name: {{ quote .Name }}{{ if .Flag }}, Flag: {{ quote .Flag }}{{ end }}{{ if .Description }}, Description: {{ quote .Description }}{{ end }}, Kind: {{ .Kind }}{{ if .Required }}, Required: true{{ end }}{{ if .Enum }}, Enum: {{ stringSlice .Enum }}{{ end }}{{ if .Minimum }}, Minimum: {{ number .Minimum }}, HasMinimum: true{{ end }}{{ if .MinLength }}, MinLength: {{ .MinLength }}{{ end }}{{ with .Object }}, Object: &InputSchema{
+{{ define "field" }}{Name: {{ quote .Name }}{{ if .Flag }}, Flag: {{ quote .Flag }}{{ end }}{{ if .Description }}, Description: {{ quote .Description }}{{ end }}, Kind: {{ .Kind }}{{ if .Required }}, Required: true{{ end }}{{ if .Enum }}, Enum: {{ stringSlice .Enum }}{{ end }}{{ if .Minimum }}, Minimum: {{ number .Minimum }}, HasMinimum: true{{ end }}{{ if .MinLength }}, MinLength: {{ .MinLength }}{{ end }}{{ if .ClientDefault }}, ClientDefault: {{ quote .ClientDefault }}{{ end }}{{ with [...]
Fields: []Field{
{{ range .Fields }}{{ template "field" . }},
{{ end }}},
@@ -234,7 +236,8 @@ func (schema *property) UnmarshalYAML(node *yaml.Node) error {
for index := 0; index+1 < len(node.Content); index += 2 {
switch key := node.Content[index].Value; key {
case "type", "description", "enum", "minimum", "minLength", "items",
- "required", "properties", "additionalProperties", "anyOf", "x-target-mode", "x-cli-flag":
+ "required", "properties", "additionalProperties", "anyOf", "x-cli-flag",
+ "x-client-default":
default:
return fmt.Errorf("unsupported input schema keyword %q at line %d", key, node.Content[index].Line)
}
@@ -503,10 +506,24 @@ func validate(document catalogDocument) error {
if tool.InputSchema.Type != "object" {
return fmt.Errorf("tool %q input schema must be an object", tool.Name)
}
- if !slices.Contains(tool.InputSchema.Required, "cluster") {
- return fmt.Errorf("tool %q must require cluster", tool.Name)
+ // Decisions 7/25/26: instanceId is a formal required input for every
+ // tool except the platform-level exemption list, which must not
+ // declare it at all. rmqctl feeds the value from the global
+ // --instance-id flag instead of a generated per-tool flag.
+ _, declaresInstance := tool.InputSchema.Properties["instanceId"]
+ if toolcatalog.IsPlatformTool(tool.Name) {
+ if declaresInstance {
+ return fmt.Errorf("platform-level tool %q must not declare instanceId", tool.Name)
+ }
+ } else {
+ if !declaresInstance {
+ return fmt.Errorf("tool %q must declare instanceId", tool.Name)
+ }
+ if !slices.Contains(tool.InputSchema.Required, "instanceId") {
+ return fmt.Errorf("tool %q must require instanceId", tool.Name)
+ }
}
- if err := validateSchema(tool.InputSchema, make(map[string]struct{})); err != nil {
+ if err := validateSchema(tool.InputSchema, make(map[string]struct{}), 0); err != nil {
return fmt.Errorf("tool %q: %w", tool.Name, err)
}
if err := validateRisk(tool); err != nil {
@@ -518,11 +535,14 @@ func validate(document catalogDocument) error {
// Flags retain their leaf names at every depth for CLI compatibility. Reject
// collisions across the entire command before Cobra can register them.
-func validateSchema(schema inputSchema, flags map[string]struct{}) error {
+func validateSchema(schema inputSchema, flags map[string]struct{}, depth int) error {
if len(schema.PropertyOrder) != len(schema.Properties) {
return fmt.Errorf("invalid input property ordering")
}
- if len(schema.Properties) == 0 {
+ // A top-level schema without properties is a zero-flag tool (e.g.
+ // rmq.dashboard.summary, a platform-level aggregate with no inputs).
+ // Nested objects must still define leaves so ObjectField binds flags.
+ if len(schema.Properties) == 0 && depth > 0 {
return fmt.Errorf("object must define properties for CLI flags")
}
for _, name := range schema.PropertyOrder {
@@ -530,24 +550,33 @@ func validateSchema(schema inputSchema, flags map[string]struct{}) error {
if !exists {
return fmt.Errorf("input property %q is undefined", name)
}
+ if field.ClientDefault != "" {
+ if depth != 0 {
+ return fmt.Errorf("property %q: x-client-default is only supported on top-level properties", name)
+ }
+ if field.ClientDefault != "NOW" {
+ return fmt.Errorf("property %q has unsupported x-client-default %q; only NOW is supported", name, field.ClientDefault)
+ }
+ }
kind, err := fieldKind(field)
if err != nil {
return fmt.Errorf("property %q: %w", name, err)
}
if kind == "ObjectField" {
- if err := validateSchema(field, flags); err != nil {
+ if err := validateSchema(field, flags, depth+1); err != nil {
return fmt.Errorf("property %q: %w", name, err)
}
continue
}
flagName := schemaFlagName(name, field)
- if field.CLIFlag != "" {
- if !validCLIFlag(field.CLIFlag) {
- return fmt.Errorf("property %q has invalid x-cli-flag %q", name, field.CLIFlag)
- }
- if _, reserved := reservedCLIFlags[field.CLIFlag]; reserved {
- return fmt.Errorf("property %q uses reserved CLI flag --%s", name, field.CLIFlag)
- }
+ if field.CLIFlag != "" && !validCLIFlag(field.CLIFlag) {
+ return fmt.Errorf("property %q has invalid x-cli-flag %q", name, field.CLIFlag)
+ }
+ // Global persistent flags own their names. The only exception is the
+ // top-level instanceId property: the runtime feeds it from the global
+ // --instance-id flag and never registers a per-tool flag for it.
+ if _, reserved := reservedCLIFlags[flagName]; reserved && !(depth == 0 && name == "instanceId") {
+ return fmt.Errorf("property %q uses reserved CLI flag --%s", name, flagName)
}
if _, exists := flags[flagName]; exists {
return fmt.Errorf("contains duplicate flag --%s", flagName)
@@ -673,7 +702,7 @@ func compileSchema(schema inputSchema) (goInputSchema, error) {
compiledField := goField{
Name: name, Flag: schemaFlagName(name, field), Description: field.Description,
Kind: kind, Required: required[name], Enum: slices.Clone(field.Enum),
- MinLength: field.MinLength,
+ MinLength: field.MinLength, ClientDefault: field.ClientDefault,
}
if field.Minimum != nil {
compiledField.Minimum = new(*field.Minimum)
@@ -839,6 +868,9 @@ func stringSet(values []string) map[string]bool {
var reservedCLIFlags = map[string]struct{}{
"help": {}, "version": {}, "context": {}, "config": {}, "output": {}, "timeout": {}, "yes": {},
+ // instance-id is the global persistent flag feeding the catalog's
+ // instanceId property; per-tool flags must not claim it.
+ "instance-id": {},
}
func validCLIFlag(value string) bool {
diff --git a/rmqctl/internal/catalog/generate/main_test.go b/rmqctl/internal/catalog/generate/main_test.go
index de1f084b4..bcf3a3f5f 100644
--- a/rmqctl/internal/catalog/generate/main_test.go
+++ b/rmqctl/internal/catalog/generate/main_test.go
@@ -23,11 +23,39 @@ import (
"testing"
)
-func TestRunGeneratesAndVerifiesCatalog(t *testing.T) {
- directory := t.TempDir()
- input := filepath.Join(directory, "rmq-tools.yaml")
- output := filepath.Join(directory, "catalog_gen.go")
- source := `version: 1.0.0
+const instanceScopedToolSource = `version: 1.0.0
+minimumClientVersion: 1.0.0
+tools:
+ - name: rmq.topic.list
+ cli:
+ resource: topic
+ verb: list
+ description: List topics.
+ riskLevel: L1
+ permission: topic:read
+ requiredCapabilities: []
+ inputSchema:
+ type: object
+ required:
+ - instanceId
+ properties:
+ instanceId:
+ type: string
+ minLength: 1
+ topicName:
+ type: string
+ minLength: 1
+ outputSchema:
+ type: object
+ properties:
+ items:
+ type: array
+ items:
+ type: object
+ viewHint: table
+`
+
+const platformToolSource = `version: 1.0.0
minimumClientVersion: 1.0.0
tools:
- name: rmq.cluster.list
@@ -40,12 +68,7 @@ tools:
requiredCapabilities: []
inputSchema:
type: object
- required:
- - cluster
properties:
- cluster:
- type: string
- minLength: 1
status:
type: string
minLength: 1
@@ -58,9 +81,20 @@ tools:
type: object
viewHint: table
`
+
+func writeCatalogSource(t *testing.T, source string) (input string, output string) {
+ t.Helper()
+ directory := t.TempDir()
+ input = filepath.Join(directory, "rmq-tools.yaml")
+ output = filepath.Join(directory, "catalog_gen.go")
if err := os.WriteFile(input, []byte(source), 0o600); err != nil {
t.Fatal(err)
}
+ return input, output
+}
+
+func TestRunGeneratesAndVerifiesCatalog(t *testing.T) {
+ input, output := writeCatalogSource(t, instanceScopedToolSource)
arguments := []string{"-input", input, "-output", output}
if err := run(arguments); err != nil {
@@ -73,11 +107,11 @@ tools:
text := string(generated)
for _, expected := range []string{
"Code generated by cataloggen. DO NOT EDIT.",
- `Name: "rmq.cluster.list"`,
- `Permission: "cluster:read"`,
+ `Name: "rmq.topic.list"`,
+ `Permission: "topic:read"`,
`RequiredCapabilities: []string{}`,
- `{Name: "cluster", Flag: "cluster", Kind: StringField, Required: true, MinLength: 1}`,
- `{Name: "status", Flag: "status", Kind: StringField, MinLength: 1}`,
+ `{Name: "instanceId", Flag: "instance-id", Kind: StringField, Required: true, MinLength: 1}`,
+ `{Name: "topicName", Flag: "topic-name", Kind: StringField, MinLength: 1}`,
`TableDataKey: "items"`,
} {
if !strings.Contains(text, expected) {
@@ -89,3 +123,161 @@ tools:
t.Fatalf("verify generated catalog: %v", err)
}
}
+
+// TestRunAcceptsPlatformToolWithoutInstanceID verifies the platform-level
+// exemption list (decisions 25/26): exempt tools must not declare instanceId.
+func TestRunAcceptsPlatformToolWithoutInstanceID(t *testing.T) {
+ input, output := writeCatalogSource(t, platformToolSource)
+ if err := run([]string{"-input", input, "-output", output}); err != nil {
+ t.Fatalf("generate catalog: %v", err)
+ }
+ generated, err := os.ReadFile(output)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if strings.Contains(string(generated), "instanceId") {
+ t.Fatalf("platform tool catalog must not carry instanceId:\n%s", generated)
+ }
+}
+
+// TestRunRejectsInstanceScopedToolWithoutInstanceID verifies that non-platform
+// tools must declare and require instanceId (decision 7).
+func TestRunRejectsInstanceScopedToolWithoutInstanceID(t *testing.T) {
+ source := strings.Replace(instanceScopedToolSource, ` required:
+ - instanceId
+ properties:
+ instanceId:
+ type: string
+ minLength: 1
+`, ` properties:
+`, 1)
+ input, output := writeCatalogSource(t, source)
+ err := run([]string{"-input", input, "-output", output})
+ if err == nil || !strings.Contains(err.Error(), "must declare instanceId") {
+ t.Fatalf("err = %v, want instanceId declaration failure", err)
+ }
+}
+
+// TestRunRejectsPlatformToolDeclaringInstanceID verifies the exemption is
+// bidirectional: platform-level tools must not declare instanceId.
+func TestRunRejectsPlatformToolDeclaringInstanceID(t *testing.T) {
+ source := strings.Replace(platformToolSource, ` inputSchema:
+ type: object
+ properties:
+`, ` inputSchema:
+ type: object
+ required:
+ - instanceId
+ properties:
+ instanceId:
+ type: string
+ minLength: 1
+`, 1)
+ input, output := writeCatalogSource(t, source)
+ err := run([]string{"-input", input, "-output", output})
+ if err == nil || !strings.Contains(err.Error(), "must not declare instanceId") {
+ t.Fatalf("err = %v, want platform-tool instanceId rejection", err)
+ }
+}
+
+// TestRunCompilesClientDefaultNow verifies the x-client-default: NOW catalog
+// extension (decision 13) is parsed, validated and compiled into the generated
+// Field so the runtime can fill the current Unix milliseconds.
+func TestRunCompilesClientDefaultNow(t *testing.T) {
+ source := strings.Replace(instanceScopedToolSource, ` topicName:
+ type: string
+ minLength: 1
+`, ` timestamp:
+ type: integer
+ x-client-default: NOW
+`, 1)
+ source = strings.Replace(source, ` required:
+ - instanceId
+`, ` required:
+ - instanceId
+ - timestamp
+`, 1)
+ input, output := writeCatalogSource(t, source)
+ if err := run([]string{"-input", input, "-output", output}); err != nil {
+ t.Fatalf("generate catalog: %v", err)
+ }
+ generated, err := os.ReadFile(output)
+ if err != nil {
+ t.Fatal(err)
+ }
+ expected := `{Name: "timestamp", Flag: "timestamp", Kind: IntegerField, Required: true, ClientDefault: "NOW"}`
+ if !strings.Contains(string(generated), expected) {
+ t.Fatalf("generated catalog does not contain %q\n%s", expected, generated)
+ }
+}
+
+// TestRunRejectsUnsupportedClientDefault verifies that only NOW is accepted
+// for x-client-default.
+func TestRunRejectsUnsupportedClientDefault(t *testing.T) {
+ source := strings.Replace(instanceScopedToolSource, ` topicName:
+ type: string
+ minLength: 1
+`, ` timestamp:
+ type: integer
+ x-client-default: TODAY
+`, 1)
+ input, output := writeCatalogSource(t, source)
+ err := run([]string{"-input", input, "-output", output})
+ if err == nil || !strings.Contains(err.Error(), "unsupported x-client-default") {
+ t.Fatalf("err = %v, want unsupported x-client-default failure", err)
+ }
+}
+
+// TestRunRejectsNestedClientDefault verifies that x-client-default is only
+// allowed on top-level properties, matching the runtime fill scope.
+func TestRunRejectsNestedClientDefault(t *testing.T) {
+ source := strings.Replace(instanceScopedToolSource, ` topicName:
+ type: string
+ minLength: 1
+`, ` filter:
+ type: object
+ properties:
+ timestamp:
+ type: integer
+ x-client-default: NOW
+`, 1)
+ input, output := writeCatalogSource(t, source)
+ err := run([]string{"-input", input, "-output", output})
+ if err == nil || !strings.Contains(err.Error(), "only supported on top-level properties") {
+ t.Fatalf("err = %v, want nested x-client-default failure", err)
+ }
+}
+
+// TestRunRejectsReservedInstanceIDFlag verifies that per-tool properties
+// cannot claim the global --instance-id flag, neither via x-cli-flag nor via
+// a nested property literally named instanceId.
+func TestRunRejectsReservedInstanceIDFlag(t *testing.T) {
+ source := strings.Replace(instanceScopedToolSource, ` topicName:
+ type: string
+ minLength: 1
+`, ` topicName:
+ type: string
+ minLength: 1
+ x-cli-flag: instance-id
+`, 1)
+ input, output := writeCatalogSource(t, source)
+ err := run([]string{"-input", input, "-output", output})
+ if err == nil || !strings.Contains(err.Error(), "reserved CLI flag --instance-id") {
+ t.Fatalf("err = %v, want reserved flag failure", err)
+ }
+
+ nested := strings.Replace(instanceScopedToolSource, ` topicName:
+ type: string
+ minLength: 1
+`, ` filter:
+ type: object
+ properties:
+ instanceId:
+ type: string
+`, 1)
+ input, output = writeCatalogSource(t, nested)
+ err = run([]string{"-input", input, "-output", output})
+ if err == nil || !strings.Contains(err.Error(), "reserved CLI flag --instance-id") {
+ t.Fatalf("err = %v, want nested instanceId rejection", err)
+ }
+}
diff --git a/rmqctl/internal/config/config.go b/rmqctl/internal/config/config.go
index bac884072..1c877742f 100644
--- a/rmqctl/internal/config/config.go
+++ b/rmqctl/internal/config/config.go
@@ -27,9 +27,12 @@ type Config struct {
Contexts map[string]Context `yaml:"contexts,omitempty" json:"contexts,omitempty"`
}
+// Context stores only the Studio Server endpoint and credential references.
+// The Studio Instance identifier is deliberately not part of the context: it
+// must be passed explicitly via the global --instance-id flag on every
+// invocation (no default injection).
type Context struct {
Server string `yaml:"server" json:"server"`
- Cluster string `yaml:"cluster" json:"cluster"`
Credential CredentialRef `yaml:"credential" json:"credential"`
}
@@ -169,7 +172,6 @@ func ValidateContext(context Context) error {
value string
}{
{"server", context.Server},
- {"cluster", context.Cluster},
{"credential.accessKeyRef", context.Credential.AccessKeyRef},
{"credential.secretKeyRef", context.Credential.SecretKeyRef},
}
diff --git a/rmqctl/internal/config/config_test.go b/rmqctl/internal/config/config_test.go
index 141e6886c..bc6fbe917 100644
--- a/rmqctl/internal/config/config_test.go
+++ b/rmqctl/internal/config/config_test.go
@@ -34,8 +34,7 @@ func TestSave(t *testing.T) {
CurrentContext: "prod",
Contexts: map[string]Context{
"prod": {
- Server: "https://studio.example.com",
- Cluster: "instance-prod",
+ Server: "https://studio.example.com",
Credential: CredentialRef{
AccessKeyRef: "env:RMQ_PROD_AK",
SecretKeyRef: "env:RMQ_PROD_SK",
diff --git a/rmqctl/internal/output/output.go b/rmqctl/internal/output/output.go
index 76ba77a91..8f7aa05a2 100644
--- a/rmqctl/internal/output/output.go
+++ b/rmqctl/internal/output/output.go
@@ -86,15 +86,15 @@ func RequireFormat(format string) error {
func ConfigTable(w io.Writer, cfg config.Config) error {
table := tabwriter.NewWriter(w, 0, 0, 2, ' ', 0)
- fmt.Fprintln(table, "CURRENT\tCONTEXT\tSERVER\tCLUSTER\tACCESS KEY REF\tSECRET KEY REF")
+ fmt.Fprintln(table, "CURRENT\tCONTEXT\tSERVER\tACCESS KEY REF\tSECRET KEY REF")
for _, name := range slices.Sorted(maps.Keys(cfg.Contexts)) {
current := ""
if name == cfg.CurrentContext {
current = "*"
}
context := cfg.Contexts[name]
- fmt.Fprintf(table, "%s\t%s\t%s\t%s\t%s\t%s\n",
- current, name, context.Server, context.Cluster,
+ fmt.Fprintf(table, "%s\t%s\t%s\t%s\t%s\n",
+ current, name, context.Server,
context.Credential.AccessKeyRef, context.Credential.SecretKeyRef)
}
return table.Flush()
@@ -106,9 +106,9 @@ func ToolCallSummary(w io.Writer, result any) error {
return err
}
table := tabwriter.NewWriter(w, 0, 0, 2, ' ', 0)
- fmt.Fprintln(table, "CLUSTER\tSTATUS\tCONFIRM TOKEN")
+ fmt.Fprintln(table, "INSTANCE\tSTATUS\tCONFIRM TOKEN")
fmt.Fprintf(table, "%s\t%s\t%s\n",
- mutation.Cluster, mutation.Status, mutation.ConfirmToken)
+ mutation.InstanceID, mutation.Status, mutation.ConfirmToken)
if err := table.Flush(); err != nil {
return err
}
diff --git a/rmqctl/internal/output/output_test.go b/rmqctl/internal/output/output_test.go
index c5a7cc2e4..b557644b1 100644
--- a/rmqctl/internal/output/output_test.go
+++ b/rmqctl/internal/output/output_test.go
@@ -26,7 +26,7 @@ func TestToolCallSummary(t *testing.T) {
buf := &bytes.Buffer{}
result := map[string]any{
"status": "PLANNED",
- "cluster": "dev",
+ "instanceId": "dev",
"confirm_token": "confirmation-token",
"plan": map[string]any{"summary": "Create topic orders"},
}
diff --git a/rmqctl/internal/studio/auth.go b/rmqctl/internal/studio/auth.go
index 63550bc2a..dc34142a5 100644
--- a/rmqctl/internal/studio/auth.go
+++ b/rmqctl/internal/studio/auth.go
@@ -20,8 +20,8 @@ import (
const (
HMACAlgorithm = "RMQ-HMAC-SHA256"
- HeaderInstance = "X-RMQ-Cluster"
- HeaderTimestamp = "X-RMQ-Timestamp"
+ HeaderInstance = "x-rmq-instance-id"
+ HeaderTimestamp = "x-rmq-timestamp"
)
type AuthTransport struct {
@@ -50,7 +50,7 @@ func signedHTTPClient(client *http.Client, target Target) (*http.Client, error)
func (transport AuthTransport) RoundTrip(request *http.Request) (*http.Response, error) {
clone := request.Clone(request.Context())
clone.Header = request.Header.Clone()
- clone.Header.Set(HeaderInstance, transport.target.Cluster)
+ clone.Header.Set(HeaderInstance, transport.target.InstanceID)
now := time.Now
if transport.now != nil {
now = transport.now
@@ -67,7 +67,7 @@ func (transport AuthTransport) RoundTrip(request *http.Request) (*http.Response,
canonical := canonicalRequest(
transport.target.Credential.AccessKey,
- transport.target.Cluster,
+ transport.target.InstanceID,
timestamp,
clone.Method,
signedPath,
@@ -81,13 +81,14 @@ func (transport AuthTransport) RoundTrip(request *http.Request) (*http.Response,
}
// canonicalRequest builds the string-to-sign for HMAC authentication. The
-// method and escaped path/query bind the request target. The body is not read
-// or authenticated by this protocol. See docs/mcp-hmac.md.
-func canonicalRequest(accessKey, cluster, timestamp, method, path string) string {
+// third line is the Studio instance identifier supplied via --instance-id.
+// The method and escaped path/query bind the request target. The body is not
+// read or authenticated by this protocol. See docs/mcp-hmac.md.
+func canonicalRequest(accessKey, instanceID, timestamp, method, path string) string {
return strings.Join([]string{
HMACAlgorithm,
accessKey,
- cluster,
+ instanceID,
timestamp,
method,
path,
diff --git a/rmqctl/internal/studio/auth_test.go b/rmqctl/internal/studio/auth_test.go
index 7a04647f7..2ba9727c9 100644
--- a/rmqctl/internal/studio/auth_test.go
+++ b/rmqctl/internal/studio/auth_test.go
@@ -26,7 +26,7 @@ type hmacGoldenVector struct {
Name string `json:"name"`
AccessKey string `json:"accessKey"`
SecretKey string `json:"secretKey"`
- Cluster string `json:"cluster"`
+ InstanceID string `json:"instanceId"`
Timestamp string `json:"timestamp"`
Method string `json:"method"`
Path string `json:"path"`
@@ -38,7 +38,7 @@ type hmacGoldenVector struct {
func TestSigningRoundTripperMatchesGoldenVectors(t *testing.T) {
for _, vector := range loadHMACGoldenVectors(t) {
t.Run(vector.Name, func(t *testing.T) {
- canonical := canonicalRequest(vector.AccessKey, vector.Cluster, vector.Timestamp,
+ canonical := canonicalRequest(vector.AccessKey, vector.InstanceID, vector.Timestamp,
vector.Method, vector.Path)
if canonical != vector.CanonicalRequest {
t.Fatalf("canonical request mismatch:\ngot:\n%s\nwant:\n%s", canonical, vector.CanonicalRequest)
@@ -70,7 +70,7 @@ func TestSigningRoundTripperMatchesGoldenVectors(t *testing.T) {
},
target: Target{
Server: "https://studio.example.com",
- Cluster: vector.Cluster,
+ InstanceID: vector.InstanceID,
Credential: Credential{AccessKey: vector.AccessKey, SecretKey: vector.SecretKey},
},
base: roundTripFunc(func(signed *http.Request) (*http.Response, error) {
@@ -79,7 +79,7 @@ func TestSigningRoundTripperMatchesGoldenVectors(t *testing.T) {
if signed.Header.Get("Authorization") != wantAuthorization {
t.Fatalf("Authorization = %q, want %q", signed.Header.Get("Authorization"), wantAuthorization)
}
- if signed.Header.Get(HeaderInstance) != vector.Cluster {
+ if signed.Header.Get(HeaderInstance) != vector.InstanceID {
t.Fatalf("signed headers = %#v", signed.Header)
}
if signed.Header.Get(HeaderTimestamp) != vector.Timestamp {
@@ -115,7 +115,7 @@ func loadHMACGoldenVectors(t *testing.T) []hmacGoldenVector {
if !ok {
t.Fatal("resolve test source path")
}
- path := filepath.Join(filepath.Dir(source), "..", "..", "..", "testdata", "auth-hmac-vectors.json")
+ path := filepath.Join(filepath.Dir(source), "testdata", "auth-hmac-vectors.json")
data, err := os.ReadFile(path)
if err != nil {
t.Fatalf("read required HMAC golden vectors: %v", err)
diff --git a/rmqctl/internal/studio/client.go b/rmqctl/internal/studio/client.go
index dd1e6c287..6eb24f376 100644
--- a/rmqctl/internal/studio/client.go
+++ b/rmqctl/internal/studio/client.go
@@ -39,7 +39,7 @@ const (
type Target struct {
Server string
- Cluster string
+ InstanceID string
Credential Credential
Timeout time.Duration
}
@@ -64,8 +64,8 @@ func (t Target) validate() error {
if server.User != nil || server.RawQuery != "" || server.Fragment != "" {
return fmt.Errorf("studio server URL must not contain user info, a query, or a fragment")
}
- if strings.TrimSpace(t.Cluster) == "" {
- return fmt.Errorf("studio target requires cluster")
+ if strings.TrimSpace(t.InstanceID) == "" {
+ return fmt.Errorf("studio target requires an instance id; pass --instance-id explicitly")
}
if t.Credential.AccessKey == "" || t.Credential.SecretKey == "" {
return fmt.Errorf("studio target requires accessKey and secretKey")
diff --git a/rmqctl/internal/studio/mcp_http.go b/rmqctl/internal/studio/mcp_http.go
index d97eb3e7f..83259e1a0 100644
--- a/rmqctl/internal/studio/mcp_http.go
+++ b/rmqctl/internal/studio/mcp_http.go
@@ -45,9 +45,9 @@ var noRedirectPolicy = func(*http.Request, []*http.Request) error {
// It handles initialize/initialized lifecycle, automatic reconnection on
// session termination, and forwarding of server-initiated notifications.
type MCPClientSession struct {
- cluster string
- transport mcptransport.HTTPConnection
- timeout time.Duration
+ instanceID string
+ transport mcptransport.HTTPConnection
+ timeout time.Duration
closeOnce sync.Once
closed chan struct{}
@@ -101,7 +101,7 @@ func (c Client) NewMCPClientSession(target Target) (*MCPClientSession, error) {
return nil, err
}
session := &MCPClientSession{
- cluster: target.Cluster,
+ instanceID: target.InstanceID,
transport: transport,
timeout: target.Timeout,
closed: make(chan struct{}),
diff --git a/rmqctl/internal/studio/mcp_http_test.go b/rmqctl/internal/studio/mcp_http_test.go
index 138930a37..4295c3c3c 100644
--- a/rmqctl/internal/studio/mcp_http_test.go
+++ b/rmqctl/internal/studio/mcp_http_test.go
@@ -92,7 +92,7 @@ func TestSessionStreamsPostSSEWithoutContinuousGet(t *testing.T) {
}
})})
session := newMCPTestSession(t, client, Target{
- Server: "http://localhost", Cluster: "instance-dev",
+ Server: "http://localhost", InstanceID: "instance-dev",
Credential: Credential{AccessKey: "test-ak", SecretKey: "test-sk"}, Timeout: time.Second,
})
ctx, cancel := context.WithCancel(context.Background())
diff --git a/rmqctl/internal/studio/mcp_message.go b/rmqctl/internal/studio/mcp_message.go
index 9f0c4ed84..49bbeccf0 100644
--- a/rmqctl/internal/studio/mcp_message.go
+++ b/rmqctl/internal/studio/mcp_message.go
@@ -23,6 +23,7 @@ import (
"fmt"
"log/slog"
+ toolcatalog "github.com/apache/rocketmq-dashboard/rmqctl/internal/catalog"
mcptransport "github.com/mark3labs/mcp-go/client/transport"
"github.com/mark3labs/mcp-go/mcp"
)
@@ -33,7 +34,7 @@ import (
// 404/session-terminated errors.
func (session *MCPClientSession) SendMessage(ctx context.Context, payload json.RawMessage) (json.RawMessage, bool, error) {
var bindErr error
- payload, bindErr = bindToolInstance(payload, session.cluster)
+ payload, bindErr = bindToolInstance(payload, session.instanceID)
if bindErr != nil {
return nil, false, bindErr
}
@@ -271,31 +272,50 @@ func (session *MCPClientSession) enqueueNotification(payload json.RawMessage) {
}
}
-// bindToolInstance fills only an absent tools/call argument. Explicit values remain subject
-// to the server's canonical Instance identity check against X-RMQ-Cluster.
-func bindToolInstance(payload json.RawMessage, cluster string) (json.RawMessage, error) {
+// bindToolInstance passes the explicit --instance-id value through to tools/call
+// arguments, but only for tools whose catalog input schema declares an instance
+// identifier field (instanceId, or the transitional cluster name). Platform-level
+// tools (no instance field in the schema) and tools unknown to the catalog are
+// left untouched. Values explicitly provided by the MCP client are preserved and
+// remain subject to the server's canonical Instance identity check against the
+// x-rmq-instance-id header.
+func bindToolInstance(payload json.RawMessage, instanceID string) (json.RawMessage, error) {
var message map[string]json.RawMessage
if err := json.Unmarshal(payload, &message); err != nil {
return nil, err
}
var method string
- if err := json.Unmarshal(message["method"], &method); err != nil || method != "tools/call" || cluster == "" {
+ if err := json.Unmarshal(message["method"], &method); err != nil || method != "tools/call" || instanceID == "" {
return payload, nil
}
var params map[string]json.RawMessage
if err := json.Unmarshal(message["params"], ¶ms); err != nil || params == nil {
return payload, nil
}
+ var toolName string
+ if raw, ok := params["name"]; ok {
+ if err := json.Unmarshal(raw, &toolName); err != nil {
+ return payload, nil
+ }
+ }
+ tool, exists := toolcatalog.LookupTool(toolName)
+ if !exists {
+ return payload, nil
+ }
+ fieldName, declaresInstance := toolcatalog.InstanceFieldName(tool.InputSchema)
+ if !declaresInstance {
+ return payload, nil
+ }
arguments := map[string]json.RawMessage{}
if raw, ok := params["arguments"]; ok {
if err := json.Unmarshal(raw, &arguments); err != nil || arguments == nil {
return payload, nil
}
}
- if _, exists := arguments["cluster"]; exists {
+ if _, exists := arguments[fieldName]; exists {
return payload, nil
}
- arguments["cluster"], _ = json.Marshal(cluster)
+ arguments[fieldName], _ = json.Marshal(instanceID)
params["arguments"], _ = json.Marshal(arguments)
message["params"], _ = json.Marshal(params)
return json.Marshal(message)
diff --git a/rmqctl/internal/studio/mcp_message_test.go b/rmqctl/internal/studio/mcp_message_test.go
new file mode 100644
index 000000000..36341238b
--- /dev/null
+++ b/rmqctl/internal/studio/mcp_message_test.go
@@ -0,0 +1,125 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package studio
+
+import (
+ "encoding/json"
+ "testing"
+)
+
+func toolCallPayload(t *testing.T, tool string, arguments map[string]any) []byte {
+ t.Helper()
+ params := map[string]any{"name": tool}
+ if arguments != nil {
+ params["arguments"] = arguments
+ }
+ payload, err := json.Marshal(map[string]any{
+ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": params,
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ return payload
+}
+
+func boundArguments(t *testing.T, payload []byte) map[string]any {
+ t.Helper()
+ var message struct {
+ Params struct {
+ Arguments map[string]any `json:"arguments"`
+ } `json:"params"`
+ }
+ if err := json.Unmarshal(payload, &message); err != nil {
+ t.Fatal(err)
+ }
+ return message.Params.Arguments
+}
+
+// TestBindToolInstanceInjectsDeclaredInstanceField verifies that the explicit
+// --instance-id value is passed through to tools whose catalog schema declares
+// the instance identifier field (instanceId, or the transitional cluster name
+// in the pre-regeneration catalog).
+func TestBindToolInstanceInjectsDeclaredInstanceField(t *testing.T) {
+ payload := toolCallPayload(t, "rmq.topic.list", nil)
+ bound, err := bindToolInstance(payload, "instance-dev")
+ if err != nil {
+ t.Fatal(err)
+ }
+ arguments := boundArguments(t, bound)
+ if len(arguments) != 1 {
+ t.Fatalf("arguments = %#v, want exactly one injected instance field", arguments)
+ }
+ for _, name := range []string{"instanceId", "cluster"} {
+ if value, ok := arguments[name]; ok {
+ if value != "instance-dev" {
+ t.Fatalf("%s = %#v, want instance-dev", name, value)
+ }
+ return
+ }
+ }
+ t.Fatalf("no instance identifier injected: %#v", arguments)
+}
+
+// TestBindToolInstanceKeepsExplicitValue verifies pass-through semantics: a
+// value explicitly provided by the MCP client is never overwritten.
+func TestBindToolInstanceKeepsExplicitValue(t *testing.T) {
+ payload := toolCallPayload(t, "rmq.topic.list", map[string]any{"instanceId": "explicit-instance"})
+ bound, err := bindToolInstance(payload, "instance-dev")
+ if err != nil {
+ t.Fatal(err)
+ }
+ arguments := boundArguments(t, bound)
+ if len(arguments) != 1 {
+ t.Fatalf("arguments = %#v, want only the explicit client value", arguments)
+ }
+ if value := arguments["instanceId"]; value != "explicit-instance" {
+ t.Fatalf("instanceId = %#v, want the explicit client value", value)
+ }
+}
+
+// TestBindToolInstanceSkipsToolsWithoutInstanceField verifies that tools whose
+// catalog schema declares no instance identifier are never modified. Today this
+// covers tools unknown to the catalog; after the catalog regeneration it also
+// covers the 11 platform-level tools (decisions 25/26) whose schemas drop
+// instanceId.
+func TestBindToolInstanceSkipsToolsWithoutInstanceField(t *testing.T) {
+ payload := toolCallPayload(t, "rmq.platform.probe.unknown", map[string]any{"topicName": "orders"})
+ original := string(payload)
+ bound, err := bindToolInstance(payload, "instance-dev")
+ if err != nil {
+ t.Fatal(err)
+ }
+ if string(bound) != original {
+ t.Fatalf("payload was modified: %s", bound)
+ }
+ if arguments := boundArguments(t, bound); arguments["instanceId"] != nil || arguments["cluster"] != nil {
+ t.Fatalf("instance identifier leaked into arguments: %#v", arguments)
+ }
+}
+
+// TestBindToolInstanceIgnoresNonToolCallMessages verifies that initialize and
+// other JSON-RPC methods are forwarded untouched.
+func TestBindToolInstanceIgnoresNonToolCallMessages(t *testing.T) {
+ payload := []byte(`{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}`)
+ bound, err := bindToolInstance(payload, "instance-dev")
+ if err != nil {
+ t.Fatal(err)
+ }
+ if string(bound) != string(payload) {
+ t.Fatalf("initialize payload was modified: %s", bound)
+ }
+}
diff --git a/rmqctl/internal/studio/testdata/auth-hmac-vectors.json b/rmqctl/internal/studio/testdata/auth-hmac-vectors.json
new file mode 100644
index 000000000..951b1f8b0
--- /dev/null
+++ b/rmqctl/internal/studio/testdata/auth-hmac-vectors.json
@@ -0,0 +1,38 @@
+[
+ {
+ "name": "get_tools_list",
+ "accessKey": "AKEXAMPLE",
+ "secretKey": "SKEXAMPLESECRET",
+ "instanceId": "open-source-local",
+ "timestamp": "1757600000000",
+ "method": "GET",
+ "path": "/api/mcp/tools/list",
+ "body": "",
+ "canonicalRequest": "RMQ-HMAC-SHA256\nAKEXAMPLE\nopen-source-local\n1757600000000\nGET\n/api/mcp/tools/list",
+ "signature": "29501e8c88ee8f20a520ba62f51942177c87dd8eff234cd0e9fa637321957786"
+ },
+ {
+ "name": "post_tool_call",
+ "accessKey": "AKEXAMPLE2",
+ "secretKey": "SKEXAMPLE2SECRET",
+ "instanceId": "rmq-cluster",
+ "timestamp": "1757600001234",
+ "method": "POST",
+ "path": "/api/mcp/tools/call",
+ "body": "{\"tool\":\"rmq.topic.list\",\"args\":{}}",
+ "canonicalRequest": "RMQ-HMAC-SHA256\nAKEXAMPLE2\nrmq-cluster\n1757600001234\nPOST\n/api/mcp/tools/call",
+ "signature": "adfae00b6d7c482d5589df19d97b06ee1625a98fac84fc113482d9d0b1fe0ae8"
+ },
+ {
+ "name": "post_tool_call_unicode_instance_id",
+ "accessKey": "AK~EXAMPLE.3",
+ "secretKey": "SKEXAMPLE3SECRET",
+ "instanceId": "instance with space",
+ "timestamp": "1757699999999",
+ "method": "POST",
+ "path": "/api/mcp/tools/call",
+ "body": "{\"tool\":\"rmq.group.list\"}",
+ "canonicalRequest": "RMQ-HMAC-SHA256\nAK~EXAMPLE.3\ninstance with space\n1757699999999\nPOST\n/api/mcp/tools/call",
+ "signature": "531af609282d32154f5a6f6962aec5cddf867c659a8c334c4bb5e16002f9dc9d"
+ }
+]
diff --git a/rmqctl/internal/studio/tools_test.go b/rmqctl/internal/studio/tools_test.go
index f091bb5df..c8513dd4e 100644
--- a/rmqctl/internal/studio/tools_test.go
+++ b/rmqctl/internal/studio/tools_test.go
@@ -54,9 +54,9 @@ func TestCallTool(t *testing.T) {
client := NewClient(server.Client())
result, err := client.CallTool(context.Background(), Target{
- Server: server.URL, Cluster: "instance-dev",
+ Server: server.URL, InstanceID: "instance-dev",
Credential: Credential{AccessKey: "test-ak", SecretKey: "test-sk"}, Timeout: time.Second,
- }, "rmq.topic.list", map[string]any{"cluster": "dev"})
+ }, "rmq.topic.list", map[string]any{"instanceId": "instance-dev"})
resultMap, ok := result.(map[string]any)
if err != nil || !ok || resultMap["items"] == nil {
t.Fatalf("result=%#v err=%v", result, err)
@@ -70,13 +70,13 @@ func TestCallToolKeepsCatalogControlsInArguments(t *testing.T) {
t.Fatal(err)
}
if request.Arguments["dry_run"] != true ||
- request.Arguments["topic"] != "orders" {
+ request.Arguments["topicName"] != "orders" {
t.Errorf("unexpected transport request: %#v", request)
}
_ = json.NewEncoder(w).Encode(map[string]any{
"code": 200, "message": "success", "data": map[string]any{
"status": "PLANNED",
- "cluster": "dev",
+ "instanceId": "instance-dev",
"confirm_token": "confirmation", "plan": map[string]any{"summary": "create"},
},
})
@@ -85,10 +85,10 @@ func TestCallToolKeepsCatalogControlsInArguments(t *testing.T) {
client := NewClient(server.Client())
result, err := client.CallTool(context.Background(), Target{
- Server: server.URL, Cluster: "instance-dev",
+ Server: server.URL, InstanceID: "instance-dev",
Credential: Credential{AccessKey: "test-ak", SecretKey: "test-sk"}, Timeout: time.Second,
- }, "rmq.topic.create", map[string]any{
- "cluster": "dev", "topic": "orders", "dry_run": true,
+ }, "rmq.topic.update", map[string]any{
+ "instanceId": "instance-dev", "topicName": "orders", "dry_run": true,
})
if err != nil {
t.Fatal(err)
diff --git a/rmqctl/internal/types/types.go b/rmqctl/internal/types/types.go
index 9d3601a6b..5f6f59578 100644
--- a/rmqctl/internal/types/types.go
+++ b/rmqctl/internal/types/types.go
@@ -30,7 +30,7 @@ type ResultEnvelope struct {
// MutationOutput is the result payload returned by L2/L3 tools.
type MutationOutput struct {
Status MutationStatus `json:"status"`
- Cluster string `json:"cluster"`
+ InstanceID string `json:"instanceId"`
Plan any `json:"plan"`
ConfirmToken string `json:"confirm_token,omitempty"`
Result any `json:"result,omitempty"`