feat(wsl): prefetch the pinned Node archive when WSL hosts turn on (#36500)

A first WSL deploy downloads the pinned Linux Node archive (about 55 MB)
while the user waits, and fails on a network that blocks it. Once the WSL
hosts flag is open and the setting is on, fetch it in the background into
the cache the deploy reads, through the same materializer (mirror, proxy,
hash check). Once per run, deduped, never boots a distro; a failure is
logged and the deploy's download path is unchanged.
This commit is contained in:
Neil
2026-10-30 17:06:45 -07:00
committed by GitHub
parent 57bc1778dc
commit 86d1623009
3 changed files with 243 additions and 0 deletions
+4
View File
@@ -43,6 +43,7 @@ import {
} from '../wsl/wsl-orcad-host-account-push'
import { wslOrcadHostSupports } from '../wsl/wsl-orcad-host-environments'
import { wslHostConnectOptions } from '../wsl/wsl-host-connect-request'
import { wireWslNodeRuntimePrefetch } from '../wsl/wsl-node-runtime-prefetch'
export const WSL_HOST_HANDLER_CHANNELS = [
'wslHosts:listDistros',
@@ -194,6 +195,9 @@ function startService(args: WslHostHandlerArgs): WslHostService | null {
return null
}
setWslHostService(created)
if (process.platform === 'win32' && !readFakeWslHostsConfig() && created.hasServerFiles()) {
wireWslNodeRuntimePrefetch({ store: args.store, userDataPath: args.getUserDataPath() })
}
args.store.onSettingsChanged((updates, settings) => {
if (changesWslHostAccounts(updates)) {
for (const status of created.getStatuses()) {
@@ -0,0 +1,144 @@
import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { dirname, join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { orcadNodeRuntimeInstallOptions } from '../ssh/orcad-node-runtime-install-options'
import {
prefetchWslNodeRuntime,
resetWslNodeRuntimePrefetchForTests,
wireWslNodeRuntimePrefetch,
wslNodeRuntimePrefetchTarget,
type WslNodeRuntimePrefetchWiring
} from './wsl-node-runtime-prefetch'
type Listener = Parameters<WslNodeRuntimePrefetchWiring['store']['onSettingsChanged']>[0]
let userDataPath: string
beforeEach(async () => {
resetWslNodeRuntimePrefetchForTests()
userDataPath = await mkdtemp(join(tmpdir(), 'orca-wsl-node-prefetch-'))
})
afterEach(async () => {
vi.restoreAllMocks()
await rm(userDataPath, { recursive: true, force: true })
})
function fakeStore(enabled: boolean) {
const listeners: Listener[] = []
let current = enabled
return {
store: {
getSettings: () => ({ experimentalWslHosts: current }),
onSettingsChanged: (listener: Listener) => {
listeners.push(listener)
}
},
set(next: boolean) {
current = next
for (const listener of listeners) {
listener({ experimentalWslHosts: next }, { experimentalWslHosts: next })
}
}
}
}
function wire(options: { enabled: boolean; gateOpen: boolean }) {
const settings = fakeStore(options.enabled)
const scheduled: (() => void)[] = []
const materialize = vi.fn(async () => 'archive')
wireWslNodeRuntimePrefetch({
userDataPath,
arch: 'x64',
materialize,
store: settings.store,
gateOpen: () => options.gateOpen,
schedule: (run) => scheduled.push(run)
})
return { settings, scheduled, materialize }
}
describe('wslNodeRuntimePrefetchTarget', () => {
it('matches the build architecture without asking a distro', () => {
expect(wslNodeRuntimePrefetchTarget('x64')).toBe('linux-x64-glibc')
expect(wslNodeRuntimePrefetchTarget('arm64')).toBe('linux-arm64-glibc')
})
})
describe('wireWslNodeRuntimePrefetch', () => {
it('prefetches into the cache a WSL deploy reads, once the setting is on and the flag open', async () => {
const { scheduled, materialize } = wire({ enabled: true, gateOpen: true })
expect(materialize).not.toHaveBeenCalled()
expect(scheduled).toHaveLength(1)
scheduled[0]()
await prefetchWslNodeRuntime({ userDataPath })
const deployCache = join(userDataPath, 'orcad-artifacts')
expect(materialize).toHaveBeenCalledWith('linux-x64-glibc', deployCache, {})
})
it('never runs while the WSL hosts flag is closed, even when the setting turns on', () => {
const { settings, scheduled } = wire({ enabled: true, gateOpen: false })
settings.set(false)
settings.set(true)
expect(scheduled).toHaveLength(0)
})
it('waits for the setting to turn on, then schedules only once', () => {
const { settings, scheduled } = wire({ enabled: false, gateOpen: true })
expect(scheduled).toHaveLength(0)
settings.set(true)
settings.set(false)
settings.set(true)
expect(scheduled).toHaveLength(1)
})
})
describe('prefetchWslNodeRuntime', () => {
it('shares one download between concurrent callers', async () => {
let finish: (path: string) => void = () => {}
const materialize = vi.fn(
() =>
new Promise<string>((resolve) => {
finish = resolve
})
)
const first = prefetchWslNodeRuntime({ userDataPath, arch: 'arm64', materialize })
const second = prefetchWslNodeRuntime({ userDataPath, arch: 'arm64', materialize })
expect(second).toBe(first)
await vi.waitFor(() => expect(materialize).toHaveBeenCalledTimes(1))
finish('archive')
await first
expect(materialize).toHaveBeenCalledWith(
'linux-arm64-glibc',
join(userDataPath, 'orcad-artifacts'),
{}
)
})
it('swallows a failed download and does not retry it this run', async () => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
const materialize = vi.fn(async () => {
throw new Error('getaddrinfo ENOTFOUND nodejs.org')
})
await expect(prefetchWslNodeRuntime({ userDataPath, materialize })).resolves.toBeUndefined()
await prefetchWslNodeRuntime({ userDataPath, materialize })
expect(materialize).toHaveBeenCalledTimes(1)
expect(warn).toHaveBeenCalledWith(expect.stringContaining('a first connect downloads it'))
})
it('skips the download when the deploy cache already has the archive', async () => {
const target = wslNodeRuntimePrefetchTarget('x64')
// The path a WSL deploy names as its offline archive is the one the prefetch fills.
const cached = orcadNodeRuntimeInstallOptions(
target,
join(userDataPath, 'orcad-artifacts'),
{}
).nodeRuntimeOfflineArchivePath
await mkdir(dirname(cached), { recursive: true })
await writeFile(cached, 'archive')
const materialize = vi.fn(async () => cached)
await prefetchWslNodeRuntime({ userDataPath, arch: 'x64', materialize })
expect(materialize).not.toHaveBeenCalled()
})
})
+95
View File
@@ -0,0 +1,95 @@
import { existsSync } from 'node:fs'
import { join } from 'node:path'
import type { NodeRuntimeTarget } from '../../shared/node-runtime-pin'
import type { GlobalSettings } from '../../shared/global-settings-types'
import { errorMessage } from '../../shared/error-message'
import {
materializeNodeRuntimeArchive,
nodeRuntimeArchiveCachePath
} from '../node-runtime/pinned-runtime-materializer'
import { wslHostsGateOpen } from './wsl-host-gate'
/** Off the startup path; the archive is about 55 MB. */
const PREFETCH_DELAY_MS = 60_000
let started: Promise<void> | null = null
export type WslNodeRuntimePrefetchOptions = {
userDataPath: string
/** The build's architecture: an x64 Orca runs x64 WSL distros, an arm64 one arm64. */
arch?: string
materialize?: typeof materializeNodeRuntimeArchive
}
/** Known without asking a distro, so a prefetch never boots one (E9). */
export function wslNodeRuntimePrefetchTarget(arch: string = process.arch): NodeRuntimeTarget {
return arch === 'arm64' ? 'linux-arm64-glibc' : 'linux-x64-glibc'
}
/**
* Once per run, caches the pinned Node archive a first WSL deploy uploads, through the deploy's own
* materializer (mirror, proxy, hash check). Failures leave the deploy's download path as it was.
*/
export function prefetchWslNodeRuntime(options: WslNodeRuntimePrefetchOptions): Promise<void> {
started ??= runPrefetch(options)
return started
}
async function runPrefetch(options: WslNodeRuntimePrefetchOptions): Promise<void> {
const target = wslNodeRuntimePrefetchTarget(options.arch)
// Must match deployOrcad's default runtimeCacheRoot.
const cacheRoot = join(options.userDataPath, 'orcad-artifacts')
// Present is enough here: the deploy re-hashes on use, so skip a 55 MB hash on every launch.
if (existsSync(nodeRuntimeArchiveCachePath(target, cacheRoot))) {
return
}
try {
await (options.materialize ?? materializeNodeRuntimeArchive)(target, cacheRoot, {})
} catch (error) {
console.warn(
`[wsl-hosts] Could not prefetch Node for WSL hosts; a first connect downloads it: ${errorMessage(error)}`
)
}
}
export type WslNodeRuntimePrefetchWiring = WslNodeRuntimePrefetchOptions & {
store: {
getSettings: () => Pick<GlobalSettings, 'experimentalWslHosts'>
onSettingsChanged: (
listener: (
updates: Partial<GlobalSettings>,
settings: Pick<GlobalSettings, 'experimentalWslHosts'>
) => void
) => unknown
}
gateOpen?: () => boolean
schedule?: (run: () => void) => void
}
/** Starts the prefetch once the WSL hosts flag is open and the setting is on, now or when it turns on. */
export function wireWslNodeRuntimePrefetch(wiring: WslNodeRuntimePrefetchWiring): void {
const gateOpen = wiring.gateOpen ?? wslHostsGateOpen
const schedule = wiring.schedule ?? scheduleAfterStartup
let scheduled = false
const consider = (enabled: boolean): void => {
if (scheduled || !enabled || !gateOpen()) {
return
}
scheduled = true
schedule(() => void prefetchWslNodeRuntime(wiring))
}
consider(wiring.store.getSettings().experimentalWslHosts === true)
wiring.store.onSettingsChanged((updates, settings) => {
if ('experimentalWslHosts' in updates) {
consider(settings.experimentalWslHosts === true)
}
})
}
function scheduleAfterStartup(run: () => void): void {
setTimeout(run, PREFETCH_DELAY_MS).unref()
}
export function resetWslNodeRuntimePrefetchForTests(): void {
started = null
}