@gentleduck/upload 0.2.6 → 0.3.0

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

@@ -0,0 +1,203 @@
+import { abortReason, makeAbortError } from './transport.libs'
+import type { Transport } from './transport.types'
+
+/**
+ * `fetch`-based transport for non-browser runtimes (Node, edge, workers, SSR)
+ * and any environment without `XMLHttpRequest`.
+ *
+ * Trade-off vs {@link createXHRTransport}: `fetch` has no portable upload
+ * progress API, so `put`/`postForm`/`patch` report a single terminal
+ * `onProgress(total, total)` on success rather than incremental bytes. Download
+ * (`get`) streams the response body, so its progress is real and incremental.
+ *
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+
+function isAbsoluteHttpUrl(url: string): boolean {
+  return /^https?:\/\//i.test(url)
+}
+
+/** Read a single-quotes-stripped ETag from response headers. */
+function readEtag(headers: Headers): string | undefined {
+  const raw = headers.get('etag') ?? headers.get('ETag')
+  if (!raw) return undefined
+  return raw.replace(/"/g, '')
+}
+
+/** Collect response headers into a lowercase-keyed record. */
+function headersToRecord(headers: Headers): Record<string, string> {
+  const out: Record<string, string> = {}
+  headers.forEach((value, key) => {
+    out[key.toLowerCase()] = value
+  })
+  return out
+}
+
+async function fetchRequest(args: {
+  method: 'POST' | 'PUT' | 'PATCH'
+  url: string
+  body: BodyInit
+  signal: AbortSignal
+  headers?: Record<string, string> | undefined
+  onProgress?: ((loaded: number, total: number) => void) | undefined
+  byteLength: number
+}): Promise<{ headers: Record<string, string>; etag?: string | undefined }> {
+  if (!args.url || !isAbsoluteHttpUrl(args.url)) {
+    throw new Error(`UploadTransport(fetch): expected absolute URL, got: ${String(args.url)}`)
+  }
+  if (args.signal.aborted) {
+    throw makeAbortError(abortReason(args.signal))
+  }
+
+  const init: RequestInit = { method: args.method, body: args.body, signal: args.signal }
+  if (args.headers) init.headers = args.headers
+
+  let res: Response
+  try {
+    res = await fetch(args.url, init)
+  } catch (err) {
+    if (args.signal.aborted || (err instanceof Error && err.name === 'AbortError')) {
+      throw makeAbortError(abortReason(args.signal))
+    }
+    throw err instanceof Error ? err : new Error(String(err))
+  }
+
+  if (res.status < 200 || res.status >= 300) {
+    throw new Error(`Upload failed with status ${res.status}`)
+  }
+
+  // fetch cannot report streamed upload progress portably; emit a single
+  // terminal tick so consumers can settle their progress bars.
+  args.onProgress?.(args.byteLength, args.byteLength)
+
+  return { headers: headersToRecord(res.headers), etag: readEtag(res.headers) }
+}
+
+/**
+ * Create a `fetch`-backed {@link Transport.Options} implementation.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export function createFetchTransport(): Transport.Options {
+  return {
+    async postForm(args) {
+      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')
+
+      const out = await fetchRequest({
+        method: 'POST',
+        url: args.url,
+        body: form,
+        signal: args.signal,
+        byteLength: args.file.size,
+        onProgress: args.onProgress,
+      })
+      return out.etag !== undefined ? { headers: out.headers, etag: out.etag } : { headers: out.headers }
+    },
+
+    async put(args) {
+      const out = await fetchRequest({
+        method: 'PUT',
+        url: args.url,
+        body: args.body,
+        signal: args.signal,
+        headers: args.headers ?? {},
+        byteLength: args.body.size,
+        onProgress: args.onProgress,
+      })
+      return { headers: out.headers, etag: out.etag }
+    },
+
+    async patch(args) {
+      const body = args.body instanceof Blob ? args.body : new Blob([args.body])
+      const out = await fetchRequest({
+        method: 'PATCH',
+        url: args.url,
+        body,
+        signal: args.signal,
+        headers: args.headers ?? {},
+        byteLength: body.size,
+        onProgress: args.onProgress,
+      })
+      return { headers: out.headers }
+    },
+
+    async get(args) {
+      if (!args.url || !isAbsoluteHttpUrl(args.url)) {
+        throw new Error(`UploadTransport(fetch): expected absolute URL, got: ${String(args.url)}`)
+      }
+      if (args.signal.aborted) {
+        throw makeAbortError(abortReason(args.signal))
+      }
+
+      const init: RequestInit = { method: 'GET', signal: args.signal }
+      if (args.headers) init.headers = args.headers
+
+      let res: Response
+      try {
+        res = await fetch(args.url, init)
+      } catch (err) {
+        if (args.signal.aborted || (err instanceof Error && err.name === 'AbortError')) {
+          throw makeAbortError(abortReason(args.signal))
+        }
+        throw err instanceof Error ? err : new Error(String(err))
+      }
+
+      if (res.status < 200 || res.status >= 300) {
+        throw new Error(`Download failed with status ${res.status}`)
+      }
+
+      const headers = headersToRecord(res.headers)
+      const total = Number(res.headers.get('content-length')) || 0
+
+      // Stream when possible for incremental progress; otherwise fall back to a
+      // buffered read.
+      if (res.body && typeof res.body.getReader === 'function') {
+        const reader = res.body.getReader()
+        const chunks: Uint8Array[] = []
+        let loaded = 0
+        for (;;) {
+          const { done, value } = await reader.read()
+          if (done) break
+          if (value) {
+            chunks.push(value)
+            loaded += value.byteLength
+            args.onProgress?.(loaded, total || loaded)
+          }
+        }
+        const blob = new Blob(chunks as BlobPart[], {
+          type: res.headers.get('content-type') ?? 'application/octet-stream',
+        })
+        return { blob, status: res.status, headers }
+      }
+
+      const blob = await res.blob()
+      args.onProgress?.(blob.size, total || blob.size)
+      return { blob, status: res.status, headers }
+    },
+
+    async head(args) {
+      if (!args.url || !isAbsoluteHttpUrl(args.url)) {
+        throw new Error(`UploadTransport(fetch): expected absolute URL, got: ${String(args.url)}`)
+      }
+      if (args.signal.aborted) {
+        throw makeAbortError(abortReason(args.signal))
+      }
+
+      const init: RequestInit = { method: 'HEAD', signal: args.signal }
+      if (args.headers) init.headers = args.headers
+
+      let res: Response
+      try {
+        res = await fetch(args.url, init)
+      } catch (err) {
+        if (args.signal.aborted || (err instanceof Error && err.name === 'AbortError')) {
+          throw makeAbortError(abortReason(args.signal))
+        }
+        throw err instanceof Error ? err : new Error(String(err))
+      }
+
+      return { status: res.status, headers: headersToRecord(res.headers) }
+    },
+  }
+}

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

@@ -17,25 +17,24 @@ export function normalizeAbortReason(r: unknown): 'pause' | 'cancel' | 'unknown'
   }
 
   if (isRecord(r) && 'reason' in r) {
-    const v = r.reason
+    const v = r['reason']
     if (v === 'pause' || v === 'cancel') return v
   }
 
   if (isRecord(r) && 'kind' in r) {
-    const v = r.kind
+    const v = r['kind']
     if (v === 'pause' || v === 'cancel') return v
   }
 
   return 'unknown'
 }
 
-export class UploadAbortError extends Error {
-  readonly code: 'aborted' = 'aborted'
-  reason: 'pause' | 'cancel' | 'unknown'
+import { UploadAbortError as CentralAbortError } from '../../errors'
 
+export class UploadAbortError extends CentralAbortError {
   constructor(reason: unknown) {
-    super('Upload aborted')
-    this.reason = normalizeAbortReason(reason)
+    const normalized = normalizeAbortReason(reason)
+    super(normalized)
   }
 }
 
@@ -45,7 +44,7 @@ export function makeAbortError(reason: unknown): UploadAbortError {
 
 /** XHR network error with `status === 0` heuristic for CORS detection. */
 export function createNetworkError(xhr: XMLHttpRequest, defaultMessage: string): Error {
-  // status 0 → CORS failure or transport-level network error.
+  // status 0 -> CORS failure or transport-level network error.
   if (xhr.status === 0) {
     return new Error(
       'CORS error: The upload server does not allow requests from this origin. Please check CORS configuration.',

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,102 +13,106 @@ 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)
+    },
+  )
 }
 
 /**
  * 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 & {
+export function createXHRTransport(): Transport.Options & {
   /** Optional PATCH for tus-style strategies. */
-  patch?: (args: XhrCommonArgs & { body: Blob | ArrayBuffer }) => Promise<{ headers: Record<string, string> }>
+  patch?: (args: Transport.XhrArgs & { body: Blob | ArrayBuffer }) => Promise<{ headers: Record<string, string> }>
 } {
   return {
     async postForm(args) {
@@ -129,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 }
@@ -141,8 +138,8 @@ 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 ?? (() => {}),
       })
 
       // S3 multipart needs the ETag from each part response.
@@ -154,11 +151,22 @@ export function createXHRTransport(): UploadTransport & {
         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,
+  }
+}