@protontech/drive-sdk 0.1.1 → 0.2.0

package/src/internal/download/seekableStream.ts

@@ -0,0 +1,182 @@
+interface UnderlyingSeekableSource extends UnderlyingDefaultSource<Uint8Array> {
+    seek: (position: number) => void | Promise<void>;
+}
+
+/**
+ * A seekable readable stream that can be used to seek to a specific position
+ * in the stream.
+ *
+ * This is useful for downloading the file in chunks or jumping to a specific
+ * position in the file when streaming a video.
+ *
+ * Example to get next chunk of data from the stream at position 100:
+ *
+ * ```
+ * const stream = new SeekableReadableStream(underlyingSource);
+ * const reader = stream.getReader();
+ * await stream.seek(100);
+ * const data = await stream.read();
+ * console.log(data);
+ * ```
+ */
+export class SeekableReadableStream extends ReadableStream<Uint8Array> {
+    private seekCallback: (position: number) => void | Promise<void>;
+
+    constructor({ seek, ...underlyingSource }: UnderlyingSeekableSource, queuingStrategy?: QueuingStrategy<Uint8Array>) {
+        super(underlyingSource, queuingStrategy);
+        this.seekCallback = seek;
+    }
+
+    seek(position: number): void | Promise<void> {
+        return this.seekCallback(position);
+    }
+}
+
+/**
+ * A buffered seekable stream that allows to seek and read specific number of
+ * bytes from the stream.
+ *
+ * This is useful for reading specific range of data from the stream. Example
+ * being video player buffering the next several bytes.
+ *
+ * The underlying source can chunk the data into various sizes. To ensure that
+ * every read operation is for the correct location, the SeekableStream is not
+ * queueing the data upfront. Instead, it will read the data and buffer it for
+ * the next read operation. If seek is called, the internal buffer is updated
+ * accordingly.
+ *
+ * Example to read 10 bytes from the stream at position 100:
+ *
+ * ```
+ * const stream = new BufferedSeekableStream(underlyingSource);
+ * await stream.seek(100);
+ * const data = await stream.read(10);
+ * console.log(data);
+ * ```
+ */
+export class BufferedSeekableStream extends SeekableReadableStream {
+    private buffer: Uint8Array = new Uint8Array(0);
+    private bufferPosition: number = 0;
+    private reader: ReadableStreamDefaultReader<Uint8Array> | null = null;
+    private streamClosed: boolean = false;
+    private currentPosition: number = 0;
+
+    constructor(underlyingSource: UnderlyingSeekableSource, queuingStrategy?: QueuingStrategy<Uint8Array>) {
+        // highWaterMark means that the stream will buffer up to this many
+        // bytes. We do not want to buffer anything
+        if (queuingStrategy && queuingStrategy.highWaterMark !== 0) {
+            throw new Error('highWaterMark must be 0');
+        }
+
+        super(underlyingSource, {
+            ...queuingStrategy,
+            highWaterMark: 0,
+        });
+
+        this.reader = super.getReader();
+    }
+
+    /**
+     * Read a specific number of bytes from the stream.
+     *
+     * When the underlying source provides more bytes than requested, the
+     * remaining bytes are buffered and used for the next read operation.
+     *
+     * @param numBytes - Number of bytes to read
+     * @returns Promise<Uint8Array> The read bytes
+     */
+    async read(numBytes: number): Promise<{ value: Uint8Array; done: boolean }> {
+        if (numBytes <= 0) {
+            throw new Error('Invalid number of bytes to read');
+        }
+
+        await this.ensureBufferSize(numBytes);
+
+        const result = this.buffer.slice(this.bufferPosition, this.bufferPosition + numBytes);
+        this.bufferPosition += numBytes;
+        this.currentPosition += numBytes;
+        return {
+            value: result,
+            done: this.streamClosed,
+        };
+    }
+
+    private async ensureBufferSize(minBytes: number): Promise<void> {
+        const availableBytes = this.buffer.length - this.bufferPosition;
+        const neededBytes = minBytes - availableBytes;
+
+        if (neededBytes <= 0 || this.streamClosed) {
+            return;
+        }
+
+        const chunks: Uint8Array[] = [];
+        let totalBytesRead = 0;
+
+        while (totalBytesRead < neededBytes && !this.streamClosed) {
+            if (!this.reader) {
+                throw new Error('Stream reader is not available');
+            }
+
+            const { done, value } = await this.reader.read();
+
+            if (done) {
+                this.streamClosed = true;
+                break;
+            }
+
+            if (value) {
+                chunks.push(value);
+                totalBytesRead += value.length;
+            }
+        }
+
+        if (chunks.length > 0) {
+            // Create new buffer with existing unused data plus new chunks
+            const unusedBufferData = this.buffer.slice(this.bufferPosition);
+            const newTotalLength = unusedBufferData.length + totalBytesRead;
+            const newBuffer = new Uint8Array(newTotalLength);
+
+            newBuffer.set(unusedBufferData, 0);
+            let offset = unusedBufferData.length;
+            for (const chunk of chunks) {
+                newBuffer.set(chunk, offset);
+                offset += chunk.length;
+            }
+
+            this.buffer = newBuffer;
+            this.bufferPosition = 0;
+        }
+    }
+
+    /**
+     * Seek to the given position in the stream.
+     *
+     * If the position is outside of internally buffered data, the buffer is
+     * cleared. If the position is seeked back, the buffer is read again from
+     * the underlying source.
+     *
+     * @param position - The position to seek to in bytes.
+     */
+    async seek(position: number): Promise<void> {
+        const endOfBufferPosition = this.currentPosition + (this.buffer.length - this.bufferPosition);
+
+        if (position > endOfBufferPosition) {
+            this.buffer = new Uint8Array(0);
+            this.bufferPosition = 0;
+        } else if (position < this.currentPosition) {
+            this.buffer = new Uint8Array(0);
+            this.bufferPosition = 0;
+        } else {
+            this.bufferPosition += position - this.currentPosition;
+        }
+
+        await super.seek(position);
+
+        if (this.reader) {
+            this.reader.releaseLock();
+        }
+        this.reader = super.getReader();
+        this.streamClosed = false;
+        this.currentPosition = position;
+    }
+}

