优化: 收敛缓存加载与代理运行状态

sunimp · sunimp · commit a41e3a1b65fa · 2026-05-12T18:08:52.000+08:00
- 默认缓存目录迁移到系统 Caches 并懒加载缓存索引
- 补充空间不足结构化错误，便于调用方识别处理
- 调整 NIO 代理线程数与运行状态维护逻辑
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,11 @@
 
 ### 改进
 
+- 默认缓存目录调整为系统 Caches 下的 `HTTPMediaCache`，不再使用 Documents 作为媒体缓存目录。
+- 缓存索引改为首次访问时懒加载磁盘缓存，避免初始化阶段同步扫描大缓存目录。
+- 空间不足错误新增结构化 `CacheError.insufficientCacheSpace(requiredLength:maxCacheLength:)`，便于调用方按错误类型处理。
+- 本地代理 NIO EventLoop 默认按处理器数量配置线程数，并收敛代理运行状态维护。
+- 简化预加载完成、取消和失败路径的公共清理逻辑。
 - 缓存空间淘汰策略升级为 LRU：成功写入、读取缓存数据和获取完整缓存文件路径会刷新缓存单元的最近访问时间；缓存状态查询不改变淘汰顺序。
 - 拆分代理路由内部职责，提取请求解析、缓存响应、回源下载、响应校验、HLS playlist 响应和代理响应写入适配，降低 `HTTPRequestRouter` 维护复杂度。
 - 拆分 `URLSessionDownloader` 内部职责，提取 streaming delegate、下载配置、响应校验、重试策略和后台任务协调。
diff --git a/README.md b/README.md
@@ -322,6 +322,10 @@ let maxLength = await HTTPMediaCache.maxCacheLength()
 
 当写入新数据会超过最大缓存空间时，缓存索引会按最近访问时间淘汰未使用中的旧缓存，并跳过正在读取或写入的缓存单元。成功写入、读取缓存数据和获取完整缓存文件路径都会刷新缓存单元的最近访问时间；单纯查询 `cacheItem` 或缓存列表不会改变淘汰顺序。
 
+默认缓存目录为系统 `Caches/HTTPMediaCache`。系统可按平台策略清理该目录，业务侧仍可通过 `deleteCache` 或 `deleteAllCaches` 主动清理缓存。
+
+如果单次写入长度超过最大缓存空间，相关预加载、读取或代理链路会抛出 `CacheError.insufficientCacheSpace(requiredLength:maxCacheLength:)`，调用方可以按需单独处理该错误。
+
 ## 下载配置
 
 可以配置下载超时、透传请求头、额外请求头和可接受的响应类型：
diff --git a/Sources/HTTPMediaCache/API/CacheError.swift b/Sources/HTTPMediaCache/API/CacheError.swift
@@ -19,6 +19,8 @@ public enum CacheError: Error, Equatable {
     case unsupportedContentType(String?)
     /// 网络请求失败。
     case networkFailure(String)
+    /// 请求写入长度超过当前最大缓存空间。
+    case insufficientCacheSpace(requiredLength: Int64, maxCacheLength: Int64)
     /// 缓存文件或索引读写失败。
     case storageFailure(String)
 }
