A full-featured download manager.
import { registerEngineFailureSubscriber } from '@core/notifications/engine-failure-subscriber'
import { NotificationCenter } from '@core/notifications/notification-center'
import { AppliedDownloadProxyPolicy } from '@core/proxy/applied-download-proxy-policy'
import { MotrixDatabase } from '@core/session/motrix-database'
import { ErrorCode } from '@shared/errors'
import { Events } from '@shared/protocol/events'
import type {
EngineFailurePayload,
EngineFeatureReport,
} from '@shared/types/engine'
import {
EngineFailureReason,
EngineProcessOwnership,
EngineRecoveryAction,
EngineState,
} from '@shared/types/engine'
import { NotificationKinds } from '@shared/types/notification'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { EventBus } from '../events/event-bus'
import type { SettingsManager } from '../settings/settings-manager'
import type { Aria2Adapter } from './aria2/aria2-adapter'
import type { Aria2ConfigBuilder } from './aria2/aria2-config-builder'
import type { Aria2ProcessManager } from './aria2/aria2-process-manager'
import type { Aria2RpcClient } from './aria2/aria2-rpc-client'
import type { Aria2TrustStore } from './aria2/aria2-trust-store'
import { DIRECT_RESOURCE_METADATA_PROFILE } from './engine-adapter'
import { EngineSupervisor } from './engine-supervisor'
import { checkPort } from './port-check'
const { probePreciseMock, recoverSessionMock } = vi.hoisted(() => ({
probePreciseMock: vi.fn(),
recoverSessionMock: vi.fn().mockResolvedValue(null),
}))
vi.mock('./aria2/aria2-session-identity-recovery', () => ({
recoverAria2SessionIdentity: recoverSessionMock,
}))
vi.mock('../probe/disk-probe', () => ({
probePrecise: probePreciseMock,
}))
// checkPort uses node:net I/O which doesn't fire under fake timers, and
// a live aria2 on the dev port would make it return false. Mock the
// port-check module so the supervisor always sees the port as available.
vi.mock('./port-check', () => ({
checkPort: vi.fn().mockResolvedValue(true),
findAvailablePort: vi.fn().mockResolvedValue(16801),
}))
// ─── Mock factories ─────────────────────────────────────────
const FEATURE_REPORT: EngineFeatureReport = {
version: '1.37.0-motrix.10',
features: ['Async DNS', 'BitTorrent', 'SQLite3-Persistence'],
hasSqlitePersistence: true,
hasBtSeedUnverified: false,
hasBtSaveMetadata: false,
hasMoveStorage: false,
}
function createMockSettingsManager(): SettingsManager {
return {
getEngine: vi.fn(() => ({
rpcPort: 16800,
rpcSecret: 'test-secret',
dhtEnabled: true,
listenPort: 6881,
dhtListenPort: 6881,
performanceProfile: 'auto',
maxConcurrentDownloads: 5,
maxConnectionPerServer: 64,
split: 16,
minSplitSize: 4194304,
userAgent: 'Motrix/2.0',
sessionSaveInterval: 60,
fileAllocation: 'none',
diskCache: 33554432,
sqlite3Persistence: true,
sqlite3DbPath: '',
sqlite3HistoryLimit: -1,
})),
getApp: vi.fn(() => ({
defaultSaveDir: '/Users/test/Downloads',
})),
getProxy: vi.fn(() => ({
enabled: false,
protocol: 'http',
host: '',
port: 8080,
user: '',
password: '',
bypass: [],
scopes: {
download: false,
updateApp: false,
updateTrackers: false,
plugins: false,
},
})),
update: vi.fn().mockResolvedValue(undefined),
} as unknown as SettingsManager
}
function createMockProcessManager(): Aria2ProcessManager {
return {
probe: vi.fn().mockResolvedValue(FEATURE_REPORT),
spawn: vi.fn().mockResolvedValue(undefined),
gracefulStop: vi.fn().mockResolvedValue(undefined),
kill: vi.fn(),
isRunning: vi.fn(() => true),
getPid: vi.fn(() => 12345),
getRecentStderr: vi.fn(() => ''),
inspectPort: vi.fn().mockResolvedValue(null),
forceTerminateVerified: vi.fn().mockResolvedValue(undefined),
onExit: null,
onError: null,
} as unknown as Aria2ProcessManager
}
function createMockConfigBuilder(): Aria2ConfigBuilder {
return {
ensureUserConfig: vi.fn().mockResolvedValue('/tmp/aria2.conf'),
hasSavedSession: vi.fn().mockResolvedValue(false),
resolveSqliteDbPath: vi.fn().mockReturnValue('/tmp/aria2.db'),
quarantineSqliteDatabase: vi.fn().mockResolvedValue({
databasePath: '/tmp/aria2.db',
quarantineBasePath: '/tmp/aria2.db.corrupt-test',
moved: ['/tmp/aria2.db.corrupt-test'],
}),
buildArgs: vi.fn(() => ['--conf-path=/tmp/aria2.conf']),
} as unknown as Aria2ConfigBuilder
}
function createMockRpcClient(): Aria2RpcClient {
return {
setSecret: vi.fn(),
connect: vi.fn().mockResolvedValue(undefined),
disconnect: vi.fn(),
isConnected: vi.fn(() => true),
getConnectionStatus: vi.fn(() => ({
transport: 'websocket',
connected: true,
})),
getVersion: vi.fn().mockResolvedValue({
version: '1.37.0',
enabledFeatures: ['SQLite3-Persistence'],
}),
saveSession: vi.fn().mockResolvedValue('OK'),
shutdown: vi.fn().mockResolvedValue('OK'),
changeGlobalOption: vi.fn().mockResolvedValue('OK'),
} as unknown as Aria2RpcClient
}
function createMockTrustStore(): Aria2TrustStore {
return {
prepareEnvironment: vi.fn().mockResolvedValue(undefined),
} as unknown as Aria2TrustStore
}
function createMockAdapter(): Aria2Adapter {
return {
setFeatureReport: vi.fn(),
inspectDirectResourceMetadataProfile: vi
.fn()
.mockResolvedValue(DIRECT_RESOURCE_METADATA_PROFILE),
setDirectResourceMetadataProfile: vi.fn(),
getDirectResourceMetadataProfile: vi.fn(() => null),
} as unknown as Aria2Adapter
}
function createMockProxyBridge() {
return {
resolveForDownload: vi.fn().mockResolvedValue(null),
}
}
// ─── Tests ──────────────────────────────────────────────────
describe('EngineSupervisor', () => {
let eventBus: EventBus
let settings: SettingsManager
let processManager: Aria2ProcessManager
let configBuilder: Aria2ConfigBuilder
let trustStore: Aria2TrustStore
let rpcClient: Aria2RpcClient
let adapter: Aria2Adapter
let proxyBridge: ReturnType<typeof createMockProxyBridge>
let supervisor: EngineSupervisor
beforeEach(() => {
vi.useFakeTimers()
probePreciseMock.mockReset()
probePreciseMock.mockResolvedValue({
platform: 'darwin',
mountPoint: '/',
fsType: 'apfs',
diskType: 'ssd',
isInternal: true,
isNetworkFs: false,
freeBytes: 100 * 1024 * 1024 * 1024,
confidence: 'high',
})
eventBus = new EventBus()
settings = createMockSettingsManager()
processManager = createMockProcessManager()
configBuilder = createMockConfigBuilder()
trustStore = createMockTrustStore()
rpcClient = createMockRpcClient()
adapter = createMockAdapter()
proxyBridge = createMockProxyBridge()
supervisor = new EngineSupervisor(
eventBus,
settings,
processManager,
configBuilder,
trustStore,
rpcClient,
adapter,
proxyBridge
)
})
afterEach(() => {
vi.useRealTimers()
vi.restoreAllMocks()
})
describe('initial state', () => {
it('starts in Stopped state', () => {
expect(supervisor.getState()).toBe(EngineState.Stopped)
})
})
describe('start — happy path', () => {
it('prepares the startup guard before spawning and reconciles before Ready', async () => {
const reconcile = vi.fn(async () => {
expect(rpcClient.connect).toHaveBeenCalledOnce()
expect(supervisor.getState()).not.toBe(EngineState.Ready)
})
const prepare = vi.fn(async () => {
expect(processManager.spawn).not.toHaveBeenCalled()
return { args: ['--pause=true'], reconcile }
})
supervisor.setStartupGuard({ prepare })
await supervisor.start('/usr/bin/aria2c')
expect(processManager.spawn).toHaveBeenCalledWith(
'/usr/bin/aria2c',
['--pause=true'],
undefined
)
expect(reconcile).toHaveBeenCalledOnce()
expect(supervisor.getState()).toBe(EngineState.Ready)
})
it('does not publish Ready when mandatory completed-task cleanup fails', async () => {
const ready = vi.fn()
eventBus.on(Events.EngineStateChanged, (state) => {
if (state === EngineState.Ready) ready()
})
supervisor.setStartupGuard({
prepare: async () => ({
args: ['--pause=true'],
reconcile: async () => {
throw new Error('completed task purge failed')
},
}),
})
await supervisor.start('/usr/bin/aria2c')
expect(ready).not.toHaveBeenCalled()
expect(supervisor.getState()).toBe(EngineState.Failed)
expect(supervisor.getLastError()).toContain('completed task purge failed')
})
it('runs startup maintenance after RPC connect and before publishing Ready', async () => {
const readyObserved = vi.fn()
eventBus.on(Events.EngineStateChanged, (state) => {
if (state === EngineState.Ready) readyObserved()
})
const maintenance = vi.fn(async () => {
expect(rpcClient.connect).toHaveBeenCalledOnce()
expect(readyObserved).not.toHaveBeenCalled()
})
supervisor.setPreReadyMaintenance(maintenance)
await supervisor.start('/usr/bin/aria2c')
expect(maintenance).toHaveBeenCalledOnce()
expect(readyObserved).toHaveBeenCalledOnce()
expect(maintenance.mock.invocationCallOrder[0]).toBeLessThan(
readyObserved.mock.invocationCallOrder[0] ?? Number.MAX_SAFE_INTEGER
)
})
it('resolves the download proxy before building aria2 arguments', async () => {
const resolved = {
allProxy: 'http://127.0.0.1:43123',
noProxy: 'localhost',
}
proxyBridge.resolveForDownload.mockResolvedValue(resolved)
await supervisor.start('/usr/bin/aria2c')
expect(proxyBridge.resolveForDownload).toHaveBeenCalledWith(
settings.getProxy()
)
expect(configBuilder.buildArgs).toHaveBeenCalledWith(
expect.anything(),
expect.any(Boolean),
resolved,
expect.anything(),
expect.any(String),
expect.any(Boolean)
)
})
it('commits the exact resolved route before publishing Ready', async () => {
const resolved = {
allProxy: 'http://bridge-user:[email protected]:43123',
noProxy: 'localhost',
}
proxyBridge.resolveForDownload.mockResolvedValue(resolved)
const order: string[] = []
const policy = {
commit: vi.fn(() => {
order.push('commit')
}),
markUnavailable: vi.fn(),
}
eventBus.on(Events.EngineRecovered, () => order.push('ready'))
supervisor = new EngineSupervisor(
eventBus,
settings,
processManager,
configBuilder,
trustStore,
rpcClient,
adapter,
proxyBridge,
policy
)
await supervisor.start('/usr/bin/aria2c')
expect(policy.commit).toHaveBeenCalledWith(resolved)
expect(order).toEqual(['commit', 'ready'])
expect(supervisor.getState()).toBe(EngineState.Ready)
})
it('repairs a proxy update persisted while the engine is Starting', async () => {
const before = {
enabled: true,
protocol: 'http' as const,
host: 'before.example',
port: 8080,
user: '',
password: '',
bypass: [],
scopes: {
download: true,
updateApp: false,
updateTrackers: false,
plugins: false,
},
}
const after = { ...before, host: 'after.example' }
let current = before
vi.mocked(settings.getProxy).mockImplementation(() => current)
proxyBridge.resolveForDownload.mockImplementation(async (value) => ({
allProxy: `http://${value.host}:${value.port}`,
noProxy: value.bypass.join(','),
}))
let releaseConnect: (() => void) | undefined
vi.mocked(rpcClient.connect).mockImplementation(
() =>
new Promise<void>((resolve) => {
releaseConnect = resolve
})
)
const policy = new AppliedDownloadProxyPolicy()
supervisor = new EngineSupervisor(
eventBus,
settings,
processManager,
configBuilder,
trustStore,
rpcClient,
adapter,
proxyBridge,
policy
)
const startup = supervisor.start('/usr/bin/aria2c')
await vi.waitFor(() => expect(rpcClient.connect).toHaveBeenCalled())
current = after
const earlyTransition = policy.applyTransition(() =>
supervisor
.applyProxyChange({
allProxy: 'http://after.example:8080',
noProxy: '',
})
.then((applied) =>
applied
? {
downloadProxy: 'applied' as const,
appliedProxy: {
allProxy: 'http://after.example:8080',
noProxy: '',
},
}
: { downloadProxy: 'unavailable' as const }
)
)
await earlyTransition
expect(policy.snapshot()).toBeNull()
releaseConnect?.()
await startup
expect(supervisor.getState()).toBe(EngineState.Ready)
expect(policy.snapshot()).toEqual({
proxy: 'http://after.example:8080',
noProxy: '',
})
expect(rpcClient.changeGlobalOption).toHaveBeenCalledWith(
expect.objectContaining({
'all-proxy': 'http://after.example:8080',
'no-proxy': '',
'proxy-method': 'get',
})
)
})
it('does not commit an applied route when startup fails', async () => {
const policy = {
commit: vi.fn(),
markUnavailable: vi.fn(),
}
vi.mocked(rpcClient.connect).mockRejectedValue(new Error('RPC down'))
supervisor = new EngineSupervisor(
eventBus,
settings,
processManager,
configBuilder,
trustStore,
rpcClient,
adapter,
proxyBridge,
policy
)
await supervisor.start('/usr/bin/aria2c')
expect(policy.commit).not.toHaveBeenCalled()
expect(policy.markUnavailable).toHaveBeenCalled()
expect(supervisor.getState()).toBe(EngineState.Failed)
})
it('transitions Stopped → Starting → Ready', async () => {
const states: EngineState[] = []
eventBus.on(Events.EngineStateChanged, (state) => {
states.push(state as EngineState)
})
await supervisor.start('/usr/bin/aria2c')
expect(states).toEqual([EngineState.Starting, EngineState.Ready])
expect(supervisor.getState()).toBe(EngineState.Ready)
})
it('publishes the sanitized metadata profile before Ready and clears it on stop', async () => {
const readyObserved = vi.fn()
eventBus.on(Events.EngineStateChanged, (state) => {
if (state === EngineState.Ready) readyObserved()
})
await supervisor.start('/usr/bin/aria2c')
expect(
adapter.inspectDirectResourceMetadataProfile
).toHaveBeenCalledOnce()
expect(adapter.setDirectResourceMetadataProfile).toHaveBeenCalledWith(
DIRECT_RESOURCE_METADATA_PROFILE
)
expect(
vi
.mocked(adapter.setDirectResourceMetadataProfile)
.mock.invocationCallOrder.at(-1)
).toBeLessThan(readyObserved.mock.invocationCallOrder[0] as number)
await supervisor.stop()
expect(adapter.setDirectResourceMetadataProfile).toHaveBeenLastCalledWith(
null
)
})
it('keeps the engine Ready with a fail-closed profile when inspection fails', async () => {
vi.mocked(adapter.inspectDirectResourceMetadataProfile).mockRejectedValue(
new Error('profile unavailable')
)
await supervisor.start('/usr/bin/aria2c')
expect(supervisor.getState()).toBe(EngineState.Ready)
expect(adapter.setDirectResourceMetadataProfile).toHaveBeenCalledWith(
null
)
})
it('synchronizes the latest RPC secret on every start before authenticated calls', async () => {
const initial = settings.getEngine()
let current = initial
vi.mocked(settings.getEngine).mockImplementation(() => current)
await supervisor.start('/usr/bin/aria2c')
current = { ...initial, rpcSecret: 'rotated-secret' }
await supervisor.restart()
current = { ...initial, rpcSecret: '' }
await supervisor.restart()
expect(rpcClient.setSecret).toHaveBeenNthCalledWith(1, initial.rpcSecret)
expect(rpcClient.setSecret).toHaveBeenNthCalledWith(2, 'rotated-secret')
expect(rpcClient.setSecret).toHaveBeenNthCalledWith(3, '')
expect(configBuilder.buildArgs).toHaveBeenLastCalledWith(
expect.objectContaining({ rpcSecret: '' }),
expect.any(Boolean),
null,
expect.anything(),
expect.any(String),
expect.any(Boolean)
)
expect(
vi.mocked(rpcClient.setSecret).mock.invocationCallOrder.at(-1)
).toBeLessThan(
vi.mocked(rpcClient.changeGlobalOption).mock.invocationCallOrder.at(-1)!
)
})
it('calls probe → ensureConfig → buildArgs → spawn → connect', async () => {
await supervisor.start('/usr/bin/aria2c')
expect(processManager.probe).toHaveBeenCalledWith('/usr/bin/aria2c')
expect(configBuilder.ensureUserConfig).toHaveBeenCalled()
expect(trustStore.prepareEnvironment).toHaveBeenCalled()
expect(configBuilder.buildArgs).toHaveBeenCalled()
expect(processManager.spawn).toHaveBeenCalledWith(
'/usr/bin/aria2c',
['--conf-path=/tmp/aria2.conf'],
undefined
)
expect(rpcClient.connect).toHaveBeenCalledWith(16800)
})
it('passes the prepared trust environment only to the aria2 process', async () => {
const env = {
PATH: '/usr/bin',
SSL_CERT_FILE: '/tmp/aria2-ca-bundle.pem',
}
vi.mocked(trustStore.prepareEnvironment).mockResolvedValue(env)
await supervisor.start('/usr/bin/aria2c')
expect(processManager.spawn).toHaveBeenCalledWith(
'/usr/bin/aria2c',
['--conf-path=/tmp/aria2.conf'],
env
)
})
it('caches feature report after successful start', async () => {
await supervisor.start('/usr/bin/aria2c')
expect(supervisor.getFeatureReport()).toEqual(FEATURE_REPORT)
})
it('injects the probed feature report into the adapter before Ready', async () => {
// The adapter's durable-remove trust gate reads its OWN featureReport.
// Nothing in production calls adapter.connect(), so the supervisor must
// inject the report it already probed — otherwise the adapter keeps its
// default (version unknown, no persistence) and the gate silently
// degrades to "always trust not-found".
await supervisor.start('/usr/bin/aria2c')
expect(adapter.setFeatureReport).toHaveBeenCalledWith(FEATURE_REPORT)
})
it('does not probe or load the text session while SQLite persistence is active', async () => {
vi.mocked(configBuilder.hasSavedSession).mockResolvedValue(true)
await supervisor.start('/usr/bin/aria2c')
expect(configBuilder.hasSavedSession).not.toHaveBeenCalled()
expect(configBuilder.buildArgs).toHaveBeenCalledWith(
expect.anything(),
true,
null,
expect.anything(),
'/Users/test/Downloads',
false
)
})
it('passes the configured default save directory on cold start', async () => {
await supervisor.start('/usr/bin/aria2c')
expect(configBuilder.buildArgs).toHaveBeenCalledWith(
expect.anything(),
true,
null,
expect.anything(),
'/Users/test/Downloads',
false
)
})
it('initializes continue for raw JSON-RPC tasks before becoming Ready', async () => {
vi.mocked(rpcClient.changeGlobalOption).mockImplementation(
async (opts) => {
expect(opts).toEqual({ continue: 'true' })
expect(supervisor.getState()).toBe(EngineState.Starting)
return 'OK'
}
)
await supervisor.start('/usr/bin/aria2c')
expect(rpcClient.changeGlobalOption).toHaveBeenCalledOnce()
expect(supervisor.getState()).toBe(EngineState.Ready)
})
it('loads an existing text session when SQLite is disabled in settings', async () => {
const configured = settings.getEngine()
vi.mocked(settings.getEngine).mockReturnValue({
...configured,
sqlite3Persistence: false,
})
vi.mocked(configBuilder.hasSavedSession).mockResolvedValue(true)
await supervisor.start('/usr/bin/aria2c')
expect(configBuilder.hasSavedSession).toHaveBeenCalledOnce()
expect(configBuilder.buildArgs).toHaveBeenCalledWith(
expect.objectContaining({ sqlite3Persistence: false }),
true,
null,
expect.anything(),
'/Users/test/Downloads',
true
)
})
it('loads an existing text session when the binary lacks SQLite support', async () => {
vi.mocked(processManager.probe).mockResolvedValue({
...FEATURE_REPORT,
version: '1.37.0',
features: ['Async DNS', 'BitTorrent'],
hasSqlitePersistence: false,
})
vi.mocked(configBuilder.hasSavedSession).mockResolvedValue(true)
await supervisor.start('/usr/bin/aria2c')
expect(configBuilder.hasSavedSession).toHaveBeenCalledOnce()
expect(configBuilder.buildArgs).toHaveBeenCalledWith(
expect.anything(),
false,
null,
expect.anything(),
'/Users/test/Downloads',
true
)
})
it('starts without input-file when the text session is missing', async () => {
const configured = settings.getEngine()
vi.mocked(settings.getEngine).mockReturnValue({
...configured,
sqlite3Persistence: false,
})
vi.mocked(configBuilder.hasSavedSession).mockResolvedValue(false)
await supervisor.start('/usr/bin/aria2c')
expect(configBuilder.hasSavedSession).toHaveBeenCalledOnce()
expect(configBuilder.buildArgs).toHaveBeenCalledWith(
expect.objectContaining({ sqlite3Persistence: false }),
true,
null,
expect.anything(),
'/Users/test/Downloads',
false
)
})
it('detects an official binary before spawn and starts with compatibility limits', async () => {
const officialReport: EngineFeatureReport = {
...FEATURE_REPORT,
version: '1.37.0',
features: ['Async DNS', 'BitTorrent'],
hasSqlitePersistence: false,
}
vi.mocked(processManager.probe).mockResolvedValue(officialReport)
const configured = settings.getEngine()
vi.mocked(settings.getEngine).mockReturnValue({
...configured,
performanceProfile: 'custom',
maxConnectionPerServer: 64,
split: 32,
})
const warning = vi.fn()
eventBus.on(Events.EngineCompatibilityWarning, warning)
await supervisor.start('/usr/bin/aria2c')
expect(warning).toHaveBeenCalledWith({
version: '1.37.0',
connectionLimit: 16,
})
expect(configBuilder.buildArgs).toHaveBeenCalledWith(
expect.objectContaining({
maxConnectionPerServer: 16,
split: 16,
}),
false,
null,
expect.anything(),
'/Users/test/Downloads',
false
)
expect(rpcClient.getVersion).not.toHaveBeenCalled()
expect(settings.update).toHaveBeenCalledWith({
engine: {
performanceProfile: 'custom',
maxConnectionPerServer: 16,
split: 16,
},
})
expect(
vi.mocked(processManager.probe).mock.invocationCallOrder[0]
).toBeLessThan(
vi.mocked(processManager.spawn).mock.invocationCallOrder[0]
)
})
it('keeps starting with runtime limits if persisting compatibility settings fails', async () => {
vi.mocked(processManager.probe).mockResolvedValue({
...FEATURE_REPORT,
version: '1.37.0',
features: ['Async DNS', 'BitTorrent'],
hasSqlitePersistence: false,
})
vi.mocked(settings.update).mockRejectedValue(new Error('disk full'))
await supervisor.start('/usr/bin/aria2c')
expect(supervisor.getState()).toBe(EngineState.Ready)
expect(configBuilder.buildArgs).toHaveBeenCalledWith(
expect.objectContaining({
maxConnectionPerServer: 16,
split: 16,
}),
false,
null,
expect.anything(),
'/Users/test/Downloads',
false
)
})
it('keeps Motrix fork connection settings above the official ceiling', async () => {
const configured = settings.getEngine()
vi.mocked(settings.getEngine).mockReturnValue({
...configured,
performanceProfile: 'custom',
maxConnectionPerServer: 64,
split: 32,
})
await supervisor.start('/usr/bin/aria2c')
expect(configBuilder.buildArgs).toHaveBeenCalledWith(
expect.objectContaining({
maxConnectionPerServer: 64,
split: 32,
}),
true,
null,
expect.anything(),
'/Users/test/Downloads',
false
)
})
it('does not overwrite persisted tuning settings during engine start', async () => {
await supervisor.start('/usr/bin/aria2c')
expect(settings.update).not.toHaveBeenCalled()
})
it('applies automatic storage tuning to runtime args', async () => {
probePreciseMock.mockResolvedValue({
platform: 'linux',
mountPoint: '/downloads',
fsType: 'ext4',
diskType: 'hdd',
isInternal: true,
isNetworkFs: false,
freeBytes: 100 * 1024 * 1024 * 1024,
confidence: 'high',
})
await supervisor.start('/usr/bin/aria2c')
expect(configBuilder.buildArgs).toHaveBeenCalledWith(
expect.objectContaining({
performanceProfile: 'auto',
diskCache: 64 * 1024 * 1024,
split: 8,
minSplitSize: 20 * 1024 * 1024,
}),
expect.anything(),
null,
expect.anything(),
'/Users/test/Downloads',
false
)
expect(settings.update).not.toHaveBeenCalled()
})
it('keeps custom performance values unchanged at runtime', async () => {
const configured = settings.getEngine()
vi.mocked(settings.getEngine).mockReturnValue({
...configured,
performanceProfile: 'custom',
diskCache: 48 * 1024 * 1024,
split: 24,
minSplitSize: 2 * 1024 * 1024,
})
await supervisor.start('/usr/bin/aria2c')
expect(probePreciseMock).not.toHaveBeenCalled()
expect(configBuilder.buildArgs).toHaveBeenCalledWith(
expect.objectContaining({
performanceProfile: 'custom',
diskCache: 48 * 1024 * 1024,
split: 24,
minSplitSize: 2 * 1024 * 1024,
}),
expect.anything(),
null,
expect.anything(),
'/Users/test/Downloads',
false
)
})
})
it('repairs persisted identities before the completed-task guard and spawn', async () => {
const prepare = vi.fn().mockResolvedValue(null)
supervisor.setStartupGuard({ prepare })
await supervisor.start('/usr/bin/aria2c')
expect(recoverSessionMock).toHaveBeenCalledWith(
'/tmp/aria2.db',
expect.any(Function),
undefined
)
expect(recoverSessionMock.mock.invocationCallOrder.at(-1)).toBeLessThan(
prepare.mock.invocationCallOrder[0]!
)
expect(prepare.mock.invocationCallOrder[0]).toBeLessThan(
vi.mocked(processManager.spawn).mock.invocationCallOrder[0]!
)
})
it('does not repair or spawn when the RPC port is occupied', async () => {
vi.mocked(checkPort).mockResolvedValueOnce(false)
const calls = recoverSessionMock.mock.calls.length
await supervisor.start('/usr/bin/aria2c')
expect(recoverSessionMock).toHaveBeenCalledTimes(calls)
expect(processManager.spawn).not.toHaveBeenCalled()
})
it('does not spawn when identity recovery fails', async () => {
recoverSessionMock.mockRejectedValueOnce(
new Error('saved metadata unavailable')
)
await supervisor.start('/usr/bin/aria2c')
expect(supervisor.getState()).toBe(EngineState.Failed)
expect(processManager.spawn).not.toHaveBeenCalled()
expect(supervisor.getLastError()).toBe('saved metadata unavailable')
})
it('starts after durable per-task quarantine and passes the application recovery store', async () => {
const store = {
getContext: vi.fn(() => ({ metadataPaths: [], retired: false })),
quarantine: vi.fn().mockResolvedValue(undefined),
}
supervisor.setSessionRecoveryStore(store)
recoverSessionMock.mockResolvedValueOnce({
backupPath: '/backup/aria2.db',
repairedGids: [],
retiredMetadataGids: ['1111111111111111'],
quarantinedGids: ['2222222222222222'],
})
await supervisor.start('/usr/bin/aria2c')
expect(recoverSessionMock).toHaveBeenLastCalledWith(
'/tmp/aria2.db',
expect.any(Function),
store
)
expect(processManager.spawn).toHaveBeenCalledOnce()
expect(supervisor.getState()).toBe(EngineState.Ready)
})
it('preserves only the GID conflict diagnostic when RPC fails', async () => {
vi.mocked(rpcClient.connect).mockRejectedValueOnce(
new Error('ECONNREFUSED')
)
vi.mocked(processManager.getRecentStderr).mockReturnValue(
'private-url\nGID 283f007637e2399d is not unique.\nCookie: private'
)
await supervisor.start('/usr/bin/aria2c')
expect(supervisor.getLastError()).toBe(
'GID 283f007637e2399d is not unique.'
)
expect(configBuilder.quarantineSqliteDatabase).not.toHaveBeenCalled()
})
describe('start — probe failure', () => {
it('transitions to Failed when probe rejects', async () => {
vi.mocked(processManager.probe).mockRejectedValue(
new Error('Binary not found')
)
await supervisor.start('/bad/path')
expect(supervisor.getState()).toBe(EngineState.Failed)
})
})
describe('start — spawn failure', () => {
it('transitions to Failed when spawn rejects', async () => {
vi.mocked(processManager.spawn).mockRejectedValue(new Error('ENOENT'))
await supervisor.start('/usr/bin/aria2c')
expect(supervisor.getState()).toBe(EngineState.Failed)
})
})
describe('start — RPC connect failure', () => {
it('transitions to Failed when RPC connect rejects', async () => {
vi.mocked(rpcClient.connect).mockRejectedValue(
new Error('Connection refused')
)
await supervisor.start('/usr/bin/aria2c')
expect(supervisor.getState()).toBe(EngineState.Failed)
expect(processManager.gracefulStop).toHaveBeenCalledWith(5_000)
expect(rpcClient.disconnect).toHaveBeenCalled()
})
it('quarantines proven aria2 SQLite corruption and retries once with text persistence', async () => {
vi.mocked(configBuilder.hasSavedSession).mockResolvedValue(true)
vi.mocked(processManager.getRecentStderr).mockReturnValue(
'SQLite error: database disk image is malformed'
)
vi.mocked(rpcClient.connect)
.mockRejectedValueOnce(new Error('Connection refused'))
.mockResolvedValueOnce(undefined)
const failures: EngineFailurePayload[] = []
eventBus.on(Events.EngineFailureOccurred, (payload) => {
failures.push(payload as EngineFailurePayload)
})
await supervisor.start('/usr/bin/aria2c')
expect(supervisor.getState()).toBe(EngineState.Ready)
expect(configBuilder.quarantineSqliteDatabase).toHaveBeenCalledOnce()
expect(settings.update).toHaveBeenCalledWith({
engine: { sqlite3Persistence: false },
})
expect(processManager.spawn).toHaveBeenCalledTimes(2)
expect(configBuilder.buildArgs).toHaveBeenLastCalledWith(
expect.objectContaining({ sqlite3Persistence: false }),
true,
null,
expect.anything(),
'/Users/test/Downloads',
true
)
expect(failures).toHaveLength(0)
})
it('does not downgrade SQLite for lock or disk failures', async () => {
vi.mocked(processManager.getRecentStderr).mockReturnValue(
'SQLite error: database is locked'
)
vi.mocked(rpcClient.connect).mockRejectedValue(
new Error('Connection refused')
)
await supervisor.start('/usr/bin/aria2c')
expect(supervisor.getState()).toBe(EngineState.Failed)
expect(configBuilder.quarantineSqliteDatabase).not.toHaveBeenCalled()
expect(settings.update).not.toHaveBeenCalled()
})
})
describe('stop', () => {
it('on stop: SIGTERMs aria2 with 30s graceful timeout, no RPC chatter', async () => {
await supervisor.start('/usr/bin/aria2c')
await supervisor.stop()
expect(rpcClient.saveSession).not.toHaveBeenCalled()
expect(rpcClient.shutdown).not.toHaveBeenCalled()
expect(processManager.gracefulStop).toHaveBeenCalledWith(30_000)
expect(supervisor.getState()).toBe(EngineState.Stopped)
})
it('emits EngineStateChanged(Stopped)', async () => {
await supervisor.start('/usr/bin/aria2c')
const states: EngineState[] = []
eventBus.on(Events.EngineStateChanged, (state) => {
states.push(state as EngineState)
})
await supervisor.stop()
expect(states).toContain(EngineState.Stopped)
})
it('is safe to call when already stopped', async () => {
await supervisor.stop()
expect(supervisor.getState()).toBe(EngineState.Stopped)
})
it('stops a tracked aria2 process even when state is Failed', async () => {
vi.mocked(processManager.probe).mockRejectedValue(
new Error('Binary not found')
)
await supervisor.start('/bad/path')
vi.mocked(processManager.gracefulStop).mockClear()
await supervisor.stop()
expect(processManager.gracefulStop).toHaveBeenCalledWith(30_000)
expect(supervisor.getState()).toBe(EngineState.Stopped)
})
})
describe('health check', () => {
it('calls getVersion every 30s when Ready', async () => {
await supervisor.start('/usr/bin/aria2c')
vi.mocked(rpcClient.getVersion).mockClear()
// Advance past heartbeat interval
await vi.advanceTimersByTimeAsync(30_000)
expect(rpcClient.getVersion).toHaveBeenCalledTimes(1)
await vi.advanceTimersByTimeAsync(30_000)
expect(rpcClient.getVersion).toHaveBeenCalledTimes(2)
})
it('triggers restart after 3 consecutive heartbeat failures', async () => {
await supervisor.start('/usr/bin/aria2c')
vi.mocked(rpcClient.getVersion).mockRejectedValue(new Error('Timeout'))
const states: EngineState[] = []
eventBus.on(Events.EngineStateChanged, (state) => {
states.push(state as EngineState)
})
// 3 consecutive failures at 30s intervals
await vi.advanceTimersByTimeAsync(30_000)
await vi.advanceTimersByTimeAsync(30_000)
await vi.advanceTimersByTimeAsync(30_000)
expect(states).toContain(EngineState.Restarting)
})
it('resets failure counter on successful heartbeat', async () => {
await supervisor.start('/usr/bin/aria2c')
// 2 failures
vi.mocked(rpcClient.getVersion).mockRejectedValueOnce(
new Error('Timeout')
)
vi.mocked(rpcClient.getVersion).mockRejectedValueOnce(
new Error('Timeout')
)
// Then success
vi.mocked(rpcClient.getVersion).mockResolvedValueOnce({
version: '1.37.0',
enabledFeatures: [],
})
await vi.advanceTimersByTimeAsync(30_000) // fail 1
await vi.advanceTimersByTimeAsync(30_000) // fail 2
await vi.advanceTimersByTimeAsync(30_000) // success — resets counter
expect(supervisor.getState()).toBe(EngineState.Ready)
})
})
describe('restart with backoff', () => {
it('uses exponential backoff delays', async () => {
await supervisor.start('/usr/bin/aria2c')
// Trigger restart by simulating process exit
const onExit = vi.mocked(processManager).onExit
expect(onExit).not.toBeNull()
// We need to verify the supervisor transitions to Restarting
// and then attempts restart after backoff delay
const states: EngineState[] = []
eventBus.on(Events.EngineStateChanged, (state) => {
states.push(state as EngineState)
})
// Simulate process unexpected exit
if (processManager.onExit) {
processManager.onExit(1, null)
}
expect(states).toContain(EngineState.Restarting)
})
it('transitions to Failed after MAX_RESTARTS', async () => {
await supervisor.start('/usr/bin/aria2c')
// Make all restart attempts fail
vi.mocked(processManager.spawn).mockRejectedValue(
new Error('Spawn failed')
)
const states: EngineState[] = []
eventBus.on(Events.EngineStateChanged, (state) => {
states.push(state as EngineState)
})
// Trigger restart
if (processManager.onExit) {
processManager.onExit(1, null)
}
// Advance through all 5 restart attempts with their backoff
// delays: 1s, 2s, 4s, 8s, 16s = 31s total
for (let i = 0; i < 5; i++) {
await vi.advanceTimersByTimeAsync(30_000)
}
expect(states).toContain(EngineState.Failed)
})
})
describe('port check', () => {
// Real port binding is an integration concern; checkPort is
// mocked at the module boundary above.
it('proceeds normally when port is available', async () => {
// Default mock: no port conflict
await supervisor.start('/usr/bin/aria2c')
expect(supervisor.getState()).toBe(EngineState.Ready)
})
})
describe('restart (manual composite)', () => {
it('stops then starts using the previously-recorded binary path', async () => {
// Drive the supervisor through a successful start so binaryPath is set.
await supervisor.start('/usr/bin/aria2c')
expect(supervisor.getState()).toBe(EngineState.Ready)
const stopSpy = vi.spyOn(supervisor, 'stop')
const startSpy = vi.spyOn(supervisor, 'start')
await supervisor.restart()
expect(stopSpy).toHaveBeenCalledOnce()
expect(startSpy).toHaveBeenCalledOnce()
expect(startSpy).toHaveBeenCalledWith('/usr/bin/aria2c')
// stop must run before start
expect(stopSpy.mock.invocationCallOrder[0]).toBeLessThan(
startSpy.mock.invocationCallOrder[0]
)
})
it('throws if called before start (no binary path stored)', async () => {
// Fresh supervisor that has never been started — binaryPath is null.
await expect(supervisor.restart()).rejects.toThrow(
'EngineSupervisor.restart called before start'
)
})
it('coalesces concurrent restart requests into one stop/start cycle', async () => {
await supervisor.start('/usr/bin/aria2c')
const stopStarted = vi.fn()
let releaseStop!: () => void
const stopGate = new Promise<void>((resolve) => {
releaseStop = resolve
})
vi.mocked(processManager.gracefulStop).mockImplementationOnce(
async () => {
stopStarted()
await stopGate
}
)
const stopSpy = vi.spyOn(supervisor, 'stop')
const startSpy = vi.spyOn(supervisor, 'start')
const first = supervisor.restart()
const second = supervisor.restart()
expect(second).toBe(first)
expect(stopStarted).toHaveBeenCalledOnce()
expect(stopSpy).toHaveBeenCalledOnce()
expect(startSpy).not.toHaveBeenCalled()
releaseStop()
await Promise.all([first, second])
expect(stopSpy).toHaveBeenCalledOnce()
expect(startSpy).toHaveBeenCalledOnce()
expect(startSpy).toHaveBeenCalledWith('/usr/bin/aria2c')
})
it('clears the single-flight guard after a restart failure', async () => {
await supervisor.start('/usr/bin/aria2c')
vi.mocked(processManager.gracefulStop).mockRejectedValueOnce(
new Error('stop failed')
)
await expect(supervisor.restart()).rejects.toThrow('stop failed')
await expect(supervisor.restart()).resolves.toBeUndefined()
expect(processManager.gracefulStop).toHaveBeenCalledTimes(2)
expect(supervisor.getState()).toBe(EngineState.Ready)
})
})
describe('EngineFailureOccurred', () => {
function collectFailures(): EngineFailurePayload[] {
const payloads: EngineFailurePayload[] = []
eventBus.on(Events.EngineFailureOccurred, (payload) => {
payloads.push(payload as EngineFailurePayload)
})
return payloads
}
it('emits exactly once on a cold-start spawn failure, with reason and a fresh incidentId', async () => {
vi.mocked(processManager.spawn).mockRejectedValue(new Error('ENOENT'))
const payloads = collectFailures()
await supervisor.start('/usr/bin/aria2c')
expect(supervisor.getState()).toBe(EngineState.Failed)
expect(payloads).toHaveLength(1)
expect(payloads[0]).toMatchObject({
reason: EngineFailureReason.SpawnFailed,
technicalMessage: 'ENOENT',
})
expect(payloads[0].incidentId).toMatch(/^engine:\d+:\d+$/)
expect(typeof payloads[0].occurredAt).toBe('number')
})
it('stop() emits EngineDisconnected but never EngineFailureOccurred', async () => {
await supervisor.start('/usr/bin/aria2c')
const payloads = collectFailures()
const disconnected = vi.fn()
eventBus.on(Events.EngineDisconnected, disconnected)
await supervisor.stop()
expect(disconnected).toHaveBeenCalledOnce()
expect(payloads).toHaveLength(0)
})
it('suppresses a process exit as soon as app shutdown is prepared', async () => {
await supervisor.start('/usr/bin/aria2c')
const payloads = collectFailures()
supervisor.prepareForShutdown()
processManager.onExit?.(1, null)
expect(payloads).toHaveLength(0)
expect(supervisor.getState()).toBe(EngineState.Ready)
await supervisor.stop()
})
it('restart() emits no EngineFailureOccurred on a successful manual restart', async () => {
await supervisor.start('/usr/bin/aria2c')
const payloads = collectFailures()
await supervisor.restart()
expect(supervisor.getState()).toBe(EngineState.Ready)
expect(payloads).toHaveLength(0)
})
it('assigns two distinct incidentIds across two consecutive cold-start failures', async () => {
vi.mocked(processManager.spawn).mockRejectedValue(new Error('ENOENT'))
const payloads = collectFailures()
await supervisor.start('/usr/bin/aria2c')
await supervisor.start('/usr/bin/aria2c')
expect(payloads).toHaveLength(2)
expect(payloads[0].incidentId).not.toBe(payloads[1].incidentId)
})
describe('cold-start delivery to the notification center', () => {
// Regression pin for the bootstrap-ordering bug: both shells used to
// wire registerEngineFailureSubscriber() only after a successful
// supervisor.start() (gated behind the Ready-state check), so a
// failure on the very first boot — the case this feature exists
// for — emitted with no subscriber listening and the notification
// was silently dropped. The fix hoists the NotificationCenter +
// registerEngineFailureSubscriber() construction to run BEFORE
// supervisor.start() in both src/main/index.ts and
// src/server/index.ts. This test reproduces that exact ordering
// end-to-end against a real in-memory MotrixDatabase, so reverting
// the bootstrap order (or the subscriber wiring) fails here first.
let db: MotrixDatabase
beforeEach(() => {
db = new MotrixDatabase(':memory:')
db.init()
})
afterEach(() => {
db.close()
})
it('delivers a notification row for a failure on the very first cold start', async () => {
const center = new NotificationCenter({
store: db,
emit: eventBus.emit.bind(eventBus),
log: { warn: vi.fn(), error: vi.fn() },
})
// Subscriber wired BEFORE start() — mirrors the fixed bootstrap
// order, not the pre-fix order (wired only after a Ready check).
registerEngineFailureSubscriber({
motrixDb: db,
eventBus,
notificationCenter: center,
log: { warn: vi.fn() },
})
vi.mocked(processManager.spawn).mockRejectedValue(new Error('ENOENT'))
await supervisor.start('/usr/bin/aria2c')
expect(supervisor.getState()).toBe(EngineState.Failed)
const rows = center.list()
expect(rows).toHaveLength(1)
expect(rows[0]).toMatchObject({
kind: NotificationKinds.EngineFailure,
severity: 'error',
titleKey: 'notification.engineFailure.title',
bodyKey: 'panel.dashboard.engine.diagnostics.reason.spawn_failed',
taskId: null,
})
})
it('a throwing store write inside the notification subscriber never blocks recordFailure() from completing its own state transition', async () => {
// Regression pin for the isolation fix in
// engine-failure-subscriber.ts: notify()'s store write
// (insertNotificationWithLedger) can throw (SQLITE_FULL etc.).
// EventBus.emit has no per-listener isolation, so a subscriber
// throw used to unwind straight through
// EngineSupervisor.recordFailure() and abort the caller's own
// setState(Failed) transition. Same cold-start wiring order as
// the test above, but with a store whose write always throws.
const throwingStore = {
deleteEngineNotificationLedgerBefore: vi.fn(() => 0),
insertNotificationWithLedger: vi.fn(() => {
throw new Error('SQLITE_FULL')
}),
} as unknown as MotrixDatabase
const log = { warn: vi.fn(), error: vi.fn() }
const center = new NotificationCenter({
store: throwingStore,
emit: eventBus.emit.bind(eventBus),
log,
})
registerEngineFailureSubscriber({
motrixDb: throwingStore,
eventBus,
notificationCenter: center,
log,
})
vi.mocked(processManager.spawn).mockRejectedValue(new Error('ENOENT'))
await supervisor.start('/usr/bin/aria2c')
expect(supervisor.getState()).toBe(EngineState.Failed)
expect(log.warn).toHaveBeenCalledOnce()
})
})
})
describe('manual recovery', () => {
it('includes the current transport state even before lifecycle health checks catch up', async () => {
await supervisor.start('/usr/bin/aria2c')
vi.mocked(rpcClient.getConnectionStatus).mockReturnValue({
transport: 'websocket',
connected: false,
})
const report = await supervisor.diagnose()
expect(report.state).toBe(EngineState.Ready)
expect(report.rpc.connection).toEqual({
transport: 'websocket',
connected: false,
})
})
function useFallbackPort(): { rpcPort: number } {
const engineSettings = {
...settings.getEngine(),
rpcPort: 16801,
}
vi.mocked(settings.getEngine).mockImplementation(() => engineSettings)
vi.mocked(settings.update).mockImplementation(async (patch) => {
if (typeof patch.engine?.rpcPort === 'number') {
engineSettings.rpcPort = patch.engine.rpcPort
}
return undefined as never
})
return engineSettings
}
it('revalidates the pid before force stopping and restarts on the same port', async () => {
await supervisor.start('/usr/bin/aria2c')
const result = await supervisor.recover({
action: EngineRecoveryAction.ForceTerminate,
expectedPid: 4321,
})
expect(processManager.forceTerminateVerified).toHaveBeenCalledWith(
4321,
16800,
expect.objectContaining({ binaryPath: '/usr/bin/aria2c' })
)
expect(result).toMatchObject({
ok: true,
previousRpcPort: 16800,
rpcPort: 16800,
})
})
it('persists and restarts on port 16800 when restoring a free default port', async () => {
useFallbackPort()
await supervisor.start('/usr/bin/aria2c')
const result = await supervisor.recover({
action: EngineRecoveryAction.RestoreDefaultPort,
})
expect(settings.update).toHaveBeenCalledWith({
engine: { rpcPort: 16800 },
})
expect(result).toMatchObject({
ok: true,
previousRpcPort: 16801,
rpcPort: 16800,
})
})
it('revalidates and stops a verified orphan before restoring port 16800', async () => {
useFallbackPort()
let defaultPortAvailable = false
vi.mocked(checkPort).mockImplementation(async (port) =>
port === 16800 ? defaultPortAvailable : true
)
vi.mocked(processManager.inspectPort).mockResolvedValue({
pid: 4321,
name: 'aria2c',
executableName: 'aria2c',
ownership: EngineProcessOwnership.VerifiedOrphan,
safeToTerminate: true,
})
vi.mocked(processManager.forceTerminateVerified).mockImplementation(
async () => {
defaultPortAvailable = true
}
)
await supervisor.start('/usr/bin/aria2c')
const result = await supervisor.recover({
action: EngineRecoveryAction.RestoreDefaultPort,
expectedPid: 4321,
})
expect(processManager.forceTerminateVerified).toHaveBeenCalledWith(
4321,
16800,
expect.objectContaining({ binaryPath: '/usr/bin/aria2c' })
)
expect(settings.update).toHaveBeenCalledWith({
engine: { rpcPort: 16800 },
})
expect(result.rpcPort).toBe(16800)
})
it('protects an unverified process using the default port', async () => {
useFallbackPort()
vi.mocked(checkPort).mockImplementation(async (port) => port !== 16800)
vi.mocked(processManager.inspectPort).mockResolvedValue({
pid: 4321,
name: 'aria2c',
executableName: 'aria2c',
ownership: EngineProcessOwnership.ExternalAria2,
safeToTerminate: false,
})
await supervisor.start('/usr/bin/aria2c')
await expect(
supervisor.recover({
action: EngineRecoveryAction.RestoreDefaultPort,
expectedPid: 4321,
})
).rejects.toMatchObject({
code: ErrorCode.EngineProcessOwnershipUnverified,
})
expect(processManager.forceTerminateVerified).not.toHaveBeenCalled()
expect(settings.update).not.toHaveBeenCalled()
})
it('reports whether a fallback session can safely restore port 16800', async () => {
useFallbackPort()
vi.mocked(checkPort).mockImplementation(async (port) => port === 16800)
await supervisor.start('/usr/bin/aria2c')
const report = await supervisor.diagnose()
expect(report.rpc.port).toBe(16801)
expect(report.defaultRpc).toEqual({
port: 16800,
isCurrent: false,
available: true,
process: null,
canRestore: true,
requiresTermination: false,
})
})
})
describe('applyAsyncDns', () => {
it('is a no-op unless Ready', async () => {
await supervisor.applyAsyncDns(false)
expect(rpcClient.changeGlobalOption).not.toHaveBeenCalled()
})
it.each([
[false, 'false'],
[true, 'true'],
] as const)(
'calls changeGlobalOption with async-dns=%s when Ready',
async (asyncDns, wire) => {
await supervisor.start('/usr/bin/aria2c')
vi.mocked(rpcClient.changeGlobalOption).mockClear()
await supervisor.applyAsyncDns(asyncDns)
expect(rpcClient.changeGlobalOption).toHaveBeenCalledWith({
'async-dns': wire,
})
}
)
})
describe('applyDefaultSaveDir', () => {
it('is a no-op unless Ready', async () => {
await supervisor.applyDefaultSaveDir('/downloads/next')
expect(rpcClient.changeGlobalOption).not.toHaveBeenCalled()
})
it('updates the global dir when Ready', async () => {
await supervisor.start('/usr/bin/aria2c')
vi.mocked(rpcClient.changeGlobalOption).mockClear()
await supervisor.applyDefaultSaveDir('/downloads/next')
expect(rpcClient.changeGlobalOption).toHaveBeenCalledExactlyOnceWith({
dir: '/downloads/next',
})
})
})
describe('applySpeedLimits', () => {
it('is a no-op unless Ready', async () => {
await supervisor.applySpeedLimits({ download: 100, upload: 50 })
expect(rpcClient.changeGlobalOption).not.toHaveBeenCalled()
})
it('calls changeGlobalOption with string values when Ready', async () => {
await supervisor.start('/usr/bin/aria2c')
vi.mocked(rpcClient.changeGlobalOption).mockClear()
await supervisor.applySpeedLimits({ download: 100, upload: 50 })
expect(rpcClient.changeGlobalOption).toHaveBeenCalledWith({
'max-overall-download-limit': '100',
'max-overall-upload-limit': '50',
})
})
it('passes effective limits from provider to buildArgs', async () => {
supervisor.setEffectiveLimitsProvider(() => ({
download: 500,
upload: 250,
}))
await supervisor.start('/usr/bin/aria2c')
expect(configBuilder.buildArgs).toHaveBeenCalledWith(
expect.anything(),
expect.anything(),
null,
{ download: 500, upload: 250 },
'/Users/test/Downloads',
false
)
})
it('passes 0/0 limits to buildArgs when no provider is registered', async () => {
// no setEffectiveLimitsProvider call
await supervisor.start('/usr/bin/aria2c')
expect(configBuilder.buildArgs).toHaveBeenCalledWith(
expect.anything(),
expect.anything(),
null,
{ download: 0, upload: 0 },
'/Users/test/Downloads',
false
)
})
})
describe('applyEngineSettings', () => {
it('never installs a global seeding timer during hot updates', async () => {
await supervisor.start('/usr/bin/aria2c')
vi.mocked(rpcClient.changeGlobalOption).mockClear()
const previous = settings.getEngine()
await supervisor.applyEngineSettings(previous, {
...previous,
seedTime: 0,
})
await supervisor.applyEngineSettings(
{ ...previous, seedTime: 0 },
{ ...previous, seedTime: 90 }
)
expect(rpcClient.changeGlobalOption).not.toHaveBeenCalled()
})
it('is a no-op unless Ready', async () => {
const previous = settings.getEngine()
await supervisor.applyEngineSettings(previous, {
...previous,
split: 32,
})
expect(rpcClient.changeGlobalOption).not.toHaveBeenCalled()
})
it('maps changed runtime settings and excludes startup-only settings', async () => {
await supervisor.start('/usr/bin/aria2c')
vi.mocked(rpcClient.changeGlobalOption).mockClear()
const previous = settings.getEngine()
await supervisor.applyEngineSettings(previous, {
...previous,
split: 32,
userAgent: 'Motrix/Test',
btEnableLpd: false,
remoteTime: true,
sessionSaveInterval: 30,
fileAllocation: 'prealloc',
diskCache: 32 * 1024 * 1024,
})
expect(rpcClient.changeGlobalOption).toHaveBeenCalledWith({
split: '32',
'user-agent': 'Motrix/Test',
'bt-enable-lpd': 'false',
'remote-time': 'true',
})
})
it('caps hot connection changes for a detected official aria2 binary', async () => {
vi.mocked(processManager.probe).mockResolvedValue({
...FEATURE_REPORT,
version: '1.37.0',
features: ['Async DNS', 'BitTorrent'],
hasSqlitePersistence: false,
})
await supervisor.start('/usr/bin/aria2c')
vi.mocked(rpcClient.changeGlobalOption).mockClear()
vi.mocked(settings.update).mockClear()
const settingsValue = settings.getEngine()
await supervisor.applyEngineSettings(
{
...settingsValue,
maxConnectionPerServer: 8,
split: 8,
},
{
...settingsValue,
maxConnectionPerServer: 64,
split: 32,
}
)
expect(rpcClient.changeGlobalOption).toHaveBeenCalledWith({
'max-connection-per-server': '16',
split: '16',
})
expect(settings.update).toHaveBeenCalledWith({
engine: {
performanceProfile: 'custom',
maxConnectionPerServer: 16,
split: 16,
},
})
})
})
describe('applyProxyChange', () => {
it('is no-op when state is not Ready', async () => {
// supervisor starts in Stopped — never started
await supervisor.applyProxyChange({
allProxy: 'http://p:80',
noProxy: '',
})
expect(rpcClient.changeGlobalOption).not.toHaveBeenCalled()
})
it('sends all-proxy + no-proxy when ready and opts provided', async () => {
await supervisor.start('/usr/bin/aria2c')
await supervisor.applyProxyChange({
allProxy: 'http://p:80',
noProxy: 'localhost',
})
expect(rpcClient.changeGlobalOption).toHaveBeenCalledWith({
'all-proxy': 'http://p:80',
'http-proxy': '',
'http-proxy-user': '',
'http-proxy-passwd': '',
'https-proxy': '',
'https-proxy-user': '',
'https-proxy-passwd': '',
'ftp-proxy': '',
'ftp-proxy-user': '',
'ftp-proxy-passwd': '',
'all-proxy-user': '',
'all-proxy-passwd': '',
'no-proxy': 'localhost',
'proxy-method': 'get',
})
})
it('clears proxy when opts is null', async () => {
await supervisor.start('/usr/bin/aria2c')
await supervisor.applyProxyChange(null)
expect(rpcClient.changeGlobalOption).toHaveBeenCalledWith({
'all-proxy': '',
'http-proxy': '',
'http-proxy-user': '',
'http-proxy-passwd': '',
'https-proxy': '',
'https-proxy-user': '',
'https-proxy-passwd': '',
'ftp-proxy': '',
'ftp-proxy-user': '',
'ftp-proxy-passwd': '',
'all-proxy-user': '',
'all-proxy-passwd': '',
'no-proxy': '',
'proxy-method': 'get',
})
})
it('pins decoded all-proxy credentials during a hot update', async () => {
await supervisor.start('/usr/bin/aria2c')
await supervisor.applyProxyChange({
allProxy: 'http://a%40b:p%3As@p:80',
noProxy: '',
})
expect(rpcClient.changeGlobalOption).toHaveBeenLastCalledWith(
expect.objectContaining({
'all-proxy': 'http://p:80',
'all-proxy-user': 'a@b',
'all-proxy-passwd': 'p:s',
'proxy-method': 'get',
})
)
})
it('accepts equivalent expanded IPv6 proxy authorities during a hot update', async () => {
await supervisor.start('/usr/bin/aria2c')
await supervisor.applyProxyChange({
allProxy: 'http://user:pass@[0:0:0:0:0:0:0:1]:8080',
noProxy: '',
})
expect(rpcClient.changeGlobalOption).toHaveBeenLastCalledWith(
expect.objectContaining({
'all-proxy': 'http://[0:0:0:0:0:0:0:1]:8080',
'all-proxy-user': 'user',
'all-proxy-passwd': 'pass',
})
)
})
it('preserves an aria2-compatible legacy IPv4 proxy during a hot update', async () => {
await supervisor.start('/usr/bin/aria2c')
await supervisor.applyProxyChange({
allProxy: 'http://user:[email protected]:8080',
noProxy: '',
})
expect(rpcClient.changeGlobalOption).toHaveBeenLastCalledWith(
expect.objectContaining({
'all-proxy': 'http://127.1:8080',
'all-proxy-user': 'user',
'all-proxy-passwd': 'pass',
})
)
})
})
describe('waitUntilReady', () => {
it('resolves immediately when the engine is already Ready', async () => {
await supervisor.start('/usr/bin/aria2c') // drives Stopped → Starting → Ready
expect(supervisor.getState()).toBe(EngineState.Ready)
await expect(supervisor.waitUntilReady(15_000)).resolves.toBeUndefined()
})
it('resolves when a later EngineStateChanged → Ready fires', async () => {
const p = supervisor.waitUntilReady(15_000) // state is Stopped → listens
eventBus.emit(Events.EngineStateChanged, EngineState.Ready)
await expect(p).resolves.toBeUndefined()
})
it('rejects with EngineTimeout when the engine goes Failed while waiting', async () => {
const p = supervisor.waitUntilReady(15_000)
eventBus.emit(Events.EngineStateChanged, EngineState.Failed)
await expect(p).rejects.toMatchObject({ code: ErrorCode.EngineTimeout })
})
it('rejects with EngineTimeout after the timeout elapses', async () => {
const p = supervisor.waitUntilReady(100)
const assertion = expect(p).rejects.toMatchObject({
code: ErrorCode.EngineTimeout,
})
await vi.advanceTimersByTimeAsync(100)
await assertion
})
it('removes its EngineStateChanged listener on settle (no leak)', async () => {
const offSpy = vi.spyOn(eventBus, 'off')
const p = supervisor.waitUntilReady(15_000)
eventBus.emit(Events.EngineStateChanged, EngineState.Ready)
await p
expect(offSpy).toHaveBeenCalledWith(
Events.EngineStateChanged,
expect.any(Function)
)
})
})
})