Add stall detection to recover from frozen uploads

This feature addresses the issue of uploads hanging indefinitely in
unreliable network conditions, particularly in Node.js environments
where no default timeout exists.

When uploads stall due to network issues, TCP connections can enter a
degraded state where no data is transferred but no error is triggered.
This implementation detects such stalls and forces a retry.

Implementation details:
- Progress-based: Detects when no upload progress events are fired
- Gracefully integrates with the existing retry mechanism
- Fully configurable with sensible defaults:
  - 30s stall timeout (time with no progress before considering stalled)
  - 5s check interval (how often to check for stalls)

This is especially important for uploads over satellite links, cellular
networks, or other unreliable connections where TCP backoff can cause
indefinite stalls.

Author: m7kvqbe1

docs/api.md

@@ -208,6 +208,34 @@ Following example will trigger up to three retries, each after 1s, 3s and 5s res
 retryDelays: [1000, 3000, 5000]
 ```
 
+#### stallDetection
+
+_Default value:_ `{ enabled: false, stallTimeout: 30000, checkInterval: 5000 }`
+
+An object controlling the stall detection feature, which can automatically detect when an upload has stopped making progress and trigger a retry. This is useful for recovering from frozen uploads caused by network issues that don't trigger explicit errors.
+
+The stall detection options are:
+- `enabled`: Boolean indicating whether stall detection is active (default: `false`)
+- `stallTimeout`: Time in milliseconds without progress before considering the upload stalled (default: `30000`)
+- `checkInterval`: How often in milliseconds to check for stalls (default: `5000`)
+
+**Note:** Stall detection only works with HTTP stacks that support progress events. Currently, this includes:
+- `XHRHttpStack` (browser default) - Supported
+- `NodeHttpStack` (Node.js default) - Supported
+- `FetchHttpStack` - Not supported
+
+When a stall is detected, the upload will be automatically retried according to your `retryDelays` configuration. If `retryDelays` is `null`, the stall will trigger an error instead.
+
+Example configuration:
+
+```js
+stallDetection: {
+    enabled: true,
+    stallTimeout: 15000,  // 15 seconds without progress
+    checkInterval: 2000   // Check every 2 seconds
+}
+```
+
 #### storeFingerprintForResuming
 
 _Default value:_ `true`
@@ -326,6 +354,7 @@ An object used as the HTTP stack for making network requests. This is an abstrac
 interface HttpStack {
     createRequest(method: string, url: string): HttpRequest;
     getName(): string;
+    supportsProgressEvents(): boolean;
 }
 
 interface HttpRequest {
@@ -367,6 +396,14 @@ interface HttpResponse {
 
 ```
 
+The `supportsProgressEvents()` method should return `true` if the HTTP stack implementation supports progress events during upload, or `false` otherwise. This is used by tus-js-client to determine whether features like stall detection can be enabled. The built-in HTTP stacks have the following support:
+
+- `XHRHttpStack` (browser default): Returns `true` - XMLHttpRequest supports progress events
+- `NodeHttpStack` (Node.js default): Returns `true` - Node.js HTTP module supports progress events
+- `FetchHttpStack`: Returns `false` - Fetch API does not support upload progress events
+
+If you're implementing a custom HTTP stack, you should return `true` only if your implementation can reliably call the progress handler set via `setProgressHandler` during the upload process.
+
 #### urlStorage
 
 _Default value:_ Environment-specific implementation

lib/StallDetector.ts

@@ -0,0 +1,93 @@
+import { log } from './logger.js'
+import type { StallDetectionOptions } from './options.js'
+import type { HttpStack } from './options.js'
+
+export class StallDetector {
+  private options: StallDetectionOptions
+  private httpStack: HttpStack
+  private onStallDetected: (reason: string) => void
+
+  private intervalId: ReturnType<typeof setInterval> | null = null
+  private lastProgressTime = 0
+  private isActive = false
+
+  constructor(
+    options: StallDetectionOptions,
+    httpStack: HttpStack,
+    onStallDetected: (reason: string) => void,
+  ) {
+    this.options = options
+    this.httpStack = httpStack
+    this.onStallDetected = onStallDetected
+  }
+
+  /**
+   * Start monitoring for stalls
+   */
+  start() {
+    if (this.intervalId) {
+      return // Already started
+    }
+
+    this.lastProgressTime = Date.now()
+    this.isActive = true
+
+    log(
+      `tus: starting stall detection with checkInterval: ${this.options.checkInterval}ms, stallTimeout: ${this.options.stallTimeout}ms`,
+    )
+
+    // Setup periodic check
+    this.intervalId = setInterval(() => {
+      if (!this.isActive) {
+        return
+      }
+
+      const now = Date.now()
+      if (this._isProgressStalled(now)) {
+        this._handleStall('no progress events received')
+      }
+    }, this.options.checkInterval)
+  }
+
+  /**
+   * Stop monitoring for stalls
+   */
+  stop(): void {
+    this.isActive = false
+    if (this.intervalId) {
+      clearInterval(this.intervalId)
+      this.intervalId = null
+    }
+  }
+
+  /**
+   * Update progress information
+   */
+  updateProgress(): void {
+    this.lastProgressTime = Date.now()
+  }
+
+  /**
+   * Check if upload has stalled based on progress events
+   */
+  private _isProgressStalled(now: number): boolean {
+    const timeSinceProgress = now - this.lastProgressTime
+    const stallTimeout = this.options.stallTimeout
+    const isStalled = timeSinceProgress > stallTimeout
+
+    if (isStalled) {
+      log(`tus: no progress for ${timeSinceProgress}ms (limit: ${stallTimeout}ms)`)
+    }
+
+    return isStalled
+  }
+
+  /**
+   * Handle a detected stall
+   */
+  private _handleStall(reason: string): void {
+    log(`tus: upload stalled: ${reason}`)
+    this.stop()
+    this.onStallDetected(reason)
+  }
+}

