70 lines
4.0 KiB
Markdown
70 lines
4.0 KiB
Markdown
# Implementation Plan: HTTP 服务与单仓代理
|
||
|
||
**Branch**: `002-fiber-single-proxy` | **Date**: 2025-11-13 | **Spec**: [spec.md](./spec.md)
|
||
**Input**: Feature specification from `/specs/002-fiber-single-proxy/spec.md`
|
||
|
||
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
|
||
|
||
## Summary
|
||
|
||
Deliver a Phase 1-ready proxy: Fiber HTTP server routing by Host→Hub, disk cache with TTL + conditional revalidation, and runnable Docker/NPM samples backed by integration tests. Core work spans server/router scaffolding, cache/proxy pipeline, observability, and documentation to prove the feature end to end.
|
||
|
||
## Technical Context
|
||
|
||
**Language/Version**: Go 1.25+ (静态链接，单二进制交付)
|
||
**Primary Dependencies**: Fiber v3（HTTP 服务）、Viper（配置）、Logrus + Lumberjack（结构化日志 & 滚动）、标准库 `net/http`/`io`
|
||
**Storage**: 本地文件系统缓存目录 `StoragePath/<Hub>/<path>` + `.meta` 元数据
|
||
**Testing**: `go test ./...`，配合 `httptest`、fake upstream server、临时目录验证路由/缓存/集成路径
|
||
**Target Platform**: Linux/Unix CLI 进程，由 systemd/supervisor 管理，匿名下游客户端
|
||
**Project Type**: 单 Go 项目（`cmd/` 入口 + `internal/*` 包）
|
||
**Performance Goals**: 缓存命中路径需低延迟（相对首个请求减少 ≥70%），回源路径流式传输并限制常驻内存 <256MB，日志可追踪命中/回源/错误
|
||
**Constraints**: 禁止 Web/UI、账号体系、额外配置源；必须通过 `config.toml` 驱动 Host、端口、缓存策略；请求匿名；不可新增未审核依赖
|
||
**Scale/Scope**: Phase 1 仅实现单 Hub 路由 + Docker/NPM 示例；后续多 Hub、多协议将基于此扩展
|
||
|
||
## Constitution Check
|
||
|
||
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
||
|
||
- 方案遵守“轻量 CLI 代理”定位，不引入 UI/账号/外部控制面。
|
||
- 继续使用 Go + Fiber/Viper/Logrus/Lumberjack + 标准库，Helm/DB/Web 依赖均不在 scope。
|
||
- 仅依赖 `config.toml` 说明 Host/端口/缓存字段；新增字段需写入配置 schema 与文档。
|
||
- 缓存策略保持“命中即返回、未命中流式回源”，并要求结构化日志记录 `cache_hit`、上游状态等字段。
|
||
- 计划包含配置解析、Host Header 路由、缓存逻辑、示例及测试，满足宪法强制测试/文档 Gate。
|
||
|
||
**Post-design re-check (Phase 1)**: 设计阶段将审查 server/cache/示例文档，确认未引入新依赖且 quickstart/contract 体现在 spec/plan/task 中；若出现额外库或多配置源，需重新申请豁免。
|
||
|
||
## Project Structure
|
||
|
||
### Documentation (this feature)
|
||
|
||
```text
|
||
specs/002-fiber-single-proxy/
|
||
├── plan.md # 当前文件
|
||
├── research.md # Phase 0 研究决策
|
||
├── data-model.md # 实体/关系/约束
|
||
├── quickstart.md # 演练 Docker/NPM 示例步骤
|
||
├── contracts/ # CLI/Fiber/缓存交付合同（md 或 OpenAPI）
|
||
└── tasks.md # Phase 2 工作拆解（/speckit.tasks 输出）
|
||
```
|
||
|
||
### Source Code (repository root)
|
||
```text
|
||
cmd/any-hub/ # CLI 入口，启动 server/cache
|
||
internal/server/ # Fiber app、Host Registry、路由/中间件
|
||
internal/cache/ # 磁盘缓存/元数据/TTL
|
||
internal/proxy/ # 回源/条件请求/流式复制
|
||
internal/logging/ # 结构化日志字段
|
||
configs/ # 示例 config (docker|npm)
|
||
tests/integration/ # upstream stub + e2e 测试
|
||
```
|
||
|
||
**Structure Decision**: 仍按单仓库单二进制；新增 `internal/server`, `internal/cache`, `tests/integration` 目录必须保持与 `internal/proxy` 清晰边界，所有引用通过包级接口注入，避免循环依赖。
|
||
|
||
## Complexity Tracking
|
||
|
||
> **Fill ONLY if Constitution Check has violations that must be justified**
|
||
|
||
| Violation | Why Needed | Simpler Alternative Rejected Because |
|
||
|-----------|------------|-------------------------------------|
|
||
| _None_ | — | — |
|