@protontech/drive-sdk 0.0.13 → 0.1.0

package/src/internal/events/eventManager.ts

@@ -1,168 +1,122 @@
 import { Logger } from "../../interface";
-import { NotFoundAPIError } from "../apiService";
-import { Events } from "./interface";
+import { EventManagerInterface, Event, EventSubscription } from "./interface";
 
-const DEFAULT_POLLING_INTERVAL_IN_SECONDS = 30;
 const FIBONACCI_LIST = [1, 1, 2, 3, 5, 8, 13];
 
-/**
- * `fullRefresh` is true when the event manager has requested a full
- * refresh of the data. That can happen if there is too many events
- * to be processed or the last event ID is too old.
- */
-type Listener<T> = (events: T[], fullRefresh: boolean) => Promise<void>;
+type Listener<T> = (event: T) => Promise<void>;
+
 
 /**
  * Event manager general helper that is responsible for fetching events
  * from the server and notifying listeners about the events.
- * 
+ *
  * The specific implementation of fetching the events from the API must
  * be passed as dependency and can be used for any type of events that
  * supports the same structure.
- * 
+ *
  * The manager will not start fetching events until the `start` method is
  * called. Once started, the manager will fetch events in a loop with
  * a timeout between each fetch. The default timeout is 30 seconds and
  * additional jitter is used in case of failure.
- * 
- * Example of usage:
- * 
- * ```typescript
- * const manager = new EventManager(
- *    logger,
- *    () => apiService.getLatestEventId(),
- *    (eventId) => apiService.getEvents(eventId),
- * );
- * 
- * manager.addListener((events, fullRefresh) => {
- *   // Process the events
- * });
- * 
- * manager.start();
- * ```
  */
