@protontech/drive-sdk 0.9.8 → 0.10.0

package/src/internal/photos/addToAlbum.ts

@@ -0,0 +1,341 @@
+import { c } from 'ttag';
+
+import { ValidationError } from '../../errors';
+import { Logger, NodeResultWithError } from '../../interface';
+import { DecryptedNodeKeys, NodeSigningKeys } from '../nodes/interface';
+import { splitNodeUid } from '../uids';
+import { AlbumsCryptoService } from './albumsCrypto';
+import { PhotosAPIService } from './apiService';
+import { MissingRelatedPhotosError } from './errors';
+import { AddToAlbumEncryptedPhotoPayload, DecryptedPhotoNode } from './interface';
+import { PhotosNodesAccess } from './nodes';
+
+/**
+ * The number of photos that are loaded in parallel to prepare the payloads.
+ */
+const BATCH_LOADING_SIZE = 20;
+
+/**
+ * The maximum number of photos that can be added to an album in a single
+ * request. The size includes the photo itself and its related photos.
+ */
+const ADD_PHOTOS_BATCH_SIZE = 10;
+
+/**
+ * Item in the processing queue representing a photo to add to an album.
+ */
+type PhotoQueueItem = {
+    photoNodeUid: string;
+    /**
+     * When retrying after a MissingRelatedPhotosError, these contain the
+     * node UIDs reported as missing by the server that need to be included
+     * as additional related photos.
+     */
+    additionalRelatedPhotoNodeUids: string[];
+};
+
+/**
+ * Manages the process of adding photos to an album.
+ *
+ * Photos are split into two queues based on volume:
+ * - Same volume: added in batches via the add-multiple endpoint.
+ * - Different volume: copied individually via the copy endpoint.
+ *
+ * Both paths handle MissingRelatedPhotosError by re-queuing the failed
+ * photo with updated related photo UIDs for one retry attempt.
+ */
+export class AddToAlbumProcess {
+    private readonly albumVolumeId: string;
+    private readonly retriedPhotoUids = new Set<string>();
+
+    constructor(
+        private readonly albumNodeUid: string,
+        private readonly albumKeys: DecryptedNodeKeys,
+        private readonly signingKeys: NodeSigningKeys,
+        private readonly apiService: PhotosAPIService,
+        private readonly cryptoService: AlbumsCryptoService,
+        private readonly nodesService: PhotosNodesAccess,
+        private readonly logger: Logger,
+        private readonly signal?: AbortSignal,
+    ) {
+        this.albumVolumeId = splitNodeUid(albumNodeUid).volumeId;
+    }
+
+    async *execute(photoNodeUids: string[]): AsyncGenerator<NodeResultWithError> {
+        const { sameVolumeQueue, differentVolumeQueue } = splitByVolume(photoNodeUids, this.albumVolumeId);
+
+        yield* this.processSameVolumeQueue(sameVolumeQueue);
+        yield* this.processDifferentVolumeQueue(differentVolumeQueue);
+    }
+
+    private async *processSameVolumeQueue(queue: PhotoQueueItem[]): AsyncGenerator<NodeResultWithError> {
+        while (queue.length > 0) {
+            const items = queue.splice(0, BATCH_LOADING_SIZE);
+            const { payloads, errors } = await this.preparePhotoPayloads(items);
+
+            for (const [uid, error] of errors) {
+                yield { uid, ok: false, error };
+            }
+
+            for (const batch of createBatches(payloads)) {
+                for await (const result of this.apiService.addPhotosToAlbum(this.albumNodeUid, batch, this.signal)) {
+                    const retryItem = this.handleMissingRelatedPhotosError(result);
+                    if (retryItem) {
+                        queue.push(retryItem);
+                        continue;
+                    }
+
+                    if (result.ok) {
+                        await this.nodesService.notifyNodeChanged(result.uid);
+                    }
+                    yield result;
+                }
+            }
+        }
+    }
+
+    private async *processDifferentVolumeQueue(queue: PhotoQueueItem[]): AsyncGenerator<NodeResultWithError> {
+        while (queue.length > 0) {
+            const items = queue.splice(0, BATCH_LOADING_SIZE);
+            const { payloads, errors } = await this.preparePhotoPayloads(items);
+
+            for (const [uid, error] of errors) {
+                yield { uid, ok: false, error };
+            }
+
+            for (const payload of payloads) {
+                try {
+                    const newPhotoNodeUid = await this.apiService.copyPhotoToAlbum(this.albumNodeUid, payload, this.signal);
+                    await this.nodesService.notifyChildCreated(newPhotoNodeUid);
+                    yield { uid: payload.nodeUid, ok: true };
+                } catch (error) {
+                    if (error instanceof MissingRelatedPhotosError) {
+                        const retryItem = this.createRetryQueueItem(payload.nodeUid, error);
+                        if (retryItem) {
+                            queue.push(retryItem);
+                            continue;
+                        }
+                    }
+                    yield {
+                        uid: payload.nodeUid,
+                        ok: false,
+                        error: error instanceof Error ? error : new Error(c('Error').t`Unknown error`, { cause: error }),
+                    };
+                }
+            }
+        }
+    }
+
+    private async preparePhotoPayloads(items: PhotoQueueItem[]): Promise<{
+        payloads: AddToAlbumEncryptedPhotoPayload[];
+        errors: Map<string, Error>;
+    }> {
+        const payloads: AddToAlbumEncryptedPhotoPayload[] = [];
+        const errors = new Map<string, Error>();
+
+        const additionalRelatedMap = new Map(
+            items.map((item) => [item.photoNodeUid, item.additionalRelatedPhotoNodeUids]),
+        );
+
+        const nodeUids = items.map((item) => item.photoNodeUid);
+        for await (const photoNode of this.nodesService.iterateNodes(nodeUids, this.signal)) {
+            if ('missingUid' in photoNode) {
+                errors.set(photoNode.missingUid, new ValidationError(c('Error').t`Photo not found`));
+                continue;
+            }
+
+            try {
+                const additionalRelated = additionalRelatedMap.get(photoNode.uid) || [];
+                const payload = await this.preparePhotoPayload(photoNode, additionalRelated);
+                payloads.push(payload);
+            } catch (error) {
+                errors.set(
+                    photoNode.uid,
+                    error instanceof Error ? error : new Error(c('Error').t`Unknown error`, { cause: error }),
+                );
+            }
+        }
+
+        return { payloads, errors };
+    }
+
+    private async preparePhotoPayload(
+        photoNode: DecryptedPhotoNode,
+        additionalRelatedPhotoNodeUids: string[],
+    ): Promise<AddToAlbumEncryptedPhotoPayload> {
+        const photoData = await this.encryptPhotoForAlbum(photoNode);
+
+        const relatedNodeUids = [...new Set([
+            ...(photoNode.photo?.relatedPhotoNodeUids || []),
+            ...additionalRelatedPhotoNodeUids,
+        ])];
+
+        const relatedPhotos =
+            relatedNodeUids.length > 0 ? await this.prepareRelatedPhotoPayloads(relatedNodeUids) : [];
+
+        return {
+            ...photoData,
+            relatedPhotos,
+        };
+    }
+
+    private async prepareRelatedPhotoPayloads(
+        nodeUids: string[],
+    ): Promise<Omit<AddToAlbumEncryptedPhotoPayload, 'relatedPhotos'>[]> {
+        const payloads: Omit<AddToAlbumEncryptedPhotoPayload, 'relatedPhotos'>[] = [];
+
+        for await (const photoNode of this.nodesService.iterateNodes(nodeUids, this.signal)) {
+            // Missing related photos means that the related photo was deleted
+            // since the loading of the metadata. It can happen and should be
+            // ignored. The backend controls all the related photos are part
+            // of the request, thus the request will fail and be retried if
+            // there is any other race condition.
+            if ('missingUid' in photoNode) {
+                continue;
+            }
+            const payload = await this.encryptPhotoForAlbum(photoNode);
+            payloads.push(payload);
+        }
+
+        return payloads;
+    }
+
+    private async encryptPhotoForAlbum(
+        photoNode: DecryptedPhotoNode,
+    ): Promise<AddToAlbumEncryptedPhotoPayload> {
+        const nodeKeys = await this.nodesService.getNodePrivateAndSessionKeys(photoNode.uid);
+
+        const contentSha1 = photoNode.activeRevision?.ok
+            ? photoNode.activeRevision.value.claimedDigests?.sha1
+            : undefined;
+
+        if (!contentSha1) {
+            throw new Error('Cannot add photo to album without a content hash');
+        }
+
+        const encryptedCrypto = await this.cryptoService.encryptPhotoForAlbum(
+            photoNode.name,
+            contentSha1,
+            nodeKeys,
+            { key: this.albumKeys.key, hashKey: this.albumKeys.hashKey! },
+            this.signingKeys,
+        );
+
+        // Node could be uploaded or renamed by anonymous user and thus have
+        // missing signatures that must be added to the request.
+        // Node passphrase and signature email must be passed if and only if
+        // the signatures are missing (key author is null).
+        const anonymousKey = photoNode.keyAuthor.ok && photoNode.keyAuthor.value === null;
+        const keySignatureProperties = !anonymousKey
+            ? {}
+            : {
+                  signatureEmail: encryptedCrypto.signatureEmail,
+                  nodePassphraseSignature: encryptedCrypto.armoredNodePassphraseSignature,
+              };
+
+        return {
+            nodeUid: photoNode.uid,
+            contentHash: encryptedCrypto.contentHash,
+            nameHash: encryptedCrypto.hash,
+            encryptedName: encryptedCrypto.encryptedName,
+            nameSignatureEmail: encryptedCrypto.nameSignatureEmail,
+            nodePassphrase: encryptedCrypto.armoredNodePassphrase,
+            ...keySignatureProperties,
+        };
+    }
+
+    /**
+     * If the result indicates a MissingRelatedPhotosError that hasn't
+     * been retried, returns a retry queue item. Otherwise returns undefined.
+     */
+    private handleMissingRelatedPhotosError(result: NodeResultWithError): PhotoQueueItem | undefined {
+        if (!result.ok && result.error instanceof MissingRelatedPhotosError) {
+            return this.createRetryQueueItem(result.uid, result.error);
+        }
+        return undefined;
+    }
+
+    /**
+     * Creates a retry queue item with the missing related photo UIDs.
+     * Returns undefined if the photo has already been retried, preventing
+     * infinite retry loops.
+     */
+    private createRetryQueueItem(
+        photoNodeUid: string,
+        error: MissingRelatedPhotosError,
+    ): PhotoQueueItem | undefined {
+        if (this.retriedPhotoUids.has(photoNodeUid)) {
+            this.logger.warn(`Missing related photos for ${photoNodeUid}, already retried`);
+            return undefined;
+        }
+
+        this.retriedPhotoUids.add(photoNodeUid);
+        this.logger.info(
+            `Missing related photos for ${photoNodeUid}, re-queuing: ${error.missingNodeUids.join(', ')}`,
+        );
+
+        return {
+            photoNodeUid,
+            additionalRelatedPhotoNodeUids: error.missingNodeUids,
+        };
+    }
+}
+
+/**
+ * Splits photo UIDs into same-volume and different-volume queues
+ * based on the album's volume ID.
+ */
+function splitByVolume(
+    photoNodeUids: string[],
+    albumVolumeId: string,
+): {
+    sameVolumeQueue: PhotoQueueItem[];
+    differentVolumeQueue: PhotoQueueItem[];
+} {
+    const sameVolumeQueue: PhotoQueueItem[] = [];
+    const differentVolumeQueue: PhotoQueueItem[] = [];
+
+    for (const photoNodeUid of photoNodeUids) {
+        const { volumeId } = splitNodeUid(photoNodeUid);
+        const item: PhotoQueueItem = {
+            photoNodeUid,
+            additionalRelatedPhotoNodeUids: [],
+        };
+
+        if (volumeId === albumVolumeId) {
+            sameVolumeQueue.push(item);
+        } else {
+            differentVolumeQueue.push(item);
+        }
+    }
+
+    return { sameVolumeQueue, differentVolumeQueue };
+}
+
+/**
+ * Groups payloads into batches respecting the API limit.
+ * Each payload's size counts itself plus its related photos.
+ */
+function* createBatches(
+    payloads: AddToAlbumEncryptedPhotoPayload[],
+): Generator<AddToAlbumEncryptedPhotoPayload[]> {
+    let batch: AddToAlbumEncryptedPhotoPayload[] = [];
+    let batchSize = 0;
+
+    for (const payload of payloads) {
+        const payloadSize = 1 + (payload.relatedPhotos?.length || 0);
+
+        if (batch.length > 0 && batchSize + payloadSize > ADD_PHOTOS_BATCH_SIZE) {
+            yield batch;
+            batch = [];
+            batchSize = 0;
+        }
+
+        batch.push(payload);
+        batchSize += payloadSize;
+    }
+
+    if (batch.length > 0) {
+        yield batch;
+    }
+}

