Skip to content

Commit 0e3971f

Browse files
sunimpsunimp
committed
初始发布 HTTPMediaCache
0 parents  commit 0e3971f

78 files changed

Lines changed: 16432 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: Bug 反馈
2+
description: 报告可复现的问题
3+
title: "[Bug]: "
4+
labels: ["bug"]
5+
body:
6+
- type: textarea
7+
id: description
8+
attributes:
9+
label: 问题描述
10+
description: 请说明实际行为和预期行为。
11+
validations:
12+
required: true
13+
- type: textarea
14+
id: steps
15+
attributes:
16+
label: 复现步骤
17+
description: 请提供稳定复现步骤或最小复现代码。
18+
placeholder: |
19+
1.
20+
2.
21+
3.
22+
validations:
23+
required: true
24+
- type: input
25+
id: version
26+
attributes:
27+
label: 使用版本
28+
placeholder: 1.0.0 或 commit hash
29+
validations:
30+
required: true
31+
- type: input
32+
id: platform
33+
attributes:
34+
label: 平台
35+
placeholder: iOS 17.5 / macOS 14.5 / Swift 5.9
36+
validations:
37+
required: true
38+
- type: textarea
39+
id: logs
40+
attributes:
41+
label: 日志
42+
render: text

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: 功能建议
2+
description: 提出新能力或改进建议
3+
title: "[Feature]: "
4+
labels: ["enhancement"]
5+
body:
6+
- type: textarea
7+
id: problem
8+
attributes:
9+
label: 背景和问题
10+
description: 请说明当前场景中的限制或痛点。
11+
validations:
12+
required: true
13+
- type: textarea
14+
id: proposal
15+
attributes:
16+
label: 建议方案
17+
description: 请说明希望增加或调整的能力。
18+
validations:
19+
required: true
20+
- type: textarea
21+
id: alternatives
22+
attributes:
23+
label: 其他方案
24+
description: 如果有替代方案或兼容性要求，请一并说明。

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
## 变更内容
2+
3+
-
4+
5+
## 验证方式
6+
7+
-
8+
9+
## 兼容性影响
10+
11+
-

‎.github/workflows/ci.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches:
7+
- main
8+
- master
9+
10+
jobs:
11+
test:
12+
name: Swift Test
13+
runs-on: macos-15
14+
steps:
15+
- name: Checkout
16+
uses: actions/checkout@v4
17+
18+
- name: Run tests
19+
run: swift test

‎.gitignore‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
### macOS
2+
# Finder metadata
3+
.DS_Store
4+
5+
# Thumbnails
6+
._*
7+
8+
# Custom folder icons
9+
Icon
10+
11+
12+
# Volume root files
13+
.DocumentRevisions-V100
14+
.fseventsd
15+
.Spotlight-V100
16+
.TemporaryItems
17+
.Trashes
18+
.VolumeIcon.icns
19+
.com.apple.timemachine.donotpresent
20+
21+
### Xcode
22+
# Xcode user settings
23+
xcuserdata/
24+
25+
# Xcode build artifacts
26+
build/
27+
DerivedData/
28+
29+
# Obj-C/Swift specific
30+
*.hmap
31+
*.ipa
32+
*.dSYM.zip
33+
*.dSYM
34+
35+
# Playgrounds
36+
timeline.xctimeline
37+
playground.xcworkspace
38+
39+
# Xcode state files
40+
*.xccheckout
41+
*.moved-aside
42+
*.xcuserstate
43+
*.xcscmblueprint
44+
45+
46+
### Objective-C
47+
# Xcode user settings
48+
xcuserdata/
49+
50+
# Xcode build data
51+
DerivedData/
52+
53+
# Obj-C/Swift specific
54+
*.hmap
55+
56+
# App packaging
57+
*.ipa
58+
*.dSYM.zip
59+
*.dSYM
60+
61+
# Playgrounds
62+
timeline.xctimeline
63+
playground.xcworkspace
64+
65+
### Swift
66+
# Xcode user settings
67+
xcuserdata/
68+
69+
# Xcode build data
70+
DerivedData/
71+
72+
# Swift/Obj-C specific
73+
*.hmap
74+
75+
# App packaging
76+
*.ipa
77+
*.dSYM.zip
78+
*.dSYM
79+
80+
# Playgrounds
81+
timeline.xctimeline
82+
playground.xcworkspace
83+
84+
# Swift Package Manager
85+
# Package.resolved
86+
.build
87+
.swiftpm
88+
89+
# Docs
90+
.superpowers
91+
docs/

