cache-proxy/memory-bank/systemPatterns.md

系统架构与设计模式

cache-proxy 的系统设计遵循了几个关键的模式和原则，以实现其高性能和高可用性的目标。

核心架构

系统可以分为三个主要部分：

1. HTTP 服务器层: 负责接收客户端请求，并使用中间件进行日志记录、错误恢复等通用处理。
2. 缓存处理层: 检查请求的文件是否存在于本地缓存中，并根据缓存策略决定是直接提供缓存文件还是向上游请求。
3. 上游选择与下载层: 这是系统的核心，负责并发地从多个上游服务器获取数据，并管理下载过程。

关键设计模式

1. 竞争式请求 (Racing Requests)

这是实现“选择最快”功能的核心模式。

• fastesUpstream 函数为每个上游服务器创建一个 goroutine。
• 所有 goroutine 并发地向上游服务器发送请求。
• 使用 sync.Once 来确保只有一个 goroutine 能够“胜出”并成为最终的数据源。
• 一旦有 goroutine 胜出，它会调用 context.CancelFunc 来通知所有其他 goroutine 停止工作，从而避免不必要的资源消耗。

2. 生产者-消费者模式 (Producer-Consumer)

在文件下载和流式响应（Ranged Request）中，使用了生产者-消费者模式。

• 生产者 (startOrJoinStream):
  • 为每个首次请求的文件启动一个 goroutine。
  • 负责从最快的上游服务器下载文件内容。
  • 将内容直接写入一个临时文件 (*os.File) 中，而不是写入内存缓冲区。
  • 通过 sync.Cond 广播下载进度（已写入的字节数 Offset）。
  • 下载成功后，将临时文件重命名为最终的缓存文件。
• 消费者 (serveRangedRequest):
  • 当收到一个范围请求时，它会找到或等待对应的 StreamObject。
  • 为了安全地并发读取正在被生产者写入的文件，消费者会使用 syscall.Dup() 复制临时文件的文件描述符。
  • 每个消费者都通过自己独立的、复制出来的文件句柄 (*os.File) 读取所需范围的数据，这避免了与生产者或其他消费者发生文件句柄状态的冲突。
  • 消费者根据生产者的 Offset 进度和 sync.Cond 信号来等待其请求范围的数据变为可用。

3. 并发访问控制与对象生命周期管理

为了处理多个客户端同时请求同一个文件的情况，系统使用了 sync.Mutex 和一个 map[string]*StreamObject。

• 当第一个对某文件的请求（我们称之为“消费者”）到达时，它会获得一个锁，并创建一个 StreamObject 来代表这个正在进行的下载任务，然后启动一个“生产者”goroutine 来执行下载。
• 后续对同一文件的请求会发现 StreamObject 已存在于 map 中，它们不会再次启动下载，而是会共享这个对象。

StreamObject 生命周期管理 (基于 GC)

我们采用了一种简洁且高效的、依赖 Go 语言垃圾回收（GC）的模式来管理 StreamObject 的生命周期：

1. 生产者负责移除: 下载 goroutine（生产者）在完成其任务（无论成功或失败）后，其唯一的职责就是将 StreamObject 从全局的 map[string]*StreamObject 中移除。
2. 消费者持有引用: 与此同时，所有正在处理该文件请求的 HTTP Handler（消费者）仍然持有对该 StreamObject 的引用。
3. GC 自动回收: 因为消费者们还持有引用，Go 的 GC 不会回收这个对象。只有当最后一个消费者处理完请求、其函数栈帧销毁后，对 StreamObject 的最后一个引用才会消失。此时，GC 会在下一次运行时自动回收该对象的内存。

这个模式避免了复杂的引用计数或定时器，代码更简洁，并且从根本上解决了之前因固定延迟导致的性能问题。

4. 中间件 (Middleware)

项目使用了 Go 的标准 http.Handler 接口和中间件模式来构建请求处理链。

• pkgs/middleware 目录中定义了可重用的中间件，如 httplog 和 recover。
• 这种模式使得在不修改核心业务逻辑的情况下，可以轻松地添加或删除日志、认证、错误处理等功能。