csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
e98dd4d7255646f97653d46691cfeb4a064a5ee1
junhong_cmp_fiber/specs/001-fiber-middleware-integration/tasks.md

23 KiB
Raw Blame History

Tasks: Fiber Middleware Integration with Configuration Management

Feature: 001-fiber-middleware-integration
Input: Design documents from /specs/001-fiber-middleware-integration/
Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/api.yaml

Tests: Unit and integration tests are REQUIRED per constitution testing standards (70%+ overall, 90%+ core business)

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: Project initialization and basic structure

  • T001 Create directory structure: pkg/config/, pkg/logger/, pkg/response/, pkg/errors/, pkg/constants/, pkg/validator/, internal/middleware/, configs/, logs/
  • T002 [P] Setup unified error codes and messages in pkg/errors/codes.go
  • T003 [P] Setup custom error types in pkg/errors/errors.go
  • T004 [P] Setup unified response structure in pkg/response/response.go
  • T005 [P] Setup response code constants in pkg/response/codes.go
  • T006 [P] Setup business constants in pkg/constants/constants.go
  • T007 [P] Setup Redis key generation functions in pkg/constants/redis.go

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Core infrastructure that MUST be complete before ANY user story can be implemented

⚠️ CRITICAL: No user story work can begin until this phase is complete

Configuration Management (US1 Foundation)

  • T008 Create Config structures with Viper mapstructure tags in pkg/config/config.go
  • T009 Implement config loading with validation in pkg/config/loader.go
  • T010 Implement config hot reload with fsnotify in pkg/config/watcher.go
  • T011 Create default configuration file in configs/config.yaml
  • T012 [P] Create environment-specific configs: config.dev.yaml, config.staging.yaml, config.prod.yaml
  • T012a [P] Unit test for environment-specific config loading (test APP_ENV variable loads correct config file) in pkg/config/loader_test.go

Logging Infrastructure (US2 Foundation)

  • T013 Initialize Zap logger with JSON encoder in pkg/logger/logger.go
  • T014 Setup Lumberjack rotation for app.log in pkg/logger/logger.go (合并到 T013)
  • T015 Setup Lumberjack rotation for access.log in pkg/logger/logger.go (合并到 T013)
  • T016 Create Fiber logger middleware adapter in pkg/logger/middleware.go

Redis Connection (US6 Foundation)

  • T017 Setup Redis client with connection pool configuration in pkg/validator/token.go (使用 go-redis 直接在 main.go 中初始化)

Checkpoint: Foundation ready - user story implementation can now begin in parallel

Phase 3: User Story 1 - Configuration Hot Reload (Priority: P1) 🎯 MVP

Goal: Enable runtime configuration updates without service restart

Independent Test: Modify config.yaml while server runs, verify changes applied within 5 seconds without restart

Unit Tests for User Story 1

  • T018 [P] [US1] Unit test for config loading and validation in pkg/config/loader_test.go
  • T019 [P] [US1] Unit test for config hot reload mechanism in pkg/config/watcher_test.go
  • T020 [P] [US1] Test invalid config handling (malformed YAML, validation errors) in pkg/config/config_test.go

Implementation for User Story 1

  • T021 [US1] Implement atomic config pointer swap in pkg/config/config.go (sync/atomic usage)
  • T022 [US1] Implement config change callback with validation in pkg/config/watcher.go
  • T023 [US1] Add config reload logging with Zap in pkg/config/watcher.go
  • T024 [US1] Integrate config watcher with context cancellation in cmd/api/main.go
  • T025 [US1] Add graceful shutdown for config watcher in cmd/api/main.go

Checkpoint: Config hot reload should work independently - modify config and see changes applied

Phase 4: User Story 2 - Structured Logging and Log Rotation (Priority: P1)

Goal: Production-ready JSON logging with automatic rotation and separate app/access logs

Independent Test: Generate logs, verify JSON format in app.log and access.log, trigger rotation by size

Unit Tests for User Story 2

  • T026 [P] [US2] Unit test for logger initialization in pkg/logger/logger_test.go
  • T027 [P] [US2] Unit test for log rotation configuration in pkg/logger/rotation_test.go
  • T028 [P] [US2] Test structured logging with fields in pkg/logger/logger_test.go

Implementation for User Story 2

  • T029 [P] [US2] Create appLogger instance with Lumberjack writer in pkg/logger/logger.go
  • T030 [P] [US2] Create accessLogger instance with separate Lumberjack writer in pkg/logger/logger.go
  • T031 [US2] Configure JSON encoder with RFC3339 timestamps in pkg/logger/logger.go
  • T032 [US2] Export GetAppLogger() and GetAccessLogger() functions in pkg/logger/logger.go
  • T033 [US2] Add logger.Sync() call in graceful shutdown in cmd/api/main.go