-export class EventManager<T> {
+export class EventManager<T extends Event> {
+    private logger: Logger;
     private latestEventId?: string;
     private timeoutHandle?: ReturnType<typeof setTimeout>;
     private processPromise?: Promise<void>;
     private listeners: Listener<T>[] = [];
     private retryIndex: number = 0;
 
-    pollingIntervalInSeconds = DEFAULT_POLLING_INTERVAL_IN_SECONDS;
-
     constructor(
-        private logger: Logger,
-        private getLatestEventId: () => Promise<string>,
-        private getEvents: (eventId: string) => Promise<Events<T>>,
-        private updateLatestEventId: (lastEventId: string) => Promise<void>,
+        private specializedEventManager: EventManagerInterface<T>,
+        private pollingIntervalInSeconds: number,
+        latestEventId: string | null,
     ) {
-        this.logger = logger;
-        this.getLatestEventId = getLatestEventId;
-        this.getEvents = getEvents;
-        this.updateLatestEventId = updateLatestEventId;
+        if (latestEventId !== null) {
+            this.latestEventId = latestEventId;
+        }
+        this.logger = specializedEventManager.getLogger();
     }
 
-    addListener(callback: Listener<T>): void {
+    async start(): Promise<void> {
+        if (this.latestEventId === undefined) {
+            this.latestEventId = await this.specializedEventManager.getLatestEventId();
+        }
+        this.processPromise = this.processEvents();
+    }
+
+    addListener(callback: Listener<T>): EventSubscription {
         this.listeners.push(callback);
+        return {
+            dispose: (): void => {
+                const index = this.listeners.indexOf(callback);
+                this.listeners.splice(index, 1);
+            },
+        };
     }
 
-    async start(): Promise<void> {
-        this.logger.info(`Starting event manager with polling interval ${this.pollingIntervalInSeconds} seconds`);
-        await this.stop();
-        this.processPromise = this.processEvents();
+    setPollingInterval(pollingIntervalInSeconds: number): void {
+        this.pollingIntervalInSeconds = pollingIntervalInSeconds;
+    }
+
+    async stop(): Promise<void> {
+        if (this.processPromise) {
+            this.logger.info(`Stopping event manager`);
+            try {
+                await this.processPromise;
+            } catch (error) {
+                this.logger.warn(`Failed to stop cleanly: ${error instanceof Error ? error.message : error}`);
+            }
+        }
+
+        if (!this.timeoutHandle) {
+            return;
+        }
+
+        clearTimeout(this.timeoutHandle);
+        this.timeoutHandle = undefined;
+    }
+
+    private async notifyListeners(event: T): Promise<void> {
+        for (const listener of this.listeners) {
+            await listener(event);
+        }
     }
 
     private async processEvents() {
+        let listenerError;
         try {
-            if (!this.latestEventId) {
-                this.latestEventId = await this.getLatestEventId();
-                await this.updateLatestEventId(this.latestEventId);
-            } else {
-                while (true) {
-                    let result;
-                    try {
-                        result = await this.getEvents(this.latestEventId);
-                    } catch (error: unknown) {
-                        // If last event ID is not found, we need to refresh the data.
-                        // Caller is notified via standard event update with refresh flag.
-                        if (error instanceof NotFoundAPIError) {
-                            this.logger.warn(`Last event ID not found, refreshing data`);
-                            result = {
-                                lastEventId: await this.getLatestEventId(), 
-                                more: false, 
-                                refresh: true,
-                                events: [],
-                            };
-                        } else {
-                            // Any other error is considered as a failure and we will retry
-                            // with backoff policy.
-                            throw error;
-                        }
-                    }
-                    await this.notifyListeners(result);
-                    if (result.lastEventId !== this.latestEventId) {
-                        await this.updateLatestEventId(result.lastEventId);
-                        this.latestEventId = result.lastEventId;
-                    }
-                    if (!result.more) {
-                        break;
-                    }
+            const events = this.specializedEventManager.getEvents(this.latestEventId!);
+            for await (const event of events) {
+                try {
+                    await this.notifyListeners(event);
+                } catch (internalListenerError) {
+                    listenerError = internalListenerError;
+                    break;
                 }
+                this.latestEventId = event.eventId;
             }
             this.retryIndex = 0;
         } catch (error: unknown) {
+            // This could be improved to catch api specific errors and let the listener errors bubble up directly
             this.logger.error(`Failed to process events: ${error instanceof Error ? error.message : error} (retry ${this.retryIndex}, last event ID: ${this.latestEventId})`);
             this.retryIndex++;
         }
+        if (listenerError) {
+            throw listenerError;
+        }
 
         this.timeoutHandle = setTimeout(() => {
             this.processPromise = this.processEvents();
         }, this.nextPollTimeout);
     };
 
-    private async notifyListeners(result: Events<T>): Promise<void> {
-        if (result.events.length === 0 && !result.refresh) {
-            return;
-        }
-        if (!this.listeners.length) {
-            return;
-        }
-
-        this.logger.debug(`Notifying listeners about ${result.events.length} events`);
-
-        for (const listener of this.listeners) {
-            try {
-                await listener(result.events, result.refresh);
-            } catch (error: unknown) {
-                this.logger.error(`Failed to process events: ${error instanceof Error ? error.message : error} (last event ID: ${result.lastEventId}, refresh: ${result.refresh})`);
-                throw error;
-            }
-        }
-    }
-
     /**
      * Polling timeout is using exponential backoff with Fibonacci sequence.
-     * 
-     * The timeout is public for testing purposes only.
      */
-    get nextPollTimeout(): number {
+    private get nextPollTimeout(): number {
         const retryIndex = Math.min(this.retryIndex, FIBONACCI_LIST.length - 1);
+        // FIXME jitter
         return this.pollingIntervalInSeconds * 1000 * FIBONACCI_LIST[retryIndex];
     }
-
-    async stop(): Promise<void> {
-        if (this.processPromise) {
-            this.logger.info(`Stopping event manager`);
-            try {
-                await this.processPromise;
-            } catch {}
-        }
-
-        if (!this.timeoutHandle) {
-            return;
-        }
-
-        clearTimeout(this.timeoutHandle);
-        this.timeoutHandle = undefined;
-    }
 }

package/src/internal/events/index.ts

@@ -1,16 +1,18 @@
-import { ProtonDriveEntitiesCache, Logger, ProtonDriveTelemetry } from "../../interface";
+import { Logger, ProtonDriveTelemetry } from "../../interface";
 import { DriveAPIService } from "../apiService";
-import { DriveListener } from "./interface";
+import { DriveEvent, DriveListener, EventSubscription, LatestEventIdProvider } from "./interface";
 import { EventsAPIService } from "./apiService";
-import { EventsCache } from "./cache";
 import { CoreEventManager } from "./coreEventManager";
 import { VolumeEventManager } from "./volumeEventManager";
+import { EventManager } from "./eventManager";
+import { SharesManager } from "../shares/manager";
 
 export type { DriveEvent, DriveListener } from "./interface";
 export { DriveEventType } from "./interface";
 
 const OWN_VOLUME_POLLING_INTERVAL = 30;
 const OTHER_VOLUME_POLLING_INTERVAL = 60;
+const CORE_POLLING_INTERVAL = 30;
 
 /**
  * Service for listening to drive events. The service is responsible for
@@ -19,113 +21,81 @@ const OTHER_VOLUME_POLLING_INTERVAL = 60;
  */
 export class DriveEventsService {
     private apiService: EventsAPIService;
-    private cache: EventsCache;
-    private subscribedToRemoteDataUpdates: boolean = false;
-    private listeners: DriveListener[] = [];
-    private coreEvents: CoreEventManager;
-    private volumesEvents: { [volumeId: string]: VolumeEventManager };
+    private coreEvents?: EventManager<DriveEvent>;
+    private volumeEventManagers: { [volumeId: string]: EventManager<DriveEvent> };
     private logger: Logger;
 
-    constructor(private telemetry: ProtonDriveTelemetry, apiService: DriveAPIService, driveEntitiesCache: ProtonDriveEntitiesCache) {
+    constructor(private telemetry: ProtonDriveTelemetry, apiService: DriveAPIService, private shareManagement: SharesManager, private cacheEventListeners: DriveListener[] = [], private latestEventIdProvider?: LatestEventIdProvider) {
         this.telemetry = telemetry;
         this.logger = telemetry.getLogger('events');
         this.apiService = new EventsAPIService(apiService);
-        this.cache = new EventsCache(driveEntitiesCache);
-
-        // FIXME: Allow to pass own core events manager from the public interface.
-        this.coreEvents = new CoreEventManager(this.logger, this.apiService, this.cache);
-        this.volumesEvents = {};
+        this.volumeEventManagers = {};
     }
 
     /**
-     * Loads all the subscribed volumes (including core events) from the
-     * cache and starts listening to their events. Any additional volume
-     * that is subscribed to later will be automatically started.
+     * Subscribe to drive events. The treeEventScopeId can be obtained from a node.
      */
-    async subscribeToRemoteDataUpdates(): Promise<void> {
-        if (this.subscribedToRemoteDataUpdates) {
-            return;
-        }
-
-        await this.loadSubscribedVolumeEventServices();
-        this.sendNumberOfVolumeSubscriptionsToTelemetry();
-
-        this.subscribedToRemoteDataUpdates = true;
-        await this.coreEvents.startSubscription();
-        await Promise.all(
-            Object.values(this.volumesEvents)
-                .map((volumeEvents) => volumeEvents.startSubscription())
-        );
-    }
-
-    /**
-     * Subscribe to given volume. The volume will be polled for events
-     * with the polling interval depending on the type of the volume.
-     * Own volumes are polled with highest frequency, while others are
-     * polled with lower frequency depending on the total number of
-     * subscriptions.
-     * 
-     * @param isOwnVolume - Owned volumes are polled with higher frequency.
-     */
-    async listenToVolume(volumeId: string, isOwnVolume = false): Promise<void> {
-        await this.loadSubscribedVolumeEventServices();
-
-        if (this.volumesEvents[volumeId]) {
-            return;
-        }
+    async subscribeToTreeEvents(treeEventScopeId: string, callback: DriveListener): Promise<EventSubscription> {
+        const volumeId = treeEventScopeId;
         this.logger.debug(`Creating volume event manager for volume ${volumeId}`);
-        const manager = this.createVolumeEventManager(volumeId, isOwnVolume);
-
-        // FIXME: Use dynamic algorithm to determine polling interval for non-own volumes.
-        manager.setPollingInterval(isOwnVolume ? OWN_VOLUME_POLLING_INTERVAL : OTHER_VOLUME_POLLING_INTERVAL);
-        if (this.subscribedToRemoteDataUpdates) {
-            await manager.startSubscription();
+        let manager = this.volumeEventManagers[volumeId];
+        let started = true;
+        if (manager === undefined) {
+            manager = await this.createVolumeEventManager(volumeId);
+            this.volumeEventManagers[volumeId] = manager;
+            started = false;
             this.sendNumberOfVolumeSubscriptionsToTelemetry();
         }
+        const eventSubscription = manager.addListener(callback);
+        if (!started) {
+            await manager.start();
+        }
+        return eventSubscription;
     }
 
-    private async loadSubscribedVolumeEventServices() {
-        for (const volumeId of await this.cache.getSubscribedVolumeIds()) {
-            if (!this.volumesEvents[volumeId]) {
-                const isOwnVolume = await this.cache.isOwnVolume(volumeId) || false;
-                this.createVolumeEventManager(volumeId, isOwnVolume);
+    // FIXME: Allow to pass own core events manager from the public interface.
+    async subscribeToCoreEvents(callback: DriveListener): Promise<EventSubscription> {
+        if (this.latestEventIdProvider === null || this.latestEventIdProvider === undefined) {
+            throw new Error('Cannot subscribe to events without passing a latestEventIdProvider in ProtonDriveClient initialization');
+        }
+        if (this.coreEvents === undefined) {
+            const coreEventManager = new CoreEventManager(this.logger, this.apiService);
+            const latestEventId = this.latestEventIdProvider.getLatestEventId('core') ?? null;
+            this.coreEvents = new EventManager(coreEventManager, CORE_POLLING_INTERVAL, latestEventId);
+            for (const listener of this.cacheEventListeners) {
+                this.coreEvents.addListener(listener);
             }
         }
+        const eventSubscription = this.coreEvents.addListener(callback);
+        await this.coreEvents.start();
+        return eventSubscription;
     }
 
     private sendNumberOfVolumeSubscriptionsToTelemetry() {
         this.telemetry.logEvent({
             eventName: 'volumeEventsSubscriptionsChanged',
-            numberOfVolumeSubscriptions: Object.keys(this.volumesEvents).length,
+            numberOfVolumeSubscriptions: Object.keys(this.volumeEventManagers).length,
         });
     }
 
-    private createVolumeEventManager(volumeId: string, isOwnVolume: boolean): VolumeEventManager {
-        const manager = new VolumeEventManager(this.logger, this.apiService, this.cache, volumeId, isOwnVolume);
-        for (const listener of this.listeners) {
-            manager.addListener(listener);
+    private async createVolumeEventManager(volumeId: string): Promise<EventManager<DriveEvent>> {
+        if (this.latestEventIdProvider === null || this.latestEventIdProvider === undefined) {
+            throw new Error('Cannot subscribe to events without passing a latestEventIdProvider in ProtonDriveClient initialization');
+        }
+        const isOwnVolume = await this.shareManagement.isOwnVolume(volumeId);
+        const pollingInterval = this.getDefaultVolumePollingInterval(isOwnVolume);
+        const volumeEventManager = new VolumeEventManager(this.logger, this.apiService, volumeId);
+        const latestEventId = this.latestEventIdProvider.getLatestEventId(volumeId);
+        const eventManager = new EventManager<DriveEvent>(volumeEventManager, pollingInterval, latestEventId);
+        for (const listener of this.cacheEventListeners) {
+            eventManager.addListener(listener);
         }
-        this.volumesEvents[volumeId] = manager;
-        return manager;
+        await eventManager.start();
+        this.volumeEventManagers[volumeId] = eventManager;
+        return eventManager;
     }
 
-    /**
-     * Listen to the drive events. The listener will be called with the
-     * new events as they arrive.
-     * 
-     * One call always provides events from withing the same volume. The
-     * second argument of the callback `fullRefreshVolumeId` is thus single
-     * ID and if multiple volumes must be fully refreshed, client will
-     * receive multiple calls.
-     */
-    addListener(callback: DriveListener): void {
-        // Add new listener to the list for any new event manager.
-        this.listeners.push(callback);
-
-        // Add new listener to all existings managers.
-        this.coreEvents.addListener(callback);
-        for (const volumeEvents of Object.values(this.volumesEvents)) {
-            volumeEvents.addListener(callback);
-        }
+    private getDefaultVolumePollingInterval(isOwnVolume: boolean): number {
+        return isOwnVolume ? OWN_VOLUME_POLLING_INTERVAL : OTHER_VOLUME_POLLING_INTERVAL
     }
 }

package/src/internal/events/interface.ts

@@ -1,19 +1,33 @@
+import { Logger } from "../../interface";
+
 /**
  * Callback that accepts list of Drive events and flag whether no
  * event should be processed, but rather full cache refresh should be
  * performed.
- * 
+ *
  * @param fullRefreshVolumeId - ID of the volume that should be fully refreshed.
  */
-export type DriveListener = (events: DriveEvent[], fullRefreshVolumeId?: string) => Promise<void>;
+export type DriveListener = (event: DriveEvent) => Promise<void>;
+
+export interface Event {
+    eventId: string;
+}
+
+export interface EventSubscription {
+    dispose(): void;
+}
+
+export interface LatestEventIdProvider {
+    getLatestEventId(treeEventScopeId: string): string | null;
+}
 
 /**
  * Generic internal event interface representing a list of events
  * with metadata about the last event ID, whether there are more
  * events to fetch, or whether the listener should refresh its state.
  */
-export type Events<T> = {
-    lastEventId: string,
+export type EventsListWithStatus<T> = {
+    latestEventId: string,
     more: boolean,
     refresh: boolean,
     events: T[],
@@ -22,30 +36,71 @@ export type Events<T> = {
 /**
  * Internal event interface representing a list of specific Drive events.
  */
-export type DriveEvents = Events<DriveEvent>;
+export type DriveEventsListWithStatus = EventsListWithStatus<DriveEvent>;
+
+type NodeCruEventType = DriveEventType.NodeCreated | DriveEventType.NodeUpdated;
+export type NodeEventType = NodeCruEventType | DriveEventType.NodeDeleted;
 
-export type DriveEvent = {
-    type: DriveEventType.NodeCreated | DriveEventType.NodeUpdated | DriveEventType.NodeUpdatedMetadata,
+export type NodeEvent = {
+    type: NodeCruEventType,
     nodeUid: string,
     parentNodeUid?: string,
     isTrashed: boolean,
     isShared: boolean,
-    isOwnVolume: boolean,
+    treeEventScopeId: string,
+    eventId: string,
 } | {
     type: DriveEventType.NodeDeleted,
     nodeUid: string,
     parentNodeUid?: string,
-    isTrashed?: boolean,
-    isShared?: boolean,
-    isOwnVolume: boolean,
-} | {
-    type: DriveEventType.ShareWithMeUpdated,
+    treeEventScopeId: string,
+    eventId: string,
 }
 
+export type FastForwardEvent = {
+    type: DriveEventType.FastForward,
+    treeEventScopeId: string,
+    eventId: string,
+}
+
+export type TreeRefreshEvent = {
+    type: DriveEventType.TreeRefresh,
+    treeEventScopeId: string,
+    eventId: string,
+}
+
+export type TreeRemovalEvent = {
+    type: DriveEventType.TreeRemove,
+    treeEventScopeId: string,
+    eventId: 'none',
+}
+
+export type SharedWithMeUpdated = {
+    type: DriveEventType.SharedWithMeUpdated,
+    eventId: string,
+    treeEventScopeId: 'core',
+}
+
+export type DriveEvent = NodeEvent | FastForwardEvent | TreeRefreshEvent | TreeRemovalEvent | FastForwardEvent | SharedWithMeUpdated;
+
 export enum DriveEventType {
     NodeCreated = 'node_created',
     NodeUpdated = 'node_updated',
-    NodeUpdatedMetadata = 'node_updated_metadata',
     NodeDeleted = 'node_deleted',
-    ShareWithMeUpdated = 'share_with_me_updated',
+    SharedWithMeUpdated = 'shared_with_me_updated',
+    TreeRefresh = 'tree_refresh',
+    TreeRemove = 'tree_remove',
+    FastForward = 'fast_forward',
+}
+
+/**
+ * This can happen if all shared nodes in that volume where unshared or if the
+ * volume was deleted.
+ */
+export class UnsubscribeFromEventsSourceError extends Error {};
+
+export interface EventManagerInterface<T> {
+    getLatestEventId(): Promise<string>;
+    getEvents(eventId: string): AsyncIterable<T>;
+    getLogger(): Logger;
 }