重构: 拆分代理与下载链路职责

- 抽出代理请求解析、响应校验、缓存写入和 HLS 处理组件
- 拆分 URLSession 下载配置、重试、校验和流式代理逻辑
- 调整缓存淘汰为最近访问顺序并补充文档与测试

Author: sunimp

Documentation/architecture.md

@@ -0,0 +1,63 @@
+# HTTPMediaCache 架构维护说明
+
+HTTPMediaCache 是一个 Swift-only 的本地 HTTP 媒体缓存库。核心路径分为代理播放、主动预加载、HLS playlist 改写、区间缓存存储和 URLSession 回源下载。
+
+## 模块边界
+
+- `API`：暴露 `HTTPMediaCache`、`CacheRequest`、`PreloadTask`、配置和查询入口。
+- `Core`：放运行时装配、Range、代理 URL 编解码等基础能力。
+- `Proxy`：承接 NIO HTTP 请求，解析代理 URL，按资源类型分发到缓存响应、回源响应或 HLS playlist 改写。
+- `Pipeline`：负责把请求区间规划为本地缓存段和远端下载段。
+- `Storage`：维护 URL 到缓存单元的索引、元数据、数据文件和缓存空间限制。
+- `Network`：定义下载抽象和默认 `URLSessionDownloader` 实现。
+- `HLS`：解析、选择、改写 playlist，并为 HLS 预加载生成资源计划。
+
+## 代理播放链路
+
+1. `NIOProxyServer` 接收播放器请求并进入 `HTTPRequestRouter`。
+2. `ProxyRequestParser` 解码原始 URL，过滤不能透传的请求头，并规范化 Range。
+3. `ProxyRequestClassifier` 区分 HLS playlist、HLS 子资源和普通媒体文件。
+4. 普通媒体优先通过 `ProxyCacheResponder` 命中完整缓存或请求区间缓存。
+5. 缓存未命中时，router 选择 HEAD、流式回源或拼接式回源路径。
+6. 回源数据通过 `ProxyCacheWriter` 写入缓存，响应长度和 Range 由 `ProxyResponseValidator` 校验。
+7. `HTTPResponseWriter+Proxy` 负责把缓存响应、数据响应和 HEAD 响应转换为 NIO 输出。
+
+`HTTPRequestRouter` 应只保留请求生命周期、路径选择和 NIO 上下文管理；新增代理行为时优先放到 responder、writer、validator 或 parser 中。
+
+## HLS 链路
+
+HLS playlist 请求由 `HLSProxyResponder` 处理。它缓存原始 playlist，再在返回播放器前通过 `HLSPlaylistRewriter` 改写 URI。改写后的 variant、rendition、segment、key 和 init map URI 会重新进入代理链路。
+
+HLS 下载请求头由 `HLSDownloadPolicy` 统一生成。playlist、key 和完整 segment 默认不继承播放器 Range；init map 与 byte-range segment 使用 playlist 中声明的 `BYTERANGE`。
+
+## 预加载链路
+
+`HTTPMediaCache.preload` 创建 `PreloadTask` 并进入 `PreloadCoordinator`。普通文件由 `FilePreloadExecutor` 规划和下载目标 Range；HLS 由 `HLSPreloadExecutor` 读取 playlist，递归选择子 playlist，并按 segment 数、字节数或时长限制预加载依赖资源。
+
+预加载和代理播放共用 `CacheIndex`、`CacheUnit`、下载器、HLS 下载策略和缓存 identity provider，因此行为变更要同时验证代理和预加载测试。
+
+## 缓存与淘汰
+
+`CacheIndex` 管理 URL 到 `CacheUnit` 的映射。`CacheUnit` 负责 `data.bin`、`metadata.json`、已缓存区间和完整文件路径。
+
+当前空间限制策略是 LRU 淘汰：写入前如果空间不足，`CacheIndex.prepareForWrite` 会按缓存单元的最近访问时间删除未使用中的旧缓存，并跳过正在读取或写入的缓存单元。成功写入、读取缓存数据和获取完整缓存文件路径会刷新最近访问时间；单纯查询 `cacheItem` 或缓存列表不会改变淘汰顺序。
+
+## 下载器拆分
+
+默认下载器由多个小组件组成：
+
+- `URLSessionDownloader`：下载入口和编排。
+- `URLSessionStreamingDelegate`：URLSession delegate、响应 continuation、body stream 和取消处理。
+- `URLSessionDownloadValidator`：内容类型、内容长度和 Range 响应校验。
+- `URLSessionDownloadRetryPolicy`：瞬时网络错误重试。
+- `URLSessionDownloaderSettings`：超时、请求头、内容类型和 metrics 配置。
+- `URLSessionDownloaderBackgroundTaskCoordinator`：iOS 后台下载任务生命周期。
+
+新增下载行为时优先扩展对应组件，避免把策略重新堆回 `URLSessionDownloader`。
+
+## 验证建议
+
+- 网络层改动：运行 `swift test --scratch-path /tmp/HTTPMediaCache-swiftpm-scratch --filter URLSessionDownloaderTests`。
+- 代理层改动：运行 `swift test --scratch-path /tmp/HTTPMediaCache-swiftpm-scratch --filter ProxyRangeResponseTests`。
+- HLS 或预加载改动：运行 `swift test --scratch-path /tmp/HTTPMediaCache-swiftpm-scratch --filter PreloadTests` 和 `--filter HLSPlaylistRewriterTests`。
+- 收尾验证：运行完整 `swift test --scratch-path /tmp/HTTPMediaCache-swiftpm-scratch`。