package/src/internal/photos/albums.test.ts

@@ -1,5 +1,6 @@
-import { NodeType, MemberRole } from '../../interface';
+import { NodeType } from '../../interface';
 import { ValidationError } from '../../errors';
+import { getMockTelemetry } from '../../tests/telemetry';
 import { Albums } from './albums';
 import { AlbumsCryptoService } from './albumsCrypto';
 import { PhotosAPIService } from './apiService';
@@ -37,6 +38,7 @@ describe('Albums', () => {
             createAlbum: jest.fn().mockResolvedValue('volumeId~newAlbumNodeId'),
             updateAlbum: jest.fn(),
             deleteAlbum: jest.fn(),
+            removePhotosFromAlbum: jest.fn(),
         };
 
         // @ts-expect-error No need to implement all methods for mocking
@@ -95,7 +97,7 @@ describe('Albums', () => {
             notifyChildCreated: jest.fn(),
         };
 
-        albums = new Albums(apiService, cryptoService, photoShares, nodesService);
+        albums = new Albums(getMockTelemetry(), apiService, cryptoService, photoShares, nodesService);
     });
 
     describe('createAlbum', () => {
@@ -171,16 +173,12 @@ describe('Albums', () => {
                 { type: 'userAddress', email: 'user@example.com', addressId: 'addressId', key: 'addressKey' },
                 'new album name',
             );
-            expect(apiService.updateAlbum).toHaveBeenCalledWith(
-                'albumNodeUid',
-                undefined,
-                {
-                    encryptedName: 'newArmoredAlbumName',
-                    hash: 'newHash',
-                    originalHash: 'albumHash',
-                    nameSignatureEmail: 'newSignatureEmail',
-                },
-            );
+            expect(apiService.updateAlbum).toHaveBeenCalledWith('albumNodeUid', undefined, {
+                encryptedName: 'newArmoredAlbumName',
+                hash: 'newHash',
+                originalHash: 'albumHash',
+                nameSignatureEmail: 'newSignatureEmail',
+            });
             expect(nodesService.notifyNodeChanged).toHaveBeenCalledWith('albumNodeUid');
         });
 
@@ -206,16 +204,12 @@ describe('Albums', () => {
                 nameAuthor: { ok: true, value: 'newSignatureEmail' },
                 hash: 'newHash',
             });
-            expect(apiService.updateAlbum).toHaveBeenCalledWith(
-                'albumNodeUid',
-                'photoNodeUid',
-                {
-                    encryptedName: 'newArmoredAlbumName',
-                    hash: 'newHash',
-                    originalHash: 'albumHash',
-                    nameSignatureEmail: 'newSignatureEmail',
-                },
-            );
+            expect(apiService.updateAlbum).toHaveBeenCalledWith('albumNodeUid', 'photoNodeUid', {
+                encryptedName: 'newArmoredAlbumName',
+                hash: 'newHash',
+                originalHash: 'albumHash',
+                nameSignatureEmail: 'newSignatureEmail',
+            });
         });
 
         it('throws validation error for invalid album name', async () => {
@@ -238,4 +232,34 @@ describe('Albums', () => {
             expect(nodesService.notifyNodeDeleted).toHaveBeenCalledWith('albumNodeUid');
         });
     });