Checkpoint: Both app.log and access.log should exist with JSON entries, rotate at configured size

Phase 5: User Story 3 - Unified API Response Format (Priority: P1)

Goal: Consistent response structure across all endpoints

Independent Test: Call any endpoint, verify response has {code, data, msg, timestamp} structure

Unit Tests for User Story 3

  • T034 [P] [US3] Unit test for Success() response helper in pkg/response/response_test.go
  • T035 [P] [US3] Unit test for Error() response helper in pkg/response/response_test.go
  • T036 [P] [US3] Test response serialization with sonic JSON in pkg/response/response_test.go

Implementation for User Story 3

  • T037 [P] [US3] Implement Success() helper function in pkg/response/response.go
  • T038 [P] [US3] Implement Error() helper function in pkg/response/response.go
  • T039 [P] [US3] Implement SuccessWithMessage() helper function in pkg/response/response.go
  • T040 [US3] Configure Fiber to use sonic as JSON serializer in cmd/api/main.go
  • T041 [US3] Create example health check endpoint using response helpers in internal/handler/health.go
  • T042 [US3] Register health check route in cmd/api/main.go

Checkpoint: Health check endpoint returns unified response format with proper structure

Phase 6: User Story 4 - Request Logging and Tracing (Priority: P2)

Goal: Unique UUID v4 request ID for every request with comprehensive access logging

Independent Test: Make requests, verify each has unique X-Request-ID header and appears in logs

Integration Tests for User Story 4

  • T043 [P] [US4] Integration test for requestid middleware (UUID v4 generation) in tests/integration/middleware_test.go
  • T044 [P] [US4] Integration test for logger middleware (access log entries) in tests/integration/middleware_test.go
  • T045 [P] [US4] Test request ID propagation through middleware chain in tests/integration/middleware_test.go

Implementation for User Story 4

  • T046 [P] [US4] Configure Fiber requestid middleware with google/uuid in cmd/api/main.go
  • T047 [US4] Implement custom logger middleware writing to accessLogger in internal/middleware/logger.go
  • T048 [US4] Add request ID to Fiber Locals in logger middleware in internal/middleware/logger.go
  • T049 [US4] Add X-Request-ID response header in logger middleware in internal/middleware/logger.go
  • T050 [US4] Log request details (method, path, status, duration, IP, user_agent) to access.log in internal/middleware/logger.go
  • T051 [US4] Register requestid and logger middleware in correct order in cmd/api/main.go

Checkpoint: Every request should have unique UUID v4 in header and access.log, with full request details

Phase 7: User Story 5 - Automatic Error Recovery (Priority: P2)

Goal: Recover from panics, log stack trace, return error response, continue serving requests

Independent Test: Trigger panic in handler, verify server doesn't crash, returns 500, logs stack trace

Integration Tests for User Story 5

  • T052 [P] [US5] Integration test for panic recovery in tests/integration/middleware_test.go
  • T053 [P] [US5] Test panic logging with stack trace in tests/integration/middleware_test.go
  • T054 [P] [US5] Test subsequent requests after panic recovery in tests/integration/middleware_test.go

Implementation for User Story 5

  • T055 [US5] Implement custom recover middleware with Zap logging in internal/middleware/recover.go
  • T056 [US5] Add stack trace capture to recover middleware in internal/middleware/recover.go
  • T057 [US5] Add request ID to panic logs in internal/middleware/recover.go
  • T058 [US5] Return unified error response (500, code 1000) on panic in internal/middleware/recover.go
  • T059 [US5] Register recover middleware as FIRST middleware in cmd/api/main.go
  • T060 [US5] Create test panic endpoint for testing in internal/handler/test.go (optional, for quickstart validation)

Checkpoint: Panic in handler should be caught, logged with stack trace, return 500, server continues running

Phase 8: User Story 6 - Token-Based Authentication (Priority: P2)

Goal: Validate authentication tokens against Redis, enforce access control

Independent Test: Request with valid/invalid/missing token, verify 200/401 responses with correct error codes

Unit Tests for User Story 6

  • T061 [P] [US6] Unit test for TokenValidator.Validate() with valid token in pkg/validator/token_test.go
  • T062 [P] [US6] Unit test for expired/invalid token (redis.Nil) in pkg/validator/token_test.go
  • T063 [P] [US6] Unit test for Redis unavailable (fail closed) in pkg/validator/token_test.go
  • T064 [P] [US6] Unit test for context timeout in Redis operations in pkg/validator/token_test.go