README.md

@@ -75,7 +75,7 @@ await HTTPMediaCache.stop()
 
 ## 项目架构
 
-完整架构图可查看 [Documentation/architecture.html](Documentation/architecture.html)。
+完整架构图可查看 [Documentation/architecture.html](Documentation/architecture.html)，维护说明可查看 [Documentation/architecture.md](Documentation/architecture.md)。
 
 ```mermaid
 flowchart LR
@@ -320,6 +320,8 @@ await HTTPMediaCache.setMaxCacheLength(500 * 1024 * 1024)
 let maxLength = await HTTPMediaCache.maxCacheLength()
 ```
 
+当写入新数据会超过最大缓存空间时，缓存索引会按最近访问时间淘汰未使用中的旧缓存，并跳过正在读取或写入的缓存单元。成功写入、读取缓存数据和获取完整缓存文件路径都会刷新缓存单元的最近访问时间；单纯查询 `cacheItem` 或缓存列表不会改变淘汰顺序。
+
 ## 下载配置
 
 可以配置下载超时、透传请求头、额外请求头和可接受的响应类型：

Sources/HTTPMediaCache/Network/HTTPURLResponse+URLSessionHeaders.swift

@@ -0,0 +1,19 @@
+//
+//  HTTPURLResponse+URLSessionHeaders.swift
+//  HTTPMediaCache
+//
+//  Created by Sun on 2026/5/12.
+//
+
+import Foundation
+
+extension HTTPURLResponse {
+    var urlSessionHeaderDictionary: [String: String] {
+        allHeaderFields.reduce(into: [String: String]()) { result, header in
+            guard let name = header.key as? String else {
+                return
+            }
+            result[name] = "\(header.value)"
+        }
+    }
+}

Sources/HTTPMediaCache/Network/URLSessionDownloadRetryPolicy.swift

@@ -0,0 +1,45 @@
+//
+//  URLSessionDownloadRetryPolicy.swift
+//  HTTPMediaCache
+//
+//  Created by Sun on 2026/5/12.
+//
+
+import Foundation
+
+struct URLSessionDownloadRetryPolicy {
+    func run<T>(_ operation: () async throws -> T) async throws -> T {
+        let maxAttemptCount = 3
+        var lastError: Error?
+
+        for attempt in 1 ... maxAttemptCount {
+            do {
+                return try await operation()
+            } catch {
+                guard attempt < maxAttemptCount, isTransientNetworkError(error) else {
+                    throw error
+                }
+                lastError = error
+                try? await Task.sleep(nanoseconds: UInt64(attempt) * 200_000_000)
+            }
+        }
+
+        throw lastError ?? CacheError.networkFailure("Transient retry failed without an underlying error.")
+    }
+
+    private func isTransientNetworkError(_ error: Error) -> Bool {
+        let nsError = error as NSError
+        guard nsError.domain == NSURLErrorDomain else {
+            return false
+        }
+
+        let retryableCodes = [
+            NSURLErrorSecureConnectionFailed,
+            NSURLErrorNetworkConnectionLost,
+            NSURLErrorTimedOut,
+            NSURLErrorCannotConnectToHost,
+            NSURLErrorDNSLookupFailed,
+        ]
+        return retryableCodes.contains(nsError.code)
+    }
+}

Sources/HTTPMediaCache/Network/URLSessionDownloadValidator.swift

@@ -0,0 +1,47 @@
+//
+//  URLSessionDownloadValidator.swift
+//  HTTPMediaCache
+//
+//  Created by Sun on 2026/5/12.
+//
+
+import Foundation
+
+struct URLSessionDownloadValidator {
+    func validate(response: HTTPURLResponse, cacheRequest: CacheRequest) async throws {
+        let settings = await URLSessionDownloaderSettings.shared.snapshot()
+        guard let contentType = response.value(forHTTPHeaderField: "Content-Type"), !contentType.isEmpty else {
+            throw CacheError.networkFailure("Unacceptable content type for \(cacheRequest.url.absoluteString).")
+        }
+
+        let acceptableContentTypes = settings.acceptableContentTypes ?? []
+        let isAcceptable = acceptableContentTypes.contains {
+            contentType.range(of: $0, options: [.caseInsensitive]) != nil
+        }
+        if !isAcceptable,
+           settings.unacceptableContentTypeDisposer?(cacheRequest.url, contentType) != true
+        {
+            throw CacheError.networkFailure("Unacceptable content type for \(cacheRequest.url.absoluteString).")
+        }
+
+        let headers = response.urlSessionHeaderDictionary
+        let contentLength = headers.contentLength ?? 0
+        guard contentLength > 0 else {
+            throw CacheError.networkFailure("Invalid Content-Length for \(cacheRequest.url.absoluteString).")
+        }
+
+        guard let range = cacheRequest.range,
+              !range.isSuffixRange,
+              let requestedEnd = range.end,
+              let expectedLength = range.length,
+              let totalLength = headers.contentRangeTotalLength ?? headers.contentLength,
+              requestedEnd < totalLength
+        else {
+            return
+        }
+
+        guard contentLength == expectedLength else {
+            throw CacheError.networkFailure("Mismatched Content-Length for \(cacheRequest.url.absoluteString).")
+        }
+    }
+}