@protontech/drive-sdk 0.4.1 → 0.5.1

package/src/diagnostic/sdkDiagnostic.ts

@@ -1,6 +1,6 @@
 import { Author, FileDownloader, MaybeNode, NodeType, Revision, ThumbnailType } from '../interface';
 import { ProtonDriveClient } from '../protonDriveClient';
-import { Diagnostic, DiagnosticOptions, DiagnosticResult, NodeDetails } from './interface';
+import { DiagnosticOptions, DiagnosticResult, NodeDetails, ExcpectedTreeNode } from './interface';
 import { IntegrityVerificationStream } from './integrityVerificationStream';
 
 /**
@@ -10,7 +10,7 @@ import { IntegrityVerificationStream } from './integrityVerificationStream';
  * It produces only events that can be read by direct SDK invocation.
  * To get the full diagnostic, use {@link FullSDKDiagnostic}.
  */
-export class SDKDiagnostic implements Diagnostic {
+export class SDKDiagnostic {
     constructor(private protonDriveClient: ProtonDriveClient) {
         this.protonDriveClient = protonDriveClient;
     }
@@ -58,7 +58,7 @@ export class SDKDiagnostic implements Diagnostic {
             yield* this.verifyAuthor(activeRevision.contentAuthor, 'content', node);
         }
 
-        yield* this.verifyFileExtendedAttributes(node);
+        yield* this.verifyFileExtendedAttributes(node, options);
 
         if (options?.verifyContent) {
             yield* this.verifyContent(node);
@@ -80,12 +80,17 @@ export class SDKDiagnostic implements Diagnostic {
         }
     }
 
-    private async *verifyFileExtendedAttributes(node: MaybeNode): AsyncGenerator<DiagnosticResult> {
+    private async *verifyFileExtendedAttributes(
+        node: MaybeNode,
+        options?: DiagnosticOptions,
+    ): AsyncGenerator<DiagnosticResult> {
         const activeRevision = getActiveRevision(node);
 
         const expectedAttributes = getNodeType(node) === NodeType.File;
 
         const claimedSha1 = activeRevision?.claimedDigests?.sha1;
+        const claimedSizeInBytes = activeRevision?.claimedSize;
+
         if (claimedSha1 && !/^[0-9a-f]{40}$/i.test(claimedSha1)) {
             yield {
                 type: 'extended_attributes_error',
@@ -102,6 +107,24 @@ export class SDKDiagnostic implements Diagnostic {
                 ...getNodeDetails(node),
             };
         }
+
+        if (options?.expectedStructure) {
+            const expectedSha1 = options.expectedStructure.expectedSha1;
+            const expectedSizeInBytes = options.expectedStructure.expectedSizeInBytes;
+
+            const wrongSha1 = expectedSha1 !== undefined && claimedSha1 !== expectedSha1;
+            const wrongSizeInBytes = expectedSizeInBytes !== undefined && claimedSizeInBytes !== expectedSizeInBytes;
+
+            if (wrongSha1 || wrongSizeInBytes) {
+                yield {
+                    type: 'expected_structure_integrity_error',
+                    claimedSha1,
+                    claimedSizeInBytes,
+                    expectedNode: getExpectedTreeNodeDetails(options.expectedStructure),
+                    ...getNodeDetails(node),
+                };
+            }
+        }
     }
 
     private async *verifyContent(node: MaybeNode): AsyncGenerator<DiagnosticResult> {
@@ -133,7 +156,7 @@ export class SDKDiagnostic implements Diagnostic {
         const claimedSizeInBytes = downloader.getClaimedSizeInBytes();
 
         const integrityVerificationStream = new IntegrityVerificationStream();
-        const controller = downloader.writeToStream(integrityVerificationStream);
+        const controller = downloader.downloadToStream(integrityVerificationStream);
 
         try {
             await controller.completion();
@@ -195,19 +218,73 @@ export class SDKDiagnostic implements Diagnostic {
         }
     }
 
-    private async *verifyNodeChildren(node: MaybeNode, options?: DiagnosticOptions): AsyncGenerator<DiagnosticResult> {
-        const nodeUid = node.ok ? node.value.uid : node.error.uid;
+    private async *verifyNodeChildren(
+        parentNode: MaybeNode,
+        options?: DiagnosticOptions,
+    ): AsyncGenerator<DiagnosticResult> {
+        const parentNodeUid = parentNode.ok ? parentNode.value.uid : parentNode.error.uid;
+        const children: MaybeNode[] = [];
+
         try {
-            for await (const child of this.protonDriveClient.iterateFolderChildren(node)) {
-                yield* this.verifyNodeTree(child, options);
+            for await (const child of this.protonDriveClient.iterateFolderChildren(parentNode)) {
+                if (options?.expectedStructure) {
+                    children.push(child);
+                }
+
+                yield *
+                    this.verifyNodeTree(child, {
+                        ...options,
+                        expectedStructure: options?.expectedStructure
+                            ? getTreeNodeChildByNodeName(options.expectedStructure, getNodeName(child))
+                            : undefined,
+                    });
             }
         } catch (error: unknown) {
             yield {
                 type: 'sdk_error',
-                call: `iterateFolderChildren(${nodeUid})`,
+                call: `iterateFolderChildren(${parentNodeUid})`,
                 error,
             };
         }
+
+        if (options?.expectedStructure) {
+            yield* this.verifyExpectedNodeChildren(parentNodeUid, children, options);
+        }
+    }
+
+    private async *verifyExpectedNodeChildren(
+        parentNodeUid: string,
+        children: MaybeNode[],
+        options: DiagnosticOptions,
+    ): AsyncGenerator<DiagnosticResult> {
+        if (!options.expectedStructure) {
+            return;
+        }
+
+        const expectedNodes = options.expectedStructure.children ?? [];
+        const actualNodeNames = children.map((child) => getNodeName(child));
+
+        for (const expectedNode of expectedNodes) {
+            if (!actualNodeNames.includes(expectedNode.name)) {
+                yield {
+                    type: 'expected_structure_missing_node',
+                    expectedNode: getExpectedTreeNodeDetails(expectedNode),
+                    parentNodeUid,
+                };
+            }
+        }
+
+        for (const child of children) {
+            const childName = getNodeName(child);
+            const isExpected = expectedNodes.some((expectedNode) => expectedNode.name === childName);
+
+            if (!isExpected) {
+                yield {
+                    type: 'expected_structure_unexpected_node',
+                    ...getNodeDetails(child),
+                };
+            }
+        }
     }
 }
 
@@ -275,3 +352,27 @@ function getActiveRevision(node: MaybeNode): Revision | undefined {
     }
     return undefined;
 }
+
+function getNodeName(node: MaybeNode): string {
+    if (node.ok) {
+        return node.value.name;
+    }
+    if (node.error.name.ok) {
+        return node.error.name.value;
+    }
+    return 'N/A';
+}
+
+function getExpectedTreeNodeDetails(expectedNode: ExcpectedTreeNode): ExcpectedTreeNode {
+    return {
+        ...expectedNode,
+        children: undefined,
+    };
+}
+
+function getTreeNodeChildByNodeName(
+    expectedSubtree: ExcpectedTreeNode,
+    nodeName: string,
+): ExcpectedTreeNode | undefined {
+    return expectedSubtree.children?.find((expectedNode) => expectedNode.name === nodeName);
+}

package/src/interface/download.ts

@@ -15,14 +15,14 @@ export interface FileDownloader {
      *
      * @param onProgress - Callback that is called with the number of downloaded bytes
      */
-    writeToStream(streamFactory: WritableStream, onProgress?: (downloadedBytes: number) => void): DownloadController;
+    downloadToStream(streamFactory: WritableStream, onProgress?: (downloadedBytes: number) => void): DownloadController;
 
     /**
-     * Same as `writeToStream` but without verification checks.
+     * Same as `downloadToStream` but without verification checks.
      *
      * Use this only for debugging purposes.
      */
-    unsafeWriteToStream(
+    unsafeDownloadToStream(
         streamFactory: WritableStream,
         onProgress?: (downloadedBytes: number) => void,
     ): DownloadController;
@@ -34,7 +34,7 @@ export interface FileDownloader {
      * need to download the entire file.
      *
      * Stream doesn't verify data integrity. For the full integrity of
-     * the file, use `writeToStream` instead.
+     * the file, use `downloadToStream` instead.
      *
      * The stream is not opportunitistically downloading the data ahead of
      * the time. It will only download the data when it is requested. To

package/src/interface/index.ts

@@ -41,6 +41,7 @@ export type {
     NodeOrUid,
     RevisionOrUid,
     NodeResult,
+    NodeResultWithNewUid,
     Membership,
 } from './nodes';
 export { NodeType, MemberRole, RevisionState } from './nodes';

package/src/interface/nodes.ts

@@ -224,3 +224,6 @@ export type NodeOrUid = MaybeNode | NodeEntity | DegradedNode | string;
 export type RevisionOrUid = Revision | string;
 
 export type NodeResult = { uid: string; ok: true } | { uid: string; ok: false; error: string };
+export type NodeResultWithNewUid =
+    | { uid: string; newUid: string; ok: true }
+    | { uid: string; ok: false; error: string };

package/src/interface/telemetry.ts

@@ -12,6 +12,7 @@ export interface Logger {
 
 export type MetricEvent =
     | MetricAPIRetrySucceededEvent
+    | MetricDebounceLongWaitEvent
     | MetricUploadEvent
     | MetricDownloadEvent
     | MetricDecryptionErrorEvent
@@ -25,6 +26,10 @@ export interface MetricAPIRetrySucceededEvent {
     failedAttempts: number;
 }
 
+export interface MetricDebounceLongWaitEvent {
+    eventName: 'debounceLongWait';
+}
+
 export interface MetricUploadEvent {
     eventName: 'upload';
     volumeType?: MetricVolumeType;

package/src/interface/upload.ts

@@ -41,7 +41,7 @@ export interface FileRevisionUploader {
      *
      * The function will reject if the node with the given name already exists.
      */
-    writeStream(
+    uploadFromStream(
         stream: ReadableStream,
         thumnbails: Thumbnail[],
         onProgress?: (uploadedBytes: number) => void,
@@ -57,7 +57,7 @@ export interface FileRevisionUploader {
      *
      * The function will reject if the node with the given name already exists.
      */
-    writeFile(
+    uploadFromFile(
         fileObject: File,
         thumnbails: Thumbnail[],
         onProgress?: (uploadedBytes: number) => void,
@@ -79,5 +79,5 @@ export interface FileUploader extends FileRevisionUploader {
 export interface UploadController {
     pause(): void;
     resume(): void;
-    completion(): Promise<string>;
+    completion(): Promise<{ nodeRevisionUid: string, nodeUid: string }>;
 }

package/src/internal/apiService/apiService.test.ts

@@ -1,3 +1,4 @@
+import { AbortError } from '../../errors';
 import { ProtonDriveHTTPClient, SDKEvent } from '../../interface';
 import { getMockTelemetry } from '../../tests/telemetry';
 import { SDKEvents } from '../sdkEvents';
@@ -112,6 +113,16 @@ describe('DriveAPIService', () => {
     });
 
     describe('should throw', () => {
+        it('AbortError on aborted error from the provided HTTP client', async () => {
+            const abortError = new Error('AbortError');
+            abortError.name = 'AbortError';
+
+            httpClient.fetchJson = jest.fn(() => Promise.reject(abortError));
+
+            await expect(api.get('test')).rejects.toThrow(new AbortError('Request aborted'));
+            expectSDKEvents();
+        });
+
         it('APIHTTPError on 4xx response without JSON body', async () => {
             httpClient.fetchJson = jest.fn(() =>
                 Promise.resolve(new Response('Not found', { status: 404, statusText: 'Not found' })),
@@ -314,5 +325,44 @@ describe('DriveAPIService', () => {
             expect(httpClient.fetchJson).toHaveBeenCalledTimes(35);
             expectSDKEvents();
         });
+
+        it('notify about offline error', async () => {
+            jest.useFakeTimers();
+            const offlineError = new Error('OfflineError');
+            offlineError.name = 'OfflineError';
+
+            let attempt = 0;
+            httpClient.fetchJson = jest.fn().mockImplementation(() => {
+                if (attempt++ >= 15) {
+                    return generateOkResponse();
+                }
+                throw offlineError;
+            });
+
+            const promise = api.get('test');
+
+            // First 9 calls (first is immediate, then 8 with 5 second delay), no events are sent yet
+            await jest.advanceTimersByTimeAsync(5 * 8 * 1000);
+            expect(httpClient.fetchJson).toHaveBeenCalledTimes(9);
+            expectSDKEvents();
+
+            // 10th call, service sends TransfersPaused event
+            await jest.advanceTimersByTimeAsync(5 * 1000);
+            expect(httpClient.fetchJson).toHaveBeenCalledTimes(10);
+            expectSDKEvents(SDKEvent.TransfersPaused);
+
+            // Next 5 calls, still offline, no more events are sent
+            await jest.advanceTimersByTimeAsync(5 * 5 * 1000);
+            expect(httpClient.fetchJson).toHaveBeenCalledTimes(15);
+            expectSDKEvents(SDKEvent.TransfersPaused);
+
+            // 16th call, mock returns OK response, service sends TransfersResumed event
+            await jest.advanceTimersByTimeAsync(5 * 1000);
+            expect(httpClient.fetchJson).toHaveBeenCalledTimes(16);
+            expectSDKEvents(SDKEvent.TransfersPaused, SDKEvent.TransfersResumed);
+
+            await promise;
+        });
+
     });
 });

package/src/internal/apiService/apiService.ts

@@ -40,6 +40,11 @@ const TOO_MANY_SUBSEQUENT_SERVER_ERRORS = 10;
  */
 const TOO_MANY_SUBSEQUENT_SERVER_ERRORS_TIMEOUT_IN_SECONDS = 60;
 
+/**
+ * How many subsequent offline errors are allowed before we consider the client offline.
+ */
+const TOO_MANY_SUBSEQUENT_OFFLINE_ERRORS = 10;
+
 /**
  * After how long to re-try after 5xx or timeout error.
  */
@@ -88,6 +93,8 @@ export class DriveAPIService {
     private subsequentServerErrorsCounter = 0;
     private lastServerErrorAt?: number;
 
+    private subsequentOfflineErrorsCounter = 0;
+
     private logger: Logger;
 
     constructor(
@@ -219,7 +226,7 @@ export class DriveAPIService {
                 if (error instanceof ProtonDriveError) {
                     throw error;
                 }
-                throw apiErrorFactory({ response });
+                throw apiErrorFactory({ response, error });
             }
         }
         return response;
@@ -261,7 +268,13 @@ export class DriveAPIService {
             response = await callback();
         } catch (error: unknown) {
             if (error instanceof Error) {
+                if (error.name === 'AbortError') {
+                    this.logger.debug(`${request.method} ${request.url}: Aborted`);
+                    throw new AbortError(c('Error').t`Request aborted`);
+                }
+
                 if (error.name === 'OfflineError') {
+                    this.offlineErrorHappened();
                     this.logger.info(`${request.method} ${request.url}: Offline error, retrying`);
                     await waitSeconds(OFFLINE_RETRY_DELAY_SECONDS);
                     return this.fetch(request, callback, attempt + 1);
@@ -282,6 +295,8 @@ export class DriveAPIService {
             throw error;
         }
 
+        this.clearSubsequentOfflineErrors();
+
         const end = Date.now();
         const duration = end - start;
 
@@ -342,7 +357,7 @@ export class DriveAPIService {
         // the client is very limited. This is generic event and it doesn't
         // take into account that various endpoints can be rate limited
         // independently.
-        if (this.subsequentTooManyRequestsCounter >= TOO_MANY_SUBSEQUENT_429_ERRORS) {
+        if (this.subsequentTooManyRequestsCounter === TOO_MANY_SUBSEQUENT_429_ERRORS) {
             this.sdkEvents.requestsThrottled();
         }
     }
@@ -373,4 +388,20 @@ export class DriveAPIService {
         this.subsequentServerErrorsCounter = 0;
         this.lastServerErrorAt = undefined;
     }
+
+    private offlineErrorHappened() {
+        this.subsequentOfflineErrorsCounter++;
+
+        if (this.subsequentOfflineErrorsCounter === TOO_MANY_SUBSEQUENT_OFFLINE_ERRORS) {
+            this.sdkEvents.transfersPaused();
+        }
+    }
+
+    private clearSubsequentOfflineErrors() {
+        if (this.subsequentOfflineErrorsCounter >= TOO_MANY_SUBSEQUENT_OFFLINE_ERRORS) {
+            this.sdkEvents.transfersResumed();
+        }
+
+        this.subsequentOfflineErrorsCounter = 0;
+    }
 }