A full-featured download manager.
import path from 'node:path'
import { getLogger } from '@core/logger'
import type { CapabilityHost } from '@core/plugin/capabilities/interface'
import { CircuitBreaker } from '@core/plugin/circuit/circuit-breaker'
import { ArtifactMutationLeaseCoordinator } from '@core/plugin/finalize/artifact-mutation-lease'
import { NativeFinalizeFilesystemAdapter } from '@core/plugin/finalize/filesystem-adapter'
import { NativeFinalizeArtifactOperations } from '@core/plugin/finalize/native-artifact-operations'
import type { GrantsManager } from '@core/plugin/grants/grants-manager'
import { HookAuditLog } from '@core/plugin/hooks/audit-log'
import { HookOrchestrator } from '@core/plugin/hooks/hook-orchestrator'
import type { StagedMetadataOp } from '@core/plugin/hooks/staged-effects'
import type { ActivationDispatcher } from '@core/plugin/host/activation-dispatcher'
import type { PluginHost } from '@core/plugin/host/plugin-host'
import type { PluginInstaller } from '@core/plugin/install/plugin-installer'
import type { PluginRegistry } from '@core/plugin/plugin-registry'
import {
createLoggingPostDeliveryObservability,
type PostDeliveryObservability,
} from '@core/plugin/post/delivery-observability'
import type { PostDeliveryRetentionRepository } from '@core/plugin/post/delivery-retention'
import type { PostDeliveryRepository } from '@core/plugin/post/delivery-types'
import { DurableFinalizeRuntime } from '@core/session/durable-finalize-runtime'
import type { SessionManager } from '@core/session/session-manager'
import type { DownloadTask } from '@shared/types/task'
import type { TaskOccurrence } from '@shared/types/task-occurrence'
import type Database from 'better-sqlite3'
import { OperationService } from '../operations/operation-service'
import {
PluginHookRuntime,
type PluginTerminalPersistenceInput,
} from './plugin-hook-runtime'
export interface PluginRuntimeFactoryOptions {
activation: ActivationDispatcher
registry: PluginRegistry
grants: GrantsManager
host: PluginHost
installer: Pick<PluginInstaller, 'bindRetentionSink'>
capabilityHost: CapabilityHost
repository: PostDeliveryRepository & PostDeliveryRetentionRepository
database: Database.Database
session: Pick<
SessionManager,
| 'persistFinalizedArtifact'
| 'persistTaskWithPluginMetadata'
| 'bindPostDeliveryObservability'
| 'bindTerminalOccurrencePersistence'
>
persistTerminal(
task: DownloadTask,
occurrence: TaskOccurrence,
input: PluginTerminalPersistenceInput
): Promise<void>
getTask?(id: string): DownloadTask | undefined
authorizeOperationPath?(
candidate: string,
mode: 'input' | 'output'
): Promise<void>
pluginsDir: string
auditLogPath: string
finalizeSidecarPath: string
acquireTaskMutationLease?(taskId: string): Promise<{
release(): Promise<void>
}>
assertEngineQuiesced(taskId: string): Promise<void>
observability?: PostDeliveryObservability
}
export interface PluginRuntimeAssembly {
operations: OperationService
auditLog: HookAuditLog
orchestrator: HookOrchestrator
hooks: PluginHookRuntime
finalize: DurableFinalizeRuntime
finalizeFilesystem: NativeFinalizeFilesystemAdapter
persistTaskWithPluginMetadata(
task: DownloadTask,
operations: readonly StagedMetadataOp[],
beforeCommit?: () => void
): Promise<void>
}
/**
* The sole production assembly point for the Hook runtime shared by Electron
* and Server. It fails closed before returning when the native finalize
* boundary cannot provide every required filesystem primitive.
*/
export async function createPluginRuntime(
options: PluginRuntimeFactoryOptions
): Promise<PluginRuntimeAssembly> {
const breakerLog = getLogger('plugin:circuit')
const auditLog = new HookAuditLog(options.auditLogPath)
const observability =
options.observability ??
createLoggingPostDeliveryObservability(getLogger('plugin:post-delivery'))
// A misbehaving plugin must degrade, not brick the app: three consecutive
// failures on the same (plugin, hook) evict it from later chains and
// disable it. Without this a `pre-resolve` builtin that fails every
// beforeCreate blocks every new task, permanently (issue #2189).
const breaker = new CircuitBreaker({
onOpen: (pluginId, hook, reason) => {
breakerLog.warn(
{ pluginId, hook, reason },
'plugin circuit breaker opened; disabling plugin'
)
},
})
const orchestrator = new HookOrchestrator({
createLog: (pluginId) => options.capabilityHost.createLog(pluginId),
host: options.host,
activationDispatcher: options.activation,
breaker,
hookTimeoutMs: { series: 10_000, parallel: 30_000 },
pluginsDir: options.pluginsDir,
pluginStorageRootFor: (pluginId) =>
path.join(options.pluginsDir, pluginId, 'storage'),
capabilityHost: options.capabilityHost,
auditLog,
})
const hooks = new PluginHookRuntime({
activation: options.activation,
registry: options.registry,
grants: options.grants,
host: options.host,
capabilityHost: options.capabilityHost,
repository: options.repository,
persistTerminal: options.persistTerminal,
observability,
})
const finalizeFilesystem = new NativeFinalizeFilesystemAdapter(
options.finalizeSidecarPath
)
const finalizeOperations = new NativeFinalizeArtifactOperations(
finalizeFilesystem
)
try {
await finalizeOperations.assertSupported()
} catch (error) {
await finalizeFilesystem.dispose()
throw error
}
const finalize = new DurableFinalizeRuntime({
db: options.database,
session: options.session,
fs: finalizeOperations,
leases: new ArtifactMutationLeaseCoordinator([
...(options.acquireTaskMutationLease
? [
{
quiesce: async (taskId: string) => {
const lease = await options.acquireTaskMutationLease?.(taskId)
if (!lease) {
throw new Error('task mutation lease provider disappeared')
}
return () => lease.release()
},
},
]
: []),
{
quiesce: async (taskId) => {
await options.assertEngineQuiesced(taskId)
return () => undefined
},
},
{
quiesce: (taskId) => options.host.quiesceArtifactWriters(taskId),
},
]),
})
options.host.bindPluginUnavailable((pluginId, reason, at) =>
hooks.pluginUnavailable(pluginId, reason, at)
)
options.grants.bindPermissionRevoked((pluginId, permissions, at) =>
hooks.permissionRevoked(pluginId, permissions, at)
)
options.installer.bindRetentionSink(hooks)
options.session.bindPostDeliveryObservability(observability)
options.session.bindTerminalOccurrencePersistence((task, occurrence) =>
hooks.persistTerminal(task, occurrence)
)
const operations = new OperationService({
registry: options.registry,
host: options.host,
capabilities: options.capabilityHost,
binary: options.finalizeSidecarPath,
storage: path.join(path.dirname(options.auditLogPath), 'operations'),
getTask: options.getTask ?? (() => undefined),
authorizePath: options.authorizeOperationPath,
})
await operations.initialize()
options.host.bindOperationsShutdown(() => operations.shutdown())
return {
operations,
auditLog,
orchestrator,
hooks,
finalize,
finalizeFilesystem,
persistTaskWithPluginMetadata: (task, operations, beforeCommit) =>
options.session.persistTaskWithPluginMetadata(
task,
operations,
beforeCommit
),
}
}