rogee/any-hub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
abfa51f12e577d2a35edcb71da906bf4fe80e2f5
any-hub/specs/002-fiber-single-proxy/tasks.md
Rogee 39ebf61572 init
2025-11-14 12:11:44 +08:00

7.0 KiB
Raw Blame History

description
description
Task list for HTTP 服务与单仓代理

Tasks: HTTP 服务与单仓代理

Input: Design documents from /specs/002-fiber-single-proxy/ Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/

Tests: 宪法 v1.0.0 要求覆盖配置解析、Host Header 路由、缓存读写、条件回源与示例集成测试，本任务清单默认包含相应测试项。

Organization: Tasks are grouped by user story to enable independent implementation and testing of each story.

Format: [ID] [P?] [Story] Description

  • [P]: Can run in parallel (different files, no dependencies)
  • [Story]: Which user story this task belongs to (e.g., US1, US2, US3)
  • Include exact file paths in descriptions

Phase 1: Setup (Shared Infrastructure)

Purpose: 准备文档与目录结构，确保团队对 Phase 1 范围有统一认知。

  • T001 更新 DEVELOPMENT.md 的 Phase 1 章节，描述 HTTP 服务/缓存迭代目标
  • T002 在 README.md 添加 “单仓代理 (Phase 1)” 小节并链接到 spec/plan
  • T003 [P] 创建 internal/server/ 与 internal/cache/ 目录说明文件（doc.go）概述职责

Phase 2: Foundational (Blocking Prerequisites)

Purpose: 构建 Host→Hub 注册表、HTTP 客户端和缓存存储基础，所有用户故事依赖这些能力。

  • T004 实现 internal/server/hub_registry.go，从配置构建 Host/端口→Hub 映射并提供查询 API
  • T005 [P] 在 internal/server/http_client.go 创建共享上游 HTTP 客户端（含超时、Proxy、Header 透传）
  • T006 设计 internal/cache/store.go 接口 + 文件布局（StoragePath/<hub>/<path> 与 .meta）
  • T007 [P] 在 tests/integration/upstream_stub_test.go 搭建可复用的模拟上游服务器（Docker/NPM 两种路径）

Checkpoint: Registry、HTTP 客户端、缓存存储与测试桩可用，方可进入用户故事实现。

Phase 3: User Story 1 - Host 路由下的单仓访问 (Priority: P1) 🎯 MVP

Goal: Fiber 服务可根据 Host/端口匹配到唯一 Hub，并将请求透明转发。

Independent Test: 使用 curl -H "Host: docker.hub.local" 对本地服务发起请求，结合 httptest 断言正确 Hub、上游 URL 和日志字段。

Tests for User Story 1

  • T008 [P] [US1] 编写路由单元测试：internal/server/router_test.go 覆盖 Host 命中/未配置/默认逻辑
  • T009 [P] [US1] 添加集成测试：tests/integration/host_routing_test.go 验证端口+Host 组合处理

Implementation for User Story 1

  • T010 [US1] 构建 Fiber App & 中间件（请求日志、错误捕获）于 internal/server/router.go
  • T011 [US1] 在 cmd/any-hub/main.go 接线 server 启动逻辑，传入 registry + HTTP 客户端
  • T012 [US1] 为 Host 未命中添加 404 响应与日志字段（internal/server/router.go）
  • T013 [US1] 更新 quickstart.md，记录如何使用 Host 头访问单仓代理

Checkpoint: CLI 可启动 HTTP 服务并完成 Host→Hub 路由，日志含 action/host 字段。

Phase 4: User Story 2 - 磁盘缓存与回源流程 (Priority: P1)

Goal: 在磁盘上缓存上游响应，支持 TTL、条件请求与流式读写。

Independent Test: 使用模拟上游写入缓存后再次请求，观察命中与 304 流程；覆盖写入失败、上游错误等场景。