‎AGENTS.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# AGENTS.md
2+
3+
本文件适用于当前目录及所有子目录。
4+
5+
## 项目概览
6+
7+
- 这是 `HTTPMediaCache`，一个 Swift-only 的本地 HTTP 多媒体缓存库。
8+
- 核心库位于 `Sources/HTTPMediaCache`，通过 Swift Package Manager 构建。
9+
- 测试位于 `Tests/HTTPMediaCacheTests`，使用 `XCTest`。
10+
- 示例工程位于 `Example/HTTPMediaCacheExample.xcodeproj`，包含 iOS 与 macOS 示例。
11+
- 主要运行环境：Swift 5.10+、iOS 15.0+、macOS 12.0+。
12+
- 当前核心第三方依赖为 `swift-nio`，主要用于本地 HTTP 代理服务。
13+
14+
## 回复与文案
15+
16+
- 默认使用简体中文回复。
17+
- 代码注释、文档和 Git commit 信息默认使用简体中文，除非用户明确要求其他语言。
18+
- 代码里的错误信息描述和日志信息默认使用英文，避免运行时输出混用中文。
19+
- 用户是有经验开发者，不解释基础语法或入门概念。
20+
- 优先给出高质量方案，减少无谓往返。
21+
- 复杂任务先给 1-3 个方案与权衡，确认后再实现；简单或中等任务可以直接处理。
22+
23+
## Git 与变更边界
24+
25+
- 只有在用户明确同意后才执行 `git commit`。
26+
- 禁止执行 `git push` 和 `git push --force`。
27+
- 未经明确要求，避免破坏性 Git 操作，例如 `git reset --hard`、`git clean -f`、`git rebase`、`git commit --amend`。
28+
- 不要回退或覆盖用户已有改动；遇到脏工作区时只处理当前任务相关文件。
29+
- 删除文件、修改公共 API、新增第三方依赖前必须先确认。
30+
- 避免无关重构、无关格式化和大范围机械改动。
31+
32+
## Swift 代码规范
33+
34+
- 新建或修改 `.swift` 文件后，必须只对该文件执行 `swiftformat <file>`。
35+
- 禁止执行目录级或全项目格式化，例如 `swiftformat .`、`swiftformat Sources`、`swiftformat Tests`。
36+
- 新建 Swift 文件必须包含完整文件头，作者或组织信息使用项目约定或实际贡献者信息，不要硬编码个人信息；日期使用创建当天实际日期：
37+
38+
```swift
39+
//
40+
// <FileName>.swift
41+
// HTTPMediaCache
42+
//
43+
// Created by <AuthorOrOrganization> on <YYYY/M/D>.
44+
//
45+
```
46+
47+
- 公开 API 需要保持中文文档注释清晰，描述行为、参数和重要边界。
48+
- 优先保持现有 async/await、actor、Swift concurrency 风格，不引入不必要的回调式封装。
49+
- 核心缓存、Range、HLS、代理和下载链路改动要保持职责边界清晰：
50+
- `API` 暴露公共入口和模型。
51+
- `Core` 放通用运行时、Range、URL 编解码等核心能力。
52+
- `Storage` 负责缓存索引、文件存储和缓存单元。
53+
- `Network` 负责下载抽象和 URLSession 下载实现。
54+
- `Pipeline` 负责读取、规划和组合缓存/远端数据。
55+
- `Proxy` 负责本地代理、请求路由和响应写入。
56+
- `HLS` 负责 playlist 解析、改写和预加载策略。
57+
- 示例工程代码位于 `Example`，不要把示例层逻辑反向引入核心库。
58+
59+
## 测试与验证
60+
61+
- 默认测试命令：
62+
63+
```bash
64+
swift test
65+
```
66+
67+
- 修改具体模块时优先运行相关测试，最后根据影响范围决定是否运行完整 `swift test`。
68+
- 行为变更必须补充或更新测试，尤其是：
69+
- Range 解析与响应。
70+
- 缓存索引、缓存区间合并和文件存储。
71+
- HLS playlist 改写、segment/key/init map 处理。
72+
- 预加载策略、取消、并发限制和进度。
73+
- 本地代理请求路由和 NIO 响应。
74+
- 下载配置、请求头、content type 和错误记录。
75+
- 测试中需要临时存储时优先使用 `FileManager.default.temporaryDirectory` 下的唯一目录，并做好清理。
76+
- 不要依赖真实公网媒体资源作为单元测试前提；优先使用测试替身、固定数据和本地可控输入。
77+
78+
## 构建与示例
79+
80+
- 打开示例工程：
81+
82+
```bash
83+
open Example/HTTPMediaCacheExample.xcodeproj
84+
```
85+
86+
- 示例工程包含以下共享或平台代码：
87+
- `Example/Shared`
88+
- `Example/iOS`
89+
- `Example/macOS`
90+
- 修改示例 UI 或播放链路时，确认 iOS 与 macOS 是否都受影响。
91+
92+
## 文档要求
93+
94+
- README 示例应与真实 API 保持一致。
95+
- 修改公共 API、安装方式、预加载语义、缓存清理语义或平台要求时，同步更新 README。
96+
- 变更用户可见行为时，视情况更新 `CHANGELOG.md`。
97+
- PR 描述应包含变更内容、验证方式和兼容性影响。

