Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

14.8 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { PlatformAdapter } from './types';
import { cacheEntryName } from './cacheEntryName';
import { contentHashHex } from '../asset/contentHash';
import { encodeUtf8, decodeUtf8 } from '../util/utf8';

const INDEX_KEY = 'estella:content-cache:index:v1';
const INDEX_NAME = cacheEntryName(INDEX_KEY);
export type CacheProtection = 'current' | 'pending' | 'rollback' | 'retained';
export interface CacheVersion {
    revision: string;
    reason: CacheProtection | null;
    keys: string[];
}
interface Entry {
    name: string;
    key?: string;
    hash?: string;
    size: number;
    lastAccess: number;
}
interface Index {
    schema: 1;
    entries: Entry[];
    owners: Record<string, CacheVersion[]>;
}
export interface ContentCacheEntry extends Entry {
    versions: string[];
    protection: string[];
}
export interface ContentCacheReport {
    /** The Assets service issuing this report, when supplied by that service. */
    owner?: string;
    capability: 'managed' | 'storage-only' | 'unavailable';
    /** Resource bytes only; index bytes are reported separately. Null is unknown. */
    usedBytes: number | null;
    indexBytes: number | null;
    protectedBytes: number | null;
    reclaimableBytes: number | null;
    entries: ContentCacheEntry[];
    versions: { owner: string; revision: string; reason: CacheProtection | null; missing: number; retained: boolean }[];
}
export interface CacheCleanupPreview {
    report: ContentCacheReport;
    budgetBytes: number;
    candidates: string[];
    releaseBytes: number;
    remainingBytes: number | null;
    budgetMet: boolean | null;
}
export interface CacheCleanupResult extends CacheCleanupPreview {
    removed: string[];
    failed: string[];
    /** Cleanup can free a full disk even when updating its index is refused.
     * The next scan reconciles those successful deletions. */
    indexPersisted?: boolean;
}

/** One coordinator per adapter: byte IO, index changes and eviction share a
 * queue. A cleaner cannot unlink a read/write in flight. Unknown legacy files
 * stay protected until a verified write establishes their resource identity. */
export class ContentCache {
    private chain_: Promise<unknown> = Promise.resolve();
    private index_: Index | null = null;
    private indexBytes_ = 0;
    constructor(private readonly platform_: PlatformAdapter) {}

    capability(): ContentCacheReport['capability'] {
        const p = this.platform_;
        if (!p.readCacheFile || !p.writeCacheFile || p.hasCacheStorage?.() === false) return 'unavailable';
        return p.listCacheFiles && p.removeCacheFile && p.canManageCache?.() !== false ? 'managed' : 'storage-only';
    }

    private run_<T>(fn: () => Promise<T>): Promise<T> {
        const result = this.chain_.then(fn);
        this.chain_ = result.catch(() => {});
        return result;
    }

    private async load_(): Promise<Index> {
        if (this.index_) return this.index_;
        const bytes = await this.platform_.readCacheFile!(INDEX_KEY);
        if (bytes) {
            try {
                const parsed = JSON.parse(decodeUtf8(new Uint8Array(bytes))) as Index;
                if (parsed.schema !== 1 || !Array.isArray(parsed.entries) || !parsed.owners
                    || !parsed.entries.every(e => /^[0-9a-f]{16}(?:\.\d+\.tmp)?$/.test(e.name)
                        && Number.isFinite(e.size) && e.size >= 0 && Number.isFinite(e.lastAccess)
                        && (e.key === undefined || (typeof e.key === 'string' && cacheEntryName(e.key) === e.name)))
                    || !Object.values(parsed.owners).every(v => Array.isArray(v) && v.every(x =>
                        typeof x.revision === 'string' && Array.isArray(x.keys) && x.keys.every(k => typeof k === 'string')
                        && [null, 'current', 'pending', 'rollback', 'retained'].includes(x.reason)))) throw Error('invalid index');
                this.index_ = parsed;
                this.indexBytes_ = bytes.byteLength;
                return parsed;
            } catch { /* Crash/corruption: rescan conservatively; never infer ownership. */ }
        }
        return this.index_ = { schema: 1, entries: [], owners: {} };
    }

    private async save_(): Promise<void> {
        const bytes = encodeUtf8(JSON.stringify(this.index_));
        await this.platform_.writeCacheFile!(INDEX_KEY, bytes.buffer as ArrayBuffer);
        this.indexBytes_ = bytes.byteLength;
    }

