diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md new file mode 100644 index 0000000..415bb48 --- /dev/null +++ b/.planning/PROJECT.md @@ -0,0 +1,82 @@ +# Fengling Gateway + +## What This Is + +API Gateway based on YARP (Yet Another Reverse Proxy) for the Fengling microservice ecosystem. Routes incoming requests to downstream services (auth-service, member-service, activity, platform, risk-control, etc.) with multi-tenant support, dynamic configuration, and distributed load balancing. + +## Core Value + +Reliable, scalable API gateway that distributes traffic to backend microservices with zero-downtime configuration updates. + +## Requirements + +### Validated + +- ✓ Multi-tenant routing based on URL path — existing +- ✓ JWT token parsing and tenant claim extraction — existing +- ✓ Dynamic route configuration from PostgreSQL — existing +- ✓ Service discovery integration with Kubernetes — existing +- ✓ Weighted round-robin load balancing — existing +- ✓ Configuration hot-reload via PostgreSQL NOTIFY — existing + +### Active + +- [ ] Implement console-driven configuration management (config changes in fengling-console, gateway listens and reloads) +- [ ] Support multiple gateway instances via broadcast events (multi-instance deployment) +- [ ] Remove K8s health monitoring from gateway (delegate to console) + +### Out of Scope + +- [Direct gateway configuration UI] — Handled by fengling-console +- [K8s service health checks in gateway] — Delegated to console +- [Authentication/Authorization logic] — Handled by auth-service + +## Context + +**Ecosystem Structure:** +``` +fengling-gateway/ # Current project - API Gateway (YARP) + ↓ routes traffic to: +fengling-console/ # Central management console - config, tenant management +fengling-console-web/ # Web UI for console +fengling-auth-service/ # Authentication service +fengling-member-service/ # Member management +fengling-activity/ # Activity service +fengling-platform/ # Platform service +fengling-risk-control/ # Risk control service +fengling-service-discovery/# Service discovery +``` + +**Architecture Decision (New):** +- Gateway configuration managed by fengling-console, not directly +- Console publishes config changes → Gateway subscribes and reloads +- Multi-instance support via broadcast (Redis pub/sub or PostgreSQL NOTIFY) +- Console responsible for all K8s service health monitoring +- Gateway only handles request routing + +**Current Issues (from CONCERNS.md):** +- Hardcoded credentials (security risk) +- JWT token not validated (security risk) +- API endpoints without authentication (security risk) +- Load balancing lock contention +- No unit tests + +## Constraints + +- **Multi-instance**: Gateway must support running multiple instances simultaneously +- **Hot reload**: Configuration changes without restart +- **Tech stack**: .NET 10.0, YARP, PostgreSQL, Redis +- **Deployment**: Docker + Kubernetes + +## Key Decisions + +| Decision | Rationale | Outcome | +|----------|-----------|---------| +| Console-driven config | Centralizes management, single source of truth | ✓ Good | +| Broadcast events for multi-instance | Enables horizontal scaling | ✓ Good | +| Delegate K8s health to console | Reduces gateway complexity, console is ops hub | ✓ Good | +| Keep YARP as core | Well-maintained, Microsoft-supported | ✓ Good | + +--- + +*Last updated: 2026-03-02 after initialization* diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md new file mode 100644 index 0000000..48f33e1 --- /dev/null +++ b/.planning/REQUIREMENTS.md @@ -0,0 +1,90 @@ +# Requirements: Fengling Gateway + +**Defined:** 2026-03-02 +**Core Value:** Reliable, scalable API gateway that distributes traffic to backend microservices with zero-downtime configuration updates. + +## v1 Requirements + +Requirements for initial release. Each maps to roadmap phases. + +### Configuration Management + +- [ ] **CFG-01**: Gateway listens to config change events from fengling-console +- [ ] **CFG-02**: Gateway reloads configuration without restart when notified +- [ ] **CFG-03**: Multi-instance gateway receives config updates via broadcast (Redis pub/sub or PostgreSQL NOTIFY) + +### Multi-Instance Support + +- [ ] **INST-01**: Multiple gateway instances can run simultaneously +- [ ] **INST-02**: Configuration changes propagate to all instances +- [ ] **INST-03**: Redis-based pub/sub for cross-instance communication + +### K8s Health Delegation + +- [ ] **K8S-01**: Remove K8s health monitoring from gateway +- [ ] **K8S-02**: Gateway delegates service health checks to console + +### Security Fixes + +- [ ] **SEC-01**: Remove hardcoded credentials from source code +- [ ] **SEC-02**: Implement proper JWT token validation +- [ ] **SEC-03**: Add authentication to gateway management API endpoints + +### Performance + +- [ ] **PERF-01**: Optimize load balancing lock contention +- [ ] **PERF-02**: Implement incremental route cache updates + +## v2 Requirements + +Deferred to future release. Tracked but not in current roadmap. + +### Observability + +- **OBS-01**: Distributed tracing integration +- **OBS-02**: Custom metrics for gateway performance + +### Testing + +- **TEST-01**: Unit tests for RouteCache +- **TEST-02**: Unit tests for JwtTransformMiddleware +- **TEST-03**: Unit tests for load balancing policy + +## Out of Scope + +| Feature | Reason | +|---------|--------| +| Direct gateway configuration UI | Handled by fengling-console | +| K8s service health checks in gateway | Delegated to console | +| Authentication logic in gateway | Handled by auth-service | +| Authorization logic in gateway | Handled by downstream services | + +## Traceability + +Which phases cover which requirements. Updated during roadmap creation. + +| Requirement | Phase | Status | +|-------------|-------|--------| +| CFG-01 | Phase 1 | Pending | +| CFG-02 | Phase 1 | Pending | +| CFG-03 | Phase 1 | Pending | +| INST-01 | Phase 1 | Pending | +| INST-02 | Phase 1 | Pending | +| INST-03 | Phase 1 | Pending | +| K8S-01 | Phase 2 | Pending | +| K8S-02 | Phase 2 | Pending | +| SEC-01 | Phase 3 | Pending | +| SEC-02 | Phase 3 | Pending | +| SEC-03 | Phase 3 | Pending | +| PERF-01 | Phase 4 | Pending | +| PERF-02 | Phase 4 | Pending | + +**Coverage:** +- v1 requirements: 12 total +- Mapped to phases: 12 +- Unmapped: 0 ✓ + +--- + +*Requirements defined: 2026-03-02* +*Last updated: 2026-03-02 after initial definition* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..7fd1f3b --- /dev/null +++ b/.planning/ROADMAP.md @@ -0,0 +1,106 @@ +# Roadmap: Fengling Gateway + +**Created:** 2026-03-02 +**Core Value:** Reliable, scalable API gateway that distributes traffic to backend microservices with zero-downtime configuration updates. + +--- + +## Phase 1: Console-Driven Configuration & Multi-Instance Support + +**Goal:** Implement console-driven configuration management and multi-instance support. + +**Requirements:** +- CFG-01: Gateway listens to config change events from fengling-console +- CFG-02: Gateway reloads configuration without restart when notified +- CFG-03: Multi-instance gateway receives config updates via broadcast +- INST-01: Multiple gateway instances can run simultaneously +- INST-02: Configuration changes propagate to all instances +- INST-03: Redis-based pub/sub for cross-instance communication + +**Success Criteria:** +1. Gateway can subscribe to config change events from console +2. Configuration reload works without gateway restart +3. Multiple gateway instances stay synchronized +4. Broadcast events reach all instances within 5 seconds + +--- + +## Phase 2: K8s Health Delegation + +**Goal:** Remove K8s health monitoring from gateway, delegate to console. + +**Requirements:** +- K8S-01: Remove K8s health monitoring from gateway +- K8S-02: Gateway delegates service health checks to console + +**Success Criteria:** +1. KubernetesPendingSyncService is deprecated/removed from gateway +2. Health check logic moved to console project +3. Gateway only performs request routing, not health monitoring + +--- + +## Phase 3: Security Hardening + +**Goal:** Fix critical security vulnerabilities. + +**Requirements:** +- SEC-01: Remove hardcoded credentials from source code +- SEC-02: Implement proper JWT token validation +- SEC-03: Add authentication to gateway management API endpoints + +**Success Criteria:** +1. No hardcoded passwords/secrets in source code +2. JWT tokens are validated (signature, expiration, issuer, audience) +3. All /api/gateway/* endpoints require authentication + +--- + +## Phase 4: Performance Optimization + +**Goal:** Optimize gateway performance under high load. + +**Requirements:** +- PERF-01: Optimize load balancing lock contention +- PERF-02: Implement incremental route cache updates + +**Success Criteria:** +1. Load balancing does not require per-request Redis lock +2. Route cache updates are incremental, not full reload +3. Gateway handles 10x more requests per second + +--- + +## Phase 5: Observability & Testing + +**Goal:** Add observability and test coverage. + +**Requirements:** +- OBS-01: Distributed tracing integration +- OBS-02: Custom metrics for gateway performance +- TEST-01: Unit tests for RouteCache +- TEST-02: Unit tests for JwtTransformMiddleware +- TEST-03: Unit tests for load balancing policy + +**Success Criteria:** +1. Distributed traces include gateway spans +2. Key metrics are exported (request count, latency, error rate) +3. Core components have >80% test coverage + +--- + +## Roadmap Summary + +| Phase | Name | Requirements | Status | +|-------|------|--------------|--------| +| 1 | Console-Driven Config & Multi-Instance | 6 | Not planned | +| 2 | K8s Health Delegation | 2 | Not planned | +| 3 | Security Hardening | 3 | Not planned | +| 4 | Performance Optimization | 2 | Not planned | +| 5 | Observability & Testing | 5 | Not planned | + +**Total:** 5 phases | 18 requirements | All covered ✓ + +--- + +*Last updated: 2026-03-02 after roadmap creation* diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 0000000..7ead9ec --- /dev/null +++ b/.planning/STATE.md @@ -0,0 +1,75 @@ +# State: Fengling Gateway + +**Last Updated:** 2026-03-02 + +--- + +## Project Reference + +See: .planning/PROJECT.md (updated 2026-03-02) + +**Core value:** Reliable, scalable API gateway that distributes traffic to backend microservices with zero-downtime configuration updates. + +**Current focus:** Phase 1: Console-Driven Configuration & Multi-Instance Support + +--- + +## Project State + +| Item | Status | +|------|--------| +| PROJECT.md | ✓ Initialized | +| config.json | ✓ Created | +| Requirements | ✓ Defined (18 requirements) | +| Roadmap | ✓ Created (5 phases) | +| Research | Not started (auto mode skipped) | + +--- + +## Phase Status + +| Phase | Name | Status | Plans | Progress | +|-------|------|--------|-------|----------| +| 1 | Console-Driven Config & Multi-Instance | Not planned | 0 | 0% | +| 2 | K8s Health Delegation | Not planned | 0 | 0% | +| 3 | Security Hardening | Not planned | 0 | 0% | +| 4 | Performance Optimization | Not planned | 0 | 0% | +| 5 | Observability & Testing | Not planned | 0 | 0% | + +--- + +## Accumulated Context + +### Initialization + +- **2026-03-02:** Project initialized via /gsd-new-project --auto +- Brownfield project with existing codebase (ARCHITECTURE.md, CONCERNS.md, STACK.md existed) +- User provided context: gateway architecture discussion with focus on console-driven config + +### Key Decisions + +| Decision | Date | Notes | +|----------|------|-------| +| Console-driven config | 2026-03-02 | Config changes in fengling-console, gateway listens | +| Multi-instance via broadcast | 2026-03-02 | Redis pub/sub or PostgreSQL NOTIFY | +| K8s health delegation | 2026-03-02 | Console handles K8s health, not gateway | + +### Roadmap Evolution + +- Phase 1 added: Console-Driven Configuration & Multi-Instance Support +- Phase 2 added: K8s Health Delegation +- Phase 3 added: Security Hardening +- Phase 4 added: Performance Optimization +- Phase 5 added: Observability & Testing + +--- + +## Notes + +- Auto mode: research skipped, workflow preferences set to yolo +- Config changes should be committed to git (commit_docs: true) +- gsd-tools.cjs not available - project structure created manually + +--- + +*Last updated: 2026-03-02 after initialization* diff --git a/.planning/config.json b/.planning/config.json new file mode 100644 index 0000000..8014a86 --- /dev/null +++ b/.planning/config.json @@ -0,0 +1,13 @@ +{ + "mode": "yolo", + "depth": "standard", + "parallelization": true, + "commit_docs": true, + "model_profile": "balanced", + "workflow": { + "research": false, + "plan_check": false, + "verifier": false, + "auto_advance": true + } +}