@sparkvault/sdk-mobile 5.2.2 → 5.3.0

package/dist/tus.js

@@ -1,5 +1,5 @@
 import { base64EncodeUtf8 } from './encoding.js';
-import { gateErrorFromBody, SparkVaultMobileError, SparkVaultValidationError, TusUploadError, } from './errors.js';
+import { BackgroundTransferError, gateErrorFromBody, SparkVaultMobileError, SparkVaultValidationError, TusUploadError, } from './errors.js';
 const TUS_VERSION = '1.0.0';
 export function parseForgeUrl(forgeUrl) {
     let url;
@@ -66,12 +66,44 @@ function ensureNotAborted(signal) {
         throw new TusUploadError('Upload cancelled', { phase: 'cancelled' });
     }
 }
-/** Strict positive-integer parse of Forge's advertised chunk size; anything else is `null`. */
-function parseChunkSizeHeader(raw) {
+/**
+ * Strict integer parse of a tus byte-count header (`Upload-Offset`,
+ * `Upload-Length`, `X-Chunk-Size`); anything malformed, unsafe, or below
+ * `minimum` is `null` so a corrupt header can never become an offset.
+ */
+function parseIntegerHeader(raw, minimum) {
     if (raw === null || !/^\d+$/.test(raw.trim()))
         return null;
     const value = Number(raw);
-    return Number.isSafeInteger(value) && value > 0 ? value : null;
+    return Number.isSafeInteger(value) && value >= minimum ? value : null;
+}
+/**
+ * Case-insensitive header lookup for adapter results. Native HTTP stacks
+ * hand headers back in whatever case they please (iOS lower-cases them),
+ * while Forge writes `Upload-Offset`.
+ */
+function getHeaderIgnoreCase(headers, name) {
+    if (!headers)
+        return null;
+    const wanted = name.toLowerCase();
+    for (const key of Object.keys(headers)) {
+        if (key.toLowerCase() === wanted)
+            return headers[key];
+    }
+    return null;
+}
+function resolveSessionSource(options) {
+    if (options.resume) {
+        const istk = options.resume.istk ?? (options.forgeUrl ? parseForgeUrl(options.forgeUrl).istk : null);
+        if (!istk) {
+            throw new SparkVaultValidationError('resume.istk or forgeUrl is required to resume a TUS upload session');
+        }
+        return { mode: 'resume', uploadUrl: options.resume.uploadUrl, istk };
+    }
+    if (!options.forgeUrl) {
+        throw new SparkVaultValidationError('forgeUrl is required to create a TUS upload session');
+    }
+    return { mode: 'create', parsed: parseForgeUrl(options.forgeUrl) };
 }
 async function createTusUpload(config, parsed, fileSize, filename, contentType, signal) {
     ensureNotAborted(signal);
@@ -127,7 +159,7 @@ async function createTusUpload(config, parsed, fileSize, filename, contentType,
     // to dictate via `X-Chunk-Size` (mirrors sdk-js). A client-side guess could
     // only ever be rejected, so a missing header is a contract violation.
     const chunkSizeHeader = response.headers.get('X-Chunk-Size');
-    const chunkSize = parseChunkSizeHeader(chunkSizeHeader);
+    const chunkSize = parseIntegerHeader(chunkSizeHeader, 1);
     if (chunkSize === null) {
         throw new TusUploadError(`TUS create response missing or invalid X-Chunk-Size header (received ${JSON.stringify(chunkSizeHeader)})`, {
             filename,
@@ -137,15 +169,159 @@ async function createTusUpload(config, parsed, fileSize, filename, contentType,
     }
     return { uploadUrl, chunkSize };
 }
-function uploadChunk(uploadUrl, istk, chunk, offset, timeoutMs, signal, onChunkProgress) {
+/**
+ * Ask Forge where a session stands (tus HEAD). This is the only way to learn
+ * what a background URLSession delivered after the process was killed, and
+ * what a failed attempt left behind — so resume never re-sends bytes the
+ * server holds. A 404/410 means the session expired or was terminated: the
+ * error carries `sessionLost` so the caller drops its persisted session and
+ * creates a fresh one rather than retrying a dead URL. Any other failure
+ * (a 5xx, an auth rejection, a timeout) leaves `sessionLost` false: the
+ * session may well be intact, and treating it as dead would re-upload a
+ * whole file over a blip.
+ */
+async function headTusSession(config, uploadUrl, istk, signal, context = {}) {
+    ensureNotAborted(signal);
+    const response = await config.fetch(uploadUrl, {
+        method: 'HEAD',
+        headers: {
+            'Tus-Resumable': TUS_VERSION,
+            'X-ISTK': istk,
+        },
+        signal,
+        timeoutMs: config.tusPostTimeoutMs,
+    }).catch(err => {
+        if (getErrorName(err) === 'AbortError') {
+            // The same AbortError ends a user cancel and the request timeout; the
+            // caller's signal tells them apart.
+            throw new TusUploadError(signal?.aborted ? 'Upload cancelled' : 'TUS HEAD request timed out', {
+                cause: err instanceof Error ? err : null,
+                ...context,
+                phase: signal?.aborted ? 'cancelled' : 'timeout',
+            });
+        }
+        throw err;
+    });
+    if (response.status === 404 || response.status === 410) {
+        throw new TusUploadError(`TUS session no longer exists on the server (${response.status})`, {
+            httpStatus: response.status,
+            ...context,
+            phase: 'create',
+            sessionLost: true,
+        });
+    }
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => '');
+        const gateError = gateErrorFromBody(response.status, parseErrorBody(errorText));
+        if (gateError) {
+            throw gateError;
+        }
+        throw new TusUploadError(`TUS HEAD failed: ${response.status} - ${errorText}`, {
+            httpStatus: response.status,
+            ...context,
+            phase: 'create',
+        });
+    }
+    const offset = parseIntegerHeader(response.headers.get('Upload-Offset'), 0);
+    const length = parseIntegerHeader(response.headers.get('Upload-Length'), 0);
+    const chunkSize = parseIntegerHeader(response.headers.get('X-Chunk-Size'), 1);
+    if (offset === null || length === null || chunkSize === null || offset > length) {
+        throw new TusUploadError('TUS HEAD response missing or invalid Upload-Offset / Upload-Length / X-Chunk-Size headers', { ...context, phase: 'create' });
+    }
+    return { offset, length, chunkSize };
+}
+/**
+ * Confirm finalization of a session Forge already holds every byte of: a
+ * zero-length PATCH at `Upload-Offset: fileSize`. Forge treats any PATCH at
+ * or past the declared size as "finalize (again) and acknowledge" - it
+ * re-runs a finalization that failed transiently after the last chunk
+ * (Core/DynamoDB/billing), and answers 204 for one that already completed.
+ * Without this a resume that finds the transfer complete would skip straight
+ * to the status poll and could report a never-activated ingot as done.
+ *
+ * 409 means another finalizer holds the lease right now: retry later, the
+ * session is intact. 404/410 mean the session is gone (`sessionLost`).
+ */
+async function confirmTusFinalization(config, uploadUrl, istk, fileSize, signal, context = {}) {
+    ensureNotAborted(signal);
+    const response = await config.fetch(uploadUrl, {
+        method: 'PATCH',
+        headers: {
+            'Tus-Resumable': TUS_VERSION,
+            'Upload-Offset': String(fileSize),
+            'Content-Type': 'application/offset+octet-stream',
+            'X-ISTK': istk,
+        },
+        signal,
+        timeoutMs: config.tusChunkTimeoutMs,
+    }).catch(err => {
+        if (getErrorName(err) === 'AbortError') {
+            throw new TusUploadError(signal?.aborted ? 'Upload cancelled' : 'TUS finalization request timed out', {
+                cause: err instanceof Error ? err : null,
+                ...context,
+                phase: signal?.aborted ? 'cancelled' : 'timeout',
+            });
+        }
+        throw err;
+    });
+    if (response.status === 404 || response.status === 410) {
+        throw new TusUploadError(`TUS session no longer exists on the server (${response.status})`, {
+            httpStatus: response.status,
+            ...context,
+            phase: 'create',
+            sessionLost: true,
+        });
+    }
+    if (response.status === 409) {
+        throw new TusUploadError('TUS finalization is already in progress on the server; retry shortly', {
+            httpStatus: 409,
+            ...context,
+            phase: 'upload',
+        });
+    }
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => '');
+        const gateError = gateErrorFromBody(response.status, parseErrorBody(errorText));
+        if (gateError) {
+            throw gateError;
+        }
+        throw new TusUploadError(`TUS finalization failed: ${response.status} - ${errorText.substring(0, 200)}`, {
+            httpStatus: response.status,
+            ...context,
+            phase: 'upload',
+        });
+    }
+}
+/**
+ * Hard ceiling on a single chunk PATCH regardless of progress. The stall
+ * watchdog is the real limit; this only ends a transfer whose progress events
+ * keep trickling in without ever finishing.
+ */
+const CHUNK_ABSOLUTE_CAP_MS = 60 * 60000;
+/**
+ * PATCH one chunk. `stallTimeoutMs` is a STALL watchdog, not a deadline: it
+ * fires only when no upload progress (and no response) arrives for that long.
+ * Forge fixes non-final chunks at 50 MB and the client cannot shrink them, so
+ * an absolute per-request timeout would kill every legitimately slow uplink
+ * (a 50 MB chunk needs ~3.5 Mbps sustained to beat 120 s) and restart the
+ * file from byte 0. The final PATCH also waits for Forge to finalize after the
+ * last byte is sent; a progress-based watchdog gives that the same patience.
+ */
+function uploadChunk(uploadUrl, istk, chunk, offset, stallTimeoutMs, signal, onChunkProgress) {
     if (typeof XMLHttpRequest === 'undefined') {
         throw new SparkVaultValidationError('XMLHttpRequest is required for mobile TUS uploads');
     }
     return new Promise((resolve, reject) => {
         const xhr = new XMLHttpRequest();
         let settled = false;
+        let watchdog = null;
+        let cap = null;
         const cleanup = () => {
             signal?.removeEventListener('abort', abort);
+            if (watchdog)
+                clearTimeout(watchdog);
+            if (cap)
+                clearTimeout(cap);
         };
         const finish = (fn) => {
             if (settled)
@@ -163,15 +339,33 @@ function uploadChunk(uploadUrl, istk, chunk, offset, timeoutMs, signal, onChunkP
             return;
         }
         signal?.addEventListener('abort', abort, { once: true });
+        // Settle BEFORE aborting: the abort handler below would otherwise report
+        // the stall as a user cancellation.
+        const stall = (message) => {
+            finish(() => reject(new TusUploadError(message, { phase: 'timeout' })));
+            xhr.abort();
+        };
+        const armWatchdog = () => {
+            if (watchdog)
+                clearTimeout(watchdog);
+            watchdog = setTimeout(() => stall(`Chunk upload stalled: no progress for ${stallTimeoutMs / 1000}s`), stallTimeoutMs);
+        };
         xhr.upload.onprogress = event => {
+            armWatchdog();
             if (event.lengthComputable) {
                 onChunkProgress?.(event.loaded);
             }
         };
         xhr.onload = () => {
             if (xhr.status >= 200 && xhr.status < 300) {
-                const offsetHeader = xhr.getResponseHeader('Upload-Offset');
-                const newOffset = offsetHeader ? parseInt(offsetHeader, 10) : offset + chunk.byteLength;
+                // Forge answers every PATCH with Upload-Offset, so a 2xx without a
+                // readable one is not Forge (a captive portal's 200 page is the
+                // classic case): report no advance and let the stall guard fail the
+                // attempt, rather than crediting bytes that may never have arrived.
+                // parseInt would also turn a garbage header into NaN, which slips
+                // through that guard (every comparison with NaN is false) and ends
+                // the upload loop as a success.
+                const newOffset = parseIntegerHeader(xhr.getResponseHeader('Upload-Offset'), 0) ?? offset;
                 finish(() => resolve(newOffset));
             }
             else {
@@ -188,18 +382,147 @@ function uploadChunk(uploadUrl, istk, chunk, offset, timeoutMs, signal, onChunkP
         };
         xhr.onerror = () => finish(() => reject(new TusUploadError('Chunk upload network error', { phase: 'network' })));
         xhr.onabort = () => finish(() => reject(new TusUploadError('Chunk upload aborted', { phase: 'cancelled' })));
-        xhr.ontimeout = () => finish(() => reject(new TusUploadError(`Chunk upload timeout after ${timeoutMs / 1000}s`, { phase: 'timeout' })));
+        xhr.ontimeout = () => finish(() => reject(new TusUploadError('Chunk upload timed out', { phase: 'timeout' })));
         xhr.open('PATCH', uploadUrl);
         xhr.setRequestHeader('Tus-Resumable', TUS_VERSION);
         xhr.setRequestHeader('Upload-Offset', String(offset));
         xhr.setRequestHeader('Content-Type', 'application/offset+octet-stream');
         xhr.setRequestHeader('X-ISTK', istk);
-        xhr.timeout = timeoutMs;
+        // No absolute XHR deadline (see the function comment); the watchdog below
+        // is armed before send and re-armed on every progress event.
+        armWatchdog();
+        cap = setTimeout(() => stall(`Chunk upload exceeded ${CHUNK_ABSOLUTE_CAP_MS / 60000} minutes`), CHUNK_ABSOLUTE_CAP_MS);
         // React Native-only body shape (see TusChunk): the native layer decodes
         // `base64` itself, so the chunk bytes never touch the JS thread.
         xhr.send({ base64: chunk.base64 });
     });
 }
+/**
+ * PATCH a whole file as the session's only chunk on the app's background
+ * URLSession. The OS owns the transfer, so it finishes even if iOS suspends
+ * the app; the trade is no progress events and no abort. The result is mapped
+ * exactly like the XHR path so callers see one error taxonomy.
+ */
+async function uploadWholeFileInBackground(uploader, uploadUrl, istk, fileUri, offset) {
+    let result;
+    try {
+        result = await uploader.uploadFile(uploadUrl, fileUri, {
+            method: 'PATCH',
+            headers: {
+                'Tus-Resumable': TUS_VERSION,
+                'Upload-Offset': String(offset),
+                'Content-Type': 'application/offset+octet-stream',
+                'X-ISTK': istk,
+            },
+        });
+    }
+    catch (err) {
+        // The adapter only throws when no HTTP response came back (offline, DNS,
+        // the OS cancelled the task); an HTTP failure is a status below.
+        throw new TusUploadError(`Background chunk upload failed: ${getErrorMessage(err)}`, {
+            cause: err instanceof Error ? err : null,
+            phase: 'network',
+        });
+    }
+    const body = typeof result.body === 'string' ? result.body : '';
+    if (result.status >= 200 && result.status < 300) {
+        const offsetHeader = getHeaderIgnoreCase(result.headers, 'Upload-Offset');
+        // Forge always answers a PATCH with Upload-Offset. A 2xx without it is not
+        // Forge (a captive portal's 200 page is the classic case), so report no
+        // advance: the stall guard fails the attempt and the next one asks Forge
+        // (HEAD) instead of marking bytes uploaded that may never have arrived.
+        return offsetHeader ? parseInt(offsetHeader, 10) : offset;
+    }
+    const gateError = gateErrorFromBody(result.status, parseErrorBody(body));
+    if (gateError) {
+        throw gateError;
+    }
+    throw new TusUploadError(`Chunk upload failed: ${result.status} - ${body.substring(0, 200)}`, {
+        httpStatus: result.status,
+        phase: 'upload',
+    });
+}
+/**
+ * Translate what the OS transfer adapter reports into the SDK's one error
+ * taxonomy, so a caller sees the same `TusUploadError` phases and typed gate
+ * errors whichever engine carried the bytes. Forge's status and body ride
+ * through untouched: a 402 becomes the gate error the XHR path throws, a
+ * 404/410 marks the session lost exactly as HEAD would, and any other status
+ * keeps its number for the caller's own policy (a 409 during finalize is a
+ * retry-later, not a lost session). The remaining kinds are transport
+ * outcomes: the caller's own abort is `cancelled`; an OS-ended task
+ * (`interrupted`) is a network failure, because the right response is the
+ * same as for a dropped connection: resume from the server offset. Anything
+ * that is not a `BackgroundTransferError` is an adapter defect and is
+ * reported as a network failure with the cause attached, never swallowed.
+ */
+export function mapBackgroundTransferError(err, context = {}) {
+    if (!(err instanceof BackgroundTransferError)) {
+        return new TusUploadError(`Background transfer failed: ${getErrorMessage(err)}`, {
+            cause: err instanceof Error ? err : null,
+            ...context,
+            phase: 'network',
+        });
+    }
+    switch (err.kind) {
+        case 'http': {
+            const status = err.httpStatus;
+            const body = err.body ?? '';
+            if (status !== undefined) {
+                const gateError = gateErrorFromBody(status, parseErrorBody(body));
+                if (gateError)
+                    return gateError;
+            }
+            const sessionLost = status === 404 || status === 410;
+            return new TusUploadError(sessionLost
+                ? `TUS session no longer exists on the server (${status})`
+                : `Background chunk upload failed: ${status ?? 'unknown status'} - ${body.substring(0, 200)}`, { cause: err, httpStatus: status ?? null, ...context, phase: 'upload', sessionLost });
+        }
+        case 'cancelled':
+            return new TusUploadError('Upload cancelled', { cause: err, ...context, phase: 'cancelled' });
+        case 'stalled':
+            return new TusUploadError(`Upload stalled: ${err.message}`, { cause: err, ...context, phase: 'stalled' });
+        case 'file':
+            return new TusUploadError(`Background transfer could not read the file: ${err.message}`, {
+                cause: err,
+                ...context,
+                phase: 'upload',
+            });
+        case 'interrupted':
+            return new TusUploadError(`Background transfer interrupted: ${err.message}`, {
+                cause: err,
+                ...context,
+                phase: 'network',
+            });
+        case 'network':
+            return new TusUploadError(`Background transfer network error: ${err.message}`, {
+                cause: err,
+                ...context,
+                phase: 'network',
+            });
+    }
+}
+/**
+ * Hand the whole remaining range of a session to the OS transfer engine and
+ * wait for its verdict. The engine chains every chunk itself, so this is one
+ * await for the entire file however large it is, and the transfer keeps
+ * going while the app is suspended or killed (the adapter re-attaches to
+ * the job by session URL). Progress arrives as absolute server offsets and
+ * is forwarded as (uploaded, total) like every other path; failures are
+ * mapped onto the XHR taxonomy so callers see one set of errors.
+ */
+async function transferRemainderInBackground(engine, job, options) {
+    try {
+        const result = await engine.transfer(job, {
+            abortSignal: options.abortSignal,
+            onProgress: offset => options.onProgress?.(offset, job.fileSize),
+        });
+        return result.offset;
+    }
+    catch (err) {
+        throw mapBackgroundTransferError(err, { filename: options.filename, fileSize: job.fileSize });
+    }
+}
 export class MobileTusUploader {
     constructor(config) {
         this.config = config;
@@ -209,22 +532,115 @@ export class MobileTusUploader {
         if (!fileReader) {
             throw new SparkVaultValidationError('fileReader adapter is required for URI uploads');
         }
-        const parsed = parseForgeUrl(options.forgeUrl);
+        const source = resolveSessionSource(options);
+        const istk = source.mode === 'create' ? source.parsed.istk : source.istk;
         const debug = options.debug;
         const cleanUri = options.fileUri.split('#')[0];
         let bytesUploaded = 0;
-        let uploadUrl = null;
+        // Known up front on resume so a cancel during the HEAD still terminates
+        // the (existing) session.
+        let uploadUrl = source.mode === 'resume' ? source.uploadUrl : null;
         try {
-            debug?.log(`Starting TUS upload for ${options.filename}`);
-            const created = await createTusUpload(this.config, parsed, options.fileSize, options.filename, options.contentType, options.abortSignal);
-            uploadUrl = created.uploadUrl;
-            const chunkSize = created.chunkSize;
+            let chunkSize;
+            let sessionUrl;
+            if (source.mode === 'resume') {
+                sessionUrl = source.uploadUrl;
+                debug?.log(`Resuming TUS upload for ${options.filename}`);
+                const probe = await headTusSession(this.config, source.uploadUrl, istk, options.abortSignal, {
+                    filename: options.filename,
+                    fileSize: options.fileSize,
+                });
+                // A session is bound to one file: a different length means the
+                // persisted session belongs to another file (or this file changed),
+                // and PATCHing into it would corrupt the ingot. That makes the
+                // session worthless for this file, which is exactly what
+                // `sessionLost` means: the caller drops it and starts fresh, the same
+                // as for a 404/410, instead of retrying a resume that can never work.
+                if (probe.length !== options.fileSize) {
+                    throw new TusUploadError(`TUS session Upload-Length (${probe.length}) does not match the file size (${options.fileSize}); the session belongs to a different file`, { filename: options.filename, fileSize: options.fileSize, phase: 'create', sessionLost: true });
+                }
+                chunkSize = probe.chunkSize;
+                bytesUploaded = probe.offset;
+                debug?.log(`TUS session for ${options.filename} is at offset ${bytesUploaded}/${options.fileSize}`);
+                if (bytesUploaded >= options.fileSize) {
+                    // Every byte is there, but the finalization the last chunk should
+                    // have triggered may not have happened (that is often why the
+                    // previous attempt failed): ask Forge to finalize and acknowledge.
+                    await confirmTusFinalization(this.config, sessionUrl, istk, options.fileSize, options.abortSignal, {
+                        filename: options.filename,
+                        fileSize: options.fileSize,
+                    });
+                    options.onProgress?.(bytesUploaded, options.fileSize);
+                }
+            }
+            else {
+                debug?.log(`Starting TUS upload for ${options.filename}`);
+                const created = await createTusUpload(this.config, source.parsed, options.fileSize, options.filename, options.contentType, options.abortSignal);
+                sessionUrl = created.uploadUrl;
+                uploadUrl = sessionUrl;
+                chunkSize = created.chunkSize;
+                // Before the first PATCH: once bytes are in flight the session is
+                // worth resuming, so the caller must already hold it.
+                options.onSessionCreated?.({ uploadUrl: sessionUrl, istk, chunkSize });
+            }
+            // The OS transfer engine, when the app provides one, takes the whole
+            // remaining range in a single hand-off: it chains the chunks itself and
+            // keeps going while the app is suspended or killed, which no JS loop
+            // can. Any size and any offset qualify, so a resumed multi-GB video
+            // rides it too; the single-chunk adapter and XHR in the loop below are
+            // the fallbacks. Start-or-attach on the session URL means a relaunch
+            // that resumes the same session re-joins the job the OS is still
+            // running instead of PATCHing over it.
+            const backgroundTransfer = options.transport === 'background' ? this.config.backgroundTransfer : undefined;
+            if (backgroundTransfer && bytesUploaded < options.fileSize) {
+                ensureNotAborted(options.abortSignal);
+                const policy = options.transferPolicy ?? {};
+                const finalOffset = await transferRemainderInBackground(backgroundTransfer, {
+                    uploadUrl: sessionUrl,
+                    istk,
+                    fileUri: cleanUri,
+                    fileSize: options.fileSize,
+                    chunkSize,
+                    offset: bytesUploaded,
+                    allowsCellularAccess: policy.allowsCellularAccess ?? true,
+                    allowsConstrainedNetworkAccess: policy.allowsConstrainedNetworkAccess ?? true,
+                }, { filename: options.filename, abortSignal: options.abortSignal, onProgress: options.onProgress });
+                // The engine only resolves at the end of the file; anything else is
+                // an engine that gave up quietly, and an offset past the file is as
+                // untrustworthy as one short of it. Same treatment as a non-advancing
+                // PATCH: fail, and let the next attempt ask Forge (HEAD) where the
+                // session really stands.
+                if (finalOffset !== options.fileSize) {
+                    throw new TusUploadError(`Upload stalled: background transfer ended at offset ${finalOffset} of ${options.fileSize}`, { phase: 'stalled', filename: options.filename, fileSize: options.fileSize });
+                }
+                // An abort that lands after the OS delivered the last byte changes
+                // nothing: the transfer is complete, and the loop below (with its
+                // abort check) has nothing left to do. Same rule as the single-chunk
+                // adapter: a finished upload is never reported as cancelled.
+                bytesUploaded = finalOffset;
+                options.onProgress?.(bytesUploaded, options.fileSize);
+            }
             while (bytesUploaded < options.fileSize) {
                 ensureNotAborted(options.abortSignal);
-                const chunkLength = Math.min(chunkSize, options.fileSize - bytesUploaded);
-                const chunk = await this.readChunk(fileReader, cleanUri, bytesUploaded, chunkLength);
                 const chunkStart = bytesUploaded;
-                const newOffset = await uploadChunk(uploadUrl, parsed.istk, chunk, chunkStart, this.config.tusChunkTimeoutMs, options.abortSignal, chunkUploaded => options.onProgress?.(chunkStart + chunkUploaded, options.fileSize));
+                const chunkLength = Math.min(chunkSize, options.fileSize - chunkStart);
+                let newOffset;
+                const backgroundUploader = options.transport === 'background' ? this.config.backgroundUploader : undefined;
+                if (backgroundUploader && this.fitsOneBackgroundRequest(chunkStart, options.fileSize, chunkSize)) {
+                    // The OS owns this request, so an abort that fires while it is in
+                    // flight cannot stop it. It only ever carries a whole single-chunk
+                    // file, so a 2xx here means the transfer is complete: the loop
+                    // ends and the upload finishes normally (the caller verifies the
+                    // ingot), because a finished upload must never be reported as
+                    // cancelled, and a DELETE now would drop bytes Forge has already
+                    // finalized. Only a response that leaves bytes missing reaches
+                    // the `ensureNotAborted` at the top of the next iteration.
+                    newOffset = await uploadWholeFileInBackground(backgroundUploader, sessionUrl, istk, cleanUri, chunkStart);
+                }
+                else {
+                    const chunk = await this.readChunk(fileReader, cleanUri, chunkStart, chunkLength);
+                    newOffset = await uploadChunk(sessionUrl, istk, chunk, chunkStart, this.config.tusChunkTimeoutMs, options.abortSignal, chunkUploaded => options.onProgress?.(chunkStart + chunkUploaded, options.fileSize));
+                }
                 if (newOffset <= chunkStart || newOffset > options.fileSize) {
                     throw new TusUploadError('Upload stalled: server offset did not advance', {
                         phase: 'stalled',
@@ -244,10 +660,17 @@ export class MobileTusUploader {
             // what lets Forge remove already-written chunk objects (otherwise they
             // are orphaned in S3 — nothing else cleans them up) and settle
             // partial-transfer billing, matching the web client's abort semantics.
+            // Unless the caller asked to keep it: a pause is not a cancel, and the
+            // bytes Forge holds are exactly what a later resume avoids re-sending.
             const cancelled = options.abortSignal?.aborted === true ||
                 (err instanceof TusUploadError && err.phase === 'cancelled');
             if (cancelled && uploadUrl) {
-                this.terminateUpload(uploadUrl, parsed.istk, debug);
+                if (options.abortBehavior === 'keep') {
+                    debug?.log(`TUS session for ${options.filename} kept on Forge for resume`);
+                }
+                else {
+                    this.terminateUpload(uploadUrl, istk, debug);
+                }
             }
             if (err instanceof TusUploadError)
                 throw err;
@@ -263,6 +686,73 @@ export class MobileTusUploader {
             });
         }
     }
+    /**
+     * Where a persisted session stands, or `null` when Forge no longer has it
+     * (404/410 — expired or terminated). Any other failure throws with
+     * `sessionLost` false (a 5xx or timeout says nothing about the session).
+     * The probe reports the session's own length; whether that length is the
+     * caller's file is for the caller (or `uploadFromUri`'s resume, which
+     * throws `sessionLost` on a mismatch) to judge. Lets a caller reconcile
+     * sessions on relaunch (a completed one just needs its ingot verified; a
+     * lost one needs a fresh create) before spending an upload slot on it.
+     */
+    async probeSession(session) {
+        try {
+            return await headTusSession(this.config, session.uploadUrl, session.istk);
+        }
+        catch (err) {
+            if (err instanceof TusUploadError && err.sessionLost)
+                return null;
+            throw err;
+        }
+    }
+    /**
+     * Whether the remaining transfer is ONE PATCH the background adapter can
+     * send: nothing uploaded yet and the whole file inside a single chunk. The
+     * adapter sends whole files and Forge rejects any non-final chunk that is
+     * not exactly `X-Chunk-Size`, so a multi-chunk file has no legal single
+     * request, and a partially uploaded session would resend bytes Forge holds.
+     * A zero-byte file stays on the XHR path (it sends no PATCH at all there).
+     */
+    fitsOneBackgroundRequest(offset, fileSize, chunkSize) {
+        return offset === 0 && fileSize > 0 && fileSize <= chunkSize;
+    }
+    /**
+     * Release a session the caller kept on Forge (`abortBehavior: 'keep'`)
+     * and will not resume after all: the tus DELETE lets Forge drop the chunk
+     * objects it holds (nothing else cleans them up before expiry) and settle
+     * the partial transfer's billing. Resolves once the session is gone,
+     * which includes Forge answering 404/410 (already expired or terminated);
+     * any other failure rejects with a `TusUploadError` (a timeout, or the
+     * status Forge sent) so the caller can retry later. Not bound to any
+     * abort signal: a terminate is the last thing a caller does with a
+     * session, never something to cancel.
+     */
+    async terminateSession(session) {
+        // A terminate is the one place the SDK knows the OS job must die with
+        // the session: a DELETE under a job the engine is still chaining would
+        // leave it PATCHing a gone session until it fails on its own.
+        const backgroundTransfer = this.config.backgroundTransfer;
+        if (backgroundTransfer) {
+            await this.cancelBackgroundTransfer(backgroundTransfer, session.uploadUrl);
+        }
+        const response = await this.requestTerminate(session.uploadUrl, session.istk).catch(err => {
+            if (getErrorName(err) === 'AbortError') {
+                throw new TusUploadError('TUS DELETE request timed out', {
+                    cause: err instanceof Error ? err : null,
+                    phase: 'timeout',
+                });
+            }
+            throw err;
+        });
+        if (response.ok || response.status === 404 || response.status === 410)
+            return;
+        const errorText = await response.text().catch(() => '');
+        throw new TusUploadError(`TUS terminate failed: ${response.status} - ${errorText.substring(0, 200)}`, {
+            httpStatus: response.status,
+            phase: 'unknown',
+        });
+    }
     /**
      * Best-effort tus termination after a cancelled upload. Fire-and-forget so
      * cancel UX stays instant and the cancellation error still propagates — a
@@ -271,17 +761,48 @@ export class MobileTusUploader {
      * which would kill the DELETE before it left the device.
      */
     terminateUpload(uploadUrl, istk, debug) {
-        void this.config
-            .fetch(uploadUrl, {
+        // The OS job, when there is one, is cancelled before the DELETE so the
+        // engine stops PATCHing a session Forge is about to forget (see
+        // terminateSession); without an engine the DELETE leaves the device
+        // synchronously, exactly as it always has.
+        const backgroundTransfer = this.config.backgroundTransfer;
+        const terminate = backgroundTransfer
+            ? this.cancelBackgroundTransfer(backgroundTransfer, uploadUrl, debug).then(() => this.requestTerminate(uploadUrl, istk))
+            : this.requestTerminate(uploadUrl, istk);
+        void terminate.catch(err => {
+            debug?.log(`TUS termination after cancel failed: ${getErrorMessage(err)}`);
+        });
+    }
+    /**
+     * Ask the OS transfer engine to drop the job for a session about to be
+     * terminated. Best-effort and never throwing: a job the engine no longer
+     * has is a no-op by contract, and a failure here must not stop the DELETE
+     * that follows, which is what actually frees Forge's chunks.
+     */
+    async cancelBackgroundTransfer(engine, uploadUrl, debug) {
+        try {
+            await engine.cancel(uploadUrl);
+        }
+        catch (err) {
+            const message = `Background transfer cancel before terminate failed: ${getErrorMessage(err)}`;
+            debug?.log(message);
+            this.config.logger.debug(message, { uploadUrl });
+        }
+    }
+    /**
+     * The one tus DELETE request builder, shared by the fire-and-forget cancel
+     * path and the awaited `terminateSession` so both send exactly the same
+     * request: same headers, same timeout, and no abort signal (see the
+     * callers for why neither may carry one).
+     */
+    requestTerminate(uploadUrl, istk) {
+        return this.config.fetch(uploadUrl, {
             method: 'DELETE',
             headers: {
                 'Tus-Resumable': TUS_VERSION,
                 'X-ISTK': istk,
             },
             timeoutMs: this.config.tusPostTimeoutMs,
-        })
-            .catch(err => {
-            debug?.log(`TUS termination after cancel failed: ${getErrorMessage(err)}`);
         });
     }
     async readChunk(fileReader, fileUri, position, length) {