+
+    describe('removePhotos', () => {
+        it('notifies nodes service only for successfully removed photos', async () => {
+            apiService.removePhotosFromAlbum = jest.fn().mockImplementation(async function* () {
+                yield { uid: 'photo1', ok: true };
+                yield { uid: 'photo2', ok: false, error: 'Some error' };
+                yield { uid: 'photo3', ok: true };
+            });
+
+            const results = [];
+            for await (const result of albums.removePhotos('albumNodeUid', ['photo1', 'photo2', 'photo3'])) {
+                results.push(result);
+            }
+
+            expect(results).toEqual([
+                { uid: 'photo1', ok: true },
+                { uid: 'photo2', ok: false, error: 'Some error' },
+                { uid: 'photo3', ok: true },
+            ]);
+            expect(apiService.removePhotosFromAlbum).toHaveBeenCalledWith(
+                'albumNodeUid',
+                ['photo1', 'photo2', 'photo3'],
+                undefined,
+            );
+            expect(nodesService.notifyNodeChanged).toHaveBeenCalledTimes(2);
+            expect(nodesService.notifyNodeChanged).toHaveBeenCalledWith('photo1');
+            expect(nodesService.notifyNodeChanged).toHaveBeenCalledWith('photo3');
+            expect(nodesService.notifyNodeChanged).not.toHaveBeenCalledWith('photo2');
+        });
+    });
 });

