feat(rules)!: create channel rules as match expressions

Channel rules now come in two modes. A `matcher` rule's id is a match
expression, with the same syntax as a capability resource ("chat:*",
"*:presence", "foo:*:baz"); a `namespace` rule's id is a single segment
that matches that channel plus everything beneath it. New rules should
be matchers - the dashboard only creates matchers - so `rules create`
now always does. `rules update` sends no mode, so a rule keeps the one
it was created with. `create`, `update` and `list` show each rule's
mode, since the same-looking id means different things in each.

BREAKING CHANGE: `ably apps rules create "chat"` used to create a rule
applying to `chat` and every channel beneath it (`chat:room1`, ...). It
now applies to the channel `chat` alone. To select the channels beneath
it, use `ably apps rules create "chat:*"`. Existing rules are unaffected
and keep matching as before.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: SimonWoolf

src/commands/apps/rules/create.ts

@@ -9,17 +9,18 @@ export default class RulesCreateCommand extends ControlBaseCommand {
 
   static args = {
     ruleName: Args.string({
-      description: "Name of the rule",
+      description:
+        'Match expression selecting the channels the rule applies to, e.g. "chat:*" or "*:presence"',
       required: true,
     }),
   };
 
   static examples = [
-    '$ ably apps rules create "chat" --persisted',
-    '$ ably apps rules create "chat" --mutable-messages',
-    '$ ably apps rules create "events" --push-enabled',
-    '$ ably apps rules create "notifications" --persisted --push-enabled --app "My App"',
-    '$ ably apps rules create "chat" --persisted --json',
+    '$ ably apps rules create "chat:*" --persisted',
+    '$ ably apps rules create "chat:*" --mutable-messages',
+    '$ ably apps rules create "*:presence" --push-enabled',
+    '$ ably apps rules create "notifications:*" --persisted --push-enabled --app "My App"',
+    '$ ably apps rules create "chat:*" --persisted --json',
   ];
 
   static flags = {
@@ -119,6 +120,7 @@ export default class RulesCreateCommand extends ControlBaseCommand {
         conflationEnabled: flags["conflation-enabled"],
         conflationInterval: flags["conflation-interval"],
         conflationKey: flags["conflation-key"],
+        mode: "matcher" as const,
         mutableMessages,
         persistLast: flags["persist-last"],
         persisted,
@@ -145,6 +147,7 @@ export default class RulesCreateCommand extends ControlBaseCommand {
               conflationKey: createdNamespace.conflationKey ?? null,
               created: new Date(createdNamespace.created).toISOString(),
               id: createdNamespace.id,
+              mode: createdNamespace.mode ?? null,
               modified: new Date(createdNamespace.modified).toISOString(),
               mutableMessages: createdNamespace.mutableMessages || false,
               persistLast: createdNamespace.persistLast || false,

src/commands/apps/rules/index.ts

@@ -4,12 +4,12 @@ export default class RulesIndexCommand extends BaseTopicCommand {
   protected topicName = "apps:rules";
   protected commandGroup = "rules";
 
-  static description = "Manage Ably rules (namespaces)";
+  static description = "Manage Ably channel rules";
 
   static examples = [
     "$ ably apps rules list",
-    '$ ably apps rules create "chat" --persisted',
-    '$ ably apps rules update "chat" --push-enabled',
-    '$ ably apps rules delete "chat"',
+    '$ ably apps rules create "chat:*" --persisted',
+    '$ ably apps rules update "chat:*" --push-enabled',
+    '$ ably apps rules delete "chat:*"',
   ];
 }

src/commands/apps/rules/list.ts

@@ -1,5 +1,8 @@
 import { Flags } from "@oclif/core";
-import type { Namespace } from "../../../services/control-api.js";
+import type {
+  ChannelRuleMode,
+  Namespace,
+} from "../../../services/control-api.js";
 
 import { ControlBaseCommand } from "../../../control-base-command.js";
 import { formatChannelRuleDetails } from "../../../utils/channel-rule-display.js";
@@ -18,6 +21,7 @@ interface ChannelRuleOutput {
   conflationKey: null | string;
   created: string;
   id: string;
+  mode: ChannelRuleMode | null;
   modified: string;
   mutableMessages: boolean;
   persistLast: boolean;
@@ -76,6 +80,7 @@ export default class RulesListCommand extends ControlBaseCommand {
                 conflationKey: rule.conflationKey ?? null,
                 created: new Date(rule.created).toISOString(),
                 id: rule.id,
+                mode: rule.mode ?? null,
                 modified: new Date(rule.modified).toISOString(),
                 mutableMessages: rule.mutableMessages || false,
                 persistLast: rule.persistLast || false,

src/commands/apps/rules/update.ts

@@ -238,6 +238,7 @@ export default class RulesUpdateCommand extends ControlBaseCommand {
               conflationKey: updatedNamespace.conflationKey ?? null,
               created: new Date(updatedNamespace.created).toISOString(),
               id: updatedNamespace.id,
+              mode: updatedNamespace.mode ?? null,
               modified: new Date(updatedNamespace.modified).toISOString(),
               mutableMessages: updatedNamespace.mutableMessages || false,
               persistLast: updatedNamespace.persistLast || false,

src/services/control-api.ts

@@ -65,6 +65,11 @@ export interface Key {
   status: string;
 }
 
+// `matcher` rules select channels by match expression (e.g. "chat:*");
+// `namespace` rules predate them and match a first segment plus everything
+// beneath it. A rule's mode is fixed at creation.
+export type ChannelRuleMode = "matcher" | "namespace";
+
 export interface Namespace {
   appId: string;
   authenticated?: boolean;
@@ -76,6 +81,7 @@ export interface Namespace {
   created: number;
   exposeTimeSerial?: boolean;
   id: string;
+  mode?: ChannelRuleMode;
   modified: number;
   mutableMessages?: boolean;
   persistLast?: boolean;
@@ -338,6 +344,7 @@ export class ControlApi {
       conflationInterval?: number;
       conflationKey?: string;
       exposeTimeSerial?: boolean;
+      mode?: ChannelRuleMode;
       mutableMessages?: boolean;
       persistLast?: boolean;
       persisted?: boolean;

src/utils/channel-rule-display.ts

@@ -37,10 +37,16 @@ export function formatChannelRuleDetails(
     showTimestamps = true,
   } = options;
   const bool = bold ? boolFieldBold : boolField;
-  const lines: string[] = [
+  const lines: string[] = [];
+
+  if (rule.mode) {
+    lines.push(`${indent}${formatLabel("Mode")} ${rule.mode}`);
+  }
+
+  lines.push(
     `${indent}${formatLabel("Persisted")} ${bool(rule.persisted)}`,
     `${indent}${formatLabel("Push Enabled")} ${bool(rule.pushEnabled)}`,
-  ];
+  );
 
   if (rule.mutableMessages !== undefined) {
     lines.push(

test/fixtures/control-api.ts

@@ -4,6 +4,8 @@
  * These provide realistic default values that can be overridden per-test.
  */
 
+import type { ChannelRuleMode } from "../../src/services/control-api.js";
+
 export interface MockApp {
   id: string;
   accountId: string;
@@ -134,6 +136,7 @@ export interface MockNamespace {
   id: string;
   persisted: boolean;
   pushEnabled: boolean;
+  mode?: ChannelRuleMode;
   mutableMessages?: boolean;
   created: number;
   modified: number;

test/unit/commands/apps/rules/create.test.ts

@@ -157,6 +157,23 @@ describe("apps:rules:create command", () => {
       expect(result!.rule).toHaveProperty("persisted", true);
       expect(result!.rule).toHaveProperty("mutableMessages", true);
     });
+
+    it("should always create a matcher-mode rule", async () => {
+      const appId = getMockConfigManager().getCurrentAppId()!;
+      nockControl()
+        .post(`/v1/apps/${appId}/namespaces`, (body) => {
+          return body.id === "chat:*" && body.mode === "matcher";
+        })
+        .reply(201, mockNamespace({ id: "chat:*", mode: "matcher" }));
+
+      const { stdout } = await runCommand(
+        ["apps:rules:create", "chat:*", "--json"],
+        import.meta.url,
+      );
+
+      const result = parseNdjsonLines(stdout).find((r) => r.type === "result")!;
+      expect(result.rule).toHaveProperty("mode", "matcher");
+    });
   });
 
   describe("error handling", () => {

test/unit/commands/apps/rules/list.test.ts

@@ -122,6 +122,31 @@ describe("apps:rules:list command", () => {
       expect(result).toHaveProperty("success", true);
       expect(result.rules).toHaveLength(2);
     });
+
+    it("should show each rule's mode", async () => {
+      const appId = getMockConfigManager().getCurrentAppId()!;
+      nockControl()
+        .get(`/v1/apps/${appId}/namespaces`)
+        .times(2)
+        .reply(200, [
+          mockNamespace({ id: "chat:*", mode: "matcher" }),
+          mockNamespace({ id: "legacy", mode: "namespace" }),
+        ]);
+
+      const { stdout } = await runCommand(["apps:rules:list"], import.meta.url);
+      expect(stdout).toContain("Mode: matcher");
+      expect(stdout).toContain("Mode: namespace");
+
+      const { stdout: jsonStdout } = await runCommand(
+        ["apps:rules:list", "--json"],
+        import.meta.url,
+      );
+      const result = parseJsonOutput(jsonStdout);
+      expect(result.rules.map((r: { mode: string }) => r.mode)).toEqual([
+        "matcher",
+        "namespace",
+      ]);
+    });
   });
 
   describe("error handling", () => {

test/unit/commands/apps/rules/update.test.ts

@@ -209,6 +209,29 @@ describe("apps:rules:update command", () => {
       expect(result).toHaveProperty("success", true);
       expect(result!.rule).toHaveProperty("persisted", true);
     });
+
+    it("should not send a mode, so an older namespace-mode rule stays one", async () => {
+      const appId = getMockConfigManager().getCurrentAppId()!;
+      nockControl()
+        .get(`/v1/apps/${appId}/namespaces`)
+        .reply(200, [mockNamespace({ id: mockRuleId, mode: "namespace" })]);
+
+      nockControl()
+        .patch(`/v1/apps/${appId}/namespaces/${mockRuleId}`, (body) => {
+          return body.persisted === true && !("mode" in body);
+        })
+        .reply(
+          200,
+          mockNamespace({ id: mockRuleId, mode: "namespace", persisted: true }),
+        );
+
+      const { stdout } = await runCommand(
+        ["apps:rules:update", mockRuleId, "--persisted"],
+        import.meta.url,
+      );
+
+      expect(stdout).toContain("Mode: namespace");
+    });
   });
 
   describe("error handling", () => {