@sparkvault/sdk-mobile 5.2.1 → 5.2.3

package/src/tus.ts

@@ -1,12 +1,25 @@
 import type { ResolvedMobileConfig } from './config.js';
 import { base64EncodeUtf8 } from './encoding.js';
 import {
+  BackgroundTransferError,
   gateErrorFromBody,
   SparkVaultMobileError,
   SparkVaultValidationError,
   TusUploadError,
 } from './errors.js';
-import type { ApiErrorBody, DebugLogger, MobileFileReader, UploadProgressCallback } from './types.js';
+import type {
+  ApiErrorBody,
+  BackgroundTransferJob,
+  DebugLogger,
+  MobileBackgroundTransfer,
+  MobileBackgroundUploader,
+  MobileFileReader,
+  TusSessionInfo,
+  UploadAbortBehavior,
+  UploadProgressCallback,
+  UploadTransferPolicy,
+  UploadTransport,
+} from './types.js';
 
 export interface ParsedForgeUrl {
   baseUrl: string;
@@ -14,14 +27,75 @@ export interface ParsedForgeUrl {
   istk: string;
 }
 
+/**
+ * A previously created tus session to continue instead of creating a new
+ * one. The uploader asks Forge where the session stands (HEAD) and PATCHes
+ * from there, so bytes the server already holds are never sent twice.
+ *
+ * A resume that cannot use the session throws a `TusUploadError` whose
+ * `sessionLost` is true exactly when the session is worthless for this file
+ * and the caller should drop it and start fresh: Forge no longer has it
+ * (404/410), or its `Upload-Length` is not this file's size (it belongs to a
+ * different file). A transient HEAD failure (5xx, timeout) is NOT
+ * `sessionLost`; the session is intact and the same resume can be retried.
+ */
+export interface TusResumeSession {
+  uploadUrl: string;
+  /** The session's ISTK. Falls back to the one in `forgeUrl` when omitted. */
+  istk?: string;
+}
+
+/** Where a tus session stands server-side, as reported by HEAD. */
+export interface TusSessionProbe {
+  offset: number;
+  length: number;
+  chunkSize: number;
+}
+
 export interface TusUploadFromUriOptions {
   fileUri: string;
   fileSize: number;
   filename: string;
   contentType: string;
-  forgeUrl: string;
+  /**
+   * Forge tus endpoint plus ISTK (`forge_url` from the ingot create).
+   * Required to create a session; on resume it only supplies the ISTK when
+   * `resume.istk` is omitted.
+   */
+  forgeUrl?: string;
+  /** Continue this session (HEAD for its offset) instead of POSTing a new one. */
+  resume?: TusResumeSession;
+  /**
+   * Invoked once the session exists server-side and before the first PATCH,
+   * so the caller can persist it and resume after a failed attempt or a
+   * relaunch. Not invoked on resume. A throw here fails the upload.
+   */
+  onSessionCreated?: (session: TusSessionInfo) => void;
+  /**
+   * `background` rides the best suspension-proof engine the app provides:
+   * the OS transfer engine (`backgroundTransfer`) for the whole remaining
+   * range of any file, else the single-chunk `backgroundUploader` (no
+   * progress, no abort) for a file that fits one chunk, else XHR. Default
+   * `foreground`: every chunk goes over XHR.
+   */
+  transport?: UploadTransport;
+  /**
+   * Network policy carried into the OS transfer engine on every request it
+   * sends (see `UploadTransferPolicy`). The XHR and single-chunk paths ignore
+   * it: JS gates connectivity for them. Defaults: both allowed.
+   */
+  transferPolicy?: UploadTransferPolicy;
   onProgress?: UploadProgressCallback;
   abortSignal?: AbortSignal;
+  /**
+   * What an abort does to the Forge session (see `UploadAbortBehavior`).
+   * Default `terminate`: a tus DELETE so Forge drops the chunks (a user
+   * cancel). `keep` leaves the session on Forge for a later `resume` from
+   * the server offset (a pause); the caller must hold the session it was
+   * handed via `onSessionCreated` (or passed in `resume`) and is expected to
+   * resume or terminate it. The cancellation error is the same either way.
+   */
+  abortBehavior?: UploadAbortBehavior;
   debug?: DebugLogger;
 }
 
@@ -109,11 +183,52 @@ interface TusChunk {
   byteLength: number;
 }
 
-/** Strict positive-integer parse of Forge's advertised chunk size; anything else is `null`. */
-function parseChunkSizeHeader(raw: string | null): number | null {
+/**
+ * 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: string | null, minimum: number): number | null {
   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: Record<string, string> | undefined, name: string): string | null {
+  if (!headers) return null;
+  const wanted = name.toLowerCase();
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() === wanted) return headers[key];
+  }
+  return null;
+}
+
+/**
+ * Where a tus upload starts: a fresh session at the Forge endpoint, or a
+ * persisted one resumed by URL. Resolved up front so a misconfigured call
+ * fails as a validation error before any request leaves the device.
+ */
+type TusSessionSource =
+  | { mode: 'create'; parsed: ParsedForgeUrl }
+  | { mode: 'resume'; uploadUrl: string; istk: string };
+
+function resolveSessionSource(options: TusUploadFromUriOptions): TusSessionSource {
+  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(
@@ -184,7 +299,7 @@ async function createTusUpload(
   // 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,
@@ -196,12 +311,176 @@ async function createTusUpload(
   return { uploadUrl, chunkSize };
 }
 
+/**
+ * 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: ResolvedMobileConfig,
+  uploadUrl: string,
+  istk: string,
+  signal?: AbortSignal,
+  context: { filename?: string; fileSize?: number } = {}
+): Promise<TusSessionProbe> {
+  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: ResolvedMobileConfig,
+  uploadUrl: string,
+  istk: string,
+  fileSize: number,
+  signal?: AbortSignal,
+  context: { filename?: string; fileSize?: number } = {}
+): Promise<void> {
+  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 * 60_000;
+
+/**
+ * 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: string,
   istk: string,
   chunk: TusChunk,
   offset: number,
-  timeoutMs: number,
+  stallTimeoutMs: number,
   signal?: AbortSignal,
   onChunkProgress?: (chunkBytesUploaded: number) => void
 ): Promise<number> {
@@ -212,9 +491,13 @@ function uploadChunk(
   return new Promise((resolve, reject) => {
     const xhr = new XMLHttpRequest();
     let settled = false;
+    let watchdog: ReturnType<typeof setTimeout> | null = null;
+    let cap: ReturnType<typeof setTimeout> | null = null;
 
     const cleanup = () => {
       signal?.removeEventListener('abort', abort);
+      if (watchdog) clearTimeout(watchdog);
+      if (cap) clearTimeout(cap);
     };
 
     const finish = (fn: () => void) => {
@@ -235,7 +518,22 @@ function uploadChunk(
     }
     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: string) => {
+      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);
       }
@@ -243,8 +541,14 @@ function uploadChunk(
 
     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 {
         const gateError = gateErrorFromBody(xhr.status, parseErrorBody(xhr.responseText));
@@ -261,20 +565,171 @@ function uploadChunk(
 
     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 / 60_000} 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 } as unknown as XMLHttpRequestBodyInit);
   });
 }
 
+/**
+ * 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: MobileBackgroundUploader,
+  uploadUrl: string,
+  istk: string,
+  fileUri: string,
+  offset: number
+): Promise<number> {
+  let result: Awaited<ReturnType<MobileBackgroundUploader['uploadFile']>>;
+  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: unknown,
+  context: { filename?: string; fileSize?: number } = {}
+): SparkVaultMobileError {
+  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: MobileBackgroundTransfer,
+  job: BackgroundTransferJob,
+  options: { filename: string; abortSignal?: AbortSignal; onProgress?: UploadProgressCallback }
+): Promise<number> {
+  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 {
   private readonly config: ResolvedMobileConfig;
 
@@ -288,40 +743,142 @@ export class MobileTusUploader {
       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: string | null = null;
+    // Known up front on resume so a cancel during the HEAD still terminates
+    // the (existing) session.
+    let uploadUrl: string | null = 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: number;
+      let sessionUrl: string;
+      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 chunkLength = Math.min(chunkSize, options.fileSize - chunkStart);
 
-        const newOffset = await uploadChunk(
-          uploadUrl,
-          parsed.istk,
-          chunk,
-          chunkStart,
-          this.config.tusChunkTimeoutMs,
-          options.abortSignal,
-          chunkUploaded => options.onProgress?.(chunkStart + chunkUploaded, options.fileSize)
-        );
+        let newOffset: number;
+        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', {
@@ -344,11 +901,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;
@@ -364,6 +927,76 @@ 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: { uploadUrl: string; istk: string }): Promise<TusSessionProbe | null> {
+    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).
+   */
+  private fitsOneBackgroundRequest(offset: number, fileSize: number, chunkSize: number): boolean {
+    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: { uploadUrl: string; istk: string }): Promise<void> {
+    // 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
@@ -372,18 +1005,54 @@ export class MobileTusUploader {
    * which would kill the DELETE before it left the device.
    */
   private terminateUpload(uploadUrl: string, istk: string, debug?: DebugLogger): void {
-    void 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)}`);
-      });
+    // 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.
+   */
+  private async cancelBackgroundTransfer(
+    engine: MobileBackgroundTransfer,
+    uploadUrl: string,
+    debug?: DebugLogger
+  ): Promise<void> {
+    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).
+   */
+  private requestTerminate(uploadUrl: string, istk: string): Promise<Response> {
+    return this.config.fetch(uploadUrl, {
+      method: 'DELETE',
+      headers: {
+        'Tus-Resumable': TUS_VERSION,
+        'X-ISTK': istk,
+      },
+      timeoutMs: this.config.tusPostTimeoutMs,
+    });
   }
 
   private async readChunk(