package/src/internal/download/telemetry.test.ts

@@ -14,7 +14,7 @@ describe('DownloadTelemetry', () => {
 
     beforeEach(() => {
         mockTelemetry = {
-            logEvent: jest.fn(),
+            recordMetric: jest.fn(),
             getLogger: jest.fn().mockReturnValue({
                 info: jest.fn(),
                 warn: jest.fn(),
@@ -34,7 +34,7 @@ describe('DownloadTelemetry', () => {
         const error = new Error('Failed');
         await downloadTelemetry.downloadInitFailed(nodeUid, error);
 
-        expect(mockTelemetry.logEvent).toHaveBeenCalledWith({
+        expect(mockTelemetry.recordMetric).toHaveBeenCalledWith({
             eventName: 'download',
             volumeType: 'own_volume',
             downloadedSize: 0,
@@ -47,7 +47,7 @@ describe('DownloadTelemetry', () => {
         const error = new Error('Failed');
         await downloadTelemetry.downloadFailed(revisionUid, error, 123, 456);
 
-        expect(mockTelemetry.logEvent).toHaveBeenCalledWith({
+        expect(mockTelemetry.recordMetric).toHaveBeenCalledWith({
             eventName: 'download',
             volumeType: 'own_volume',
             downloadedSize: 123,
@@ -60,7 +60,7 @@ describe('DownloadTelemetry', () => {
     it('should log successful download (excludes error)', async () => {
         await downloadTelemetry.downloadFinished(revisionUid, 500);
 
-        expect(mockTelemetry.logEvent).toHaveBeenCalledWith({
+        expect(mockTelemetry.recordMetric).toHaveBeenCalledWith({
             eventName: 'download',
             volumeType: 'own_volume',
             downloadedSize: 500,
@@ -70,7 +70,7 @@ describe('DownloadTelemetry', () => {
 
     describe('detect error category', () => {
         const verifyErrorCategory = (error: string) => {
-            expect(mockTelemetry.logEvent).toHaveBeenCalledWith(
+            expect(mockTelemetry.recordMetric).toHaveBeenCalledWith(
                 expect.objectContaining({
                     error,
                 }),
@@ -80,7 +80,7 @@ describe('DownloadTelemetry', () => {
         it('should ignore ValidationError', async () => {
             const error = new ValidationError('Validation error');
             await downloadTelemetry.downloadFailed(revisionUid, error, 100, 200);
-            expect(mockTelemetry.logEvent).not.toHaveBeenCalled();
+            expect(mockTelemetry.recordMetric).not.toHaveBeenCalled();
         });
 
         it('should ignore AbortError', async () => {
@@ -88,7 +88,7 @@ describe('DownloadTelemetry', () => {
             error.name = 'AbortError';
             await downloadTelemetry.downloadFailed(revisionUid, error, 100, 200);
 
-            expect(mockTelemetry.logEvent).not.toHaveBeenCalled();
+            expect(mockTelemetry.recordMetric).not.toHaveBeenCalled();
         });
 
         it('should detect "rate_limited" error for RateLimitedError', async () => {

package/src/internal/download/telemetry.ts

@@ -80,7 +80,7 @@ export class DownloadTelemetry {
             this.logger.error('Failed to get metric volume type', error);
         }
 
-        this.telemetry.logEvent({
+        this.telemetry.recordMetric({
             eventName: 'download',
             volumeType,
             ...options,

package/src/internal/errors.test.ts

@@ -2,20 +2,54 @@ import { VERIFICATION_STATUS } from '../crypto';
 import { getVerificationMessage } from './errors';
 
 describe('getVerificationMessage', () => {
-    const testCases: [VERIFICATION_STATUS, string | undefined, boolean, string][] = [
-        [VERIFICATION_STATUS.NOT_SIGNED, 'type', false, 'Missing signature for type'],
-        [VERIFICATION_STATUS.NOT_SIGNED, undefined, false, 'Missing signature'],
-        [VERIFICATION_STATUS.NOT_SIGNED, 'type', true, 'Missing signature for type'],
-        [VERIFICATION_STATUS.NOT_SIGNED, undefined, true, 'Missing signature'],
-        [VERIFICATION_STATUS.SIGNED_AND_INVALID, 'type', false, 'Signature verification for type failed'],
-        [VERIFICATION_STATUS.SIGNED_AND_INVALID, undefined, false, 'Signature verification failed'],
-        [VERIFICATION_STATUS.SIGNED_AND_INVALID, 'type', true, 'Verification keys for type are not available'],
-        [VERIFICATION_STATUS.SIGNED_AND_INVALID, undefined, true, 'Verification keys are not available'],
+    const testCases: [VERIFICATION_STATUS, Error[] | undefined, string | undefined, boolean, string][] = [
+        [VERIFICATION_STATUS.NOT_SIGNED, undefined, 'type', false, 'Missing signature for type'],
+        [VERIFICATION_STATUS.NOT_SIGNED, undefined, undefined, false, 'Missing signature'],
+        [VERIFICATION_STATUS.NOT_SIGNED, undefined, 'type', true, 'Missing signature for type'],
+        [VERIFICATION_STATUS.NOT_SIGNED, undefined, undefined, true, 'Missing signature'],
+        [VERIFICATION_STATUS.SIGNED_AND_INVALID, undefined, 'type', false, 'Signature verification for type failed'],
+        [VERIFICATION_STATUS.SIGNED_AND_INVALID, undefined, undefined, false, 'Signature verification failed'],
+        [
+            VERIFICATION_STATUS.SIGNED_AND_INVALID,
+            undefined,
+            'type',
+            true,
+            'Verification keys for type are not available',
+        ],
+        [VERIFICATION_STATUS.SIGNED_AND_INVALID, undefined, undefined, true, 'Verification keys are not available'],
+        [
+            VERIFICATION_STATUS.SIGNED_AND_INVALID,
+            [new Error('error1'), new Error('error2')],
+            undefined,
+            false,
+            'Signature verification failed: error1, error2',
+        ],
+        [
+            VERIFICATION_STATUS.SIGNED_AND_INVALID,
+            [new Error('error1'), new Error('error2')],
+            'type',
+            false,
+            'Signature verification for type failed: error1, error2',
+        ],
+        [
+            VERIFICATION_STATUS.SIGNED_AND_INVALID,
+            [new Error('error1'), new Error('error2')],
+            undefined,
+            true,
+            'Verification keys are not available',
+        ],
+        [
+            VERIFICATION_STATUS.SIGNED_AND_INVALID,
+            [new Error('error1'), new Error('error2')],
+            'type',
+            true,
+            'Verification keys for type are not available',
+        ],
     ];
 
-    for (const [status, type, notAvailable, expected] of testCases) {
+    for (const [status, errors, type, notAvailable, expected] of testCases) {
         it(`returns correct message for status ${status} with type ${type} and notAvailable ${notAvailable}`, () => {
-            expect(getVerificationMessage(status, type, notAvailable)).toBe(expected);
+            expect(getVerificationMessage(status, errors, type, notAvailable)).toBe(expected);
         });
     }
 });

package/src/internal/errors.ts

@@ -11,6 +11,7 @@ export function getErrorMessage(error: unknown): string {
  */
 export function getVerificationMessage(
     verified: VERIFICATION_STATUS,
+    verificationErrors?: Error[],
     signatureType?: string,
     notAvailableVerificationKeys = false,
 ): string {
@@ -24,6 +25,13 @@ export function getVerificationMessage(
             : c('Error').t`Verification keys are not available`;
     }
 
+    if (verificationErrors) {
+        const errorMessage = verificationErrors?.map((e) => e.message).join(', ');
+        return signatureType
+            ? c('Error').t`Signature verification for ${signatureType} failed: ${errorMessage}`
+            : c('Error').t`Signature verification failed: ${errorMessage}`;
+    }
+
     return signatureType
         ? c('Error').t`Signature verification for ${signatureType} failed`
         : c('Error').t`Signature verification failed`;

package/src/internal/events/eventManager.test.ts

@@ -9,20 +9,16 @@ const POLLING_INTERVAL = 1;
 describe('EventManager', () => {
     let manager: EventManager<DriveEvent>;
 
-    const getLatestEventIdMock = jest.fn();
-    const getEventsMock = jest.fn();
     const listenerMock = jest.fn();
-    const mockLogger = getMockLogger();
     const subscriptions: EventSubscription[] = [];
+    const mockEventManager = {
+        getLogger: () => getMockLogger(),
+        getLatestEventId: jest.fn(),
+        getEvents: jest.fn(),
+    };
 
     beforeEach(() => {
-        const mockEventManager = {
-            getLogger: () => mockLogger,
-            getLatestEventId: getLatestEventIdMock,
-            getEvents: getEventsMock,
-        };
-
-        manager = new EventManager(mockEventManager as any, POLLING_INTERVAL, null);
+        manager = new EventManager(mockEventManager, POLLING_INTERVAL, null);
         const subscription = manager.addListener(listenerMock);
         subscriptions.push(subscription);
     });
@@ -37,7 +33,7 @@ describe('EventManager', () => {
     });
 
     it('should start polling when started', async () => {
-        getLatestEventIdMock.mockResolvedValue('EventId1');
+        mockEventManager.getLatestEventId.mockResolvedValue('EventId1');
 
         const mockEvents: DriveEvent[][] = [
             [
@@ -56,7 +52,7 @@ describe('EventManager', () => {
             ],
         ];
 
-        getEventsMock
+        mockEventManager.getEvents
             .mockImplementationOnce(async function* () {
                 yield* mockEvents[0];
             })
@@ -65,22 +61,23 @@ describe('EventManager', () => {
             })
             .mockImplementationOnce(async function* () {});
 
-        expect(getLatestEventIdMock).toHaveBeenCalledTimes(0);
-        expect(getEventsMock).toHaveBeenCalledTimes(0);
+        expect(mockEventManager.getLatestEventId).toHaveBeenCalledTimes(0);
+        expect(mockEventManager.getEvents).toHaveBeenCalledTimes(0);
 
         expect(await manager.start()).toBeUndefined();
+        await jest.runOnlyPendingTimersAsync();
 
-        expect(getLatestEventIdMock).toHaveBeenCalledTimes(1);
-        expect(getEventsMock).toHaveBeenCalledWith('EventId1');
+        expect(mockEventManager.getLatestEventId).toHaveBeenCalledTimes(1);
+        expect(mockEventManager.getEvents).toHaveBeenCalledWith('EventId1');
 
         await jest.runOnlyPendingTimersAsync();
-        expect(getEventsMock).toHaveBeenCalledTimes(2);
-        expect(getEventsMock).toHaveBeenCalledWith('EventId2');
+        expect(mockEventManager.getEvents).toHaveBeenCalledTimes(2);
+        expect(mockEventManager.getEvents).toHaveBeenCalledWith('EventId2');
     });
 
     it('should stop polling when stopped', async () => {
-        getLatestEventIdMock.mockResolvedValue('eventId1');
-        getEventsMock.mockImplementation(async function* () {
+        mockEventManager.getLatestEventId.mockResolvedValue('eventId1');
+        mockEventManager.getEvents.mockImplementation(async function* () {
             yield {
                 type: DriveEventType.FastForward,
                 treeEventScopeId: 'volume1',
@@ -91,16 +88,16 @@ describe('EventManager', () => {
         await manager.start();
         await jest.runOnlyPendingTimersAsync();
 
-        const callsBeforeStop = getEventsMock.mock.calls.length;
+        const callsBeforeStop = mockEventManager.getEvents.mock.calls.length;
         await manager.stop();
         await jest.runOnlyPendingTimersAsync();
 
         // Should not have made additional calls after stopping
-        expect(getEventsMock).toHaveBeenCalledTimes(callsBeforeStop);
+        expect(mockEventManager.getEvents).toHaveBeenCalledTimes(callsBeforeStop);
     });
 
     it('should notify all listeners when getting events', async () => {
-        getLatestEventIdMock.mockResolvedValue('eventId1');
+        mockEventManager.getLatestEventId.mockResolvedValue('eventId1');
 
         const mockEvents: DriveEvent[] = [
             {
@@ -114,7 +111,7 @@ describe('EventManager', () => {
             },
         ];
 
-        getEventsMock
+        mockEventManager.getEvents
             .mockImplementationOnce(async function* () {
                 yield* mockEvents;
             })
@@ -127,19 +124,19 @@ describe('EventManager', () => {
     });
 
     it('should propagate unsubscription errors', async () => {
-        getLatestEventIdMock.mockImplementation(() => {
+        mockEventManager.getLatestEventId.mockImplementation(() => {
             throw new UnsubscribeFromEventsSourceError('Not found');
         });
 
         await expect(manager.start()).rejects.toThrow(UnsubscribeFromEventsSourceError);
 
-        expect(getLatestEventIdMock).toHaveBeenCalledTimes(1);
+        expect(mockEventManager.getLatestEventId).toHaveBeenCalledTimes(1);
         expect(listenerMock).toHaveBeenCalledTimes(0);
-        expect(getEventsMock).toHaveBeenCalledTimes(0);
+        expect(mockEventManager.getEvents).toHaveBeenCalledTimes(0);
     });
 
     it('should continue processing multiple events', async () => {
-        getLatestEventIdMock.mockResolvedValue('eventId1');
+        mockEventManager.getLatestEventId.mockResolvedValue('eventId1');
 
         const mockEvents: DriveEvent[] = [
             {
@@ -162,7 +159,7 @@ describe('EventManager', () => {
             },
         ];
 
-        getEventsMock
+        mockEventManager.getEvents
             .mockImplementationOnce(async function* () {
                 yield* mockEvents;
             })
@@ -177,7 +174,7 @@ describe('EventManager', () => {
         expect(listenerMock).toHaveBeenNthCalledWith(1, mockEvents[0]);
         expect(listenerMock).toHaveBeenNthCalledWith(2, mockEvents[1]);
 
-        getEventsMock.mockImplementationOnce(async function* () {
+        mockEventManager.getEvents.mockImplementationOnce(async function* () {
             yield* mockEvents;
         });
         await jest.runOnlyPendingTimersAsync();
@@ -187,10 +184,10 @@ describe('EventManager', () => {
     });
 
     it('should retry on error with exponential backoff', async () => {
-        getLatestEventIdMock.mockResolvedValue('eventId1');
+        mockEventManager.getLatestEventId.mockResolvedValue('eventId1');
 
         let callCount = 0;
-        getEventsMock.mockImplementation(async function* () {
+        mockEventManager.getEvents.mockImplementation(async function* () {
             callCount++;
             if (callCount <= 3) {
                 throw new Error('Network error');
@@ -205,11 +202,12 @@ describe('EventManager', () => {
         expect(manager['retryIndex']).toEqual(0);
 
         expect(await manager.start()).toBeUndefined();
-        expect(getEventsMock).toHaveBeenCalledTimes(1);
+        await jest.runOnlyPendingTimersAsync();
+        expect(mockEventManager.getEvents).toHaveBeenCalledTimes(1);
         expect(manager['retryIndex']).toEqual(1);
 
         await jest.runOnlyPendingTimersAsync();
-        expect(getEventsMock).toHaveBeenCalledTimes(2);
+        expect(mockEventManager.getEvents).toHaveBeenCalledTimes(2);
         expect(manager['retryIndex']).toEqual(2);
 
         await jest.runOnlyPendingTimersAsync();
@@ -224,8 +222,8 @@ describe('EventManager', () => {
     });
 
     it('should stop polling when stopped immediately', async () => {
-        getLatestEventIdMock.mockResolvedValue('eventId1');
-        getEventsMock.mockImplementation(async function* () {
+        mockEventManager.getLatestEventId.mockResolvedValue('eventId1');
+        mockEventManager.getEvents.mockImplementation(async function* () {
             yield {
                 type: DriveEventType.FastForward,
                 treeEventScopeId: 'volume1',
@@ -234,18 +232,19 @@ describe('EventManager', () => {
         });
 
         expect(await manager.start()).toBeUndefined();
-        expect(getEventsMock).toHaveBeenCalledTimes(1);
+        await jest.runOnlyPendingTimersAsync();
+        expect(mockEventManager.getEvents).toHaveBeenCalledTimes(1);
         await manager.stop();
         await jest.runOnlyPendingTimersAsync();
 
         // getEvents should have been called once during start, but not again after stop
-        expect(getEventsMock).toHaveBeenCalledTimes(1);
+        expect(mockEventManager.getEvents).toHaveBeenCalledTimes(1);
     });
 
     it('should handle empty event streams', async () => {
-        getLatestEventIdMock.mockResolvedValue('eventId1');
+        mockEventManager.getLatestEventId.mockResolvedValue('eventId1');
 
-        getEventsMock.mockImplementation(async function* () {
+        mockEventManager.getEvents.mockImplementation(async function* () {
             // Empty generator - no events
         });
 
@@ -254,4 +253,26 @@ describe('EventManager', () => {
 
         expect(listenerMock).toHaveBeenCalledTimes(0);
     });
+
+    it('should poll right away after start if latestEventId is passed', async () => {
+        manager = new EventManager(mockEventManager, POLLING_INTERVAL, 'eventId1');
+
+        await manager.start();
+
+        // Right after the start it is called.
+        expect(mockEventManager.getEvents).toHaveBeenCalledTimes(1);
+    });
+
+    it('should not poll right away after start if latestEventId is not passed', async () => {
+        manager = new EventManager(mockEventManager, POLLING_INTERVAL, null);
+
+        await manager.start();
+
+        // Right after the start it is not called.
+        expect(mockEventManager.getEvents).not.toHaveBeenCalled();
+
+        // But it is scheduled to be called after the polling interval.
+        await jest.runOnlyPendingTimersAsync();
+        expect(mockEventManager.getEvents).toHaveBeenCalledTimes(1);
+    });
 });

package/src/internal/events/eventManager.ts

@@ -38,8 +38,11 @@ export class EventManager<T extends Event> {
     }
 
     async start(): Promise<void> {
+        this.logger.info(`Starting event manager with latestEventId: ${this.latestEventId}`);
         if (this.latestEventId === undefined) {
             this.latestEventId = await this.specializedEventManager.getLatestEventId();
+            this.scheduleNextPoll();
+            return;
         }
         this.processPromise = this.processEvents();
     }
@@ -107,6 +110,13 @@ export class EventManager<T extends Event> {
             throw listenerError;
         }
 
+        this.scheduleNextPoll();
+    }
+
+    private scheduleNextPoll() {
+        if (this.timeoutHandle) {
+            clearTimeout(this.timeoutHandle);
+        }
         this.timeoutHandle = setTimeout(() => {
             this.processPromise = this.processEvents();
         }, this.nextPollTimeout);