package/src/internal/photos/albums.ts

@@ -1,12 +1,13 @@
-import { MemberRole, NodeType, resultOk } from '../../interface';
+import { Logger, MemberRole, NodeResultWithError, NodeType, ProtonDriveTelemetry, resultOk } from '../../interface';
 import { BatchLoading } from '../batchLoading';
 import { DecryptedNode } from '../nodes';
 import { ALBUM_MEDIA_TYPE } from '../nodes/mediaTypes';
 import { validateNodeName } from '../nodes/validations';
 import { splitNodeUid } from '../uids';
+import { AddToAlbumProcess } from './addToAlbum';
 import { AlbumsCryptoService } from './albumsCrypto';
 import { PhotosAPIService } from './apiService';
-import { DecryptedPhotoNode } from './interface';
+import { AlbumItem, DecryptedPhotoNode } from './interface';
 import { PhotosNodesAccess } from './nodes';
 import { PhotoSharesManager } from './shares';
 
@@ -16,12 +17,16 @@ const BATCH_LOADING_SIZE = 10;
  * Provides access and high-level actions for managing albums.
  */
 export class Albums {
+    private logger: Logger;
+
     constructor(
+        telemetry: ProtonDriveTelemetry,
         private apiService: PhotosAPIService,
         private cryptoService: AlbumsCryptoService,
         private photoShares: PhotoSharesManager,
         private nodesService: PhotosNodesAccess,
     ) {
+        this.logger = telemetry.getLogger('albums');
         this.apiService = apiService;
         this.cryptoService = cryptoService;
         this.photoShares = photoShares;
@@ -41,6 +46,10 @@ export class Albums {
         yield* batchLoading.loadRest();
     }
 
+    async *iterateAlbum(albumNodeUid: string, signal?: AbortSignal): AsyncGenerator<AlbumItem> {
+        yield* this.apiService.iterateAlbumChildren(albumNodeUid, signal);
+    }
+
     async createAlbum(name: string): Promise<DecryptedPhotoNode> {
         validateNodeName(name);
 
@@ -152,6 +161,43 @@ export class Albums {
         await this.nodesService.notifyNodeDeleted(nodeUid);
     }
 
+    async *addPhotos(
+        albumNodeUid: string,
+        photoNodeUids: string[],
+        signal?: AbortSignal,
+    ): AsyncGenerator<NodeResultWithError> {
+        const albumKeys = await this.nodesService.getNodeKeys(albumNodeUid);
+        if (!albumKeys.hashKey) {
+            throw new Error('Cannot add photos to album: album hash key not available');
+        }
+        const signingKeys = await this.nodesService.getNodeSigningKeys({ nodeUid: albumNodeUid });
+
+        const process = new AddToAlbumProcess(
+            albumNodeUid,
+            albumKeys,
+            signingKeys,
+            this.apiService,
+            this.cryptoService,
+            this.nodesService,
+            this.logger,
+            signal,
+        );
+        yield * process.execute(photoNodeUids);
+    }
+
+    async *removePhotos(
+        albumNodeUid: string,
+        photoNodeUids: string[],
+        signal?: AbortSignal,
+    ): AsyncGenerator<NodeResultWithError> {
+        for await (const result of this.apiService.removePhotosFromAlbum(albumNodeUid, photoNodeUids, signal)) {
+            if (result.ok) {
+                await this.nodesService.notifyNodeChanged(result.uid);
+            }
+            yield result;
+        }
+    }
+
     private async *iterateNodesAndIgnoreMissingOnes(
         nodeUids: string[],
         signal?: AbortSignal,

package/src/internal/photos/albumsCrypto.ts

@@ -1,4 +1,7 @@
-import { DriveCrypto, PrivateKey } from '../../crypto';
+import { c } from 'ttag';
+import { DriveCrypto, PrivateKey, SessionKey } from '../../crypto';
+import { ValidationError } from '../../errors';
+import { InvalidNameError, Result } from '../../interface';
 import { DecryptedNodeKeys, NodeSigningKeys } from '../nodes/interface';
 
 /**
@@ -13,7 +16,7 @@ export class AlbumsCryptoService {
     }
 
     async createAlbum(
-        parentKeys: { key: PrivateKey; hashKey: Uint8Array },
+        parentKeys: { key: PrivateKey; hashKey: Uint8Array<ArrayBuffer> },
         signingKeys: NodeSigningKeys,
         name: string,
     ): Promise<{
@@ -62,7 +65,7 @@ export class AlbumsCryptoService {
     }
 
     async renameAlbum(
-        parentKeys: { key: PrivateKey; hashKey?: Uint8Array },
+        parentKeys: { key: PrivateKey; hashKey?: Uint8Array<ArrayBuffer> },
         encryptedName: string,
         signingKeys: NodeSigningKeys,
         newName: string,
@@ -97,4 +100,52 @@ export class AlbumsCryptoService {
             hash,
         };
     }
+
+    async encryptPhotoForAlbum(
+        nodeName: Result<string, Error | InvalidNameError>,
+        sha1: string,
+        nodeKeys: { passphrase: string; passphraseSessionKey: SessionKey; nameSessionKey: SessionKey },
+        albumKeys: { key: PrivateKey; hashKey: Uint8Array<ArrayBuffer> },
+        signingKeys: NodeSigningKeys,
+    ): Promise<{
+        encryptedName: string;
+        hash: string;
+        contentHash: string;
+        armoredNodePassphrase: string;
+        armoredNodePassphraseSignature: string;
+        signatureEmail: string;
+        nameSignatureEmail: string;
+    }> {
+        if (!nodeName.ok) {
+            throw new ValidationError(c('Error').t`Cannot add photo to album without a valid name`);
+        }
+        if (signingKeys.type !== 'userAddress') {
+            throw new Error('Adding photos to album by anonymous user is not supported');
+        }
+        const email = signingKeys.email;
+        const signingKey = signingKeys.key;
+
+        const [{ armoredNodeName }, hash, contentHash, { armoredPassphrase, armoredPassphraseSignature }] =
+            await Promise.all([
+                this.driveCrypto.encryptNodeName(nodeName.value, nodeKeys.nameSessionKey, albumKeys.key, signingKey),
+                this.driveCrypto.generateLookupHash(nodeName.value, albumKeys.hashKey),
+                this.driveCrypto.generateLookupHash(sha1, albumKeys.hashKey),
+                this.driveCrypto.encryptPassphrase(
+                    nodeKeys.passphrase,
+                    nodeKeys.passphraseSessionKey,
+                    [albumKeys.key],
+                    signingKey,
+                ),
+            ]);
+
+        return {
+            encryptedName: armoredNodeName,
+            hash,
+            contentHash,
+            armoredNodePassphrase: armoredPassphrase,
+            armoredNodePassphraseSignature: armoredPassphraseSignature,
+            signatureEmail: email,
+            nameSignatureEmail: email,
+        };
+    }
 }