@dxos/app-framework 0.8.4-main.bc674ce → 0.8.4-main.bcb3aa67d6

package/src/core/plugin-manager.ts

@@ -15,6 +15,7 @@ import * as PubSub from 'effect/PubSub';
 import * as Ref from 'effect/Ref';
 
 import { runAndForwardErrors } from '@dxos/effect';
+import { Performance } from '@dxos/effect';
 import { log } from '@dxos/log';
 
 import * as ActivationEvent from './activation-event';
@@ -36,7 +37,13 @@ export type ManagerOptions = {
   registry?: Registry.Registry;
 };
 
-type ActivationMessage = { event: string; state: 'activating' | 'activated' | 'error'; error?: Error };
+export type ActivationMessage = {
+  event: string;
+  state: 'activating' | 'activated' | 'error';
+  /** Module ID when the message pertains to a specific module activation. */
+  module?: string;
+  error?: Error;
+};
 
 /**
  * Interface for the Plugin Manager.
@@ -74,6 +81,13 @@ export interface PluginManager {
   ): Effect.Effect<boolean, Error>;
   deactivate(id: string): Effect.Effect<boolean, Error>;
   reset(event: ActivationEvent.ActivationEvent | string): Effect.Effect<boolean, Error>;
+
+  /**
+   * Shuts down the manager by deactivating all active modules in reverse activation order,
+   * clearing all capabilities, and resetting lifecycle bookkeeping.
+   * Plugins, core, enabled, and modules remain intact so the manager can be reused.
+   */
+  shutdown(): Effect.Effect<boolean, Error>;
 }
 
 /**
@@ -105,6 +119,9 @@ class ManagerImpl implements PluginManager {
   private readonly _moduleSemaphores = new Map<Plugin.PluginModule['id'], Effect.Semaphore>();
   private readonly _activatingEvents = Effect.runSync(Ref.make<string[]>([]));
   private readonly _activatingModules = Effect.runSync(Ref.make<string[]>([]));
+  private readonly _inFlightFibers = Effect.runSync(Ref.make<Array<Fiber.Fiber<unknown, unknown>>>([]));
+  private readonly _shutdownSemaphore = Effect.runSync(Effect.makeSemaphore(1));
+  private readonly _shuttingDown = Effect.runSync(Ref.make(false));
 
   constructor({
     pluginLoader,
@@ -210,7 +227,7 @@ class ManagerImpl implements PluginManager {
       log('add plugin', { id });
       const plugin = yield* this._pluginLoader(id);
       this._addPlugin(plugin);
-      return yield* this.enable(id);
+      return yield* this.enable(plugin.meta.id);
     });
   }
 
@@ -299,146 +316,30 @@ class ManagerImpl implements PluginManager {
   ): Effect.Effect<boolean, Error> {
     const key = typeof event === 'string' ? event : ActivationEvent.eventKey(event);
     return Effect.gen(this, function* () {
-      log('activating', { key, ...params });
-      yield* Ref.update(this._activatingEvents, (activating) => Array.append(activating, key));
-      const pendingIndex = this._get(this._pendingResetAtom).findIndex((event) => event === key);
-      if (pendingIndex !== -1) {
-        this._update(this._pendingResetAtom, (pending) => pending.filter((event) => event !== key));
-      }
-
-      const activatingEvents = yield* this._activatingEvents;
-      const activatingModules = yield* this._activatingModules;
-      const modules = this._getInactiveModulesByEvent(key).filter((module) => {
-        const allOf = ActivationEvent.isAllOf(module.activatesOn);
-        if (!allOf) {
-          return true;
-        }
-
-        // Check to see if all of the events in the `allOf` have been fired.
-        // An event can be considered "fired" if it is in the `eventsFired` list or if it is currently being activated.
-        const events = ActivationEvent.getEvents(module.activatesOn).filter(
-          (event) => ActivationEvent.eventKey(event) !== key,
-        );
-        return (
-          events.every(
-            (event) =>
-              this._get(this._eventsFiredAtom).includes(ActivationEvent.eventKey(event)) ||
-              activatingEvents.includes(ActivationEvent.eventKey(event)),
-          ) && !activatingModules.includes(module.id)
-        );
-      });
-      yield* Ref.update(this._activatingModules, (activating) =>
-        Array.appendAll(
-          activating,
-          modules.map((module) => module.id),
-        ),
-      );
-      if (modules.length === 0) {
-        log('no modules to activate', { key });
-        if (!this._get(this._eventsFiredAtom).includes(key)) {
-          this._update(this._eventsFiredAtom, (events) => [...events, key]);
-        }
+      if (yield* this._isShuttingDown()) {
+        log('skipping activation during shutdown', { key, ...params });
         return false;
       }
 
-      log('activating modules', { key, modules: modules.map((module) => module.id) });
-      yield* PubSub.publish(this.activation, { event: key, state: 'activating' });
-
-      // Fire activatesBefore events.
-      const beforeEvents = Function.pipe(
-        modules,
-        Array.flatMap((module) => module.activatesBefore ?? []),
-        HashSet.fromIterable,
-        HashSet.toValues,
-        Array.filter((event) => !activatingEvents.includes(ActivationEvent.eventKey(event))),
-      );
-      yield* Function.pipe(
-        beforeEvents,
-        Array.map((event) => this.activate(event, { before: key })),
-        Effect.allWith({ concurrency: 'unbounded' }),
-        together(
-          Effect.sleep(Duration.seconds(10)).pipe(
-            Effect.andThen(
-              Effect.sync(() =>
-                log.warn('activatesBefore is taking a long time', {
-                  event: key,
-                  beforeEvents: beforeEvents.map(ActivationEvent.eventKey),
-                }),
-              ),
-            ),
-          ),
-        ),
-      );
-
-      // Concurrently triggers loading of lazy capabilities.
-      const getCapabilities = yield* Function.pipe(
-        modules,
-        Array.map((mod) => this._loadModule(mod)),
-        Effect.allWith({ concurrency: 'unbounded' }),
-        Effect.catchAll((error) => {
-          return Effect.gen(this, function* () {
-            yield* PubSub.publish(this.activation, { event: key, state: 'error', error });
-            return yield* Effect.fail(error);
-          });
-        }),
-      );
-
-      // Contribute the capabilities from the activated modules.
-      yield* Function.pipe(
-        modules,
-        Array.zip(getCapabilities),
-        Array.map(([module, capabilities]) => this._contributeCapabilities(module, capabilities)),
-        // TODO(wittjosiah): This currently can't be run in parallel.
-        //   Running this with concurrency causes races with `allOf` activation events.
-        Effect.all,
-      );
-
-      // Fire activatesAfter events.
-      const afterEvents = Function.pipe(
-        modules,
-        Array.flatMap((module) => module.activatesAfter ?? []),
-        HashSet.fromIterable,
-        HashSet.toValues,
-        Array.filter((event) => !activatingEvents.includes(ActivationEvent.eventKey(event))),
-      );
-      yield* Function.pipe(
-        afterEvents,
-        Array.map((event) => this.activate(event, { after: key })),
-        Effect.allWith({ concurrency: 'unbounded' }),
-        together(
-          Effect.sleep(Duration.seconds(10)).pipe(
-            Effect.andThen(
-              Effect.sync(() =>
-                log.warn('activatesAfter is taking a long time', {
-                  event: key,
-                  afterEvents: afterEvents.map(ActivationEvent.eventKey),
-                }),
-              ),
+      return yield* Effect.withFiberRuntime<boolean, Error>((fiber) =>
+        this._activateEvent(key, params, fiber).pipe(
+          together(
+            Effect.sleep(Duration.seconds(15)).pipe(
+              Effect.andThen(Effect.sync(() => log.warn('event activation is taking a long time', { event: key }))),
             ),
           ),
+          Performance.addTrackEntry({
+            name: typeof event === 'string' ? event : ActivationEvent.eventKey(event),
+            devtools: {
+              dataType: 'track-entry',
+              track: 'Event Activation',
+              trackGroup: 'Composer',
+              color: 'primary',
+            },
+          }),
         ),
       );
-
-      yield* Ref.update(this._activatingEvents, (activating) => Array.filter(activating, (event) => event !== key));
-      yield* Ref.update(this._activatingModules, (activating) =>
-        Array.filter(activating, (module) => !modules.map((module) => module.id).includes(module)),
-      );
-
-      if (!this._get(this._eventsFiredAtom).includes(key)) {
-        this._update(this._eventsFiredAtom, (events) => [...events, key]);
-      }
-
-      yield* PubSub.publish(this.activation, { event: key, state: 'activated' });
-      log('activated', { key });
-
-      return true;
-    }).pipe(
-      together(
-        Effect.sleep(Duration.seconds(15)).pipe(
-          Effect.andThen(Effect.sync(() => log.warn('event activation is taking a long time', { event: key }))),
-        ),
-      ),
-    );
+    });
   }
 
   /**
@@ -485,6 +386,40 @@ class ManagerImpl implements PluginManager {
     });
   }
 
+  shutdown(): Effect.Effect<boolean, Error> {
+    return this._shutdownSemaphore.withPermits(1)(
+      Effect.gen(this, function* () {
+        yield* Ref.set(this._shuttingDown, true);
+        log('shutdown');
+
+        yield* this._interruptInFlightActivations();
+
+        const activeIds = [...this._get(this._activeAtom)].reverse();
+        const allModules = this._get(this._modulesAtom);
+        const modulesToDeactivate = activeIds
+          .map((id) => allModules.find((module) => module.id === id))
+          .filter((module): module is Plugin.PluginModule => module != null);
+
+        for (const module of modulesToDeactivate) {
+          yield* this._deactivateModule(module);
+        }
+
+        this._set(this._eventsFiredAtom, []);
+        this._set(this._pendingResetAtom, []);
+        this._moduleMemoMap.clear();
+        yield* Ref.set(this._activatingEvents, []);
+        yield* Ref.set(this._activatingModules, []);
+
+        log('shutdown complete');
+        return true;
+      }).pipe(Effect.ensuring(Ref.set(this._shuttingDown, false))),
+    );
+  }
+
+  //
+  // State helpers
+  //
+
   private _get<T>(atom: Atom.Atom<T>): T {
     return this.registry.get(atom);
   }
@@ -497,26 +432,8 @@ class ManagerImpl implements PluginManager {
     this._set(atom, updater(this._get(atom)));
   }
 
-  private _addPlugin(plugin: Plugin.Plugin): void {
-    log('add plugin', { id: plugin.meta.id });
-    // TODO(wittjosiah): Find a way to add a warning for duplicate plugins that doesn't cause log spam.
-    this._update(this._pluginsAtom, (plugins) => (plugins.includes(plugin) ? plugins : [...plugins, plugin]));
-  }
-
-  private _removePlugin(id: string): void {
-    log('remove plugin', { id });
-    this._update(this._pluginsAtom, (plugins) => plugins.filter((plugin) => plugin.meta.id !== id));
-  }
-
-  private _addModule(module: Plugin.PluginModule): void {
-    log('add module', { id: module.id });
-    // TODO(wittjosiah): Find a way to add a warning for duplicate modules that doesn't cause log spam.
-    this._update(this._modulesAtom, (modules) => (modules.includes(module) ? modules : [...modules, module]));
-  }
-
-  private _removeModule(id: string): void {
-    log('remove module', { id });
-    this._update(this._modulesAtom, (modules) => modules.filter((module) => module.id !== id));
+  private _isShuttingDown(): Effect.Effect<boolean> {
+    return Ref.get(this._shuttingDown);
   }
 
   private _getPlugin(id: string): Plugin.Plugin | undefined {
@@ -560,6 +477,257 @@ class ManagerImpl implements PluginManager {
     }
   }
 
+  private _clearPendingReset(key: string): void {
+    const pendingIndex = this._get(this._pendingResetAtom).findIndex((event) => event === key);
+    if (pendingIndex !== -1) {
+      this._update(this._pendingResetAtom, (pending) => pending.filter((event) => event !== key));
+    }
+  }
+
+  //
+  // Fiber helpers
+  //
+
+  private _interruptInFlightActivations(): Effect.Effect<void> {
+    return Effect.gen(this, function* () {
+      const inFlightFibers = yield* Ref.get(this._inFlightFibers);
+      yield* Effect.forEach(inFlightFibers, (fiber) => Fiber.interrupt(fiber), {
+        concurrency: 'unbounded',
+      });
+    });
+  }
+
+  private _trackFiber(
+    ref: Ref.Ref<Array<Fiber.Fiber<unknown, unknown>>>,
+    fiber: Fiber.Fiber<unknown, unknown>,
+  ): Effect.Effect<void> {
+    return Ref.update(ref, (fibers) => [...fibers, fiber]);
+  }
+
+  private _untrackFiber(
+    ref: Ref.Ref<Array<Fiber.Fiber<unknown, unknown>>>,
+    fiber: Fiber.Fiber<unknown, unknown>,
+  ): Effect.Effect<void> {
+    return Ref.update(ref, (fibers) => fibers.filter((trackedFiber) => trackedFiber !== fiber));
+  }
+
+  //
+  // Registration helpers
+  //
+
+  private _addPlugin(plugin: Plugin.Plugin): void {
+    log('add plugin', { id: plugin.meta.id });
+    // TODO(wittjosiah): Find a way to add a warning for duplicate plugins that doesn't cause log spam.
+    this._update(this._pluginsAtom, (plugins) => (plugins.includes(plugin) ? plugins : [...plugins, plugin]));
+  }
+
+  private _removePlugin(id: string): void {
+    log('remove plugin', { id });
+    this._update(this._pluginsAtom, (plugins) => plugins.filter((plugin) => plugin.meta.id !== id));
+  }
+
+  private _addModule(module: Plugin.PluginModule): void {
+    log('add module', { id: module.id });
+    // TODO(wittjosiah): Find a way to add a warning for duplicate modules that doesn't cause log spam.
+    this._update(this._modulesAtom, (modules) => (modules.includes(module) ? modules : [...modules, module]));
+  }
+
+  private _removeModule(id: string): void {
+    log('remove module', { id });
+    this._update(this._modulesAtom, (modules) => modules.filter((module) => module.id !== id));
+  }
+
+  //
+  // Activation helpers
+  //
+
+  private _activateEvent(
+    key: string,
+    params: { before?: string; after?: string } | undefined,
+    fiber: Fiber.Fiber<unknown, unknown>,
+  ): Effect.Effect<boolean, Error> {
+    return Effect.gen(this, function* () {
+      yield* this._trackFiber(this._inFlightFibers, fiber);
+      log('activating', { key, ...params });
+      yield* Ref.update(this._activatingEvents, (activating) => Array.append(activating, key));
+      this._clearPendingReset(key);
+
+      const activatingEvents = yield* this._activatingEvents;
+      const activatingModules = yield* this._activatingModules;
+      const modules = this._getModulesForActivation(key, activatingEvents, activatingModules);
+      if (modules.length === 0) {
+        log('no modules to activate', { key });
+        if (!this._get(this._eventsFiredAtom).includes(key)) {
+          this._update(this._eventsFiredAtom, (events) => [...events, key]);
+        }
+        return false;
+      }
+
+      return yield* this._activateModulesForEvent(key, modules, activatingEvents);
+    }).pipe(
+      Effect.ensuring(
+        Effect.all([
+          this._untrackFiber(this._inFlightFibers, fiber),
+          Ref.update(this._activatingEvents, (activating) => Array.filter(activating, (event) => event !== key)),
+        ]),
+      ),
+    );
+  }
+
+  private _activateModulesForEvent(
+    key: string,
+    modules: Plugin.PluginModule[],
+    activatingEvents: string[],
+  ): Effect.Effect<boolean, Error> {
+    const activatingModuleIds = modules.map((module) => module.id);
+    return Effect.gen(this, function* () {
+      yield* Ref.update(this._activatingModules, (activating) => Array.appendAll(activating, activatingModuleIds));
+
+      log('activating modules', { key, modules: activatingModuleIds });
+      performance.mark(`event:${key}:start`);
+      yield* PubSub.publish(this.activation, { event: key, state: 'activating' });
+
+      yield* this._activateRelatedEvents(key, this._getBeforeEvents(modules, activatingEvents), 'before');
+
+      const capabilities = yield* this._loadCapabilitiesForModules(key, modules);
+      yield* this._contributeCapabilitiesForModules(modules, capabilities);
+
+      yield* this._activateRelatedEvents(key, this._getAfterEvents(modules, activatingEvents), 'after');
+
+      if (!this._get(this._eventsFiredAtom).includes(key)) {
+        this._update(this._eventsFiredAtom, (events) => [...events, key]);
+      }
+
+      performance.mark(`event:${key}:end`);
+      performance.measure(`event:${key}`, `event:${key}:start`, `event:${key}:end`);
+      yield* PubSub.publish(this.activation, { event: key, state: 'activated' });
+      log('activated', { key });
+
+      return true;
+    }).pipe(
+      Effect.ensuring(
+        Ref.update(this._activatingModules, (activating) =>
+          Array.filter(activating, (module) => !activatingModuleIds.includes(module)),
+        ),
+      ),
+    );
+  }
+
+  private _getModulesForActivation(
+    key: string,
+    activatingEvents: string[],
+    activatingModules: string[],
+  ): Plugin.PluginModule[] {
+    return this._getInactiveModulesByEvent(key).filter((module) => {
+      const allOf = ActivationEvent.isAllOf(module.activatesOn);
+      if (!allOf) {
+        return true;
+      }
+
+      // Check to see if all of the events in the `allOf` have been fired.
+      // An event can be considered "fired" if it is in the `eventsFired` list or if it is currently being activated.
+      const events = ActivationEvent.getEvents(module.activatesOn).filter(
+        (event) => ActivationEvent.eventKey(event) !== key,
+      );
+      return (
+        events.every(
+          (event) =>
+            this._get(this._eventsFiredAtom).includes(ActivationEvent.eventKey(event)) ||
+            activatingEvents.includes(ActivationEvent.eventKey(event)),
+        ) && !activatingModules.includes(module.id)
+      );
+    });
+  }
+
+  private _getBeforeEvents(
+    modules: Plugin.PluginModule[],
+    activatingEvents: string[],
+  ): ActivationEvent.ActivationEvent[] {
+    return Function.pipe(
+      modules,
+      Array.flatMap((module) => module.activatesBefore ?? []),
+      HashSet.fromIterable,
+      HashSet.toValues,
+      Array.filter((event) => !activatingEvents.includes(ActivationEvent.eventKey(event))),
+    );
+  }
+
+  private _getAfterEvents(
+    modules: Plugin.PluginModule[],
+    activatingEvents: string[],
+  ): ActivationEvent.ActivationEvent[] {
+    return Function.pipe(
+      modules,
+      Array.flatMap((module) => module.activatesAfter ?? []),
+      HashSet.fromIterable,
+      HashSet.toValues,
+      Array.filter((event) => !activatingEvents.includes(ActivationEvent.eventKey(event))),
+    );
+  }
+
+  private _activateRelatedEvents(
+    key: string,
+    events: ActivationEvent.ActivationEvent[],
+    phase: 'before' | 'after',
+  ): Effect.Effect<void, Error> {
+    const logLabel = phase === 'before' ? 'activatesBefore' : 'activatesAfter';
+    const eventKey = phase === 'before' ? 'beforeEvents' : 'afterEvents';
+    return Function.pipe(
+      events,
+      Array.map((event) => this.activate(event, phase === 'before' ? { before: key } : { after: key })),
+      Effect.allWith({ concurrency: 'unbounded' }),
+      together(
+        Effect.sleep(Duration.seconds(10)).pipe(
+          Effect.andThen(
+            Effect.sync(() =>
+              log.warn(`${logLabel} is taking a long time`, {
+                event: key,
+                [eventKey]: events.map(ActivationEvent.eventKey),
+              }),
+            ),
+          ),
+        ),
+      ),
+      Effect.asVoid,
+    );
+  }
+
+  //
+  // Module lifecycle helpers
+  //
+
+  private _loadCapabilitiesForModules(
+    key: string,
+    modules: Plugin.PluginModule[],
+  ): Effect.Effect<Capability.Any[][], Error> {
+    return Function.pipe(
+      modules,
+      Array.map((mod) => this._loadModule(mod)),
+      Effect.allWith({ concurrency: 'unbounded' }),
+      Effect.catchAll((error) => {
+        return Effect.gen(this, function* () {
+          yield* PubSub.publish(this.activation, { event: key, state: 'error', error });
+          return yield* Effect.fail(error);
+        });
+      }),
+    );
+  }
+
+  private _contributeCapabilitiesForModules(
+    modules: Plugin.PluginModule[],
+    capabilities: Capability.Any[][],
+  ): Effect.Effect<void, Error> {
+    return Function.pipe(
+      modules,
+      Array.zip(capabilities),
+      Array.map(([module, capabilitySet]) => this._contributeCapabilities(module, capabilitySet)),
+      // TODO(wittjosiah): This currently can't be run in parallel.
+      //   Running this with concurrency causes races with `allOf` activation events.
+      Effect.all,
+      Effect.asVoid,
+    );
+  }
+
   private _getModuleSemaphore(moduleId: Plugin.PluginModule['id']): Effect.Semaphore {
     let semaphore = this._moduleSemaphores.get(moduleId);
     if (!semaphore) {
@@ -586,6 +754,8 @@ class ManagerImpl implements PluginManager {
 
         const loadEffect = Effect.gen(this, function* () {
           log('loading module', { module: module.id });
+          performance.mark(`module:${module.id}:start`);
+          yield* PubSub.publish(this.activation, { event: '', state: 'activating', module: module.id });
           const [duration, capabilities] = yield* module
             .activate()
             .pipe(
@@ -594,9 +764,13 @@ class ManagerImpl implements PluginManager {
               Effect.timed,
             );
           const normalized = capabilities == null ? [] : Array.isArray(capabilities) ? capabilities : [capabilities];
+          const elapsed = Duration.toMillis(duration);
+          performance.mark(`module:${module.id}:end`);
+          performance.measure(`module:${module.id}`, `module:${module.id}:start`, `module:${module.id}:end`);
+          yield* PubSub.publish(this.activation, { event: '', state: 'activated', module: module.id });
           log('loaded module', {
             module: module.id,
-            elapsed: Duration.toMillis(duration),
+            elapsed,
             failed: false,
           });
           return normalized as Capability.Any[];
@@ -609,10 +783,19 @@ class ManagerImpl implements PluginManager {
               ),
             ),
           ),
+          Performance.addTrackEntry({
+            name: module.id,
+            devtools: {
+              dataType: 'track-entry',
+              track: 'Module Activation',
+              trackGroup: 'Composer',
+              color: 'primary',
+            },
+          }),
         );
 
         // Fork the load to run in background, completing the deferred when done.
-        yield* Effect.forkDaemon(
+        const fiber = yield* Effect.forkDaemon(
           loadEffect.pipe(
             Effect.tap((result) => Deferred.succeed(deferred, result)),
             Effect.catchAllCause((cause) => {
@@ -627,6 +810,10 @@ class ManagerImpl implements PluginManager {
             }),
           ),
         );
+        yield* this._trackFiber(this._inFlightFibers, fiber);
+        yield* Effect.forkDaemon(
+          Fiber.await(fiber).pipe(Effect.andThen(() => this._untrackFiber(this._inFlightFibers, fiber))),
+        );
 
         return deferred;
       }).pipe(semaphore.withPermits(1));

package/src/core/plugin.ts

@@ -45,11 +45,18 @@ export const activate = (event: ActivationEvent.ActivationEvent): Effect.Effect<
 export const reset = (event: ActivationEvent.ActivationEvent): Effect.Effect<boolean, Error, Service> =>
   Effect.flatMap(Service, (manager) => manager.reset(event));
 
+/**
+ * Shuts down the plugin manager, deactivating all active modules and clearing lifecycle state.
+ * Accesses the PluginManager via the Effect layer system.
+ */
+export const shutdown = (): Effect.Effect<boolean, Error, Service> =>
+  Effect.flatMap(Service, (manager) => manager.shutdown());
+
 /**
  * Computes a module ID from plugin ID and export name.
  */
 const computeModuleId = (pluginId: string, moduleName: string): string => {
-  return `${pluginId}/module/${moduleName}`;
+  return `${pluginId}.module.${moduleName}`;
 };
 
 /**
@@ -128,7 +135,7 @@ export type Meta = {
    *
    * Expected to be in the form of a valid URL.
    *
-   * @example dxos.org/plugin/example
+   * @example org.dxos.plugin.example
    */
   id: string;
 
@@ -190,6 +197,7 @@ export const isPlugin = (value: unknown): value is Plugin => {
  * A collection of modules that are be enabled/disabled as a unit.
  * Plugins provide things such as components, state, actions, etc. to the application.
  */
+// TODO(burdon): Convert to ECHO schema.
 export interface Plugin {
   readonly [PluginTypeId]: PluginTypeId;
   readonly meta: Readonly<Meta>;