# 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*