@agent-foundry/replay-server 1.0.0 → 1.0.2

package/src/services/BundleManager.ts

@@ -0,0 +1,503 @@
+/**
+ * Bundle Manager
+ *
+ * Manages bundle lifecycle: download, extraction, caching, and cleanup.
+ * Uses LRU eviction to manage cache size.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { createGunzip } from 'zlib';
+import { pipeline } from 'stream/promises';
+import { extract } from 'tar-stream';
+import type { OSSClient } from './OSSClient.js';
+import type { BundleInfo, BundleManagerConfig, CacheStats, DownloadStats } from './types.js';
+
+/**
+ * Error thrown by bundle manager operations
+ */
+export class BundleManagerError extends Error {
+    constructor(
+        message: string,
+        public readonly code: string,
+        public readonly bundleId?: string
+    ) {
+        super(message);
+        this.name = 'BundleManagerError';
+    }
+}
+
+/**
+ * Bundle Manager for downloading, caching, and serving game bundles
+ */
+export class BundleManager {
+    private readonly bundlesDir: string;
+    private readonly maxCacheSize: number;
+    private readonly ossClient: OSSClient;
+
+    private bundles = new Map<string, BundleInfo>();
+    private downloadPromises = new Map<string, Promise<string>>();
+    private bundlesInUse = new Set<string>();
+
+    private downloadStats: DownloadStats = {
+        active: 0,
+        completed: 0,
+        failed: 0,
+    };
+
+    constructor(config: BundleManagerConfig & { ossClient: OSSClient }) {
+        this.bundlesDir = config.bundlesDir;
+        this.maxCacheSize = config.maxCacheSize;
+        this.ossClient = config.ossClient;
+
+        // Ensure bundles directory exists
+        fs.mkdirSync(this.bundlesDir, { recursive: true });
+
+        // Load existing bundles from disk
+        this.loadCachedBundles();
+    }
+
+    /**
+     * Ensure a bundle is available (download if needed)
+     * Returns the path to the bundle directory
+     */
+    async ensureBundle(bundleId: string, bundleUrl?: string): Promise<string> {
+        const bundlePath = path.join(this.bundlesDir, bundleId);
+
+        // Check if already cached
+        if (this.isCached(bundleId)) {
+            // Update last accessed time
+            const info = this.bundles.get(bundleId);
+            if (info) {
+                info.lastAccessedAt = new Date();
+            }
+            return bundlePath;
+        }
+
+        // Check if already downloading
+        if (this.downloadPromises.has(bundleId)) {
+            console.log(`[BundleManager] Waiting for existing download: ${bundleId}`);
+            return this.downloadPromises.get(bundleId)!;
+        }
+
+        // Need to download
+        if (!bundleUrl) {
+            throw new BundleManagerError(
+                `Bundle ${bundleId} not cached and no bundleUrl provided`,
+                'BUNDLE_URL_REQUIRED',
+                bundleId
+            );
+        }
+
+        // Start download
+        const downloadPromise = this.downloadBundle(bundleId, bundleUrl);
+        this.downloadPromises.set(bundleId, downloadPromise);
+
+        try {
+            const result = await downloadPromise;
+            return result;
+        } finally {
+            this.downloadPromises.delete(bundleId);
+        }
+    }
+
+    /**
+     * Check if a bundle is cached and ready
+     */
+    isCached(bundleId: string): boolean {
+        const bundlePath = path.join(this.bundlesDir, bundleId);
+        const indexPath = path.join(bundlePath, 'index.html');
+        return fs.existsSync(bundlePath) && fs.existsSync(indexPath);
+    }
+
+    /**
+     * Mark bundle as in use (prevents eviction during rendering)
+     */
+    markInUse(bundleId: string): void {
+        this.bundlesInUse.add(bundleId);
+    }
+
+    /**
+     * Mark bundle as no longer in use
+     */
+    markNotInUse(bundleId: string): void {
+        this.bundlesInUse.delete(bundleId);
+    }
+
+    /**
+     * Download and extract a bundle
+     */
+    private async downloadBundle(bundleId: string, bundleUrl: string): Promise<string> {
+        const bundlePath = path.join(this.bundlesDir, bundleId);
+        const tempPath = `${bundlePath}.downloading`;
+        const archivePath = `${bundlePath}.tar.gz`;
+
+        // Initialize bundle info
+        this.bundles.set(bundleId, {
+            bundleId,
+            bundleUrl,
+            status: 'downloading',
+            progress: 0,
+        });
+
+        this.downloadStats.active++;
+
+        try {
+            console.log(`[BundleManager] Downloading bundle ${bundleId} from ${bundleUrl}`);
+
+            // Ensure cache has space
+            await this.ensureCacheSpace(100 * 1024 * 1024); // Reserve 100MB
+
+            // Download archive
+            await this.ossClient.downloadFile(bundleUrl, archivePath, (percent) => {
+                const info = this.bundles.get(bundleId);
+                if (info) {
+                    info.progress = percent;
+                }
+            });
+
+            console.log(`[BundleManager] Extracting bundle ${bundleId}...`);
+
+            // Create temp directory for extraction
+            fs.mkdirSync(tempPath, { recursive: true });
+
+            // Extract TAR.GZ
+            await this.extractTarGz(archivePath, tempPath);
+
+            // Clean up archive
+            fs.unlinkSync(archivePath);
+
+            // Move temp to final location
+            if (fs.existsSync(bundlePath)) {
+                fs.rmSync(bundlePath, { recursive: true });
+            }
+            fs.renameSync(tempPath, bundlePath);
+
+            // Verify extraction
+            const indexPath = path.join(bundlePath, 'index.html');
+            if (!fs.existsSync(indexPath)) {
+                throw new BundleManagerError(
+                    `Bundle extraction failed: index.html not found`,
+                    'EXTRACTION_INVALID',
+                    bundleId
+                );
+            }
+
+            // Calculate bundle size
+            const size = this.getDirectorySize(bundlePath);
+
+            // Update bundle info
+            this.bundles.set(bundleId, {
+                bundleId,
+                bundleUrl,
+                status: 'ready',
+                size,
+                cachedAt: new Date(),
+                lastAccessedAt: new Date(),
+            });
+
+            this.downloadStats.active--;
+            this.downloadStats.completed++;
+
+            console.log(`[BundleManager] Bundle ${bundleId} ready (${(size / 1024 / 1024).toFixed(2)} MB)`);
+
+            return bundlePath;
+        } catch (error) {
+            // Cleanup on error
+            for (const p of [tempPath, archivePath, bundlePath]) {
+                if (fs.existsSync(p)) {
+                    try {
+                        fs.rmSync(p, { recursive: true });
+                    } catch {
+                        // Ignore cleanup errors
+                    }
+                }
+            }
+
+            const errorMessage = error instanceof Error ? error.message : String(error);
+
+            this.bundles.set(bundleId, {
+                bundleId,
+                bundleUrl,
+                status: 'error',
+                error: errorMessage,
+            });
+
+            this.downloadStats.active--;
+            this.downloadStats.failed++;
+
+            throw new BundleManagerError(
+                `Failed to download bundle ${bundleId}: ${errorMessage}`,
+                'DOWNLOAD_FAILED',
+                bundleId
+            );
+        }
+    }
+
+    /**
+     * Extract TAR.GZ archive to destination directory
+     */
+    private async extractTarGz(archivePath: string, destPath: string): Promise<void> {
+        return new Promise((resolve, reject) => {
+            const extractStream = extract();
+            const entries: string[] = [];
+
+            extractStream.on('entry', (header, stream, next) => {
+                let filePath = path.join(destPath, header.name);
+
+                // Handle case where archive has a single root directory
+                // (common with GitHub releases: bundle-v1.0.0/index.html)
+                entries.push(header.name);
+
+                if (header.type === 'directory') {
+                    fs.mkdirSync(filePath, { recursive: true });
+                    stream.resume();
+                    next();
+                } else if (header.type === 'file') {
+                    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+                    const writeStream = fs.createWriteStream(filePath);
+                    stream.pipe(writeStream);
+                    stream.on('end', () => {
+                        writeStream.end();
+                        next();
+                    });
+                    stream.on('error', reject);
+                    writeStream.on('error', reject);
+                } else {
+                    // Skip other types (symlinks, etc.)
+                    stream.resume();
+                    next();
+                }
+            });
+
+            extractStream.on('finish', () => {
+                // Check if all files are in a subdirectory
+                // If so, move them up one level
+                const subdirs = fs.readdirSync(destPath);
+                if (subdirs.length === 1) {
+                    const subdir = path.join(destPath, subdirs[0]);
+                    if (fs.statSync(subdir).isDirectory()) {
+                        // Check if index.html is in subdirectory
+                        if (fs.existsSync(path.join(subdir, 'index.html'))) {
+                            // Move all files up
+                            const files = fs.readdirSync(subdir);
+                            for (const file of files) {
+                                fs.renameSync(
+                                    path.join(subdir, file),
+                                    path.join(destPath, file)
+                                );
+                            }
+                            fs.rmdirSync(subdir);
+                        }
+                    }
+                }
+                resolve();
+            });
+
+            extractStream.on('error', reject);
+
+            const gunzip = createGunzip();
+            gunzip.on('error', reject);
+
+            const readStream = fs.createReadStream(archivePath);
+            readStream.on('error', reject);
+
+            readStream.pipe(gunzip).pipe(extractStream);
+        });
+    }
+
+    /**
+     * Ensure cache has enough space by evicting old bundles
+     */
+    private async ensureCacheSpace(requiredBytes: number): Promise<void> {
+        const stats = this.getCacheStats();
+        const availableBytes = this.maxCacheSize - stats.used;
+
+        if (availableBytes >= requiredBytes) {
+            return;
+        }
+
+        const bytesToFree = requiredBytes - availableBytes;
+        let freedBytes = 0;
+
+        // Get bundles sorted by last accessed time (oldest first)
+        const evictionCandidates = Array.from(this.bundles.entries())
+            .filter(([id, info]) => {
+                return (
+                    info.status === 'ready' &&
+                    !this.bundlesInUse.has(id) &&
+                    !this.downloadPromises.has(id)
+                );
+            })
+            .sort(([, a], [, b]) => {
+                const aTime = a.lastAccessedAt?.getTime() || 0;
+                const bTime = b.lastAccessedAt?.getTime() || 0;
+                return aTime - bTime;
+            });
+
+        for (const [bundleId, info] of evictionCandidates) {
+            if (freedBytes >= bytesToFree) {
+                break;
+            }
+
+            console.log(`[BundleManager] Evicting bundle ${bundleId} to free space`);
+            this.removeBundle(bundleId);
+            freedBytes += info.size || 0;
+        }
+
+        if (freedBytes < bytesToFree) {
+            throw new BundleManagerError(
+                `Unable to free enough cache space (needed: ${bytesToFree}, freed: ${freedBytes})`,
+                'CACHE_FULL'
+            );
+        }
+    }
+
+    /**
+     * Load existing bundles from disk
+     */
+    private loadCachedBundles(): void {
+        if (!fs.existsSync(this.bundlesDir)) {
+            return;
+        }
+
+        const entries = fs.readdirSync(this.bundlesDir, { withFileTypes: true });
+
+        for (const entry of entries) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+
+            // Skip temp directories
+            if (entry.name.endsWith('.downloading') || entry.name.endsWith('.tar.gz')) {
+                // Clean up orphaned temp files
+                try {
+                    fs.rmSync(path.join(this.bundlesDir, entry.name), { recursive: true });
+                } catch {
+                    // Ignore
+                }
+                continue;
+            }
+
+            const bundlePath = path.join(this.bundlesDir, entry.name);
+            const indexPath = path.join(bundlePath, 'index.html');
+
+            if (fs.existsSync(indexPath)) {
+                const stats = fs.statSync(bundlePath);
+                const size = this.getDirectorySize(bundlePath);
+
+                this.bundles.set(entry.name, {
+                    bundleId: entry.name,
+                    status: 'ready',
+                    size,
+                    cachedAt: stats.mtime,
+                    lastAccessedAt: stats.mtime,
+                });
+            }
+        }
+
+        console.log(`[BundleManager] Loaded ${this.bundles.size} cached bundles`);
+    }
+
+    /**
+     * Get directory size recursively
+     */
+    private getDirectorySize(dirPath: string): number {
+        let size = 0;
+
+        try {
+            const files = fs.readdirSync(dirPath);
+
+            for (const file of files) {
+                const filePath = path.join(dirPath, file);
+                const stats = fs.statSync(filePath);
+
+                if (stats.isDirectory()) {
+                    size += this.getDirectorySize(filePath);
+                } else {
+                    size += stats.size;
+                }
+            }
+        } catch {
+            // Ignore errors
+        }
+
+        return size;
+    }
+
+    /**
+     * List all bundles
+     */
+    listBundles(): BundleInfo[] {
+        return Array.from(this.bundles.values());
+    }
+
+    /**
+     * Get bundle info
+     */
+    getBundleInfo(bundleId: string): BundleInfo | undefined {
+        return this.bundles.get(bundleId);
+    }
+
+    /**
+     * Remove bundle from cache
+     */
+    removeBundle(bundleId: string): void {
+        const bundlePath = path.join(this.bundlesDir, bundleId);
+
+        if (fs.existsSync(bundlePath)) {
+            try {
+                fs.rmSync(bundlePath, { recursive: true });
+            } catch (error) {
+                console.error(`[BundleManager] Failed to remove bundle ${bundleId}:`, error);
+            }
+        }
+
+        this.bundles.delete(bundleId);
+    }
+
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): CacheStats {
+        let used = 0;
+        let count = 0;
+
+        for (const info of this.bundles.values()) {
+            if (info.status === 'ready' && info.size) {
+                used += info.size;
+                count++;
+            }
+        }
+
+        return {
+            used,
+            max: this.maxCacheSize,
+            usedPercent: Math.round((used / this.maxCacheSize) * 100),
+            bundleCount: count,
+        };
+    }
+
+    /**
+     * Get download statistics
+     */
+    getDownloadStats(): DownloadStats {
+        return { ...this.downloadStats };
+    }
+
+    /**
+     * Get bundles directory path
+     */
+    getBundlesDir(): string {
+        return this.bundlesDir;
+    }
+}
+
+/**
+ * Create a bundle manager instance
+ */
+export function createBundleManager(
+    config: BundleManagerConfig & { ossClient: OSSClient }
+): BundleManager {
+    return new BundleManager(config);
+}