Add mutable-messages flag to channel rules

sacOO7 · umair-ably · commit cb8fa5407aa7 · 2026-03-11T14:02:58.000Z
Add --mutable-messages flag to channel-rules create and update commands,
enabling message editing and deletion on channels. Persistence is
automatically enabled when mutable messages is set. Validation prevents
disabling persistence while mutable messages is active.
diff --git a/src/commands/apps/channel-rules/create.ts b/src/commands/apps/channel-rules/create.ts
@@ -2,13 +2,18 @@ import { Flags } from "@oclif/core";
 
 import { ControlBaseCommand } from "../../../control-base-command.js";
 import { formatChannelRuleDetails } from "../../../utils/channel-rule-display.js";
-import { formatSuccess } from "../../../utils/output.js";
+import {
+  formatLabel,
+  formatSuccess,
+  formatWarning,
+} from "../../../utils/output.js";
 
 export default class ChannelRulesCreateCommand extends ControlBaseCommand {
   static description = "Create a channel rule";
 
   static examples = [
     '$ ably apps channel-rules create --name "chat" --persisted',
+    '$ ably apps channel-rules create --name "chat" --mutable-messages',
     '$ ably apps channel-rules create --name "events" --push-enabled',
     '$ ably apps channel-rules create --name "notifications" --persisted --push-enabled --app "My App"',
     '$ ably apps channel-rules create --name "chat" --persisted --json',
@@ -55,6 +60,11 @@ export default class ChannelRulesCreateCommand extends ControlBaseCommand {
         "Whether to expose the time serial for messages on channels matching this rule",
       required: false,
     }),
+    "mutable-messages": Flags.boolean({
+      description:
+        "Whether messages on channels matching this rule can be updated or deleted after publishing. Automatically enables message persistence",
+      required: false,
+    }),
     name: Flags.string({
       description: "Name of the channel rule",
       required: true,
@@ -94,6 +104,22 @@ export default class ChannelRulesCreateCommand extends ControlBaseCommand {
 
     try {
       const controlApi = this.createControlApi(flags);
+
+      // When mutableMessages is enabled, persisted must also be enabled
+      const mutableMessages = flags["mutable-messages"];
+      let persisted = flags.persisted;
+
+      if (mutableMessages) {
+        persisted = true;
+        if (!this.shouldOutputJson(flags)) {
+          this.logToStderr(
+            formatWarning(
+              "Message persistence is automatically enabled when mutable messages is enabled.",
+            ),
+          );
+        }
+      }
+
       const namespaceData = {
         authenticated: flags.authenticated,
         batchingEnabled: flags["batching-enabled"],
@@ -103,8 +129,9 @@ export default class ChannelRulesCreateCommand extends ControlBaseCommand {
         conflationInterval: flags["conflation-interval"],
         conflationKey: flags["conflation-key"],
         exposeTimeSerial: flags["expose-time-serial"],
+        mutableMessages,
         persistLast: flags["persist-last"],
-        persisted: flags.persisted,
+        persisted,
         populateChannelRegistry: flags["populate-channel-registry"],
         pushEnabled: flags["push-enabled"],
         tlsOnly: flags["tls-only"],
@@ -129,6 +156,7 @@ export default class ChannelRulesCreateCommand extends ControlBaseCommand {
               created: new Date(createdNamespace.created).toISOString(),
               exposeTimeSerial: createdNamespace.exposeTimeSerial,
               id: createdNamespace.id,
+              mutableMessages: createdNamespace.mutableMessages,
               name: flags.name,
               persistLast: createdNamespace.persistLast,
               persisted: createdNamespace.persisted,
@@ -142,7 +170,7 @@ export default class ChannelRulesCreateCommand extends ControlBaseCommand {
         );
       } else {
         this.log(formatSuccess("Channel rule created."));
-        this.log(`ID: ${createdNamespace.id}`);
+        this.log(`${formatLabel("ID")} ${createdNamespace.id}`);
         for (const line of formatChannelRuleDetails(createdNamespace, {
           formatDate: (t) => this.formatDate(t),
         })) {
diff --git a/src/commands/apps/channel-rules/index.ts b/src/commands/apps/channel-rules/index.ts
@@ -9,6 +9,7 @@ export default class ChannelRulesIndexCommand extends BaseTopicCommand {
   static examples = [
     "ably apps channel-rules list",
     'ably apps channel-rules create --name "chat" --persisted',
+    "ably apps channel-rules update chat --mutable-messages",
     "ably apps channel-rules update chat --push-enabled",
     "ably apps channel-rules delete chat",
   ];
diff --git a/src/commands/apps/channel-rules/list.ts b/src/commands/apps/channel-rules/list.ts
@@ -16,6 +16,7 @@ interface ChannelRuleOutput {
   exposeTimeSerial: boolean;
   id: string;
   modified: string;
+  mutableMessages: boolean;
   persistLast: boolean;
   persisted: boolean;
   populateChannelRegistry: boolean;
@@ -65,6 +66,7 @@ export default class ChannelRulesListCommand extends ControlBaseCommand {
                 exposeTimeSerial: rule.exposeTimeSerial || false,
                 id: rule.id,
                 modified: new Date(rule.modified).toISOString(),
+                mutableMessages: rule.mutableMessages || false,
                 persistLast: rule.persistLast || false,
                 persisted: rule.persisted || false,
                 populateChannelRegistry: rule.populateChannelRegistry || false,
diff --git a/src/commands/apps/channel-rules/update.ts b/src/commands/apps/channel-rules/update.ts
@@ -2,6 +2,11 @@ import { Args, Flags } from "@oclif/core";
 
 import { ControlBaseCommand } from "../../../control-base-command.js";
 import { formatChannelRuleDetails } from "../../../utils/channel-rule-display.js";
+import {
+  formatLabel,
+  formatSuccess,
+  formatWarning,
+} from "../../../utils/output.js";
 
 export default class ChannelRulesUpdateCommand extends ControlBaseCommand {
   static args = {
@@ -15,6 +20,7 @@ export default class ChannelRulesUpdateCommand extends ControlBaseCommand {
 
   static examples = [
     "$ ably apps channel-rules update chat --persisted",
+    "$ ably apps channel-rules update chat --mutable-messages",
     "$ ably apps channel-rules update events --push-enabled=false",
     '$ ably apps channel-rules update notifications --persisted --push-enabled --app "My App"',
     "$ ably apps channel-rules update chat --persisted --json",
@@ -65,6 +71,12 @@ export default class ChannelRulesUpdateCommand extends ControlBaseCommand {
         "Whether to expose the time serial for messages on channels matching this rule",
       required: false,
     }),
+    "mutable-messages": Flags.boolean({
+      allowNo: true,
+      description:
+        "Whether messages on channels matching this rule can be updated or deleted after publishing. Automatically enables message persistence",
+      required: false,
+    }),
     "persist-last": Flags.boolean({
       allowNo: true,
       description:
@@ -120,10 +132,37 @@ export default class ChannelRulesUpdateCommand extends ControlBaseCommand {
       const updateData: Record<string, boolean | number | string | undefined> =
         {};
 
+      // Validation for mutable-messages flag, checks with supplied/existing mutableMessages flag
+      if (
+        flags.persisted === false &&
+        (flags["mutable-messages"] || namespace.mutableMessages)
+      ) {
+        this.fail(
+          "Cannot disable persistence when mutable messages is enabled. Mutable messages requires message persistence.",
+          flags,
+          "channelRuleUpdate",
+          { appId, ruleId: namespace.id },
+        );
+      }
+
       if (flags.persisted !== undefined) {
         updateData.persisted = flags.persisted;
       }
 
+      if (flags["mutable-messages"] !== undefined) {
+        updateData.mutableMessages = flags["mutable-messages"];
+        if (flags["mutable-messages"]) {
+          updateData.persisted = true;
+          if (!this.shouldOutputJson(flags)) {
+            this.logToStderr(
+              formatWarning(
+                "Message persistence is automatically enabled when mutable messages is enabled.",
+              ),
+            );
+          }
+        }
+      }
+
       if (flags["push-enabled"] !== undefined) {
         updateData.pushEnabled = flags["push-enabled"];
       }
@@ -199,6 +238,7 @@ export default class ChannelRulesUpdateCommand extends ControlBaseCommand {
               exposeTimeSerial: updatedNamespace.exposeTimeSerial,
               id: updatedNamespace.id,
               modified: new Date(updatedNamespace.modified).toISOString(),
+              mutableMessages: updatedNamespace.mutableMessages,
               persistLast: updatedNamespace.persistLast,
               persisted: updatedNamespace.persisted,
               populateChannelRegistry: updatedNamespace.populateChannelRegistry,
@@ -210,8 +250,8 @@ export default class ChannelRulesUpdateCommand extends ControlBaseCommand {
           flags,
         );
       } else {
-        this.log("Channel rule updated successfully:");
-        this.log(`ID: ${updatedNamespace.id}`);
+        this.log(formatSuccess("Channel rule updated."));
+        this.log(`${formatLabel("ID")} ${updatedNamespace.id}`);
         for (const line of formatChannelRuleDetails(updatedNamespace, {
           formatDate: (t) => this.formatDate(t),
           showTimestamps: true,
diff --git a/src/services/control-api.ts b/src/services/control-api.ts
@@ -57,6 +57,7 @@ export interface Namespace {
   exposeTimeSerial?: boolean;
   id: string;
   modified: number;
+  mutableMessages?: boolean;
   persistLast?: boolean;
   persisted: boolean;
   populateChannelRegistry?: boolean;
@@ -231,6 +232,7 @@ export class ControlApi {
       conflationInterval?: number;
       conflationKey?: string;
       exposeTimeSerial?: boolean;
+      mutableMessages?: boolean;
       persistLast?: boolean;
       persisted?: boolean;
       populateChannelRegistry?: boolean;
@@ -457,6 +459,7 @@ export class ControlApi {
       conflationInterval?: number;
       conflationKey?: string;
       exposeTimeSerial?: boolean;
+      mutableMessages?: boolean;
       persistLast?: boolean;
       persisted?: boolean;
       populateChannelRegistry?: boolean;
diff --git a/src/utils/channel-rule-display.ts b/src/utils/channel-rule-display.ts
@@ -43,6 +43,10 @@ export function formatChannelRuleDetails(
     `${indent}Push Enabled: ${bool(rule.pushEnabled)}`,
   );
 
+  if (rule.mutableMessages !== undefined) {
+    lines.push(`${indent}Mutable Messages: ${bool(rule.mutableMessages)}`);
+  }
+
   if (rule.authenticated !== undefined) {
     lines.push(`${indent}Authenticated: ${bool(rule.authenticated)}`);
   }
diff --git a/test/unit/commands/apps/channel-rules/create.test.ts b/test/unit/commands/apps/channel-rules/create.test.ts
@@ -79,6 +79,73 @@ describe("apps:channel-rules:create command", () => {
       expect(stdout).toContain("Push Enabled: Yes");
     });
 
+    it("should create a channel rule with mutable-messages flag and auto-enable persisted", async () => {
+      const appId = getMockConfigManager().getCurrentAppId()!;
+      nock("https://control.ably.net")
+        .post(`/v1/apps/${appId}/namespaces`, (body) => {
+          return body.mutableMessages === true && body.persisted === true;
+        })
+        .reply(201, {
+          id: mockRuleId,
+          persisted: true,
+          pushEnabled: false,
+          mutableMessages: true,
+          created: Date.now(),
+          modified: Date.now(),
+        });
+
+      const { stdout, stderr } = await runCommand(
+        [
+          "apps:channel-rules:create",
+          "--name",
+          mockRuleName,
+          "--mutable-messages",
+        ],
+        import.meta.url,
+      );
+
+      expect(stdout).toContain("Channel rule created.");
+      expect(stdout).toContain("Persisted: Yes");
+      expect(stdout).toContain("Mutable Messages: Yes");
+      expect(stderr).toContain(
+        "Message persistence is automatically enabled when mutable messages is enabled.",
+      );
+    });
+
+    it("should include mutableMessages in JSON output when --mutable-messages is used", async () => {
+      const appId = getMockConfigManager().getCurrentAppId()!;
+      nock("https://control.ably.net")
+        .post(`/v1/apps/${appId}/namespaces`, (body) => {
+          return body.mutableMessages === true && body.persisted === true;
+        })
+        .reply(201, {
+          id: mockRuleId,
+          persisted: true,
+          pushEnabled: false,
+          mutableMessages: true,
+          created: Date.now(),
+          modified: Date.now(),
+        });
+
+      const { stdout, stderr } = await runCommand(
+        [
+          "apps:channel-rules:create",
+          "--name",
+          mockRuleName,
+          "--mutable-messages",
+          "--json",
+        ],
+        import.meta.url,
+      );
+
+      const result = JSON.parse(stdout);
+      expect(result).toHaveProperty("success", true);
+      expect(result.rule).toHaveProperty("mutableMessages", true);
+      expect(result.rule).toHaveProperty("persisted", true);
+      // Warning should not appear in JSON mode
+      expect(stderr).not.toContain("Warning");
+    });
+
     it("should output JSON format when --json flag is used", async () => {
       const appId = getMockConfigManager().getCurrentAppId()!;
       const mockRule = {
diff --git a/test/unit/commands/apps/channel-rules/list.test.ts b/test/unit/commands/apps/channel-rules/list.test.ts
@@ -84,6 +84,69 @@ describe("apps:channel-rules:list command", () => {
       expect(stdout).toContain("Persisted: ✓ Yes");
       expect(stdout).toContain("Push Enabled: ✓ Yes");
     });
+
+    it("should display mutableMessages in rule details", async () => {
+      const appId = getMockConfigManager().getCurrentAppId()!;
+      const mockRules = [
+        {
+          id: "mutable-chat",
+          persisted: true,
+          pushEnabled: false,
+          mutableMessages: true,
+          created: Date.now(),
+          modified: Date.now(),
+        },
+      ];
+
+      nock("https://control.ably.net")
+        .get(`/v1/apps/${appId}/namespaces`)
+        .reply(200, mockRules);
+
+      const { stdout } = await runCommand(
+        ["apps:channel-rules:list"],
+        import.meta.url,
+      );
+
+      expect(stdout).toContain("Found 1 channel rules");
+      expect(stdout).toContain("mutable-chat");
+      expect(stdout).toContain("Mutable Messages: ✓ Yes");
+    });
+
+    it("should include mutableMessages in JSON output", async () => {
+      const appId = getMockConfigManager().getCurrentAppId()!;
+      const mockRules = [
+        {
+          id: "mutable-chat",
+          persisted: true,
+          pushEnabled: false,
+          mutableMessages: true,
+          created: Date.now(),
+          modified: Date.now(),
+        },
+        {
+          id: "regular-chat",
+          persisted: false,
+          pushEnabled: false,
+          created: Date.now(),
+          modified: Date.now(),
+        },
+      ];
+
+      nock("https://control.ably.net")
+        .get(`/v1/apps/${appId}/namespaces`)
+        .reply(200, mockRules);
+
+      const { stdout } = await runCommand(
+        ["apps:channel-rules:list", "--json"],
+        import.meta.url,
+      );
+
+      const result = JSON.parse(stdout);
+      expect(result).toHaveProperty("success", true);
+      expect(result.rules).toHaveLength(2);
+      expect(result.rules[0]).toHaveProperty("mutableMessages", true);
+      expect(result.rules[1]).toHaveProperty("mutableMessages", false);
+    });
   });
 
   describe("error handling", () => {
diff --git a/test/unit/commands/apps/channel-rules/update.test.ts b/test/unit/commands/apps/channel-rules/update.test.ts
diff --git a/test/unit/commands/channel-rule/update.test.ts b/test/unit/commands/channel-rule/update.test.ts
