feat(files): stream runtime file and folder downloads with progress, cancel and open-locally

This commit is contained in:
Neil
2026-11-09 15:35:45 -08:00
parent 923a1504b9
commit 9d48206ac8
26 changed files with 2131 additions and 6 deletions
+2
View File
@@ -8,6 +8,7 @@ import {
} from './filesystem-handler-context'
import { registerFilesystemReadHandlers } from './filesystem-read-handlers'
import { registerFilesystemDownloadHandlers } from './filesystem-download-handlers'
import { registerRuntimeDownloadHandlers } from '../../runtime-downloads/runtime-download-handlers'
import { registerFilesystemWriteHandlers } from './filesystem-write-handlers'
import { registerFilesystemSearchHandlers } from './filesystem-search-handlers'
import { registerFilesystemGitStatusHandlers } from './filesystem-git-status-handlers'
@@ -33,6 +34,7 @@ export function registerFilesystemHandlers(
registerFilesystemReadHandlers(context)
registerFilesystemDownloadHandlers(context)
registerRuntimeDownloadHandlers()
registerFilesystemWriteHandlers(context)
registerFilesystemSearchHandlers(context)
registerFilesystemGitStatusHandlers(context)
@@ -0,0 +1,47 @@
import type { RuntimeDownloadErrorCode } from '../../shared/runtime-downloads/runtime-download-contract'
import { RuntimeDownloadError } from './runtime-download-transfer'
const HOST_MESSAGE_CODES: Record<string, RuntimeDownloadErrorCode> = {
archive_too_large: 'too_large',
archive_too_many_entries: 'too_many_entries',
archive_busy: 'host_busy',
archive_not_directory: 'not_a_directory',
archive_canceled: 'canceled',
file_too_large: 'too_large'
}
/** Maps a failed host reply onto a stable code the renderer can word. */
export function runtimeDownloadErrorFromResponse(error: {
code: string
message: string
}): RuntimeDownloadError {
if (error.code === 'method_not_found') {
return new RuntimeDownloadError('host_update_required', error.message)
}
const mapped = HOST_MESSAGE_CODES[error.message]
if (mapped) {
return new RuntimeDownloadError(mapped, error.message)
}
if (/ENOENT|not[_ ]found|no such file/i.test(error.message)) {
return new RuntimeDownloadError('not_found', error.message)
}
if (/disconnect|unreachable|closed|timed? ?out|offline/i.test(`${error.code} ${error.message}`)) {
return new RuntimeDownloadError('disconnected', error.message)
}
return new RuntimeDownloadError('transfer_failed', error.message)
}
export function toRuntimeDownloadError(error: unknown, signal: AbortSignal): RuntimeDownloadError {
if (signal.aborted) {
return new RuntimeDownloadError('canceled')
}
if (error instanceof RuntimeDownloadError) {
return error
}
const message = error instanceof Error ? error.message : String(error)
const code =
typeof (error as { code?: unknown } | null)?.code === 'string'
? (error as { code: string }).code
: 'runtime_error'
return runtimeDownloadErrorFromResponse({ code, message })
}
@@ -0,0 +1,238 @@
import { app, BrowserWindow, dialog, ipcMain, shell, type WebContents } from 'electron'
import { open } from 'node:fs/promises'
import { join } from 'node:path'
import {
RUNTIME_OPEN_LOCALLY_MAX_BYTES,
type RuntimeDownloadProgressEvent,
type RuntimeDownloadResult,
type RuntimeDownloadStartArgs
} from '../../shared/runtime-downloads/runtime-download-contract'
import { callRuntimeEnvironment } from '../ipc/runtime-environments/runtime-environment-transport-routing'
import { getRuntimeEnvironmentRegistryRoot } from '../ipc/runtime-environments/runtime-environment-registry-root'
import { sanitizeLocalDownloadFilename } from '../ipc/filesystem/local-download-filename'
import {
cleanupLocalTransferPath,
createSiblingTransferPath,
inspectDownloadDestination,
promoteDownloadedFile
} from '../ipc/filesystem/filesystem-download-promotion'
import { abortWhenRendererGone } from '../ipc/renderer-lifetime-abort'
import {
RuntimeDownloadError,
transferRuntimeFile,
transferRuntimeFolder,
type RuntimeDownloadCall,
type RuntimeDownloadProgress
} from './runtime-download-transfer'
import { runtimeDownloadErrorFromResponse, toRuntimeDownloadError } from './runtime-download-errors'
import {
createRuntimeOpenLocalDirectory,
pruneRuntimeOpenLocalCache
} from './runtime-open-local-cache'
export const RUNTIME_DOWNLOAD_PROGRESS_CHANNEL = 'runtimeDownloads:progress'
// A toast cannot show finer progress than this, and every event crosses IPC.
const PROGRESS_INTERVAL_MS = 120
const MAX_ACTIVE_DOWNLOADS = 8
const activeDownloads = new Map<string, AbortController>()
function validateArgs(args: unknown): RuntimeDownloadStartArgs {
const value = args as Partial<RuntimeDownloadStartArgs> | null
const isText = (field: unknown, allowEmpty = false): field is string =>
typeof field === 'string' && (allowEmpty || field.trim() !== '') && field.length <= 4096
if (
!value ||
!isText(value.downloadId) ||
!isText(value.environmentId) ||
!isText(value.worktree) ||
!isText(value.relativePath, true) ||
!isText(value.name) ||
(value.kind !== 'file' && value.kind !== 'folder') ||
(value.intent !== 'save' && value.intent !== 'open')
) {
throw new Error('Invalid runtime download request')
}
if (value.intent === 'open' && value.kind !== 'file') {
throw new Error('Only files can be opened locally')
}
return value as RuntimeDownloadStartArgs
}
function createCall(args: RuntimeDownloadStartArgs): RuntimeDownloadCall {
return async <T>(
method: string,
params: unknown,
options: { timeoutMs: number; signal: AbortSignal }
): Promise<T> => {
const response = await callRuntimeEnvironment(
getRuntimeEnvironmentRegistryRoot(),
args.environmentId,
method,
params,
options.timeoutMs,
args.expectedEnvironmentPairingRevision,
undefined,
{ signal: options.signal }
)
if (!response.ok) {
throw runtimeDownloadErrorFromResponse(response.error)
}
return response.result as T
}
}
function createProgressEmitter(sender: WebContents, downloadId: string) {
let lastSentAt = 0
let destinationPath: string | undefined
const send = (event: Omit<RuntimeDownloadProgressEvent, 'downloadId' | 'destinationPath'>) => {
if (!sender.isDestroyed()) {
sender.send(RUNTIME_DOWNLOAD_PROGRESS_CHANNEL, {
downloadId,
...event,
...(destinationPath ? { destinationPath } : {})
} satisfies RuntimeDownloadProgressEvent)
}
}
return {
setDestination(path: string) {
destinationPath = path
},
preparing() {
send({ phase: 'preparing', receivedBytes: 0, totalBytes: null, processedBytes: 0 })
},
progress(progress: RuntimeDownloadProgress) {
const now = Date.now()
if (now - lastSentAt < PROGRESS_INTERVAL_MS) {
return
}
lastSentAt = now
send({ phase: 'transferring', ...progress })
}
}
}
async function chooseDestination(
sender: WebContents,
args: RuntimeDownloadStartArgs
): Promise<string | null> {
const baseName = sanitizeLocalDownloadFilename(args.name)
if (args.intent === 'open') {
void pruneRuntimeOpenLocalCache()
return join(await createRuntimeOpenLocalDirectory(), baseName)
}
const suggestedName = args.kind === 'folder' ? `${baseName}.zip` : baseName
const parentWindow = BrowserWindow.fromWebContents(sender) ?? undefined
const options: Electron.SaveDialogOptions = {
defaultPath: join(app.getPath('downloads'), suggestedName),
...(args.kind === 'folder' ? { filters: [{ name: 'ZIP archive', extensions: ['zip'] }] } : {})
}
const result = parentWindow
? await dialog.showSaveDialog(parentWindow, options)
: await dialog.showSaveDialog(options)
return result.canceled || !result.filePath ? null : result.filePath
}
async function runDownload(
sender: WebContents,
args: RuntimeDownloadStartArgs,
controller: AbortController
): Promise<RuntimeDownloadResult> {
const destinationPath = await chooseDestination(sender, args)
if (!destinationPath || controller.signal.aborted) {
return { status: 'canceled' }
}
const emitter = createProgressEmitter(sender, args.downloadId)
emitter.setDestination(destinationPath)
emitter.preparing()
const { existed } = await inspectDownloadDestination(destinationPath)
const tempPath = createSiblingTransferPath(destinationPath, 'download')
const sink = await open(tempPath, 'wx')
let promoted = false
try {
const transferInput = {
call: createCall(args),
worktree: args.worktree,
relativePath: args.relativePath,
sink,
signal: controller.signal,
onProgress: (progress: RuntimeDownloadProgress) => emitter.progress(progress)
}
const outcome =
args.kind === 'folder'
? await transferRuntimeFolder({
...transferInput,
excludeDefaultDirs: args.excludeDefaultDirs !== false
})
: await transferRuntimeFile({
...transferInput,
...(args.intent === 'open' ? { maxBytes: RUNTIME_OPEN_LOCALLY_MAX_BYTES } : {})
})
await sink.close()
if (controller.signal.aborted) {
throw new RuntimeDownloadError('canceled')
}
await promoteDownloadedFile(tempPath, destinationPath, existed)
promoted = true
let openError: string | undefined
if (args.intent === 'open') {
const message = await shell.openPath(destinationPath)
openError = message === '' ? undefined : message
}
return {
status: 'done',
destinationPath,
...outcome,
...(openError ? { openError } : {})
}
} finally {
await sink.close().catch(() => {})
if (!promoted) {
await cleanupLocalTransferPath(tempPath)
}
}
}
export function registerRuntimeDownloadHandlers(): void {
ipcMain.handle(
'runtimeDownloads:start',
async (event, rawArgs: unknown): Promise<RuntimeDownloadResult> => {
const args = validateArgs(rawArgs)
if (activeDownloads.has(args.downloadId)) {
throw new Error('Download already running')
}
if (activeDownloads.size >= MAX_ACTIVE_DOWNLOADS) {
return {
status: 'error',
code: 'host_busy',
message: 'Too many downloads are running; wait for one to finish.'
}
}
const controller = new AbortController()
activeDownloads.set(args.downloadId, controller)
// Closing the window must not leave a transfer running nobody can cancel.
const lifetime = abortWhenRendererGone(event.sender)
const onGone = () => controller.abort()
lifetime.signal.addEventListener('abort', onGone, { once: true })
try {
return await runDownload(event.sender, args, controller)
} catch (error) {
const failure = toRuntimeDownloadError(error, controller.signal)
return failure.code === 'canceled'
? { status: 'canceled' }
: { status: 'error', code: failure.code, message: failure.message }
} finally {
lifetime.signal.removeEventListener('abort', onGone)
lifetime.dispose()
activeDownloads.delete(args.downloadId)
}
}
)
ipcMain.handle('runtimeDownloads:cancel', (_event, args: { downloadId?: unknown }) => {
const controller =
typeof args?.downloadId === 'string' ? activeDownloads.get(args.downloadId) : undefined
controller?.abort()
return { canceled: controller !== undefined }
})
}
@@ -0,0 +1,123 @@
import { mkdtemp, open, readFile, rm } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
import {
RuntimeDownloadError,
transferRuntimeFile,
transferRuntimeFolder,
type RuntimeDownloadCall
} from './runtime-download-transfer'
let dir: string
beforeEach(async () => {
dir = await mkdtemp(join(tmpdir(), 'orca-runtime-download-'))
})
afterEach(async () => {
await rm(dir, { recursive: true, force: true })
})
function fileHost(content: Buffer, statSize = content.byteLength): RuntimeDownloadCall {
return (async (method: string, params: { offset: number; length: number }) => {
if (method === 'files.stat') {
return { size: statSize, isDirectory: false }
}
const bytes = content.subarray(params.offset, params.offset + params.length)
// Out-of-order replies: later pages may land first.
await new Promise((resolve) => setTimeout(resolve, params.offset % 3))
return {
contentBase64: bytes.toString('base64'),
bytesRead: bytes.byteLength,
eof: params.offset + bytes.byteLength >= content.byteLength
}
}) as RuntimeDownloadCall
}
async function runFile(call: RuntimeDownloadCall, extra: { maxBytes?: number } = {}) {
const sink = await open(join(dir, 'out'), 'w+')
try {
const result = await transferRuntimeFile({
call,
worktree: 'wt',
relativePath: 'a.bin',
sink,
signal: new AbortController().signal,
onProgress: () => {},
chunkBytes: 7,
concurrency: 3,
...extra
})
return { result, bytes: await readFile(join(dir, 'out')) }
} finally {
await sink.close()
}
}
describe('transferRuntimeFile', () => {
it('reassembles pages fetched in parallel in order', async () => {
const content = Buffer.from('the quick brown fox jumps over the lazy dog, twice over')
const { result, bytes } = await runFile(fileHost(content))
expect(result.bytes).toBe(content.byteLength)
expect(bytes.equals(content)).toBe(true)
})
it('keeps a file that shrank after stat to its final length', async () => {
const content = Buffer.from('short file')
const { bytes } = await runFile(fileHost(content, 1000))
expect(bytes.toString()).toBe('short file')
})
it('downloads an empty file', async () => {
const { bytes } = await runFile(fileHost(Buffer.alloc(0)))
expect(bytes.byteLength).toBe(0)
})
it('refuses a file over the caller limit before reading it', async () => {
await expect(runFile(fileHost(Buffer.alloc(20)), { maxBytes: 10 })).rejects.toEqual(
new RuntimeDownloadError('too_large')
)
})
})
describe('transferRuntimeFolder', () => {
it('releases the host archive when the download is canceled', async () => {
const controller = new AbortController()
const calls: string[] = []
const call = (async (method: string) => {
calls.push(method)
if (method === 'files.archiveStart') {
return { archiveId: 'z1', totalBytes: 10, excludedDirCount: 0, fileCount: 1 }
}
if (method === 'files.archiveRead') {
controller.abort()
return {
contentBase64: 'AA==',
bytesRead: 1,
eof: false,
processedBytes: 1,
skippedCount: 0
}
}
return { released: true }
}) as RuntimeDownloadCall
const sink = await open(join(dir, 'out.zip'), 'w+')
try {
await expect(
transferRuntimeFolder({
call,
worktree: 'wt',
relativePath: 'src',
sink,
signal: controller.signal,
onProgress: () => {},
excludeDefaultDirs: true
})
).rejects.toEqual(new RuntimeDownloadError('canceled'))
} finally {
await sink.close()
}
expect(calls).toEqual(['files.archiveStart', 'files.archiveRead', 'files.archiveCancel'])
})
})
@@ -0,0 +1,187 @@
import type { FileHandle } from 'node:fs/promises'
import type { RuntimeFileReadChunkResult } from '../../shared/file-content/runtime-file-read'
import {
FOLDER_ARCHIVE_MAX_READ_BYTES,
type FileArchiveReadResult,
type FileArchiveStartResult
} from '../../shared/rpc-contract/files-archive-params'
import type { RuntimeDownloadErrorCode } from '../../shared/runtime-downloads/runtime-download-contract'
/** files.readChunk's schema ceiling; older hosts accept nothing larger. */
const FILE_CHUNK_BYTES = 512 * 1024
// The main-process bulk-read lane admits two calls per host, so a third would only queue.
const FILE_CHUNK_CONCURRENCY = 2
const CHUNK_TIMEOUT_MS = 60_000
// The walk of a large tree runs before the first byte; give it room.
const ARCHIVE_START_TIMEOUT_MS = 120_000
export class RuntimeDownloadError extends Error {
constructor(
readonly code: RuntimeDownloadErrorCode,
message: string = code
) {
super(message)
this.name = 'RuntimeDownloadError'
}
}
export type RuntimeDownloadCall = <T>(
method: string,
params: unknown,
options: { timeoutMs: number; signal: AbortSignal }
) => Promise<T>
export type RuntimeDownloadProgress = {
receivedBytes: number
/** Expected bytes; for folders this counts uncompressed source bytes, not ZIP bytes. */
totalBytes: number | null
/** Source bytes covered so far, comparable with totalBytes. */
processedBytes: number
}
type TransferInput = {
call: RuntimeDownloadCall
worktree: string
relativePath: string
sink: FileHandle
signal: AbortSignal
onProgress: (progress: RuntimeDownloadProgress) => void
}
/** Pages a remote file into `sink` with a few positional reads in flight to hide link latency. */
export async function transferRuntimeFile(
input: TransferInput & { maxBytes?: number; chunkBytes?: number; concurrency?: number }
): Promise<{ bytes: number }> {
const chunkBytes = input.chunkBytes ?? FILE_CHUNK_BYTES
const stat = await input.call<{ size: number; isDirectory: boolean }>(
'files.stat',
{ worktree: input.worktree, relativePath: input.relativePath },
{ timeoutMs: CHUNK_TIMEOUT_MS, signal: input.signal }
)
if (stat.isDirectory) {
throw new RuntimeDownloadError('not_a_file')
}
if (input.maxBytes !== undefined && stat.size > input.maxBytes) {
throw new RuntimeDownloadError('too_large')
}
let nextOffset = 0
// The file may change size mid-transfer; the first EOF page fixes the final length.
let endOffset: number | null = null
let received = 0
const worker = async (): Promise<void> => {
for (;;) {
if (input.signal.aborted) {
throw new RuntimeDownloadError('canceled')
}
if (endOffset !== null && nextOffset >= endOffset) {
return
}
const offset = nextOffset
nextOffset += chunkBytes
const chunk = await input.call<RuntimeFileReadChunkResult>(
'files.readChunk',
{
worktree: input.worktree,
relativePath: input.relativePath,
offset,
length: chunkBytes
},
{ timeoutMs: CHUNK_TIMEOUT_MS, signal: input.signal }
)
if (chunk.bytesRead > 0) {
const bytes = Buffer.from(chunk.contentBase64, 'base64')
if (bytes.byteLength !== chunk.bytesRead) {
throw new RuntimeDownloadError('transfer_failed', 'Remote page length mismatch')
}
await input.sink.write(bytes, 0, bytes.byteLength, offset)
received += bytes.byteLength
input.onProgress({
receivedBytes: received,
totalBytes: stat.size,
processedBytes: received
})
}
if (chunk.eof || chunk.bytesRead < chunkBytes) {
const end = offset + chunk.bytesRead
endOffset = endOffset === null ? end : Math.min(endOffset, end)
return
}
}
}
const concurrency = Math.max(1, input.concurrency ?? FILE_CHUNK_CONCURRENCY)
await Promise.all(Array.from({ length: concurrency }, worker))
const finalLength = endOffset ?? received
// A page past a shrunken EOF may have landed; cut the file back to the agreed length.
await input.sink.truncate(finalLength)
return { bytes: finalLength }
}
export type FolderTransferResult = {
bytes: number
skippedCount: number
excludedDirCount: number
fileCount: number
}
/** Asks the host to zip a folder, then appends its pages to `sink` until EOF. */
export async function transferRuntimeFolder(
input: TransferInput & { excludeDefaultDirs: boolean }
): Promise<FolderTransferResult> {
const started = await input.call<FileArchiveStartResult>(
'files.archiveStart',
{
worktree: input.worktree,
relativePath: input.relativePath,
excludeDefaultDirs: input.excludeDefaultDirs
},
{ timeoutMs: ARCHIVE_START_TIMEOUT_MS, signal: input.signal }
)
let finished = false
let received = 0
try {
for (;;) {
if (input.signal.aborted) {
throw new RuntimeDownloadError('canceled')
}
const page = await input.call<FileArchiveReadResult>(
'files.archiveRead',
{ archiveId: started.archiveId, maxBytes: FOLDER_ARCHIVE_MAX_READ_BYTES },
{ timeoutMs: CHUNK_TIMEOUT_MS, signal: input.signal }
)
if (page.bytesRead > 0) {
const bytes = Buffer.from(page.contentBase64, 'base64')
await input.sink.write(bytes, 0, bytes.byteLength, received)
received += bytes.byteLength
}
input.onProgress({
receivedBytes: received,
totalBytes: started.totalBytes,
processedBytes: page.processedBytes
})
if (page.eof) {
finished = true
return {
bytes: received,
skippedCount: page.skippedCount,
excludedDirCount: started.excludedDirCount,
fileCount: started.fileCount
}
}
}
} finally {
if (!finished) {
// Best effort: the host's idle timer frees the session if this never arrives.
const release = new AbortController()
void input
.call(
'files.archiveCancel',
{ archiveId: started.archiveId },
{
timeoutMs: 10_000,
signal: release.signal
}
)
.catch(() => {})
}
}
}
@@ -0,0 +1,44 @@
import { randomUUID } from 'node:crypto'
import { mkdir, readdir, rm, stat } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
// Opened copies only need to outlive the app that opens them; a day covers a long session.
const OPEN_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000
export function runtimeOpenLocalCacheRoot(): string {
return join(tmpdir(), 'orca-opened-remote-files')
}
/** A fresh directory per open, so two opens of same-named files never clobber each other. */
export async function createRuntimeOpenLocalDirectory(root = runtimeOpenLocalCacheRoot()) {
const directory = join(root, randomUUID())
await mkdir(directory, { recursive: true, mode: 0o700 })
return directory
}
/** Best effort: removes cached copies older than a day. Failures never block an open. */
export async function pruneRuntimeOpenLocalCache(
root = runtimeOpenLocalCacheRoot(),
now = Date.now(),
maxAgeMs = OPEN_CACHE_MAX_AGE_MS
): Promise<void> {
let names: string[]
try {
names = await readdir(root)
} catch {
return
}
await Promise.all(
names.map(async (name) => {
const path = join(root, name)
try {
if (now - (await stat(path)).mtimeMs > maxAgeMs) {
await rm(path, { recursive: true, force: true })
}
} catch {
// Another app instance may be pruning the same entry.
}
})
)
}
@@ -29,6 +29,7 @@ export type RuntimeFileCommandSurface = Pick<
| 'readFileExplorerPreview'
| 'readChatImagePreview'
| 'readFileExplorerChunk'
| 'resolveFileExplorerArchivePath'
| 'readDocPreviewFile'
| 'readDocPreviewChunk'
> &
@@ -91,6 +92,7 @@ export function installRuntimeFileCommandSurface(
readFileExplorerPreview: fileReads.readFileExplorerPreview.bind(fileReads),
readChatImagePreview: fileReads.readChatImagePreview.bind(fileReads),
readFileExplorerChunk: fileReads.readFileExplorerChunk.bind(fileReads),
resolveFileExplorerArchivePath: fileReads.resolveFileExplorerArchivePath.bind(fileReads),
readDocPreviewFile: fileReads.readDocPreviewFile.bind(fileReads),
readDocPreviewChunk: fileReads.readDocPreviewChunk.bind(fileReads),
writeFileExplorerFile: fileMutations.writeFileExplorerFile.bind(fileMutations),
@@ -0,0 +1,172 @@
import { mkdtemp, mkdir, rm, symlink, writeFile, chmod } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { unzipSync } from 'fflate'
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
import { FolderArchiveSessions } from './folder-archive-sessions'
import { FolderArchiveLimitError, planFolderArchive } from './folder-archive-walk'
import { FolderArchiveZipStream } from './folder-archive-zip-stream'
let root: string
beforeEach(async () => {
root = await mkdtemp(join(tmpdir(), 'orca-archive-test-'))
})
afterEach(async () => {
await rm(root, { recursive: true, force: true })
})
async function drain(sessions: FolderArchiveSessions, archiveId: string, ownerKey = 'device-a') {
const parts: Buffer[] = []
for (;;) {
const page = await sessions.read({ archiveId, ownerKey, maxBytes: 64 * 1024 })
parts.push(Buffer.from(page.contentBase64, 'base64'))
if (page.eof) {
return { bytes: Buffer.concat(parts), last: page }
}
}
}
describe('FolderArchiveSessions', () => {
it('zips a folder with nested files, empty dirs and the default exclusions applied', async () => {
const project = join(root, 'project')
await mkdir(join(project, 'src', 'empty'), { recursive: true })
await mkdir(join(project, 'node_modules', 'pkg'), { recursive: true })
await mkdir(join(project, '.git'), { recursive: true })
await writeFile(join(project, 'src', 'a.txt'), 'hello')
await writeFile(join(project, 'run.sh'), '#!/bin/sh\n')
await chmod(join(project, 'run.sh'), 0o755)
await writeFile(join(project, 'node_modules', 'pkg', 'index.js'), 'x')
await writeFile(join(project, '.git', 'HEAD'), 'ref')
const sessions = new FolderArchiveSessions()
const started = await sessions.start({
folderPath: project,
ownerKey: 'device-a',
excludeDefaultDirs: true
})
expect(started).toMatchObject({
suggestedName: 'project.zip',
fileCount: 2,
totalBytes: 15,
excludedDirCount: 2
})
const { bytes, last } = await drain(sessions, started.archiveId)
expect(last.processedBytes).toBe(15)
const files = unzipSync(bytes)
expect(Object.keys(files).sort()).toEqual([
'project/',
'project/run.sh',
'project/src/',
'project/src/a.txt',
'project/src/empty/'
])
expect(Buffer.from(files['project/src/a.txt']).toString()).toBe('hello')
expect(sessions.activeCount()).toBe(0)
})
it('includes dependency folders when exclusion is off', async () => {
await mkdir(join(root, 'node_modules'), { recursive: true })
await writeFile(join(root, 'node_modules', 'x.js'), 'x')
const plan = await planFolderArchive(root, 'r', { excludeDefaultDirs: false })
expect(plan.entries.map((entry) => entry.archivePath)).toContain('r/node_modules/x.js')
})
it('stores symlinks as links and never reads what they point at', async () => {
const outside = join(root, 'outside-secret.txt')
await writeFile(outside, 'secret')
const project = join(root, 'p')
await mkdir(project)
await symlink(outside, join(project, 'link'))
await symlink(root, join(project, 'dir-link'))
const plan = await planFolderArchive(project, 'p', { excludeDefaultDirs: true })
expect(plan.totalBytes).toBe(0)
const stream = new FolderArchiveZipStream(plan.entries)
const parts: Buffer[] = []
for (;;) {
const page = await stream.read(1 << 20)
parts.push(page.bytes)
if (page.eof) {
break
}
}
const files = unzipSync(Buffer.concat(parts))
expect(Buffer.from(files['p/link']).toString()).toBe(outside)
expect(Object.keys(files).some((name) => name.includes('outside-secret'))).toBe(false)
expect(Object.keys(files)).not.toContain('p/dir-link/')
})
it('refuses folders over the byte or entry limits', async () => {
await writeFile(join(root, 'a'), Buffer.alloc(10))
await writeFile(join(root, 'b'), Buffer.alloc(10))
await expect(
planFolderArchive(root, 'r', { excludeDefaultDirs: true, maxTotalBytes: 15 })
).rejects.toEqual(new FolderArchiveLimitError('archive_too_large'))
await expect(
planFolderArchive(root, 'r', { excludeDefaultDirs: true, maxEntries: 2 })
).rejects.toEqual(new FolderArchiveLimitError('archive_too_many_entries'))
})
it('refuses to archive a file', async () => {
await writeFile(join(root, 'f'), 'x')
const sessions = new FolderArchiveSessions()
await expect(
sessions.start({ folderPath: join(root, 'f'), ownerKey: 'a', excludeDefaultDirs: true })
).rejects.toThrow('archive_not_directory')
})
it('hides an archive from other devices and frees it on cancel', async () => {
await writeFile(join(root, 'f'), 'x')
const sessions = new FolderArchiveSessions()
const { archiveId } = await sessions.start({
folderPath: root,
ownerKey: 'device-a',
excludeDefaultDirs: true
})
await expect(sessions.read({ archiveId, ownerKey: 'device-b', maxBytes: 10 })).rejects.toThrow(
'archive_not_found'
)
expect(sessions.cancel({ archiveId, ownerKey: 'device-b' })).toBe(false)
expect(sessions.cancel({ archiveId, ownerKey: 'device-a' })).toBe(true)
expect(sessions.activeCount()).toBe(0)
await expect(sessions.read({ archiveId, ownerKey: 'device-a', maxBytes: 10 })).rejects.toThrow(
'archive_not_found'
)
})
it('caps concurrent archives and releases idle ones', async () => {
const sessions = new FolderArchiveSessions(20, 1)
const first = await sessions.start({
folderPath: root,
ownerKey: 'a',
excludeDefaultDirs: true
})
await expect(
sessions.start({ folderPath: root, ownerKey: 'a', excludeDefaultDirs: true })
).rejects.toThrow('archive_busy')
await new Promise((resolve) => setTimeout(resolve, 60))
expect(sessions.activeCount()).toBe(0)
await expect(
sessions.read({ archiveId: first.archiveId, ownerKey: 'a', maxBytes: 10 })
).rejects.toThrow('archive_not_found')
})
it('pauses the producer at the high-water mark until the reader drains', async () => {
await writeFile(join(root, 'big.png'), Buffer.alloc(4 * 1024 * 1024, 7))
const plan = await planFolderArchive(root, 'r', { excludeDefaultDirs: true })
const stream = new FolderArchiveZipStream(plan.entries, 512 * 1024)
await new Promise((resolve) => setTimeout(resolve, 50))
expect(stream.processedBytes).toBeLessThanOrEqual(1024 * 1024)
let total = 0
for (;;) {
const page = await stream.read(256 * 1024)
total += page.bytes.byteLength
if (page.eof) {
break
}
}
expect(stream.processedBytes).toBe(4 * 1024 * 1024)
expect(total).toBeGreaterThan(4 * 1024 * 1024)
})
})
@@ -0,0 +1,164 @@
import { randomUUID } from 'node:crypto'
import { realpath } from 'node:fs/promises'
import { basename } from 'node:path'
import type {
FileArchiveReadResult,
FileArchiveStartResult
} from '../../../../shared/rpc-contract/files-archive-params'
import { planFolderArchive } from './folder-archive-walk'
import { FolderArchiveZipStream } from './folder-archive-zip-stream'
// A lost cancel (closed laptop, dropped socket) must not pin host memory or file handles.
export const FOLDER_ARCHIVE_IDLE_TIMEOUT_MS = 2 * 60_000
const MAX_ACTIVE_ARCHIVES = 4
type ArchiveSession = {
id: string
/** Only the connection that started an archive may read or cancel it. */
ownerKey: string
stream: FolderArchiveZipStream
reading: boolean
idleTimer: ReturnType<typeof setTimeout> | null
}
export class FolderArchiveSessions {
private readonly sessions = new Map<string, ArchiveSession>()
constructor(
private readonly idleTimeoutMs = FOLDER_ARCHIVE_IDLE_TIMEOUT_MS,
private readonly maxActive = MAX_ACTIVE_ARCHIVES
) {}
/** `folderPath` must already be confined to an allowed workspace root by the caller. */
async start(input: {
folderPath: string
ownerKey: string
excludeDefaultDirs: boolean
signal?: AbortSignal
}): Promise<FileArchiveStartResult> {
if (this.sessions.size >= this.maxActive) {
throw new Error('archive_busy')
}
const rootName = sanitizeArchiveRootName(basename(await realpath(input.folderPath)))
const plan = await planFolderArchive(input.folderPath, rootName, {
excludeDefaultDirs: input.excludeDefaultDirs,
...(input.signal ? { signal: input.signal } : {})
})
// Re-check after the walk: concurrent starts may have filled the slots meanwhile.
if (this.sessions.size >= this.maxActive) {
throw new Error('archive_busy')
}
const session: ArchiveSession = {
id: randomUUID(),
ownerKey: input.ownerKey,
stream: new FolderArchiveZipStream(plan.entries),
reading: false,
idleTimer: null
}
this.sessions.set(session.id, session)
this.armIdleTimer(session)
return {
archiveId: session.id,
suggestedName: `${rootName}.zip`,
fileCount: plan.fileCount,
directoryCount: plan.directoryCount,
totalBytes: plan.totalBytes,
excludedDirCount: plan.excludedDirCount
}
}
async read(input: {
archiveId: string
ownerKey: string
maxBytes: number
}): Promise<FileArchiveReadResult> {
const session = this.requireSession(input.archiveId, input.ownerKey)
if (session.reading) {
throw new Error('archive_busy')
}
session.reading = true
this.clearIdleTimer(session)
try {
const page = await session.stream.read(input.maxBytes)
if (page.eof) {
this.release(session)
}
return {
contentBase64: page.bytes.toString('base64'),
bytesRead: page.bytes.byteLength,
eof: page.eof,
processedBytes: session.stream.processedBytes,
skippedCount: session.stream.skippedCount
}
} catch (error) {
this.release(session)
throw error
} finally {
session.reading = false
if (this.sessions.get(session.id) === session) {
this.armIdleTimer(session)
}
}
}
cancel(input: { archiveId: string; ownerKey: string }): boolean {
const session = this.sessions.get(input.archiveId)
if (!session || session.ownerKey !== input.ownerKey) {
return false
}
this.release(session)
return true
}
activeCount(): number {
return this.sessions.size
}
private requireSession(archiveId: string, ownerKey: string): ArchiveSession {
const session = this.sessions.get(archiveId)
// Another connection's archive looks the same as a missing one.
if (!session || session.ownerKey !== ownerKey) {
throw new Error('archive_not_found')
}
return session
}
private release(session: ArchiveSession): void {
this.clearIdleTimer(session)
if (this.sessions.get(session.id) === session) {
this.sessions.delete(session.id)
}
session.stream.cancel()
}
private armIdleTimer(session: ArchiveSession): void {
this.clearIdleTimer(session)
session.idleTimer = setTimeout(() => this.release(session), this.idleTimeoutMs)
session.idleTimer.unref?.()
}
private clearIdleTimer(session: ArchiveSession): void {
if (session.idleTimer) {
clearTimeout(session.idleTimer)
session.idleTimer = null
}
}
}
function sanitizeArchiveRootName(name: string): string {
// A filesystem root has no basename; zip readers choke on separators or control characters here.
// oxlint-disable-next-line no-control-regex
const cleaned = name.replace(/[\u0000-\u001f/\\]/g, '_').trim()
return cleaned === '' || cleaned === '.' || cleaned === '..' ? 'folder' : cleaned
}
const sessionsByRuntime = new WeakMap<object, FolderArchiveSessions>()
export function getFolderArchiveSessions(runtime: object): FolderArchiveSessions {
let sessions = sessionsByRuntime.get(runtime)
if (!sessions) {
sessions = new FolderArchiveSessions()
sessionsByRuntime.set(runtime, sessions)
}
return sessions
}
@@ -0,0 +1,189 @@
import { lstat, readdir, realpath } from 'node:fs/promises'
import { join } from 'node:path'
import {
FOLDER_ARCHIVE_DEFAULT_EXCLUDED_NAMES,
FOLDER_ARCHIVE_MAX_ENTRIES,
FOLDER_ARCHIVE_MAX_TOTAL_BYTES
} from '../../../../shared/rpc-contract/files-archive-params'
export type FolderArchiveEntry = {
/** Path inside the archive, `/`-separated, prefixed by the archived folder's name. */
archivePath: string
absolutePath: string
kind: 'file' | 'directory' | 'symlink'
size: number
mode: number
mtimeMs: number
}
export type FolderArchivePlan = {
entries: FolderArchiveEntry[]
fileCount: number
directoryCount: number
totalBytes: number
excludedDirCount: number
}
export class FolderArchiveLimitError extends Error {
constructor(readonly code: 'archive_too_large' | 'archive_too_many_entries') {
super(code)
this.name = 'FolderArchiveLimitError'
}
}
export type FolderArchiveWalkOptions = {
excludeDefaultDirs: boolean
maxTotalBytes?: number
maxEntries?: number
signal?: AbortSignal
}
/**
* Lists a folder for archiving without ever following a symlink, so every entry stays under
* the root's real path. A directory swapped for a link mid-walk fails its realpath check and is skipped.
*/
export async function planFolderArchive(
rootPath: string,
archiveRootName: string,
options: FolderArchiveWalkOptions
): Promise<FolderArchivePlan> {
// Child realpath checks compare against this, so the root itself must be canonical.
const rootRealPath = await realpath(rootPath)
const maxTotalBytes = options.maxTotalBytes ?? FOLDER_ARCHIVE_MAX_TOTAL_BYTES
const maxEntries = options.maxEntries ?? FOLDER_ARCHIVE_MAX_ENTRIES
const excluded = new Set<string>(
options.excludeDefaultDirs ? FOLDER_ARCHIVE_DEFAULT_EXCLUDED_NAMES : []
)
const rootStat = await lstat(rootRealPath)
if (!rootStat.isDirectory()) {
throw new Error('archive_not_directory')
}
const plan: FolderArchivePlan = {
entries: [
{
archivePath: `${archiveRootName}/`,
absolutePath: rootRealPath,
kind: 'directory',
size: 0,
mode: rootStat.mode,
mtimeMs: rootStat.mtimeMs
}
],
fileCount: 0,
directoryCount: 1,
totalBytes: 0,
excludedDirCount: 0
}
// Depth-first with an explicit stack: deep trees must not grow the JS call stack.
const pending: { absolutePath: string; archivePath: string }[] = [
{ absolutePath: rootRealPath, archivePath: `${archiveRootName}/` }
]
while (pending.length > 0) {
if (options.signal?.aborted) {
throw new Error('archive_canceled')
}
const dir = pending.pop()!
if (dir.absolutePath !== rootRealPath && !(await isUnmovedDirectory(dir.absolutePath))) {
continue
}
let names: string[]
try {
names = await readdir(dir.absolutePath)
} catch (error) {
if (isVanishedOrDenied(error)) {
continue
}
throw error
}
names.sort()
const stats = await Promise.all(
names.map(async (name) => {
try {
return { name, stat: await lstat(join(dir.absolutePath, name)) }
} catch (error) {
if (isVanishedOrDenied(error)) {
return null
}
throw error
}
})
)
const childDirs: { absolutePath: string; archivePath: string }[] = []
for (const item of stats) {
if (!item) {
continue
}
const { name, stat } = item
const absolutePath = join(dir.absolutePath, name)
const archivePath = `${dir.archivePath}${name}`
if (stat.isDirectory()) {
if (excluded.has(name)) {
plan.excludedDirCount += 1
continue
}
plan.directoryCount += 1
plan.entries.push({
archivePath: `${archivePath}/`,
absolutePath,
kind: 'directory',
size: 0,
mode: stat.mode,
mtimeMs: stat.mtimeMs
})
childDirs.push({ absolutePath, archivePath: `${archivePath}/` })
} else if (stat.isFile() || stat.isSymbolicLink()) {
const kind = stat.isFile() ? 'file' : 'symlink'
if (kind === 'file') {
plan.fileCount += 1
plan.totalBytes += stat.size
if (plan.totalBytes > maxTotalBytes) {
throw new FolderArchiveLimitError('archive_too_large')
}
}
plan.entries.push({
archivePath,
absolutePath,
kind,
size: kind === 'file' ? stat.size : 0,
mode: stat.mode,
mtimeMs: stat.mtimeMs
})
}
// Sockets, FIFOs and devices have no archivable content.
if (plan.entries.length > maxEntries) {
throw new FolderArchiveLimitError('archive_too_many_entries')
}
}
// Reverse so the stack pops children in sorted order.
for (let index = childDirs.length - 1; index >= 0; index -= 1) {
pending.push(childDirs[index])
}
}
return plan
}
async function isUnmovedDirectory(absolutePath: string): Promise<boolean> {
try {
const resolved = await realpath(absolutePath)
// Windows paths compare case-insensitively; realpath may report a different casing.
return process.platform === 'win32'
? resolved.toLowerCase() === absolutePath.toLowerCase()
: resolved === absolutePath
} catch (error) {
if (isVanishedOrDenied(error)) {
return false
}
throw error
}
}
export function isVanishedOrDenied(error: unknown): boolean {
const code = (error as NodeJS.ErrnoException | null)?.code
return (
code === 'ENOENT' ||
code === 'ENOTDIR' ||
code === 'EACCES' ||
code === 'EPERM' ||
code === 'ELOOP'
)
}
@@ -0,0 +1,252 @@
import { constants } from 'node:fs'
import { open, readlink } from 'node:fs/promises'
import { extname } from 'node:path'
import { Zip, ZipDeflate, ZipPassThrough, type ZipInputFile } from 'fflate'
import { isVanishedOrDenied, type FolderArchiveEntry } from './folder-archive-walk'
const FILE_READ_BYTES = 256 * 1024
/** Encoded bytes buffered ahead of the reader before the producer pauses. */
const DEFAULT_HIGH_WATER_BYTES = 8 * 1024 * 1024
// Level 4 keeps pure-JS deflate fast enough not to starve a fast link while still shrinking text.
const DEFLATE_LEVEL = 4
const UNIX_OS = 3
const S_IFLNK = 0o120000
// Recompressing these costs CPU for no size win.
const STORED_EXTENSIONS = new Set([
'.7z',
'.avif',
'.br',
'.bz2',
'.dmg',
'.gif',
'.gz',
'.heic',
'.jar',
'.jpeg',
'.jpg',
'.m4a',
'.mkv',
'.mov',
'.mp3',
'.mp4',
'.ogg',
'.png',
'.rar',
'.tgz',
'.webm',
'.webp',
'.whl',
'.woff',
'.woff2',
'.xz',
'.zip',
'.zst'
])
/**
* Turns a planned entry list into ZIP bytes on demand. The producer runs ahead of the reader by at
* most `highWaterBytes`, so a slow link never makes the host buffer a whole folder.
*/
export class FolderArchiveZipStream {
private readonly chunks: Uint8Array[] = []
private bufferedBytes = 0
private finished = false
private failure: Error | null = null
private canceled = false
private wakeReader: (() => void) | null = null
private wakeProducer: (() => void) | null = null
private readonly zip: Zip
processedBytes = 0
skippedCount = 0
constructor(
private readonly entries: readonly FolderArchiveEntry[],
private readonly highWaterBytes = DEFAULT_HIGH_WATER_BYTES
) {
this.zip = new Zip((error, data, final) => {
if (error) {
this.fail(error)
return
}
if (data.byteLength > 0) {
this.chunks.push(data)
this.bufferedBytes += data.byteLength
}
if (final) {
this.finished = true
}
this.notifyReader()
})
void this.produce()
}
/** Resolves with up to `maxBytes` once that much is buffered or the archive ends. */
async read(maxBytes: number): Promise<{ bytes: Buffer; eof: boolean }> {
while (!this.failure && !this.finished && this.bufferedBytes < maxBytes) {
await new Promise<void>((resolve) => {
this.wakeReader = resolve
})
}
if (this.failure) {
throw this.failure
}
const parts: Uint8Array[] = []
let taken = 0
while (this.chunks.length > 0 && taken < maxBytes) {
const head = this.chunks[0]
const room = maxBytes - taken
if (head.byteLength <= room) {
parts.push(head)
taken += head.byteLength
this.chunks.shift()
} else {
parts.push(head.subarray(0, room))
this.chunks[0] = head.subarray(room)
taken += room
}
}
this.bufferedBytes -= taken
this.notifyProducer()
return {
bytes: Buffer.concat(parts, taken),
eof: this.finished && this.chunks.length === 0
}
}
cancel(): void {
this.canceled = true
this.zip.terminate()
this.chunks.length = 0
this.bufferedBytes = 0
this.fail(new Error('archive_canceled'))
this.notifyProducer()
}
private async produce(): Promise<void> {
try {
for (const entry of this.entries) {
if (this.canceled) {
return
}
await this.addEntry(entry)
}
this.zip.end()
} catch (error) {
this.fail(error instanceof Error ? error : new Error(String(error)))
}
}
private async addEntry(entry: FolderArchiveEntry): Promise<void> {
if (entry.kind === 'directory') {
const file = withAttributes(new ZipPassThrough(entry.archivePath), entry, entry.mode)
this.zip.add(file)
file.push(new Uint8Array(0), true)
return
}
if (entry.kind === 'symlink') {
let target: string
try {
target = await readlink(entry.absolutePath)
} catch (error) {
return this.skip(error)
}
// Stored as a link, never dereferenced: the target may name anything on the host.
const file = withAttributes(
new ZipPassThrough(entry.archivePath),
entry,
S_IFLNK | (entry.mode & 0o777)
)
this.zip.add(file)
file.push(new TextEncoder().encode(target), true)
return
}
let handle: Awaited<ReturnType<typeof open>>
try {
handle = await open(entry.absolutePath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0))
} catch (error) {
return this.skip(error)
}
try {
// A file swapped for something else after the walk is skipped, not archived.
if (!(await handle.stat()).isFile()) {
this.skippedCount += 1
return
}
const file = withAttributes(
STORED_EXTENSIONS.has(extname(entry.archivePath).toLowerCase())
? new ZipPassThrough(entry.archivePath)
: new ZipDeflate(entry.archivePath, { level: DEFLATE_LEVEL }),
entry,
entry.mode
)
this.zip.add(file)
const buffer = Buffer.allocUnsafe(FILE_READ_BYTES)
for (;;) {
await this.waitForRoom()
if (this.canceled) {
return
}
const { bytesRead } = await handle.read(buffer, 0, FILE_READ_BYTES, null)
if (bytesRead === 0) {
file.push(new Uint8Array(0), true)
return
}
this.processedBytes += bytesRead
// fflate may keep a reference until it deflates, so hand it a copy.
file.push(Uint8Array.prototype.slice.call(buffer, 0, bytesRead) as Uint8Array, false)
}
} finally {
await handle.close().catch(() => {})
}
}
private skip(error: unknown): void {
if (!isVanishedOrDenied(error)) {
throw error
}
this.skippedCount += 1
}
private async waitForRoom(): Promise<void> {
while (!this.canceled && this.bufferedBytes >= this.highWaterBytes) {
await new Promise<void>((resolve) => {
this.wakeProducer = resolve
})
}
}
private fail(error: Error): void {
this.failure ??= error
this.notifyReader()
}
private notifyReader(): void {
const wake = this.wakeReader
this.wakeReader = null
wake?.()
}
private notifyProducer(): void {
const wake = this.wakeProducer
this.wakeProducer = null
wake?.()
}
}
function withAttributes<T extends ZipInputFile>(
file: T,
entry: FolderArchiveEntry,
mode: number
): T {
file.os = UNIX_OS
file.attrs = (mode & 0xffff) << 16
file.mtime = clampZipMtime(entry.mtimeMs)
return file
}
// DOS timestamps cover 1980-2107; fflate throws outside that range.
function clampZipMtime(mtimeMs: number): number {
const min = Date.UTC(1980, 0, 2)
const max = Date.UTC(2107, 11, 30)
return Math.min(Math.max(mtimeMs, min), max)
}
+10
View File
@@ -198,6 +198,16 @@ export class RuntimeFileReads {
return readLocalFileRange(filePath, offset, length)
}
/** A workspace folder's real path for archiving, under the same containment as chunk reads. */
async resolveFileExplorerArchivePath(
worktreeSelector: string,
relativePath: string
): Promise<string> {
const target = await resolveFileExplorerPath(this.host, worktreeSelector, relativePath)
requireLocalRuntimeFileRoute(target)
return resolveRuntimeAuthorizedPath(target.path, this.host.requireStore())
}
/** A host image a chat names, under desktop's chat-image rule; the path must be on this machine. */
async readChatImagePreview(
worktreeSelector: string,
@@ -0,0 +1,58 @@
import { defineMethod, type RpcContext } from '../../core'
import {
FileArchiveCancel,
FileArchiveRead,
FileArchiveStart
} from '../../../../../shared/rpc-contract/files-archive-params'
import { getFolderArchiveSessions } from '../../../files/archive/folder-archive-sessions'
// Why device identity: one-shot calls from the same desktop may arrive on different sockets.
function archiveOwnerKey(
context: Pick<RpcContext, 'pairedDeviceId' | 'clientId' | 'connectionId'>
) {
return context.pairedDeviceId ?? context.clientId ?? context.connectionId ?? 'in-process'
}
/** Folder downloads: the host zips a workspace folder and the client pages the bytes. */
export const FILE_ARCHIVE_METHODS = [
defineMethod({
name: 'files.archiveStart',
permission: 'workspace',
params: FileArchiveStart,
handler: async (params, context) => {
// Same containment as every files.* read: workspace-relative, then authorized-root checked.
const folderPath = await context.runtime.resolveFileExplorerArchivePath(
params.worktree,
params.relativePath
)
return getFolderArchiveSessions(context.runtime).start({
folderPath,
ownerKey: archiveOwnerKey(context),
excludeDefaultDirs: params.excludeDefaultDirs !== false,
...(context.signal ? { signal: context.signal } : {})
})
}
}),
defineMethod({
name: 'files.archiveRead',
permission: 'workspace',
params: FileArchiveRead,
handler: async (params, context) =>
getFolderArchiveSessions(context.runtime).read({
archiveId: params.archiveId,
ownerKey: archiveOwnerKey(context),
maxBytes: params.maxBytes
})
}),
defineMethod({
name: 'files.archiveCancel',
permission: 'workspace',
params: FileArchiveCancel,
handler: async (params, context) => ({
released: getFolderArchiveSessions(context.runtime).cancel({
archiveId: params.archiveId,
ownerKey: archiveOwnerKey(context)
})
})
})
]
@@ -1,5 +1,6 @@
import { defineMethod, defineStreamingMethod } from '../../core'
import { runFileWatchStream } from './file-watch-stream-lifecycle'
import { FILE_ARCHIVE_METHODS } from './files-archive-methods'
import { FILE_MUTATION_METHODS } from './files-mutation-methods'
import { dirListingPageCache } from './files-read-dir-page'
import { FILE_STAGED_SAVE_METHODS } from './files-staged-save-methods'
@@ -210,6 +211,7 @@ export const FILE_METHODS = [
}),
...FILE_MUTATION_METHODS,
...FILE_STAGED_SAVE_METHODS,
...FILE_ARCHIVE_METHODS,
defineMethod({
name: 'files.search',
permission: 'workspace',
+3
View File
@@ -71,6 +71,7 @@ import type { ShellApi } from './api/shell-api'
import type { SpeechApi } from './api/speech-api'
import type { SshApi } from './api/ssh-api'
import type { PlainSshTerminalApi } from './api/plain-ssh-terminal-bridge'
import type { RuntimeDownloadsApi } from './api/runtime-downloads-bridge'
import type { LegacyRelayBridgeApi } from './api/legacy-relay-bridge-api'
import type { DiagnosticsApi, MemoryApi, StatsApi, TelemetryApi } from './api/telemetry-api'
import type { UiCommandEventApi } from './api/ui-command-event-api'
@@ -180,6 +181,8 @@ export type PreloadApi = {
ssh: SshApi
/** Desktop only: an unmanaged ssh login to a host whose move is blocked. */
plainSsh?: PlainSshTerminalApi
/** Desktop only: streams files and folders from a paired runtime host to this machine. */
runtimeDownloads?: RuntimeDownloadsApi
/** Desktop only: the API keys Orca hands to agent launches. */
agentApiKeys?: AgentApiKeysApi
/** Desktop only: Orca Cloud API keys, org settings and routines (hosted builds). */
@@ -0,0 +1,24 @@
import { ipcRenderer } from 'electron'
import type {
RuntimeDownloadProgressEvent,
RuntimeDownloadResult,
RuntimeDownloadStartArgs
} from '../../shared/runtime-downloads/runtime-download-contract'
export type RuntimeDownloadsApi = {
/** Resolves when the download finishes, fails or is canceled. */
start: (args: RuntimeDownloadStartArgs) => Promise<RuntimeDownloadResult>
cancel: (args: { downloadId: string }) => Promise<{ canceled: boolean }>
onProgress: (callback: (event: RuntimeDownloadProgressEvent) => void) => () => void
}
export const runtimeDownloadsApi: RuntimeDownloadsApi = {
start: (args) => ipcRenderer.invoke('runtimeDownloads:start', args),
cancel: (args) => ipcRenderer.invoke('runtimeDownloads:cancel', args),
onProgress: (callback) => {
const listener = (_event: Electron.IpcRendererEvent, payload: RuntimeDownloadProgressEvent) =>
callback(payload)
ipcRenderer.on('runtimeDownloads:progress', listener)
return () => ipcRenderer.removeListener('runtimeDownloads:progress', listener)
}
}
+2
View File
@@ -91,6 +91,7 @@ import { grokAccountsApi } from './api/grok-accounts-bridge'
import { cursorAccountsApi } from './api/cursor-accounts-bridge'
import { sshApi } from './api/ssh-bridge'
import { plainSshTerminalApi } from './api/plain-ssh-terminal-bridge'
import { runtimeDownloadsApi } from './api/runtime-downloads-bridge'
import { agentApiKeysApi } from './api/agent-api-keys-bridge'
import { cloudApiBridge } from './api/cloud-api-bridge'
import { cloudSecretsApi } from './api/cloud-secrets-bridge'
@@ -205,6 +206,7 @@ const api = {
cursorAccounts: cursorAccountsApi,
ssh: sshApi,
plainSsh: plainSshTerminalApi,
runtimeDownloads: runtimeDownloadsApi,
agentApiKeys: agentApiKeysApi,
cloudApi: cloudApiBridge,
cloudSecrets: cloudSecretsApi,
@@ -22,11 +22,13 @@ export function shouldShowRemoteDownloadAction(
connectionId?: string | null,
runtimeDownloadContext?: RuntimeFileOperationArgs | null,
// Require advertised SFTP recursive transfer; unknown and system-SSH folder downloads stay hidden.
supportsFolderDownload = false
supportsFolderDownload = false,
// Desktop main can stream from the runtime host directly, including host-zipped folders.
canStreamFromRuntime = false
): boolean {
// Native save dialogs require desktop; runtime/system-SSH folders lack recursive transfer contracts.
// Native save dialogs require desktop; system-SSH folders lack a recursive transfer contract.
const hasDownloadCapability = node.isDirectory
? Boolean(connectionId && supportsFolderDownload)
? Boolean(connectionId ? supportsFolderDownload : canStreamFromRuntime)
: Boolean(connectionId || runtimeDownloadContext)
return (
hasDownloadCapability &&
@@ -34,6 +36,15 @@ export function shouldShowRemoteDownloadAction(
)
}
/** Fetch a runtime-hosted file into a temp copy and open it with the local default app. */
export function shouldShowOpenLocallyAction(
node: TreeNode,
connectionId: string | null | undefined,
canStreamFromRuntime: boolean
): boolean {
return !node.isDirectory && !connectionId && canStreamFromRuntime
}
export function shouldShowCopyFileAction(
node: TreeNode,
connectionId?: string | null,
@@ -11,6 +11,7 @@ import {
FolderPlus,
Globe,
ListCollapse,
MonitorDown,
Pencil,
Search,
SquareTerminal,
@@ -43,11 +44,13 @@ import {
shouldShowCopyFileAction,
shouldShowFindInFolderAction,
shouldShowOpenInTerminalAction,
shouldShowOpenLocallyAction,
shouldShowRemoteDownloadAction,
shouldShowViewFileAction
} from './file-explorer-row-action-visibility'
import { copyFileToOsClipboard, downloadRemoteFile } from './file-explorer-row-file-transfer'
import { fileExplorerNodeTabRelativePath } from '../tree/file-explorer-directory-listing'
import { canStreamRuntimeDownload, startRuntimeDownload } from './runtime-download-actions'
const isMac = navigator.userAgent.includes('Mac')
@@ -107,11 +110,19 @@ export function FileExplorerRowContextMenu({
const copyPathShortcutLabel = useShortcutLabel('fileExplorer.copyPath')
const copyRelativePathShortcutLabel = useShortcutLabel('fileExplorer.copyRelativePath')
const findInFolderShortcutLabel = useShortcutLabel('sidebar.search.toggle')
const canStreamFromRuntime =
!connectionId && canStreamRuntimeDownload(node, runtimeDownloadContext)
const showRemoteDownloadAction = shouldShowRemoteDownloadAction(
node,
connectionId,
runtimeDownloadContext,
supportsFolderDownload
supportsFolderDownload,
canStreamFromRuntime
)
const showOpenLocallyAction = shouldShowOpenLocallyAction(
node,
connectionId,
canStreamFromRuntime
)
const showCopyFileAction = shouldShowCopyFileAction(node, connectionId, selectionSize)
const revealOwner = useAppStore((s) =>
@@ -133,12 +144,21 @@ export function FileExplorerRowContextMenu({
}
}, [activeWorktreeId, node.path])
const handleDownload = useCallback(() => {
if (canStreamFromRuntime && runtimeDownloadContext) {
void startRuntimeDownload(node, runtimeDownloadContext, 'save')
return
}
const downloadTarget = connectionId || runtimeDownloadContext
if (!downloadTarget) {
return
}
void downloadRemoteFile(node, downloadTarget)
}, [connectionId, node, runtimeDownloadContext])
}, [canStreamFromRuntime, connectionId, node, runtimeDownloadContext])
const handleOpenLocally = useCallback(() => {
if (runtimeDownloadContext) {
void startRuntimeDownload(node, runtimeDownloadContext, 'open')
}
}, [node, runtimeDownloadContext])
const handleCopyFile = useCallback(() => {
void copyFileToOsClipboard(node, connectionId)
}, [connectionId, node])
@@ -237,10 +257,21 @@ export function FileExplorerRowContextMenu({
<ContextMenuItem onSelect={handleDownload}>
<Download />
{node.isDirectory
? t('auto.components.right.sidebar.FileExplorerRow.7ac885bd2f', 'Download Folder')
? canStreamFromRuntime
? t(
'auto.components.right.sidebar.FileExplorerRow.downloadFolderZip',
'Download as ZIP…'
)
: t('auto.components.right.sidebar.FileExplorerRow.7ac885bd2f', 'Download Folder')
: t('auto.components.right.sidebar.FileExplorerRow.c2112579f6', 'Download')}
</ContextMenuItem>
)}
{showOpenLocallyAction && (
<ContextMenuItem onSelect={handleOpenLocally}>
<MonitorDown />
{t('auto.components.right.sidebar.FileExplorerRow.openLocally', 'Open on This Computer')}
</ContextMenuItem>
)}
{canCollapseFolderSubtree && shouldShowCollapseFolderAction(node, isExpanded) && (
<ContextMenuItem onSelect={onCollapseFolderSubtree}>
<ListCollapse />
@@ -0,0 +1,225 @@
import { toast } from 'sonner'
import { createNonSecureContextUuid } from '../../../../../../shared/non-secure-context-uuid'
import { translate } from '@/i18n/i18n'
import { getRevealInFileManagerLabel, revealInFileManager } from '@/lib/reveal-in-file-manager'
import { getRemoteFileArgs } from '@/runtime/files/runtime-file-routing'
import type { RuntimeFileOperationArgs } from '@/runtime/files/runtime-file-client-types'
import { captureRuntimeEnvironmentRequestRevision } from '@/runtime/rpc/environment-revisions/runtime-environment-revision'
import { trackRuntimeDownload } from '@/runtime/files/downloads/runtime-download-progress-store'
import { LOCAL_EXECUTION_HOST_ID } from '../../../../../../shared/execution-host'
import { formatBytes } from '../../../../../../shared/format-bytes'
import type { RuntimeDownloadResult } from '../../../../../../shared/runtime-downloads/runtime-download-contract'
import type { TreeNode } from '../tree/file-explorer-types'
import { RuntimeDownloadProgressBody, runtimeDownloadErrorMessage } from './runtime-download-toast'
export type RuntimeDownloadIntent = 'save' | 'open'
/** Whether this desktop can stream the node straight from its runtime host. */
export function canStreamRuntimeDownload(
node: TreeNode,
context: RuntimeFileOperationArgs | null | undefined
): context is RuntimeFileOperationArgs {
return Boolean(
context && window.api.runtimeDownloads && getRemoteFileArgs(context, node.path) !== null
)
}
function localName(destinationPath: string): string {
const separator = window.api.platform.get().platform === 'win32' ? /[\\/]/ : /\//
return destinationPath.split(separator).pop() || destinationPath
}
export async function startRuntimeDownload(
node: TreeNode,
context: RuntimeFileOperationArgs,
intent: RuntimeDownloadIntent,
options: { excludeDefaultDirs?: boolean } = {}
): Promise<void> {
const api = window.api.runtimeDownloads
const remote = getRemoteFileArgs(context, node.path)
if (!api || !remote) {
return
}
const kind = node.isDirectory ? 'folder' : 'file'
const downloadId = createNonSecureContextUuid()
const toastId = `runtime-download:${downloadId}`
const release = trackRuntimeDownload(downloadId)
const excludeDefaultDirs = options.excludeDefaultDirs !== false
const pending = api.start({
downloadId,
environmentId: remote.target.environmentId,
worktree: remote.worktreeSelector,
relativePath: remote.relativePath,
name: node.name,
kind,
intent,
excludeDefaultDirs,
expectedEnvironmentPairingRevision: captureRuntimeEnvironmentRequestRevision(
remote.target.environmentId
)
})
// The save dialog comes first; show progress only after the user has picked a place.
const showProgress = (): void => {
toast.loading(
intent === 'open'
? translate(
'auto.components.right.sidebar.runtimeDownload.opening',
"Opening '{{value0}}'",
{
value0: node.name
}
)
: translate(
'auto.components.right.sidebar.runtimeDownload.downloading',
"Downloading '{{value0}}'",
{ value0: kind === 'folder' ? `${node.name}.zip` : node.name }
),
{
id: toastId,
description: <RuntimeDownloadProgressBody downloadId={downloadId} kind={kind} />,
duration: Infinity,
dismissible: false,
action: {
label: translate('auto.components.right.sidebar.runtimeDownload.cancel', 'Cancel'),
onClick: (event) => {
event.preventDefault()
void api.cancel({ downloadId })
}
}
}
)
}
const stopProgressWatch = window.api.runtimeDownloads!.onProgress((event) => {
if (event.downloadId === downloadId) {
stopProgressWatch()
showProgress()
}
})
let result: RuntimeDownloadResult
try {
result = await pending
} catch (error) {
result = {
status: 'error',
code: 'transfer_failed',
message: error instanceof Error ? error.message : String(error)
}
} finally {
stopProgressWatch()
release()
}
showOutcome(result, { node, kind, intent, toastId, context, excludeDefaultDirs })
}
function showOutcome(
result: RuntimeDownloadResult,
input: {
node: TreeNode
kind: 'file' | 'folder'
intent: RuntimeDownloadIntent
toastId: string
context: RuntimeFileOperationArgs
excludeDefaultDirs: boolean
}
): void {
const { node, kind, intent, toastId } = input
if (result.status === 'canceled') {
toast.dismiss(toastId)
return
}
if (result.status === 'error') {
toast.error(
intent === 'open'
? translate(
'auto.components.right.sidebar.runtimeDownload.openFailed',
"Couldn't open '{{value0}}'",
{ value0: node.name }
)
: translate(
'auto.components.right.sidebar.runtimeDownload.failed',
"Couldn't download '{{value0}}'",
{ value0: node.name }
),
{
id: toastId,
description: runtimeDownloadErrorMessage(result.code, result.message),
duration: 8000,
dismissible: true,
action: undefined
}
)
return
}
const reveal = {
label: getRevealInFileManagerLabel(),
onClick: () => void revealInFileManager(result.destinationPath, LOCAL_EXECUTION_HOST_ID)
}
if (intent === 'open') {
if (!result.openError) {
toast.dismiss(toastId)
return
}
toast.error(
translate(
'auto.components.right.sidebar.runtimeDownload.noAppToOpen',
"No app could open '{{value0}}'",
{ value0: node.name }
),
{
id: toastId,
description: result.openError,
duration: 8000,
dismissible: true,
action: reveal
}
)
return
}
const parts = [formatBytes(result.bytes)]
if (kind === 'folder' && result.fileCount !== undefined) {
parts.push(
translate('auto.components.right.sidebar.runtimeDownload.fileCount', '{{count}} files', {
count: result.fileCount,
defaultValue_one: '{{count}} file'
})
)
}
if (kind === 'folder' && (result.excludedDirCount ?? 0) > 0) {
parts.push(
translate(
'auto.components.right.sidebar.runtimeDownload.excludedDefaultDirs',
'without node_modules and .git'
)
)
}
if ((result.skippedCount ?? 0) > 0) {
parts.push(
translate(
'auto.components.right.sidebar.runtimeDownload.skipped',
'{{count}} unreadable items skipped',
{ count: result.skippedCount, defaultValue_one: '{{count}} unreadable item skipped' }
)
)
}
toast.success(
translate('auto.components.right.sidebar.runtimeDownload.done', "Downloaded '{{value0}}'", {
value0: localName(result.destinationPath)
}),
{
id: toastId,
description: parts.join(' · '),
duration: 8000,
dismissible: true,
action: reveal,
...(kind === 'file'
? {
cancel: {
label: translate('auto.components.right.sidebar.runtimeDownload.open', 'Open'),
onClick: () =>
void window.api.shell.openPath(result.destinationPath, LOCAL_EXECUTION_HOST_ID)
}
}
: {})
}
)
}
@@ -0,0 +1,139 @@
import { useSyncExternalStore } from 'react'
import { Progress } from '@/components/ui/progress'
import { useTranslate } from '@/i18n/use-translate'
import { translate } from '@/i18n/i18n'
import { formatBytes } from '../../../../../../shared/format-bytes'
import type { RuntimeDownloadErrorCode } from '../../../../../../shared/runtime-downloads/runtime-download-contract'
import {
getRuntimeDownloadProgress,
subscribeRuntimeDownloadProgress,
type RuntimeDownloadProgressSnapshot
} from '@/runtime/files/downloads/runtime-download-progress-store'
/** Fraction done, or null while the size is unknown (folder walk, empty file). */
export function runtimeDownloadFraction(
snapshot: RuntimeDownloadProgressSnapshot | null
): number | null {
if (!snapshot || snapshot.phase !== 'transferring' || !snapshot.totalBytes) {
return null
}
return Math.min(1, snapshot.processedBytes / snapshot.totalBytes)
}
export function RuntimeDownloadProgressBody({
downloadId,
kind
}: {
downloadId: string
kind: 'file' | 'folder'
}): React.JSX.Element {
const t = useTranslate()
const snapshot = useSyncExternalStore(
(listener) => subscribeRuntimeDownloadProgress(downloadId, listener),
() => getRuntimeDownloadProgress(downloadId)
)
const fraction = runtimeDownloadFraction(snapshot)
const percent = fraction === null ? null : Math.round(fraction * 100)
const progressLabel = t(
'auto.components.right.sidebar.runtimeDownload.progressLabel',
'Download progress'
)
let detail: string
if (!snapshot || snapshot.phase === 'preparing') {
detail =
kind === 'folder'
? t('auto.components.right.sidebar.runtimeDownload.preparingFolder', 'Collecting files…')
: t('auto.components.right.sidebar.runtimeDownload.preparingFile', 'Starting…')
} else {
const received = formatBytes(snapshot.receivedBytes)
const rate =
snapshot.bytesPerSecond && snapshot.bytesPerSecond > 0
? t('auto.components.right.sidebar.runtimeDownload.rate', '{{value0}}/s', {
value0: formatBytes(snapshot.bytesPerSecond)
})
: null
const amount =
kind === 'file' && snapshot.totalBytes
? t(
'auto.components.right.sidebar.runtimeDownload.amountOfTotal',
'{{value0}} of {{value1}}',
{
value0: received,
value1: formatBytes(snapshot.totalBytes)
}
)
: received
detail = rate ? `${amount} · ${rate}` : amount
}
return (
<div className="flex w-full min-w-0 flex-col gap-1.5 pt-1">
{percent === null ? (
// Unknown size: an honest sweep beats a faked percentage.
<span
role="progressbar"
aria-label={progressLabel}
aria-valuetext={detail}
className="block h-1.5 w-full overflow-hidden rounded-full bg-primary/20"
>
<span className="block h-full w-2/5 animate-[skill-update-slide_1.35s_ease-in-out_infinite] rounded-full bg-primary motion-reduce:w-full motion-reduce:animate-none motion-reduce:opacity-40" />
</span>
) : (
<Progress
value={percent}
aria-label={progressLabel}
aria-valuetext={`${percent}%, ${detail}`}
className="h-1.5"
/>
)}
<p className="truncate text-xs tabular-nums text-muted-foreground">{detail}</p>
</div>
)
}
export function runtimeDownloadErrorMessage(
code: RuntimeDownloadErrorCode,
hostMessage: string
): string {
switch (code) {
case 'too_large':
return translate(
'auto.components.right.sidebar.runtimeDownload.errorTooLarge',
'It is larger than the 2 GB download limit. Download smaller folders or individual files.'
)
case 'too_many_entries':
return translate(
'auto.components.right.sidebar.runtimeDownload.errorTooManyEntries',
'It has more than 65,000 files and folders. Download a smaller folder.'
)
case 'host_update_required':
return translate(
'auto.components.right.sidebar.runtimeDownload.errorHostUpdate',
'The remote host runs an older Orca server that cannot do this. Update it and try again.'
)
case 'host_busy':
return translate(
'auto.components.right.sidebar.runtimeDownload.errorBusy',
'Too many downloads are running. Wait for one to finish and try again.'
)
case 'not_found':
return translate(
'auto.components.right.sidebar.runtimeDownload.errorNotFound',
'It no longer exists on the remote host.'
)
case 'not_a_file':
case 'not_a_directory':
return translate(
'auto.components.right.sidebar.runtimeDownload.errorChanged',
'It changed on the remote host. Refresh the file explorer and try again.'
)
case 'disconnected':
return translate(
'auto.components.right.sidebar.runtimeDownload.errorDisconnected',
'The connection to the remote host was lost. Reconnect and try again.'
)
case 'open_failed':
case 'transfer_failed':
case 'canceled':
return hostMessage
}
}
@@ -0,0 +1,84 @@
import type { RuntimeDownloadProgressEvent } from '../../../../../shared/runtime-downloads/runtime-download-contract'
export type RuntimeDownloadProgressSnapshot = RuntimeDownloadProgressEvent & {
/** Recent receive rate, smoothed so the label does not jitter. */
bytesPerSecond: number | null
}
type Entry = {
snapshot: RuntimeDownloadProgressSnapshot | null
listeners: Set<() => void>
lastSample: { at: number; bytes: number } | null
}
const entries = new Map<string, Entry>()
let unsubscribeIpc: (() => void) | null = null
// Rate is averaged over this window; shorter windows swing with every page.
const RATE_SMOOTHING = 0.3
function entryFor(downloadId: string): Entry {
let entry = entries.get(downloadId)
if (!entry) {
entry = { snapshot: null, listeners: new Set(), lastSample: null }
entries.set(downloadId, entry)
}
return entry
}
export function applyRuntimeDownloadProgress(
event: RuntimeDownloadProgressEvent,
now = performance.now()
): void {
const entry = entries.get(event.downloadId)
if (!entry) {
return
}
let bytesPerSecond = entry.snapshot?.bytesPerSecond ?? null
if (entry.lastSample && now > entry.lastSample.at) {
const instant =
((event.receivedBytes - entry.lastSample.bytes) * 1000) / (now - entry.lastSample.at)
bytesPerSecond =
bytesPerSecond === null
? instant
: bytesPerSecond + RATE_SMOOTHING * (instant - bytesPerSecond)
}
entry.lastSample = { at: now, bytes: event.receivedBytes }
entry.snapshot = { ...event, bytesPerSecond }
for (const listener of entry.listeners) {
listener()
}
}
/** Starts tracking a download; returns a release that forgets it once its toast is done. */
export function trackRuntimeDownload(downloadId: string): () => void {
entryFor(downloadId)
if (!unsubscribeIpc && window.api.runtimeDownloads) {
unsubscribeIpc = window.api.runtimeDownloads.onProgress((event) =>
applyRuntimeDownloadProgress(event)
)
}
return () => {
entries.delete(downloadId)
if (entries.size === 0 && unsubscribeIpc) {
unsubscribeIpc()
unsubscribeIpc = null
}
}
}
export function subscribeRuntimeDownloadProgress(
downloadId: string,
listener: () => void
): () => void {
const entry = entryFor(downloadId)
entry.listeners.add(listener)
return () => {
entry.listeners.delete(listener)
}
}
export function getRuntimeDownloadProgress(
downloadId: string
): RuntimeDownloadProgressSnapshot | null {
return entries.get(downloadId)?.snapshot ?? null
}
@@ -0,0 +1,54 @@
import { z } from 'zod'
import { FileTreePath } from './files-params'
/** Uncompressed bytes one folder archive may hold; ZIP without ZIP64 tops out at 4 GiB. */
export const FOLDER_ARCHIVE_MAX_TOTAL_BYTES = 2 * 1024 * 1024 * 1024
/** Entries one folder archive may hold; a ZIP without ZIP64 counts entries in 16 bits. */
export const FOLDER_ARCHIVE_MAX_ENTRIES = 65_000
/** Largest archive page one read returns; base64 keeps the reply well under the 4 MiB frame budget. */
export const FOLDER_ARCHIVE_MAX_READ_BYTES = 2 * 1024 * 1024
/** Directory names skipped when the caller asks to leave out dependency and VCS folders. */
export const FOLDER_ARCHIVE_DEFAULT_EXCLUDED_NAMES = ['node_modules', '.git'] as const
export const FileArchiveStart = FileTreePath.extend({
/** Skip FOLDER_ARCHIVE_DEFAULT_EXCLUDED_NAMES at any depth. */
excludeDefaultDirs: z.boolean().optional()
})
export const FileArchiveRead = z.object({
archiveId: z.string().min(1).max(128),
maxBytes: z.number().int().positive().max(FOLDER_ARCHIVE_MAX_READ_BYTES)
})
export const FileArchiveCancel = z.object({
archiveId: z.string().min(1).max(128)
})
export type FileArchiveStartResult = {
archiveId: string
/** Archive name the host suggests, e.g. `src.zip`. */
suggestedName: string
fileCount: number
directoryCount: number
/** Sum of the regular files' sizes at walk time. */
totalBytes: number
/** Directories left out by `excludeDefaultDirs`. */
excludedDirCount: number
}
export type FileArchiveReadResult = {
contentBase64: string
bytesRead: number
eof: boolean
/** Uncompressed file bytes archived so far; compare with `totalBytes` for progress. */
processedBytes: number
/** Entries skipped because they vanished or became unreadable mid-archive. */
skippedCount: number
}
export type FileArchiveErrorCode =
| 'archive_not_directory'
| 'archive_too_large'
| 'archive_too_many_entries'
| 'archive_not_found'
| 'archive_busy'
+4
View File
@@ -238,6 +238,7 @@ import {
TypeParams
} from './emulator-params'
import { EnvironmentDoctorParams } from './environment-doctor-params'
import { FileArchiveCancel, FileArchiveRead, FileArchiveStart } from './files-archive-params'
import {
FileCommitUpload,
FileCopy,
@@ -1066,6 +1067,9 @@ export const RPC_PARAMS_BY_METHOD = {
'emulator.type': TypeParams,
'emulator.unregisterActive': EmulatorUnregisterActiveParams,
'environment.doctor': EnvironmentDoctorParams,
'files.archiveCancel': FileArchiveCancel,
'files.archiveRead': FileArchiveRead,
'files.archiveStart': FileArchiveStart,
'files.browseServerDir': ServerDirectoryBrowse,
'files.commitUpload': FileCommitUpload,
'files.copy': FileCopy,
@@ -0,0 +1,57 @@
/** Desktop downloads of files and folders that live on a paired runtime host. */
export type RuntimeDownloadErrorCode =
| 'canceled'
| 'not_a_file'
| 'not_a_directory'
| 'too_large'
| 'too_many_entries'
| 'host_update_required'
| 'host_busy'
| 'not_found'
| 'disconnected'
| 'open_failed'
| 'transfer_failed'
/** Largest file "Open locally" will fetch into the temp cache. */
export const RUNTIME_OPEN_LOCALLY_MAX_BYTES = 1024 * 1024 * 1024
export type RuntimeDownloadStartArgs = {
/** Caller-chosen id; progress events and cancel use it. */
downloadId: string
environmentId: string
worktree: string
relativePath: string
/** Display name of the remote entry, used for the suggested local name. */
name: string
kind: 'file' | 'folder'
/** `save` asks where to put it; `open` fetches into a temp cache and opens it. */
intent: 'save' | 'open'
excludeDefaultDirs?: boolean
expectedEnvironmentPairingRevision?: number
}
export type RuntimeDownloadProgressEvent = {
downloadId: string
phase: 'preparing' | 'transferring'
receivedBytes: number
totalBytes: number | null
processedBytes: number
/** Present once a save location is chosen. */
destinationPath?: string
}
export type RuntimeDownloadResult =
| { status: 'canceled' }
| {
status: 'done'
destinationPath: string
bytes: number
/** Folder downloads only. */
fileCount?: number
skippedCount?: number
excludedDirCount?: number
/** `open` intent: the OS refused to open the fetched file. */
openError?: string
}
| { status: 'error'; code: RuntimeDownloadErrorCode; message: string }
+1
View File
@@ -63,6 +63,7 @@ function isLongWaitRuntimeMethod(method: string): boolean {
function isBulkReadRuntimeMethod(method: string): boolean {
return (
method === 'files.readChunk' ||
method === 'files.archiveRead' ||
method === 'files.readDocPreviewChunk' ||
method === 'files.readTerminalArtifactChunk'
)