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

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/helpers/e2e-mutable-messages.ts

@@ -6,8 +6,9 @@ export { SHOULD_SKIP_CONTROL_E2E as SHOULD_SKIP_MUTABLE_TESTS } from "./e2e-test
 
 /** Namespace prefix for mutable message test channels. */
 export const MUTABLE_NAMESPACE = "e2e-mutable";
+const MUTABLE_RULE = `${MUTABLE_NAMESPACE}:*`;
 
-// The module-level ruleCreated flag and the shared MUTABLE_NAMESPACE channel
+// The module-level ruleCreated flag and the shared MUTABLE_RULE channel
 // rule assume e2e files run serially. Vitest's e2e project sets
 // `fileParallelism: false` (see vitest.config.ts), so only one file uses this
 // helper at a time. If that config ever changes, switch to a per-caller
@@ -32,7 +33,7 @@ export async function setupMutableMessagesRule(): Promise<void> {
       "apps",
       "rules",
       "create",
-      MUTABLE_NAMESPACE,
+      MUTABLE_RULE,
       "--mutable-messages",
       "--app",
       appId,
@@ -63,7 +64,7 @@ export async function setupMutableMessagesRule(): Promise<void> {
       mutableMessages?: boolean;
     }>;
     const existing = rules.find(
-      (r) => r.id === MUTABLE_NAMESPACE && r.mutableMessages === true,
+      (r) => r.id === MUTABLE_RULE && r.mutableMessages === true,
     );
 
     if (existing) {
@@ -93,7 +94,7 @@ export async function teardownMutableMessagesRule(): Promise<void> {
       "apps",
       "rules",
       "delete",
-      MUTABLE_NAMESPACE,
+      MUTABLE_RULE,
       "--app",
       appId,
       "--force",
@@ -110,7 +111,7 @@ export async function teardownMutableMessagesRule(): Promise<void> {
 
 /**
  * Generate a channel name under the mutable namespace.
- * Format: "e2e-mutable:<suffix>-<uuid>" — matches the namespace rule.
+ * Format: "e2e-mutable:<suffix>-<uuid>" — matches MUTABLE_RULE.
  */
 export function getMutableChannelName(suffix: string): string {
   return `${MUTABLE_NAMESPACE}:${suffix}-${randomUUID().slice(0, 8)}`;

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", () => {