A full-featured download manager.
import path from 'node:path'
import { stripHopByHopHeaders } from '@core/bridge-receiver/header-replay'
import { ensureMediaExtension } from '@core/bridge-receiver/pipelines/media-final-name'
import {
type AdaptedMux,
sanitizeFilename,
} from '@core/bridge-receiver/submit-download-adapter'
import type {
AddTorrentParams,
CreateDownloadParams,
DirectResourceMetadataProfile,
EngineAdapter,
} from '@core/engine/engine-adapter'
import { DIRECT_RESOURCE_METADATA_PROFILE } from '@core/engine/engine-adapter'
import { ensureDirectory } from '@core/fs/ensure-directory'
import { sanitizeFinalizeFilename } from '@core/fs/finalize-path'
import { newEngineTaskId, newTaskId } from '@core/lib/ids'
import { getLogger } from '@core/logger'
import type { HookAuditLog } from '@core/plugin/hooks/audit-log'
import type { HookOrchestrator } from '@core/plugin/hooks/hook-orchestrator'
import type { StagedMetadataOp } from '@core/plugin/hooks/staged-effects'
import type {
AppliedDownloadProxyPolicyReader,
AppliedDownloadProxySnapshot,
} from '@core/proxy/applied-download-proxy-policy'
import {
extractAria2ProxyCredentials,
normalizeAria2TaskProxyUrl,
normalizeProxyUrl,
} from '@core/proxy/aria2-proxy-routing'
import type { SettingsManager } from '@core/settings/settings-manager'
import { INCOMPLETE_SUFFIX } from '@shared/constants/incomplete'
import { AppError, ErrorCode } from '@shared/errors'
import { formatFileSelection } from '@shared/lib/file-selection-ranges'
import type {
TaskCreateRequest,
TaskCreateSuccessResult,
} from '@shared/schemas/add-task'
import { taskCreateRequestSchema } from '@shared/schemas/add-task'
import type { BeforeCreateHttpContextDTO } from '@shared/types/plugin-hooks'
import type {
DownloadTask,
SourceMeta,
TaskInstance,
TaskSource,
} from '@shared/types/task'
import {
makeDefaultBtExtension,
makeDownloadTask,
TaskInstancePhase,
TaskKind,
TaskStatus,
TaskType,
TransitionPhase,
} from '@shared/types/task'
import {
canManageBtStorage,
isTorrentLikeType,
} from '@shared/types/task-actions'
import type { TaskActivityRecorder } from '@shared/types/task-activity'
import type Database from 'better-sqlite3'
import {
acquireBtInfoHashAdmission,
existingFilesConflict,
extractMagnetInfoHash,
inspectBtDuplicate,
reservedBtFinalNames,
TorrentDuplicateConflictError,
withBtOutputAdmission,
} from './bt-duplicate-policy'
import { verifyBtFiles } from './bt-file-verifier'
import {
btOutputPaths,
hasBtControlFile,
hasReservedTaskOutput,
} from './bt-output-reservation'
import {
btStoragePayload,
createBtDirectStoragePlan,
type ParsedBtFileLayout,
parseBtFileLayout,
shouldPrioritizeBtPreviewPieces,
UnsafeTorrentPathError,
} from './bt-storage-layout'
import {
type CreateRequestReceipt,
createRequestFingerprint,
runCreateRequest,
} from './create-request-id'
import {
buildDirectReplayRecipe,
type DirectReplayRecipe,
} from './direct-replay-recipe'
import {
canMirrorAria2MetadataHeaders,
canRepresentDirectResourceHeaders,
type DirectResourceMetadata,
type DirectResourceRequestOptions,
type DirectResourceValidatorService,
sanitizeRemoteFilename,
} from './direct-resource-validator'
import type { FinalNamePicker } from './final-name-picker'
import { findPathOverrun } from './path-length'
import { toTempPath } from './paths'
import {
admitDownloadSources,
admitHttpSource,
admitTaskCreateRequest,
DownloadSourceError,
} from './source-admission'
import { admitTaskCookies } from './task-cookie-admission'
import type { TaskManager } from './task-manager'
import type { TorrentMetaStore } from './torrent-meta-store'
const log = getLogger('create-task')
type CreateDirectResourceValidator = Pick<
DirectResourceValidatorService,
'capture'
> &
Partial<Pick<DirectResourceValidatorService, 'probe'>>
export interface CreateTaskDeps {
adapter: EngineAdapter
settingsManager: SettingsManager
finalNamePicker: FinalNamePicker
torrentMetaStore: TorrentMetaStore
taskManager: TaskManager
activityRecorder: TaskActivityRecorder
eventBus: { emit(event: string, payload: unknown): void }
/** Optional best-effort capture of a non-secret HTTP resource validator. */
directResourceValidator?: CreateDirectResourceValidator
/**
* Holds the engine's applied proxy generation stable from metadata discovery
* through the matching aria2 addUri dispatch.
*/
directResourceProxyPolicy: AppliedDownloadProxyPolicyReader
/**
* Coalesced TaskUpdated publication (TaskUpdatePublisher.publish). Both
* create-side broadcasts are non-terminal (announce a new owned task /
* republish after a rolled-back create), so they ride the trailing window.
*/
publishTaskUpdate: () => void
// Optional plugin-hook plumbing (Plan C / T15). All three must be present
// for the chain to fire; absence is a clean no-op for backward compat.
orchestrator?: HookOrchestrator
auditLog?: HookAuditLog
/**
* Persists the new task graph and pre-Hook metadata in one SQLite
* transaction. Required whenever beforeCreate stages metadata operations.
*/
persistTaskWithPluginMetadata?: (
task: DownloadTask,
operations: readonly StagedMetadataOp[],
beforeCommit?: () => void
) => Promise<void>
/** @deprecated Retained for legacy composition; never used for Hook commit. */
db?: Database.Database
/** Optional engine-readiness gate. Awaited immediately before each engine
* adapter call so a cold-start request waits for aria2 instead of hitting
* a not-yet-connected RPC socket. Absent ⇒ no gate (back-compat / tests). */
waitForEngineReady?: () => Promise<void>
/**
* Synchronous readiness check used while an applied-proxy read lease is
* held. It must not wait for a restart: a restarted engine belongs to a new
* applied-proxy generation and the current admission must fail closed.
*/
assertEngineReady?: () => void
/**
* Host-owned save-directory preflight. Server injects containment and
* writability enforcement; Electron may omit it because its native picker
* and shell own that policy.
*/
prepareSaveDir?: (requested: string) => Promise<string>
/** Rejecting parent-row durability barrier, invoked before publication. */
persistTask?: (task: DownloadTask) => Promise<void>
/**
* Inspector Activity parent/Added barrier. The runtime invokes
* `persistParent`, ensures the activity parent, and records Added before
* returning.
*/
parentTaskCreated?: (
task: DownloadTask,
persistParent: () => void | Promise<void>
) => Promise<void>
/**
* Compensating delete for a parent row whose durable create intent must be
* rolled back. Production implementations must include the Inspector
* Activity parent/timeline in the same serialized deletion.
*/
rollbackTaskCreation?: (taskId: string) => Promise<void>
/** Deterministic seam for tests; defaults to a random aria2-compatible GID. */
createEngineTaskId?: () => string
/** Serialize publication/removal races for the newly allocated public ID. */
runTaskMutation?: <T>(
taskIds: readonly string[],
operation: () => Promise<T>
) => Promise<T>
/**
* Optional YouTube/bilibili pre-resolver. When present and the HTTP URL
* resolves to a mux pair (video + audio), the download is routed to the
* MuxPipeline instead of the normal HTTP engine path. Both deps must be
* present for the seam to fire; absence of either → unchanged HTTP path.
* Errors are owned by the factory (returns null → HTTP fallback).
* The optional cookieHeader arg is for bilibili HD (desktop Add-Task path
* passes no cookies — only the extension submit path forwards them).
*/
resolveToMux?: (
url: string,
cookieHeader?: string
) => Promise<{
videoUrl: string
audioUrl: string
container: 'mp4' | 'mkv'
headers?: Record<string, string>
title?: string
} | null>
/** Dispatch an AdaptedMux to the shared MuxPipeline. Must be paired with
* resolveToMux — both present or both absent. */
dispatchMux?: (adapted: AdaptedMux) => Promise<{ taskId: string }>
/** Re-adds a terminal BT task against its final layout with integrity
* checking. Shell command handlers inject the existing reAddTask action. */
reuseExistingBt?: (taskId: string) => Promise<void>
/** Called with content and destination admission already held. */
relocateExistingBt?: (
taskId: string,
directory: string,
name: string
) => Promise<void>
}
export interface CreateTaskOptions {
/** Internal paired-bridge reservation. Only the host can supply this callback. */
handoff?: {
taskId: string
gid: string
commit: (task: DownloadTask, request: CreateDownloadParams) => Promise<void>
}
source?: TaskSource // default 'user'
sourceMeta?: SourceMeta // default null
/** Ephemeral credentials; kept out of persisted task records and plugins. */
cookies?: CreateDownloadParams['cookies']
/** Engine option dictionary merged into the engine call: header
* (repeated), referer. createTaskHandler forwards these
* via CreateDownloadParams.extraEngineOptions; the adapter honors the
* keys it understands. */
extraEngineOptions?: Record<string, string | string[]>
}
type AdmittedCreateOptions = CreateTaskOptions & {
receipt?: CreateRequestReceipt
}
/**
* Create a new download task. Side effects, in order:
* 1. Resolve `finalName` via FinalNamePicker (collision-safe).
* 2. Persist torrent bytes (BT torrent-base64 only) via TorrentMetaStore.
* 3. Build engine-agnostic create params with path overrides so on-disk
* artifacts land in the task's in-flight location.
* 4. Call the EngineAdapter to obtain the engine gid.
* 5. Register the fully-populated DownloadTask with TaskManager so
* subsequent polling updates merge onto an already-present record
* (preserving diskPath / finalPath / finalName / transitionPhase /
* torrentMetaPath).
*
* The legacy IPC contract returned only `{ gid }`; the result now also
* carries the freshly-minted `taskId` (== DownloadTask.id) so callers
* that need the stable public identifier (notably the MDXP bridge, where
* gid can rotate across instance swaps) don't have to reach into
* TaskManager to look it up. Renderer-facing IPC paths still narrow to
* `{ gid }` structurally — the extra field is harmless excess.
*/
export async function handleCreateTask(
rawRequest: unknown,
deps: CreateTaskDeps,
opts: CreateTaskOptions = {}
): Promise<TaskCreateSuccessResult> {
const request = admitTaskCreateRequest(rawRequest)
if (request.type === 'http' && request.uris[0].startsWith('ftp:')) {
const reason = !deps.adapter.getCapabilities().ftp
? 'unsupportedProtocol'
: opts.cookies?.length ||
Object.keys(opts.extraEngineOptions ?? {}).length
? 'unsupportedRequestOptions'
: null
if (reason)
throw new DownloadSourceError({
stage: 'input',
index: 0,
diagnostic: { reason, start: 0, end: 0 },
})
}
const fingerprint = createRequestFingerprint({ request, opts })
const receipt =
request.type === 'http' && request.requestId
? {
createRequestId: request.requestId,
createRequestFingerprint: fingerprint,
}
: undefined
return runCreateRequest(
deps.taskManager,
request.type === 'http' ? request.requestId : undefined,
fingerprint,
() => createAdmittedTask(request, deps, { ...opts, receipt })
)
}
async function createAdmittedTask(
rawRequest: unknown,
deps: CreateTaskDeps,
opts: AdmittedCreateOptions
): Promise<TaskCreateSuccessResult> {
const parsed = taskCreateRequestSchema.safeParse(rawRequest)
if (parsed.success && parsed.data.type === 'http') {
// Snapshot and clean credentials before any await or task side effect.
// Existing idempotent receipts are resolved before reaching this admission.
if (opts.cookies !== undefined)
opts = { ...opts, cookies: admitTaskCookies(deps.adapter, opts.cookies) }
const policy = deps.directResourceProxyPolicy
// Cold-start waiting happens before taking the proxy read lease. Once the
// lease is held, a later disconnect must fail fast instead of waiting on
// a restart that belongs to a newer applied-route generation.
if (deps.waitForEngineReady) {
await deps.waitForEngineReady()
}
// Keep a runtime guard for untyped composition code: missing policy
// injection must disable metadata I/O instead of consulting newer,
// potentially unapplied SettingsManager values.
const requestedDir =
parsed.data.saveDir || deps.settingsManager.getApp().defaultSaveDir
const preparedDir = deps.prepareSaveDir
? await deps.prepareSaveDir(requestedDir)
: requestedDir
return withBtOutputAdmission(preparedDir, () =>
policy
? policy.runWithSnapshot((snapshot, lease) =>
handleCreateTaskUnderAdmission(
rawRequest,
deps,
opts,
snapshot,
lease.assertCurrent,
preparedDir
)
)
: handleCreateTaskUnderAdmission(
rawRequest,
deps,
opts,
null,
undefined,
preparedDir
)
)
}
if (!parsed.success || parsed.data.type !== 'bt') {
return handleCreateTaskUnderAdmission(rawRequest, deps, opts)
}
const req = parsed.data
const requestedSaveDir =
req.saveDir || deps.settingsManager.getApp().defaultSaveDir
const preparedSaveDir = deps.prepareSaveDir
? await deps.prepareSaveDir(requestedSaveDir)
: requestedSaveDir
const createBtTask = () =>
withBtOutputAdmission(preparedSaveDir, () =>
handleCreateTaskUnderAdmission(
rawRequest,
deps,
opts,
undefined,
undefined,
preparedSaveDir
)
)
let infoHash =
req.payload.kind === 'magnet'
? extractMagnetInfoHash(req.payload.uri)
: null
if (!infoHash && req.payload.kind === 'torrent-base64') {
try {
const bytes = req.torrentBytes ?? decodeBase64ToBytes(req.payload.base64)
infoHash = (await parseBtFileLayout(bytes)).infoHash
} catch {
// The canonical create path below owns parse-error handling and logging.
}
}
if (!infoHash) return createBtTask()
const release = await acquireBtInfoHashAdmission(infoHash)
try {
return await createBtTask()
} finally {
release()
}
}
async function handleCreateTaskUnderAdmission(
rawRequest: unknown,
deps: CreateTaskDeps,
opts: AdmittedCreateOptions = {},
appliedProxySnapshot?: AppliedDownloadProxySnapshot,
assertAppliedProxyCurrent?: () => void,
preparedSaveDir?: string
): Promise<TaskCreateSuccessResult> {
const parsed = taskCreateRequestSchema.safeParse(rawRequest)
if (!parsed.success) {
throw new AppError(
ErrorCode.IpcInvalidPayload,
`Invalid task create request: ${parsed.error.message}`
)
}
const req = parsed.data
const appSettings = deps.settingsManager.getApp()
const engineSettings = deps.settingsManager.getEngine()
if (req.type === 'http')
req.uris = admitDownloadSources(req.uris, 'input', [
'http',
'https',
'ftp',
]).map((source) => source.sourceUrl)
const requestedSaveDir = req.saveDir || appSettings.defaultSaveDir
const effectiveSaveDir =
preparedSaveDir ??
(deps.prepareSaveDir
? await deps.prepareSaveDir(requestedSaveDir)
: requestedSaveDir)
const taskId = opts.handoff?.taskId ?? newTaskId()
log.info(
{
type: req.type,
payloadKind: req.type === 'bt' ? req.payload.kind : 'http',
saveDir: effectiveSaveDir,
selectedFiles: req.type === 'bt' ? req.selectedFiles.length : undefined,
},
'createTask received'
)
// Decode torrent bytes once — needed for both name extraction (info.name)
// and TorrentMetaStore persistence. Bencode parsing lets us honor the
// torrent's self-declared name instead of falling back to the literal
// 'torrent' when neither displayName nor magnet dn= is provided.
let torrentBytes: Uint8Array | null = null
let torrentInfoName: string | null = null
let parsedBtLayout: ParsedBtFileLayout | null = null
let isPrivateFromTorrent = false
if (req.type === 'bt' && req.payload.kind === 'torrent-base64') {
torrentBytes = req.torrentBytes ?? decodeBase64ToBytes(req.payload.base64)
try {
parsedBtLayout = await parseBtFileLayout(torrentBytes, req.selectedFiles)
torrentInfoName = parsedBtLayout.torrentRootName
isPrivateFromTorrent = parsedBtLayout.isPrivate
} catch (err) {
if (err instanceof AppError) throw err
throw new AppError(
ErrorCode.TorrentParseFailed,
err instanceof UnsafeTorrentPathError
? 'Torrent contains an unsafe file path'
: 'Invalid torrent metadata',
err
)
}
}
const btInfoHash =
req.type !== 'bt'
? null
: (parsedBtLayout?.infoHash ??
(req.payload.kind === 'magnet'
? extractMagnetInfoHash(req.payload.uri)
: null))
const useExistingFiles =
req.type === 'bt' && req.duplicatePolicy === 'use-existing'
if (
useExistingFiles &&
req.type === 'bt' &&
parsedBtLayout &&
btInfoHash &&
deps.relocateExistingBt
) {
const matching = deps.taskManager
.getAll()
.filter(
(task) =>
task.status !== TaskStatus.Removed &&
task.infoHash?.toLowerCase() === btInfoHash
)
const sameSelection = (values: readonly number[]) =>
[...new Set(values)].sort((a, b) => a - b).join(',')
const owner = matching.length === 1 ? matching[0] : undefined
if (
owner &&
canManageBtStorage(owner) &&
sameSelection(owner.bt?.selectedFiles ?? []) ===
sameSelection(req.selectedFiles)
) {
await deps.relocateExistingBt(
owner.id,
effectiveSaveDir,
sanitizeFinalizeFilename(deriveDesiredName(req, torrentInfoName))
)
return {
outcome: 'rechecked',
taskId: owner.id,
gid:
deps.taskManager.getById(owner.id)?.engineTaskId ??
owner.engineTaskId,
}
}
if (matching.length > 0)
throw new TorrentDuplicateConflictError({
reason: 'active-info-hash',
infoHash: btInfoHash,
targetDir: effectiveSaveDir,
existingTaskId: matching[0].id,
existingTaskName: matching[0].name,
existingTaskStatus: matching[0].status,
canCreateCopy: false,
})
}
if (req.type === 'bt' && btInfoHash) {
const admission = inspectBtDuplicate(deps.taskManager.getAll(), {
infoHash: btInfoHash,
saveDir: effectiveSaveDir,
selectedFiles: req.selectedFiles,
duplicatePolicy:
req.duplicatePolicy === 'use-existing' ? 'reuse' : req.duplicatePolicy,
excludeTaskId: req.existingTaskId,
})
if (admission.action === 'conflict') {
throw new TorrentDuplicateConflictError(admission.conflict)
}
if (admission.action === 'reuse') {
const didRecheck = admission.recheck && Boolean(deps.reuseExistingBt)
if (didRecheck) {
await deps.reuseExistingBt?.(admission.task.id)
}
const owner =
deps.taskManager.getById(admission.task.id) ?? admission.task
return {
outcome: didRecheck ? 'rechecked' : 'reused',
gid: owner.engineTaskId,
taskId: owner.id,
}
}
}
// 1. Decide final on-disk name (handles collisions).
const desiredName = deriveDesiredName(req, torrentInfoName)
const existingName = sanitizeFinalizeFilename(desiredName)
if (
req.type === 'bt' &&
btInfoHash &&
req.duplicatePolicy === 'reuse' &&
deps.finalNamePicker.isTaken &&
(await deps.finalNamePicker.isTaken(
effectiveSaveDir,
desiredName,
parsedBtLayout?.multiFile === false
))
) {
throw existingFilesConflict(btInfoHash, effectiveSaveDir)
}
const reservedNames = reservedBtFinalNames(
deps.taskManager.getAll(),
effectiveSaveDir,
req.type === 'bt' ? req.existingTaskId : undefined
)
const pickHttpFinalName = (desired: string) =>
reservedNames.length > 0
? deps.finalNamePicker.pick(effectiveSaveDir, desired, reservedNames)
: deps.finalNamePicker.pick(effectiveSaveDir, desired)
let finalName = useExistingFiles
? existingName
: req.type === 'bt'
? await deps.finalNamePicker.pick(
effectiveSaveDir,
desiredName,
reservedNames,
parsedBtLayout?.multiFile === false
)
: await pickHttpFinalName(desiredName)
if (useExistingFiles) {
if (!torrentBytes || !parsedBtLayout || req.type !== 'bt')
throw new AppError(
ErrorCode.TorrentParseFailed,
'task.storage.errors.unavailable'
)
const output = path.join(effectiveSaveDir, existingName)
if (
hasReservedTaskOutput(
deps.taskManager.getAll(),
btOutputPaths(output, parsedBtLayout.multiFile)
) ||
(!parsedBtLayout.multiFile && (await hasBtControlFile(output)))
)
throw new AppError(
ErrorCode.TorrentDuplicateConflict,
'task.storage.errors.conflict'
)
const verification = await verifyBtFiles({
metadata: torrentBytes,
payloadPath: output,
selectedFiles: req.selectedFiles,
})
if (!verification.complete)
throw new AppError(ErrorCode.TaskNotRetryable, 'task.storage.incomplete')
}
const taskType = deriveTaskType(req)
let finalPath = path.join(effectiveSaveDir, finalName)
let diskPath = isTorrentLikeType(taskType) ? finalPath : toTempPath(finalPath)
// Anchor "now" early so the hook DTO's requestedAt and the persisted
// task row share a clock — they are written in the same SQLite
// transaction when plugin metadata is staged.
const now = Date.now()
// 2. Persist torrent bytes for the re-seed dance (BT with raw .torrent).
let torrentMetaPath: string | null = null
if (torrentBytes) {
try {
torrentMetaPath = await deps.torrentMetaStore.persist(
taskId,
torrentBytes
)
} catch (cause) {
throw new AppError(
ErrorCode.TaskCreateTorrentMetaFailed,
'Failed to persist torrent metadata',
cause
)
}
}
const btStoragePlan = isTorrentLikeType(taskType)
? createBtDirectStoragePlan(finalPath, parsedBtLayout, torrentMetaPath)
: null
if (useExistingFiles && btStoragePlan) btStoragePlan.layout.finalized = true
// Fail before a single byte moves when a destination cannot be opened at
// all. The engine opens Windows paths past MAX_PATH (agalwood/Motrix#2183),
// but not past the extended-length limit (see path-length); without this
// the user would pay for the transfer before a generic write error. A
// .torrent declares its internal paths up front, so its deepest one is
// checkable here; a magnet's is not, and falls back to the terminal-error
// classifier.
const plannedPaths = [diskPath, finalPath]
for (const file of parsedBtLayout?.files ?? []) {
if (file.pathInsideRoot) {
plannedPaths.push(path.join(finalPath, file.pathInsideRoot))
}
}
const overrun = findPathOverrun(plannedPaths, process.platform)
if (overrun) {
throw new AppError(
ErrorCode.TaskPathTooLong,
`task path too long: ${overrun.length}/${overrun.limit}: ${overrun.path}`
)
}
// Create the engine's directory before admission so aria2 can persist its
// torrent metadata. Parsed BT maps payloads from its private metadata
// directory into their final locations; unresolved BT uses the final
// container. HTTP keeps its incomplete suffix inside the chosen save root.
const ensureDir = btStoragePlan?.saveDir ?? effectiveSaveDir
try {
await ensureDirectory(ensureDir)
} catch (cause) {
log.warn(
{ err: cause, ensureDir, taskType },
'pre-create disk slot failed; relying on aria2 to mkdirs'
)
}
// 3. Build engine-agnostic create params per task family and dispatch
// through the EngineAdapter. For HTTP, dir=saveDir and out uses the
// incomplete suffix. BT uses its final output directory and no `out`;
// parsed torrents additionally carry per-file output mappings. The adapter
// is responsible for the aria2 wire shape.
let recordPluginEngineDispatch:
| ((params: CreateDownloadParams) => void)
| undefined
let pluginMetadataOps: readonly StagedMetadataOp[] = []
let assertPluginPolicyCurrent: (() => void) | undefined
let handoffRequest: CreateDownloadParams | undefined
let dispatchEngine: (reservedGid: string) => Promise<string>
let directReplay: DirectReplayRecipe | null = null
let canonicalUris = deriveUris(req)
let resourceMetadata: DirectResourceMetadata | null = null
let resourceProbeAttempted = false
const metadataHeadersSupported = canMirrorAria2MetadataHeaders(
deps.adapter.getFeatureReport?.()
)
// Shared by the HTTP and magnet branches — both dispatch through
// createDownload with an identical log line; only their params differ.
const dispatchCreateDownload =
(params: CreateDownloadParams) =>
async (reservedGid: string): Promise<string> => {
params.gid = reservedGid
log.info(
{
method: 'createDownload',
uriCount: params.uris.length,
uris: params.uris,
gid: reservedGid,
saveDir: params.saveDir,
filename: params.filename,
connections: params.connections,
},
'dispatching to engine'
)
recordPluginEngineDispatch?.(params)
return deps.adapter.createDownload(params)
}
if (req.type === 'http' && req.uris[0].startsWith('ftp:')) {
directReplay = buildDirectReplayRecipe({
connections: req.connections,
proxy: req.proxy,
})
canonicalUris = admitDownloadSources(req.uris, 'input', ['ftp']).map(
(source) => source.requestUrl
)
dispatchEngine = dispatchCreateDownload({
uris: canonicalUris,
saveDir: effectiveSaveDir,
filename: `${finalName}${INCOMPLETE_SUFFIX}`,
performanceProfile: engineSettings.performanceProfile,
connections: req.connections,
proxy: req.proxy,
})
} else if (req.type === 'http') {
const clampedConnections =
req.connections !== undefined
? Math.min(req.connections, engineSettings.maxConnectionPerServer)
: undefined
const headersRecord =
req.headers.length > 0
? Object.fromEntries(req.headers.map((h) => [h.name, h.value]))
: undefined
const params: CreateDownloadParams = {
uris: [...req.uris],
// applyPathOverrides HTTP equivalent: dir = saveDir, out = <name>.motrix
saveDir: effectiveSaveDir,
filename: `${finalName}${INCOMPLETE_SUFFIX}`,
performanceProfile: engineSettings.performanceProfile,
userAgent: engineSettings.userAgent,
connections: clampedConnections,
headers: headersRecord,
cookies: opts.cookies,
proxy: req.proxy,
// Bridge referer; createDownload merges these raw AFTER
// dir/out so a shell-supplied option can override (matches old order).
extraEngineOptions: opts.extraEngineOptions,
}
let currentHttpDesiredName = desiredName
const pickHttpName = async (nextDesiredName: string): Promise<void> => {
if (nextDesiredName === currentHttpDesiredName) return
finalName = await pickHttpFinalName(nextDesiredName)
currentHttpDesiredName = nextDesiredName
finalPath = path.join(effectiveSaveDir, finalName)
diskPath = toTempPath(finalPath)
params.filename = `${finalName}${INCOMPLETE_SUFFIX}`
}
// 3.4. Mux pre-resolve seam (desktop Add-Task path).
// When both resolveToMux and dispatchMux are wired (bridge enabled +
// youtube/bilibili URL), call the resolver BEFORE beforeCreate fires.
// On a non-null mux pair, build an AdaptedMux reusing the already-computed
// taskId/saveDir/finalName, then delegate to MuxPipeline and return — the
// entire HTTP/beforeCreate/engine path is bypassed for this URL.
// On null (non-resolver URL, bridge disabled, plugin not enabled) → fall
// through to the unchanged HTTP path. No try/catch here: the factory owns
// error handling (returns null on failure).
if (deps.resolveToMux && deps.dispatchMux) {
const uri = params.uris[0]
if (uri) {
const muxResult = await deps.resolveToMux(uri)
if (muxResult) {
const sanitizedHeaders = muxResult.headers
? stripHopByHopHeaders(muxResult.headers)
: {}
// DIAGNOSTIC: confirm the resolver returned distinct upos hosts and
// that the gatekeeper header (Referer) survives sanitize into the
// MediaJob. Logs HOSTS + header KEY presence only — never values.
log.info(
{
taskId,
videoHost: safeHost(muxResult.videoUrl),
audioHost: safeHost(muxResult.audioUrl),
sameUrl: muxResult.videoUrl === muxResult.audioUrl,
container: muxResult.container,
rawHeaderKeys: Object.keys(muxResult.headers ?? {}),
hasReferer: 'Referer' in sanitizedHeaders,
hasUserAgent: 'User-Agent' in sanitizedHeaders,
},
'mux resolve result'
)
// Prefer the resolver's human title over the URL-derived name (the
// bvid BV1xxx is meaningless). Sanitize, append the container
// extension, THEN dedup — the pick must run on the on-disk name.
const titleBase = muxResult.title
? sanitizeFilename(muxResult.title).trim()
: ''
const muxFinalName = titleBase
? await deps.finalNamePicker.pick(
effectiveSaveDir,
ensureMediaExtension(titleBase, muxResult.container)
)
: finalName
const adaptedMux: AdaptedMux = {
kind: 'mux',
taskId,
saveDir: effectiveSaveDir,
finalName: muxFinalName,
videoUrl: admitHttpSource(muxResult.videoUrl),
audioUrl: admitHttpSource(muxResult.audioUrl),
sanitizedHeaders,
container: muxResult.container,
// Desktop path: no extension session context; sourceMeta is null.
// MediaTaskCoordinator accepts SourceMeta (= BridgeSourceMeta | null).
sourceMeta: null,
receipt: opts.receipt,
}
const muxDispatchResult = await deps.dispatchMux(adaptedMux)
return {
outcome: 'created',
gid: muxDispatchResult.taskId,
taskId: muxDispatchResult.taskId,
}
}
}
}
// 3.5. Plan C plugin-hook chain (HTTP only — BT/magnet beforeCreate is
// out of scope for T15; the orchestrator currently exposes only
// `runBeforeCreateHttp`). When the orchestrator is wired we let eligible
// plugins mutate the create params (uris, headers, proxy) and stage
// metadata that will be committed in the same SQLite transaction as the
// task row. Aborted chains skip the engine call entirely and surface
// PluginRuntimeFault to the IPC caller.
log.info(
{
taskId,
hasOrchestrator: Boolean(deps.orchestrator),
reqType: req.type,
uriCount: req.uris.length,
},
'beforeCreate hook chain pre-check'
)
if (deps.orchestrator) {
const ctxDto: BeforeCreateHttpContextDTO = {
schemaVersion: 1,
invocationId: `before-create:${taskId}`,
taskId,
type: 'http',
sourceUrl: params.uris[0] ?? '',
uris: [...params.uris],
saveDir: effectiveSaveDir,
filename: desiredName,
connections: req.connections,
headers: req.headers.map((h) => ({ name: h.name, value: h.value })),
proxy: req.proxy,
createdBy: 'user',
requestedAt: now,
}
const result = await deps.orchestrator.runBeforeCreateHttp(ctxDto, taskId)
log.info(
{
taskId,
aborted: result.aborted === true,
rewrittenUris: result.aborted ? undefined : result.final.uris,
rewrittenUriCount: result.aborted
? undefined
: result.final.uris.length,
contributors: result.aborted ? undefined : result.contributors,
},
'beforeCreate hook chain result'
)
if (result.aborted) {
await deps.auditLog?.log({
type: 'chain.abort',
hook: 'beforeCreate',
taskId,
reason: result.reason,
})
throw new AppError(
ErrorCode.PluginRuntimeFault,
`plugin chain aborted: ${result.reason}`
)
}
recordPluginEngineDispatch = result.recordEngineDispatch
if (result.staged.hasPolicyChecks) {
assertPluginPolicyCurrent = () => result.staged.assertPolicyCurrent()
assertPluginPolicyCurrent()
}
// Apply merged outputs back to the create params. mergeChain is
// well-defined for the slot keys we care about; absent keys keep
// the user's input intact. Conditionality matches the old code:
// - uris: ALWAYS overwritten (the chain always produces a final set)
// - headers: only when the chain produced headers (else keep req)
// - proxy: TRUTHY check (an empty-string proxy must NOT overwrite)
params.uris = [...result.final.uris]
// Hook outputs are task sources, not plugin HTTP requests. Re-run the
// same source policy as user input; hostPermissions never authorize an
// otherwise invalid or credential-bearing download target.
params.uris = admitDownloadSources(params.uris, 'plugin', [
'http',
'https',
]).map((source) => source.requestUrl)
if (result.final.headers.length > 0) {
params.headers = Object.fromEntries(
result.final.headers.map((h) => [h.name, h.value])
)
}
if (result.final.proxy) {
params.proxy = result.final.proxy
}
// Always emit chain.commit on a successful chain — a chain that
// mutates only uris or proxy (no headers) still completes and
// deserves an audit trail. Matches the sibling site in finalizeTask.
await deps.auditLog?.log({
type: 'chain.commit',
hook: 'beforeCreate',
taskId,
headerContributors: result.contributors.headers,
proxyContributor: result.contributors.proxy,
uriContributor: result.contributors.uris,
finalHeaderCount: result.final.headers.length,
})
assertPluginPolicyCurrent?.()
pluginMetadataOps =
typeof result.staged.allMetadataOps === 'function'
? result.staged.allMetadataOps()
: []
if (pluginMetadataOps.length > 0 && !deps.persistTaskWithPluginMetadata) {
throw new AppError(
ErrorCode.PluginRuntimeFault,
'beforeCreate metadata requires an atomic task persistence boundary'
)
}
}
assertSupportedHttpTaskProxy(params.proxy)
const ambientMetadataProfile = metadataHeadersSupported
? resolveDirectResourceMetadataProfile(deps.adapter)
: null
params.uris = admitDownloadSources(params.uris, 'plugin', [
'http',
'https',
]).map((source) => source.requestUrl)
const metadataRequestProfile = canApplyDirectResourceMetadataProfile(
params,
ambientMetadataProfile
)
if (metadataRequestProfile) {
params.directResourceMetadataProfile = metadataRequestProfile
}
// The hook may replace the source URI. Rebase the non-explicit fallback
// name onto that final URI before probing, so a failed/empty metadata
// response cannot resurrect the original request's basename.
if (!req.filename?.trim()) {
await pickHttpName(uriBasename(params.uris[0]) ?? 'download')
}
assertPluginPolicyCurrent?.()
// Probe only after mux has declined the URL and the plugin chain has
// accepted and finalized its URI/header/proxy outputs. An aborted or
// rewritten request must never probe the stale user-supplied target.
// Manual names remain authoritative and skip filename discovery.
if (
!opts.handoff &&
!req.filename?.trim() &&
params.uris.length === 1 &&
metadataRequestProfile !== null &&
deps.directResourceValidator?.probe
) {
const uri = params.uris[0]
if (uri) {
resourceProbeAttempted = true
try {
const requestContext = directResourceRequestContext(
params,
appliedProxySnapshot ?? null
)
resourceMetadata = requestContext
? await deps.directResourceValidator.probe(uri, requestContext)
: null
const remoteName = resourceMetadata?.filename
? sanitizeRemoteFilename(resourceMetadata.filename)
: null
if (remoteName) await pickHttpName(remoteName)
} catch {
// Fetch/proxy errors may echo signed URLs or credentials. Keep the
// optional fallback diagnostic limited to the non-secret host.
log.debug(
{ host: safeHost(uri), taskId },
'remote resource metadata probe skipped'
)
}
}
}
// Persist only the request-shape capability needed to decide whether a
// future retry can be reconstructed from TaskInstance. Paths and URIs are
// already canonical fields on the instance; modifier VALUES remain
// engine-call-only so credentials never enter motrix.db.
assertPluginPolicyCurrent?.()
if (
params.uris.length === 1 &&
(await deps.adapter.supportsDirectTaskRetry?.())
) {
params.retainRequestContext = true
}
directReplay = buildDirectReplayRecipe(
params,
ambientMetadataProfile === null
)
if (
directReplay.replayability === 'uri-only' &&
metadataRequestProfile !== null &&
!opts.handoff &&
deps.directResourceValidator &&
params.uris.length === 1
) {
try {
const uri = params.uris[0] as string
const requestContext = directResourceRequestContext(
params,
appliedProxySnapshot ?? null
)
const resourceValidator = resourceProbeAttempted
? resourceMetadata?.validator
: requestContext
? await deps.directResourceValidator.capture(uri, requestContext)
: null
if (resourceValidator) {
directReplay = { ...directReplay, resourceValidator }
}
} catch (error) {
// Validator capture is an optional safety enhancement. A HEAD failure
// must not make an otherwise valid download impossible to create.
log.debug(
{ err: error, taskId },
'direct resource validator capture skipped'
)
}
}
assertPluginPolicyCurrent?.()
canonicalUris = [...params.uris]
if (opts.handoff) handoffRequest = params
dispatchEngine = dispatchCreateDownload(params)
} else if (req.payload.kind === 'torrent-base64') {
// Torrent bytes were decoded earlier for name/private extraction; they
// are always present on the torrent-base64 path.
const params: AddTorrentParams = {
metadata: torrentBytes ?? decodeBase64ToBytes(req.payload.base64),
...(useExistingFiles
? { checkIntegrity: true, preserveExistingFiles: true }
: {}),
saveDir: btStoragePlan?.saveDir ?? diskPath,
// CREATE-PATH +1: req indices are 0-based; aria2 select-file is
// 1-based. The adapter compacts consecutive indices into ranges.
selectedFiles: req.selectedFiles.map((i) => i + 1),
outputFilePaths: btStoragePlan?.outputFilePaths,
outputRoot: btStoragePlan?.outputRoot,
dlLimit: req.dlLimit,
ulLimit: req.ulLimit,
seedRatio: req.seedRatio,
// Replaces the old inline `options['bt-tracker'] = ''` set.
isPrivate: isPrivateFromTorrent,
...(parsedBtLayout && shouldPrioritizeBtPreviewPieces(parsedBtLayout)
? { prioritizePreviewPieces: true }
: {}),
}
dispatchEngine = async (reservedGid) => {
params.gid = reservedGid
// Never log `params.metadata` itself: pino would expand the whole
// torrent byte array into a multi-megabyte JSON line.
const { metadata, selectedFiles, outputFilePaths } = params
log.info(
{
method: 'addTorrent',
metadataBytes: metadata.length,
selectedFileCount: selectedFiles?.length,
mappedFileCount: outputFilePaths?.length,
},
'dispatching to engine'
)
return deps.adapter.addTorrent(params)
}
} else {
// Magnet: BT-typed but no metadata bytes, so it CANNOT use addTorrent.
// Reproduce the old `toBt` magnet wire (addUri with a BT-ish option map +
// dir=diskPath, no out) through createDownload + extraEngineOptions.
const magnetEngineOpts: Record<string, string> = {}
if (req.selectedFiles.length > 0) {
magnetEngineOpts['select-file'] = formatFileSelection(
req.selectedFiles,
0
)
}
if (req.dlLimit !== undefined) {
magnetEngineOpts['max-download-limit'] = String(req.dlLimit)
}
if (req.ulLimit !== undefined) {
magnetEngineOpts['max-upload-limit'] = String(req.ulLimit)
}
if (req.seedRatio !== undefined) {
magnetEngineOpts['seed-ratio'] = String(req.seedRatio)
}
const params: CreateDownloadParams = {
uris: [req.payload.uri],
// dir = diskPath; NO filename → createDownload emits no `out`.
saveDir: diskPath,
// Spread order: magnet opts first, then shell-supplied opts (which
// merged LAST in the old code and could override). createDownload then
// merges extraEngineOptions after `dir`, so the final aria2 map is
// { dir: diskPath, ...magnetEngineOpts, ...opts.extraEngineOptions } —
// explicit shell overrides keep their existing precedence.
extraEngineOptions: {
...magnetEngineOpts,
...(opts.extraEngineOptions ?? {}),
},
}
dispatchEngine = dispatchCreateDownload(params)
}
// Resolve readiness before publishing a durable create intent. A rejected
// cold-start gate must not leave a queued task that was never dispatched.
if (req.type === 'http') {
assertAppliedProxyCurrent?.()
deps.assertEngineReady?.()
} else if (deps.waitForEngineReady) {
await deps.waitForEngineReady()
}
const gid =
opts.handoff?.gid ?? newEngineTaskId(deps.createEngineTaskId, 'createTask')
// 5. Build a fully-populated durable owner before engine dispatch.
const isBtLike = isTorrentLikeType(taskType)
const taskKind: TaskKind = isBtLike ? TaskKind.Bt : TaskKind.Direct
const phase: TaskInstancePhase = isBtLike
? TaskInstancePhase.BtDownload
: TaskInstancePhase.HttpDownload
const primaryInstance: TaskInstance = {
instanceId: `primary:${taskId}`,
motrixId: taskId,
gid,
phase,
status: TaskStatus.Queued,
progress: 0,
totalBytes: parsedBtLayout?.totalBytes ?? 0,
downloadedBytes: 0,
uploadedBytes: 0,
diskPath,
transitionPhase: TransitionPhase.Idle,
uris: canonicalUris,
uriHash: null,
payload: btStoragePlan
? btStoragePayload(btStoragePlan.layout)
: directReplay
? { directReplay }
: {},
createdAt: now,
updatedAt: now,
}
if (opts.receipt) {
primaryInstance.payload = {
...primaryInstance.payload,
...opts.receipt,
}
}
const task: DownloadTask = makeDownloadTask({
id: taskId,
engineTaskId: gid,
name: finalName,
kind: taskKind,
type: taskType,
saveDir: effectiveSaveDir,
createdAt: now,
updatedAt: now,
uris: canonicalUris,
dlLimit: req.type === 'bt' ? (req.dlLimit ?? 0) : 0,
ulLimit: req.type === 'bt' ? (req.ulLimit ?? 0) : 0,
filename: finalName,
diskPath,
finalPath,
finalName,
torrentMetaPath,
infoHash: btInfoHash,
...(parsedBtLayout
? {
totalBytes: parsedBtLayout.totalBytes ?? 0,
sizeWhenDone: parsedBtLayout.totalBytes ?? 0,
fileCount: parsedBtLayout.files.length,
}
: {}),
// For BT/Magnet, seed bt.isPrivate at creation time so SessionManager.save()
// persists is_private to db. Other bt fields are filled in by the next poll
// cycle via translateBtExtension; mergeEngineTask preserves this metadata
// while merging live engine metrics.
bt: isBtLike
? makeDefaultBtExtension({
isPrivate: isPrivateFromTorrent,
selectedFiles: req.type === 'bt' ? req.selectedFiles : [],
})
: undefined,
// Provenance: defaults to 'user'. Bridge receiver passes 'bridge' +
// BridgeSourceMeta via CreateTaskOptions to attribute rows correctly.
source: opts.source ?? 'user',
sourceMeta: opts.sourceMeta ?? null,
instances: [primaryInstance],
})
const createReservedTask = async (): Promise<TaskCreateSuccessResult> => {
if (opts.handoff) {
if (
!handoffRequest ||
pluginMetadataOps.length ||
assertPluginPolicyCurrent
)
throw new Error('Unsupported handoff creation policy')
await opts.handoff.commit(task, { ...handoffRequest, gid })
return { outcome: 'created', taskId, gid }
}
deps.taskManager.reserveEngineTaskId(gid)
const persistParent = async (): Promise<void> => {
assertPluginPolicyCurrent?.()
if (assertPluginPolicyCurrent && deps.persistTaskWithPluginMetadata) {
await deps.persistTaskWithPluginMetadata(
task,
pluginMetadataOps,
assertPluginPolicyCurrent
)
return
}
if (pluginMetadataOps.length > 0) {
await deps.persistTaskWithPluginMetadata?.(task, pluginMetadataOps)
return
}
await deps.persistTask?.(task)
}
const hasDurableIntent = Boolean(
deps.persistTask ||
deps.parentTaskCreated ||
((pluginMetadataOps.length > 0 || assertPluginPolicyCurrent) &&
deps.persistTaskWithPluginMetadata)
)
const rollbackDurableIntent = async (): Promise<boolean> => {
if (!hasDurableIntent) return true
if (!deps.rollbackTaskCreation) return false
try {
await deps.rollbackTaskCreation(task.id)
return true
} catch (rollbackError) {
log.error(
{ err: rollbackError, taskId: task.id },
'failed to roll back durable create intent'
)
return false
}
}
const announceOwnedTask = (): void => {
deps.activityRecorder.recordSubmitted({
taskId: task.id,
occurredAt: task.createdAt,
})
deps.publishTaskUpdate()
}
try {
if (deps.parentTaskCreated) {
await deps.parentTaskCreated(task, persistParent)
} else {
await persistParent()
}
} catch (cause) {
const rolledBack = await rollbackDurableIntent()
if (rolledBack) {
deps.taskManager.releaseEngineTaskIdReservation(gid)
} else {
// A side-effect-then-throw persistence implementation may have left a
// recoverable parent. Keep an in-process owner instead of an unbounded
// ownerless reservation.
deps.taskManager.add(task)
announceOwnedTask()
}
throw cause
}
// Silent reservation owner: SessionManager snapshots now see the durable
// intent, while isEngineTaskIdRetired(gid) continues to block poll merges
// until the adapter confirms the caller-reserved GID.
deps.taskManager.setReservedEngineTaskOwner(task.id, task, gid)
try {
if (req.type === 'http') {
deps.assertEngineReady?.()
assertAppliedProxyCurrent?.()
}
assertPluginPolicyCurrent?.()
const actualGid = await dispatchEngine(gid)
assertPluginPolicyCurrent?.()
if (actualGid.toLowerCase() !== gid.toLowerCase()) {
throw new Error(
`Engine returned gid ${actualGid} instead of reserved gid ${gid}`
)
}
// Ordinary set claims the reservation and opens authoritative polling.
deps.taskManager.add(task)
log.info({ gid, taskId, finalName }, 'engine accepted task')
} catch (cause) {
log.error({ err: cause, taskId, finalName }, 'engine rejected task')
try {
await deps.adapter.forceRemoveTask(gid)
} catch (cleanupError) {
log.warn(
{ err: cleanupError, gid, taskId },
'create compensation force-remove failed'
)
}
let cleanupComplete = false
try {
await deps.adapter.removeDownloadResult(gid)
cleanupComplete = true
} catch (cleanupError) {
cleanupComplete = false
log.error(
{ err: cleanupError, gid, taskId },
'create compensation result cleanup failed'
)
}
if (cleanupComplete) {
// remove() moves the indexed provisional owner into the retired shield;
// consume the still-live reservation before awaiting parent rollback.
deps.taskManager.remove(task.id)
deps.taskManager.retireEngineTaskIdReservation(gid)
const rolledBack = await rollbackDurableIntent()
if (rolledBack) {
deps.publishTaskUpdate()
throw cause
}
}
// The engine outcome or durable rollback is uncertain. Promote the silent
// candidate to an ordinary owner so every live GID has the same public
// task identity and recovery can reconcile it after restart.
if (parsedBtLayout) {
task.status = TaskStatus.Error
primaryInstance.status = TaskStatus.Error
primaryInstance.payload.unconfirmedTorrentCreateGid = gid
task.errorMessage = cause instanceof Error ? cause.message : null
try {
await deps.persistTask?.(task)
} catch (error) {
log.warn(
{ err: error, taskId },
'could not persist uncertain torrent creation'
)
}
}
deps.taskManager.add(task)
announceOwnedTask()
throw cause
}
announceOwnedTask()
// Push the new snapshot so the renderer's UI shows the task
// immediately — without this, the new task is invisible until the
// next polling tick (and even then, if the polled fields match the
// initial Queued/zero state, handlePolledTasks's dirty guard might
// not emit either).
return { outcome: 'created', gid, taskId }
}
return deps.runTaskMutation
? deps.runTaskMutation([taskId], createReservedTask)
: createReservedTask()
}
// ─── Helpers ──────────────────────────────────────────────────
function deriveTaskType(req: TaskCreateRequest): TaskType {
if (req.type === 'http')
return req.uris[0]?.startsWith('ftp:') ? TaskType.Ftp : TaskType.Http
return req.payload.kind === 'magnet' ? TaskType.Magnet : TaskType.Bt
}
function deriveUris(req: TaskCreateRequest): string[] {
if (req.type === 'http') return [...req.uris]
if (req.payload.kind === 'magnet') return [req.payload.uri]
return []
}
function deriveDesiredName(
req: TaskCreateRequest,
torrentInfoName: string | null
): string {
if (req.type === 'http') {
const fname = req.filename?.trim()
if (fname) return fname
const fromUri = uriBasename(req.uris[0])
if (fromUri) return fromUri
return 'download'
}
// BT / magnet priority: explicit displayName > torrent info.name >
// magnet dn= > infoHash > literal fallback.
const display = req.displayName?.trim()
if (display) return display
if (torrentInfoName) return torrentInfoName
if (req.payload.kind === 'magnet') {
const fromMagnet = extractMagnetDn(req.payload.uri)
if (fromMagnet) return fromMagnet
return extractMagnetInfoHash(req.payload.uri) ?? 'magnet'
}
return 'torrent'
}
function directResourceRequestContext(
params: Pick<
CreateDownloadParams,
| 'headers'
| 'cookies'
| 'proxy'
| 'extraEngineOptions'
| 'userAgent'
| 'directResourceMetadataProfile'
>,
appliedProxySnapshot: AppliedDownloadProxySnapshot
): DirectResourceRequestOptions | null {
// Passthrough engine options can add cookies, a referer, headers, or other
// request semantics the metadata client cannot reconstruct safely.
// An explicitly empty task jar is representable; keep it isolated when
// dispatching to the engine, while refusing probes for populated jars.
if (
(params.cookies?.length ?? 0) > 0 ||
(params.extraEngineOptions &&
Object.keys(params.extraEngineOptions).length > 0) ||
params.directResourceMetadataProfile !== DIRECT_RESOURCE_METADATA_PROFILE ||
!canRepresentDirectResourceHeaders(params.headers)
) {
return null
}
const options: DirectResourceRequestOptions = {}
if (params.headers) options.headers = params.headers
if (params.userAgent !== undefined) options.userAgent = params.userAgent
if (appliedProxySnapshot === null) return null
const globalProxy = appliedProxySnapshot
const explicitProxy = params.proxy?.trim()
if (explicitProxy) {
// aria2's task-level all-proxy accepts HTTP proxy syntax only. In
// particular, probing through Undici's SOCKS agent before aria2 rejects
// the task would expose request headers to a route the download never
// uses. Invalid or SOCKS task proxies therefore disable metadata I/O.
const metadataProxy = normalizeProxyUrl(explicitProxy)
if (!metadataProxy || metadataProxy.protocol === 'socks5:') return null
options.proxy = explicitProxy
// aria2's task-level all-proxy overrides only the proxy endpoint. Its
// global no-proxy list still applies, so metadata discovery must inherit
// the same bypass decision or it could send task headers to a proxy while
// the actual download connects directly.
if (globalProxy.noProxy) {
options.noProxy = globalProxy.noProxy
}
return options
}
if (globalProxy.proxy) options.proxy = globalProxy.proxy
if (globalProxy.noProxy) options.noProxy = globalProxy.noProxy
return options
}
function resolveDirectResourceMetadataProfile(
adapter: EngineAdapter
): DirectResourceMetadataProfile | null {
if (!adapter.getDirectResourceMetadataProfile) return null
try {
return adapter.getDirectResourceMetadataProfile()
} catch {
return null
}
}
function canApplyDirectResourceMetadataProfile(
params: Pick<CreateDownloadParams, 'uris' | 'cookies' | 'extraEngineOptions'>,
profile: DirectResourceMetadataProfile | null
): DirectResourceMetadataProfile | null {
if (
profile === null ||
(params.cookies?.length ?? 0) > 0 ||
(params.extraEngineOptions &&
Object.keys(params.extraEngineOptions).length > 0) ||
!params.uris.every(isCredentialFreeHttpUri)
) {
return null
}
return profile
}
function isCredentialFreeHttpUri(uri: string): boolean {
try {
const parsed = new URL(uri)
return (
(parsed.protocol === 'http:' || parsed.protocol === 'https:') &&
parsed.username === '' &&
parsed.password === ''
)
} catch {
return false
}
}
function assertSupportedHttpTaskProxy(proxy: string | undefined): void {
const value = proxy?.trim()
if (
!value ||
(normalizeAria2TaskProxyUrl(value) &&
extractAria2ProxyCredentials(value) !== null)
) {
return
}
throw new AppError(
ErrorCode.TaskCreateFailed,
'Task proxy must use aria2-compatible HTTP or HTTPS syntax; configure SOCKS5 as the global download proxy instead'
)
}
function uriBasename(uri: string | undefined): string | null {
if (!uri) return null
try {
const url = new URL(uri)
const parts = url.pathname.split('/').filter(Boolean)
const last = parts[parts.length - 1]
if (!last) return null
try {
return sanitizeRemoteFilename(decodeURIComponent(last))
} catch {
return sanitizeRemoteFilename(last)
}
} catch {
return null
}
}
/** Host of a URL for diagnostics, or a marker if it doesn't parse. */
function safeHost(u: string): string {
try {
return new URL(u).host
} catch {
return '<unparseable>'
}
}
function extractMagnetDn(uri: string): string | null {
const match = uri.match(/[?&]dn=([^&]+)/)
if (!match) return null
try {
return decodeURIComponent(match[1].replace(/\+/g, ' '))
} catch {
return match[1]
}
}
function decodeBase64ToBytes(b64: string): Uint8Array {
return Uint8Array.from(Buffer.from(b64, 'base64'))
}