lib/browser/FetchHttpStack.ts

@@ -16,6 +16,11 @@ export class FetchHttpStack implements HttpStack {
   getName() {
     return 'FetchHttpStack'
   }
+
+  supportsProgressEvents(): boolean {
+    // The Fetch API does not support progress events for uploads
+    return false
+  }
 }
 
 class FetchRequest implements HttpRequest {

lib/browser/XHRHttpStack.ts

@@ -15,6 +15,11 @@ export class XHRHttpStack implements HttpStack {
   getName() {
     return 'XHRHttpStack'
   }
+
+  supportsProgressEvents(): boolean {
+    // XMLHttpRequest supports progress events via the upload.onprogress event
+    return true
+  }
 }
 
 class XHRRequest implements HttpRequest {

lib/browser/index.ts

@@ -19,12 +19,32 @@ const defaultOptions = {
 
 class Upload extends BaseUpload {
   constructor(file: UploadInput, options: Partial<UploadOptions> = {}) {
-    const allOpts = { ...defaultOptions, ...options }
+    const allOpts = {
+      ...defaultOptions,
+      ...options,
+      // Deep merge stallDetection options if provided
+      ...(options.stallDetection && {
+        stallDetection: {
+          ...defaultOptions.stallDetection,
+          ...options.stallDetection,
+        },
+      }),
+    }
     super(file, allOpts)
   }
 
   static terminate(url: string, options: Partial<UploadOptions> = {}) {
-    const allOpts = { ...defaultOptions, ...options }
+    const allOpts = {
+      ...defaultOptions,
+      ...options,
+      // Deep merge stallDetection options if provided
+      ...(options.stallDetection && {
+        stallDetection: {
+          ...defaultOptions.stallDetection,
+          ...options.stallDetection,
+        },
+      }),
+    }
     return terminate(url, allOpts)
   }
 }

lib/node/NodeHttpStack.ts

@@ -28,6 +28,11 @@ export class NodeHttpStack implements HttpStack {
   getName() {
     return 'NodeHttpStack'
   }
+
+  supportsProgressEvents(): boolean {
+    // Node.js HTTP stack supports progress tracking through streams
+    return true
+  }
 }
 
 class Request implements HttpRequest {

lib/node/index.ts

@@ -19,12 +19,32 @@ const defaultOptions = {
 
 class Upload extends BaseUpload {
   constructor(file: UploadInput, options: Partial<UploadOptions> = {}) {
-    const allOpts = { ...defaultOptions, ...options }
+    const allOpts = {
+      ...defaultOptions,
+      ...options,
+      // Deep merge stallDetection options if provided
+      ...(options.stallDetection && {
+        stallDetection: {
+          ...defaultOptions.stallDetection,
+          ...options.stallDetection,
+        },
+      }),
+    }
     super(file, allOpts)
   }
 
   static terminate(url: string, options: Partial<UploadOptions> = {}) {
-    const allOpts = { ...defaultOptions, ...options }
+    const allOpts = {
+      ...defaultOptions,
+      ...options,
+      // Deep merge stallDetection options if provided
+      ...(options.stallDetection && {
+        stallDetection: {
+          ...defaultOptions.stallDetection,
+          ...options.stallDetection,
+        },
+      }),
+    }
     return terminate(url, allOpts)
   }
 }

lib/options.ts

@@ -48,6 +48,15 @@ export type UploadInput =
   // available in React Native
   | ReactNativeFile
 
+/**
+ * Options for configuring stall detection behavior
+ */
+export interface StallDetectionOptions {
+  enabled: boolean
+  stallTimeout: number // Time in ms before considering progress stalled
+  checkInterval: number // How often to check for stalls
+}
+
 export interface UploadOptions {
   endpoint?: string
 
@@ -84,6 +93,8 @@ export interface UploadOptions {
   httpStack: HttpStack
 
   protocol: typeof PROTOCOL_TUS_V1 | typeof PROTOCOL_IETF_DRAFT_03 | typeof PROTOCOL_IETF_DRAFT_05
+
+  stallDetection?: StallDetectionOptions
 }
 
 export interface OnSuccessPayload {
@@ -141,6 +152,10 @@ export type SliceResult =
 export interface HttpStack {
   createRequest(method: string, url: string): HttpRequest
   getName(): string
+
+  // Indicates whether this HTTP stack implementation
+  // supports progress events during upload.
+  supportsProgressEvents: () => boolean
 }
 
 export type HttpProgressHandler = (bytesSent: number) => void