    async read(key: string): Promise<ArrayBuffer | null> {
        if (this.capability() !== 'managed') return this.platform_.readCacheFile!(key);
        return this.run_(async () => {
            const index = await this.load_();
            const bytes = await this.platform_.readCacheFile!(key);
            const entry = index.entries.find(e => e.name === cacheEntryName(key));
            if (bytes && entry) {
                entry.lastAccess = Date.now();
                // An access-time write failure must not prevent an offline read.
                await this.save_().catch(() => {});
            }
            return bytes;
        });
    }

    async write(key: string, bytes: ArrayBuffer): Promise<void> {
        if (this.capability() !== 'managed') return this.platform_.writeCacheFile!(key, bytes);
        return this.run_(async () => {
            const index = await this.load_();
            await this.platform_.writeCacheFile!(key, bytes);
            const entry: Entry = { name: cacheEntryName(key), key, hash: contentHashHex(new Uint8Array(bytes)),
                size: bytes.byteLength, lastAccess: Date.now() };
            index.entries = index.entries.filter(e => e.name !== entry.name);
            index.entries.push(entry);
            await this.save_();
        });
    }

    /** Replaces this application's protected versions, preserving historical
     * ownership and other applications sharing the directory. Persists before
     * an updater starts downloading or switches its active manifest. */
    async protect(owner: string, versions: CacheVersion[]): Promise<void> {
        if (this.capability() !== 'managed') return;
        const merged = new Map<string, CacheVersion>();
        const ranks = [null, 'retained', 'rollback', 'pending', 'current'];
        for (const version of versions) {
            const prev = merged.get(version.revision);
            merged.set(version.revision, { revision: version.revision,
                reason: prev && ranks.indexOf(prev.reason) > ranks.indexOf(version.reason) ? prev.reason : version.reason,
                keys: [...new Set([...(prev?.keys ?? []), ...version.keys])] });
        }
        const snapshot = [...merged.values()];
        return this.run_(async () => {
            const index = await this.load_();
            const previous = index.owners[owner] ?? [];
            index.owners[owner] = [...previous.filter(v => !snapshot.some(n => n.revision === v.revision))
                .map(v => ({ ...v, reason: null })), ...snapshot];
            await this.save_();
        });
    }

    private async scan_(repair = false): Promise<void> {
        const index = await this.load_();
        const files = await this.platform_.listCacheFiles!();
        const known = new Map(index.entries.map(e => [e.name, e]));
        index.entries = files.filter(f => f.name !== INDEX_NAME).map(f => ({ ...known.get(f.name), ...f,
            lastAccess: Math.max(known.get(f.name)?.lastAccess ?? 0, f.lastAccess) }));
        this.indexBytes_ = files.find(f => f.name === INDEX_NAME)?.size ?? 0;
        if (repair) {
            // A surviving manifest gives an old file a resource identity even
            // when its index was lost. Infer only exact URL-name matches; saves,
            // orphan files and interrupted temporaries remain unindexed/pinned.
            const referenced = new Map<string, string>();
            for (const versions of Object.values(index.owners)) for (const version of versions)
                for (const key of version.keys) referenced.set(cacheEntryName(key), key);
            for (const entry of index.entries) {
                const key = referenced.get(entry.name);
                if (entry.key || !key) continue;
                const bytes = await this.platform_.readCacheFile!(key).catch(() => null);
                if (!bytes) continue;
                entry.key = key;
                entry.hash = contentHashHex(new Uint8Array(bytes));
                entry.size = bytes.byteLength;
            }
        }
    }

    /** Explicit retention lives under its own owner, so advancing the automatic
     * current/rollback pair cannot silently release a developer's retained build. */
    async retainVersion(owner: string, revision: string, retain = true): Promise<void> {
        if (this.capability() !== 'managed') throw Error('cache management unavailable');
        return this.run_(async () => {
            const index = await this.load_();
            const retainedOwner = `retained:${owner}`;
            const retained = index.owners[retainedOwner] ?? [];
            const version = index.owners[owner]?.find(v => v.revision === revision);
            if (!version) throw Error('unknown cache version');
            index.owners[retainedOwner] = retained.filter(v => v.revision !== revision);
            if (retain) index.owners[retainedOwner].push({ ...version, keys: [...version.keys], reason: 'retained' });
            await this.save_();
        });
    }

