@gentleduck/upload 0.2.5 → 0.3.0

package/src/core/contracts/transport/transport.ts

@@ -1,12 +1,5 @@
 import { abortReason, createNetworkError, makeAbortError, parseHeaders } from './transport.libs'
-import type { UploadTransport } from './transport.types'
-
-type XhrCommonArgs = {
-  url: string
-  signal?: AbortSignal
-  headers?: Record<string, string>
-  onProgress?: (loaded: number, total: number) => void
-}
+import type { Transport } from './transport.types'
 
 function isAbsoluteHttpUrl(url: string) {
   return /^https?:\/\//i.test(url)
@@ -20,107 +13,110 @@ function readEtag(xhr: XMLHttpRequest) {
 }
 
 function xhrRequest(args: {
-  method: 'POST' | 'PUT' | 'PATCH'
+  method: 'POST' | 'PUT' | 'PATCH' | 'HEAD'
   url: string
   body: Document | BodyInit | null
   signal?: AbortSignal
   headers?: Record<string, string>
   onProgress?: (loaded: number, total: number) => void
 }) {
-  return new Promise<{ headers: Record<string, string>; etag?: string }>((resolve, reject) => {
-    if (!args.url || typeof args.url !== 'string') {
-      reject(new Error(`UploadTransport: missing url`))
-      return
-    }
-    if (!isAbsoluteHttpUrl(args.url)) {
-      reject(new Error(`UploadTransport: expected absolute URL, got: ${String(args.url)}`))
-      return
-    }
-
-    const xhr = new XMLHttpRequest()
-    let settled = false
-
-    const settle = (fn: () => void) => {
-      if (settled) return
-      settled = true
-      cleanup()
-      fn()
-    }
-
-    const onAbort = () => {
-      try {
-        xhr.abort()
-      } finally {
-        settle(() => reject(makeAbortError(abortReason(args.signal))))
+  return new Promise<{ status: number; headers: Record<string, string>; etag?: string | undefined }>(
+    (resolve, reject) => {
+      if (!args.url || typeof args.url !== 'string') {
+        reject(new Error(`UploadTransport: missing url`))
+        return
+      }
+      if (!isAbsoluteHttpUrl(args.url)) {
+        reject(new Error(`UploadTransport: expected absolute URL, got: ${String(args.url)}`))
+        return
       }
-    }
 
-    const cleanup = () => {
-      if (args.signal) args.signal.removeEventListener('abort', onAbort)
+      const xhr = new XMLHttpRequest()
+      let settled = false
 
-      xhr.upload.onprogress = null
-      xhr.onload = null
-      xhr.onerror = null
-      xhr.onabort = null
-    }
+      const settle = (fn: () => void) => {
+        if (settled) return
+        settled = true
+        cleanup()
+        fn()
+      }
 
-    if (args.signal?.aborted) {
-      settle(() => reject(makeAbortError(abortReason(args.signal))))
-      return
-    }
+      const onAbort = () => {
+        try {
+          xhr.abort()
+        } finally {
+          settle(() => reject(makeAbortError(abortReason(args.signal))))
+        }
+      }
 
-    if (args.signal) args.signal.addEventListener('abort', onAbort, { once: true })
+      const cleanup = () => {
+        if (args.signal) args.signal.removeEventListener('abort', onAbort)
 
-    if (args.onProgress) {
-      xhr.upload.onprogress = (e) => {
-        if (e.lengthComputable) args.onProgress?.(e.loaded, e.total)
+        xhr.upload.onprogress = null
+        xhr.onload = null
+        xhr.onerror = null
+        xhr.onabort = null
       }
-    }
-
-    xhr.onload = () => {
-      const status = xhr.status
-      // S3 multipart UploadPart returns 200, tus PATCH returns 204 typically.
-      if (status >= 200 && status < 300) {
-        settle(() =>
-          resolve({
-            headers: parseHeaders(xhr),
-            etag: readEtag(xhr),
-          }),
-        )
-      } else {
-        settle(() => reject(new Error(`Upload failed with status ${status}`)))
+
+      if (args.signal?.aborted) {
+        settle(() => reject(makeAbortError(abortReason(args.signal))))
+        return
       }
-    }
 
-    xhr.onerror = () => settle(() => reject(createNetworkError(xhr, 'Network error during upload')))
+      if (args.signal) args.signal.addEventListener('abort', onAbort, { once: true })
 
-    xhr.onabort = () =>
-      settle(() => reject(makeAbortError(args.signal?.aborted ? abortReason(args.signal) : 'unknown')))
+      if (args.onProgress) {
+        xhr.upload.onprogress = (e) => {
+          if (e.lengthComputable) args.onProgress?.(e.loaded, e.total)
+        }
+      }
 
-    xhr.open(args.method, args.url)
+      xhr.onload = () => {
+        const status = xhr.status
+        // S3 multipart UploadPart returns 200, tus PATCH returns 204 typically.
+        if (status >= 200 && status < 300) {
+          settle(() =>
+            resolve({
+              status,
+              headers: parseHeaders(xhr),
+              etag: readEtag(xhr),
+            }),
+          )
+        } else {
+          settle(() => reject(new Error(`Upload failed with status ${status}`)))
+        }
+      }
+
+      xhr.onerror = () => settle(() => reject(createNetworkError(xhr, 'Network error during upload')))
+
+      xhr.onabort = () =>
+        settle(() => reject(makeAbortError(args.signal?.aborted ? abortReason(args.signal) : 'unknown')))
 
-    if (args.headers) {
-      for (const [k, v] of Object.entries(args.headers)) {
-        xhr.setRequestHeader(k, v)
+      xhr.open(args.method, args.url)
+
+      if (args.headers) {
+        for (const [k, v] of Object.entries(args.headers)) {
+          xhr.setRequestHeader(k, v)
+        }
       }
-    }
 
-    xhr.send(args.body as XMLHttpRequestBodyInit | Document | null)
-  })
+      xhr.send(args.body as XMLHttpRequestBodyInit | Document | null)
+    },
+  )
 }
 
 /**
- * Creates a browser-native XHR transport.
- * We use XMLHttpRequest instead of fetch because fetch does not yet support
- * upload progress events in a standard cross-browser way.
+ * Browser-native XHR transport. Uses `XMLHttpRequest` over `fetch` because
+ * `fetch` lacks cross-browser upload-progress events.
+ * @author wildduck2 <https://github.com/wildduck2>
  */
-export function createXHRTransport(): UploadTransport & {
-  // Optional: for tus strategies (PATCH)
-  patch?: (args: XhrCommonArgs & { body: Blob | ArrayBuffer }) => Promise<{ headers: Record<string, string> }>
+export function createXHRTransport(): Transport.Options & {
+  /** Optional PATCH for tus-style strategies. */
+  patch?: (args: Transport.XhrArgs & { body: Blob | ArrayBuffer }) => Promise<{ headers: Record<string, string> }>
 } {
   return {
     async postForm(args) {
-      // Note: presigned POST is usually absolute already (MinIO/S3 URL)
+      // Presigned POST URLs are absolute (MinIO/S3).
       const form = new FormData()
       for (const [k, v] of Object.entries(args.fields)) form.append(k, v)
       form.append('file', args.file, args.filename ?? 'file')
@@ -130,7 +126,7 @@ export function createXHRTransport(): UploadTransport & {
         url: args.url,
         body: form,
         signal: args.signal,
-        onProgress: args.onProgress,
+        onProgress: args.onProgress ?? (() => {}),
       })
 
       return { headers: out.headers }
@@ -142,25 +138,35 @@ export function createXHRTransport(): UploadTransport & {
         url: args.url,
         body: args.body,
         signal: args.signal,
-        headers: args.headers,
-        onProgress: args.onProgress,
+        headers: args.headers ?? {},
+        onProgress: args.onProgress ?? (() => {}),
       })
 
-      // multipart needs ETag from each part
+      // S3 multipart needs the ETag from each part response.
       return { headers: out.headers, etag: out.etag }
     },
 
-    // Optional for tus strategy (PATCH)
     async patch(args) {
       const out = await xhrRequest({
         method: 'PATCH',
         url: args.url,
         body: args.body,
-        signal: args.signal,
-        headers: args.headers,
-        onProgress: args.onProgress,
+        signal: args.signal ?? new AbortController().signal,
+        headers: args.headers ?? {},
+        onProgress: args.onProgress ?? (() => {}),
       })
       return { headers: out.headers }
     },
+
+    async head(args) {
+      const out = await xhrRequest({
+        method: 'HEAD',
+        url: args.url,
+        body: null,
+        signal: args.signal,
+        headers: args.headers ?? {},
+      })
+      return { status: out.status, headers: out.headers }
+    },
   }
 }

package/src/core/contracts/transport/transport.types.ts

@@ -1,44 +1,80 @@
 /**
- * Abstraction layer for network operations.
- * Allows switching between XHR (browser) or other implementations (testing/Node).
- *
- * Designed to support:
- * - Deterministic progress tracking (requires XHR in browsers)
- * - Cancellation via AbortSignal
- * - Header parsing (ETag extraction)
+ * Transport contracts: the network layer the engine uses to move bytes.
+ * @author wildduck2 <https://github.com/wildduck2>
  */
-export interface UploadTransport {
+export namespace Transport {
   /**
-   * Performs an HTTP PUT request (typically for S3 signed URLs).
+   * Abstraction layer for network operations.
+   * Allows switching between XHR (browser) or other implementations (testing/Node).
+   *
+   * Designed to support:
+   * - Deterministic progress tracking (requires XHR in browsers)
+   * - Cancellation via AbortSignal
+   * - Header parsing (ETag extraction)
    */
-  put(args: {
-    url: string
-    body: Blob
-    headers?: Record<string, string>
-    signal: AbortSignal
-    onProgress?: (u: number, t: number) => void
-  }): Promise<{ etag?: string; headers?: Record<string, string> }>
+  export type Options = {
+    /**
+     * Performs an HTTP PUT request (typically for S3 signed URLs).
+     */
+    put(args: {
+      url: string
+      body: Blob
+      headers?: Record<string, string>
+      signal: AbortSignal
+      onProgress?: (u: number, t: number) => void
+    }): Promise<{ etag?: string | undefined; headers?: Record<string, string> }>
 
-  /**
-   * Performs an HTTP POST multipart request.
-   */
-  postForm(args: {
-    url: string
-    fields: Record<string, string>
-    file: File | Blob
-    filename?: string
-    signal: AbortSignal
-    onProgress?: (uploadedBytes: number, totalBytes: number) => void
-  }): Promise<{ etag?: string; headers?: Record<string, string> }>
+    /**
+     * Performs an HTTP POST multipart request.
+     */
+    postForm(args: {
+      url: string
+      fields: Record<string, string>
+      file: File | Blob
+      filename?: string
+      signal: AbortSignal
+      onProgress?: (uploadedBytes: number, totalBytes: number) => void
+    }): Promise<{ etag?: string; headers?: Record<string, string> }>
 
-  /**
-   * Performs an HTTP request.
-   */
-  patch(args: {
+    /**
+     * Performs an HTTP request.
+     */
+    patch(args: {
+      url: string
+      body: Blob | ArrayBuffer
+      headers?: Record<string, string>
+      signal: AbortSignal
+      onProgress?: (u: number, t: number) => void
+    }): Promise<{ headers?: Record<string, string> }>
+
+    /**
+     * Optional HTTP GET download. Streams the response so `onProgress` can
+     * report bytes as they arrive. Not every transport implements it — check
+     * for presence before calling.
+     */
+    get?(args: {
+      url: string
+      headers?: Record<string, string>
+      signal: AbortSignal
+      onProgress?: (loaded: number, total: number) => void
+    }): Promise<{ blob: Blob; status: number; headers?: Record<string, string> }>
+
+    /**
+     * Optional HTTP HEAD. Used by resumable strategies (tus) to read the
+     * server's current `Upload-Offset` before resuming. Not every transport
+     * implements it — check for presence before calling.
+     */
+    head?(args: {
+      url: string
+      headers?: Record<string, string>
+      signal: AbortSignal
+    }): Promise<{ status: number; headers: Record<string, string> }>
+  }
+
+  export type XhrArgs = {
     url: string
-    body: Blob | ArrayBuffer
+    signal?: AbortSignal
     headers?: Record<string, string>
-    signal: AbortSignal
-    onProgress?: (u: number, t: number) => void
-  }): Promise<{ headers?: Record<string, string> }>
+    onProgress?: (loaded: number, total: number) => void
+  }
 }

package/src/core/engine/__tests__/config-nan-bypass.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from 'vitest'
+import { resolveUploadConfig } from '../engine.libs'
+
+describe('resolveUploadConfig - NaN-bypass defense', () => {
+  test('NaN maxAttempts falls back to default (does NOT propagate NaN)', () => {
+    const cfg = resolveUploadConfig({ maxAttempts: Number.NaN })
+    expect(Number.isFinite(cfg.maxAttempts)).toBe(true)
+    expect(cfg.maxAttempts).toBeGreaterThanOrEqual(1)
+  })
+
+  test('Infinity maxAttempts falls back to default (no infinite retry loop)', () => {
+    const cfg = resolveUploadConfig({ maxAttempts: Number.POSITIVE_INFINITY })
+    expect(Number.isFinite(cfg.maxAttempts)).toBe(true)
+  })
+
+  test('NaN maxConcurrentUploads falls back', () => {
+    const cfg = resolveUploadConfig({ maxConcurrentUploads: Number.NaN })
+    expect(Number.isFinite(cfg.maxConcurrentUploads)).toBe(true)
+  })
+
+  test('Infinity progressThrottleMs falls back (no scheduler wedge)', () => {
+    const cfg = resolveUploadConfig({ progressThrottleMs: Number.POSITIVE_INFINITY })
+    expect(Number.isFinite(cfg.progressThrottleMs)).toBe(true)
+  })
+
+  test('NaN maxItems falls back', () => {
+    const cfg = resolveUploadConfig({ maxItems: Number.NaN })
+    expect(Number.isFinite(cfg.maxItems)).toBe(true)
+  })
+
+  test('negative maxAttempts clamps to 1', () => {
+    const cfg = resolveUploadConfig({ maxAttempts: -5 })
+    expect(cfg.maxAttempts).toBe(1)
+  })
+
+  test('finite positive maxAttempts is preserved', () => {
+    const cfg = resolveUploadConfig({ maxAttempts: 7 })
+    expect(cfg.maxAttempts).toBe(7)
+  })
+})

package/src/core/engine/engine.libs.ts

@@ -0,0 +1,35 @@
+import {
+  DEFAULT_MAX_ATTEMPTS,
+  DEFAULT_MAX_CONCURRENT_UPLOADS,
+  DEFAULT_MAX_ITEMS,
+  DEFAULT_PROGRESS_THROTTLE_MS,
+} from '../utils/constants'
+import type { Engine } from './engine.types'
+
+/**
+ * Clamp a numeric config field, rejecting non-finite values (NaN, Infinity)
+ * that would otherwise slip past a plain `Math.max`.
+ */
+function finitePositive(input: number | undefined, fallback: number, min = 1): number {
+  if (typeof input !== 'number' || !Number.isFinite(input)) return fallback
+  return Math.max(min, input)
+}
+
+/**
+ * Normalizes user config by applying sensible defaults.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export function resolveUploadConfig<P extends string>(input?: Partial<Engine.Config<P>>): Engine.Config<P> {
+  return {
+    maxConcurrentUploads: finitePositive(input?.maxConcurrentUploads, DEFAULT_MAX_CONCURRENT_UPLOADS),
+    autoStart: input?.autoStart,
+    progressThrottleMs: finitePositive(input?.progressThrottleMs, DEFAULT_PROGRESS_THROTTLE_MS, 0),
+    validation: input?.validation ?? {},
+    maxAttempts: finitePositive(input?.maxAttempts, DEFAULT_MAX_ATTEMPTS),
+    retryPolicy: input?.retryPolicy,
+    maxItems: finitePositive(input?.maxItems, DEFAULT_MAX_ITEMS),
+    completedItemTTL: input?.completedItemTTL,
+    strictMimeMatch: input?.strictMimeMatch ?? false,
+    checksumMaxSize: input?.checksumMaxSize ?? null,
+  }
+}