A full-featured download manager.
import path from 'node:path'
import { DirectPipeline } from '@core/bridge-receiver/pipelines/direct-pipeline'
import { SubmitDownloadAdapter } from '@core/bridge-receiver/submit-download-adapter'
import { initLogger } from '@core/logger'
import {
AppliedDownloadProxyPolicy,
type AppliedDownloadProxySnapshot,
} from '@core/proxy/applied-download-proxy-policy'
import { proxyToDownloadRequestOptions } from '@core/proxy/serializers'
import { encode } from '@motrix/torrent'
import { AppError, ErrorCode } from '@shared/errors'
import { DEFAULT_ENGINE_SETTINGS } from '@shared/schemas/engine-settings'
import { DEFAULT_PROXY_SETTINGS } from '@shared/schemas/proxy-settings'
import type { EngineFeatureReport } from '@shared/types/engine'
import type { ProxySettings } from '@shared/types/settings'
import type { DownloadTask } from '@shared/types/task'
import {
makeDefaultBtExtension,
makeDownloadTask,
TaskInstancePhase,
TaskKind,
TaskStatus,
TaskType,
TransitionPhase,
} from '@shared/types/task'
import { storageTorrent } from '@test-utils/bt-storage'
import { makeDownloadTask as makeTestTask } from '@test-utils/task'
import { v7 as uuidv7 } from 'uuid'
import { beforeEach, describe, expect, it, vi } from 'vitest'
import { Aria2Adapter } from '../engine/aria2/aria2-adapter'
import { DIRECT_RESOURCE_METADATA_PROFILE } from '../engine/engine-adapter'
import { verifyBtFiles } from './bt-file-verifier'
import { parseBtFileLayout } from './bt-storage-layout'
import { handleCreateTask } from './create-task-handler'
import { mergeEngineTask } from './merge-engine-task'
const sampleTorrentBase64 = storageTorrent([
{ name: 'a', data: 'a' },
{ name: 'b', data: 'b' },
{ name: 'c', data: 'c' },
]).toString('base64')
vi.mock('./bt-file-verifier', () => ({ verifyBtFiles: vi.fn() }))
import {
DirectResourceValidatorService,
sanitizeRemoteFilename,
} from './direct-resource-validator'
import { FinalNamePickerImpl } from './final-name-picker'
// Stub directory preparation (and the other `fs.*` calls inadvertently dragged
// in via TorrentMetaStore) so unit tests don't touch the real
// filesystem. The production code calls
// `ensureDirectory(<saveDir-or-diskPath>)`
// with paths like '/d/foo.bin.motrix' which would either fail with
// EACCES or — worse — actually mutate the runner's filesystem. The
// mock also lets us assert WHICH path the production code chose,
// which is the whole point of the BT-vs-HTTP type-gate fix.
//
// `vi.hoisted` is required: `vi.mock` is hoisted above all imports,
// and so are the closures it captures. A plain `const mkdirMock` at
// module scope would be `undefined` when the mock factory runs.
//
// Both `default` and named exports are provided so that TorrentMetaStore's
// `import fs from 'node:fs/promises'` (default) and the directory helper's
// named imports both resolve.
const { mkdirMock, fsStub } = vi.hoisted(() => {
const mkdirMock = vi.fn(async () => undefined)
const fsStub = {
access: vi.fn(async () => {
throw Object.assign(new Error('missing file'), { code: 'ENOENT' })
}),
lstat: vi.fn(async (): Promise<unknown> => {
throw Object.assign(new Error('missing file'), { code: 'ENOENT' })
}),
mkdir: mkdirMock,
stat: vi.fn(async (): Promise<{ isDirectory(): boolean }> => {
throw Object.assign(new Error('missing directory'), { code: 'ENOENT' })
}),
writeFile: vi.fn(async () => undefined),
readFile: vi.fn(async () => Buffer.alloc(0)),
unlink: vi.fn(async () => undefined),
}
return { mkdirMock, fsStub }
})
vi.mock('node:fs/promises', () => ({
...fsStub,
default: fsStub,
}))
const logInfo = vi.fn()
const logWarn = vi.fn()
const logError = vi.fn()
const logDebug = vi.fn()
beforeEach(() => {
mkdirMock.mockReset()
fsStub.stat.mockReset()
logInfo.mockClear()
logWarn.mockClear()
logError.mockClear()
logDebug.mockClear()
initLogger({
child: () => ({
info: logInfo,
warn: logWarn,
error: logError,
debug: logDebug,
}),
} as never)
})
// Build a minimal valid bencoded torrent with an optional private flag.
// Shape: d4:infod<private field?>6:lengthi1024e4:name<N>:<name>
// 12:piece lengthi16384e6:pieces20:<20 zero bytes>ee
function buildMinimalTorrentBytes(
name: string,
isPrivate: boolean
): Uint8Array {
return encode({
info: {
name,
length: 1024,
'piece length': 16384,
pieces: new Uint8Array(20),
...(isPrivate ? { private: 1 } : {}),
},
})
}
function makePrivateTorrentFixture(): Uint8Array {
return buildMinimalTorrentBytes('private-torrent', true)
}
function makePublicTorrentFixture(): Uint8Array {
return buildMinimalTorrentBytes('public-torrent', false)
}
type Deps = Parameters<typeof handleCreateTask>[1]
interface DepOverrides {
addUriGid?: string
addTorrentGid?: string
pick?: (dir: string, name: string) => Promise<string>
persist?: (id: string, bytes: Uint8Array) => Promise<string>
defaultSaveDir?: string
proxySettings?: ProxySettings
appliedProxySnapshot?: AppliedDownloadProxySnapshot
engineUserAgent?: string
engineFeatureReport?: EngineFeatureReport
waitForEngineReady?: () => Promise<void>
prepareSaveDir?: (requested: string) => Promise<string>
}
function httpRequest() {
return {
type: 'http',
uris: ['https://a/b'],
saveDir: '/d',
headers: [],
}
}
describe('source admission before side effects', () => {
it.each([
'https:example.test/a',
'https://example.test/a\\b',
'https://example.test/a%ZZ',
'https://user:[email protected]/a',
'https://example.test/a\tb',
'sftp://example.test/a',
'ftps://example.test/a',
])(
'rejects %s without plugin, directory, probe or engine work',
async (uri) => {
const wait = vi.fn(async () => {})
const prepare = vi.fn(async (dir: string) => dir)
const deps = makeDeps({
waitForEngineReady: wait,
prepareSaveDir: prepare,
})
const { addUri, pick, add } = deps
const plugin = vi.fn()
const probe = vi.fn()
deps.orchestrator = { runBeforeCreateHttp: plugin } as never
deps.directResourceValidator = { capture: probe, probe }
await expect(
handleCreateTask({ ...httpRequest(), uris: [uri] }, deps)
).rejects.toMatchObject({
code: ErrorCode.TaskSourceInvalid,
details: { stage: 'input', index: 0 },
})
for (const fn of [
wait,
prepare,
pick,
plugin,
probe,
mkdirMock,
addUri,
add,
])
expect(fn).not.toHaveBeenCalled()
}
)
it('routes FTP to the FTP task type and skips HTTP plugins and probes', async () => {
const deps = makeDeps()
const { addUri, add } = deps
const plugin = vi.fn()
const probe = vi.fn()
const resolve = vi.fn()
deps.orchestrator = { runBeforeCreateHttp: plugin } as never
deps.directResourceValidator = { capture: probe, probe }
deps.resolveToMux = resolve
await handleCreateTask(
{ ...httpRequest(), uris: ['ftp://example.test/archive.zip'] },
deps
)
expect(addUri).toHaveBeenCalledWith(
['ftp://example.test/archive.zip'],
expect.objectContaining({ dir: '/d' })
)
expect(addUri.mock.calls[0][1]).not.toHaveProperty('header')
expect(add.mock.calls[0][0]).toMatchObject({ type: TaskType.Ftp })
for (const fn of [plugin, probe, resolve]) expect(fn).not.toHaveBeenCalled()
})
it('reuses a persisted receipt even when the prepared directory differs from the request', async () => {
const deps = makeDeps({ prepareSaveDir: async () => '/resolved-dir' })
const { addUri, add } = deps
const tasks: DownloadTask[] = []
vi.mocked(deps.taskManager.getAll).mockImplementation(() => tasks)
add.mockImplementation((task) => tasks.push(task))
const request = { ...httpRequest(), requestId: uuidv7() }
const first = await handleCreateTask(request, deps)
const second = await handleCreateTask(request, deps)
expect(second).toMatchObject({ outcome: 'reused', taskId: first.taskId })
expect(addUri).toHaveBeenCalledOnce()
})
})
function makeDeps(overrides: DepOverrides = {}): Deps & {
addUri: ReturnType<typeof vi.fn>
addUriWithCookies: ReturnType<typeof vi.fn>
addTorrent: ReturnType<typeof vi.fn>
pick: ReturnType<typeof vi.fn>
persist: ReturnType<typeof vi.fn>
set: ReturnType<typeof vi.fn>
add: ReturnType<typeof vi.fn>
remove: ReturnType<typeof vi.fn>
setReservedEngineTaskOwner: ReturnType<typeof vi.fn>
rollbackReservedEngineTaskOwner: ReturnType<typeof vi.fn>
reserveEngineTaskId: ReturnType<typeof vi.fn>
releaseEngineTaskIdReservation: ReturnType<typeof vi.fn>
retireEngineTaskIdReservation: ReturnType<typeof vi.fn>
forceRemove: ReturnType<typeof vi.fn>
removeDownloadResult: ReturnType<typeof vi.fn>
waitForEngineReady?: () => Promise<void>
} {
const addUri = vi.fn(
async (_uris: string[], options: Record<string, unknown>) =>
String(options.gid ?? overrides.addUriGid ?? 'gid-http')
)
const addTorrent = vi.fn(
async (
_metadata: string,
_uris: string[],
options: Record<string, unknown>
) => String(options.gid ?? overrides.addTorrentGid ?? 'gid-bt')
)
const addUriWithCookies = vi.fn(
async (
_uris: string[],
_cookies: unknown[],
options: Record<string, unknown>
) => String(options.gid ?? 'cookie-gid')
)
const forceRemove = vi.fn(async () => undefined)
const removeDownloadResult = vi.fn(async () => undefined)
const pick = vi.fn(
overrides.pick ?? (async (_dir: string, name: string) => name)
)
const persist = vi.fn(
overrides.persist ?? (async (id: string) => `/torrents/${id}.torrent`)
)
const set = vi.fn()
const add = vi.fn()
const remove = vi.fn(() => true)
const setReservedEngineTaskOwner = vi.fn()
const rollbackReservedEngineTaskOwner = vi.fn(() => true)
const reserveEngineTaskId = vi.fn()
const releaseEngineTaskIdReservation = vi.fn(() => true)
const retireEngineTaskIdReservation = vi.fn(() => true)
// Route the create path through a real Aria2Adapter wrapping mock RPC
// spies so handler tests cover the integration boundary. The three `on*`
// subscriptions are required by the constructor and are no-op stubs here.
const rpcClient = {
addUri,
addUriWithCookies,
addTorrent,
forceRemove,
removeDownloadResult,
onBtDownloadComplete: vi.fn(),
onDownloadComplete: vi.fn(),
onDownloadError: vi.fn(),
}
// The mock rpc only needs the subset Aria2Adapter touches on the create
// path (addUri/addTorrent + the three on* subscriptions).
const adapter = new Aria2Adapter(rpcClient as never)
adapter.setDirectResourceMetadataProfile(DIRECT_RESOURCE_METADATA_PROFILE)
if (overrides.engineFeatureReport) {
adapter.setFeatureReport(overrides.engineFeatureReport)
}
const settingsManager = {
getApp: () => ({
defaultSaveDir: overrides.defaultSaveDir ?? '/fallback',
}),
getEngine: () => ({
performanceProfile: DEFAULT_ENGINE_SETTINGS.performanceProfile,
maxConnectionPerServer: DEFAULT_ENGINE_SETTINGS.maxConnectionPerServer,
userAgent: overrides.engineUserAgent,
}),
getProxy: () => overrides.proxySettings ?? DEFAULT_PROXY_SETTINGS,
} as unknown as Deps['settingsManager']
const configuredRequestProxy = proxyToDownloadRequestOptions(
overrides.proxySettings ?? DEFAULT_PROXY_SETTINGS
)
const appliedProxySnapshot = Object.hasOwn(overrides, 'appliedProxySnapshot')
? (overrides.appliedProxySnapshot ?? null)
: (configuredRequestProxy ?? { noProxy: '' })
const finalNamePicker = { pick } as unknown as Deps['finalNamePicker']
const torrentMetaStore = {
persist,
read: vi.fn(),
remove: vi.fn(),
} as unknown as Deps['torrentMetaStore']
const taskManager = {
set,
add,
remove,
getAll: vi.fn(() => []),
getById: vi.fn(),
getByEngineTaskId: vi.fn(),
clear: vi.fn(),
setReservedEngineTaskOwner,
rollbackReservedEngineTaskOwner,
reserveEngineTaskId,
releaseEngineTaskIdReservation,
retireEngineTaskIdReservation,
} as unknown as Deps['taskManager']
const eventBus = { emit: vi.fn() }
const activityRecorder = {
recordSubmitted: vi.fn(),
recordDownloadCompleted: vi.fn(),
}
const deps: ReturnType<typeof makeDeps> = {
adapter,
settingsManager,
directResourceProxyPolicy: new AppliedDownloadProxyPolicy(
appliedProxySnapshot
),
finalNamePicker,
torrentMetaStore,
taskManager,
activityRecorder,
eventBus,
addUri,
addUriWithCookies,
addTorrent,
pick,
persist,
set,
add,
remove,
setReservedEngineTaskOwner,
rollbackReservedEngineTaskOwner,
reserveEngineTaskId,
releaseEngineTaskIdReservation,
retireEngineTaskIdReservation,
forceRemove,
removeDownloadResult,
// Spy pass-through: keeps legacy ordering assertions on eventBus.emit
// valid while the production path routes through the publisher.
publishTaskUpdate: vi.fn(() => {
eventBus.emit('event:taskUpdated', [])
}),
}
if (overrides.waitForEngineReady)
deps.waitForEngineReady = overrides.waitForEngineReady
if (overrides.prepareSaveDir) deps.prepareSaveDir = overrides.prepareSaveDir
return deps
}
function lastAddedTask(deps: { add: ReturnType<typeof vi.fn> }): DownloadTask {
expect(deps.add).toHaveBeenCalledOnce()
const call = deps.add.mock.calls[0]
return call[0] as DownloadTask
}
describe('browser direct download filenames', () => {
const url =
'https://cdn.example/c-m9021?filename=BCUninstaller_6.3.0_portable.7z'
const filename = 'BCUninstaller_6.3.0_portable.7z'
async function submit(
suggestedFilename: string,
response: Response | Response[] | Error,
requestUrl = url
) {
const deps = makeDeps()
const fetchMetadata = vi.fn(
async (_url: string | URL, _init?: RequestInit) => {
if (response instanceof Error) throw response
const next = Array.isArray(response) ? response.shift() : response
if (!next) throw new Error('unexpected metadata request')
return next
}
)
deps.directResourceValidator = new DirectResourceValidatorService(
fetchMetadata
)
const adapter = new SubmitDownloadAdapter({
getDefaultSaveDir: () => '/d',
pickName: (dir, name) => deps.finalNamePicker.pick(dir, name),
mintTaskId: () => 'bridge-filename',
})
const adapted = await adapter.adapt(
{
source: {
pageUrl: 'https://origin.example/page',
pageTitle: 'Download',
detectedAt: 1,
},
selection: {
kind: 'direct',
primary: {
url: requestUrl,
headers: {},
cookies: [],
refererPolicy: 'strict-origin-when-cross-origin',
},
},
meta: { suggestedFilename, qualityLabel: 'file' },
},
{ extensionId: 'extension', browser: 'chromium' }
)
if (adapted.kind !== 'direct') throw new Error('expected direct')
const pipeline = new DirectPipeline({
createTask: (request, _deps, options) =>
handleCreateTask(request, deps, options),
removeTask: vi.fn(),
})
await pipeline.dispatch(adapted)
return { deps, fetchMetadata }
}
it.each([
['automatic', filename],
[
'legacy Windows automatic',
String.raw`E:\Downloads\BCUninstaller_6.3.0_portable.7z`,
],
['right click', ''],
])(
'uses the same final filename for %s and manual paste',
async (_origin, hint) => {
const response = () =>
new Response(null, {
headers: {
'Content-Type': 'application/octet-stream',
'Content-Disposition': `attachment; filename="${filename}"; filename*=UTF-8''${filename}`,
},
})
const { deps, fetchMetadata } = await submit(hint, response())
expect(lastAddedTask(deps).finalName).toBe(filename)
expect(deps.addUriWithCookies).toHaveBeenCalledWith(
[url],
[],
expect.objectContaining({
out: `${filename}.motrix`,
header: expect.arrayContaining([
'Referer: https://origin.example/page',
]),
})
)
if (!hint) {
expect(fetchMetadata).toHaveBeenCalledOnce()
const init = fetchMetadata.mock.calls[0]?.[1]
expect(init?.method).toBe('GET')
expect(new Headers(init?.headers).get('referer')).toBe(
'https://origin.example/page'
)
}
const manualDeps = makeDeps()
manualDeps.directResourceValidator = new DirectResourceValidatorService(
async () => response()
)
await handleCreateTask(
{ type: 'http', uris: [url], saveDir: '/d', headers: [] },
manualDeps
)
expect(lastAddedTask(manualDeps).finalName).toBe(filename)
}
)
it('retains the URL fallback when optional filename discovery fails', async () => {
const { deps, fetchMetadata } = await submit('', new Error('offline'))
expect(fetchMetadata).toHaveBeenCalledOnce()
expect(lastAddedTask(deps).finalName).toBe('c-m9021')
expect(deps.addUriWithCookies).toHaveBeenCalledOnce()
})
it('pins the redirected URL filename for a right-click download without Content-Disposition', async () => {
const requestUrl = 'https://download.example/?product=thunderbird'
const remoteName = 'Thunderbird Setup 157.0.exe'
const finalUrl =
'https://cdn.example/releases/Thunderbird%20Setup%20157.0.exe'
const { deps, fetchMetadata } = await submit(
'',
[
new Response(null, {
status: 302,
headers: { Location: finalUrl },
}),
new Response(null, {
headers: { 'Content-Type': 'application/x-msdos-program' },
}),
],
requestUrl
)
expect(lastAddedTask(deps)).toMatchObject({
finalName: remoteName,
finalPath: `/d/${remoteName}`,
diskPath: `/d/${remoteName}.motrix`,
})
expect(fetchMetadata).toHaveBeenCalledTimes(2)
expect(String(fetchMetadata.mock.calls[1]?.[0])).toBe(finalUrl)
expect(
new Headers(fetchMetadata.mock.calls[1]?.[1]?.headers).get('referer')
).toBe('https://origin.example/page')
expect(deps.addUriWithCookies).toHaveBeenCalledWith(
[requestUrl],
[],
expect.objectContaining({ out: `${remoteName}.motrix` })
)
})
it('preserves a browser-selected name instead of replacing it with a header', async () => {
const { deps, fetchMetadata } = await submit(
'chosen.7z',
new Error('must not probe')
)
expect(lastAddedTask(deps).finalName).toBe('chosen.7z')
expect(fetchMetadata).not.toHaveBeenCalled()
})
})
describe('handleCreateTask', () => {
it('cleans and snapshots credentials before waiting and reports only safe filtering metadata', async () => {
const deps = makeDeps()
let ready!: () => void
deps.waitForEngineReady = () =>
new Promise<void>((resolve) => {
ready = resolve
})
const cookies = [
{ name: 'sid', value: 'auth-secret', domain: 'example.com' },
{ name: '', value: 'discarded-secret', domain: 'example.com' },
]
const pending = handleCreateTask(
{
type: 'http',
uris: ['https://example.com/file'],
saveDir: '/d',
headers: [],
},
deps,
{ source: 'bridge', cookies }
)
cookies[0]!.value = 'mutated\nsecret'
ready()
await pending
expect(deps.addUriWithCookies).toHaveBeenCalledWith(
expect.any(Array),
[{ name: 'sid', value: 'auth-secret', domain: 'example.com' }],
expect.any(Object)
)
expect(logWarn.mock.calls[0]?.[0]).toMatchObject({
inputCount: 2,
keptCount: 1,
discardedCount: 1,
diagnostics: [{ index: 1, field: 'name', reason: 'syntax' }],
})
expect(JSON.stringify(logWarn.mock.calls)).not.toContain('secret')
expect(JSON.stringify(lastAddedTask(deps))).not.toContain('secret')
})
it.each([
{ name: 'sid', value: 'secret\nvalue', domain: 'example.com' },
{ name: '', value: 'secret', domain: 'example.com' },
])(
'rejects cookies before creating directories, persistent intent or engine tasks',
async (cookie) => {
const deps = makeDeps()
const prepareSaveDir = vi.fn(async (directory: string) => directory)
deps.prepareSaveDir = prepareSaveDir
const persistTask = vi.fn()
deps.persistTask = persistTask
const request = {
type: 'http',
uris: ['https://example.com/file'],
saveDir: '/d',
headers: [],
}
await expect(
handleCreateTask(request, deps, { source: 'bridge', cookies: [cookie] })
).rejects.toMatchObject({
diagnostic: { index: -1, reason: 'noUsableCookies' },
})
for (const effect of [
prepareSaveDir,
persistTask,
deps.pick,
deps.reserveEngineTaskId,
deps.addUri,
deps.addUriWithCookies,
deps.forceRemove,
]) {
expect(effect).not.toHaveBeenCalled()
}
expect(JSON.stringify(logInfo.mock.calls)).not.toContain('secret')
expect(logWarn.mock.calls[0]?.[0]).toMatchObject({
diagnostic: {
index: -1,
field: expect.any(String),
reason: expect.any(String),
},
})
expect(JSON.stringify(logWarn.mock.calls)).not.toContain('secret')
}
)
it('reserves different final outputs for concurrent torrents with the same chosen name', async () => {
const deps = makeDeps()
const owners: DownloadTask[] = []
deps.add.mockImplementation((task: DownloadTask) => owners.push(task))
vi.mocked(deps.taskManager.getAll).mockImplementation(() => owners)
deps.finalNamePicker = new FinalNamePickerImpl({
exists: async () => false,
})
await Promise.all(
['first.iso', 'second.iso'].map((name) => {
const bytes = buildMinimalTorrentBytes(name, false)
return handleCreateTask(
{
type: 'bt',
payload: {
kind: 'torrent-base64',
base64: Buffer.from(bytes).toString('base64'),
},
selectedFiles: [0],
saveDir: '/d',
displayName: 'chosen.iso',
},
deps
)
})
)
expect(owners.map((task) => task.diskPath).sort()).toEqual([
'/d/chosen (1).iso',
'/d/chosen.iso',
])
expect(owners.every((task) => task.diskPath === task.finalPath)).toBe(true)
})
it('dispatches cookies only to the engine and blocks credential-free probing and replay', async () => {
const deps = makeDeps()
const probe = vi.fn()
const capture = vi.fn()
deps.directResourceValidator = { probe, capture }
const cookies = [
{ name: 'sid', value: 'COOKIE_ONLY_IN_MEMORY', domain: 'a' },
]
await handleCreateTask(
{ type: 'http', uris: ['https://a/b'], saveDir: '/d', headers: [] },
deps,
{ source: 'bridge', cookies }
)
expect(deps.addUriWithCookies).toHaveBeenCalledWith(
['https://a/b'],
cookies,
expect.objectContaining({ dir: '/d' })
)
expect(deps.addUri).not.toHaveBeenCalled()
expect(probe).not.toHaveBeenCalled()
expect(capture).not.toHaveBeenCalled()
const task = lastAddedTask(deps)
expect(task.instances[0]?.payload).toMatchObject({
directReplay: {
requestModifiers: ['cookies'],
replayability: 'requires-credentials',
},
})
expect(JSON.stringify(task)).not.toContain('COOKIE_ONLY_IN_MEMORY')
expect(JSON.stringify(logInfo.mock.calls)).not.toContain(
'COOKIE_ONLY_IN_MEMORY'
)
})
it('reuses an exact active torrent before allocating storage or an engine gid', async () => {
const bytes = makePublicTorrentFixture()
const parsed = await parseBtFileLayout(bytes)
const deps = makeDeps()
const existing = makeDownloadTask({
id: 'existing-task',
engineTaskId: 'existing-gid',
name: 'public-torrent',
kind: TaskKind.Bt,
type: TaskType.Bt,
status: TaskStatus.Seeding,
saveDir: '/d',
createdAt: 1,
updatedAt: 1,
filename: 'public-torrent',
diskPath: '/d/public-torrent',
finalPath: '/d/public-torrent',
finalName: 'public-torrent',
infoHash: parsed.infoHash,
bt: makeDefaultBtExtension({ selectedFiles: [0] }),
source: 'user',
sourceMeta: null,
instances: [
{
instanceId: 'primary:existing-task',
motrixId: 'existing-task',
gid: 'existing-gid',
phase: TaskInstancePhase.BtDownload,
status: TaskStatus.Seeding,
progress: 1,
totalBytes: 1024,
downloadedBytes: 1024,
uploadedBytes: 0,
diskPath: '/d/public-torrent',
transitionPhase: TransitionPhase.Idle,
uris: [],
uriHash: null,
payload: {},
createdAt: 1,
updatedAt: 1,
},
],
})
vi.mocked(deps.taskManager.getAll).mockReturnValue([existing])
vi.mocked(deps.taskManager.getById).mockReturnValue(existing)
await expect(
handleCreateTask(
{
type: 'bt',
payload: {
kind: 'torrent-base64',
base64: Buffer.from(bytes).toString('base64'),
},
selectedFiles: [0],
saveDir: '/d',
},
deps
)
).resolves.toEqual({
outcome: 'reused',
gid: 'existing-gid',
taskId: 'existing-task',
})
expect(deps.addTorrent).not.toHaveBeenCalled()
expect(deps.pick).not.toHaveBeenCalled()
expect(deps.persist).not.toHaveBeenCalled()
})
it('does not silently suffix orphaned torrent files without confirmation', async () => {
const bytes = makePublicTorrentFixture()
const deps = makeDeps()
deps.finalNamePicker.isTaken = vi.fn(async () => true)
await expect(
handleCreateTask(
{
type: 'bt',
payload: {
kind: 'torrent-base64',
base64: Buffer.from(bytes).toString('base64'),
},
selectedFiles: [0],
saveDir: '/d',
},
deps
)
).rejects.toMatchObject({
conflict: { reason: 'existing-files', canCreateCopy: true },
})
expect(deps.addTorrent).not.toHaveBeenCalled()
expect(deps.pick).not.toHaveBeenCalled()
expect(deps.persist).not.toHaveBeenCalled()
})
it('rejects invalid payload with AppError', async () => {
await expect(handleCreateTask({ junk: true }, makeDeps())).rejects.toThrow(
AppError
)
})
it('redacts sensitive create data while retaining safe engine diagnostics', async () => {
const secrets = {
urlToken: 'URL_SECRET_123',
authorization: 'AUTH_SECRET_456',
cookie: 'COOKIE_SECRET_789',
proxy: 'PROXY_SECRET_321',
referer: 'REFERER_SECRET_654',
cookieJar: 'COOKIE_JAR_SECRET_987',
unknownOption: 'UNKNOWN_OPTION_SECRET_159',
}
const deps = makeDeps()
await handleCreateTask(
{
type: 'http',
uris: [`https://example.com/file.zip?token=${secrets.urlToken}`],
saveDir: '/d',
filename: 'file.zip',
connections: 8,
headers: [
{
name: 'Authorization',
value: `Bearer ${secrets.authorization}`,
},
{
name: 'Cookie',
value: `session=${secrets.cookie}`,
},
],
proxy: `http://user:${secrets.proxy}@proxy.example:8080`,
},
deps,
{
extraEngineOptions: {
referer: `https://origin.example/watch?token=${secrets.referer}`,
'load-cookies': `/tmp/${secrets.cookieJar}.txt`,
'unknown-option': secrets.unknownOption,
},
}
)
const serializedLogs = JSON.stringify(logInfo.mock.calls)
for (const secret of Object.values(secrets)) {
expect(serializedLogs).not.toContain(secret)
}
const dispatch = logInfo.mock.calls.find(
(call) => call[1] === 'dispatching to engine'
)
expect(dispatch?.[0]).toMatchObject({
method: 'createDownload',
uriCount: 1,
saveDir: '/d',
filename: 'file.zip.motrix',
connections: 8,
})
const dispatchFields = dispatch?.[0] as
| { gid: string; params?: unknown; uris?: unknown; headers?: unknown }
| undefined
expect(dispatchFields?.gid).toMatch(/^[0-9a-f]{16}$/)
expect(dispatchFields).not.toHaveProperty('params')
expect(dispatchFields).toHaveProperty('uris', [
'https://example.com/file.zip?token=[redacted]',
])
expect(dispatchFields).not.toHaveProperty('headers')
expect(dispatchFields).not.toHaveProperty('proxy')
expect(dispatchFields).not.toHaveProperty('extraEngineOptions')
const taskPayload = lastAddedTask(deps).instances[0]?.payload
expect(taskPayload).toEqual({
directReplay: {
version: 1,
connections: 8,
requestModifiers: ['headers', 'proxy', 'extraEngineOptions'],
replayability: 'requires-credentials',
},
})
const serializedPayload = JSON.stringify(taskPayload)
for (const secret of Object.values(secrets)) {
expect(serializedPayload).not.toContain(secret)
}
})
it('logs plugin attribution and URI counts without exposing rewritten targets', async () => {
const rewrittenSecret = 'REWRITTEN_URI_SECRET_753'
const orchestrator = {
runBeforeCreateHttp: vi.fn().mockResolvedValue({
final: {
type: 'http' as const,
sourceUrl: 'https://original.example/file.zip',
uris: [`https://cdn.example/file.zip?signature=${rewrittenSecret}`],
saveDir: '/d',
filename: 'file.zip',
connections: undefined,
headers: [],
proxy: undefined,
createdBy: 'user' as const,
requestedAt: 0,
},
contributors: {
headers: [],
proxy: null,
uris: 'plugin-rewriter',
},
staged: { commitMetadata: vi.fn() },
}),
} as unknown as Deps['orchestrator']
const deps = makeDeps()
await handleCreateTask(
{
type: 'http',
uris: ['https://original.example/file.zip'],
saveDir: '/d',
filename: 'file.zip',
headers: [],
},
{ ...deps, orchestrator }
)
const resultLog = logInfo.mock.calls.find(
(call) => call[1] === 'beforeCreate hook chain result'
)
expect(resultLog?.[0]).toMatchObject({
rewrittenUriCount: 1,
contributors: { uris: 'plugin-rewriter' },
})
const task = lastAddedTask(deps)
expect(task.uris).toEqual([
`https://cdn.example/file.zip?signature=${rewrittenSecret}`,
])
expect(task.instances[0]?.uris).toEqual(task.uris)
expect(task.instances[0]?.payload).toEqual({
directReplay: {
version: 1,
requestModifiers: [],
replayability: 'uri-only',
},
})
expect(JSON.stringify(logInfo.mock.calls)).not.toContain(rewrittenSecret)
})
it('dispatches http request via rpcClient.addUri', async () => {
const deps = makeDeps({ addUriGid: 'gid-x' })
const result = await handleCreateTask(
{
type: 'http',
uris: ['https://a/b'],
saveDir: '/d',
headers: [],
},
deps
)
expect(result.gid).toMatch(/^[0-9a-f]{16}$/)
expect(typeof result.taskId).toBe('string')
expect(result.taskId).not.toBe(result.gid)
expect(deps.addUri).toHaveBeenCalledWith(
['https://a/b'],
expect.objectContaining({ dir: '/d' })
)
expect(lastAddedTask(deps).instances[0]?.payload).toEqual({
directReplay: {
version: 1,
requestModifiers: [],
replayability: 'uri-only',
},
})
})
it('persists a captured validator for a public direct download', async () => {
const deps = makeDeps()
const resourceValidator = {
kind: 'strong-etag' as const,
value: '"release-v1"',
contentLength: 4096,
capturedAt: 7,
}
const capture = vi.fn().mockResolvedValue(resourceValidator)
deps.directResourceValidator = { capture }
await handleCreateTask(httpRequest(), deps)
expect(capture).toHaveBeenCalledWith('https://a/b', {})
expect(lastAddedTask(deps).instances[0]?.payload).toEqual({
directReplay: {
version: 1,
requestModifiers: [],
replayability: 'uri-only',
resourceValidator,
},
})
})
it('passes the effective engine User-Agent to metadata discovery', async () => {
const deps = makeDeps({ engineUserAgent: 'Motrix/Test' })
const probe = vi.fn(async () => {
vi.spyOn(deps.settingsManager, 'getEngine').mockReturnValue({
...DEFAULT_ENGINE_SETTINGS,
userAgent: 'Motrix/Newer',
})
return { filename: null, validator: null }
})
deps.directResourceValidator = { capture: vi.fn(), probe }
await handleCreateTask(
{
type: 'http',
uris: ['https://example.com/stable'],
saveDir: '/d',
headers: [],
},
deps
)
expect(probe).toHaveBeenCalledWith('https://example.com/stable', {
userAgent: 'Motrix/Test',
})
expect(deps.addUri).toHaveBeenCalledWith(
['https://example.com/stable'],
expect.objectContaining({ 'user-agent': 'Motrix/Test' })
)
})
it('skips metadata when a concrete aria2 lacks mirrored header features', async () => {
const deps = makeDeps({
engineFeatureReport: {
version: '1.37.0',
features: ['GZip'],
hasSqlitePersistence: false,
hasBtSeedUnverified: false,
hasBtSaveMetadata: false,
hasMoveStorage: false,
},
})
const probe = vi.fn()
const capture = vi.fn()
deps.directResourceValidator = { probe, capture }
await handleCreateTask(
{
type: 'http',
uris: ['https://example.com/stable'],
saveDir: '/d',
headers: [],
},
deps
)
expect(probe).not.toHaveBeenCalled()
expect(capture).not.toHaveBeenCalled()
expect(deps.addUri).toHaveBeenCalledOnce()
})
it('preserves unsafe ambient aria2 behavior and records it as non-replayable', async () => {
const deps = makeDeps()
;(deps.adapter as Aria2Adapter).setDirectResourceMetadataProfile(null)
const probe = vi.fn()
const capture = vi.fn()
deps.directResourceValidator = { probe, capture }
await handleCreateTask(httpRequest(), deps)
expect(probe).not.toHaveBeenCalled()
expect(capture).not.toHaveBeenCalled()
expect(lastAddedTask(deps).instances[0]?.payload).toEqual({
directReplay: {
version: 1,
requestModifiers: ['engineGlobalOptions'],
replayability: 'requires-credentials',
},
})
const options = deps.addUri.mock.calls[0]?.[1]
expect(options?.header).toEqual(['Accept: */*'])
expect(options).not.toHaveProperty('no-netrc')
})
it('skips metadata when passthrough engine options change HTTP semantics', async () => {
const deps = makeDeps()
const probe = vi.fn()
const capture = vi.fn()
deps.directResourceValidator = { capture, probe }
await handleCreateTask(
{
type: 'http',
uris: ['https://example.com/stable'],
saveDir: '/d',
headers: [],
},
deps,
{ extraEngineOptions: { referer: 'https://origin.example/' } }
)
expect(probe).not.toHaveBeenCalled()
expect(capture).not.toHaveBeenCalled()
expect(deps.addUri).toHaveBeenCalledOnce()
})
it('skips metadata when a task header cannot be represented by Fetch', async () => {
const deps = makeDeps()
const probe = vi.fn()
const capture = vi.fn()
deps.directResourceValidator = { capture, probe }
await handleCreateTask(
{
type: 'http',
uris: ['https://example.com/stable'],
saveDir: '/d',
headers: [{ name: 'Host', value: 'other.example' }],
},
deps
)
expect(probe).not.toHaveBeenCalled()
expect(capture).not.toHaveBeenCalled()
expect(deps.addUri).toHaveBeenCalledOnce()
})
it('does not probe a direct request that depends on credentials', async () => {
const deps = makeDeps()
const capture = vi.fn()
deps.directResourceValidator = { capture }
await handleCreateTask(
{
...httpRequest(),
headers: [{ name: 'Authorization', value: 'Bearer secret' }],
},
deps
)
expect(capture).not.toHaveBeenCalled()
expect(lastAddedTask(deps).instances[0]?.payload).toEqual({
directReplay: {
version: 1,
requestModifiers: ['headers'],
replayability: 'requires-credentials',
},
})
})
it('does not attach one validator to an ambiguous mirror set', async () => {
const deps = makeDeps()
const capture = vi.fn()
deps.directResourceValidator = { capture }
await handleCreateTask(
{
...httpRequest(),
uris: [
'https://mirror-a.example/file',
'https://mirror-b.example/file',
],
},
deps
)
expect(capture).not.toHaveBeenCalled()
expect(
lastAddedTask(deps).instances[0]?.payload.directReplay
).not.toHaveProperty('resourceValidator')
})
it('uses the host-prepared save directory for task and aria2 paths', async () => {
const prepareSaveDir = vi.fn(async () => '/downloads/canonical')
const deps = makeDeps({ prepareSaveDir })
await handleCreateTask(httpRequest(), deps)
expect(prepareSaveDir).toHaveBeenCalledWith('/d')
expect(deps.pick).toHaveBeenCalledWith('/downloads/canonical', 'b')
expect(deps.addUri).toHaveBeenCalledWith(
['https://a/b'],
expect.objectContaining({ dir: '/downloads/canonical' })
)
expect(lastAddedTask(deps).saveDir).toBe('/downloads/canonical')
})
it('records one submitted event after canonical registration and before TaskUpdated', async () => {
const deps = makeDeps({ addUriGid: 'gid-activity' })
const result = await handleCreateTask(
{
type: 'http',
uris: ['https://example.com/file.zip'],
saveDir: '/d',
headers: [],
},
deps
)
const task = lastAddedTask(deps)
const recordSubmitted = deps.activityRecorder.recordSubmitted as ReturnType<
typeof vi.fn
>
const emit = deps.eventBus.emit as ReturnType<typeof vi.fn>
expect(recordSubmitted).toHaveBeenCalledOnce()
expect(recordSubmitted).toHaveBeenCalledWith({
taskId: result.taskId,
occurredAt: task.createdAt,
})
expect(deps.add.mock.invocationCallOrder[0]).toBeLessThan(
recordSubmitted.mock.invocationCallOrder[0] ?? Number.POSITIVE_INFINITY
)
expect(recordSubmitted.mock.invocationCallOrder[0]).toBeLessThan(
emit.mock.invocationCallOrder[0] ?? Number.POSITIVE_INFINITY
)
})
it('persists the parent and records Added before publishing the task', async () => {
const deps = makeDeps({ addUriGid: 'gid-durable' })
const order: string[] = []
deps.add.mockImplementation(() => {
order.push('publish')
})
const persistTask = vi.fn(async () => {
order.push('persist-parent')
})
const parentTaskCreated = vi.fn(
async (
_task: DownloadTask,
persistParent: () => void | Promise<void>
) => {
await persistParent()
order.push('record-added')
}
)
await handleCreateTask(httpRequest(), {
...deps,
persistTask,
parentTaskCreated,
})
expect(order).toEqual(['persist-parent', 'record-added', 'publish'])
})
it('dispatches bt torrent via rpcClient.addTorrent', async () => {
const deps = makeDeps({ addTorrentGid: 'gid-bt' })
const result = await handleCreateTask(
{
type: 'bt',
payload: { kind: 'torrent-base64', base64: sampleTorrentBase64 },
selectedFiles: [0],
saveDir: '/d',
displayName: 'mytorrent',
},
deps
)
expect(result.gid).toMatch(/^[0-9a-f]{16}$/)
expect(typeof result.taskId).toBe('string')
expect(deps.addTorrent).toHaveBeenCalledWith(
sampleTorrentBase64,
[],
expect.objectContaining({ 'select-file': '1' })
)
})
it('extracts torrent info.name when displayName is absent', async () => {
// Hand-rolled minimal bencode torrent: single file "x", name = the
// given string. Shape: d4:infod6:lengthi1024e4:name<N>:<name>
// 12:piece lengthi16384e6:pieces20:<20 zero bytes>ee
function buildMinimalTorrent(name: string): Uint8Array {
const nameField = `4:name${Buffer.byteLength(name, 'utf8')}:${name}`
const prefix = Buffer.from(
`d4:infod6:lengthi1024e${nameField}12:piece lengthi16384e6:pieces20:`,
'utf8'
)
const pieces = Buffer.alloc(20)
const suffix = Buffer.from('ee', 'utf8')
return new Uint8Array(Buffer.concat([prefix, pieces, suffix]))
}
const deps = makeDeps({ addTorrentGid: 'gid-bt' })
const bytes = buildMinimalTorrent('ubuntu-25.10-desktop-amd64.iso')
await handleCreateTask(
{
type: 'bt',
payload: {
kind: 'torrent-base64',
base64: Buffer.from(bytes).toString('base64'),
},
selectedFiles: [0],
saveDir: '/d',
// no displayName — should derive from info.name
},
deps
)
const task = lastAddedTask(deps)
expect(task.finalName).toBe('ubuntu-25.10-desktop-amd64.iso')
expect(task.diskPath).toBe(task.finalPath)
expect(task.instances[0].payload.btStorageLayout).toMatchObject({
version: 2,
strategy: 'direct',
finalized: false,
torrentRootName: 'ubuntu-25.10-desktop-amd64.iso',
multiFile: false,
})
const [, , options] = deps.addTorrent.mock.calls[0]
expect(options).toMatchObject({
dir: `${task.torrentMetaPath}.state`,
'index-out': ['1=/d/ubuntu-25.10-desktop-amd64.iso'],
})
expect(options).not.toHaveProperty('bt-prioritize-piece')
})
it('enables preview piece priority for a video-only torrent', async () => {
const deps = makeDeps({ addTorrentGid: 'gid-bt' })
const bytes = buildMinimalTorrentBytes('Movie.MP4', false)
await handleCreateTask(
{
type: 'bt',
payload: {
kind: 'torrent-base64',
base64: Buffer.from(bytes).toString('base64'),
},
selectedFiles: [0],
saveDir: '/d',
},
deps
)
const [, , options] = deps.addTorrent.mock.calls[0]
expect(options['bt-prioritize-piece']).toBe('head=10M,tail=10M')
})
it.each([
{ base64: 'AAAA', code: ErrorCode.TorrentParseFailed },
{
base64: Buffer.from(
encode({
info: {
name: 'v2',
'meta version': 2,
'piece length': 16384,
'file tree': { empty: { '': { length: 0 } } },
},
})
).toString('base64'),
code: ErrorCode.EngineFeatureUnavailable,
},
])(
'rejects unsupported or invalid metadata before allocating engine/storage state ($code)',
async ({ base64, code }) => {
const deps = makeDeps()
await expect(
handleCreateTask(
{
type: 'bt',
payload: { kind: 'torrent-base64', base64 },
selectedFiles: [0],
saveDir: '/d',
},
deps
)
).rejects.toMatchObject({ code })
expect(deps.addTorrent).not.toHaveBeenCalled()
expect(deps.add).not.toHaveBeenCalled()
expect(deps.reserveEngineTaskId).not.toHaveBeenCalled()
expect(deps.persist).not.toHaveBeenCalled()
expect(mkdirMock).not.toHaveBeenCalled()
}
)
it('rejects a parseable torrent with an unsafe root path', async () => {
const deps = makeDeps({ addTorrentGid: 'gid-bt' })
const bytes = buildMinimalTorrentBytes('..', false)
await expect(
handleCreateTask(
{
type: 'bt',
payload: {
kind: 'torrent-base64',
base64: Buffer.from(bytes).toString('base64'),
},
selectedFiles: [0],
saveDir: '/d',
},
deps
)
).rejects.toMatchObject({ code: ErrorCode.TorrentParseFailed })
expect(deps.addTorrent).not.toHaveBeenCalled()
})
it('dispatches magnet via rpcClient.addUri', async () => {
const deps = makeDeps({ addUriGid: 'gid-magnet' })
const result = await handleCreateTask(
{
type: 'bt',
payload: {
kind: 'magnet',
uri: 'magnet:?xt=urn:btih:a03e3f9a05341aa336e9d9d3f06b33cddafe0bdc',
},
dlLimit: 1_000_000,
ulLimit: 512_000,
selectedFiles: [0],
saveDir: '/d',
displayName: 'mag-name',
},
deps
)
expect(result.gid).toMatch(/^[0-9a-f]{16}$/)
expect(typeof result.taskId).toBe('string')
expect(deps.addUri).toHaveBeenCalledWith(
['magnet:?xt=urn:btih:a03e3f9a05341aa336e9d9d3f06b33cddafe0bdc'],
expect.any(Object)
)
const [, options] = deps.addUri.mock.calls[0]
expect(options).toMatchObject({
'max-download-limit': '1000000',
'max-upload-limit': '512000',
})
expect(options).not.toHaveProperty('bt-prioritize-piece')
})
})
describe('handleCreateTask download paths', () => {
it('HTTP task: taskManager receives task with diskPath=.motrix, finalPath clean', async () => {
const deps = makeDeps()
await handleCreateTask(
{
type: 'http',
uris: ['https://example.com/foo.mp4'],
saveDir: '/d',
filename: 'foo.mp4',
headers: [],
},
deps
)
const task = lastAddedTask(deps)
expect(task.diskPath).toBe('/d/foo.mp4.motrix')
expect(task.finalPath).toBe('/d/foo.mp4')
expect(task.finalName).toBe('foo.mp4')
expect(task.filename).toBe('foo.mp4')
expect(task.saveDir).toBe('/d')
expect(task.transitionPhase).toBe(TransitionPhase.Idle)
expect(task.type).toBe(TaskType.Http)
expect(task.engineTaskId).toMatch(/^[0-9a-f]{16}$/)
expect(task.torrentMetaPath).toBeNull()
})
it('HTTP task: overrides aria2 `out` to <finalName>.motrix inside the saveDir', async () => {
const deps = makeDeps()
await handleCreateTask(
{
type: 'http',
uris: ['https://example.com/foo.mp4'],
saveDir: '/d',
filename: 'foo.mp4',
headers: [],
},
deps
)
const [, options] = deps.addUri.mock.calls[0]
expect(options.dir).toBe('/d')
expect(options.out).toBe('foo.mp4.motrix')
})
it('validated BT task: persists the final directory without a temporary output', async () => {
const deps = makeDeps({
persist: async (id) => `/torrents/${id}.torrent`,
})
await handleCreateTask(
{
type: 'bt',
payload: { kind: 'torrent-base64', base64: sampleTorrentBase64 },
selectedFiles: [0],
saveDir: '/d',
displayName: 'mytorrent',
torrentBytes: storageTorrent([
{ name: 'a', data: 'a' },
{ name: 'b', data: 'b' },
{ name: 'c', data: 'c' },
]),
},
deps
)
const task = lastAddedTask(deps)
expect(task.diskPath).toBe(task.finalPath)
expect(task.diskPath).toBe(task.finalPath)
expect(task.instances[0].diskPath).toBe(task.diskPath)
expect(task.instances[0].payload.btStorageLayout).toMatchObject({
version: 2,
strategy: 'direct',
torrentRootName: 'bundle',
})
expect(task.finalPath).toBe('/d/mytorrent')
expect(task.finalName).toBe('mytorrent')
expect(task.type).toBe(TaskType.Bt)
expect(task.torrentMetaPath).toBe(`/torrents/${task.id}.torrent`)
})
it('validated BT task: aria2 uses explicit output mappings in the final directory', async () => {
const deps = makeDeps()
await handleCreateTask(
{
type: 'bt',
payload: { kind: 'torrent-base64', base64: sampleTorrentBase64 },
selectedFiles: [0],
saveDir: '/d',
displayName: 'mytorrent',
},
deps
)
const [, , options] = deps.addTorrent.mock.calls[0]
expect(options.dir).toBe(`${lastAddedTask(deps).torrentMetaPath}.state`)
expect(options.out).toBeUndefined()
expect(options['index-out']).toEqual([
'1=/d/mytorrent/a',
'2=/d/mytorrent/b',
'3=/d/mytorrent/c',
])
})
it('Magnet task: derives name from dn= when no displayName provided', async () => {
const deps = makeDeps({ addUriGid: 'gid-m' })
await handleCreateTask(
{
type: 'bt',
payload: {
kind: 'magnet',
uri: 'magnet:?xt=urn:btih:a03e3f9a05341aa336e9d9d3f06b33cddafe0bdc&dn=Ubuntu%2024.04',
},
selectedFiles: [0],
saveDir: '/d',
},
deps
)
const task = lastAddedTask(deps)
expect(task.finalName).toBe('Ubuntu 24.04')
expect(task.diskPath).toBe(task.finalPath)
expect(task.instances[0].diskPath).toBe(task.diskPath)
expect(deps.addUri.mock.calls[0][1].dir).toBe(task.diskPath)
expect(task.type).toBe(TaskType.Magnet)
// magnet payloads never persist torrentBytes
expect(task.torrentMetaPath).toBeNull()
expect(deps.persist).not.toHaveBeenCalled()
})
it('HTTP task: falls back to URI basename when filename absent', async () => {
const deps = makeDeps()
await handleCreateTask(
{
type: 'http',
uris: ['https://example.com/path/archive.tar.gz'],
saveDir: '/d',
headers: [],
},
deps
)
expect(deps.pick).toHaveBeenCalledWith('/d', 'archive.tar.gz')
const task = lastAddedTask(deps)
expect(task.finalName).toBe('archive.tar.gz')
})
it('HTTP task: resolves a stable URL from final request params and prefers its explicit proxy', async () => {
const deps = makeDeps({
proxySettings: {
...DEFAULT_PROXY_SETTINGS,
enabled: true,
host: 'global-proxy.example',
port: 3128,
bypass: ['localhost'],
scopes: { ...DEFAULT_PROXY_SETTINGS.scopes, download: true },
},
})
const probe = vi.fn().mockResolvedValue({
filename: '../../VSCodeUserSetup-x64-1.103.2.exe',
validator: null,
})
const capture = vi.fn().mockResolvedValue(null)
deps.directResourceValidator = { capture, probe }
await handleCreateTask(
{
type: 'http',
uris: [
'https://update.code.visualstudio.com/latest/win32-x64-user/stable',
],
saveDir: '/d',
headers: [{ name: 'User-Agent', value: 'Motrix test' }],
proxy: 'http://proxy.example:8080',
},
deps
)
expect(probe).toHaveBeenCalledWith(
'https://update.code.visualstudio.com/latest/win32-x64-user/stable',
{
headers: { 'User-Agent': 'Motrix test' },
proxy: 'http://proxy.example:8080',
noProxy: 'localhost',
}
)
expect(deps.pick).toHaveBeenCalledWith(
'/d',
'VSCodeUserSetup-x64-1.103.2.exe'
)
expect(deps.addUri).toHaveBeenCalledWith(
['https://update.code.visualstudio.com/latest/win32-x64-user/stable'],
expect.objectContaining({
dir: '/d',
out: 'VSCodeUserSetup-x64-1.103.2.exe.motrix',
})
)
expect(lastAddedTask(deps).finalName).toBe(
'VSCodeUserSetup-x64-1.103.2.exe'
)
expect(capture).not.toHaveBeenCalled()
})
it('HTTP task: rejects an explicit SOCKS proxy before metadata or durable intent', async () => {
const deps = makeDeps()
const probe = vi.fn()
const capture = vi.fn()
deps.directResourceValidator = { capture, probe }
await expect(
handleCreateTask(
{
type: 'http',
uris: ['https://downloads.example/stable'],
saveDir: '/d',
headers: [{ name: 'Authorization', value: 'Bearer secret' }],
proxy: 'socks5://proxy.example:1080',
},
deps
)
).rejects.toThrow('Task proxy must use aria2-compatible HTTP or HTTPS')
expect(probe).not.toHaveBeenCalled()
expect(capture).not.toHaveBeenCalled()
expect(deps.addUri).not.toHaveBeenCalled()
expect(deps.reserveEngineTaskId).not.toHaveBeenCalled()
})
it('HTTP task: downloads through legacy IPv4 proxy syntax without metadata I/O', async () => {
const deps = makeDeps()
const probe = vi.fn()
const capture = vi.fn()
deps.directResourceValidator = { capture, probe }
await handleCreateTask(
{
type: 'http',
uris: ['https://downloads.example/stable'],
saveDir: '/d',
headers: [],
proxy: 'http://user:[email protected]:8080',
},
deps
)
expect(probe).not.toHaveBeenCalled()
expect(capture).not.toHaveBeenCalled()
expect(deps.addUri).toHaveBeenCalledWith(
['https://downloads.example/stable'],
expect.objectContaining({
'all-proxy': 'http://127.1:8080',
'all-proxy-user': 'user',
'all-proxy-passwd': 'pass',
})
)
})
it('HTTP task: never probes through malformed task proxy syntax', async () => {
const deps = makeDeps()
const probe = vi.fn()
const capture = vi.fn()
deps.directResourceValidator = { capture, probe }
await expect(
handleCreateTask(
{
type: 'http',
uris: ['https://downloads.example/stable'],
saveDir: '/d',
headers: [{ name: 'Authorization', value: 'Bearer secret' }],
proxy: 'http://proxy.example:8080/not-an-authority',
},
deps
)
).rejects.toThrow('Task proxy must use aria2-compatible HTTP or HTTPS')
expect(probe).not.toHaveBeenCalled()
expect(capture).not.toHaveBeenCalled()
expect(deps.addUri).not.toHaveBeenCalled()
expect(deps.reserveEngineTaskId).not.toHaveBeenCalled()
})
it('HTTP task: rejects control characters decoded from proxy credentials before metadata or durable intent', async () => {
const deps = makeDeps()
const probe = vi.fn()
const capture = vi.fn()
deps.directResourceValidator = { capture, probe }
await expect(
handleCreateTask(
{
type: 'http',
uris: ['https://downloads.example/stable'],
saveDir: '/d',
headers: [],
proxy:
'http://user%0Ahttp-proxy%3Dhttp%3A%2F%2Fevil:[email protected]:8080',
},
deps
)
).rejects.toThrow('Task proxy must use aria2-compatible HTTP or HTTPS')
expect(probe).not.toHaveBeenCalled()
expect(capture).not.toHaveBeenCalled()
expect(deps.addUri).not.toHaveBeenCalled()
expect(deps.reserveEngineTaskId).not.toHaveBeenCalled()
})
it('HTTP task: skips metadata when the applied route is unavailable even with an explicit proxy', async () => {
const deps = makeDeps({ appliedProxySnapshot: null })
const probe = vi.fn()
const capture = vi.fn()
deps.directResourceValidator = { capture, probe }
await handleCreateTask(
{
type: 'http',
uris: ['https://downloads.example/stable'],
saveDir: '/d',
headers: [{ name: 'Authorization', value: 'Bearer secret' }],
proxy: 'http://task-proxy.example:8080',
},
deps
)
expect(probe).not.toHaveBeenCalled()
expect(capture).not.toHaveBeenCalled()
expect(deps.addUri).toHaveBeenCalledOnce()
})
it('HTTP task: uses the applied snapshot instead of newer settings for metadata', async () => {
const deps = makeDeps({
proxySettings: {
...DEFAULT_PROXY_SETTINGS,
enabled: true,
host: 'new-unapplied.example',
port: 9000,
scopes: { ...DEFAULT_PROXY_SETTINGS.scopes, download: true },
},
appliedProxySnapshot: {
proxy: 'http://old-applied.example:8080',
noProxy: '.internal',
},
})
const capture = vi.fn().mockResolvedValue(null)
deps.directResourceValidator = { capture }
await handleCreateTask(httpRequest(), deps)
expect(capture).toHaveBeenCalledWith('https://a/b', {
proxy: 'http://old-applied.example:8080',
noProxy: '.internal',
})
})
it('HTTP task: aborts before addUri when restart invalidates its metadata lease', async () => {
const deps = makeDeps()
let finishCapture: (() => void) | undefined
const captureGate = new Promise<void>((resolve) => {
finishCapture = resolve
})
const capture = vi.fn(async () => {
await captureGate
return null
})
deps.directResourceValidator = { capture }
deps.assertEngineReady = vi.fn()
const creating = handleCreateTask(httpRequest(), deps)
await vi.waitFor(() => expect(capture).toHaveBeenCalledOnce())
;(
deps.directResourceProxyPolicy as AppliedDownloadProxyPolicy
).markUnavailable()
finishCapture?.()
await expect(creating).rejects.toThrow(
'applied download proxy policy changed'
)
expect(deps.addUri).not.toHaveBeenCalled()
})
it('HTTP task: an explicit filename skips discovery but still captures a URI-only validator once', async () => {
const deps = makeDeps({
proxySettings: {
...DEFAULT_PROXY_SETTINGS,
enabled: true,
host: 'proxy.example',
port: 8080,
bypass: ['localhost'],
scopes: { ...DEFAULT_PROXY_SETTINGS.scopes, download: true },
},
})
const probe = vi.fn()
const capture = vi.fn().mockResolvedValue({
kind: 'strong-etag' as const,
value: '"proxied-release"',
capturedAt: 9,
})
deps.directResourceValidator = {
capture,
probe,
}
await handleCreateTask(
{
type: 'http',
uris: [
'https://update.code.visualstudio.com/latest/win32-x64-user/stable',
],
saveDir: '/d',
filename: 'chosen.exe',
headers: [],
},
deps
)
expect(probe).not.toHaveBeenCalled()
expect(capture).toHaveBeenCalledWith(
'https://update.code.visualstudio.com/latest/win32-x64-user/stable',
{
proxy: 'http://proxy.example:8080',
noProxy: 'localhost',
}
)
expect(deps.pick).toHaveBeenCalledWith('/d', 'chosen.exe')
expect(lastAddedTask(deps).instances[0]?.payload).toEqual({
directReplay: {
version: 1,
requestModifiers: [],
replayability: 'uri-only',
resourceValidator: {
kind: 'strong-etag',
value: '"proxied-release"',
capturedAt: 9,
},
},
})
})
it.each([
['download.php', 'release.zip'],
['api/file.bin', 'real-installer.exe'],
])(
'HTTP task: probes a single URI ending in %s despite its apparent extension',
async (uriPath, remoteName) => {
const deps = makeDeps()
const probe = vi.fn().mockResolvedValue({
filename: remoteName,
validator: null,
})
deps.directResourceValidator = {
capture: vi.fn(),
probe,
}
await handleCreateTask(
{
type: 'http',
uris: [`https://example.com/${uriPath}`],
saveDir: '/d',
headers: [],
},
deps
)
expect(probe).toHaveBeenCalledOnce()
expect(deps.pick).toHaveBeenLastCalledWith('/d', remoteName)
expect(lastAddedTask(deps).finalName).toBe(remoteName)
}
)
it.each([
['ASCII', `${'release'.repeat(80)}.zip`],
['Chinese', `${'下载文件'.repeat(80)}.zip`],
['emoji', `${'📦🚀'.repeat(80)}.zip`],
])(
'HTTP task: keeps a deduplicated long %s filename within the filesystem byte limit',
async (_label, remoteName) => {
const safeRemoteName = sanitizeRemoteFilename(remoteName) as string
const picker = new FinalNamePickerImpl({
exists: vi.fn(
async (candidate) => candidate === `/d/${safeRemoteName}`
),
})
const deps = makeDeps({
pick: (dir, name) => picker.pick(dir, name),
})
deps.directResourceValidator = {
capture: vi.fn(),
probe: vi.fn().mockResolvedValue({
filename: remoteName,
validator: null,
}),
}
await handleCreateTask(
{
type: 'http',
uris: ['https://example.com/stable'],
saveDir: '/d',
headers: [],
},
deps
)
const task = lastAddedTask(deps)
expect(task.finalName).toMatch(/ \(1\)\.zip$/)
expect(
Buffer.byteLength(`${task.finalName}.motrix`, 'utf8')
).toBeLessThanOrEqual(255)
expect(Buffer.from(task.finalName, 'utf8').toString('utf8')).toBe(
task.finalName
)
}
)
it('HTTP task: reuses the filename probe validator without a second HEAD', async () => {
const deps = makeDeps()
const resourceValidator = {
kind: 'strong-etag' as const,
value: '"release-v1"',
contentLength: 4096,
capturedAt: 7,
}
const probe = vi.fn().mockResolvedValue({
filename: 'release.zip',
validator: resourceValidator,
})
const capture = vi.fn()
deps.directResourceValidator = { capture, probe }
await handleCreateTask(
{
type: 'http',
uris: ['https://example.com/stable'],
saveDir: '/d',
headers: [],
},
deps
)
expect(probe).toHaveBeenCalledOnce()
expect(capture).not.toHaveBeenCalled()
expect(lastAddedTask(deps).instances[0]?.payload).toEqual({
directReplay: {
version: 1,
requestModifiers: [],
replayability: 'uri-only',
resourceValidator,
},
})
})
it('HTTP task: persists a validator observed through the global download proxy without proxy credentials', async () => {
const deps = makeDeps({
proxySettings: {
...DEFAULT_PROXY_SETTINGS,
enabled: true,
host: 'proxy.example',
port: 8080,
user: 'proxy-user',
password: 'proxy-pass',
bypass: ['localhost', '*.internal'],
scopes: { ...DEFAULT_PROXY_SETTINGS.scopes, download: true },
},
})
const probe = vi.fn().mockResolvedValue({
filename: 'release.zip',
validator: {
kind: 'strong-etag' as const,
value: '"proxied-release"',
capturedAt: 8,
},
})
const capture = vi.fn()
deps.directResourceValidator = { capture, probe }
await handleCreateTask(
{
type: 'http',
uris: ['https://example.com/download.php'],
saveDir: '/d',
headers: [],
},
deps
)
expect(probe).toHaveBeenCalledWith('https://example.com/download.php', {
proxy: 'http://proxy-user:[email protected]:8080',
noProxy: 'localhost,*.internal',
})
expect(capture).not.toHaveBeenCalled()
const payload = lastAddedTask(deps).instances[0]?.payload
expect(payload).toEqual({
directReplay: {
version: 1,
requestModifiers: [],
replayability: 'uri-only',
resourceValidator: {
kind: 'strong-etag',
value: '"proxied-release"',
capturedAt: 8,
},
},
})
expect(JSON.stringify(payload)).not.toContain('proxy-user')
expect(JSON.stringify(payload)).not.toContain('proxy-pass')
expect(JSON.stringify(payload)).not.toContain('proxy.example')
})
it('HTTP task: metadata failure logs no signed URL or credential value', async () => {
const deps = makeDeps()
deps.directResourceValidator = {
capture: vi.fn(),
probe: vi
.fn()
.mockRejectedValue(
new Error(
'https://example.com/stable?token=URL_SECRET Authorization=AUTH_SECRET'
)
),
}
await handleCreateTask(
{
type: 'http',
uris: ['https://example.com/stable?token=URL_SECRET'],
saveDir: '/d',
headers: [{ name: 'Authorization', value: 'Bearer AUTH_SECRET' }],
},
deps
)
const serializedLogs = JSON.stringify({
debug: logDebug.mock.calls,
info: logInfo.mock.calls,
warn: logWarn.mock.calls,
error: logError.mock.calls,
})
expect(serializedLogs).not.toContain('URL_SECRET')
expect(serializedLogs).not.toContain('AUTH_SECRET')
expect(serializedLogs).toContain('example.com')
expect(lastAddedTask(deps).finalName).toBe('stable')
})
it('delegates to FinalNamePicker and uses returned dedup name', async () => {
const deps = makeDeps({ pick: async () => 'foo (1).mp4' })
await handleCreateTask(
{
type: 'http',
uris: ['https://example.com/foo.mp4'],
saveDir: '/d',
filename: 'foo.mp4',
headers: [],
},
deps
)
expect(deps.pick).toHaveBeenCalledWith('/d', 'foo.mp4')
const task = lastAddedTask(deps)
expect(task.finalName).toBe('foo (1).mp4')
expect(task.diskPath).toBe('/d/foo (1).mp4.motrix')
expect(task.finalPath).toBe('/d/foo (1).mp4')
})
it('wraps TorrentMetaStore failure in TaskCreateTorrentMetaFailed', async () => {
const deps = makeDeps({
persist: async () => {
throw new Error('disk full')
},
})
try {
await handleCreateTask(
{
type: 'bt',
payload: { kind: 'torrent-base64', base64: sampleTorrentBase64 },
selectedFiles: [0],
saveDir: '/d',
displayName: 'mytorrent',
},
deps
)
expect.unreachable('should have thrown')
} catch (err) {
expect(err).toBeInstanceOf(AppError)
expect((err as AppError).code).toBe(ErrorCode.TaskCreateTorrentMetaFailed)
}
// engine is not called when meta persistence fails
expect(deps.addTorrent).not.toHaveBeenCalled()
expect(deps.add).not.toHaveBeenCalled()
})
it('propagates FinalNamePicker.pick rejection (TaskCreateDedupExhausted)', async () => {
const deps = makeDeps({
pick: async () => {
throw new AppError(
ErrorCode.TaskCreateDedupExhausted,
'too many collisions'
)
},
})
await expect(
handleCreateTask(
{
type: 'http',
uris: ['https://a/b'],
saveDir: '/d',
filename: 'foo.mp4',
headers: [],
},
deps
)
).rejects.toMatchObject({ code: ErrorCode.TaskCreateDedupExhausted })
expect(deps.addUri).not.toHaveBeenCalled()
expect(deps.add).not.toHaveBeenCalled()
})
})
describe('handleCreateTask mkdir target by task type', () => {
it('dispatches a download in an existing volume root without trying to create it', async () => {
const saveDir = path.parse(path.resolve('/')).root
fsStub.stat.mockResolvedValue({ isDirectory: () => true })
// Model Windows mkdir on a drive root, even on a POSIX test host.
mkdirMock.mockRejectedValueOnce(
Object.assign(new Error(`EPERM: mkdir '${saveDir}'`), { code: 'EPERM' })
)
const deps = makeDeps()
await handleCreateTask(
{ ...httpRequest(), saveDir, filename: 'archive.zip' },
deps
)
expect(deps.addUri).toHaveBeenCalledWith(
['https://a/b'],
expect.objectContaining({ dir: saveDir, out: 'archive.zip.motrix' })
)
expect(deps.add).toHaveBeenCalledOnce()
expect(logWarn).not.toHaveBeenCalled()
expect(mkdirMock).not.toHaveBeenCalled()
})
// BT/Magnet: `diskPath` is the container directory aria2 populates,
// and aria2.addTorrent writes `<sha1>.torrent` inside it at add time
// — pre-creating the dir is required to keep that write from
// silently failing (which would skip the sqlite3 task row and hit a
// FK violation on the next pause).
it('BT task: creates the engine state directory before dispatch', async () => {
const deps = makeDeps()
await handleCreateTask(
{
type: 'bt',
payload: { kind: 'torrent-base64', base64: sampleTorrentBase64 },
selectedFiles: [0],
saveDir: '/d',
displayName: 'mytorrent',
},
deps
)
expect(mkdirMock).toHaveBeenCalledWith(
`${lastAddedTask(deps).torrentMetaPath}.state`,
{ recursive: true }
)
expect(mkdirMock).toHaveBeenCalledTimes(2)
expect(mkdirMock).toHaveBeenNthCalledWith(
2,
`${lastAddedTask(deps).torrentMetaPath}.state`,
{ recursive: true }
)
})
it('Magnet task: mkdirs the final container (diskPath)', async () => {
const deps = makeDeps({ addUriGid: 'gid-m' })
await handleCreateTask(
{
type: 'bt',
payload: {
kind: 'magnet',
uri: 'magnet:?xt=urn:btih:a03e3f9a05341aa336e9d9d3f06b33cddafe0bdc&dn=Ubuntu',
},
selectedFiles: [0],
saveDir: '/d',
},
deps
)
expect(mkdirMock).toHaveBeenCalledTimes(1)
expect(mkdirMock).toHaveBeenCalledWith(lastAddedTask(deps).finalPath, {
recursive: true,
})
})
// HTTP/FTP: `diskPath` IS the file path — mkdir'ing it would race
// with aria2's open(2) for write (EISDIR). Pre-create the parent
// saveDir instead so aria2's `dir` option is reachable.
it('HTTP task: mkdirs the saveDir, NOT the .motrix file path', async () => {
const deps = makeDeps()
await handleCreateTask(
{
type: 'http',
uris: ['https://example.com/foo.mp4'],
saveDir: '/d',
filename: 'foo.mp4',
headers: [],
},
deps
)
expect(mkdirMock).toHaveBeenCalledTimes(1)
expect(mkdirMock).toHaveBeenCalledWith('/d', { recursive: true })
expect(mkdirMock).not.toHaveBeenCalledWith(
'/d/foo.mp4.motrix',
expect.anything()
)
})
it('HTTP task: still proceeds when mkdir fails (defence-in-depth)', async () => {
mkdirMock.mockRejectedValueOnce(new Error('EACCES'))
const deps = makeDeps()
await handleCreateTask(
{
type: 'http',
uris: ['https://example.com/foo.mp4'],
saveDir: '/d',
filename: 'foo.mp4',
headers: [],
},
deps
)
// engine still dispatched, task still registered
expect(deps.addUri).toHaveBeenCalledOnce()
expect(deps.add).toHaveBeenCalledOnce()
})
})
describe('handleCreateTask isPrivate propagation', () => {
it('persists isPrivate=true for a private torrent', async () => {
const torrentBytes = makePrivateTorrentFixture()
const deps = makeDeps({ addTorrentGid: 'gid-bt' })
await handleCreateTask(
{
type: 'bt',
payload: {
kind: 'torrent-base64',
base64: Buffer.from(torrentBytes).toString('base64'),
},
selectedFiles: [0],
saveDir: '/d',
displayName: 'private-torrent',
},
deps
)
const task = lastAddedTask(deps)
expect(task.bt?.isPrivate).toBe(true)
})
it('persists isPrivate=false for a public torrent', async () => {
const torrentBytes = makePublicTorrentFixture()
const deps = makeDeps({ addTorrentGid: 'gid-bt' })
await handleCreateTask(
{
type: 'bt',
payload: {
kind: 'torrent-base64',
base64: Buffer.from(torrentBytes).toString('base64'),
},
selectedFiles: [0],
saveDir: '/d',
displayName: 'public-torrent',
},
deps
)
const task = lastAddedTask(deps)
expect(task.bt?.isPrivate).toBe(false)
})
it('passes bt-tracker="" to addTorrent for private torrents', async () => {
const torrentBytes = makePrivateTorrentFixture()
const deps = makeDeps({ addTorrentGid: 'gid-bt' })
await handleCreateTask(
{
type: 'bt',
payload: {
kind: 'torrent-base64',
base64: Buffer.from(torrentBytes).toString('base64'),
},
selectedFiles: [0],
saveDir: '/d',
displayName: 'private-torrent',
},
deps
)
const addTorrentCall = deps.addTorrent.mock.calls[0]
const opts = addTorrentCall[2] as Record<string, string>
expect(opts['bt-tracker']).toBe('')
})
it('does not override bt-tracker for public torrents', async () => {
const torrentBytes = makePublicTorrentFixture()
const deps = makeDeps({ addTorrentGid: 'gid-bt' })
await handleCreateTask(
{
type: 'bt',
payload: {
kind: 'torrent-base64',
base64: Buffer.from(torrentBytes).toString('base64'),
},
selectedFiles: [0],
saveDir: '/d',
displayName: 'public-torrent',
},
deps
)
const addTorrentCall = deps.addTorrent.mock.calls[0]
const opts = addTorrentCall[2] as Record<string, string>
expect(opts['bt-tracker']).toBeUndefined()
})
})
describe('handleCreateTask CreateTaskOptions', () => {
it('persists source and sourceMeta when caller supplies them', async () => {
const deps = makeDeps()
const req = {
type: 'http',
uris: ['http://example.com/x.mp4'],
saveDir: '/tmp/save',
filename: 'x.mp4',
connections: 1,
headers: [],
}
await handleCreateTask(req, deps, {
source: 'bridge',
sourceMeta: {
kind: 'direct',
extensionId: 'e',
browser: 'chromium',
sessionKey: 'chromium:e',
pageUrl: 'http://page',
pageTitle: 't',
qualityLabel: 'q',
durationSec: null,
submittedAt: 1,
},
})
const task = lastAddedTask(deps)
expect(task.source).toBe('bridge')
expect(task.sourceMeta?.kind).toBe('direct')
})
it('merges extraEngineOptions into aria2.addUri options', async () => {
const deps = makeDeps({ addUriGid: 'gid-x' })
const req = {
type: 'http',
uris: ['http://example.com/y.mp4'],
saveDir: '/tmp/save',
filename: 'y.mp4',
connections: 1,
headers: [],
}
await handleCreateTask(req, deps, {
extraEngineOptions: {
header: ['X-A: 1', 'X-B: 2'],
'load-cookies': '/tmp/jar.txt',
referer: 'http://page',
},
})
const [, options] = deps.addUri.mock.calls[0] as [
unknown,
Record<string, unknown>,
]
expect(options.header).toEqual(['X-A: 1', 'X-B: 2'])
expect(options['load-cookies']).toBe('/tmp/jar.txt')
expect(options.referer).toBe('http://page')
expect(lastAddedTask(deps).instances[0]?.payload).toEqual({
directReplay: {
version: 1,
connections: 1,
requestModifiers: ['extraEngineOptions'],
replayability: 'requires-credentials',
},
})
})
})
describe('handleCreateTask plugin-hook chain (Plan C / T15)', () => {
// Mocks the HookOrchestrator and HookAuditLog dependencies the production
// code expects when the host has wired up the Plan C hook surface. The
// staged-effect store can stay a real instance — it is plain data.
function makeStaged(
metadataOps: readonly {
pluginId: string
op: 'set' | 'delete'
key: string
value?: unknown
}[] = []
) {
return {
allMetadataOps: vi.fn(() => metadataOps),
}
}
function makeOrchestrator(
result:
| ReturnType<typeof makeChainCommit>
| { aborted: true; reason: string }
) {
return {
runBeforeCreateHttp: vi.fn().mockResolvedValue(result),
runBeforeFinalize: vi.fn(),
runParallel: vi.fn(),
} as unknown as Deps['orchestrator']
}
function makeAuditLog() {
return {
log: vi.fn(async () => {}),
} as unknown as Deps['auditLog']
}
function makeChainCommit(
overrides: {
uris?: string[]
headers?: Array<{ name: string; value: string }>
proxy?: string
headerContributors?: string[]
uriContributor?: string
proxyContributor?: string
staged?: ReturnType<typeof makeStaged>
} = {}
) {
const staged = overrides.staged ?? makeStaged()
return {
final: {
type: 'http' as const,
sourceUrl: overrides.uris?.[0] ?? 'https://a/b',
uris: overrides.uris ?? ['https://a/b'],
saveDir: '/d',
filename: 'b',
connections: undefined,
headers: overrides.headers ?? [],
proxy: overrides.proxy,
createdBy: 'user' as const,
requestedAt: 0,
},
contributors: {
headers: overrides.headerContributors ?? [],
proxy: overrides.proxyContributor,
uris: overrides.uriContributor,
},
staged,
}
}
it('waits for mux fallback and a successful hook rewrite before probing metadata', async () => {
const order: string[] = []
const chainResult = makeChainCommit({
uris: ['https://cdn.example/api/file.bin'],
headers: [{ name: 'User-Agent', value: 'plugin-agent' }],
proxy: 'http://plugin-proxy.example:8080',
headerContributors: ['plugin-a'],
uriContributor: 'plugin-a',
proxyContributor: 'plugin-a',
})
const orchestrator = {
runBeforeCreateHttp: vi.fn(async () => {
order.push('hook')
return chainResult
}),
runBeforeFinalize: vi.fn(),
runParallel: vi.fn(),
} as unknown as Deps['orchestrator']
const resolveToMux = vi.fn(async () => {
order.push('mux')
return null
})
const dispatchMux = vi.fn()
const probe = vi.fn(async () => {
order.push('probe')
return { filename: 'rewritten.exe', validator: null }
})
const deps = makeDeps()
await handleCreateTask(
{
type: 'http',
uris: ['https://origin.example/stable'],
saveDir: '/d',
headers: [],
},
{
...deps,
orchestrator,
resolveToMux,
dispatchMux,
directResourceValidator: { capture: vi.fn(), probe },
}
)
expect(order).toEqual(['mux', 'hook', 'probe'])
expect(probe).toHaveBeenCalledWith('https://cdn.example/api/file.bin', {
headers: { 'User-Agent': 'plugin-agent' },
proxy: 'http://plugin-proxy.example:8080',
})
expect(deps.addUri.mock.calls[0]?.[0]).toEqual([
'https://cdn.example/api/file.bin',
])
})
it('keeps the rewritten URI basename when its metadata probe fails', async () => {
const orchestrator = makeOrchestrator(
makeChainCommit({
uris: ['https://cdn.example/release.zip'],
uriContributor: 'plugin-a',
})
)
const probe = vi.fn().mockRejectedValue(new Error('metadata unavailable'))
const capture = vi.fn()
const deps = makeDeps()
await handleCreateTask(
{
type: 'http',
uris: ['https://origin.example/stable'],
saveDir: '/d',
headers: [],
},
{
...deps,
orchestrator,
directResourceValidator: { capture, probe },
}
)
expect(probe).toHaveBeenCalledWith('https://cdn.example/release.zip', {})
expect(capture).not.toHaveBeenCalled()
expect(deps.pick).toHaveBeenLastCalledWith('/d', 'release.zip')
expect(deps.addUri).toHaveBeenCalledWith(
['https://cdn.example/release.zip'],
expect.objectContaining({ out: 'release.zip.motrix' })
)
expect(lastAddedTask(deps)).toMatchObject({
finalName: 'release.zip',
finalPath: '/d/release.zip',
diskPath: '/d/release.zip.motrix',
})
})
it('uses merged uris and headers from the chain when present', async () => {
const orchestrator = makeOrchestrator(
makeChainCommit({
uris: ['https://cdn.example/b'],
headers: [
{ name: 'X-Plugin', value: 'on' },
{ name: 'User-Agent', value: 'rewritten' },
],
proxy: 'http://proxy.example:1080',
headerContributors: ['plugin-a'],
uriContributor: 'plugin-a',
proxyContributor: 'plugin-a',
})
)
const auditLog = makeAuditLog()
const deps = makeDeps({ addUriGid: 'gid-x' })
const probe = vi.fn().mockResolvedValue({
filename: 'rewritten-release.exe',
validator: null,
})
const fullDeps = {
...deps,
orchestrator,
auditLog,
directResourceValidator: { capture: vi.fn(), probe },
}
await handleCreateTask(
{
type: 'http',
uris: ['https://a/b'],
saveDir: '/d',
headers: [],
},
fullDeps
)
expect(orchestrator?.runBeforeCreateHttp).toHaveBeenCalledOnce()
const [, options] = deps.addUri.mock.calls[0]
expect(deps.addUri.mock.calls[0][0]).toEqual(['https://cdn.example/b'])
expect(options.header).toEqual([
'X-Plugin: on',
'User-Agent: rewritten',
'Cookie: ',
'Accept: */*',
])
expect(options['all-proxy']).toBe('http://proxy.example:1080')
expect(options.out).toBe('rewritten-release.exe.motrix')
expect(probe).toHaveBeenCalledWith('https://cdn.example/b', {
headers: { 'X-Plugin': 'on', 'User-Agent': 'rewritten' },
proxy: 'http://proxy.example:1080',
})
expect(auditLog?.log).toHaveBeenCalledWith(
expect.objectContaining({
type: 'chain.commit',
hook: 'beforeCreate',
headerContributors: ['plugin-a'],
proxyContributor: 'plugin-a',
uriContributor: 'plugin-a',
finalHeaderCount: 2,
})
)
})
it('rejects a plugin-rewritten SOCKS proxy before metadata or durable intent', async () => {
const orchestrator = makeOrchestrator(
makeChainCommit({
proxy: 'socks5://proxy.example:1080',
proxyContributor: 'plugin-a',
})
)
const deps = makeDeps()
const probe = vi.fn()
const capture = vi.fn()
await expect(
handleCreateTask(httpRequest(), {
...deps,
orchestrator,
directResourceValidator: { capture, probe },
})
).rejects.toThrow('Task proxy must use aria2-compatible HTTP or HTTPS')
expect(probe).not.toHaveBeenCalled()
expect(capture).not.toHaveBeenCalled()
expect(deps.addUri).not.toHaveBeenCalled()
expect(deps.reserveEngineTaskId).not.toHaveBeenCalled()
})
it('commits staged metadata inside the same transaction as task add', async () => {
const metadataOps = [
{
pluginId: 'plugin-a',
op: 'set' as const,
key: 'release',
value: 'stable',
},
]
const staged = makeStaged(metadataOps)
const orchestrator = makeOrchestrator(
makeChainCommit({ staged, headerContributors: ['p'] })
)
const auditLog = makeAuditLog()
const persistTaskWithPluginMetadata = vi.fn(
async (_task: DownloadTask, _operations: readonly unknown[]) => undefined
)
const deps = makeDeps()
const fullDeps = {
...deps,
orchestrator,
auditLog,
persistTaskWithPluginMetadata,
}
await handleCreateTask(
{
type: 'http',
uris: ['https://a/b'],
saveDir: '/d',
headers: [],
},
fullDeps
)
expect(persistTaskWithPluginMetadata).toHaveBeenCalledOnce()
expect(persistTaskWithPluginMetadata.mock.calls[0]?.[1]).toEqual(
metadataOps
)
expect(deps.persist).not.toHaveBeenCalled()
expect(deps.add).toHaveBeenCalledOnce()
})
it.each(['persistence', 'engine'])(
'rejects revocation during %s after a hook has returned',
async (boundary) => {
let revoked = false
const staged = {
...makeStaged(),
hasPolicyChecks: true,
assertPolicyCurrent: () => {
if (revoked) throw new Error('security revoked')
},
}
const deps = makeDeps()
const persistTaskWithPluginMetadata = vi.fn(async () => {
if (boundary === 'persistence') revoked = true
})
if (boundary === 'engine') {
const addUri = deps.addUri.getMockImplementation() as (
...args: unknown[]
) => Promise<string>
deps.addUri.mockImplementation(async (...args) => {
const result = await addUri(...args)
revoked = true
return result
})
}
await expect(
handleCreateTask(httpRequest(), {
...deps,
orchestrator: makeOrchestrator(makeChainCommit({ staged })),
persistTaskWithPluginMetadata,
rollbackTaskCreation: vi.fn(async () => undefined),
})
).rejects.toThrow('security revoked')
expect(persistTaskWithPluginMetadata).toHaveBeenCalledOnce()
if (boundary === 'persistence') expect(deps.addUri).not.toHaveBeenCalled()
else expect(deps.addUri).toHaveBeenCalledOnce()
expect(deps.forceRemove).toHaveBeenCalledOnce()
expect(deps.removeDownloadResult).toHaveBeenCalledOnce()
expect(deps.add).not.toHaveBeenCalled()
}
)
it('fails closed when metadata is staged without an atomic boundary', async () => {
const staged = makeStaged([
{
pluginId: 'plugin-a',
op: 'set',
key: 'release',
value: 'stable',
},
])
const deps = makeDeps()
await expect(
handleCreateTask(httpRequest(), {
...deps,
orchestrator: makeOrchestrator(makeChainCommit({ staged })),
})
).rejects.toThrow(
'beforeCreate metadata requires an atomic task persistence boundary'
)
expect(deps.addUri).not.toHaveBeenCalled()
})
it.each([
['unsupported scheme', 'file:///etc/passwd'],
['non-empty credentials', 'https://user:[email protected]/file'],
['empty userinfo', 'https://@example.test/file'],
['malformed URL', 'not a URL'],
])('rejects Hook-produced URI with %s', async (_name, uri) => {
const deps = makeDeps()
await expect(
handleCreateTask(httpRequest(), {
...deps,
orchestrator: makeOrchestrator(
makeChainCommit({ uris: [uri], uriContributor: 'plugin-a' })
),
})
).rejects.toMatchObject({
code: ErrorCode.TaskSourceInvalid,
details: { stage: 'plugin' },
})
expect(deps.addUri).not.toHaveBeenCalled()
expect(deps.reserveEngineTaskId).not.toHaveBeenCalled()
})
it('accepts an admitted public HTTPS URI produced by a resolver', async () => {
const deps = makeDeps()
const uri =
'https://upload.wikimedia.org/wikipedia/commons/example-release.zip'
await handleCreateTask(httpRequest(), {
...deps,
orchestrator: makeOrchestrator(
makeChainCommit({ uris: [uri], uriContributor: 'plugin-a' })
),
})
expect(deps.addUri).toHaveBeenCalledWith([uri], expect.any(Object))
})
it('throws PluginRuntimeFault and emits chain.abort when chain aborts', async () => {
const orchestrator = makeOrchestrator({ aborted: true, reason: 'boom' })
const auditLog = makeAuditLog()
const deps = makeDeps()
const probe = vi.fn()
const capture = vi.fn()
const fullDeps = {
...deps,
orchestrator,
auditLog,
directResourceValidator: { capture, probe },
}
await expect(
handleCreateTask(
{
type: 'http',
uris: ['https://a/b'],
saveDir: '/d',
headers: [],
},
fullDeps
)
).rejects.toMatchObject({ code: ErrorCode.PluginRuntimeFault })
expect(auditLog?.log).toHaveBeenCalledWith(
expect.objectContaining({
type: 'chain.abort',
hook: 'beforeCreate',
reason: 'boom',
})
)
// engine never dispatched, task never registered
expect(deps.addUri).not.toHaveBeenCalled()
expect(deps.add).not.toHaveBeenCalled()
expect(probe).not.toHaveBeenCalled()
expect(capture).not.toHaveBeenCalled()
})
it('skips the chain for BT tasks (out of scope for T15)', async () => {
const orchestrator = makeOrchestrator(makeChainCommit())
const deps = makeDeps()
const fullDeps = { ...deps, orchestrator }
await handleCreateTask(
{
type: 'bt',
payload: { kind: 'torrent-base64', base64: sampleTorrentBase64 },
selectedFiles: [0],
saveDir: '/d',
displayName: 'mytorrent',
},
fullDeps
)
expect(orchestrator?.runBeforeCreateHttp).not.toHaveBeenCalled()
expect(deps.addTorrent).toHaveBeenCalledOnce()
})
it('emits chain.commit even when only proxy/uri changed (no header contributors)', async () => {
// Regression: previously, the chain.commit emission was gated on
// headerContributors.length > 0, which silently dropped audit lines
// for chains that mutate only `uris` or `proxy`. Successful chains
// must always leave an audit trail.
const orchestrator = makeOrchestrator(
makeChainCommit({
uris: ['https://cdn.example/b'],
proxy: 'http://proxy.example:1080',
headerContributors: [],
uriContributor: 'plugin-b',
proxyContributor: 'plugin-b',
})
)
const auditLog = makeAuditLog()
const deps = makeDeps({ addUriGid: 'gid-y' })
const fullDeps = { ...deps, orchestrator, auditLog }
await handleCreateTask(
{
type: 'http',
uris: ['https://a/b'],
saveDir: '/d',
headers: [],
},
fullDeps
)
expect(auditLog?.log).toHaveBeenCalledWith(
expect.objectContaining({
type: 'chain.commit',
hook: 'beforeCreate',
headerContributors: [],
proxyContributor: 'plugin-b',
uriContributor: 'plugin-b',
finalHeaderCount: 0,
})
)
})
})
describe('handleCreateTask engine-ready gate', () => {
it('awaits waitForEngineReady before dispatching to the engine (http)', async () => {
const order: string[] = []
const waitForEngineReady = vi.fn(async () => {
order.push('gate')
})
const deps = makeDeps({ waitForEngineReady })
deps.addUri.mockImplementation(async (_uris, options) => {
order.push('adapter')
return String(options.gid)
})
await handleCreateTask(httpRequest(), deps)
expect(waitForEngineReady).toHaveBeenCalledOnce()
expect(order).toEqual(['gate', 'adapter'])
})
it('waits for HTTP readiness before acquiring the applied-proxy lease', async () => {
const order: string[] = []
const deps = makeDeps({
waitForEngineReady: async () => {
order.push('gate')
},
})
const policy = deps.directResourceProxyPolicy
deps.directResourceProxyPolicy = {
snapshot: () => policy.snapshot(),
runWithSnapshot: (operation) => {
order.push('reader')
return policy.runWithSnapshot(operation)
},
}
deps.addUri.mockImplementation(async (_uris, options) => {
order.push('adapter')
return String(options.gid)
})
await handleCreateTask(httpRequest(), deps)
expect(order).toEqual(['gate', 'reader', 'adapter'])
})
it('throws and does NOT call the adapter when the gate rejects', async () => {
const waitForEngineReady = vi.fn(async () => {
throw new AppError(
ErrorCode.EngineTimeout,
'engine not ready within 15000ms'
)
})
const deps = makeDeps({ waitForEngineReady })
await expect(handleCreateTask(httpRequest(), deps)).rejects.toMatchObject({
code: ErrorCode.EngineTimeout,
})
expect(deps.addUri).not.toHaveBeenCalled()
})
it('does not await the gate for an invalid payload (gate runs after validation)', async () => {
const waitForEngineReady = vi.fn(async () => {})
const deps = makeDeps({ waitForEngineReady })
await expect(
handleCreateTask({ type: 'nonsense' }, deps)
).rejects.toMatchObject({
code: ErrorCode.IpcInvalidPayload,
})
expect(waitForEngineReady).not.toHaveBeenCalled()
})
it('creates normally when no gate is provided (back-compat)', async () => {
const deps = makeDeps()
const { taskId } = await handleCreateTask(httpRequest(), deps)
expect(typeof taskId).toBe('string')
expect(deps.addUri).toHaveBeenCalledOnce()
})
})
describe('handleCreateTask reserved-GID ownership', () => {
const reservedGid = '0123456789abcdef'
it('persists a reserved owner before the engine can expose its gid', async () => {
const order: string[] = []
const deps = makeDeps()
const persistTask = vi.fn(async (task: DownloadTask) => {
expect(task.engineTaskId).toBe(reservedGid)
order.push('persist')
})
deps.setReservedEngineTaskOwner.mockImplementation(() => {
order.push('reserved-owner')
})
deps.addUri.mockImplementation(
async (_uris: string[], options: Record<string, unknown>) => {
expect(options.gid).toBe(reservedGid)
expect(deps.reserveEngineTaskId).toHaveBeenCalledWith(reservedGid)
expect(persistTask).toHaveBeenCalledOnce()
expect(deps.setReservedEngineTaskOwner).toHaveBeenCalledOnce()
expect(deps.add).not.toHaveBeenCalled()
order.push('engine')
return reservedGid
}
)
deps.add.mockImplementation(() => {
order.push('publish')
})
await handleCreateTask(httpRequest(), {
...deps,
persistTask,
createEngineTaskId: () => reservedGid,
} as Deps)
expect(order).toEqual(['persist', 'reserved-owner', 'engine', 'publish'])
})
it('holds the public task mutation admission across engine dispatch', async () => {
const deps = makeDeps()
let releaseEngine: (() => void) | undefined
let engineEntered: (() => void) | undefined
const engineGate = new Promise<void>((resolve) => {
releaseEngine = resolve
})
const entered = new Promise<void>((resolve) => {
engineEntered = resolve
})
deps.addUri.mockImplementation(async (_uris, options) => {
engineEntered?.()
await engineGate
return String(options.gid)
})
let mutationTail: Promise<unknown> = Promise.resolve()
const runTaskMutation = vi.fn(
<T>(_taskIds: readonly string[], operation: () => Promise<T>) => {
const result = mutationTail.then(operation)
mutationTail = result.catch(() => undefined)
return result
}
)
let taskId = ''
const creating = handleCreateTask(httpRequest(), {
...deps,
persistTask: vi.fn(async (task) => {
taskId = task.id
}),
rollbackTaskCreation: vi.fn(async () => {}),
createEngineTaskId: () => reservedGid,
runTaskMutation,
} as Deps)
await entered
let competingMutationRan = false
const competing = runTaskMutation([taskId], async () => {
competingMutationRan = true
})
await Promise.resolve()
expect(competingMutationRan).toBe(false)
releaseEngine?.()
await creating
await competing
expect(competingMutationRan).toBe(true)
})
it('does not dispatch and releases the reservation when the durable intent rejects', async () => {
const deps = makeDeps()
const failure = new Error('durable intent failed')
await expect(
handleCreateTask(httpRequest(), {
...deps,
persistTask: vi.fn(async () => {
throw failure
}),
rollbackTaskCreation: vi.fn(async () => {}),
createEngineTaskId: () => reservedGid,
} as Deps)
).rejects.toBe(failure)
expect(deps.addUri).not.toHaveBeenCalled()
expect(deps.releaseEngineTaskIdReservation).toHaveBeenCalledWith(
reservedGid
)
expect(deps.retireEngineTaskIdReservation).not.toHaveBeenCalled()
})
it('retires rather than releases a cleaned-up post-dispatch reservation', async () => {
const deps = makeDeps()
const failure = new Error('transport lost after accept')
deps.addUri.mockRejectedValue(failure)
const rollbackTaskCreation = vi.fn(async () => {})
let taskId = ''
await expect(
handleCreateTask(httpRequest(), {
...deps,
persistTask: vi.fn(async (task) => {
taskId = task.id
}),
rollbackTaskCreation,
createEngineTaskId: () => reservedGid,
} as Deps)
).rejects.toBe(failure)
expect(deps.forceRemove).toHaveBeenCalledWith(reservedGid)
expect(deps.removeDownloadResult).toHaveBeenCalledWith(reservedGid)
expect(rollbackTaskCreation).toHaveBeenCalledWith(taskId)
expect(deps.remove).toHaveBeenCalledWith(taskId)
expect(deps.retireEngineTaskIdReservation).toHaveBeenCalledWith(reservedGid)
expect(deps.releaseEngineTaskIdReservation).not.toHaveBeenCalled()
expect(deps.setReservedEngineTaskOwner).toHaveBeenCalledOnce()
expect(deps.add).not.toHaveBeenCalled()
})
it('retains a failed torrent with known size and the reserved identity until cleanup can be confirmed', async () => {
const deps = makeDeps()
const error = new Error('addTorrent timed out')
deps.addTorrent.mockRejectedValue(error)
deps.forceRemove.mockRejectedValue(new Error('engine offline'))
deps.removeDownloadResult.mockRejectedValue(new Error('engine offline'))
const persistTask = vi.fn(async () => {})
await expect(
handleCreateTask(
{
type: 'bt',
payload: { kind: 'torrent-base64', base64: sampleTorrentBase64 },
selectedFiles: [0, 2],
saveDir: '/d',
},
{ ...deps, persistTask, createEngineTaskId: () => reservedGid } as Deps
)
).rejects.toBe(error)
const task = lastAddedTask(deps)
expect(task).toMatchObject({
status: TaskStatus.Error,
totalBytes: 2,
sizeWhenDone: 2,
fileCount: 3,
errorMessage: error.message,
engineTaskId: reservedGid,
})
expect(task.instances[0]?.payload.unconfirmedTorrentCreateGid).toBe(
reservedGid
)
expect(persistTask).toHaveBeenLastCalledWith(task)
expect(mergeEngineTask(task, { ...task, status: TaskStatus.Queued })).toBe(
task
)
})
it('publishes the durable candidate when post-dispatch cleanup is uncertain', async () => {
const deps = makeDeps()
const failure = new Error('transport lost after accept')
deps.addUri.mockRejectedValue(failure)
deps.forceRemove.mockRejectedValue(new Error('cleanup transport lost'))
deps.removeDownloadResult.mockRejectedValue(
new Error('result cleanup transport lost')
)
const rollbackTaskCreation = vi.fn(async () => {})
await expect(
handleCreateTask(httpRequest(), {
...deps,
persistTask: vi.fn(async () => {}),
rollbackTaskCreation,
createEngineTaskId: () => reservedGid,
} as Deps)
).rejects.toBe(failure)
const owner = lastAddedTask(deps)
expect(owner.engineTaskId).toBe(reservedGid)
expect(rollbackTaskCreation).not.toHaveBeenCalled()
expect(deps.releaseEngineTaskIdReservation).not.toHaveBeenCalled()
expect(deps.retireEngineTaskIdReservation).not.toHaveBeenCalled()
})
})
describe('handleCreateTask mux pre-resolve seam', () => {
it('routes http to dispatchMux (not engine) when resolveToMux returns a mux pair', async () => {
const muxPair = {
videoUrl: 'https://video.example/v.mp4',
audioUrl: 'https://audio.example/a.m4a',
container: 'mp4' as const,
headers: { 'x-test': 'yes' },
}
const resolveToMux = vi.fn().mockResolvedValue(muxPair)
const dispatchMux = vi.fn().mockResolvedValue({ taskId: 'mux-task-id' })
const deps = makeDeps()
const probe = vi.fn()
const capture = vi.fn()
const result = await handleCreateTask(
{
type: 'http',
uris: ['https://www.youtube.com/watch?v=abc'],
saveDir: '/d',
headers: [],
},
{
...deps,
resolveToMux,
dispatchMux,
directResourceValidator: { capture, probe },
}
)
// dispatchMux was called, NOT the engine
expect(dispatchMux).toHaveBeenCalledOnce()
expect(deps.addUri).not.toHaveBeenCalled()
// taskId is reused from the mux pipeline result
expect(result.taskId).toBe('mux-task-id')
// dispatchMux received an AdaptedMux with the mux pair's fields
const adapted = dispatchMux.mock.calls[0][0]
expect(adapted.kind).toBe('mux')
expect(adapted.videoUrl).toBe(muxPair.videoUrl)
expect(adapted.audioUrl).toBe(muxPair.audioUrl)
expect(adapted.container).toBe('mp4')
expect(probe).not.toHaveBeenCalled()
expect(capture).not.toHaveBeenCalled()
})
it("uses the resolver's title (sanitized) as the mux finalName, not the URL bvid", async () => {
const resolveToMux = vi.fn().mockResolvedValue({
videoUrl: 'https://v/v.mp4',
audioUrl: 'https://a/a.m4a',
container: 'mp4' as const,
title: '9.9分!风道机箱唯一真神:酷冷 HAF II 500',
})
const dispatchMux = vi.fn().mockResolvedValue({ taskId: 't' })
const deps = makeDeps()
await handleCreateTask(
{
type: 'http',
uris: ['https://www.bilibili.com/video/BV14vJg6ZEd4/'],
saveDir: '/d',
headers: [],
},
{ ...deps, resolveToMux, dispatchMux }
)
const adapted = dispatchMux.mock.calls[0][0]
// Full-width !/: are not filesystem-illegal, so they survive. The point:
// the human title is used, NOT the meaningless "BV14vJg6ZEd4" bvid — and
// the container extension is appended BEFORE the dedup pick so the picked
// name is the on-disk name.
expect(adapted.finalName).toBe(
'9.9分!风道机箱唯一真神:酷冷 HAF II 500.mp4'
)
})
it('replaces filesystem-illegal characters in the resolver title', async () => {
const resolveToMux = vi.fn().mockResolvedValue({
videoUrl: 'https://v/v.mp4',
audioUrl: 'https://a/a.m4a',
container: 'mp4' as const,
title: 'A/B: C? "D" <E>',
})
const dispatchMux = vi.fn().mockResolvedValue({ taskId: 't' })
const deps = makeDeps()
await handleCreateTask(
{
type: 'http',
uris: ['https://www.bilibili.com/video/BV14vJg6ZEd4/'],
saveDir: '/d',
headers: [],
},
{ ...deps, resolveToMux, dispatchMux }
)
const adapted = dispatchMux.mock.calls[0][0]
expect(adapted.finalName).toBe('A_B_ C_ _D_ _E_.mp4')
})
it('reuses the computed taskId when dispatching via mux', async () => {
const resolveToMux = vi.fn().mockResolvedValue({
videoUrl: 'https://v.example/v',
audioUrl: 'https://a.example/a',
container: 'mp4' as const,
})
let capturedTaskId: string | undefined
const dispatchMux = vi.fn().mockImplementation(async (adapted) => {
capturedTaskId = adapted.taskId
return { taskId: adapted.taskId }
})
const deps = makeDeps()
const result = await handleCreateTask(
{
type: 'http',
uris: ['https://www.youtube.com/watch?v=xyz'],
saveDir: '/d',
headers: [],
},
{ ...deps, resolveToMux, dispatchMux }
)
expect(capturedTaskId).toBe(result.taskId)
expect(typeof capturedTaskId).toBe('string')
})
it('falls through to the normal HTTP path (engine.createDownload) when resolveToMux returns null', async () => {
let muxFinished = false
const resolveToMux = vi.fn(async () => {
muxFinished = true
return null
})
const dispatchMux = vi.fn()
const deps = makeDeps({ addUriGid: 'gid-http' })
const probe = vi.fn(async () => {
expect(muxFinished).toBe(true)
return { filename: 'release.zip', validator: null }
})
const result = await handleCreateTask(
{
type: 'http',
uris: ['https://example.com/file.zip'],
saveDir: '/d',
headers: [],
},
{
...deps,
resolveToMux,
dispatchMux,
directResourceValidator: { capture: vi.fn(), probe },
}
)
expect(deps.addUri).toHaveBeenCalledOnce()
expect(dispatchMux).not.toHaveBeenCalled()
expect(probe).toHaveBeenCalledOnce()
expect(result.gid).toMatch(/^[0-9a-f]{16}$/)
})
it('falls through to HTTP path when resolveToMux and dispatchMux are absent', async () => {
const deps = makeDeps({ addUriGid: 'gid-fallback' })
const result = await handleCreateTask(
{
type: 'http',
uris: ['https://www.youtube.com/watch?v=test'],
saveDir: '/d',
headers: [],
},
deps
)
expect(deps.addUri).toHaveBeenCalledOnce()
expect(result.gid).toMatch(/^[0-9a-f]{16}$/)
})
it('never calls resolveToMux for magnet/bt requests', async () => {
const resolveToMux = vi.fn().mockResolvedValue(null)
const dispatchMux = vi.fn()
const deps = makeDeps({ addUriGid: 'gid-m' })
await handleCreateTask(
{
type: 'bt',
payload: {
kind: 'magnet',
uri: 'magnet:?xt=urn:btih:a03e3f9a05341aa336e9d9d3f06b33cddafe0bdc&dn=Test',
},
selectedFiles: [],
saveDir: '/d',
},
{ ...deps, resolveToMux, dispatchMux }
)
expect(resolveToMux).not.toHaveBeenCalled()
expect(dispatchMux).not.toHaveBeenCalled()
expect(deps.addUri).toHaveBeenCalledOnce()
})
})
it.each([
['foo', 'foo'],
['foo', 'foo.aria2'],
['foo.motrix', 'foo'],
])('isolates a pending BT %s from HTTP %s', async (btName, httpName) => {
const deps = makeDeps()
const owners: DownloadTask[] = []
deps.add.mockImplementation((task: DownloadTask) => owners.push(task))
vi.mocked(deps.taskManager.getAll).mockImplementation(() => owners)
deps.finalNamePicker = new FinalNamePickerImpl({ exists: async () => false })
const entered = Promise.withResolvers<void>()
const release = Promise.withResolvers<void>()
deps.addTorrent.mockImplementationOnce(async (_metadata, _uris, options) => {
entered.resolve()
await release.promise
return options.gid
})
const bt = handleCreateTask(
{
type: 'bt',
payload: {
kind: 'torrent-base64',
base64: Buffer.from(buildMinimalTorrentBytes('source', false)).toString(
'base64'
),
},
selectedFiles: [0],
saveDir: '/d',
displayName: btName,
},
deps
)
await entered.promise
const http = handleCreateTask({ ...httpRequest(), filename: httpName }, deps)
await Promise.resolve()
expect(deps.addUri).not.toHaveBeenCalled()
release.resolve()
await Promise.all([bt, http])
const httpTask = owners.find((task) => task.type === TaskType.Http)!
expect(httpTask.finalName).not.toBe(httpName)
expect(httpTask.diskPath).toBe(`${httpTask.finalPath}.motrix`)
})
describe('verified existing torrent adoption', () => {
const complete = {
complete: true,
checkedPieces: 1,
totalPieces: 1,
validPieces: 1,
missingFiles: [],
invalidFiles: [],
}
const request = () => ({
type: 'bt' as const,
payload: {
kind: 'torrent-base64' as const,
base64: Buffer.from(makePublicTorrentFixture()).toString('base64'),
},
selectedFiles: [0],
saveDir: '/d',
duplicatePolicy: 'use-existing' as const,
})
it('verifies the exact existing path before engine admission without allocating a suffix', async () => {
const deps = makeDeps()
deps.finalNamePicker.isTaken = vi.fn(async () => true)
vi.mocked(verifyBtFiles).mockResolvedValue(complete)
await handleCreateTask(request(), deps)
expect(verifyBtFiles).toHaveBeenCalledWith(
expect.objectContaining({
payloadPath: '/d/public-torrent',
selectedFiles: [0],
})
)
expect(deps.pick).not.toHaveBeenCalled()
expect(deps.addTorrent).toHaveBeenCalledWith(
expect.any(String),
[],
expect.objectContaining({
'check-integrity': 'true',
'allow-overwrite': 'false',
'bt-seed-unverified': 'false',
})
)
expect(lastAddedTask(deps).finalPath).toBe('/d/public-torrent')
})
it('does not adopt a directory containing another task output', async () => {
const deps = makeDeps()
vi.mocked(deps.taskManager.getAll).mockReturnValue([
makeTestTask({ id: 'other', finalPath: '/d/public-torrent/owned.bin' }),
])
await expect(handleCreateTask(request(), deps)).rejects.toThrow(
'task.storage.errors.conflict'
)
expect(deps.addTorrent).not.toHaveBeenCalled()
})
it('does not adopt over another task pending control-file name', async () => {
const deps = makeDeps()
vi.mocked(verifyBtFiles).mockResolvedValue(complete)
vi.mocked(deps.taskManager.getAll).mockReturnValue([
makeTestTask({
id: 'other',
finalPath: '/d/public-torrent.aria2',
status: TaskStatus.Queued,
}),
])
await expect(handleCreateTask(request(), deps)).rejects.toThrow(
'task.storage.errors.conflict'
)
expect(deps.addTorrent).not.toHaveBeenCalled()
})
it('does not adopt files beside an unowned existing control file', async () => {
const deps = makeDeps()
fsStub.lstat.mockResolvedValueOnce({})
await expect(handleCreateTask(request(), deps)).rejects.toThrow(
'task.storage.errors.conflict'
)
expect(deps.addTorrent).not.toHaveBeenCalled()
expect(deps.persist).not.toHaveBeenCalled()
})
it('does not adopt a payload named as another task control file', async () => {
const deps = makeDeps()
vi.mocked(deps.taskManager.getAll).mockReturnValue([
makeTestTask({
id: 'other',
finalPath: '/d/public-torrent',
status: TaskStatus.Queued,
}),
])
await expect(
handleCreateTask(
{ ...request(), displayName: 'public-torrent.aria2' },
deps
)
).rejects.toThrow('task.storage.errors.conflict')
expect(deps.addTorrent).not.toHaveBeenCalled()
})
it('does not create a task or start the engine for damaged existing files', async () => {
const deps = makeDeps()
vi.mocked(verifyBtFiles).mockResolvedValue({
...complete,
complete: false,
validPieces: 0,
})
await expect(handleCreateTask(request(), deps)).rejects.toThrow(
'task.storage.incomplete'
)
expect(deps.addTorrent).not.toHaveBeenCalled()
expect(deps.persist).not.toHaveBeenCalled()
expect(deps.taskManager.add).not.toHaveBeenCalled()
})
it('uses the original task ID and relocation service for an unambiguous old location', async () => {
const deps = makeDeps()
const infoHash = (await parseBtFileLayout(makePublicTorrentFixture()))
.infoHash
const task = makeDownloadTask({
id: 'original',
type: TaskType.Bt,
status: TaskStatus.Completed,
name: 'original',
saveDir: '/old',
createdAt: 1,
updatedAt: 1,
diskPath: '/old/public-torrent',
filename: 'public-torrent',
finalName: 'public-torrent',
instances: [],
kind: TaskKind.Bt,
source: 'user',
sourceMeta: null,
infoHash,
torrentMetaPath: '/metadata.torrent',
finalPath: '/old/public-torrent',
bt: makeDefaultBtExtension({ selectedFiles: [0] }),
})
vi.mocked(deps.taskManager.getAll).mockReturnValue([task])
vi.mocked(deps.taskManager.getById).mockReturnValue(task)
deps.relocateExistingBt = vi.fn(async () => {})
expect(await handleCreateTask(request(), deps)).toMatchObject({
outcome: 'rechecked',
taskId: 'original',
})
expect(deps.relocateExistingBt).toHaveBeenCalledWith(
'original',
'/d',
'public-torrent'
)
expect(deps.addTorrent).not.toHaveBeenCalled()
})
it('refuses metadata-only magnets for explicit existing-file adoption', async () => {
const deps = makeDeps()
await expect(
handleCreateTask(
{
...request(),
payload: {
kind: 'magnet',
uri: `magnet:?xt=urn:btih:${'a'.repeat(40)}`,
},
},
deps
)
).rejects.toThrow('Invalid task create request')
expect(deps.addUri).not.toHaveBeenCalled()
})
})