    private report_(): ContentCacheReport {
        const capability = this.capability();
        if (capability !== 'managed') return { capability, usedBytes: null, indexBytes: null,
            protectedBytes: null, reclaimableBytes: null, entries: [], versions: [] };
        const index = this.index_!;
        // Invert version references once. Looking up every URL for every file
        // makes a modest cache report block the editor for seconds (E × R).
        const names = new Set(index.entries.map(e => e.name));
        const ownership = new Map<string, { versions: Set<string>; protection: Set<string> }>();
        const versionReports: ContentCacheReport['versions'] = [];
        for (const [owner, refs] of Object.entries(index.owners)) {
            const retainedVersions = new Set(index.owners[`retained:${owner}`]?.map(v => v.revision) ?? []);
            for (const version of refs) {
                let missing = 0;
                for (const key of version.keys) {
                    const name = cacheEntryName(key);
                    if (!names.has(name)) missing++;
                    let refsForFile = ownership.get(name);
                    if (!refsForFile) {
                        refsForFile = { versions: new Set(), protection: new Set() };
                        ownership.set(name, refsForFile);
                    }
                    refsForFile.versions.add(version.revision);
                    if (version.reason) refsForFile.protection.add(`${owner}:${version.reason}`);
                }
                if (!owner.startsWith('retained:')) {
                    const retained = retainedVersions.has(version.revision);
                    versionReports.push({ owner, revision: version.revision,
                        reason: version.reason ?? (retained ? 'retained' : null), retained, missing });
                }
            }
        }
        const entries = index.entries.map(e => {
            const refs = ownership.get(e.name);
            return { ...e, versions: [...(refs?.versions ?? [])],
                protection: [...(e.key ? [] : ['unindexed']), ...(refs?.protection ?? [])] };
        });
        const usedBytes = entries.reduce((n, e) => n + e.size, 0);
        const protectedBytes = entries.reduce((n, e) => n + (e.protection.length ? e.size : 0), 0);
        return { capability, usedBytes, indexBytes: this.indexBytes_, protectedBytes,
            reclaimableBytes: usedBytes - protectedBytes, entries,
            versions: versionReports };
    }

    async report(rescan = false): Promise<ContentCacheReport> {
        if (this.capability() !== 'managed') return this.report_();
        return this.run_(async () => {
            await this.scan_(rescan);
            if (rescan) await this.save_();
            return this.report_();
        });
    }

    private preview_(budgetBytes: number): CacheCleanupPreview {
        const report = this.report_();
        let remainingBytes = report.usedBytes;
        const candidates: string[] = [];
        let releaseBytes = 0;
        if (remainingBytes !== null) for (const e of [...report.entries]
            .filter(e => e.protection.length === 0).sort((a, b) => a.lastAccess - b.lastAccess || a.name.localeCompare(b.name))) {
            if (remainingBytes <= budgetBytes) break;
            candidates.push(e.name);
            releaseBytes += e.size;
            remainingBytes -= e.size;
        }
        return { report, budgetBytes, candidates, releaseBytes, remainingBytes,
            budgetMet: remainingBytes === null ? null : remainingBytes <= budgetBytes };
    }

    /** Re-evaluates protection at execution; never trusts a stale UI preview.
     * Serial deletion yields every batch and reports only successful unlinks. */
    async cleanup(budgetBytes: number, execute = false): Promise<CacheCleanupResult> {
        if (!Number.isSafeInteger(budgetBytes) || budgetBytes < 0) throw Error('cache budget must be a non-negative safe integer');
        return this.run_(async () => {
            if (this.capability() === 'managed') await this.scan_();
            const preview = this.preview_(budgetBytes);
            const removed: string[] = [], failed: string[] = [];
            if (!execute || preview.report.capability !== 'managed') return { ...preview, removed, failed };
            let released = 0;
            for (const name of preview.candidates) {
                try {
                    await this.platform_.removeCacheFile!(name);
                    released += this.index_!.entries.find(e => e.name === name)!.size;
                    this.index_!.entries = this.index_!.entries.filter(e => e.name !== name);
                    removed.push(name);
                } catch { failed.push(name); }
                if ((removed.length + failed.length) % 16 === 0) await new Promise(r => setTimeout(r, 0));
            }
            // If interrupted, a later scan reconciles the on-disk truth.
            const indexPersisted = await this.save_().then(() => true, () => false);
            const report = this.report_();
            return { ...preview, report, releaseBytes: released, remainingBytes: report.usedBytes,
                budgetMet: report.usedBytes! <= budgetBytes, removed, failed, indexPersisted };
        });
    }
}

const caches = new WeakMap<PlatformAdapter, ContentCache>();
export function contentCacheFor(platform: PlatformAdapter): ContentCache {
    let cache = caches.get(platform);
    if (!cache) { cache = new ContentCache(platform); caches.set(platform, cache); }
    return cache;
}