ui: add API for command filtering for embedders

In some applications that embed the Perfetto UI, there are a number of
commands that are not needed. For example, in an application that
manages the opening of traces into instances of the Perfetto UI, there
is no need for the commands that open and close traces. And other
commands may overlap or conflict with other capabilities provided by the
host application, which therefore may wish to exclude those commands.

Add an API to the Registry class to permit an embedding application to
install a filter that quietly prevents registration of unwanted
services. Employ this capability in the CommandManager.

Signed-off-by: Christian W. Damus <cdamus.ext@eclipsesource.com>

Author: cdamus

ui/src/base/registry.ts

@@ -26,6 +26,7 @@ export class RegistryError extends Error {
 export class Registry<T> {
   private key: (t: T) => string;
   protected registry: Map<string, T>;
+  private keyFilter: (key: string) => boolean = () => true;
 
   static kindRegistry<T extends HasKind>(): Registry<T> {
     return new Registry<T>((t) => t.kind);
@@ -36,8 +37,23 @@ export class Registry<T> {
     this.key = key;
   }
 
+  set filter(filter: ((key: string) => boolean) | undefined) {
+    this.keyFilter = filter ?? (() => true);
+
+    // Run the filter to knock out anything already registered that does not pass it
+    [...this.registry.keys()]
+      .filter((key) => !this.keyFilter(key))
+      .forEach((key) => this.registry.delete(key));
+  }
+
   register(registrant: T): Disposable {
     const kind = this.key(registrant);
+    if (!this.keyFilter(kind)) {
+      // Simply refuse to register the entry
+      return {
+        [Symbol.dispose]: () => undefined,
+      };
+    }
     if (this.registry.has(kind)) {
       throw new RegistryError(
         `Registrant ${kind} already exists in the registry`,
@@ -85,8 +101,14 @@ export class Registry<T> {
     // A proxy is not sufficient because we need non-overridden
     // methods to delegate to overridden methods.
     const result = new (class ChildRegistry extends Registry<T> {
-      constructor (private readonly parent: Registry<T>) {
+      constructor(private readonly parent: Registry<T>) {
         super(parent.key);
+        this.keyFilter = parent.keyFilter;
+      }
+
+      override set filter(filter: ((key: string) => boolean) | undefined) {
+        this.parent.filter = filter;
+        super.filter = filter;
       }
 
       override has(kind: string): boolean {

ui/src/base/registry_unittest.ts

@@ -59,6 +59,37 @@ test('registry allows iteration', () => {
   expect(values.includes(b)).toBe(true);
 });
 
+describe('registry filter', () => {
+  test('prevents registration of non-matching kinds', () => {
+    const registry = Registry.kindRegistry<Registrant>();
+    registry.filter = (key) => key.startsWith('a');
+
+    const alpha: Registrant = {kind: 'alpha', n: 1};
+    const beta: Registrant = {kind: 'beta', n: 2};
+    registry.register(alpha);
+    registry.register(beta);
+
+    expect(registry.has('alpha')).toBe(true);
+    expect(registry.has('beta')).toBe(false);
+    expect(() => registry.get('beta')).toThrow();
+    expect(registry.get('alpha')).toBe(alpha);
+  });
+
+  test('removes extant non-matching registrations', () => {
+    const registry = Registry.kindRegistry<Registrant>();
+    const a: Registrant = {kind: 'alpha', n: 1};
+    const b: Registrant = {kind: 'beta', n: 2};
+    registry.register(a);
+    registry.register(b);
+
+    registry.filter = (key) => key.startsWith('a');
+
+    expect(registry.has('alpha')).toBe(true);
+    expect(registry.has('beta')).toBe(false);
+    expect(() => registry.get('beta')).toThrow();
+  });
+});
+
 describe('Hierarchical (child) registries', () => {
   test('inheritance of registrations', () => {
     const parent = Registry.kindRegistry<Registrant>();
@@ -176,4 +207,60 @@ describe('Hierarchical (child) registries', () => {
 
     expect(child).not.toHaveProperty('id');
   });
+
+  describe('registry filter', () => {
+    test('child inherits parent filter', () => {
+      const parent = Registry.kindRegistry<Registrant>();
+      parent.filter = (key) => key.startsWith('x');
+
+      const child = parent.createChild();
+
+      const childOk: Registrant = {kind: 'xyz', n: 1};
+      const childNok: Registrant = {kind: 'abc', n: 2};
+      child.register(childOk);
+      child.register(childNok);
+
+      const parentOk: Registrant = {kind: 'xenon', n: 3};
+      const parentNok: Registrant = {kind: 'beta', n: 4};
+      parent.register(parentOk);
+      parent.register(parentNok);
+
+      expect(child.has('xyz')).toBe(true);
+      expect(child.has('abc')).toBe(false);
+      expect(child.get('xyz')).toBe(childOk);
+
+      // Other registrations still accessible (or not) as usual
+      expect(child.get('xenon')).toBe(parentOk);
+      expect(parent.has('beta')).toBe(false);
+      expect(() => child.get('beta')).toThrow();
+    });
+
+    test('setting filter on child cascades to parent and prunes both registries', () => {
+      const parent = Registry.kindRegistry<Registrant>();
+      const a: Registrant = {kind: 'a', n: 1};
+      const b: Registrant = {kind: 'b', n: 2};
+      parent.register(a);
+      parent.register(b);
+
+      const child = parent.createChild();
+      const c: Registrant = {kind: 'c', n: 3};
+      const d: Registrant = {kind: 'd', n: 4};
+      child.register(c);
+      child.register(d);
+
+      child.filter = (key) => key === 'b' || key === 'd';
+
+      // Parent pruned
+      expect(parent.has('a')).toBe(false);
+      expect(parent.has('b')).toBe(true);
+
+      // Child pruned
+      expect(child.has('c')).toBe(false);
+      expect(child.has('d')).toBe(true);
+
+      // Other registrations still accessible (or not) as usual
+      expect(child.get('b')).toBe(b);
+      expect(() => parent.get('d')).toThrow();
+    });
+  });
 });

ui/src/core/command_manager.ts

@@ -82,6 +82,16 @@ export class CommandManagerImpl implements CommandManager {
     return new CommandManagerImpl(this.registry);
   }
 
+  /**
+   * Set a filter to screen command registrations. Command IDs that do not
+   * pass the filter are not registered. This is distinct from the
+   * `allowlistCheck` function, which screens out start-up commands that
+   * should be skipped.
+   */
+  set filter(filter: ((commandId: string) => boolean) | undefined) {
+    this.registry.filter = filter;
+  }
+
   getCommand(commandId: string): Command {
     return this.registry.get(commandId);
   }

ui/src/core/command_manager_unittest.ts

@@ -38,3 +38,36 @@ describe('CommandManagerImpl child manager', () => {
     expect(parent.hasCommand('child')).toBe(false);
   });
 });
+
+describe('CommandManagerImpl filtering', () => {
+  test('filters existing and future registrations', () => {
+    const parent = new CommandManagerImpl();
+
+    const allowCmd = TestCommand('allow');
+    const denyCmd = TestCommand('deny');
+
+    parent.registerCommand(allowCmd);
+    parent.registerCommand(denyCmd);
+
+    const mgr = parent.createChild();
+    expect(mgr.hasCommand('allow')).toBe(true);
+    expect(mgr.hasCommand('deny')).toBe(true);
+
+    mgr.filter = (id) => id.startsWith('allow');
+
+    // Extant non-matching commands are purged
+    expect(mgr.hasCommand('allow')).toBe(true);
+    expect(mgr.hasCommand('deny')).toBe(false);
+
+    // New registrations are screened by the filter.
+    mgr.registerCommand(TestCommand('deny'));
+    expect(mgr.hasCommand('deny')).toBe(false);
+    mgr.registerCommand(TestCommand('allowed'));
+    expect(mgr.hasCommand('allowed')).toBe(true);
+
+    // Clearing the filter allows registering the previously denied command.
+    mgr.filter = undefined;
+    mgr.registerCommand(TestCommand('deny'));
+    expect(mgr.hasCommand('deny')).toBe(true);
+  });
+});