Integration Tests for User Story 6

  • T065 [P] [US6] Integration test for keyauth middleware with valid token in tests/integration/auth_test.go
  • T066 [P] [US6] Integration test for missing token (401, code 1001) in tests/integration/auth_test.go
  • T067 [P] [US6] Integration test for invalid token (401, code 1002) in tests/integration/auth_test.go
  • T068 [P] [US6] Integration test for Redis down (503, code 1004) in tests/integration/auth_test.go

Implementation for User Story 6

  • T069 [US6] Create TokenValidator struct with Redis client in pkg/validator/token.go
  • T070 [US6] Implement TokenValidator.Validate() with Redis GET operation in pkg/validator/token.go
  • T071 [US6] Add context timeout (50ms) for Redis operations in pkg/validator/token.go
  • T072 [US6] Implement Redis availability check (Ping) with fail-closed behavior in pkg/validator/token.go
  • T073 [US6] Implement custom keyauth middleware wrapper in internal/middleware/auth.go
  • T074 [US6] Configure keyauth with header lookup "token" in internal/middleware/auth.go
  • T075 [US6] Add validator callback to keyauth config in internal/middleware/auth.go
  • T076 [US6] Store user_id in Fiber Locals after successful validation in internal/middleware/auth.go
  • T077 [US6] Implement custom ErrorHandler mapping errors to response codes in internal/middleware/auth.go
  • T078 [US6] Add auth failure logging with request ID in internal/middleware/auth.go
  • T079 [US6] Register keyauth middleware after logger in cmd/api/main.go
  • T080 [US6] Create protected example endpoint (/api/v1/users) in internal/handler/user.go
  • T081 [US6] Register protected routes with middleware in cmd/api/main.go

Checkpoint: Protected endpoints require valid token, reject invalid/missing tokens with correct error codes

Phase 9: User Story 7 - Rate Limiting Configuration (Priority: P3)

Goal: Provide IP-based rate limiting capability (disabled by default, easy to enable)

Independent Test: Enable limiter, exceed limit, verify 429 responses; disable and verify no limiting

Integration Tests for User Story 7

  • T082 [P] [US7] Integration test for rate limiter with limit exceeded (429, code 1003) in tests/integration/ratelimit_test.go
  • T083 [P] [US7] Integration test for rate limit reset after window expiration in tests/integration/ratelimit_test.go
  • T084 [P] [US7] Test per-IP rate limiting (different IPs have separate limits) in tests/integration/ratelimit_test.go

Implementation for User Story 7

  • T085 [US7] Implement rate limiter middleware wrapper (COMMENTED by default) in internal/middleware/ratelimit.go
  • T086 [US7] Configure limiter with IP-based key generator (c.IP()) in internal/middleware/ratelimit.go
  • T087 [US7] Configure limiter with config values (Max, Expiration) in internal/middleware/ratelimit.go
  • T088 [US7] Add custom LimitReached handler returning unified error response in internal/middleware/ratelimit.go
  • T089 [US7] Add commented middleware registration example in cmd/api/main.go
  • T090 [US7] Document rate limiter usage in quickstart.md (how to enable, configure)
  • T091 [US7] Add rate limiter configuration examples to config files

Checkpoint: Rate limiter can be enabled via config, blocks excess requests per IP, returns 429 with code 1003

Phase 10: Polish & Quality Gates

Purpose: Final quality checks and cross-cutting improvements

Documentation & Examples

  • T092 [P] Update quickstart.md with actual file paths and final configuration
  • T093 [P] Create example requests (curl commands) in quickstart.md for all scenarios
  • T094 [P] Document middleware execution order in docs/ or README
  • T095 [P] Add troubleshooting section to quickstart.md
  • T095a [P] Create docs/rate-limiting.md with configuration guide, code examples, testing instructions, storage options comparison, and common usage patterns (implements FR-020)

Code Quality

  • T096 [P] Add Go doc comments to all exported functions and types
  • T097 [P] Run code quality checks (gofmt, go vet, golangci-lint) on all Go files
  • T098 [P] Fix all formatting, linting, and static analysis issues reported by T097
  • T099 Review all Redis key usage, ensure no hardcoded strings (use constants.RedisAuthTokenKey())
  • T101 Review all error handling, ensure explicit returns (no panic abuse)
  • T102 Review naming conventions (UserID not userId, HTTPServer not HttpServer)
  • T103 Check for Java-style anti-patterns (no I-prefix, no Impl-suffix, no getters/setters)

