Skip to content

A full-featured download manager.

5.5 KB
Raw Blame
import {
  type DownloadTask,
  type TaskInstance,
  TaskInstancePhase,
  TaskStatus,
  TransitionPhase,
} from '@shared/types/task'
import type { TaskActivityRecorder } from '@shared/types/task-activity'
import {
  applyTerminalTransition,
  type TerminalTransitionInput,
} from './apply-terminal-transition'

/**
 * Every engine gid a task currently owns: each instance's gid plus the
 * aggregate `engineTaskId` (the legacy single-instance handle). The single
 * source of the "which gids belong to this task" rule — TaskManager's index,
 * clear-stopped cleanup, and startup recovery all derive from this.
 */
export function collectTaskGids(task: DownloadTask): Set<string> {
  const gids = new Set<string>()
  for (const inst of task.instances) {
    if (inst.gid) gids.add(inst.gid)
  }
  if (task.engineTaskId) gids.add(task.engineTaskId)
  return gids
}

// Phase priority for choosing the primary instance, highest priority first.
// FfmpegMux > BtDownload > HttpDownload > MagnetMetadataResolution
//          > HlsSegment > HlsSubtitle > HlsAudio
//
// Rationale: the primary instance is the one whose gid and status should
// surface as the task's engineTaskId / aggregate status for
// backward-compatible UI. The final-stage instance (mux for HLS, bt_download
// once metadata resolves) wins so the task status reflects the user-visible
// outcome rather than a transient earlier stage.
const PHASE_PRIORITY: Record<TaskInstancePhase, number> = {
  [TaskInstancePhase.FfmpegMux]: 100,
  [TaskInstancePhase.BtDownload]: 90,
  [TaskInstancePhase.HttpDownload]: 80,
  [TaskInstancePhase.MagnetMetadataResolution]: 70,
  [TaskInstancePhase.HlsSegment]: 50,
  [TaskInstancePhase.HlsSubtitle]: 40,
  [TaskInstancePhase.HlsAudio]: 30,
}

export function pickPrimaryInstance(
  instances: TaskInstance[]
): TaskInstance | null {
  if (instances.length === 0) return null
  if (instances.length === 1) return instances[0]

  let best = instances[0]
  let bestPriority = PHASE_PRIORITY[best.phase] ?? 0
  for (let i = 1; i < instances.length; i += 1) {
    const candidate = instances[i]
    const candidatePriority = PHASE_PRIORITY[candidate.phase] ?? 0
    if (candidatePriority > bestPriority) {
      best = candidate
      bestPriority = candidatePriority
    }
  }
  return best
}

/**
 * Keep the aggregate filesystem transition and its durable instance rows in
 * lockstep. SessionManager persists existing task instances verbatim and
 * restore reconstructs the aggregate transition from an instance row, so
 * changing only DownloadTask.transitionPhase does not create a crash barrier.
 *
 * Multi-instance media tasks share one output rename, therefore every instance
 * carries the same aggregate transition marker. This also makes restore
 * deterministic when multiple instances have identical createdAt values.
 */
export function setTaskTransitionPhase(
  task: DownloadTask,
  transitionPhase: TransitionPhase
): void {
  task.transitionPhase = transitionPhase
  for (const instance of task.instances) {
    instance.transitionPhase = transitionPhase
  }
}

/**
 * Synchronize the durable primary instance identity after a single-instance
 * task changes engine gid or aggregate status (BT reseed/adoption).
 */
export function syncPrimaryInstanceIdentity(task: DownloadTask): void {
  const primary = pickPrimaryInstance(task.instances)
  if (!primary) return
  primary.gid = task.engineTaskId || null
  primary.status = task.status
}

/** Terminal aggregate states apply to every logical instance. */
export function syncTerminalInstanceStatus(
  task: DownloadTask,
  status: TaskStatus.Completed | TaskStatus.Error
): void {
  for (const instance of task.instances) {
    instance.status = status
  }
}

/**
 * Apply a terminal aggregate transition AND mirror it onto every instance
 * row in one step. SessionManager restore rebuilds task state from instance
 * rows, so an aggregate terminal status whose instance rows were left behind
 * resurrects a contradictory state after restart — never split this pairing
 * across call sites.
 */
export function applyTerminalStatusToTask(
  task: DownloadTask,
  status: TaskStatus.Completed | TaskStatus.Error,
  incoming: TerminalTransitionInput = {},
  now = Date.now()
): void {
  Object.assign(task, applyTerminalTransition(task, status, incoming, now))
  syncTerminalInstanceStatus(task, status)
}

/**
 * The shared "task is complete after a successful rename" sequence used by
 * the HTTP finalize path, media mux completion, and rename recovery.
 *
 * diskPath is rewritten on every instance too — restore() rebuilds a
 * Completed task's diskPath from the primary instance row, so a stale
 * instance path would resurrect the now-nonexistent placeholder after an
 * app restart, breaking reveal-in-folder and delete-with-files.
 */
export function applyCompletedTaskAfterRename(
  task: DownloadTask,
  finalDiskPath: string,
  completedAt: number
): void {
  task.diskPath = finalDiskPath
  setTaskTransitionPhase(task, TransitionPhase.Idle)
  syncTerminalInstanceStatus(task, TaskStatus.Completed)
  for (const instance of task.instances) {
    instance.diskPath = finalDiskPath
  }
  Object.assign(
    task,
    applyTerminalTransition(task, TaskStatus.Completed, {}, completedAt)
  )
}

export function completeTaskAfterRename(
  task: DownloadTask,
  finalDiskPath: string,
  completedAt: number,
  activityRecorder: TaskActivityRecorder
): void {
  applyCompletedTaskAfterRename(task, finalDiskPath, completedAt)
  activityRecorder.recordDownloadCompleted({
    taskId: task.id,
    occurredAt: completedAt,
  })
}