Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

perf(files): 统一远程文件缓存并后台检查更新

Dash83be7aaac344
diff --git a/apps/desktop/src/main/device-link/__tests__/fileAccess.test.ts b/apps/desktop/src/main/device-link/__tests__/fileAccess.test.ts
index ebf65af326..25da52d402 100644
--- a/apps/desktop/src/main/device-link/__tests__/fileAccess.test.ts
+++ b/apps/desktop/src/main/device-link/__tests__/fileAccess.test.ts
@@ -1,7 +1,10 @@
import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { promises as fs } from 'node:fs';
const peer = vi.hoisted(() => vi.fn());
const remove = vi.hoisted(() => vi.fn());
const owner = vi.hoisted(() => ({ current: true }));
+const cache = vi.hoisted(() => ({ get: vi.fn(), put: vi.fn(), invalidate: vi.fn() }));
+vi.mock('../remoteFileVersionCache', () => ({ remoteFileVersionCache: () => cache }));
vi.mock('../filePeer', () => ({ tryPeerFile: peer }));
vi.mock('../mediaTransfer', () => ({ removeRemote: remove }));
vi.mock('../broadcast-tap', () => ({
@@ -16,6 +19,35 @@ beforeEach(() => {
peer.mockResolvedValue(null);
});
describe('desktop shared file access', () => {
+ it('returns cached HTML before a blocked host version check completes', async () => {
+ const result = { ossKey: '', size: 3, mimeType: 'text/html', version: 'c'.repeat(64), inlineBase64: 'YWJj' };
+ cache.get.mockResolvedValueOnce(null).mockResolvedValueOnce('/cache/instant');
+ const read = vi.spyOn(fs, 'readFile').mockResolvedValueOnce(Buffer.from('abc'));
+ const invoke = vi.fn(async (_device, _channel, [args]) => ({ ok: true, result: args.metadataOnly
+ ? { ...result, inlineBase64: undefined, transferRequired: true } : result }));
+ let reply!: (value: any) => void;
+ try {
+ await readRemoteDeviceFile('instant', 'xdt-file://open?path=/cached.html', invoke);
+ invoke.mockImplementationOnce(() => new Promise(resolve => { reply = resolve; }));
+ expect(await readRemoteDeviceFile('instant', 'xdt-file://open?path=/cached.html', invoke)).toEqual(result);
+ expect(invoke).toHaveBeenCalledTimes(3);
+ reply({ ok: true, result });
+ } finally { read.mockRestore(); }
+ });
+ it('checks metadata then reads the same durable cache used by large files', async () => {
+ const result = { ossKey: '', size: 3, mimeType: 'text/html', version: 'a'.repeat(64), inlineBase64: 'YWJj' };
+ cache.get.mockResolvedValueOnce(null).mockResolvedValueOnce('/cache/html');
+ const read = vi.spyOn(fs, 'readFile').mockResolvedValueOnce(Buffer.from('abc'));
+ const invoke = vi.fn(async (_device, _channel, [args]) => ({ ok: true, result: args.metadataOnly
+ ? { ...result, inlineBase64: undefined, transferRequired: true } : result }));
+ try {
+ expect(await readRemoteDeviceFile('d', 'xdt-file://open?path=/a.html', invoke)).toEqual(result);
+ expect(cache.put).toHaveBeenCalledWith(Buffer.from('abc'));
+ expect(await readRemoteDeviceFile('d', 'xdt-file://open?path=/a.html', invoke)).toEqual(result);
+ expect(invoke).toHaveBeenCalledTimes(3);
+ expect(peer).not.toHaveBeenCalled();
+ } finally { read.mockRestore(); }
+ });
it.each(['abort', 'stop', 'owner'] as const)('keeps business requests cancelled while permitting owner-safe close (%s)', async reason => {
const abort = new AbortController();
const invoke = vi.fn(async () => ({ ok: true, result: { ossKey: '', size: 5, mimeType: 'text/plain', transferRequired: true } }));
diff --git a/apps/desktop/src/main/device-link/__tests__/mediaFetch.test.ts b/apps/desktop/src/main/device-link/__tests__/mediaFetch.test.ts
index 880d5856a8..707b33f3c4 100644
--- a/apps/desktop/src/main/device-link/__tests__/mediaFetch.test.ts
+++ b/apps/desktop/src/main/device-link/__tests__/mediaFetch.test.ts
@@ -170,6 +170,17 @@ describe('fetchLocalMediaToOss — scheme 路由', () => {
expect(logDebug.mock.calls.flat().join('\n')).not.toMatch(/xdt-|path=|\/cache\//);
},
);
+ it('returns only authorized metadata for small files when requested', async () => {
+ const read = vi.fn(), close = vi.fn();
+ openMock.mockResolvedValue({ stat: async () => ({ isFile: () => true, size: 5, mtimeMs: 1 }), read, close });
+ imageResolve.mockReturnValue({ absPath: '/cache/a.png', mimeType: 'image/png' });
+ const result = await fetchLocalMediaToOss({ url: 'xdt-image://sess/a.png', prepareOnly: true, metadataOnly: true });
+ expect(result).toMatchObject({ size: 5, transferRequired: true, version: expect.stringMatching(/^[a-f0-9]{64}$/) });
+ expect(result.inlineBase64).toBeUndefined();
+ expect(read).not.toHaveBeenCalled();
+ expect(uploadLocalFile).not.toHaveBeenCalled();
+ expect(close).toHaveBeenCalledOnce();
+ });
it('revalidates source identity without reading/uploading bytes, including restored mtime', async () => {
let ctimeMs = 1;
const read = vi.fn();
diff --git a/apps/desktop/src/main/device-link/__tests__/remoteMediaProtocol.test.ts b/apps/desktop/src/main/device-link/__tests__/remoteMediaProtocol.test.ts
index dee50ccd03..baa451df64 100644
--- a/apps/desktop/src/main/device-link/__tests__/remoteMediaProtocol.test.ts
+++ b/apps/desktop/src/main/device-link/__tests__/remoteMediaProtocol.test.ts
@@ -290,7 +290,7 @@ describe('handleRemoteMedia', () => {
});
const r = await handleRemoteMedia(URL_BLOB, null);
expect(remoteInvoke).toHaveBeenCalledWith('dev-1', 'device-link:media:fetch', [
- { url: BLOB_URL, prepareOnly: true },
+ { url: BLOB_URL, prepareOnly: true, metadataOnly: true },
]);
expect(r.status).toBe(200);
});
@@ -355,7 +355,7 @@ describe('handleRemoteMedia', () => {
const r = await handleRemoteMedia(URL_IMG, null);
expect(remoteInvoke).toHaveBeenCalledWith('dev-1', 'device-link:media:fetch', [
- { url: 'xdt-image://s/a.png', prepareOnly: true },
+ { url: 'xdt-image://s/a.png', prepareOnly: true, metadataOnly: true },
]);
expect(downloadToBuffer).toHaveBeenCalledWith('oss/k.png');
expect(removeRemote).toHaveBeenCalledWith('oss/k.png'); // 用后删
@@ -458,7 +458,7 @@ describe('handleRemoteMedia', () => {
const r = await handleRemoteMedia(URL_IMG, null);
expect(remoteInvoke).toHaveBeenNthCalledWith(1, 'dev-1', 'device-link:media:fetch', [
- { url: 'xdt-image://s/a.png', prepareOnly: true },
+ { url: 'xdt-image://s/a.png', prepareOnly: true, metadataOnly: true },
]);
expect(remoteInvoke).toHaveBeenNthCalledWith(2, 'dev-1', 'device-link:media:fetch', [
{ url: 'xdt-image://s/a.png', skipCache: true },
diff --git a/apps/desktop/src/main/device-link/fileAccess.ts b/apps/desktop/src/main/device-link/fileAccess.ts
index b125fd8770..625b00ba55 100644
--- a/apps/desktop/src/main/device-link/fileAccess.ts
+++ b/apps/desktop/src/main/device-link/fileAccess.ts
@@ -3,16 +3,26 @@ import {
DL_MEDIA_FETCH_CHANNEL,
FILE_PEER_CHANNEL,
FILE_PEER_MAX_BYTES,
+ FILE_INLINE_MAX_BYTES,
+ isSharedTaskPeer,
+ validFileVersion,
type DeviceFileResult,
} from '@cindy/device-link';
-import { tryPeerFile } from './filePeer';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { tryPeerFile, copyReceivedFile } from './filePeer';
+import { activeOwnerScopeKey } from '../appSessionState';
import { captureFilePeerScope } from './filePeerScope';
-import { removeRemote } from './mediaTransfer';
+import { downloadToFile, removeRemote } from './mediaTransfer';
import { captureDataOwnerBroadcastScope, isDataOwnerBroadcastScopeCurrent } from './broadcast-tap';
import { captureRemoteMediaCacheValidity } from './remoteMediaPersistentCache';
type Invoke = Parameters<typeof tryPeerFile>[2];
type LocalFileResult = DeviceFileResult & { path: string; dispose(): Promise<void> };
+// Metadata only: bytes remain in the existing managed disk caches.
+const latestFiles = new Map<string, { url: string; metadata: DeviceFileResult }>();
+let latestOwner = '';
/** Platform adapter; authorization stays in the controlled host's shared resolver. */
export function readRemoteDeviceFile(
device: string,
@@ -35,6 +45,15 @@ export function readRemoteDeviceFile(
const owner = captureDataOwnerBroadcastScope();
const assertCacheCurrent = options.assertCacheCurrent ?? captureRemoteMediaCacheValidity();
const isCurrent = captureFilePeerScope(device);
+ const scope = activeOwnerScopeKey();
+ if (latestOwner !== scope) { latestFiles.clear(); latestOwner = scope; }
+ const cacheKey = JSON.stringify([scope, device, url, options.workdir, options.relPath]);
+ let returnedCached = false;
+ const remember = (result: DeviceFileResult) => {
+ if (isCurrent() && validFileVersion(result.version))
+ latestFiles.set(cacheKey, { url, metadata: { ossKey: '', size: result.size, mimeType: result.mimeType, version: result.version } });
+ return result;
+ };
const invoke: Invoke = async (target, channel, args) => {
// A connection can outlive this read, including an offer answered after cancellation.
// Teardown may cross the read's cancellation boundary, never the account boundary.
@@ -46,9 +65,9 @@ export function readRemoteDeviceFile(
throw new Error('FILE_PEER_CANCELLED');
return rawInvoke(target, channel, args);
};
- const fetch = async (prepareOnly: boolean): Promise<DeviceFileResult> => {
+ const fetch = async (prepareOnly: boolean, metadataOnly = false): Promise<DeviceFileResult> => {
const response = await invoke(device, DL_MEDIA_FETCH_CHANNEL, [
- { url, prepareOnly, ...(options.skipCache ? { skipCache: true } : {}) },
+ { url, prepareOnly, ...(metadataOnly ? { metadataOnly: true } : {}), ...(options.skipCache ? { skipCache: true } : {}) },
]);
if (!response.ok) {
const error = (response as { error?: { code?: string; message?: string } }).error;
@@ -57,6 +76,65 @@ export function readRemoteDeviceFile(
return response.result as DeviceFileResult;
};
return readDeviceFile<LocalFileResult>({
+ cacheFirst: options.skipCache || isSharedTaskPeer(device) ? undefined : {
+ key: cacheKey,
+ read: async () => {
+ const previous = latestFiles.get(cacheKey);
+ if (!previous || (options.stream && /^(audio|video)\//.test(previous.metadata.mimeType))) return null;
+ const { remoteFileVersionCache } = await import('./remoteFileVersionCache');
+ const path = await remoteFileVersionCache(device, previous.url, { ...previous.metadata, assertCacheCurrent })?.get();
+ if (!path) return null;
+ if (previous.metadata.size <= FILE_INLINE_MAX_BYTES) {
+ const bytes = await fs.readFile(path);
+ if (bytes.length !== previous.metadata.size) return null;
+ url = previous.url;
+ returnedCached = true;
+ return { ...previous.metadata, inlineBase64: bytes.toString('base64') };
+ }
+ const copy = await copyReceivedFile({ ...previous.metadata, path, dispose: async () => {} });
+ url = previous.url;
+ returnedCached = true;
+ return { ...copy, ossKey: '' };
+ },
+ retain: async (result) => {
+ if (result.ossKey && validFileVersion(result.version)) {
+ const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'cindy-file-peer-'));
+ try {
+ const file = path.join(directory, 'file');
+ await downloadToFile(result.ossKey, file, undefined, undefined, options.signal);
+ if (!isCurrent() || options.signal?.aborted) return;
+ if ((await fs.stat(file)).size !== result.size) return;
+ const { remoteFileVersionCache } = await import('./remoteFileVersionCache');
+ await remoteFileVersionCache(device, url, { ...result, assertCacheCurrent })?.put(file);
+ } finally { await fs.rm(directory, { recursive: true, force: true }); }
+ }
+ remember(result);
+ },
+ },
+ inline: () => fetch(true),
+ revalidate: () => fetch(true, true),
+ inlineCache: {
+ read: async (metadata) => {
+ const { remoteFileVersionCache } = await import('./remoteFileVersionCache');
+ const cache = remoteFileVersionCache(device, url, { ...metadata, assertCacheCurrent });
+ if (options.skipCache) {
+ await cache?.invalidate();
+ return null;
+ }
+ const path = await cache?.get();
+ if (!path) return null;
+ const bytes = await fs.readFile(path);
+ if (bytes.length !== metadata.size) return null;
+ return { ossKey: '', size: bytes.length, mimeType: metadata.mimeType,
+ version: metadata.version, inlineBase64: bytes.toString('base64') };
+ },
+ store: async (result) => {
+ const { remoteFileVersionCache } = await import('./remoteFileVersionCache');
+ if (options.signal?.aborted || !isCurrent()) return;
+ await remoteFileVersionCache(device, url, { ...result, assertCacheCurrent })
+ ?.put(Buffer.from(result.inlineBase64!, 'base64'));
+ },
+ },
stream: options.stream,
signal: options.signal,
isCurrent,
@@ -89,7 +167,7 @@ export function readRemoteDeviceFile(
url = bounded.toString();
}
}
- return fetch(true);
+ return fetch(true, true);
},
peer: async (metadata) => {
if (
@@ -110,5 +188,5 @@ export function readRemoteDeviceFile(
return result ? { ...result, ossKey: '' } : null;
},
fallback: options.fallback ?? (() => fetch(false)),
- });
+ }).then((result) => { if (!returnedCached) remember(result); return result; });
}
diff --git a/apps/desktop/src/main/device-link/filePeer.ts b/apps/desktop/src/main/device-link/filePeer.ts
index ced1c85fd6..08029401d9 100644
--- a/apps/desktop/src/main/device-link/filePeer.ts
+++ b/apps/desktop/src/main/device-link/filePeer.ts
@@ -749,7 +749,7 @@ export function tryPeerFile(
signal,
);
}
-async function copyReceivedFile(source: ReceivedFile): Promise<ReceivedFile> {
+export async function copyReceivedFile(source: ReceivedFile): Promise<ReceivedFile> {
const directory = await fs.mkdtemp(path.join(app.getPath('temp'), 'cindy-file-peer-'));
const destination = path.join(directory, 'file');
const dispose = () => fs.rm(directory, { recursive: true, force: true });
diff --git a/apps/desktop/src/main/device-link/mediaFetch.ts b/apps/desktop/src/main/device-link/mediaFetch.ts
index 670c2e4d41..464507ce58 100644
--- a/apps/desktop/src/main/device-link/mediaFetch.ts
+++ b/apps/desktop/src/main/device-link/mediaFetch.ts
@@ -440,7 +440,7 @@ export async function resolveAuthorizedMedia(arg: unknown, maximumBytes?: number
export async function fetchLocalMediaToOss(arg: unknown): Promise<MediaFetchResult> {
const record =
arg && typeof arg === 'object'
- ? (arg as { url?: unknown; skipCache?: unknown; thumbnail?: unknown; prepareOnly?: unknown })
+ ? (arg as { url?: unknown; skipCache?: unknown; thumbnail?: unknown; prepareOnly?: unknown; metadataOnly?: unknown })
: {};
const { absPath, mimeType, uploadExtHint, maxBytes, sourceVersion } = await resolveAuthorizedMedia(arg);
const url = record.url as string;
@@ -462,7 +462,7 @@ export async function fetchLocalMediaToOss(arg: unknown): Promise<MediaFetchResu
mimeType ??
mimeOf((uploadExtHint ?? path.extname(absPath)).replace(/^\./, '').toLowerCase()),
};
- if (before.size > FILE_INLINE_MAX_BYTES) {
+ if (record.metadataOnly === true || before.size > FILE_INLINE_MAX_BYTES) {
log.debug(`media:fetch prepare → transfer size=${before.size} mime=${result.mimeType}`);
return { ...result, transferRequired: true };
}
diff --git a/apps/desktop/src/main/device-link/remoteFileVersionCache.ts b/apps/desktop/src/main/device-link/remoteFileVersionCache.ts
index 9de797c993..aa0c942d1b 100644
--- a/apps/desktop/src/main/device-link/remoteFileVersionCache.ts
+++ b/apps/desktop/src/main/device-link/remoteFileVersionCache.ts
@@ -27,7 +27,8 @@ export type FileVersionMetadata = Pick<DeviceFileResult, 'version' | 'size' | 'm
};
/** An adapter to the existing media warehouse / ordinary-file LRU, not another byte store.
- * Authorization and stat happen on the host before this adapter is called, every time.
+ * Versions originate from host authorization/stat; same-owner previews may reuse
+ * the previous version while revalidating in the background.
* Generations guard in-flight work; stable owner IDs key the durable cache across restarts. */
export function remoteFileVersionCache(
device: string,
diff --git a/apps/desktop/src/main/file-browser/__tests__/html-preview-ipc.test.ts b/apps/desktop/src/main/file-browser/__tests__/html-preview-ipc.test.ts
index db4deeb3d9..6c95c00c18 100644
--- a/apps/desktop/src/main/file-browser/__tests__/html-preview-ipc.test.ts
+++ b/apps/desktop/src/main/file-browser/__tests__/html-preview-ipc.test.ts
@@ -81,6 +81,30 @@ it('opens a preview before downloading even a large entry file', async () => {
await expect(mocks.handle.mock.calls[0][1]({}, args)).resolves.toMatchObject({ ok: true });
expect(read).not.toHaveBeenCalled();
});
+it('serves cached HTML while remote stat is blocked, then uses the changed file on the next open', async () => {
+ const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'cindy-preview-swr-test-'));
+ let reply!: (value: any) => void;
+ const metadata = { relPath: 'index.html', type: 'file' as const, size: 3, mtimeMs: 1 };
+ const stat = vi.fn(async () => metadata);
+ const read = vi.fn(async () => path.join(dir, 'old.html'));
+ try {
+ await fs.writeFile(path.join(dir, 'old.html'), 'old');
+ await fs.writeFile(path.join(dir, 'new.html'), 'new');
+ registerHtmlPreviewIpc({ stat, read });
+ const open = mocks.handle.mock.calls[0][1];
+ const first = await open({}, args);
+ expect(await (await readResource(first.url, '/index.html')).text()).toContain('old');
+ stat.mockImplementationOnce(() => new Promise(resolve => { reply = resolve; }));
+ const second = await open({}, args);
+ expect(await (await readResource(second.url, '/index.html')).text()).toContain('old');
+ expect(read).toHaveBeenCalledOnce();
+ read.mockResolvedValueOnce(path.join(dir, 'new.html'));
+ reply({ ...metadata, mtimeMs: 2 });
+ await vi.waitFor(() => expect(read).toHaveBeenCalledTimes(2));
+ const third = await open({}, args);
+ expect(await (await readResource(third.url, '/index.html')).text()).toContain('new');
+ } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
it('passes the captured owner guard through reference-free cache ingestion', async () => {
const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'cindy-preview-owner-test-'));
try {
diff --git a/apps/desktop/src/main/file-browser/html-preview-ipc.ts b/apps/desktop/src/main/file-browser/html-preview-ipc.ts
index 4066067417..888785bb40 100644
--- a/apps/desktop/src/main/file-browser/html-preview-ipc.ts
+++ b/apps/desktop/src/main/file-browser/html-preview-ipc.ts
@@ -19,6 +19,7 @@ import {
} from '../device-link/broadcast-tap.js';
import { getDbClient } from '../localDb/client/current.js';
import { throwIpcError } from '../utils/ipcValidate.js';
+import { isSharedTaskPeer } from '@cindy/device-link';
const log = createLogger('html-preview');
export const HTML_PREVIEW_CHANNEL = 'maker:html-preview:open';
@@ -35,6 +36,11 @@ export async function disposeHtmlPreviews(): Promise<void> {
await Promise.allSettled([...active].map((close) => close()));
}
export function registerHtmlPreviewIpc(remote: RemoteSource): void {
+ // Keep only references to managed cache files, never another copy of their bytes.
+ type CachedFile = { metadata: DirEntry; path: string };
+ const files = new Map<string, CachedFile>();
+ const refreshing = new Set<string>();
+ let cacheOwner: string | undefined;
ipcMain.handle(HTML_PREVIEW_CHANNEL, async (event, args: HtmlPreviewArgs) => {
assertTrustedAppRendererEvent(event);
if (shuttingDown || preparing >= 8)
@@ -43,6 +49,11 @@ export function registerHtmlPreviewIpc(remote: RemoteSource): void {
try {
previewLocation(args);
const scope = captureDataOwnerBroadcastScope();
+ const ownerKey = scope.ownerScopeKey;
+ const cacheable = !!ownerKey && !(args.origin.kind === 'device' && isSharedTaskPeer(args.origin.deviceId));
+ if (cacheOwner !== ownerKey) { files.clear(); cacheOwner = ownerKey; }
+ const keyOf = (root: string, rel: string) => JSON.stringify([ownerKey, args.origin, args.workdir, root, rel]);
+ const selected = new Map<string, CachedFile>();
const isCurrent = () => !shuttingDown && isDataOwnerBroadcastScopeCurrent(scope);
const db = getDbClient().drizzle;
// Finished snapshots are a bounded cache, not concurrent preparation slots.
@@ -59,14 +70,32 @@ export function registerHtmlPreviewIpc(remote: RemoteSource): void {
// Log status only: paths, signed URLs and page contents are not diagnostics.
onResourceError: (status) => log.warn('Preview resource request failed', { status }),
stat: async (root, rel) => {
- if (args.origin.kind !== 'local') return remote.stat(args, root, rel);
+ if (args.origin.kind !== 'local') {
+ const key = keyOf(root, rel);
+ const cached = cacheable ? files.get(key) : undefined;
+ const stat = cached && await fs.stat(cached.path).catch(() => null);
+ if (cached && stat?.isFile() && stat.size === cached.metadata.size) {
+ selected.set(key, cached);
+ return cached.metadata;
+ }
+ selected.delete(key);
+ files.delete(key);
+ return remote.stat(args, root, rel);
+ }
const real = await fs.realpath(path.join(root, rel));
if (!isPathAllowedAgainst(real, getSensitiveMediaBlocklist()))
throw new Error('BAD_ARGS');
return statEntry(root, rel);
},
read: async (root, entry, signal) => {
- if (args.origin.kind !== 'local') return remote.read(args, root, entry, signal);
+ if (args.origin.kind !== 'local') {
+ const key = keyOf(root, entry.relPath);
+ const cached = selected.get(key);
+ if (cached) return cached.path;
+ const file = await remote.read(args, root, entry, signal);
+ if (cacheable && isCurrent() && !signal?.aborted) files.set(key, { metadata: entry, path: file });
+ return file;
+ }
const source = path.join(root, entry.relPath);
const [rootReal, real] = await Promise.all([fs.realpath(root), fs.realpath(source)]);
if (
@@ -79,6 +108,22 @@ export function registerHtmlPreviewIpc(remote: RemoteSource): void {
materialize: async (source, dest, expectedSize) => {
// The temporary tree is a view of managed media, not another persistent media store.
await copyPreviewFile(source, dest, expectedSize);
+ // Start after copying: replacing the shared cache cannot invalidate this view.
+ for (const [key, cached] of selected) {
+ if (cached.path !== source || refreshing.has(key)) continue;
+ refreshing.add(key);
+ const [, , , root, rel] = JSON.parse(key) as string[];
+ void (async () => {
+ if (!isCurrent()) return;
+ const metadata = await remote.stat(args, root, rel);
+ if (!isCurrent() || metadata.type !== 'file') return;
+ const entry = { ...metadata, name: cached.metadata.name };
+ if (entry.size === cached.metadata.size && entry.mtimeMs === cached.metadata.mtimeMs) return;
+ const file = await remote.read(args, root, entry);
+ if (isCurrent()) files.set(key, { metadata: entry, path: file });
+ })().catch(() => { /* Preserve the usable snapshot while offline. */ })
+ .finally(() => refreshing.delete(key));
+ }
const file = await fs.open(dest, 'r');
const probe = Buffer.alloc(8192);
let mime: string | null;
diff --git a/apps/mobile/app/files/[sessionId].tsx b/apps/mobile/app/files/[sessionId].tsx
index ff531928c1..1bada65123 100644
--- a/apps/mobile/app/files/[sessionId].tsx
+++ b/apps/mobile/app/files/[sessionId].tsx
@@ -556,6 +556,11 @@ function RemoteFileBrowserContent() {
deviceId,
openLink,
presignGet,
+ deleteOssObject: (key) => {
+ void auth.apiFetch('/api/device-link/media', {
+ baseUrl: DEVICE_LINK_API_BASE_URL, method: 'DELETE', body: { key },
+ }).catch(() => undefined);
+ },
isCancelled: () => unmountedRef.current || run.cancelled,
},
workdir,
@@ -580,7 +585,7 @@ function RemoteFileBrowserContent() {
}
}
})();
- }, [absolutePathOf, deviceId, maker, openLink, presignGet, resolveFileMedia, showNotice, stopExportRun, t, workdir]);
+ }, [absolutePathOf, auth, deviceId, maker, openLink, presignGet, resolveFileMedia, showNotice, stopExportRun, t, workdir]);
/** lightbox 底部显式操作(与预览页底栏同构):复制路径 / 发送到会话。 */
const lightboxActions = useMemo((): readonly ImageLightboxAction[] => [
diff --git a/apps/mobile/app/files/preview/[sessionId].tsx b/apps/mobile/app/files/preview/[sessionId].tsx
index df00c4b29d..b5b67c02c9 100644
--- a/apps/mobile/app/files/preview/[sessionId].tsx
+++ b/apps/mobile/app/files/preview/[sessionId].tsx
@@ -94,7 +94,7 @@ import { ImageLightbox } from '@/session/ImageLightbox';
import { buildMediaPayload } from '@/session/messagePayload';
import type { MobileMessageGalleryImage } from '@/session/messageGallery';
import type { MobileRemoteMediaPresignResult } from '@/session/remoteMedia';
-import { downloadRemoteMediaShareTemp } from '@/session/remoteMediaDiskCacheExpo';
+import { downloadRemoteMediaShareTemp, retainRemoteFilePreview } from '@/session/remoteMediaDiskCacheExpo';
import { remoteSessionStore, useRemoteSessions } from '@/session/remoteSessionStore';
import { CindyMakeSessionGate } from '@/session/CindyMakeSessionGate';
import { CINDY_MAKE_ENABLED, isCindyMakeSource } from '@cindy/maker-shared/cindy-make-feature';
@@ -430,6 +430,19 @@ function RemoteFilePreviewContent() {
});
}, [auth]);
+ /**
+ * 回收资源取件产生的 OSS 对象(与会话页 deleteRemoteMediaObject 同一端点与语义)。
+ * 空 ossKey(inline 缩略图 / 缓存命中)没有在世对象,跳过。
+ */
+ const deleteResourceOssObject = useCallback((ossKey: string) => {
+ if (!ossKey) return;
+ void auth.apiFetch('/api/device-link/media', {
+ baseUrl: DEVICE_LINK_API_BASE_URL,
+ method: 'DELETE',
+ body: { key: ossKey },
+ }).catch(() => undefined);
+ }, [auth]);
+
/**
* 两段式导出 → presign 下载地址(图片/PDF/音视频原件与「下载原文件」共用)。
* 实现在 fileBrowserExport(与浏览页长按分享共用):path+mtime 缓存、
@@ -443,7 +456,7 @@ function RemoteFilePreviewContent() {
const isCancelled = () => unmountedRef.current || options?.isCancelled?.() === true;
if (singleAbsPath) {
return fetchRemoteAbsFileToUrl(
- { maker, deviceId, openLink, presignGet, stream, isCancelled },
+ { maker, deviceId, openLink, presignGet, stream, isCancelled, deleteOssObject: deleteResourceOssObject },
singleAbsPath,
);
}
@@ -456,28 +469,16 @@ function RemoteFilePreviewContent() {
stream,
isCancelled,
onProgress: options?.onProgress,
+ deleteOssObject: deleteResourceOssObject,
},
workdir,
relPath,
mtimeMs,
);
},
- [deviceId, maker, openLink, presignGet, singleAbsPath, workdir],
+ [deleteResourceOssObject, deviceId, maker, openLink, presignGet, singleAbsPath, workdir],
);
- /**
- * 回收资源取件产生的 OSS 对象(与会话页 deleteRemoteMediaObject 同一端点与语义)。
- * 空 ossKey(inline 缩略图 / 缓存命中)没有在世对象,跳过。
- */
- const deleteResourceOssObject = useCallback((ossKey: string) => {
- if (!ossKey) return;
- void auth.apiFetch('/api/device-link/media', {
- baseUrl: DEVICE_LINK_API_BASE_URL,
- method: 'DELETE',
- body: { key: ossKey },
- }).catch(() => undefined);
- }, [auth]);
-
// SSH 远程工作区的取件上下文:三项必须同时给(被控端 parseSshMediaOrigin 会按
// sessionId 反查会话库逐项比对);本机会话为 null,取件走被控桌面本机路径。
const sshMediaContext = useMemo((): RemoteMediaSshContext | null => {
@@ -1071,7 +1072,7 @@ function PdfPreviewPage({
workdir,
}: {
active: boolean;
- exportToUrl(relPath: string, mtimeMs: number): Promise<string>;
+ exportToUrl(relPath: string, mtimeMs: number, options?: ExportToUrlOptions): Promise<string>;
item: FileBrowserGridItem;
onDownload(): void;
recoveryEpoch: number;
@@ -1108,7 +1109,7 @@ function PdfPreviewPage({
requestedAtRecoveryEpochRef.current = latestRecoveryEpochRef.current;
let cancelled = false;
setFailure(null);
- void exportToUrl(item.relPath, item.mtimeMs)
+ void exportToUrl(item.relPath, item.mtimeMs, { stream: false })
.then(preparePdfPreviewSource)
.then((source) => {
if (cancelled) { source.release(); return; }
@@ -1200,11 +1201,11 @@ function TextPreviewPage({
const [browserNavigation, setBrowserNavigation] = useState<{
preview: MobileHtmlPreview; state: WebViewNavigation;
} | null>(null);
- // absPath 单文件模式(item.relPath 为绝对路径)没有可靠 mtime(恒 0),
- // 缓存键无法随文件覆写失效,读写一律跳过缓存。
- const cacheable = !!workdir && !isAbsolutePathShape(item.relPath);
+ // A cached preview renders immediately, including absolute paths without mtime.
+ // The bounded text request below refreshes it in the background.
+ const cacheable = !!workdir;
const [state, setState] = useState<TextPreviewState>(() => {
- // 内存缓存命中(mtime keyed)直接就绪:翻页/重进零等待、零重复拉取。
+ // Cache identity includes the account, device, workdir and path.
const cached = cacheable ? getCachedPreviewText(cacheScope, workdir, item.relPath, item.mtimeMs) : null;
return cached
? {
@@ -1220,7 +1221,7 @@ function TextPreviewPage({
// data-src-line 定位到覆盖目标行的块并闪高亮;切到源码态仍走精确行号跳转),
// 可切源码;其余文本恒为源码态。
const [richView, setRichView] = useState<'rendered' | 'source'>(richKind ? 'rendered' : 'source');
- const loadedRef = useRef(state.status === 'ready');
+ const loadedRef = useRef(false);
const [textReloadEpoch, setTextReloadEpoch] = useState(0);
const codeListRef = useRef<FlatList<string>>(null);
const scrolledToTargetRef = useRef(false);
@@ -1229,12 +1230,15 @@ function TextPreviewPage({
if (!active || loadedRef.current || !workdir) return;
loadedRef.current = true;
let cancelled = false;
+ const unavailable = (value: TextPreviewState) => setState((previous) =>
+ previous.status === 'ready' ? previous : value);
void readTextFile(item.relPath)
.then((res: FileBrowserReadFileResult) => {
if (cancelled) return;
if (!res.ok) {
+ // A failed refresh must not hide the text the user is already reading.
if (res.code === 'OVERSIZE') {
- setState({
+ unavailable({
status: 'unavailable',
oversize: true,
reason: t('files.preview.oversize', {
@@ -1242,9 +1246,9 @@ function TextPreviewPage({
}),
});
} else if (res.code === 'BINARY_FILE') {
- setState({ status: 'unavailable', reason: t('files.preview.binaryFile') });
+ unavailable({ status: 'unavailable', reason: t('files.preview.binaryFile') });
} else {
- setState({ status: 'unavailable', reason: t('files.preview.readFailed'), retryable: true });
+ unavailable({ status: 'unavailable', reason: t('files.preview.readFailed'), retryable: true });
}
return;
}
@@ -1265,10 +1269,12 @@ function TextPreviewPage({
.catch((err) => {
if (cancelled) return;
loadedRef.current = false; // 传输层瞬断允许重进重试
- setState({ status: 'unavailable', reason: t('files.preview.readFailed'), retryable: true });
+ setState((previous) => previous.status === 'ready' ? previous
+ : { status: 'unavailable', reason: t('files.preview.readFailed'), retryable: true });
});
return () => {
cancelled = true;
+ loadedRef.current = false;
};
}, [active, cacheable, cacheScope, item.relPath, richKind, readTextFile, t, workdir, textReloadEpoch]);
@@ -1490,7 +1496,7 @@ function ImagePreviewPage({
workdir,
}: {
active: boolean;
- exportToUrl(relPath: string, mtimeMs: number): Promise<string>;
+ exportToUrl(relPath: string, mtimeMs: number, options?: ExportToUrlOptions): Promise<string>;
item: FileBrowserGridItem;
maker: Pick<MobileMakerTransport, 'fileBrowser'>;
onOpenLightbox(url: string): void;
@@ -1512,15 +1518,21 @@ function ImagePreviewPage({
const [failure, setFailure] = useState<string | null>(null);
const [attempt, setAttempt] = useState(0);
const requestedRef = useRef(false);
+ const releaseSourceRef = useRef<(() => void) | undefined>(undefined);
+ useEffect(() => () => releaseSourceRef.current?.(), []);
useEffect(() => {
if (!active || requestedRef.current || !workdir) return undefined;
requestedRef.current = true;
let cancelled = false;
setFailure(null);
- void exportToUrl(item.relPath, item.mtimeMs)
- .then((url) => {
- if (!cancelled) setFullUrl(url);
+ void exportToUrl(item.relPath, item.mtimeMs, { stream: false })
+ .then((url) => retainRemoteFilePreview(url, shareMimeForFileName(item.name), item.name))
+ .then((source) => {
+ if (cancelled) { source.release(); return; }
+ releaseSourceRef.current?.();
+ releaseSourceRef.current = source.release;
+ setFullUrl(source.uri);
})
.catch((err) => {
if (cancelled) return;
@@ -1530,7 +1542,7 @@ function ImagePreviewPage({
return () => {
cancelled = true;
};
- }, [active, attempt, exportToUrl, item.mtimeMs, item.relPath, workdir]);
+ }, [active, attempt, exportToUrl, item.mtimeMs, item.name, item.relPath, workdir]);
const displayUri = fullUrl ?? thumbUri;
return (
diff --git a/apps/mobile/app/sessions/[sessionId].tsx b/apps/mobile/app/sessions/[sessionId].tsx
index c89cc3f98f..7651fad2f1 100644
--- a/apps/mobile/app/sessions/[sessionId].tsx
+++ b/apps/mobile/app/sessions/[sessionId].tsx
@@ -9014,9 +9014,7 @@ function SessionScreenContent() {
t,
]);
- /** chip 菜单「导出 / 分享」:两段式导出 → 系统分享单(与文件浏览器同链路);
- * mtime 先列一拍父目录拿真实值(导出 URL 缓存 key 依赖),拿不到用当前时间
- * 兜底——宁可多导出一次也不复用同路径被覆写前的旧文件。
+ /** chip 菜单「导出 / 分享」:优先复用完整文件缓存,后台复验版本,再交给系统分享单。
* workdir 外文件(relPath 为 null)改走被控端 media:fetch 绝对路径取件
* (xdt-file://open?path=…,与文件浏览器 gallery / 预览页 absPath 模式同一通道)。 */
const shareChipFile = useCallback(async (target: ChatFilePathTarget) => {
@@ -9029,29 +9027,23 @@ function SessionScreenContent() {
'/api/device-link/media/presign-get',
{ baseUrl: DEVICE_LINK_API_BASE_URL, method: 'POST', body: { key: ossKey } },
);
+ const deleteOssObject = (key: string) => {
+ void auth.apiFetch('/api/device-link/media', {
+ baseUrl: DEVICE_LINK_API_BASE_URL, method: 'DELETE', body: { key },
+ }).catch(() => undefined);
+ };
let url: string;
if (target.relPath === null) {
url = await fetchRemoteAbsFileToUrl(
- { maker, deviceId, openLink, presignGet, stream: false },
+ { maker, deviceId, openLink, presignGet, stream: false, deleteOssObject },
target.absPath,
);
} else {
- let mtimeMs = Date.now();
- try {
- const raw = await withTransientRemoteRetry(async () => {
- await openLink(deviceId);
- return maker.fileBrowser.listDir(workdir, parentRelPath(target.relPath ?? '') ?? '');
- });
- const entry = normalizeRemoteOpDirEntries(raw).find((item) => item.relPath === target.relPath);
- if (entry) mtimeMs = entry.mtimeMs;
- } catch {
- /* 列目录失败不阻断分享,退当前时间 key */
- }
url = await exportRemoteFileToUrl(
- { maker, deviceId, openLink, presignGet },
+ { maker, deviceId, openLink, presignGet, deleteOssObject },
workdir,
target.relPath,
- mtimeMs,
+ 0,
);
}
const mime = shareMimeForFileName(name);
diff --git a/apps/mobile/src/__tests__/fileAccessCache.test.ts b/apps/mobile/src/__tests__/fileAccessCache.test.ts
index fa1398c22a..addae1c898 100644
--- a/apps/mobile/src/__tests__/fileAccessCache.test.ts
+++ b/apps/mobile/src/__tests__/fileAccessCache.test.ts
@@ -36,6 +36,8 @@ describe("file cache identity", () => {
expect(
getCachedPreviewText("account-b/device-a", "/same", "a", 1),
).toBeNull();
+ // A changed listing mtime doesn't block rendering the previous bounded text.
+ expect(getCachedPreviewText("account-a/device-a", "/same", "a", 2)?.lines).toEqual(['private']);
});
it("does not coalesce indexes on different devices and preserves the real RPC path", async () => {
const make = (scope: string) => ({
diff --git a/apps/mobile/src/__tests__/fileBrowserExportStreaming.test.ts b/apps/mobile/src/__tests__/fileBrowserExportStreaming.test.ts
index ff3d4c2f94..eefd75c283 100644
--- a/apps/mobile/src/__tests__/fileBrowserExportStreaming.test.ts
+++ b/apps/mobile/src/__tests__/fileBrowserExportStreaming.test.ts
@@ -31,7 +31,7 @@ describe('file browser playback and download', () => {
expect(await exportRemoteFileToUrl({ ...deps, stream }, '/p', 'media', 1))
.toBe(stream ? 'https://example.test/stream' : local);
}
- expect(peer).toHaveBeenCalledOnce();
+ expect(peer).toHaveBeenCalledTimes(2);
expect(deps.presignGet).toHaveBeenCalledOnce();
} finally { uninstall(); clearPeerMedia(); }
}
diff --git a/apps/mobile/src/__tests__/mobileMakerTransport.test.ts b/apps/mobile/src/__tests__/mobileMakerTransport.test.ts
index c46a3b8587..e821b3d118 100644
--- a/apps/mobile/src/__tests__/mobileMakerTransport.test.ts
+++ b/apps/mobile/src/__tests__/mobileMakerTransport.test.ts
@@ -10,6 +10,8 @@ import {
} from "@/device-link/mobileMakerTransport";
import type { RemoteInvoke } from "@/device-link/mobileMakerTransport";
import { installPeerFileDownload } from "@/device-link/peerFileRegistry";
+const fileCache = vi.hoisted(() => ({ readLatest: vi.fn(), readInline: vi.fn(), storeInline: vi.fn(), invalidate: vi.fn(), download: vi.fn() }));
+vi.mock('@/device-link/peerFileCache', () => ({ createPeerFileCache: async () => fileCache }));
import { isDirectPreviewableMediaUrl, resolveMobileRemoteMedia } from "@/session/remoteMedia";
import {
setMobileAuthOwner,
@@ -35,6 +37,41 @@ function harness() {
}
describe("mobile maker transport", () => {
+ it('opens a cached file without waiting for connection or host metadata, then refreshes in background', async () => {
+ setMobileAuthOwner('cache-first-owner');
+ const cached = { ossKey: '', size: 3, mimeType: 'application/pdf', version: 'a'.repeat(64), inlineBase64: 'YWJj' };
+ fileCache.readLatest.mockResolvedValueOnce(cached);
+ let connect!: () => void;
+ const beforeFetch = vi.fn(() => new Promise<void>(resolve => { connect = resolve; }));
+ const invoke = vi.fn(async () => ({ ...cached, inlineBase64: undefined, transferRequired: true }));
+ const maker = createMobileMakerTransport({ deviceId: 'cached-device', invoke: invoke as RemoteInvoke });
+ try {
+ expect(await maker.fetchRemoteMedia('xdt-file://open?path=/cached.pdf', { stream: false, beforeFetch })).toEqual(cached);
+ expect(invoke).not.toHaveBeenCalled();
+ expect(beforeFetch).toHaveBeenCalledOnce();
+ connect();
+ await vi.waitFor(() => expect(invoke).toHaveBeenCalledOnce());
+ } finally { authOwnerTesting.reset(); vi.clearAllMocks(); }
+ });
+ it('checks the host version on every small-file read, reuses disk bytes, and honors forced refresh', async () => {
+ setMobileAuthOwner('cache-owner');
+ const result = { ossKey: '', size: 3, mimeType: 'text/html', version: 'a'.repeat(64), inlineBase64: 'YWJj' };
+ let stored: typeof result | null = null;
+ fileCache.readInline.mockImplementation(async () => stored);
+ fileCache.storeInline.mockImplementation(async (_device, _url, value) => { stored = value; });
+ fileCache.invalidate.mockImplementation(async () => { stored = null; });
+ const invoke = vi.fn(async (_device, _channel, [args]) => args.metadataOnly
+ ? { ...result, inlineBase64: undefined, transferRequired: true } : result);
+ const maker = createMobileMakerTransport({ deviceId: 'd', invoke: invoke as RemoteInvoke });
+ try {
+ expect(await maker.fetchRemoteMedia('xdt-file://open?path=/a.html', { stream: false })).toEqual(result);
+ expect(await maker.fetchRemoteMedia('xdt-file://open?path=/a.html', { stream: false })).toEqual(result);
+ expect(invoke).toHaveBeenCalledTimes(3);
+ await maker.fetchRemoteMedia('xdt-file://open?path=/a.html', { stream: false, skipCache: true });
+ expect(fileCache.invalidate).toHaveBeenCalledWith('d', 'xdt-file://open?path=/a.html');
+ expect(invoke).toHaveBeenCalledTimes(5);
+ } finally { authOwnerTesting.reset(); vi.clearAllMocks(); }
+ });
describe.each([
["video", "video/mp4", "mp4"],
["audio", "audio/mpeg", "mp3"],
@@ -815,7 +852,7 @@ describe("mobile maker transport", () => {
],
[
"device-link:media:fetch",
- [{ url: "xdt-image://local/a.png", prepareOnly: true }],
+ [{ url: "xdt-image://local/a.png", prepareOnly: true, metadataOnly: true }],
],
[
"device-link:voice:transcribe",
diff --git a/apps/mobile/src/__tests__/pdfPreviewSource.test.ts b/apps/mobile/src/__tests__/pdfPreviewSource.test.ts
index bd88907253..992a3106ad 100644
--- a/apps/mobile/src/__tests__/pdfPreviewSource.test.ts
+++ b/apps/mobile/src/__tests__/pdfPreviewSource.test.ts
@@ -1,13 +1,12 @@
import { beforeEach, describe, expect, it, vi } from 'vitest';
const { download, remove } = vi.hoisted(() => ({ download: vi.fn(), remove: vi.fn() }));
-vi.mock('@/session/remoteMediaDiskCacheExpo', () => ({ downloadRemoteMediaShareTemp: download }));
-vi.mock('expo-file-system', () => ({ File: class { exists = true; delete = remove; } }));
+vi.mock('@/session/remoteMediaDiskCacheExpo', () => ({ retainRemoteFilePreview: download }));
import { preparePdfPreviewSource } from '@/session/pdfPreviewSource';
describe('PDF preview native source', () => {
beforeEach(() => { vi.clearAllMocks(); });
it('materializes inline PDF bytes and releases only its temporary file', async () => {
- download.mockResolvedValue('file:///cache/preview.pdf');
+ download.mockResolvedValue({ uri: 'file:///cache/preview.pdf', release: remove });
const source = await preparePdfPreviewSource('data:application/pdf;base64,JVBERg==');
expect(source.uri).toBe('file:///cache/preview.pdf');
expect(download).toHaveBeenCalledWith('data:application/pdf;base64,JVBERg==', 'application/pdf', 'preview.pdf');
@@ -15,16 +14,17 @@ describe('PDF preview native source', () => {
source.release();
expect(remove).toHaveBeenCalledOnce();
});
- it.each(['https://example.com/document.pdf', 'file:///existing/document.pdf'])('preserves existing source %s without owning its file', async uri => {
+ it.each(['https://example.com/document.pdf', 'file:///existing/document.pdf'])('delegates source ownership for %s', async uri => {
+ download.mockResolvedValue({ uri, release: remove });
const source = await preparePdfPreviewSource(uri);
expect(source.uri).toBe(uri);
source.release();
- expect(download).not.toHaveBeenCalled();
- expect(remove).not.toHaveBeenCalled();
+ expect(download).toHaveBeenCalledWith(uri, 'application/pdf', 'preview.pdf');
+ expect(remove).toHaveBeenCalledOnce();
});
it('rejects unsupported sources and failed cache writes before reaching WebView', async () => {
await expect(preparePdfPreviewSource('data:text/html;base64,AA==')).rejects.toThrow('INVALID_PDF_URL');
- download.mockResolvedValue(null);
- await expect(preparePdfPreviewSource('data:application/pdf;base64,JVBERg==')).rejects.toThrow('PDF_CACHE_FAILED');
+ download.mockRejectedValue(new Error('PREVIEW_CACHE_FAILED'));
+ await expect(preparePdfPreviewSource('data:application/pdf;base64,JVBERg==')).rejects.toThrow('PREVIEW_CACHE_FAILED');
});
});
diff --git a/apps/mobile/src/__tests__/peerFileCache.test.ts b/apps/mobile/src/__tests__/peerFileCache.test.ts
index a9d2356f73..dcff3f2bae 100644
--- a/apps/mobile/src/__tests__/peerFileCache.test.ts
+++ b/apps/mobile/src/__tests__/peerFileCache.test.ts
@@ -41,6 +41,7 @@ vi.mock("expo-file-system", () => ({
delete() {
disk.files.delete(this.uri);
}
+ async base64() { return Buffer.from(disk.files.get(this.uri)!).toString('base64'); }
async copy(target: { uri: string }) {
disk.copying = true;
if (disk.gate) await disk.gate;
@@ -53,6 +54,13 @@ vi.mock("expo-file-system", () => ({
},
}));
vi.mock("@/session/remoteMediaDiskCacheExpo", () => ({
+ downloadRemoteMediaShareTemp: async (url: string) => {
+ const uri = `file:///download-${++disk.seq}`;
+ const bytes = disk.files.get(url);
+ if (!bytes) return null;
+ disk.files.set(uri, bytes.slice());
+ return uri;
+ },
createExpoRemoteMediaDiskCacheIO: (namespace: string) => {
const uri = (name: string) => `file:///cache/${namespace}/${name}`;
return {
@@ -72,7 +80,7 @@ vi.mock("@/session/remoteMediaDiskCacheExpo", () => ({
.filter((p) => p.startsWith(`file:///cache/${namespace}/`))
.map((p) => p.split("/").at(-1)!),
download: async (source: string, name: string) => {
- const bytes = disk.files.get(source);
+ const bytes = source.startsWith('data:') ? Buffer.from(source.split(',')[1], 'base64') : disk.files.get(source);
if (!bytes) return null;
disk.files.set(uri(name), bytes.slice());
return bytes.length;
@@ -94,6 +102,26 @@ afterEach(() => {
disk.available = 10 * 1024 ** 3;
});
const metadata = { size: 5, mimeType: "text/html", version: "a".repeat(64) };
+it('reuses completed OSS downloads through the same cache and does not retain changed-sized bytes', async () => {
+ const cache = await createPeerFileCache('oss-owner');
+ disk.files.set('https://oss/file', new Uint8Array(5));
+ const result = await cache.download('device', 'url', metadata, 'https://oss/file', () => true);
+ expect(result).not.toBeNull();
+ releasePeerMedia(peerMediaUri(result!)!);
+ expect(await cache.read('device', 'url', metadata, () => true)).not.toBeNull();
+ expect(await cache.download('device', 'changed', { ...metadata, size: 6 }, 'https://oss/file', () => true)).toBeNull();
+ expect(await cache.read('device', 'changed', metadata, () => true)).toBeNull();
+});
+it.each([0, 5])('shares %s-byte inline files with the durable version cache', async size => {
+ const cache = await createPeerFileCache(`inline-${size}`);
+ const result = { ossKey: '', ...metadata, size, inlineBase64: Buffer.alloc(size, 7).toString('base64') };
+ await cache.storeInline('device', 'url', result);
+ expect(await cache.readLatest('device', 'url', () => true)).toEqual(result);
+ expect(await cache.readInline('device', 'url', result, () => true)).toEqual(result);
+ expect(await cache.readInline('other-device', 'url', result, () => true)).toBeNull();
+ expect(await cache.readInline('device', 'url', { ...result, version: 'b'.repeat(64) }, () => true)).toBeNull();
+ expect(await cache.readLatest('device', 'url', () => true)).toEqual(result);
+});
async function seed(owner: string) {
const cache = await createPeerFileCache(owner);
const uri = `file:///received/${owner}`;
diff --git a/apps/mobile/src/__tests__/remoteAbsFileFetch.test.ts b/apps/mobile/src/__tests__/remoteAbsFileFetch.test.ts
index af18ea7865..9439fd727c 100644
--- a/apps/mobile/src/__tests__/remoteAbsFileFetch.test.ts
+++ b/apps/mobile/src/__tests__/remoteAbsFileFetch.test.ts
@@ -38,15 +38,15 @@ function makeDeps(overrides: Partial<{
}
describe('fetchRemoteAbsFileToUrl', () => {
- it('separates streaming and complete-file cache entries in either order', async () => {
+ it('revalidates complete files while retaining streaming URLs', async () => {
for (const first of [true, false]) {
const { deps, fetchRemoteMedia } = makeDeps();
await fetchRemoteAbsFileToUrl({ ...deps, stream: first }, '/media.mp4');
await fetchRemoteAbsFileToUrl({ ...deps, stream: !first }, '/media.mp4');
await fetchRemoteAbsFileToUrl({ ...deps, stream: first }, '/media.mp4');
- expect(fetchRemoteMedia).toHaveBeenCalledTimes(2);
- expect(fetchRemoteMedia.mock.calls.map((call) => (call as unknown[])[1])).toEqual(
- first ? [undefined, { stream: false }] : [{ stream: false }, undefined],
+ expect(fetchRemoteMedia).toHaveBeenCalledTimes(first ? 2 : 3);
+ expect(fetchRemoteMedia.mock.calls.map((call) => ((call as unknown[])[1] as { stream?: boolean }).stream)).toEqual(
+ first ? [undefined, false] : [false, undefined, false],
);
}
});
@@ -78,7 +78,7 @@ describe('fetchRemoteAbsFileToUrl', () => {
expect(url).toBe('https://oss.example/get/abc');
expect(fetchRemoteMedia).toHaveBeenCalledWith(
`xdt-file://open?path=${encodeURIComponent('/tmp/shot.png')}`,
- undefined,
+ expect.objectContaining({ beforeFetch: expect.any(Function) }),
);
expect(presignGet).toHaveBeenCalledWith('oss/abc');
});
@@ -134,7 +134,7 @@ describe('fetchRemoteAbsFileToUrl', () => {
await fetchRemoteAbsFileToUrl(deps, 'C:\\tmp\\shot.png');
expect(fetchRemoteMedia).toHaveBeenCalledWith(
`xdt-file://open?path=${encodeURIComponent('C:\\tmp\\shot.png')}`,
- undefined,
+ expect.objectContaining({ beforeFetch: expect.any(Function) }),
);
});
});
diff --git a/apps/mobile/src/__tests__/remoteMedia.test.ts b/apps/mobile/src/__tests__/remoteMedia.test.ts
index 0b1d7adf6a..37d39ef774 100644
--- a/apps/mobile/src/__tests__/remoteMedia.test.ts
+++ b/apps/mobile/src/__tests__/remoteMedia.test.ts
@@ -12,6 +12,42 @@ import {
} from "@/session/remoteMedia";
describe("mobile remote media", () => {
+ it('retains a background fallback and releases its staging copy and cloud object', async () => {
+ const { recordPeerMedia } = await import('@/device-link/peerFileRegistry');
+ const local = { ossKey: '', mimeType: 'application/pdf', size: 3 };
+ const dispose = vi.fn();
+ recordPeerMedia(local, 'file:///background/pdf', dispose);
+ let retain!: NonNullable<import('@/session/remoteMedia').MobileRemoteMediaFetchOptions['retainBackground']>;
+ const discardBackgroundOssKey = vi.fn();
+ await resolveMobileRemoteMedia({ kind: 'file', url: 'xdt-file://open?path=/a.pdf' }, {
+ fetchRemoteMedia: async (_url, options) => {
+ retain = options!.retainBackground!;
+ return { ...local, inlineBase64: 'YWJj' };
+ },
+ presignGet: async () => ({ getUrl: 'https://oss/new', expiresAt: '2099-01-01T00:00:00Z' }),
+ }, { stream: false, discardBackgroundOssKey });
+ const cacheDownload = vi.fn(async () => local);
+ await retain({ ...local, ossKey: 'oss/new', cacheDownload });
+ expect(cacheDownload).toHaveBeenCalledWith('https://oss/new');
+ expect(dispose).toHaveBeenCalledOnce();
+ expect(discardBackgroundOssKey).toHaveBeenCalledWith('oss/new');
+ });
+ it('returns a completed fallback copy while preserving ownership of the OSS object', async () => {
+ const { recordPeerMedia, releasePeerMedia } = await import('@/device-link/peerFileRegistry');
+ const local = { ossKey: '', mimeType: 'application/pdf', size: 3 };
+ recordPeerMedia(local, 'file:///cached/pdf', () => {});
+ const cacheDownload = vi.fn(async () => local);
+ const onOssKey = vi.fn();
+ try {
+ const result = await resolveMobileRemoteMedia({ kind: 'file', url: 'xdt-file://open?path=/a.pdf' }, {
+ fetchRemoteMedia: async () => ({ ossKey: 'oss/file', size: 3, mimeType: local.mimeType, cacheDownload }),
+ presignGet: async () => ({ getUrl: 'https://oss/file', expiresAt: '2099-01-01T00:00:00Z' }),
+ }, { stream: false, onOssKey });
+ expect(result).toMatchObject({ url: 'file:///cached/pdf', ossKey: 'oss/file' });
+ expect(cacheDownload).toHaveBeenCalledWith('https://oss/file');
+ expect(onOssKey).toHaveBeenCalledExactlyOnceWith('oss/file');
+ } finally { releasePeerMedia('file:///cached/pdf'); }
+ });
it.each(['DEVICE_OFFLINE', 'NOT_CONNECTED', 'DEVICE_LINK_NOT_CONNECTED', 'PEER_OFFLINE'])(
'recognizes the structured %s code even when its message has no code', (code) => {
expect(mediaLoadFailureKey(Object.assign(new Error('remote device is unavailable'), { code }))).toBe('message.lightbox.deviceOffline');
diff --git a/apps/mobile/src/__tests__/remoteMediaDiskCache.test.ts b/apps/mobile/src/__tests__/remoteMediaDiskCache.test.ts
index 0047d2efa7..5093009f21 100644
--- a/apps/mobile/src/__tests__/remoteMediaDiskCache.test.ts
+++ b/apps/mobile/src/__tests__/remoteMediaDiskCache.test.ts
@@ -36,6 +36,17 @@ const URL_B = 'xdt-image://cache/b.png';
const URL_C = 'xdt-image://cache/c.png';
describe('remoteMediaDiskCache', () => {
+ it('keeps the previous version available until a changed download successfully commits', async () => {
+ const { io } = memoryIO();
+ const cache = createRemoteMediaDiskCache(io);
+ await cache.store(URL_A, 'https://old', 'application/pdf', 1000, 'a'.repeat(64));
+ expect(await cache.lookup(URL_A, 'b'.repeat(64))).toBeNull();
+ vi.mocked(io.download).mockResolvedValueOnce(null);
+ expect(await cache.store(URL_A, 'https://new', 'application/pdf', 1000, 'b'.repeat(64))).toBe(false);
+ expect(await cache.lookup(URL_A)).toMatchObject({ version: 'a'.repeat(64), size: 1000 });
+ await cache.store(URL_A, 'https://new', 'application/pdf', 1000, 'b'.repeat(64));
+ expect(await cache.lookup(URL_A)).toMatchObject({ version: 'b'.repeat(64), size: 1000 });
+ });
it('protects the source of a pending copy while reclaiming other entries', async () => {
const h = memoryIO();
let capacity = 10_000;
diff --git a/apps/mobile/src/__tests__/remoteMediaDiskCacheExpo.test.ts b/apps/mobile/src/__tests__/remoteMediaDiskCacheExpo.test.ts
index 632a7c39bb..9ef3d5a6aa 100644
--- a/apps/mobile/src/__tests__/remoteMediaDiskCacheExpo.test.ts
+++ b/apps/mobile/src/__tests__/remoteMediaDiskCacheExpo.test.ts
@@ -3,6 +3,7 @@ import {
downloadRemoteMediaAsDataUri,
downloadRemoteMediaShareTemp,
withDownloadedRemoteMediaFile,
+ retainRemoteFilePreview,
} from '@/session/remoteMediaDiskCacheExpo';
const io = vi.hoisted(() => ({
@@ -63,6 +64,18 @@ beforeEach(() => {
});
describe('bounded temporary media downloads', () => {
+ it('keeps a preview copy alive after transport staging expires, until its owner releases it', async () => {
+ const { recordPeerMedia, releasePeerMedia } = await import('@/device-link/peerFileRegistry');
+ const dispose = vi.fn();
+ recordPeerMedia({ ossKey: '', size: 5, mimeType: 'application/pdf' }, 'file:///peer/source', dispose);
+ const retained = await retainRemoteFilePreview('file:///peer/source', 'application/pdf', 'preview.pdf');
+ expect(io.copied.has(retained.uri)).toBe(true);
+ expect(dispose).toHaveBeenCalledOnce();
+ releasePeerMedia('file:///peer/source');
+ expect(io.remove).not.toHaveBeenCalled();
+ retained.release();
+ expect(io.remove).toHaveBeenCalledExactlyOnceWith(retained.uri);
+ });
it('keeps the file until the asynchronous consumer finishes, then removes it', async () => {
let finish!: (value: string) => void;
const read = vi.fn(() => new Promise<string>((done) => { finish = done; }));
diff --git a/apps/mobile/src/device-link/mobileMakerTransport.ts b/apps/mobile/src/device-link/mobileMakerTransport.ts
index 3e850e9c37..a63b6c578c 100644
--- a/apps/mobile/src/device-link/mobileMakerTransport.ts
+++ b/apps/mobile/src/device-link/mobileMakerTransport.ts
@@ -4,6 +4,7 @@ import {
releasePeerMedia,
} from "./peerFileRegistry";
import { withTransientRemoteRetry } from "./remoteRetry";
+import { getActiveMobileSessionRealm } from '@/config/env';
import { expandGhostCommand, parseGhostCommandWord, splitGhostDirective } from '@cindy/maker-shared/ghost-command';
import { composerPluginListSchema, isComposerPluginCatalogUnsupportedError, type ComposerPlugin } from '@/session/remoteComposerPlugins';
import type { OrcaWorkerAgentKind, OrcaWorkerPermissionMode } from "@cindy/maker-shared/orca-team";
@@ -43,6 +44,7 @@ import {
createDeviceFileOperations,
exportDeviceFile,
assertFileReadActive,
+ validFileVersion,
type DeviceFileResult,
} from "@cindy/device-link";
import { errorText, mediaExtOf, nextFileTrace } from "@/debug/fileDiagnostics";
@@ -911,6 +913,7 @@ export interface MobileMakerTransport {
beforeInvoke?: () => Promise<unknown>,
options?: {
stream?: boolean;
+ retainBackground?: MobileRemoteMediaFetchOptions['retainBackground'];
/** Upload progress while the computer stages the file in cloud storage. */
onProgress?: (uploaded: number, total: number) => void;
},
@@ -1006,6 +1009,8 @@ export type SessionMetaPatch = Partial<
>;
export const MOBILE_MAKER_CHANNELS = MOBILE_REMOTE_INVOKE_CHANNELS;
+const fileReferences = new Map<string, string>();
+let fileReferencesOwner = '';
export function createMobileMakerTransport({
deviceId,
@@ -1014,8 +1019,17 @@ export function createMobileMakerTransport({
}: MobileMakerTransportDeps): MobileMakerTransport {
const fileOwner = getMobileAuthOwner();
const callerIsCurrent = isCurrent;
- isCurrent = () =>
+ const fileIsCurrent = () =>
isMobileAuthOwnerCurrent(fileOwner) && callerIsCurrent?.() !== false;
+ isCurrent = fileIsCurrent;
+ const fileCacheOwner = JSON.stringify([getActiveMobileSessionRealm(), fileOwner.accountId]);
+ const referenceOwner = JSON.stringify([fileOwner.accountKey, fileOwner.generation]);
+ if (fileReferencesOwner !== referenceOwner) { fileReferences.clear(); fileReferencesOwner = referenceOwner; }
+ const getFileCache = async () => {
+ if (!fileOwner.accountId || !fileIsCurrent()) return null;
+ const { createPeerFileCache } = await import('./peerFileCache');
+ return createPeerFileCache(fileCacheOwner);
+ };
const call = <T>(channel: string, args: unknown[] = []): Promise<T> => {
if (!deviceId)
return Promise.reject(new Error("remote device id is required"));
@@ -1054,15 +1068,35 @@ export function createMobileMakerTransport({
fallback?: () => Promise<MobileRemoteMediaFetchResult>,
stream = opts?.stream ?? true,
) => {
- const fetch = (prepareOnly: boolean) =>
- call<MobileRemoteMediaFetchResult>(DEVICE_LINK_MEDIA_FETCH_CHANNEL, [
+ const fetch = async (prepareOnly: boolean, metadataOnly = false) => {
+ if (!fileIsCurrent() || opts?.signal?.aborted) throw new Error('FILE_PEER_CANCELLED');
+ await opts?.beforeFetch?.();
+ if (!fileIsCurrent() || opts?.signal?.aborted) throw new Error('FILE_PEER_CANCELLED');
+ return call<MobileRemoteMediaFetchResult>(DEVICE_LINK_MEDIA_FETCH_CHANNEL, [
{
url,
prepareOnly,
+ ...(metadataOnly ? { metadataOnly: true } : {}),
...(opts?.skipCache ? { skipCache: true } : {}),
...(opts?.thumbnail ? { thumbnail: true } : {}),
},
]);
+ };
+ const withDownload = (result: MobileRemoteMediaFetchResult): MobileRemoteMediaFetchResult => {
+ if (stream || opts?.thumbnail || !result.ossKey || !validFileVersion(result.version)) return result;
+ return { ...result, cacheDownload: async (downloadUrl) => {
+ const active = () => fileIsCurrent() && !opts?.signal?.aborted;
+ if (!active()) throw new Error('FILE_PEER_CANCELLED');
+ const cache = await getFileCache().catch(() => null);
+ const local = await cache?.download(deviceId, url, result, downloadUrl, active, opts?.signal).catch(() => null);
+ if (!active()) {
+ const uri = local && peerMediaUri(local);
+ if (uri) releasePeerMedia(uri);
+ throw new Error('FILE_PEER_CANCELLED');
+ }
+ return local ?? null;
+ } };
+ };
// Chat thumbnails are high-volume and already covered by the list; trace full-file reads only.
const trace = opts?.thumbnail ? 0 : nextFileTrace();
const stage = <T>(
@@ -1107,7 +1141,28 @@ export function createMobileMakerTransport({
"result",
() =>
readDeviceFile({
+ cacheFirst: stream || opts?.skipCache || opts?.thumbnail || isSharedTaskPeer(deviceId) ? undefined : {
+ key: JSON.stringify([fileOwner.accountKey, fileOwner.generation, deviceId, url]),
+ read: async () => (await getFileCache())?.readLatest(deviceId, url, () => fileIsCurrent() && !opts?.signal?.aborted) ?? null,
+ retain: async (result) => { await opts?.retainBackground?.(withDownload(result), fileIsCurrent); },
+ },
stream,
+ inline: () => fetch(true),
+ revalidate: () => fetch(true, true),
+ inlineCache: opts?.thumbnail ? undefined : {
+ read: async (metadata) => {
+ const cache = await getFileCache();
+ if (opts?.skipCache) {
+ await cache?.invalidate(deviceId, url);
+ return null;
+ }
+ return cache?.readInline(deviceId, url, metadata, () => isCurrent() && !opts?.signal?.aborted) ?? null;
+ },
+ store: async (result) => {
+ const cache = await getFileCache();
+ if (isCurrent() && !opts?.signal?.aborted) await cache?.storeInline(deviceId, url, result);
+ },
+ },
peerResultIsTransient: true,
isCurrent,
discard: (result) => {
@@ -1122,7 +1177,7 @@ export function createMobileMakerTransport({
},
signal: opts?.signal,
prepare: () =>
- stage("prepare", () => fetch(!opts?.thumbnail), describeResult),
+ stage("prepare", () => fetch(!opts?.thumbnail, !opts?.thumbnail), describeResult),
peer: (metadata) =>
metadata.size <= FILE_PEER_MAX_BYTES
? stage(
@@ -1143,7 +1198,7 @@ export function createMobileMakerTransport({
: "upload",
size: result.size,
}),
- );
+ ).then(withDownload);
};
return {
@@ -1529,13 +1584,18 @@ export function createMobileMakerTransport({
assertFileReadActive(signal);
return fileOp<T>(args);
});
+ const referenceKey = JSON.stringify([referenceOwner, deviceId, workdir, relPath]);
+ const knownUrl = fileReferences.get(referenceKey);
+ const fallback = () =>
+ exportDeviceFile(retryOp, workdir, relPath, signal, options?.onProgress);
+ const fetchOptions = { signal, beforeFetch: beforeInvoke, retainBackground: options?.retainBackground };
+ if (knownUrl && !isSharedTaskPeer(deviceId))
+ return fetchMedia(knownUrl, fetchOptions, fallback, options?.stream ?? false);
const caps = await retryOp<{ fileRead?: boolean }>({
op: "caps",
workdir,
});
assertFileReadActive(signal);
- const fallback = () =>
- exportDeviceFile(retryOp, workdir, relPath, signal, options?.onProgress);
if (!caps.fileRead) {
mobileDebugLog("debug", "files", "file export without direct read", {
reason: "host-lacks-file-read",
@@ -1550,7 +1610,8 @@ export function createMobileMakerTransport({
assertFileReadActive(signal);
if (!reference.ok)
throw new Error(reference.message ?? "FILE_READ_FAILED");
- return fetchMedia(reference.url, { signal }, fallback, options?.stream ?? false);
+ if (fileIsCurrent()) fileReferences.set(referenceKey, reference.url);
+ return fetchMedia(reference.url, fetchOptions, fallback, options?.stream ?? false);
},
caps: (workdir) =>
call("file-browser:remote-op", [{ op: "caps", workdir }]),
diff --git a/apps/mobile/src/device-link/peerFileCache.ts b/apps/mobile/src/device-link/peerFileCache.ts
index c1bf06d50e..16d93ce59a 100644
--- a/apps/mobile/src/device-link/peerFileCache.ts
+++ b/apps/mobile/src/device-link/peerFileCache.ts
@@ -4,13 +4,14 @@ import {
digestStringAsync,
randomUUID,
} from "expo-crypto";
-import { validFileVersion, type DeviceFileResult } from "@cindy/device-link";
+import { FILE_INLINE_MAX_BYTES, validFileVersion, type DeviceFileResult } from "@cindy/device-link";
import { createRemoteMediaDiskCache } from "@/session/remoteMediaDiskCache";
-import { createExpoRemoteMediaDiskCacheIO } from "@/session/remoteMediaDiskCacheExpo";
+import { createExpoRemoteMediaDiskCacheIO, downloadRemoteMediaShareTemp } from "@/session/remoteMediaDiskCacheExpo";
import {
PEER_FILE_DISK_RESERVE_BYTES,
recordPeerMedia,
peerMediaUri,
+ releasePeerMedia,
type LocalPeerMedia,
} from "./peerFileRegistry";
@@ -39,7 +40,44 @@ async function openPeerFileCache(owner: string) {
persistAccess: true,
},
);
- return {
+ const api = {
+ async readLatest(device: string, url: string, active: () => boolean): Promise<DeviceFileResult | null> {
+ const hit = await cache.lookup(JSON.stringify([device, url]));
+ if (!active() || !hit || !validFileVersion(hit.version)) return null;
+ const metadata = { size: hit.size, mimeType: hit.mimeType, version: hit.version };
+ return hit.size <= FILE_INLINE_MAX_BYTES
+ ? api.readInline(device, url, metadata, active)
+ : api.read(device, url, metadata, active);
+ },
+ /** A completed OSS fallback joins the same version cache as direct downloads. */
+ async download(device: string, url: string, metadata: Metadata, downloadUrl: string,
+ active: () => boolean, signal?: AbortSignal): Promise<LocalPeerMedia | null> {
+ if (!active() || !validFileVersion(metadata.version) || !(await cache.prune(2 * metadata.size))) return null;
+ const uri = await downloadRemoteMediaShareTemp(downloadUrl, metadata.mimeType, undefined, signal);
+ if (!uri) return null;
+ const file = new File(uri);
+ const dispose = () => { if (file.exists) file.delete(); };
+ if (!active() || signal?.aborted || file.size !== metadata.size) { dispose(); return null; }
+ const result = { ossKey: '', ...metadata };
+ if (!recordPeerMedia(result, uri, dispose)) { dispose(); return null; }
+ await api.store(device, url, metadata, result).catch(() => undefined);
+ if (!active() || signal?.aborted) { releasePeerMedia(uri); return null; }
+ return result;
+ },
+ async readInline(device: string, url: string, metadata: Metadata, active: () => boolean) {
+ if (!validFileVersion(metadata.version) || metadata.size > FILE_INLINE_MAX_BYTES) return null;
+ const hit = await cache.lookup(JSON.stringify([device, url]), metadata.version);
+ if (!active() || !hit || hit.size !== metadata.size) return null;
+ const inlineBase64 = await new File(hit.uri).base64();
+ if (!active()) return null;
+ return { ossKey: '', ...metadata, inlineBase64 };
+ },
+ async storeInline(device: string, url: string, result: DeviceFileResult) {
+ if (!validFileVersion(result.version) || typeof result.inlineBase64 !== 'string'
+ || result.size > FILE_INLINE_MAX_BYTES) return;
+ await cache.store(JSON.stringify([device, url]),
+ `data:${result.mimeType};base64,${result.inlineBase64}`, result.mimeType, result.size, result.version);
+ },
prune: (size: number) => cache.prune(2 * size),
invalidate: (device: string, url: string) =>
cache.remove(JSON.stringify([device, url])),
@@ -105,4 +143,5 @@ async function openPeerFileCache(owner: string) {
);
},
};
+ return api;
}
diff --git a/apps/mobile/src/session/fileBrowserCache.ts b/apps/mobile/src/session/fileBrowserCache.ts
index f9a3a9d01d..22f3d8ff72 100644
--- a/apps/mobile/src/session/fileBrowserCache.ts
+++ b/apps/mobile/src/session/fileBrowserCache.ts
@@ -261,10 +261,10 @@ export function getCachedPreviewText(
scope: string,
workdir: string,
relPath: string,
- mtimeMs: number,
+ _mtimeMs: number,
): CachedPreviewText | null {
workdir = JSON.stringify([scope, workdir]);
- const key = snippetKey(workdir, relPath, mtimeMs);
+ const key = snippetKey(workdir, relPath, 0);
const value = previewTextMemory.get(key);
if (!value) return null;
previewTextMemory.delete(key);
@@ -276,11 +276,11 @@ export function storeCachedPreviewText(
scope: string,
workdir: string,
relPath: string,
- mtimeMs: number,
+ _mtimeMs: number,
value: CachedPreviewText,
): void {
workdir = JSON.stringify([scope, workdir]);
- const key = snippetKey(workdir, relPath, mtimeMs);
+ const key = snippetKey(workdir, relPath, 0);
previewTextMemory.delete(key);
previewTextMemory.set(key, value);
while (previewTextMemory.size > PREVIEW_TEXT_MAX_ENTRIES) {
diff --git a/apps/mobile/src/session/fileBrowserExport.ts b/apps/mobile/src/session/fileBrowserExport.ts
index ea5ff3ca94..7b1e5f23aa 100644
--- a/apps/mobile/src/session/fileBrowserExport.ts
+++ b/apps/mobile/src/session/fileBrowserExport.ts
@@ -1,6 +1,6 @@
/**
* 浏览页与预览页共用文件读取接口,转换为分享/下载地址。
- * 按账号、设备、path 和 mtime 缓存到地址过期;传输选择与瞬断重试由文件接口负责。
+ * 完整文件由共用读取层优先返回本地缓存、后台复验;流式地址保留独立有效期。
*/
import { i18n } from "@/i18n";
import type { MobileMakerTransport } from "@/device-link/mobileMakerTransport";
@@ -9,7 +9,7 @@ import {
storeCachedExportUrl,
} from "@/session/fileBrowserCache";
import type { MobileRemoteMediaPresignResult } from "@/session/remoteMedia";
-import { peerMediaUri, peerMediaExpiry } from "@/device-link/peerFileRegistry";
+import { peerMediaUri, releasePeerMedia } from "@/device-link/peerFileRegistry";
import { errorText } from "@/debug/fileDiagnostics";
import { mobileDebugLog } from "@/debug/mobileDebugLog";
@@ -20,6 +20,7 @@ export interface ExportRemoteFileDeps {
deviceId: string;
openLink: (deviceId: string) => Promise<unknown>;
presignGet: (ossKey: string) => Promise<MobileRemoteMediaPresignResult>;
+ deleteOssObject?: (key: string) => void;
/** 取消信号(如页面卸载),转成文件读取接口的 AbortSignal。 */
isCancelled?: () => boolean;
/** 电脑上传到云存储期间的真实字节进度(缓存命中与直连不回调)。 */
@@ -34,7 +35,7 @@ export async function exportRemoteFileToUrl(
): Promise<string> {
const ownerScope = deps.maker.fileBrowser.cacheScope ?? deps.deviceId;
const scope = JSON.stringify([ownerScope, deps.stream === true ? "stream" : "file"]);
- const cached = getCachedExportUrl(scope, workdir, relPath, mtimeMs);
+ const cached = deps.stream === true ? getCachedExportUrl(scope, workdir, relPath, mtimeMs) : null;
if (cached) {
mobileDebugLog("debug", "files", "file export cache hit", { stream: deps.stream === true });
return cached;
@@ -52,22 +53,22 @@ export async function exportRemoteFileToUrl(
relPath,
abort.signal,
() => deps.openLink(deps.deviceId),
- { stream: deps.stream === true, onProgress: deps.onProgress },
+ { stream: deps.stream === true, onProgress: deps.onProgress,
+ retainBackground: async (fresh, isCurrent) => {
+ if (!fresh.ossKey || isCurrent?.() === false) return;
+ try {
+ const signed = await deps.presignGet(fresh.ossKey);
+ const local = await fresh.cacheDownload?.(signed.getUrl);
+ const uri = local && peerMediaUri(local);
+ if (uri) releasePeerMedia(uri);
+ } finally { if (isCurrent?.() !== false) deps.deleteOssObject?.(fresh.ossKey); }
+ },
+ },
);
check();
if (abort.signal.aborted) throw new Error(i18n.t("files.export.leftPage"));
const local = peerMediaUri(result);
- if (local) {
- storeCachedExportUrl(
- scope,
- workdir,
- relPath,
- mtimeMs,
- local,
- peerMediaExpiry(result)!,
- );
- return local;
- }
+ if (local) return local;
if (result.inlineBase64 !== undefined)
return `data:${result.mimeType};base64,${result.inlineBase64}`;
const presignStartedAt = Date.now();
@@ -78,13 +79,16 @@ export async function exportRemoteFileToUrl(
});
throw error;
});
+ const downloaded = await result.cacheDownload?.(signed.getUrl);
+ const downloadedUri = downloaded && peerMediaUri(downloaded);
+ if (downloadedUri) return downloadedUri;
mobileDebugLog("debug", "files", "file export presigned", {
ms: Date.now() - presignStartedAt,
size: result.size,
});
check();
if (abort.signal.aborted) throw new Error(i18n.t("files.export.leftPage"));
- storeCachedExportUrl(
+ if (deps.stream === true) storeCachedExportUrl(
scope,
workdir,
relPath,
diff --git a/apps/mobile/src/session/pdfPreviewSource.ts b/apps/mobile/src/session/pdfPreviewSource.ts
index 40f7b0c9c9..a362b4e744 100644
--- a/apps/mobile/src/session/pdfPreviewSource.ts
+++ b/apps/mobile/src/session/pdfPreviewSource.ts
@@ -1,16 +1,8 @@
-import { File } from 'expo-file-system';
-import { downloadRemoteMediaShareTemp } from '@/session/remoteMediaDiskCacheExpo';
+import { retainRemoteFilePreview } from '@/session/remoteMediaDiskCacheExpo';
/** WKWebView cannot load a data URI through its native file-URL loader. */
export async function preparePdfPreviewSource(url: string): Promise<{ uri: string; release(): void }> {
- if (/^(https?:\/\/|file:\/\/)/i.test(url)) return { uri: url, release() {} };
- if (!url.startsWith('data:application/pdf;base64,')) throw new Error('INVALID_PDF_URL');
- const uri = await downloadRemoteMediaShareTemp(url, 'application/pdf', 'preview.pdf');
- if (!uri) throw new Error('PDF_CACHE_FAILED');
- return {
- uri,
- release() {
- try { const file = new File(uri); if (file.exists) file.delete(); } catch { /* OS cache reclamation is the fallback. */ }
- },
- };
+ if (!/^(https?:\/\/|file:\/\/)/i.test(url) && !url.startsWith('data:application/pdf;base64,'))
+ throw new Error('INVALID_PDF_URL');
+ return retainRemoteFilePreview(url, 'application/pdf', 'preview.pdf');
}
diff --git a/apps/mobile/src/session/remoteAbsFileFetch.ts b/apps/mobile/src/session/remoteAbsFileFetch.ts
index 865f9f2149..b1c504e3b0 100644
--- a/apps/mobile/src/session/remoteAbsFileFetch.ts
+++ b/apps/mobile/src/session/remoteAbsFileFetch.ts
@@ -9,7 +9,8 @@
* ——media:fetch 故意不限 workdir,靠 device-link 的三道 gate(被控开关 /
* 撤销黑名单 / channel 白名单)保证「等同本地访问」的信任级。
*
- * 缓存策略(bot review 实捉后收紧):`xdt-file://` 不进被控端 mtime/size 感知
+ * 完整文件进入共用读取层,优先使用持久字节缓存、后台复验,不复用下述临时 URL。
+ * 流式地址缓存策略:`xdt-file://` 不进被控端 mtime/size 感知
* 的上传去重缓存(那只对 `xdt-image://` 生效,见 desktop mediaFetch.ts),手机侧
* 又没有 mtime 来源可验证文件是否被覆写——若按 presign 全期(约 1 小时)缓存,
* 同路径文件被 agent 覆写后会一直吃到旧字节。因此这里只做**短 TTL** 缓存:
@@ -43,6 +44,7 @@ export interface RemoteAbsFileFetchDeps {
deviceId: string;
openLink: (deviceId: string) => Promise<unknown>;
presignGet: (ossKey: string) => Promise<MobileRemoteMediaPresignResult>;
+ deleteOssObject?: (key: string) => void;
/** 取消信号(如页面卸载、导出提示上的「取消」):中止取件,不再重试。 */
isCancelled?: () => boolean;
}
@@ -101,7 +103,7 @@ export async function fetchRemoteAbsFileToUrl(
? `${eff.sessionId}\u0000${eff.remoteHostId}\u0000${eff.workdir}`
: '';
const key = `${deps.deviceId}\u0000${absPath}\u0000${sshKey}\u0000${deps.stream === false ? 'file' : 'stream'}`;
- const cached = lookupCache(key, Date.now());
+ const cached = deps.stream === false ? null : lookupCache(key, Date.now());
if (cached) return cached.url;
// 与 exportRemoteFileToUrl 同一写法:轮询 isCancelled 转成取件的 AbortSignal。
const abort = deps.isCancelled ? new AbortController() : null;
@@ -115,12 +117,13 @@ export async function fetchRemoteAbsFileToUrl(
const timer = abort ? setInterval(check, 100) : null;
try {
const fetchOpts = {
+ beforeFetch: () => deps.openLink(deps.deviceId),
+ ...(deps.deleteOssObject ? { discardBackgroundOssKey: deps.deleteOssObject } : {}),
...(deps.stream === false ? { stream: false } : {}),
...(abort ? { signal: abort.signal } : {}),
};
const resolved = await withTransientRemoteRetry(async () => {
assertActive();
- await deps.openLink(deps.deviceId);
// kind 只影响结果的 previewable 标志(此处不消费),按 image 占位。
return resolveMobileRemoteMedia(
{ kind: 'image', url: remoteFileMediaUrl(absPath, undefined, ssh) },
@@ -128,7 +131,7 @@ export async function fetchRemoteAbsFileToUrl(
Object.keys(fetchOpts).length ? fetchOpts : undefined,
);
});
- rememberFetch(key, resolved, Date.now());
+ if (deps.stream !== false) rememberFetch(key, resolved, Date.now());
assertActive();
return resolved.url;
} finally {
@@ -169,12 +172,12 @@ export async function fetchRemoteAbsFileOnce(
signal?: AbortSignal,
): Promise<MobileResolvedRemoteMedia> {
return withTransientRemoteRetry(async () => {
- await deps.openLink(deps.deviceId);
// kind 只影响结果的 previewable 标志(此处不消费),按 image 占位。
return resolveMobileRemoteMedia(
{ kind: 'image', url: remoteFileMediaUrl(absPath, undefined, ssh, constraints) },
{ fetchRemoteMedia: deps.maker.fetchRemoteMedia, presignGet: deps.presignGet },
- { onOssKey, signal, stream: false },
+ { onOssKey, signal, stream: false, beforeFetch: () => deps.openLink(deps.deviceId),
+ discardBackgroundOssKey: deps.deleteOssObject },
);
});
}
diff --git a/apps/mobile/src/session/remoteMedia.ts b/apps/mobile/src/session/remoteMedia.ts
index 85414bada1..eac26f5713 100644
--- a/apps/mobile/src/session/remoteMedia.ts
+++ b/apps/mobile/src/session/remoteMedia.ts
@@ -1,4 +1,4 @@
-import { peerMediaUri, peerMediaExpiry } from "@/device-link/peerFileRegistry";
+import { peerMediaUri, peerMediaExpiry, releasePeerMedia } from "@/device-link/peerFileRegistry";
import type { NormalizedToolMedia } from "@/session/messageNormalize";
import {
isPayloadDesktopLocalMediaUrl,
@@ -22,6 +22,9 @@ export function mediaLoadFailureKey(error: unknown): 'message.lightbox.sourceMis
}
export interface MobileRemoteMediaFetchResult {
+ version?: string;
+ /** Local adapter only; never sent over device-link. Copies an OSS result into the shared file cache. */
+ cacheDownload?: (downloadUrl: string) => Promise<MobileRemoteMediaFetchResult | null>;
/** inline 缩略图回包(新被控端)时为空串。 */
ossKey: string;
mimeType: string;
@@ -48,6 +51,9 @@ export interface MobileResolvedRemoteMedia {
}
export interface MobileRemoteMediaFetchOptions {
+ /** Local callbacks: only connect on a cache miss or during background revalidation. */
+ beforeFetch?: () => Promise<unknown>;
+ retainBackground?: (result: MobileRemoteMediaFetchResult, isCurrent?: () => boolean) => Promise<void>;
/** Local read intent only; false for consumers that copy complete bytes. */
stream?: boolean;
skipCache?: boolean;
@@ -66,6 +72,8 @@ export interface MobileRemoteMediaResolverDeps {
}
export interface MobileRemoteMediaResolveOptions {
+ beforeFetch?: () => Promise<unknown>;
+ discardBackgroundOssKey?: (key: string) => void;
stream?: boolean;
signal?: AbortSignal;
/** 强制被控端绕过上传去重缓存(上次的 ossKey 已悬空时的自愈路径)。 */
@@ -180,6 +188,16 @@ export async function resolveMobileRemoteMedia(
throw new Error(i18n.t("composer.attachments.notFetchableMedia"));
}
const fetchOpts = {
+ ...(opts?.beforeFetch ? { beforeFetch: opts.beforeFetch } : {}),
+ ...(opts?.stream === false ? { retainBackground: async (result: MobileRemoteMediaFetchResult, isCurrent?: () => boolean) => {
+ if (!result.ossKey || isCurrent?.() === false) return;
+ try {
+ const signed = await deps.presignGet(result.ossKey);
+ const copy = await result.cacheDownload?.(signed.getUrl);
+ const uri = copy && peerMediaUri(copy);
+ if (uri) releasePeerMedia(uri);
+ } finally { if (isCurrent?.() !== false) opts.discardBackgroundOssKey?.(result.ossKey); }
+ } } : {}),
...(opts?.stream !== undefined ? { stream: opts.stream } : {}),
...(opts?.onOssKey ? { onDiscardOssKey: opts.onOssKey } : {}),
...(opts?.signal ? { signal: opts.signal } : {}),
@@ -238,6 +256,13 @@ export async function resolveMobileRemoteMedia(
mobileDebugLog("warn", "files", "remote media presign invalid", { kind: media.kind });
throw new Error(i18n.t("composer.attachments.mediaUrlInvalid"));
}
+ const downloaded = await fetched.cacheDownload?.(signed.getUrl);
+ const downloadedUri = downloaded && peerMediaUri(downloaded);
+ if (downloadedUri) return {
+ url: downloadedUri, ossKey: fetched.ossKey, mimeType: fetched.mimeType, size: fetched.size,
+ expiresAt: peerMediaExpiry(downloaded!)!,
+ previewable: canPreviewResolvedRemoteMedia(media.kind, fetched.mimeType),
+ };
if (media.kind !== "image")
mobileDebugLog("debug", "files", "remote media presigned", {
kind: media.kind,
diff --git a/apps/mobile/src/session/remoteMediaDiskCache.ts b/apps/mobile/src/session/remoteMediaDiskCache.ts
index f7c3cf03f8..79df86e53e 100644
--- a/apps/mobile/src/session/remoteMediaDiskCache.ts
+++ b/apps/mobile/src/session/remoteMediaDiskCache.ts
@@ -56,6 +56,7 @@ export interface RemoteMediaDiskCacheHit {
uri: string;
mimeType: string;
size: number;
+ version?: string;
}
export interface RemoteMediaDiskCache {
@@ -140,7 +141,7 @@ export function createRemoteMediaDiskCache(
* download / writeFileBase64 落位之后的共同收尾(两条写入路径同一套失败语义):
* - size === null:写入失败(IO 契约保证原子落位、失败不动现有文件)——同名
* 刷新场景下 name 就是现存条目的好文件,不能误删;只清理并非现存条目的半成品;
- * - size <= 0:0 字节文件已落位顶替,文件与同名旧条目一并作废,下次 lookup 重取;
+ * - size === 0:普通图片缓存视为失败;版本已确认的空文件(例如 CSS)正常保留;
* - 成功:mime 变化换扩展名时删除不再被引用的旧文件,登记条目并做配额回收。
* 返回 true 仅当本次确实登记了新写入的字节(见 store 返回值契约)。
*/
@@ -158,7 +159,7 @@ export function createRemoteMediaDiskCache(
}
return false;
}
- if (size <= 0 || !entries) {
+ if (size < 0 || (size === 0 && !version) || !entries) {
await Promise.resolve(io.deleteFile(name)).catch(() => undefined);
if (prev && prev.name === name && entries) {
entries.delete(key);
@@ -230,9 +231,7 @@ export function createRemoteMediaDiskCache(
const entry = entries?.get(key);
if (!entry) return null;
if (version !== undefined && entry.version !== version) {
- await Promise.resolve(io.deleteFile(entry.name)).catch(() => undefined);
- entries?.delete(key);
- await persistIndex().catch(() => undefined);
+ // Keep the last usable copy until its replacement commits successfully.
return null;
}
const exists = await Promise.resolve(io.fileExists(entry.name)).catch(() => false);
@@ -244,7 +243,8 @@ export function createRemoteMediaDiskCache(
}
entry.lastUsedAt = now();
if (options.persistAccess) await persistIndex().catch(() => undefined);
- return { uri: io.fileUri(entry.name), mimeType: entry.mimeType, size: entry.size };
+ return { uri: io.fileUri(entry.name), mimeType: entry.mimeType, size: entry.size,
+ ...(entry.version ? { version: entry.version } : {}) };
},
async store(sourceUrl, downloadUrl, mimeType, expectedSize, version) {
@@ -262,6 +262,10 @@ export function createRemoteMediaDiskCache(
const name = `${key}${version ? `-${version}` : ''}.${extOfMime(mimeType)}`;
const prev = entries?.get(key);
const size = await io.download(downloadUrl, name);
+ if (size !== null && expectedSize !== undefined && size !== expectedSize) {
+ await Promise.resolve(io.deleteFile(name)).catch(() => undefined);
+ return false;
+ }
return commitWrittenFile(key, name, prev, size, mimeType, version);
};
const pending = downloading.get(key);
diff --git a/apps/mobile/src/session/remoteMediaDiskCacheExpo.ts b/apps/mobile/src/session/remoteMediaDiskCacheExpo.ts
index 3a1a071638..bee7eca5fd 100644
--- a/apps/mobile/src/session/remoteMediaDiskCacheExpo.ts
+++ b/apps/mobile/src/session/remoteMediaDiskCacheExpo.ts
@@ -7,6 +7,7 @@
* JS 层引用,不影响 fingerprint(以 mobile:release:check 实测为准)。
*/
import { Directory, File, Paths } from "expo-file-system";
+import { releasePeerMedia } from '@/device-link/peerFileRegistry';
import {
extOfMime,
@@ -79,6 +80,21 @@ async function copyRemoteFile(
return File.downloadFileAsync(url, target, { idempotent: true });
}
+/** A visible preview owns its copy; transport staging and cache eviction cannot expire it. */
+export async function retainRemoteFilePreview(url: string, mimeType: string, fileName: string) {
+ if (!url.startsWith('file://') && !url.startsWith('data:')) return { uri: url, release() {} };
+ let uri: string | null;
+ try { uri = await downloadRemoteMediaShareTemp(url, mimeType, fileName); }
+ finally { if (url.startsWith('file://')) releasePeerMedia(url); }
+ if (!uri) throw new Error('PREVIEW_CACHE_FAILED');
+ return {
+ uri,
+ release() {
+ try { const file = new File(uri); if (file.exists) file.delete(); } catch { /* OS reclaims cache files. */ }
+ },
+ };
+}
+
/**
* 一次性分享临时文件:超出磁盘缓存预算的对象走 store 会被 LRU 立即逐出,
* lookup 拿不到 → 分享失败。这里绕开 LRU 直接下到独立临时目录,只服务本次
@@ -220,7 +236,7 @@ export function createExpoRemoteMediaDiskCacheIO(namespace?: string): RemoteMedi
encoding: FileSystem.EncodingType.Base64,
});
const size = tmp.size ?? 0;
- if (size <= 0) {
+ if (size < 0) {
if (tmp.exists) tmp.delete();
return null;
}
diff --git a/docs/dev-rules/protocol-compatibility.md b/docs/dev-rules/protocol-compatibility.md
index 36ceee229e..91185493f4 100644
--- a/docs/dev-rules/protocol-compatibility.md
+++ b/docs/dev-rules/protocol-compatibility.md
@@ -842,8 +842,9 @@ dev/ino/size/mtime/ctime,连同解析后的路径生成不透明版本。SSH
例外:由 materializer 用远端主机、工作目录、相对路径及远端 size/mtime 生成源版本,
prepare/open 复用该源版本并校验副本大小,不使用带登录代次的本地路径或 LRU 时间。
缓存仍按稳定账号隔离,原有代次取消校验保留;不把版本当作授权凭据。
-新版控制端只有两次版本一致且传输成功才保留私有缓存副本;读取缓存前仍执行
-prepare 授权与版本查询。缺失/非法版本的旧端不启用此缓存,旧控制端忽略新增字段。
+新版控制端只有两次版本一致且传输成功才保留私有缓存副本。同账号文件预览优先显示
+已有本地副本,prepare 授权与版本查询放到后台;共享任务仍先复验权限。
+缺失/非法版本的旧端不启用此缓存,旧控制端忽略新增字段。
缓存按稳定账号、目标设备、完整媒体 URL 隔离(含 SSH 与目录约束),跨重启保留,
不设时间 TTL、16 MiB 单文件门槛或条目数门槛。账号代次用于拒绝迟到结果,不能进入
持久缓存键。Desktop 图片等媒体复用 `cindy-media` 的 `integration-cache` 索引和
@@ -855,10 +856,26 @@ HTML 等普通文件复用 `remote-file-cache` 的 4 GiB 总量上限、LRU 与
Mobile 复用 `remote-media` 磁盘缓存,放入 realm/账号 SHA-256 命名空间;无固定容量
门槛,仅在现有传输空间预留不足时按 LRU 清理(保留 256 MiB,并考虑下载与消费者副本)。
-访问顺序落盘、版本不同删除旧条目;版本进入物理文件名,避免异步复制撞上覆盖写。
+访问顺序落盘,新版本完整保存后再替换旧条目;版本进入物理文件名,避免异步复制撞上覆盖写。
系统清掉目录后,下一次取件自动重建。两端消费者均拿独立副本,清缓存不删正在预览的副本。
强制刷新只跳过旧副本的读取,成功后仍更新缓存,避免下次普通打开又命中损坏副本。
-已有 OSS 和流式媒体缓存维持原生命周期;此缓存只保存已完成的 peer 整文件下载。
+完整文件读取统一复用版本缓存,覆盖 inline 小文件、peer 下载及已经完成的 OSS 回退下载。
+`device-link:media:fetch` 在 `prepareOnly: true` 时接受可选 `metadataOnly: true`:
+仍先授权并从打开的文件句柄取版本,但小文件也只返回 `transferRequired: true` 与元数据。
+两端共用读取策略:小文件先查同一版本缓存,未命中再以原 `prepareOnly` 请求取 inline 字节;
+大文件沿用 peer/OSS 读取。旧 Host 忽略 `metadataOnly`,新控制端接收原 inline/OSS 结果;
+旧控制端不传此字段,新 Host 保持原行为。两段式导出缺版本时,以导出前后主机版本和大小一致
+作为登记条件,变化或无版本的结果不登记为长期有效。缓存失败不阻断正常读取。
+Mobile 的 HTML 资源、文件浏览器原图、PDF、下载/分享使用完整文件路径,先取当前账号、设备、
+完整 URL 对应的本地缓存,再后台检查版本;同源在途后台检查合并。连接恢复也放到缓存读取之后。
+Desktop 完整文件与远程 HTML 预览复用已知元数据和现有磁盘副本,后台检查变化;进程重启后
+尚无元数据索引时先查询版本,字节仍可从已有磁盘缓存复用。后台失败保留旧副本,更新完成后
+后续打开使用新版;不强制重载正在操作的 HTML、图片或 PDF。预览持有自己的副本,关闭时仅释放这份副本,
+不会删除可复用的源缓存。零字节 HTML 配套资源也可按版本缓存。
+音视频播放继续用保留的流式地址,不为了缓存而预先下载整份媒体;完整下载仍按上述规则。
+不可变聊天图片与目录维持已有专用缓存;Mobile 限量文本预览先显示缓存(包括绝对路径),
+后台读取后更新当前文本,失败不遮住已有内容,文本不改为无界整文件下载。
+不增加缓存目录、额度、通道、服务端改动或 Mobile 原生指纹;完整优化需要两端客户端更新。
网络帧仍是旧版可读的 16 KiB,不增加 wire 通道。新版接收运行时仅在本地桥接声明
批量写入时,把已到达帧合为至多 256 KiB 后串行写盘;仍按实际写入块数归还流控额度,
diff --git a/packages/device-link/src/__tests__/fileAccess.test.ts b/packages/device-link/src/__tests__/fileAccess.test.ts
index 886bd532ca..1a7ce9028a 100644
--- a/packages/device-link/src/__tests__/fileAccess.test.ts
+++ b/packages/device-link/src/__tests__/fileAccess.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it, vi } from "vitest";
-import { readDeviceFile } from "../fileAccess";
+import { readDeviceFile, type DeviceFileResult } from "../fileAccess";
const metadata = {
ossKey: "",
@@ -8,6 +8,99 @@ const metadata = {
transferRequired: true,
};
describe("shared file read policy", () => {
+ it('returns cached bytes while the host is pending, and merges background revalidation', async () => {
+ const cached = { ...metadata, version: 'a'.repeat(64), inlineBase64: 'YQ==' };
+ let reply!: (value: DeviceFileResult) => void;
+ const prepare = vi.fn(() => new Promise<DeviceFileResult>(resolve => { reply = resolve; }));
+ const retain = vi.fn(), discard = vi.fn(), peer = vi.fn();
+ const options = { prepare, peer, fallback: vi.fn(), discard,
+ cacheFirst: { key: 'cache-first-pending', read: async () => cached, retain } };
+ expect(await readDeviceFile(options)).toBe(cached);
+ expect(await readDeviceFile(options)).toBe(cached);
+ expect(prepare).toHaveBeenCalledOnce();
+ const fresh = { ...cached, version: 'b'.repeat(64), transferRequired: false, inlineBase64: 'Yg==' };
+ reply(fresh);
+ await vi.waitFor(() => expect(retain).toHaveBeenCalledWith(fresh));
+ expect(discard).toHaveBeenCalledWith(fresh);
+ expect(peer).not.toHaveBeenCalled();
+ });
+ it.each(['unchanged', 'offline'] as const)('keeps cached bytes on %s without transferring them again', async mode => {
+ const cached = { ...metadata, version: 'a'.repeat(64), inlineBase64: 'YQ==' };
+ const prepare = vi.fn(async () => {
+ if (mode === 'offline') throw new Error('offline');
+ return cached;
+ });
+ const peer = vi.fn(), fallback = vi.fn(), retain = vi.fn();
+ expect(await readDeviceFile({ prepare, peer, fallback,
+ cacheFirst: { key: mode, read: async () => cached, retain } })).toBe(cached);
+ await vi.waitFor(() => expect(prepare).toHaveBeenCalledOnce());
+ expect(peer).not.toHaveBeenCalled();
+ expect(fallback).not.toHaveBeenCalled();
+ expect(retain).not.toHaveBeenCalled();
+ });
+ it('disposes a cached consumer copy if its account changes during lookup', async () => {
+ let current = true;
+ const cached = { ...metadata, version: 'a'.repeat(64) };
+ const discard = vi.fn(), prepare = vi.fn();
+ await expect(readDeviceFile({ prepare, peer: vi.fn(), fallback: vi.fn(), discard,
+ isCurrent: () => current, cacheFirst: { key: 'switched', read: async () => { current = false; return cached; } },
+ })).rejects.toThrow('FILE_PEER_CANCELLED');
+ expect(discard).toHaveBeenCalledWith(cached);
+ expect(prepare).not.toHaveBeenCalled();
+ });
+ it.each([true, false])('only versions a completed fallback when its source is unchanged (%s)', async unchanged => {
+ const version = 'a'.repeat(64);
+ const prepared = { ...metadata, version };
+ const result = await readDeviceFile({
+ prepare: async () => prepared,
+ peer: async () => null,
+ fallback: async () => ({ ossKey: 'export/key', size: prepared.size, mimeType: 'application/octet-stream' }),
+ revalidate: async () => ({ ...prepared, version: unchanged ? version : 'b'.repeat(64) }),
+ });
+ expect(result.version).toBe(unchanged ? version : undefined);
+ expect(result.mimeType).toBe(unchanged ? metadata.mimeType : 'application/octet-stream');
+ });
+ it.each(['text/html', 'text/css', 'application/javascript', 'text/plain', 'application/pdf', 'image/png', 'application/zip'])(
+ 'revalidates %s before reusing bytes and replaces changed versions', async (mimeType) => {
+ let version = 'a'.repeat(64);
+ let stored: DeviceFileResult | undefined;
+ const prepare = vi.fn(async () => ({ ...metadata, size: 3, mimeType, version }));
+ const inline = vi.fn(async () => ({ ossKey: '', size: 3, mimeType, version, inlineBase64: 'YWJj' }));
+ const peer = vi.fn(), fallback = vi.fn();
+ const inlineCache = {
+ read: vi.fn(async (meta: DeviceFileResult) => stored?.version === meta.version ? stored! : null),
+ store: vi.fn(async (result: DeviceFileResult) => { stored = result; }),
+ };
+ const options = { prepare, inline, peer, fallback, inlineCache };
+ await readDeviceFile(options);
+ await readDeviceFile(options);
+ expect(prepare).toHaveBeenCalledTimes(2);
+ expect(inline).toHaveBeenCalledOnce();
+ version = 'b'.repeat(64);
+ expect((await readDeviceFile(options)).version).toBe(version);
+ expect(inline).toHaveBeenCalledTimes(2);
+ prepare.mockRejectedValueOnce(new Error('DENIED'));
+ await expect(readDeviceFile(options)).rejects.toThrow('DENIED');
+ expect(inlineCache.read).toHaveBeenCalledTimes(3);
+ expect(peer).not.toHaveBeenCalled();
+ expect(fallback).not.toHaveBeenCalled();
+ },
+ );
+ it('does not deliver a cache hit after cancellation or fail a read when the cache fails', async () => {
+ const abort = new AbortController();
+ const result = { ossKey: '', size: 3, mimeType: 'text/plain', version: 'a'.repeat(64), inlineBase64: 'YWJj' };
+ const inline = vi.fn(async () => result);
+ const options = {
+ prepare: async () => ({ ...result, inlineBase64: undefined, transferRequired: true }),
+ inline, peer: vi.fn(), fallback: vi.fn(), signal: abort.signal,
+ inlineCache: { read: vi.fn(async () => { abort.abort(); return result; }), store: vi.fn() },
+ };
+ await expect(readDeviceFile(options)).rejects.toThrow('FILE_PEER_CANCELLED');
+ expect(inline).not.toHaveBeenCalled();
+ options.inlineCache.read.mockRejectedValueOnce(new Error('disk unavailable'));
+ options.inlineCache.store.mockRejectedValueOnce(new Error('disk full'));
+ expect(await readDeviceFile({ ...options, signal: undefined })).toBe(result);
+ });
it.each(["audio/mpeg", "video/mp4", "image/png", "application/pdf", "application/octet-stream"])("keeps retained %s previews on OSS but full-file reads on peer", async (mimeType) => {
const prepared = { ...metadata, mimeType };
const peer = vi.fn(async () => ({ ...prepared, transferRequired: false }));
diff --git a/packages/device-link/src/fileAccess.ts b/packages/device-link/src/fileAccess.ts
index 96b3626c9b..8b88d64aa8 100644
--- a/packages/device-link/src/fileAccess.ts
+++ b/packages/device-link/src/fileAccess.ts
@@ -1,5 +1,8 @@
+import { validFileVersion } from './fileTransferPolicy';
+
/** Shared file read policy. UI entry points never choose a transport. */
export const FILE_INLINE_MAX_BYTES = 64 * 1024;
+const revalidatingFiles = new Map<string, Promise<void>>();
export interface DeviceFileResult {
ossKey: string;
@@ -21,6 +24,22 @@ export async function readDeviceFile<T extends DeviceFileResult>(options: {
prepare(): Promise<DeviceFileResult>;
peer(metadata: DeviceFileResult): Promise<T | null>;
fallback(): Promise<DeviceFileResult>;
+ /** Metadata-only preparation is opt-in; old hosts may still return bytes. */
+ inline?(): Promise<DeviceFileResult>;
+ /** Recheck the source after two-stage export before retaining a reusable copy. */
+ revalidate?(): Promise<DeviceFileResult>;
+ /** Small files share the platform's versioned disk store with peer downloads. */
+ inlineCache?: {
+ read(metadata: DeviceFileResult): Promise<DeviceFileResult | null>;
+ store(result: DeviceFileResult): Promise<void>;
+ };
+ /** Same-owner local bytes may render before the host responds. Explicit refresh omits this. */
+ cacheFirst?: {
+ key: string;
+ read(): Promise<DeviceFileResult | T | null>;
+ /** Finish retaining a changed fallback before disposing its temporary result. */
+ retain?(result: DeviceFileResult | T): Promise<void>;
+ };
/** Retained preview/playback URL, rather than an immediate complete-file copy. */
stream?: boolean;
/** Adapter returns expiring staging URLs without copying them into consumer-owned storage. */
@@ -42,9 +61,47 @@ export async function readDeviceFile<T extends DeviceFileResult>(options: {
}
};
assertActive();
- const prepared = await options.prepare();
+ if (options.cacheFirst) {
+ const cached = await options.cacheFirst.read().catch(() => null);
+ if (!active()) return discardCancelled(cached ?? { ossKey: '', size: 0, mimeType: '' });
+ if (cached) {
+ const { key, retain } = options.cacheFirst;
+ if (!revalidatingFiles.has(key)) {
+ const refresh = Promise.resolve().then(async () => {
+ assertActive();
+ const metadata = await options.prepare();
+ if (!active()) return discardCancelled(metadata);
+ if (validFileVersion(cached.version) && metadata.version === cached.version && metadata.size === cached.size) {
+ if (metadata.ossKey) await options.discard?.(metadata);
+ return;
+ }
+ const fresh = await readDeviceFile({ ...options, cacheFirst: undefined, prepare: async () => metadata });
+ try { await retain?.(fresh); }
+ finally { await options.discard?.(fresh); }
+ }).catch(() => { /* Background failure must not replace an already usable preview. */ })
+ .finally(() => { if (revalidatingFiles.get(key) === refresh) revalidatingFiles.delete(key); });
+ revalidatingFiles.set(key, refresh);
+ }
+ return cached;
+ }
+ }
+ let prepared = await options.prepare();
if (!active()) return discardCancelled(prepared);
- const mediaStream = options.stream && /^(audio|video)\//i.test(prepared.mimeType);
+ const isMediaStream = (file: DeviceFileResult) => options.stream && /^(audio|video)\//i.test(file.mimeType);
+ if (!isMediaStream(prepared) && validFileVersion(prepared.version) && prepared.size <= FILE_INLINE_MAX_BYTES) {
+ if (prepared.transferRequired === true && options.inline) {
+ const cached = await options.inlineCache?.read(prepared).catch(() => null);
+ if (!active()) return discardCancelled(cached ?? prepared);
+ if (cached) return cached;
+ prepared = await options.inline();
+ if (!active()) return discardCancelled(prepared);
+ }
+ if (typeof prepared.inlineBase64 === 'string') {
+ await options.inlineCache?.store(prepared).catch(() => undefined);
+ if (!active()) return discardCancelled(prepared);
+ }
+ }
+ const mediaStream = isMediaStream(prepared);
// Small audio/video files arrive inline too, but playback still needs a retained
// URL. Reuse the streaming path without re-uploading an old host's OSS result.
const inlineMediaStream = mediaStream && !prepared.ossKey &&
@@ -57,6 +114,14 @@ export async function readDeviceFile<T extends DeviceFileResult>(options: {
if (direct) return direct;
const result = await options.fallback();
if (!active()) return discardCancelled(result);
+ if (!mediaStream && !result.version && validFileVersion(prepared.version) && options.revalidate) {
+ let after: DeviceFileResult;
+ try { after = await options.revalidate(); }
+ catch (error) { await options.discard?.(result); throw error; }
+ if (!active()) return discardCancelled(result);
+ if (after.version === prepared.version && after.size === prepared.size && result.size === prepared.size)
+ return { ...result, version: prepared.version, mimeType: prepared.mimeType };
+ }
return result;
}