diff --git a/Sources/HTTPMediaCache/API/HTTPMediaCache.swift b/Sources/HTTPMediaCache/API/HTTPMediaCache.swift
@@ -61,6 +61,13 @@ public enum HTTPMediaCache {
         let task = Task<Void, Error> {
             await startGate.wait()
             var didEnterPreloadQueue = false
+            func finishPreload() async {
+                if didEnterPreloadQueue {
+                    await PreloadCoordinator.shared.leave()
+                }
+                await PreloadCoordinator.shared.unregister(id: taskID)
+                progress.finish()
+            }
             do {
                 try await withTaskCancellationHandler {
                     try await PreloadCoordinator.shared.enter(id: taskID)
@@ -78,27 +85,15 @@ public enum HTTPMediaCache {
                     progress: progress
                 )
                 await CacheLogStore.shared.cleanError(for: request.url)
-                if didEnterPreloadQueue {
-                    await PreloadCoordinator.shared.leave()
-                }
+                await finishPreload()
             } catch is CancellationError {
-                if didEnterPreloadQueue {
-                    await PreloadCoordinator.shared.leave()
-                }
-                await PreloadCoordinator.shared.unregister(id: taskID)
-                progress.finish()
+                await finishPreload()
                 throw CancellationError()
             } catch {
-                if didEnterPreloadQueue {
-                    await PreloadCoordinator.shared.leave()
-                }
                 await addError(error, for: request.url)
-                await PreloadCoordinator.shared.unregister(id: taskID)
-                progress.finish()
+                await finishPreload()
                 throw error
             }
-            await PreloadCoordinator.shared.unregister(id: taskID)
-            progress.finish()
         }
         await PreloadCoordinator.shared.register(id: taskID, task: task)
         await startGate.open()
diff --git a/Sources/HTTPMediaCache/Core/CacheRuntime.swift b/Sources/HTTPMediaCache/Core/CacheRuntime.swift
@@ -11,7 +11,7 @@ actor CacheRuntime {
     static let shared = CacheRuntime()
 
     private(set) var server = NIOProxyServer()
-    private(set) var cacheIndex = CacheIndex(rootDirectory: CacheRuntime.defaultRootDirectory)
+    private(set) var cacheIndex = CacheIndex(rootDirectory: CacheRuntime.defaultRootDirectoryURL)
     private(set) var downloader: any CacheDownloading = URLSessionDownloader()
     private var hlsContentHandler: (@Sendable (String) -> String)?
     private var hlsVariantStreamSelectionHandler: HLSVariantStreamSelectionHandler?
@@ -95,9 +95,12 @@ actor CacheRuntime {
         return renditions.first { $0.isDefault } ?? renditions.first
     }
 
-    private func defaultVariantStream(from variants: [HLSVariantStreamItem]) -> HLSVariantStreamItem {
+    private func defaultVariantStream(from variants: [HLSVariantStreamItem]) -> HLSVariantStreamItem? {
+        guard let fallback = fallbackVariantStream(from: variants) else {
+            return nil
+        }
         guard variants.contains(where: { $0.codecs != nil || $0.videoRange != nil || $0.averageBandwidth > 0 }) else {
-            return variants[variants.count / 2]
+            return fallback
         }
 
         return variants.min { lhs, rhs in
@@ -107,7 +110,14 @@ actor CacheRuntime {
                 return left < right
             }
             return effectiveBandwidth(lhs) < effectiveBandwidth(rhs)
-        } ?? variants[variants.count / 2]
+        } ?? fallback
+    }
+
+    private func fallbackVariantStream(from variants: [HLSVariantStreamItem]) -> HLSVariantStreamItem? {
+        guard !variants.isEmpty else {
+            return nil
+        }
+        return variants[variants.count / 2]
     }
 
     private func variantCompatibilityScore(_ variant: HLSVariantStreamItem) -> Int {
@@ -116,19 +126,19 @@ actor CacheRuntime {
         var score = 0
 
         if videoRange == "PQ" || videoRange == "HLG" {
-            score += 100
+            score += VariantCompatibilityScore.hdrPenalty
         }
         if codecs.contains("dvh") || codecs.contains("dvhe") {
-            score += 100
+            score += VariantCompatibilityScore.dolbyVisionPenalty
         }
         if codecs.contains("ec-3") || codecs.contains("ac-3") {
-            score += 20
+            score += VariantCompatibilityScore.surroundAudioPenalty
         }
         if codecs.contains("mp4a") {
-            score -= 10
+            score += VariantCompatibilityScore.commonCodecBonus
         }
         if codecs.contains("avc1") {
-            score -= 10
+            score += VariantCompatibilityScore.commonCodecBonus
         }
 
         return score
@@ -157,10 +167,20 @@ actor CacheRuntime {
         await cacheIndex.setCacheIdentifierProvider(provider)
     }
 
-    private static var defaultRootDirectory: URL {
-        let baseDirectory = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first ??
-            FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask)[0]
-        return baseDirectory
-            .appendingPathComponent("HTTPMediaCache", isDirectory: true)
+    static func defaultRootDirectory(cachesDirectory: URL, documentsDirectory _: URL) -> URL {
+        cachesDirectory.appendingPathComponent("HTTPMediaCache", isDirectory: true)
+    }
+
+    private static var defaultRootDirectoryURL: URL {
+        let cachesDirectory = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask)[0]
+        let documentsDirectory = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first ?? cachesDirectory
+        return defaultRootDirectory(cachesDirectory: cachesDirectory, documentsDirectory: documentsDirectory)
     }
 }
+
+private enum VariantCompatibilityScore {
+    static let hdrPenalty = 100
+    static let dolbyVisionPenalty = 100
+    static let surroundAudioPenalty = 20
+    static let commonCodecBonus = -10
+}
diff --git a/Sources/HTTPMediaCache/Proxy/NIOProxyServer.swift b/Sources/HTTPMediaCache/Proxy/NIOProxyServer.swift
@@ -16,23 +16,39 @@ import NIOHTTP1
 
 /// 基于 SwiftNIO 的本地 HTTP 代理服务。
 public actor NIOProxyServer {
-    private let group = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+    let eventLoopThreadCount: Int
+    private let group: MultiThreadedEventLoopGroup
     private var channel: Channel?
     private var codec: ProxyURLCodec?
-    private var wantsRunning = false
-    private var requestedPort: UInt16 = 0
+    private var state = ServerState.stopped
     private var foregroundObserver: ForegroundRestartObserver?
 
     /// 代理服务是否正在运行。
-    public private(set) var isRunning = false
+    public var isRunning: Bool {
+        if case .running = state {
+            return true
+        }
+        return false
+    }
 
     /// 创建本地代理服务。
-    public init() {}
+    public init() {
+        self.init(eventLoopThreadCount: Self.defaultEventLoopThreadCount)
+    }
+
+    init(eventLoopThreadCount: Int) {
+        let resolvedThreadCount = max(1, eventLoopThreadCount)
+        self.eventLoopThreadCount = resolvedThreadCount
+        group = MultiThreadedEventLoopGroup(numberOfThreads: resolvedThreadCount)
+    }
+
+    deinit {
+        try? group.syncShutdownGracefully()
+    }
 
     /// 启动代理服务。
     public func start(port: UInt16) async throws {
-        wantsRunning = true
-        requestedPort = port
+        state = .starting(requestedPort: port)
         if foregroundObserver == nil {
             foregroundObserver = ForegroundRestartObserver { [weak self] in
                 Task {
@@ -41,6 +57,7 @@ public actor NIOProxyServer {
             }
         }
         guard channel == nil else {
+            state = .running(requestedPort: port)
             return
         }
 
@@ -52,20 +69,26 @@ public actor NIOProxyServer {
                 }
             }
 
-        let bound = try await bootstrap.bind(host: "0.0.0.0", port: Int(port)).get()
-        channel = bound
-        let actualPort = bound.localAddress?.port ?? Int(port)
-        codec = ProxyURLCodec(port: UInt16(actualPort))
-        isRunning = true
+        do {
+            let bound = try await bootstrap.bind(host: "0.0.0.0", port: Int(port)).get()
+            channel = bound
+            let actualPort = bound.localAddress?.port ?? Int(port)
+            codec = ProxyURLCodec(port: UInt16(actualPort))
+            state = .running(requestedPort: port)
+        } catch {
+            channel = nil
+            codec = nil
+            state = .stopped
+            throw error
+        }
     }
 
     /// 停止代理服务。
     public func stop() async {
-        wantsRunning = false
+        state = .stopped
         try? await channel?.close().get()
         channel = nil
         codec = nil
-        isRunning = false
     }
 
     /// 将原始 URL 转成当前代理服务可处理的 URL。
@@ -85,7 +108,7 @@ public actor NIOProxyServer {
     }
 
     private func restartAfterForegroundIfNeeded() async {
-        guard wantsRunning else {
+        guard case let .running(requestedPort) = state else {
             return
         }
 
@@ -96,7 +119,7 @@ public actor NIOProxyServer {
         try? await channel?.close().get()
         channel = nil
         codec = nil
-        isRunning = false
+        state = .stopped
         try? await start(port: requestedPort)
     }
 
@@ -118,6 +141,16 @@ public actor NIOProxyServer {
             return false
         }
     }
+
+    private static var defaultEventLoopThreadCount: Int {
+        max(1, ProcessInfo.processInfo.activeProcessorCount)
+    }
+}
+
+private enum ServerState {
+    case stopped
+    case starting(requestedPort: UInt16)
+    case running(requestedPort: UInt16)
 }
 
 private final class ForegroundRestartObserver: NSObject, @unchecked Sendable {
diff --git a/Sources/HTTPMediaCache/Storage/CacheIndex.swift b/Sources/HTTPMediaCache/Storage/CacheIndex.swift
diff --git a/Tests/HTTPMediaCacheTests/CacheStorageTests.swift b/Tests/HTTPMediaCacheTests/CacheStorageTests.swift
diff --git a/Tests/HTTPMediaCacheTests/NIOProxyServerTests.swift b/Tests/HTTPMediaCacheTests/NIOProxyServerTests.swift

Original file line number	Diff line number	Diff line change
`@@ -19,6 +19,8 @@ public enum CacheError: Error, Equatable {`
`19`	`19`	`case unsupportedContentType(String?)`
`20`	`20`	`/// 网络请求失败。`
`21`	`21`	`case networkFailure(String)`
	`22`	`+ /// 请求写入长度超过当前最大缓存空间。`
	`23`	`+ case insufficientCacheSpace(requiredLength: Int64, maxCacheLength: Int64)`
`22`	`24`	`/// 缓存文件或索引读写失败。`
`23`	`25`	`case storageFailure(String)`
`24`	`26`	`}`