Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

fix(lume): add OCI layer caching to pullOCI (#1233)

ddupont065cc4699345
diff --git a/libs/lume/src/ContainerRegistry/ImageContainerRegistry.swift b/libs/lume/src/ContainerRegistry/ImageContainerRegistry.swift
index 50225f151d..dc2be746c5 100644
--- a/libs/lume/src/ContainerRegistry/ImageContainerRegistry.swift
+++ b/libs/lume/src/ContainerRegistry/ImageContainerRegistry.swift
@@ -881,6 +881,8 @@ class ImageContainerRegistry: ImageRegistry, @unchecked Sendable {
Logger.debug("Pulling OCI-compliant image")
try await pullOCI(
manifest: manifest,
+ manifestId: manifestId,
+ imageName: imageName,
repository: "\(self.organization)/\(imageName)",
token: token,
to: tempVMDir
@@ -4664,6 +4666,8 @@ class ImageContainerRegistry: ImageRegistry, @unchecked Sendable {
/// Pull an OCI-compliant image (kubelet format) into `destination` as a Lume VM directory.
private func pullOCI(
manifest: Manifest,
+ manifestId: String,
+ imageName: String,
repository: String,
token: String,
to destination: URL
@@ -4672,6 +4676,22 @@ class ImageContainerRegistry: ImageRegistry, @unchecked Sendable {
try FileManager.default.createDirectory(
at: destination, withIntermediateDirectories: true)
+ // ── Top-level OCI cache check ─────────────────────────────────────────
+ if cachingEnabled && validateOCICache(manifest: manifest, manifestId: manifestId) {
+ Logger.info("OCI cache hit — copying from cache instead of downloading")
+ try copyFromOCICache(manifest: manifest, manifestId: manifestId, to: destination)
+ Logger.info("OCI cache copy complete")
+ try cleanupOldVersions(currentManifestId: manifestId, image: imageName)
+ try saveImageMetadata(image: imageName, manifestId: manifestId)
+ return
+ }
+
+ // Ensure cache directory exists for this image when caching is enabled
+ if cachingEnabled {
+ let cacheDir = getImageCacheDirectory(manifestId: manifestId)
+ try FileManager.default.createDirectory(at: cacheDir, withIntermediateDirectories: true)
+ }
+
let tempDir = FileManager.default.temporaryDirectory
.appendingPathComponent("lume_oci_\(UUID().uuidString)")
try FileManager.default.createDirectory(at: tempDir, withIntermediateDirectories: true)
@@ -4691,35 +4711,65 @@ class ImageContainerRegistry: ImageRegistry, @unchecked Sendable {
// ── Download config & aux (shared by both paths) ─────────────────────
var configData: Data?
if let configLayer = manifest.config {
- let blobDest = tempDir.appendingPathComponent(
- configLayer.digest.replacingOccurrences(of: ":", with: "_"))
- Logger.info("Downloading config layer (\(configLayer.digest.prefix(19))…)")
- try await downloadLayer(
- repository: repository,
- digest: configLayer.digest,
- mediaType: configLayer.mediaType,
- token: token,
- to: blobDest,
- maxRetries: 5,
- progress: downloadProgress
- )
+ let cachedConfigPath = cachingEnabled
+ ? getCachedLayerPath(manifestId: manifestId, digest: configLayer.digest) : nil
+ let blobDest: URL
+ if let cached = cachedConfigPath,
+ FileManager.default.fileExists(atPath: cached.path)
+ {
+ Logger.info("Config layer found in cache, skipping download (\(configLayer.digest.prefix(19))…)")
+ await downloadProgress.addProgress(Int64(configLayer.size))
+ blobDest = cached
+ } else {
+ blobDest = tempDir.appendingPathComponent(
+ configLayer.digest.replacingOccurrences(of: ":", with: "_"))
+ Logger.info("Downloading config layer (\(configLayer.digest.prefix(19))…)")
+ try await downloadLayer(
+ repository: repository,
+ digest: configLayer.digest,
+ mediaType: configLayer.mediaType,
+ token: token,
+ to: blobDest,
+ maxRetries: 5,
+ progress: downloadProgress
+ )
+ // Save to cache
+ if let cached = cachedConfigPath {
+ try? FileManager.default.copyItem(at: blobDest, to: cached)
+ }
+ }
configData = try Data(contentsOf: blobDest)
}
var nvramBlobPath: URL?
if let nvramLayer = manifest.layers.first(where: { $0.mediaType == OCIMediaType.nvram }) {
- let blobDest = tempDir.appendingPathComponent(
- nvramLayer.digest.replacingOccurrences(of: ":", with: "_"))
- Logger.info("Downloading nvram layer (\(nvramLayer.digest.prefix(19))…)")
- try await downloadLayer(
- repository: repository,
- digest: nvramLayer.digest,
- mediaType: nvramLayer.mediaType,
- token: token,
- to: blobDest,
- maxRetries: 5,
- progress: downloadProgress
- )
+ let cachedNvramPath = cachingEnabled
+ ? getCachedLayerPath(manifestId: manifestId, digest: nvramLayer.digest) : nil
+ let blobDest: URL
+ if let cached = cachedNvramPath,
+ FileManager.default.fileExists(atPath: cached.path)
+ {
+ Logger.info("Nvram layer found in cache, skipping download (\(nvramLayer.digest.prefix(19))…)")
+ await downloadProgress.addProgress(Int64(nvramLayer.size))
+ blobDest = cached
+ } else {
+ blobDest = tempDir.appendingPathComponent(
+ nvramLayer.digest.replacingOccurrences(of: ":", with: "_"))
+ Logger.info("Downloading nvram layer (\(nvramLayer.digest.prefix(19))…)")
+ try await downloadLayer(
+ repository: repository,
+ digest: nvramLayer.digest,
+ mediaType: nvramLayer.mediaType,
+ token: token,
+ to: blobDest,
+ maxRetries: 5,
+ progress: downloadProgress
+ )
+ // Save to cache
+ if let cached = cachedNvramPath {
+ try? FileManager.default.copyItem(at: blobDest, to: cached)
+ }
+ }
nvramBlobPath = blobDest
}
@@ -4839,7 +4889,8 @@ class ImageContainerRegistry: ImageRegistry, @unchecked Sendable {
}
// Download chunks in parallel (4 concurrent)
- try await withThrowingTaskGroup(of: (Int, URL, UInt64).self) { group in
+ // Result tuple: (chunkIndex, blobPath, chunkOffset, isFromCache)
+ try await withThrowingTaskGroup(of: (Int, URL, UInt64, Bool).self) { group in
let maxConcurrent = 4
var enqueued = 0
@@ -4850,7 +4901,8 @@ class ImageContainerRegistry: ImageRegistry, @unchecked Sendable {
Logger.error("Task group unexpectedly empty while throttling downloads")
continue
}
- let (completedIdx, completedPath, completedOffset) = result
+ let (completedIdx, completedPath, completedOffset, completedFromCache) =
+ result
await pullProgress.updateStatus(
id: "chunk-\(completedIdx)", status: .decompressing)
let handle = try FileHandle(forWritingTo: diskDest)
@@ -4858,7 +4910,9 @@ class ImageContainerRegistry: ImageRegistry, @unchecked Sendable {
inputPath: completedPath, outputHandle: handle,
startOffset: completedOffset)
try handle.close()
- try? FileManager.default.removeItem(at: completedPath)
+ if !completedFromCache {
+ try? FileManager.default.removeItem(at: completedPath)
+ }
await pullProgress.markDone(id: "chunk-\(completedIdx)")
}
@@ -4866,26 +4920,54 @@ class ImageContainerRegistry: ImageRegistry, @unchecked Sendable {
UInt64(chunk.annotations?[OCIAnnotation.partOffset] ?? "0") ?? 0
group.addTask {
- let blobDest = tempDir.appendingPathComponent(
- chunk.digest.replacingOccurrences(of: ":", with: "_"))
- await pullProgress.updateStatus(
- id: "chunk-\(idx)", status: .downloading)
- try await self.downloadLayer(
- repository: repository,
- digest: chunk.digest,
- mediaType: chunk.mediaType,
- token: token,
- to: blobDest,
- maxRetries: 5,
- progress: self.downloadProgress
- )
- return (idx, blobDest, chunkOffset)
+ let cachedChunkPath = self.cachingEnabled
+ ? self.getCachedLayerPath(manifestId: manifestId, digest: chunk.digest)
+ : nil
+ let blobDest: URL
+ if let cached = cachedChunkPath,
+ FileManager.default.fileExists(atPath: cached.path)
+ {
+ await pullProgress.updateStatus(
+ id: "chunk-\(idx)", status: .downloading)
+ Logger.info(
+ "Chunk \(idx) found in cache, skipping download (\(chunk.digest.prefix(19))…)"
+ )
+ await self.downloadProgress.addProgress(Int64(chunk.size))
+ // Copy to a unique temp path to avoid sibling .raw race when
+ // multiple pulls decompress the same cached file concurrently.
+ let tmpCopy = tempDir.appendingPathComponent(
+ UUID().uuidString + ".gz")
+ try FileManager.default.copyItem(at: cached, to: tmpCopy)
+ blobDest = tmpCopy
+ return (idx, blobDest, chunkOffset, false)
+ } else {
+ blobDest = tempDir.appendingPathComponent(
+ chunk.digest.replacingOccurrences(of: ":", with: "_"))
+ await pullProgress.updateStatus(
+ id: "chunk-\(idx)", status: .downloading)
+ try await self.downloadLayer(
+ repository: repository,
+ digest: chunk.digest,
+ mediaType: chunk.mediaType,
+ token: token,
+ to: blobDest,
+ maxRetries: 5,
+ progress: self.downloadProgress
+ )
+ // Save chunk to cache
+ if let cached = cachedChunkPath {
+ try? FileManager.default.copyItem(at: blobDest, to: cached)
+ }
+ return (idx, blobDest, chunkOffset, false)
+ }
}
enqueued += 1
}
// Drain remaining
- for try await (completedIdx, completedPath, completedOffset) in group {
+ for try await (completedIdx, completedPath, completedOffset, completedFromCache)
+ in group
+ {
await pullProgress.updateStatus(
id: "chunk-\(completedIdx)", status: .decompressing)
let handle = try FileHandle(forWritingTo: diskDest)
@@ -4893,7 +4975,9 @@ class ImageContainerRegistry: ImageRegistry, @unchecked Sendable {
inputPath: completedPath, outputHandle: handle,
startOffset: completedOffset)
try handle.close()
- try? FileManager.default.removeItem(at: completedPath)
+ if !completedFromCache {
+ try? FileManager.default.removeItem(at: completedPath)
+ }
await pullProgress.markDone(id: "chunk-\(completedIdx)")
}
}
@@ -4903,18 +4987,40 @@ class ImageContainerRegistry: ImageRegistry, @unchecked Sendable {
} else if let singleDiskLayer = diskLayers.first {
// ── Single-blob fallback (backward compat) ───────────────────────
- let blobDest = tempDir.appendingPathComponent(
- singleDiskLayer.digest.replacingOccurrences(of: ":", with: "_"))
- Logger.info("Downloading single disk layer (\(singleDiskLayer.digest.prefix(19))…)")
- try await downloadLayer(
- repository: repository,
- digest: singleDiskLayer.digest,
- mediaType: singleDiskLayer.mediaType,
- token: token,
- to: blobDest,
- maxRetries: 5,
- progress: downloadProgress
- )
+ let cachedDiskPath = cachingEnabled
+ ? getCachedLayerPath(manifestId: manifestId, digest: singleDiskLayer.digest) : nil
+ let blobDest: URL
+ if let cached = cachedDiskPath,
+ FileManager.default.fileExists(atPath: cached.path)
+ {
+ Logger.info(
+ "Single disk layer found in cache, skipping download (\(singleDiskLayer.digest.prefix(19))…)"
+ )
+ await downloadProgress.addProgress(Int64(singleDiskLayer.size))
+ // Copy to a unique temp path to avoid sibling .raw race when
+ // multiple pulls decompress the same cached file concurrently.
+ let tmpCopy = tempDir.appendingPathComponent(UUID().uuidString + ".gz")
+ try FileManager.default.copyItem(at: cached, to: tmpCopy)
+ blobDest = tmpCopy
+ } else {
+ blobDest = tempDir.appendingPathComponent(
+ singleDiskLayer.digest.replacingOccurrences(of: ":", with: "_"))
+ Logger.info(
+ "Downloading single disk layer (\(singleDiskLayer.digest.prefix(19))…)")
+ try await downloadLayer(
+ repository: repository,
+ digest: singleDiskLayer.digest,
+ mediaType: singleDiskLayer.mediaType,
+ token: token,
+ to: blobDest,
+ maxRetries: 5,
+ progress: downloadProgress
+ )
+ // Save to cache
+ if let cached = cachedDiskPath {
+ try? FileManager.default.copyItem(at: blobDest, to: cached)
+ }
+ }
let uncompSizeStr = singleDiskLayer.annotations?["org.trycua.lume.content.uncompressed-size"]
if let sizeStr = uncompSizeStr, let uncompSize = UInt64(sizeStr), uncompSize > 0 {
@@ -4932,8 +5038,183 @@ class ImageContainerRegistry: ImageRegistry, @unchecked Sendable {
}
}
+ // Register this OCI image in metadata so getImages() can discover it and
+ // cleanupOldVersions can remove superseded manifests.
+ if cachingEnabled {
+ try cleanupOldVersions(currentManifestId: manifestId, image: imageName)
+ try saveImageMetadata(image: imageName, manifestId: manifestId)
+ }
+
Logger.info("OCI pull complete")
}
+
+ /// Returns true when every OCI layer for this manifest is already in the local cache.
+ /// When this returns true, `copyFromOCICache` can reconstruct the VM directory without
+ /// any network activity.
+ private func validateOCICache(manifest: Manifest, manifestId: String) -> Bool {
+ guard cachingEnabled else { return false }
+
+ // Check config layer
+ if let configLayer = manifest.config {
+ let cached = getCachedLayerPath(manifestId: manifestId, digest: configLayer.digest)
+ guard FileManager.default.fileExists(atPath: cached.path) else { return false }
+ }
+
+ // Check all disk / nvram layers
+ for layer in manifest.layers {
+ guard layer.mediaType != "application/vnd.oci.empty.v1+json" else { continue }
+ let cached = getCachedLayerPath(manifestId: manifestId, digest: layer.digest)
+ guard FileManager.default.fileExists(atPath: cached.path) else {
+ Logger.debug("OCI cache miss for layer \(layer.digest.prefix(19))…")
+ return false
+ }
+ }
+
+ Logger.debug("OCI cache fully valid for manifestId: \(manifestId)")
+ return true
+ }
+
+ /// Copies all OCI layers from the local cache into `destination`, producing the same
+ /// VM directory layout that `pullOCI` would create via network download.
+ private func copyFromOCICache(manifest: Manifest, manifestId: String, to destination: URL)
+ throws
+ {
+ Logger.info("Copying OCI image from layer cache")
+
+ // ── Config ────────────────────────────────────────────────────────────
+ if let configLayer = manifest.config {
+ let cached = getCachedLayerPath(manifestId: manifestId, digest: configLayer.digest)
+ let configData = try Data(contentsOf: cached)
+ if let ociCfg = try? JSONDecoder().decode(LumeOCIConfig.self, from: configData) {
+ let hardwareModel = Data(base64Encoded: ociCfg.hardwareModel)
+ let machineIdentifier = Data(base64Encoded: ociCfg.machineIdentifier)
+ let ann = manifest.annotations
+ let cpuCount = ann?["org.trycua.lume.cpu-count"].flatMap(Int.init)
+ let memorySize = ann?["org.trycua.lume.memory-size"].flatMap(UInt64.init)
+ let display = ann?["org.trycua.lume.display"] ?? "1920x1080"
+ let netModeStr = ann?["org.trycua.lume.network-mode"] ?? "nat"
+
+ let diskLayers = manifest.layers.filter { $0.mediaType == OCIMediaType.disk }
+ var diskUncompressedSize: UInt64?
+ if let totalSizeStr = ann?["org.trycua.lume.total-uncompressed-size"],
+ let totalSize = UInt64(totalSizeStr)
+ {
+ diskUncompressedSize = totalSize
+ } else {
+ diskUncompressedSize = diskLayers.compactMap {
+ $0.annotations?["org.trycua.lume.content.uncompressed-size"].flatMap(
+ UInt64.init)
+ }.reduce(0, +)
+ }
+ let diskSize =
+ ann?["org.trycua.lume.disk-size"].flatMap(UInt64.init) ?? diskUncompressedSize
+
+ if let vmConfig = try? VMConfig(
+ os: ociCfg.os,
+ cpuCount: cpuCount,
+ memorySize: memorySize,
+ diskSize: diskSize,
+ display: display,
+ hardwareModel: hardwareModel,
+ machineIdentifier: machineIdentifier,
+ networkMode: NetworkMode.parse(netModeStr) ?? .nat
+ ) {
+ let encoder = JSONEncoder()
+ encoder.outputFormatting = .prettyPrinted
+ try encoder.encode(vmConfig).write(
+ to: destination.appendingPathComponent("config.json"))
+ Logger.info("Wrote config.json from cache")
+ }
+ }
+ }
+
+ // ── NVRAM ─────────────────────────────────────────────────────────────
+ if let nvramLayer = manifest.layers.first(where: { $0.mediaType == OCIMediaType.nvram }) {
+ let cached = getCachedLayerPath(manifestId: manifestId, digest: nvramLayer.digest)
+ try FileManager.default.copyItem(
+ at: cached, to: destination.appendingPathComponent("nvram.bin"))
+ Logger.info("Copied nvram.bin from cache")
+ }
+
+ // ── Disk ──────────────────────────────────────────────────────────────
+ let diskDest = destination.appendingPathComponent("disk.img")
+ let diskLayers = manifest.layers.filter { $0.mediaType == OCIMediaType.disk }
+ let isChunked =
+ diskLayers.count > 1
+ || (diskLayers.count == 1
+ && diskLayers[0].annotations?[OCIAnnotation.partNumber] != nil)
+
+ if isChunked {
+ let sortedChunks = diskLayers.sorted {
+ let a = Int($0.annotations?[OCIAnnotation.partNumber] ?? "0") ?? 0
+ let b = Int($1.annotations?[OCIAnnotation.partNumber] ?? "0") ?? 0
+ return a < b
+ }
+
+ let ann = manifest.annotations
+ let totalSize: UInt64
+ if let totalSizeStr = ann?["org.trycua.lume.total-uncompressed-size"],
+ let ts = UInt64(totalSizeStr)
+ {
+ totalSize = ts
+ } else {
+ totalSize = sortedChunks.compactMap {
+ $0.annotations?["org.trycua.lume.content.uncompressed-size"].flatMap(
+ UInt64.init)
+ }.reduce(0, +)
+ }
+
+ FileManager.default.createFile(atPath: diskDest.path, contents: nil)
+ let diskHandle = try FileHandle(forWritingTo: diskDest)
+ try diskHandle.truncate(atOffset: totalSize)
+ try diskHandle.close()
+
+ let copyTempDir = FileManager.default.temporaryDirectory
+ .appendingPathComponent("lume_oci_copy_\(UUID().uuidString)")
+ try FileManager.default.createDirectory(
+ at: copyTempDir, withIntermediateDirectories: true)
+ defer { try? FileManager.default.removeItem(at: copyTempDir) }
+ for (idx, chunk) in sortedChunks.enumerated() {
+ let cached = getCachedLayerPath(manifestId: manifestId, digest: chunk.digest)
+ let chunkOffset = UInt64(chunk.annotations?[OCIAnnotation.partOffset] ?? "0") ?? 0
+ Logger.info(
+ "Decompressing cached chunk \(idx + 1)/\(sortedChunks.count) from cache")
+ // Copy to unique temp path to avoid sibling .raw race with concurrent pulls.
+ let tmpCopy = copyTempDir.appendingPathComponent(UUID().uuidString + ".gz")
+ try FileManager.default.copyItem(at: cached, to: tmpCopy)
+ defer { try? FileManager.default.removeItem(at: tmpCopy) }
+ let handle = try FileHandle(forWritingTo: diskDest)
+ let _ = try gunzipChunkAndWriteSparse(
+ inputPath: tmpCopy, outputHandle: handle, startOffset: chunkOffset)
+ try handle.close()
+ }
+ Logger.info("Disk image reassembled from \(sortedChunks.count) cached chunks")
+ } else if let singleDiskLayer = diskLayers.first {
+ let cached = getCachedLayerPath(manifestId: manifestId, digest: singleDiskLayer.digest)
+ let uncompSizeStr = singleDiskLayer.annotations?[
+ "org.trycua.lume.content.uncompressed-size"]
+ if let sizeStr = uncompSizeStr, let uncompSize = UInt64(sizeStr), uncompSize > 0 {
+ FileManager.default.createFile(atPath: diskDest.path, contents: nil)
+ let diskHandle = try FileHandle(forWritingTo: diskDest)
+ try diskHandle.truncate(atOffset: uncompSize)
+ // Copy to unique temp path to avoid sibling .raw race with concurrent pulls.
+ let singleCopyTempDir = FileManager.default.temporaryDirectory
+ .appendingPathComponent("lume_oci_copy_\(UUID().uuidString)")
+ try FileManager.default.createDirectory(
+ at: singleCopyTempDir, withIntermediateDirectories: true)
+ defer { try? FileManager.default.removeItem(at: singleCopyTempDir) }
+ let tmpCopy = singleCopyTempDir.appendingPathComponent(UUID().uuidString + ".gz")
+ try FileManager.default.copyItem(at: cached, to: tmpCopy)
+ let _ = try gunzipChunkAndWriteSparse(
+ inputPath: tmpCopy, outputHandle: diskHandle, startOffset: 0)
+ try diskHandle.close()
+ Logger.info("Disk image decompressed (sparse) from cache")
+ } else {
+ try FileManager.default.copyItem(at: cached, to: diskDest)
+ Logger.info("Saved disk.img (uncompressed) from cache")
+ }
+ }
+ }
}
/// Delegate that tracks upload byte progress via URLSession callbacks.