ODS V3 Pre-Release: Public testing and refinement ahead of the official V3 launch. Turn your PC, Mac, or Linux box into a private AI server.
Python ai-agentsamdcomfyuidockerllama-cppllmlocal-ain8nnvidiaopen-webuiragself-hostedspeech-to-textstrix-halotext-to-speechworkflow-automation
import { useState, useEffect, useCallback, useRef } from 'react'
const TERMINAL_DOWNLOAD_STATUSES = new Set(['failed', 'error', 'cancelled'])
// Allow the API's 30-second host-agent request to settle before giving up.
const CANCEL_ACK_TIMEOUT_MS = 45000
// Status reads normally allow five seconds for the host-agent observation.
const STATUS_TIMEOUT_MS = 15000
function isTerminalProgress(progress) {
return TERMINAL_DOWNLOAD_STATUSES.has(progress?.status)
}
function downloadArtifactKey(model) {
if (typeof model !== 'string') return null
// Active split downloads name a part, while cancellation names part one.
// Normalize only the host's documented progress suffix and GGUF part index.
return model.replace(/ \((?:part \d+\/\d+|\d+ parts?)\)$/, '')
.replace(/-\d{5}-of-(\d{5})(\.gguf)$/i, '-part-of-$1$2')
}
function cancelledTransfer(current, terminal) {
// The API keeps cancellation inactive: idle + lastTerminalStatus. Consume
// that record only for a transfer this hook actually observed, so historical
// receipts cannot reappear on mount, after dismissal, or after completion.
const terminalStatus = typeof terminal?.status === 'string' ? terminal.status.toLowerCase() : null
if (!['downloading', 'verifying'].includes(current?.status)
|| !['cancelled', 'canceled'].includes(terminalStatus)
|| typeof terminal?.model !== 'string' || !terminal.model
|| downloadArtifactKey(terminal.model) !== downloadArtifactKey(current.downloadTarget || current.model)) return null
const observedAt = Date.parse(current.updatedAt || current.startedAt)
const terminalAt = Date.parse(terminal.updatedAt)
if (Number.isFinite(observedAt) && (!Number.isFinite(terminalAt) || terminalAt < observedAt)) return null
return {
status: 'cancelled',
model: terminal.model,
error: (typeof terminal.error === 'string' && terminal.error)
|| (typeof terminal.message === 'string' && terminal.message)
|| 'Download cancelled',
}
}
async function errorFromResponse(response, fallback) {
try {
const payload = await response.json()
const detail = payload?.detail
if (typeof detail === 'string' && detail.trim()) return detail
if (typeof payload?.error === 'string' && payload.error.trim()) return payload.error
if (typeof payload?.message === 'string' && payload.message.trim()) return payload.message
} catch {
// Fall through to the stable user-facing fallback.
}
return fallback
}
/**
* Hook to poll download progress during model downloads.
* Returns progress data when a download is active.
*/
export function useDownloadProgress(pollIntervalMs = 1000) {
const [progress, setProgress] = useState(null)
const [isDownloading, setIsDownloading] = useState(false)
const [completedDownload, setCompletedDownload] = useState(null)
const [statusError, setStatusError] = useState(null)
const [cancelError, setCancelError] = useState(null)
const [isCancelling, setIsCancelling] = useState(false)
const lastCompleteKeyRef = useRef(null)
const progressRequestRef = useRef(0)
const activeProgressRequestRef = useRef(null)
const cancelInFlightRef = useRef(false)
const fetchProgress = useCallback(async (skipIfPending = false) => {
const previous = activeProgressRequestRef.current
if (previous) {
if (skipIfPending) return null
clearTimeout(previous.timer)
previous.controller.abort()
}
const requestId = ++progressRequestRef.current
const controller = new AbortController()
const request = { controller, timer: null }
request.timer = setTimeout(() => {
controller.abort()
if (activeProgressRequestRef.current === request) {
activeProgressRequestRef.current = null
setStatusError('Download status unavailable: request timed out.')
}
}, STATUS_TIMEOUT_MS)
activeProgressRequestRef.current = request
try {
const response = await fetch('/api/models/download-status', { signal: controller.signal })
if (requestId !== progressRequestRef.current || controller.signal.aborted) return null
if (!response.ok) {
const detail = await errorFromResponse(
response,
`Download status unavailable (HTTP ${response.status}).`,
)
if (requestId !== progressRequestRef.current || controller.signal.aborted) return null
setStatusError(detail)
return null
}
const data = await response.json()
if (requestId !== progressRequestRef.current || controller.signal.aborted) return null
setStatusError(null)
if (data.status === 'downloading' || data.status === 'verifying') {
const downloaded = data.bytesDownloaded || 0
const total = data.bytesTotal || 0
const rawPercent = total > 0 ? (downloaded / total) * 100 : 0
const percent = Math.min(100, Math.max(0, rawPercent))
setIsDownloading(true)
setProgress({
model: data.model,
downloadTarget: data.activeOperation === 'model_download' && typeof data.activeTarget === 'string'
? data.activeTarget : data.model,
status: data.status,
percent,
bytesDownloaded: downloaded,
bytesTotal: total,
speedMbps: data.speedBytesPerSec ? data.speedBytesPerSec / (1024 * 1024) : 0,
eta: data.eta,
startedAt: data.startedAt,
updatedAt: data.updatedAt,
})
} else if (data.status === 'complete' || data.status === 'idle') {
setIsDownloading(false)
setCancelError(null)
if (data.status === 'complete') {
setProgress(null)
const completeKey = `${data.model || ''}:${data.updatedAt || ''}`
if (completeKey && completeKey !== lastCompleteKeyRef.current) {
lastCompleteKeyRef.current = completeKey
setCompletedDownload({
model: data.model,
status: data.status,
updatedAt: data.updatedAt
})
}
} else {
// A later idle snapshot must not erase the only visible record of a
// failed or cancelled transfer. The next download or dismissal does.
setProgress(current => cancelledTransfer(current, data.lastTerminalStatus)
|| (isTerminalProgress(current) ? current : null))
}
} else if (TERMINAL_DOWNLOAD_STATUSES.has(data.status)) {
setIsDownloading(false)
setCancelError(null)
setProgress({
status: data.status,
error: data.error || data.message || (data.status === 'cancelled' ? 'Download cancelled' : 'Download failed'),
model: data.model
})
}
return data
} catch (err) {
if (requestId !== progressRequestRef.current || controller.signal.aborted) return null
setStatusError(`Download status unavailable: ${err?.message || 'network error'}`)
return null
} finally {
clearTimeout(request.timer)
if (activeProgressRequestRef.current === request) activeProgressRequestRef.current = null
}
}, [])
useEffect(() => {
void fetchProgress()
return () => {
// Invalidate even a body that settles after abort during navigation.
++progressRequestRef.current
const request = activeProgressRequestRef.current
activeProgressRequestRef.current = null
if (request) {
clearTimeout(request.timer)
request.controller.abort()
}
}
}, [fetchProgress])
useEffect(() => {
// Poll frequently only while downloading; otherwise check every 10s.
// Skip ticks while the tab is hidden — nobody sees the progress bar and
// the visibility handler below catches state up on return (#1490).
const activeInterval = isDownloading ? pollIntervalMs : 10000
const tick = () => { if (!document.hidden) fetchProgress(true) }
const interval = setInterval(tick, activeInterval)
// Resume immediately when the tab becomes visible again
const onVisibility = () => { if (!document.hidden) fetchProgress() }
document.addEventListener('visibilitychange', onVisibility)
return () => {
clearInterval(interval)
document.removeEventListener('visibilitychange', onVisibility)
}
}, [fetchProgress, pollIntervalMs, isDownloading])
// Format helpers
const formatBytes = (bytes) => {
if (!bytes) return '0 B'
const gb = bytes / (1024 ** 3)
if (gb >= 1) return `${gb.toFixed(2)} GB`
const mb = bytes / (1024 ** 2)
if (mb >= 1) return `${mb.toFixed(1)} MB`
const kb = bytes / 1024
if (kb >= 1) return `${kb.toFixed(0)} KB`
return `${bytes.toFixed(0)} B`
}
const formatEta = (eta) => {
if (!eta || eta === 'calculating...') return 'calculating...'
if (typeof eta === 'number') {
const mins = Math.floor(eta / 60)
// Floor the seconds too — a fractional eta (bytes-remaining / rate is a
// float) otherwise renders as "1m 30.700000000000003s". Mirrors the
// Math.floor already applied to minutes.
const secs = Math.floor(eta % 60)
if (mins > 0) return `${mins}m ${secs}s`
return `${secs}s`
}
return eta
}
const cancelDownload = useCallback(async () => {
if (cancelInFlightRef.current) return null
cancelInFlightRef.current = true
setIsCancelling(true)
setCancelError(null)
const controller = new AbortController()
const timeout = setTimeout(() => controller.abort(), CANCEL_ACK_TIMEOUT_MS)
try {
const response = await fetch('/api/models/download/cancel', {
method: 'POST',
signal: controller.signal,
})
if (!response.ok) throw new Error(await errorFromResponse(response, 'Failed to cancel download.'))
// The acknowledgement owns this guard. Status polling remains authoritative
// about the transfer and must not keep the Cancel button locked on a stall.
return fetchProgress()
} catch (err) {
setCancelError(controller.signal.aborted
? 'Cancellation was not acknowledged within 45 seconds. Check download progress before retrying.'
: err?.message || 'Failed to cancel download.')
return null
} finally {
clearTimeout(timeout)
cancelInFlightRef.current = false
setIsCancelling(false)
}
}, [fetchProgress])
const clearTerminal = useCallback(() => {
setProgress(current => isTerminalProgress(current) ? null : current)
setCancelError(null)
}, [])
return {
isDownloading,
progress,
completedDownload,
statusError,
cancelError,
isCancelling,
formatBytes,
formatEta,
refresh: fetchProgress,
cancelDownload,
clearTerminal
}
}