Testing & Coverage

  • T104 Run all unit tests: go test ./pkg/...
  • T105 Run all integration tests: go test ./tests/integration/...
  • T106 Measure test coverage: go test -cover ./...
  • T107 Verify core business logic coverage >= 90% (config, logger, validator)
  • T108 Verify overall coverage >= 70%

Security Audit

  • T109 Review authentication fail-closed behavior (Redis unavailable = 503)
  • T110 Review context timeouts on Redis operations
  • T111 Check for command injection vulnerabilities
  • T112 Verify no sensitive data in logs (tokens, passwords)
  • T113 Review error messages (no sensitive information leakage)

Performance Validation

  • T114 Test middleware overhead < 5ms per request (load testing)
  • T115 Verify log rotation doesn't block requests
  • T116 Test config hot reload doesn't affect in-flight requests
  • T117 Verify Redis connection pool handles load correctly

Final Quality Gates

  • T118 Quality Gate: All tests pass (go test ./...)
  • T119 Quality Gate: No formatting issues (gofmt -l . returns empty)
  • T120 Quality Gate: No vet issues (go vet ./...)
  • T121 Quality Gate: Test coverage meets requirements (70%+ overall, 90%+ core)
  • T122 Quality Gate: All TODOs/FIXMEs addressed or documented
  • T123 Quality Gate: quickstart.md works end-to-end (manual validation)
  • T124 Quality Gate: All middleware integrated and working together
  • T125 Quality Gate: Graceful shutdown works correctly (no goroutine leaks)
  • T126 Quality Gate: Constitution compliance verified (no violations)

Dependencies & Execution Order

Phase Dependencies

  1. Setup (Phase 1): No dependencies - start immediately
  2. Foundational (Phase 2): Depends on Setup (Phase 1) - BLOCKS all user stories
  3. User Stories (Phases 3-9): All depend on Foundational (Phase 2) completion
    • US1, US2, US3 can proceed in parallel (independent)
    • US4 depends on US2 (needs logger)
    • US5 can proceed in parallel with others
    • US6 depends on US3 (needs response format)
    • US7 depends on US3 (needs response format)
  4. Polish (Phase 10): Depends on all desired user stories being complete

User Story Dependencies

Foundational (Phase 2) - MUST COMPLETE FIRST
    ├─→ US1: Config Hot Reload (independent)
    ├─→ US2: Logging (independent)
    ├─→ US3: Response Format (independent)
    │
    ├─→ US4: Request Tracing (depends on US2: logger)
    ├─→ US5: Error Recovery (independent)
    │
    ├─→ US6: Authentication (depends on US3: response format)
    └─→ US7: Rate Limiting (depends on US3: response format)

Within Each User Story

  • Tests MUST be written FIRST and FAIL before implementation
  • Models/structures before services
  • Services before middleware
  • Middleware before registration in main.go
  • Core implementation before integration

Parallel Opportunities

Phase 1 (Setup): All tasks T002-T007 marked [P] can run in parallel

Phase 2 (Foundational):

  • T012 (dev/staging/prod configs) can run in parallel with others
  • T013-T016 (logging) can run in parallel as group
  • These are independent file operations

Phase 3-9 (User Stories):

  • After Foundational completes, these can start in parallel:
    • US1: T018-T025 (config hot reload)
    • US2: T026-T033 (logging)
    • US3: T034-T042 (response format)
    • US5: T052-T060 (error recovery)
  • After US2 completes:
    • US4: T043-T051 (request tracing)
  • After US3 completes:
    • US6: T061-T081 (authentication)
    • US7: T082-T091 (rate limiting)

Phase 10 (Polish): Many tasks marked [P] can run in parallel (documentation, linting, etc.)

Parallel Execution Examples

Example 1: Setup Phase (All Parallel)

# Launch all setup tasks together (different files):
Task T002: "Setup unified error codes in pkg/errors/codes.go"
Task T003: "Setup custom error types in pkg/errors/errors.go"
Task T004: "Setup unified response structure in pkg/response/response.go"
Task T005: "Setup response code constants in pkg/response/codes.go"
Task T006: "Setup business constants in pkg/constants/constants.go"
Task T007: "Setup Redis key generation functions in pkg/constants/redis.go"

Example 2: User Story Tests (Parallel within Story)