Tests for User Story 2

  • T014 [P] [US2] 为 internal/cache/store_test.go 添加命中/未命中/TTL 过期测试
  • T015 [P] [US2] 在 tests/integration/cache_flow_test.go 编写端到端测试（首次写入、304 回退、上游失败）

Implementation for User Story 2

  • T016 [US2] 在 internal/cache/store.go 实现读/写/元数据 API，并处理并发写入/临时文件
  • T017 [US2] 在 internal/proxy/handler.go 中实现缓存流程（命中→读磁盘，未命中→回源→写缓存→流式返回）
  • T018 [US2] 支持条件请求 Header（If-None-Match/If-Modified-Since）并处理 304（internal/proxy/upstream.go）
  • T019 [US2] 扩展日志字段，记录 cache_hit、upstream_status、elapsed_ms（internal/logging/fields.go + internal/proxy/handler.go）
  • T020 [US2] 在 config.example.toml 增加缓存路径/TTL 示例，并更新 DEVELOPMENT.md 的缓存调优段落

Checkpoint: 缓存命中率可在日志中观察；回源路径流式返回并具备条件请求能力。

Phase 5: User Story 3 - 最小 Docker/NPM 代理样例 (Priority: P2)

Goal: 提供可复制的示例配置与 quickstart 脚本，验证 Docker 或 NPM 仓库的代理行为。

Independent Test: 运行文档中的 quickstart，对真实或模拟上游完成一次包/镜像拉取，并验证缓存目录写入。

Tests for User Story 3

  • T021 [P] [US3] 编写示例集成测试 tests/integration/docker_sample_test.go（或 npm_sample_test.go）验证端到端流程

Implementation for User Story 3

  • T022 [US3] 添加 configs/docker.sample.toml 与 configs/npm.sample.toml，注释必要字段
  • T023 [US3] 在 quickstart.md 新增示例步骤（Docker/NPM）、常见问题与日志示例
  • T024 [US3] 准备脚本或 Make 目标 scripts/demo-proxy.sh 运行示例配置
  • T025 [US3] 补充 README “示例代理” 章节链接 demo 脚本与 quickstart

Checkpoint: 示例配置 & 文档可指导用户完成最小代理体验，并由自动化测试验证。

Phase 6: Polish & Cross-Cutting Concerns

Purpose: 收尾文档、CI 与质量保证，确保 Phase 1 可长期维护。

  • T026 在 cmd/any-hub/main.go 与 internal/* 新增中文注释，解释 server/cache 关键流程
  • T027 [P] 增加 tests/integration/interrupt_test.go，验证下载中断后的缓存清理
  • T028 更新 CHANGELOG.md 与 README.md，记录 Phase 1 完成情况
  • T029 运行 gofmt、go test ./...，并在 DEVELOPMENT.md 记录验证结果与命令

Dependencies & Execution Order

Phase Dependencies

  • Phase 1 → Phase 2 → User Stories (US1/US2/US3) → Phase 6

User Story Dependencies

  • US1 (Host 路由) 依赖 Phase 2 完整；US2 依赖 US1 提供的 Fiber/Proxy 框架；US3 依赖 US1+US2 的代理能力

Parallel Execution Examples

  • US1: T008 与 T009（测试）可并行；T010/T011 实现后可由 T012/T013 跟进
  • US2: T014/T015 可并行；缓存实现 T016 可与日志扩展 T019 同步推进
  • US3: T022（配置）与 T024（脚本）可并行，测试 T021 需在示例完成后执行

Implementation Strategy

MVP First (User Story 1 Only)

  1. 完成 Phase 1-2
  2. 交付 Host 路由 + HTTP 服务（US1），即可演示基础代理能力

Incremental Delivery

  1. 在 MVP 基础上继续 US2（缓存）→ US3（示例）
  2. 每个阶段完成后运行 quickstart + 集成测试，确保可独立交付

Parallel Team Strategy

  • 团队 A：负责 server/router（US1）
  • 团队 B：负责 cache/proxy（US2）
  • 团队 C：负责示例配置与文档（US3）
Reference in New Issue View Git Blame Copy Permalink