‎CHANGELOG.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Changelog
2+
3+
## 1.0.0 - 2026-05-12
4+
5+
### 功能
6+
7+
- 首个开源版本。
8+
- 支持本地 HTTP 代理、Range 缓存、文件预加载、HLS 预加载、HLS 播放列表改写、缓存查询和缓存清理。
9+
- 支持缓存 identity provider，可在 URL converter 之外自定义缓存 key 归一化；设置后优先级高于 URL converter。
10+
- 支持 HLS 下载请求头 provider，可按 playlist、key、init map、segment 等资源类型追加下载请求头。
11+
- 支持 URLSession 下载指标回调，普通资源和 HLS 资源共用 metrics 采集路径。当前回调直接暴露 `URLSessionTaskMetrics`，不额外引入二次封装。
12+
- 支持代理 URL 判断与原始 URL 还原 API，便于播放器链路和业务层区分代理地址。
13+
- 提供 `cacheReader`、`cacheLoader` 与 `cacheHLSLoader`，支持不经过播放器代理时直接读取并复用缓存。
14+
- 支持下载响应 content type 白名单与不可接受类型 disposer，支持业务侧兼容特殊服务端响应。
15+
- 支持下载 Range 长度 provider，缺失区间回源时可按业务策略拆分 Range 请求。
16+
- 支持控制台日志、文件日志和按 URL 记录的错误查询、清理 API。
17+
- 提供 iOS 与 macOS 示例工程。
18+
19+
### HLS 下载策略
20+
21+
- HLS playlist、key 和完整 segment 回源默认不带播放器请求头，也不生成默认 Range。
22+
- HLS init map 与 byte-range segment 使用 playlist 声明的 Range；HLS 下载请求头 provider 返回的 `Range` 会被忽略，避免覆盖 playlist 语义。
23+
- HLS preload 与代理播放共用同一套下载策略、cache identity 和 metrics 采集路径。

‎CONTRIBUTING.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# 贡献指南
2+
3+
感谢你愿意为 HTTPMediaCache 贡献代码、文档或问题反馈。
4+
5+
## 开发流程
6+
7+
1. Fork 仓库并创建特性分支。
8+
2. 修改代码或文档。
9+
3. 运行必要测试，至少覆盖改动影响范围。
10+
4. 提交 pull request，并说明变更内容、验证方式和兼容性影响。
11+
12+
## 代码要求
13+
14+
- Swift 代码应保持清晰的命名和边界，公开 API 需要补充中文文档注释。
15+
- 行为变更应补充测试。
16+
- 不在 pull request 中混入无关格式化或重构。
17+
- 不提交本地构建产物、用户配置或派生数据。
18+
19+
## 问题反馈
20+
21+
提交 issue 时请尽量包含：
22+
23+
- 使用版本或 commit。
24+
- 运行平台和系统版本。
25+
- 可复现步骤。
26+
- 预期行为与实际行为。
27+
- 相关日志或最小复现工程。

0 commit comments

Comments
 (0)