# US6 unit tests - all can run in parallel:
Task T061: "Unit test for TokenValidator with valid token"
Task T062: "Unit test for expired/invalid token"
Task T063: "Unit test for Redis unavailable"
Task T064: "Unit test for context timeout"

# US6 integration tests - all can run in parallel:
Task T065: "Integration test with valid token"
Task T066: "Integration test for missing token"
Task T067: "Integration test for invalid token"
Task T068: "Integration test for Redis down"

Example 3: Independent User Stories (After Foundation)

# After Phase 2 completes, these can all start in parallel:
Agent 1: Work on US1 (Config Hot Reload) - T018 through T025
Agent 2: Work on US2 (Logging) - T026 through T033
Agent 3: Work on US3 (Response Format) - T034 through T042
Agent 4: Work on US5 (Error Recovery) - T052 through T060

Implementation Strategy

MVP First (Minimum Viable Product)

Recommendation: Complete Phases 1-5 (Setup + Foundation + US1 + US2 + US3) for MVP

This delivers:

  • Configuration hot reload (US1)
  • Production logging (US2)
  • API response consistency (US3)

Then deploy and validate before adding authentication and other features.

Incremental Delivery Roadmap

  1. Foundation (Phases 1-2): ~2-3 days

    • Setup + Foundational infrastructure
    • Deliverable: Basic Fiber app with config, logging, response structure

  2. MVP (Phases 3-5): ~2-3 days

    • US1: Config hot reload
    • US2: Logging with rotation
    • US3: Unified responses
    • Deliverable: Production-ready foundation with observability

  3. Observability+ (Phases 6-7): ~2-3 days

    • US4: Request tracing
    • US5: Error recovery
    • Deliverable: Complete observability and fault tolerance

  4. Security (Phase 8): ~2-3 days

    • US6: Authentication
    • Deliverable: Secured API with Redis token validation

  5. Production Hardening (Phases 9-10): ~2-3 days

    • US7: Rate limiting (optional)
    • Polish and quality gates
    • Deliverable: Production-ready system

Total Estimated Time: 10-15 days (single developer)

Parallel Team Strategy

With 3 developers after Foundation completes:

  • Dev A: US1 + US2 (Config + Logging) - Core infrastructure
  • Dev B: US3 + US4 (Response + Tracing) - API foundation
  • Dev C: US5 + US6 (Recovery + Auth) - Reliability + Security

Then converge for US7 and Polish.

Estimated Time with Parallel Work: 7-10 days

Task Summary

  • Total Tasks: 127 (updated: added T012a for environment config testing, T095a for rate-limiting.md documentation, consolidated code quality checks from 4 tasks into 3 tasks)
  • Setup Phase: 7 tasks
  • Foundational Phase: 11 tasks (BLOCKING) - includes T012a
  • User Story 1 (Config): 8 tasks (3 tests + 5 implementation)
  • User Story 2 (Logging): 8 tasks (3 tests + 5 implementation)
  • User Story 3 (Response): 9 tasks (3 tests + 6 implementation)
  • User Story 4 (Tracing): 9 tasks (3 tests + 6 implementation)
  • User Story 5 (Recovery): 9 tasks (3 tests + 6 implementation)
  • User Story 6 (Auth): 21 tasks (8 tests + 13 implementation)
  • User Story 7 (Rate Limit): 10 tasks (3 tests + 7 implementation)
  • Polish Phase: 35 tasks (documentation, quality, security) - includes T095a, consolidated code quality checks

Parallelizable Tasks: 47 tasks marked [P] (added T012a, T095a)

Test Coverage:

  • Unit tests: 24 tasks (added T012a)
  • Integration tests: 18 tasks
  • Total test tasks: 42 (33% of all tasks)

Constitution Compliance:

  • ✅ All tasks follow Handler → Service → Store → Model pattern
  • ✅ All Redis keys use generation functions (no hardcoded strings)
  • ✅ All responses use unified format
  • ✅ All error codes centralized
  • ✅ Go idiomatic patterns (no Java-style anti-patterns)
  • ✅ Explicit error handling throughout
  • ✅ Context usage for timeouts and cancellation

Next Steps

  1. ✅ Tasks.md generated and validated
  2. ⏳ Review task list with team
  3. ⏳ Set up development environment (Go 1.25.1, Redis 7.x)
  4. ⏳ Run /speckit.implement to begin implementation
  5. ⏳ Start with Phase 1 (Setup) - all tasks can run in parallel

Ready for Implementation: Yes - all tasks are specific, have file paths, and follow constitution principles.

Reference in New Issue View Git Blame Copy Permalink