@droponair/sdk-js 0.34.2 → 0.36.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.36.0
+
+### Added
+
+- **Downloads carry on where they stopped.** A download that breaks keeps what it
+  already had and asks the storage for the rest by range, retrying six times with a
+  growing wait. Nothing to change in an app: it happens inside `downloadAttachment`.
+
+## 0.35.0
+
+### Added
+
+- **Download progress.** `downloadAttachment(ref, { onProgress })` reports bytes as
+  they arrive.
+- **Real upload progress in browsers.** `onUploadProgress` now reports as the bytes
+  go up where `XMLHttpRequest` exists; elsewhere it still reports once at the end.
+- **`AttachmentUnavailableError`.** `downloadAttachment` throws it, with the HTTP
+  status, when the file is no longer there to fetch: deleted once everybody had it,
+  past its deadline, or revoked. A failure worth trying again stays a plain `Error`.
+
 ## 0.34.2
 
 ### Fixed

package/dist/attachment/attachment-client.d.ts

@@ -4,7 +4,7 @@ interface DeviceKeyInfo {
     deviceId: string;
     publicKey: string;
 }
-import { AttachmentRef, CreateUploadSessionOptions, DownloadedAttachment, PrepareAttachmentOptions, UploadSession } from './attachment-types';
+import { AttachmentRef, CreateUploadSessionOptions, DownloadAttachmentOptions, DownloadedAttachment, PrepareAttachmentOptions, UploadSession } from './attachment-types';
 interface AttachmentClientDeps {
     httpUrl: string;
     fetchFn: typeof fetch;
@@ -62,7 +62,7 @@ export declare class AttachmentClient {
      * Downloads + decrypts an attachment. For E2EE, finds the wrappedKey for the
      * current device, unwraps it, then decrypts the stored bytes.
      */
-    downloadAttachment(ref: AttachmentRef): Promise<DownloadedAttachment>;
+    downloadAttachment(ref: AttachmentRef, opts?: DownloadAttachmentOptions): Promise<DownloadedAttachment>;
     /** Best effort: a missed confirmation only means the copy waits for its own expiry. */
     private confirmReceived;
     /** Convert public AttachmentRef into the wire-format type for proto encoding. */

package/dist/attachment/attachment-client.js

@@ -6,10 +6,43 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AttachmentClient = void 0;
 const tweetnacl_1 = __importDefault(require("tweetnacl"));
 const bytes_1 = require("../core/bytes");
+const attachment_types_1 = require("./attachment-types");
 const STORAGE_PRIVATE = 'droponair.identity.privateKey.v1';
 function asBufferSource(data) {
     return new Uint8Array(data);
 }
+/** Reads a response body, saying how far it has got when asked to. */
+async function readWithProgress(resp, expectedBytes, onProgress) {
+    const reader = onProgress && resp.body ? resp.body.getReader() : null;
+    if (!reader || !onProgress) {
+        const bytes = new Uint8Array(await resp.arrayBuffer());
+        onProgress?.(bytes.length, bytes.length);
+        return bytes;
+    }
+    const header = Number(resp.headers?.get?.('content-length'));
+    const total = Number.isFinite(header) && header > 0 ? header : expectedBytes;
+    const chunks = [];
+    let received = 0;
+    onProgress(0, total);
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        chunks.push(value);
+        received += value.length;
+        onProgress(received, total);
+    }
+    const out = new Uint8Array(received);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+/** How many times a broken download is tried again, and how long between tries. */
+const DOWNLOAD_ATTEMPTS = 6;
+const DOWNLOAD_BACKOFF_MS = [2000, 4000, 8000, 15000, 30000];
 async function sha256Hex(bytes) {
     const digest = await crypto.subtle.digest('SHA-256', asBufferSource(bytes));
     const hex = [];
@@ -174,7 +207,11 @@ class AttachmentClient {
         });
         if (!resp.ok) {
             const text = await resp.text().catch(() => '');
-            throw new Error(`Failed to get download URL (HTTP ${resp.status}): ${text}`);
+            const message = `Failed to get download URL (HTTP ${resp.status}): ${text}`;
+            if (resp.status === 404 || resp.status === 410) {
+                throw new attachment_types_1.AttachmentUnavailableError(attachmentId, resp.status, message);
+            }
+            throw new Error(message);
         }
         const body = await resp.json();
         return {
@@ -190,15 +227,50 @@ class AttachmentClient {
      * Downloads + decrypts an attachment. For E2EE, finds the wrappedKey for the
      * current device, unwraps it, then decrypts the stored bytes.
      */
-    async downloadAttachment(ref) {
-        const info = await this.getDownloadUrl(ref.attachmentId);
-        const resp = await this.deps.fetchFn(info.url, { method: info.method, headers: info.headers });
-        if (!resp.ok) {
-            const text = await resp.text().catch(() => '');
-            throw new Error(`Failed to download attachment bytes (HTTP ${resp.status}): ${text}`);
+    async downloadAttachment(ref, opts = {}) {
+        // What has already arrived is kept between attempts, and the rest asked for by
+        // range, so a download that breaks does not start the file again. A fresh link
+        // is asked for each attempt, since a link lasts minutes.
+        let had = new Uint8Array(0);
+        let info;
+        for (let attempt = 1;; attempt++) {
+            try {
+                info = await this.getDownloadUrl(ref.attachmentId);
+                const headers = { ...info.headers };
+                if (had.length > 0)
+                    headers.Range = `bytes=${had.length}-`;
+                const resp = await this.deps.fetchFn(info.url, { method: info.method, headers });
+                if (resp.status === 416 && had.length > 0)
+                    break;
+                if (!resp.ok) {
+                    const text = await resp.text().catch(() => '');
+                    const message = `Failed to download attachment bytes (HTTP ${resp.status}): ${text}`;
+                    // The link was good and the bytes are not there: deleted from storage
+                    // underneath a record that still existed.
+                    if (resp.status === 404)
+                        throw new attachment_types_1.AttachmentUnavailableError(ref.attachmentId, 404, message);
+                    throw new Error(message);
+                }
+                const resuming = resp.status === 206 && had.length > 0;
+                const base = resuming ? had : new Uint8Array(0);
+                const rest = await readWithProgress(resp, Math.max(0, info.sizeBytes - base.length), opts.onProgress
+                    ? (received, total) => opts.onProgress(base.length + received, base.length + total)
+                    : undefined);
+                const joined = new Uint8Array(base.length + rest.length);
+                joined.set(base, 0);
+                joined.set(rest, base.length);
+                had = joined;
+                break;
+            }
+            catch (error) {
+                if (error instanceof attachment_types_1.AttachmentUnavailableError)
+                    throw error;
+                if (attempt >= DOWNLOAD_ATTEMPTS)
+                    throw error;
+                await new Promise((resolve) => setTimeout(resolve, DOWNLOAD_BACKOFF_MS[Math.min(attempt - 1, DOWNLOAD_BACKOFF_MS.length - 1)]));
+            }
         }
-        const arrayBuf = await resp.arrayBuffer();
-        let stored = new Uint8Array(arrayBuf);
+        let stored = had;
         if (ref.encryptionType === 'CLEARTEXT') {
             await this.confirmReceived(ref.attachmentId);
             return { attachmentId: ref.attachmentId, mimeType: info.mimeType, sizeBytes: info.sizeBytes, sha256: info.sha256, bytes: stored };
@@ -281,6 +353,24 @@ class AttachmentClient {
     }
     // ─── internals ───
     async uploadBytes(session, bytes, onProgress) {
+        // In a browser an XMLHttpRequest can say how far the body has got; fetch cannot.
+        if (onProgress && typeof XMLHttpRequest !== 'undefined') {
+            await new Promise((resolve, reject) => {
+                const xhr = new XMLHttpRequest();
+                xhr.open(session.uploadMethod || 'PUT', session.uploadUrl);
+                for (const [k, v] of Object.entries(session.uploadHeaders ?? {}))
+                    xhr.setRequestHeader(k, v);
+                xhr.upload.onprogress = (e) => onProgress(e.loaded, e.lengthComputable ? e.total : bytes.length);
+                xhr.onload = () => (xhr.status >= 200 && xhr.status < 300)
+                    ? resolve()
+                    : reject(new Error(`Storage upload failed (HTTP ${xhr.status}): ${String(xhr.responseText).slice(0, 400)}`));
+                xhr.onerror = () => reject(new Error('Storage upload failed: network error'));
+                onProgress(0, bytes.length);
+                xhr.send(asBufferSource(bytes));
+            });
+            onProgress(bytes.length, bytes.length);
+            return;
+        }
         const resp = await this.deps.fetchFn(session.uploadUrl, {
             method: session.uploadMethod || 'PUT',
             headers: session.uploadHeaders,

package/dist/attachment/attachment-types.d.ts

@@ -97,6 +97,21 @@ export interface PrepareAttachmentOptions {
     /** Mime type of the thumbnail bytes (defaults to 'image/jpeg'). */
     thumbnailMimeType?: string;
 }
+/** Options for downloadAttachment. */
+export interface DownloadAttachmentOptions {
+    /** Called as bytes arrive, with the bytes received so far and the total. */
+    onProgress?: (bytesReceived: number, totalBytes: number) => void;
+}
+/**
+ * The file is not there to fetch: deleted once everybody had it, past its
+ * deadline, revoked, or never existed. Nothing will bring it back, unlike a
+ * failure worth trying again. `status` is the HTTP status that said so.
+ */
+export declare class AttachmentUnavailableError extends Error {
+    readonly attachmentId: string;
+    readonly status: number;
+    constructor(attachmentId: string, status: number, message: string);
+}
 /** Bytes payload returned by downloadAttachment. */
 export interface DownloadedAttachment {
     attachmentId: string;

package/dist/attachment/attachment-types.js

@@ -9,3 +9,18 @@
 // used for message payloads.
 // ---------------------------------------------------------------------------
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.AttachmentUnavailableError = void 0;
+/**
+ * The file is not there to fetch: deleted once everybody had it, past its
+ * deadline, revoked, or never existed. Nothing will bring it back, unlike a
+ * failure worth trying again. `status` is the HTTP status that said so.
+ */
+class AttachmentUnavailableError extends Error {
+    constructor(attachmentId, status, message) {
+        super(message);
+        this.attachmentId = attachmentId;
+        this.status = status;
+        this.name = 'AttachmentUnavailableError';
+    }
+}
+exports.AttachmentUnavailableError = AttachmentUnavailableError;

package/dist/core/messaging-client.d.ts

@@ -113,7 +113,7 @@ export declare class MessagingClient implements DropOnAirClient {
     prepareAttachmentAndUpload(bytes: Uint8Array, options: PrepareAttachmentOptions): Promise<AttachmentRef>;
     createUploadSession(options: CreateUploadSessionOptions): Promise<UploadSession>;
     finalizeAttachment(attachmentId: string, sha256: string): Promise<void>;
-    downloadAttachment(ref: AttachmentRef): Promise<DownloadedAttachment>;
+    downloadAttachment(ref: AttachmentRef, options?: import('../attachment/attachment-types').DownloadAttachmentOptions): Promise<DownloadedAttachment>;
     revokeAttachment(attachment: string | AttachmentRef): Promise<void>;
     /**
      * How the identity private key is held. See {@link KeyCustody}.

package/dist/core/messaging-client.js

@@ -338,8 +338,8 @@ class MessagingClient {
     async finalizeAttachment(attachmentId, sha256) {
         return this.attachmentClient.finalize(attachmentId, sha256);
     }
-    async downloadAttachment(ref) {
-        return this.attachmentClient.downloadAttachment(ref);
+    async downloadAttachment(ref, options) {
+        return this.attachmentClient.downloadAttachment(ref, options);
     }
     async revokeAttachment(attachment) {
         if (typeof attachment === 'string') {

package/dist/core/types.d.ts

@@ -600,7 +600,7 @@ export interface DropOnAirClient {
     /** Low-level: finalize an upload, committing the integrity hash. */
     finalizeAttachment(attachmentId: string, sha256: string): Promise<void>;
     /** Download (and for E2EE decrypt) an attachment referenced inside a received message. */
-    downloadAttachment(ref: import('../attachment/attachment-types').AttachmentRef): Promise<import('../attachment/attachment-types').DownloadedAttachment>;
+    downloadAttachment(ref: import('../attachment/attachment-types').AttachmentRef, options?: import('../attachment/attachment-types').DownloadAttachmentOptions): Promise<import('../attachment/attachment-types').DownloadedAttachment>;
     /**
      * Revoke an attachment you sent. The platform stops issuing download URLs
      * for it and notifies recipients; bytes already downloaded cannot be

package/dist/index.d.ts

@@ -23,7 +23,8 @@ export { SDK_VERSION, PROTOCOL_VERSION, PAYLOAD_FORMAT_VERSION } from './version
 export declare function createSecureIdentity(store?: IdentityRecordStore): Promise<WebCryptoIdentityProvider | null>;
 export declare function initialize(options: InitializeOptions): Promise<DropOnAirClient>;
 export type { InitializeOptions, DropOnAirClient, DropOnAirEvent, MessageCallback, EventCallback, DecryptedMessage, KeyStorageAdapter, CallEvent, CallEventType, CallEventCallback, TurnCredentials, BroadcastMessage, BroadcastCallback, GroupInfo, GroupMemberInfo, DecryptedGroupMessage, GroupMessageCallback, GroupCallEvent, GroupCallEventType, GroupCallEventCallback, Room, RoomPolicy, CreateRoomOptions, UpdateRoomOptions, SfuToken, SfuRecording, MessageEditEvent, MessageEditCallback, MessageDeleteEvent, MessageDeleteCallback, GroupMessageEditEvent, GroupMessageEditCallback, GroupMessageDeleteEvent, GroupMessageDeleteCallback, DeviceInfo, ReadReceiptEvent, ReadReceiptCallback, TypingEvent, TypingCallback, NotificationClearEvent, NotificationClearCallback, DraftSyncEvent, DraftSyncCallback, } from './core/types';
-export type { AttachmentEncryptionType, AttachmentConversationType, AttachmentRef, DeviceWrappedKey, CreateUploadSessionOptions, UploadSession, PrepareAttachmentOptions, DownloadedAttachment, } from './attachment/attachment-types';
+export type { AttachmentEncryptionType, AttachmentConversationType, AttachmentRef, DeviceWrappedKey, CreateUploadSessionOptions, UploadSession, PrepareAttachmentOptions, DownloadedAttachment, DownloadAttachmentOptions, } from './attachment/attachment-types';
+export { AttachmentUnavailableError } from './attachment/attachment-types';
 export { SseTransport, type SseTransportOptions, type SseFrameHandler, type SseStateHandler, } from './transport/sse-transport';
 export { WebTransportTransport, type WebTransportTransportOptions, type WTFrameHandler, type WTStateHandler, } from './transport/webtransport-transport';
 export { selectTransport, type TransportLane, type SelectTransportOptions, } from './transport/auto-select';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MemoryIdentityRecordStore = exports.IndexedDbIdentityRecordStore = exports.WebCryptoIdentityProvider = exports.selectTransport = exports.WebTransportTransport = exports.SseTransport = exports.PAYLOAD_FORMAT_VERSION = exports.PROTOCOL_VERSION = exports.SDK_VERSION = void 0;
+exports.MemoryIdentityRecordStore = exports.IndexedDbIdentityRecordStore = exports.WebCryptoIdentityProvider = exports.selectTransport = exports.WebTransportTransport = exports.SseTransport = exports.AttachmentUnavailableError = exports.PAYLOAD_FORMAT_VERSION = exports.PROTOCOL_VERSION = exports.SDK_VERSION = void 0;
 exports.createSecureIdentity = createSecureIdentity;
 exports.initialize = initialize;
 const messaging_client_1 = require("./core/messaging-client");
@@ -61,6 +61,8 @@ async function initialize(options) {
     }
     return client;
 }
+var attachment_types_1 = require("./attachment/attachment-types");
+Object.defineProperty(exports, "AttachmentUnavailableError", { enumerable: true, get: function () { return attachment_types_1.AttachmentUnavailableError; } });
 // HTTP fallback lane primitive for restrictive networks.
 var sse_transport_1 = require("./transport/sse-transport");
 Object.defineProperty(exports, "SseTransport", { enumerable: true, get: function () { return sse_transport_1.SseTransport; } });

package/dist/version.d.ts

@@ -7,7 +7,7 @@
  *   MINOR, additive feature (e.g. multi-device payloads, new call event type)
  *   PATCH, bug-fix / perf improvement with no wire or API change
  */
-export declare const SDK_VERSION = "0.34.2";
+export declare const SDK_VERSION = "0.36.0";
 /**
  * Binary encrypted-payload format version.
  * Included as the first byte of every encrypted payload so receivers can

package/dist/version.js

@@ -10,7 +10,7 @@ exports.PROTOCOL_VERSION = exports.PAYLOAD_FORMAT_VERSION = exports.SDK_VERSION
  *   MINOR, additive feature (e.g. multi-device payloads, new call event type)
  *   PATCH, bug-fix / perf improvement with no wire or API change
  */
-exports.SDK_VERSION = '0.34.2';
+exports.SDK_VERSION = '0.36.0';
 /**
  * Binary encrypted-payload format version.
  * Included as the first byte of every encrypted payload so receivers can

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@droponair/sdk-js",
-  "version": "0.34.2",
+  "version": "0.36.0",
   "description": "End-to-end encrypted messaging, voice and video calling SDK. The relay never sees your keys or message content.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",