134 lines
6 KiB
Markdown
134 lines
6 KiB
Markdown
# Word of Wisdom Server - Implementation Plan
|
|
|
|
## Phase 1: Proof of Work Package Implementation
|
|
**Goal**: Create standalone, testable PoW package with HMAC-signed stateless challenges
|
|
|
|
- [X] **Project Setup**
|
|
- [X] Initialize Go module and basic project structure
|
|
- [X] Create PoW challenge structure and types
|
|
- [X] Set up testing framework and utilities
|
|
|
|
- [X] **Challenge Generation & HMAC Security**
|
|
- [X] Implement HMAC-signed challenge generation (stateless)
|
|
- [X] Create challenge authenticity verification
|
|
- [X] Add timestamp validation for replay protection (5 minutes TTL)
|
|
- [X] Implement canonical challenge field ordering for HMAC
|
|
- [X] Add Base64URL encoding for HMAC signatures (JSON handles this)
|
|
- [X] Implement challenge string construction (`quotes:timestamp:difficulty:random`)
|
|
|
|
- [X] **PoW Algorithm Implementation**
|
|
- [X] Implement SHA-256 based PoW solution algorithm
|
|
- [X] Implement leading zero bit counting for difficulty
|
|
- [X] Create nonce iteration and solution finding
|
|
- [X] Add difficulty scaling (3-10 bits range)
|
|
- [X] Create challenge string format: `quotes:timestamp:difficulty:random:nonce`
|
|
- [X] Implement hash verification for submitted solutions
|
|
|
|
- [X] **Verification & Validation**
|
|
- [X] Create challenge verification logic with HMAC validation
|
|
- [X] Add solution validation against original challenge
|
|
- [X] Test HMAC tamper detection and validation
|
|
- [X] Add difficulty adjustment mechanisms (config-based)
|
|
|
|
- [X] **Testing & Performance**
|
|
- [X] Unit tests for challenge generation and verification
|
|
- [X] Unit tests for HMAC signing and validation
|
|
- [X] Unit tests for PoW solution finding and verification
|
|
- [X] Benchmark tests for different difficulty levels
|
|
- [X] Test edge cases (expired challenges, invalid HMAC, wrong difficulty)
|
|
- [X] Performance tests for concurrent challenge operations
|
|
|
|
## Phase 2: Quote Handler
|
|
**Goal**: Simple quote service with public API using resty
|
|
|
|
- [X] Add resty dependency to go.mod
|
|
- [X] Create quote service package
|
|
- [X] Implement quote fetching with HTTP client
|
|
- [X] Add basic error handling
|
|
|
|
## Phase 3: Service Layer Implementation
|
|
**Goal**: Complete service layer with DI for handling requests (untied from TCP presentation)
|
|
|
|
- [X] Create service layer interfaces and contracts
|
|
- [X] Implement quote request service workflow
|
|
- [X] Integrate PoW challenge generation and verification
|
|
- [X] Set up simple dependency wiring
|
|
- [X] Implement full request-response cycle
|
|
- [X] Add comprehensive service layer tests
|
|
- [X] Add error handling and validation
|
|
- [X] Create public concrete WisdomService type
|
|
- [X] Add workflow tests with real PoW implementations
|
|
- [X] Add unsuccessful flow tests for invalid solutions
|
|
|
|
## Phase 4: Binary Protocol Implementation
|
|
- [X] Implement binary message protocol codec with Reader/Writer abstraction
|
|
- [X] Create protocol message types and structures
|
|
- [X] Add message serialization/deserialization (JSON)
|
|
- [X] Implement protocol parsing with proper error handling
|
|
- [X] Create message validation and bounds checking
|
|
- [X] Write unit tests for protocol components
|
|
|
|
## Phase 5: Binary Protocol Reworking & Application Layer Integration
|
|
- [X] Refactor protocol codec into streaming MessageDecoder
|
|
- [X] Implement streaming message processing with io.Reader
|
|
- [X] Create request/response encoding and decoding methods
|
|
- [X] Add comprehensive round-trip testing for protocol validation
|
|
- [X] Update application layer to use streaming Message interface
|
|
- [X] Fix application tests for new protocol design
|
|
|
|
## Phase 6: TCP Server & Connection Management
|
|
- [X] Implement TCP server with connection handling
|
|
- [X] Add dual timeout protection:
|
|
- [X] Connection timeout (max total connection time)
|
|
- [X] Read timeout (max idle time between bytes - slowloris protection)
|
|
- [X] Implement proper connection lifecycle management
|
|
- [X] Create protocol state machine for request/response flow
|
|
- [X] Add graceful connection cleanup and error handling
|
|
- [X] Add slog structured logging to TCP server
|
|
- [X] Implement functional options pattern for server configuration
|
|
- [X] Update cmd/server to use new TCP server with logging
|
|
|
|
## Phase 7: Client Implementation
|
|
- [X] Create client application structure
|
|
- [X] Implement PoW solver algorithm on client side
|
|
- [X] Create client-side protocol implementation
|
|
- [X] Add retry logic and error handling
|
|
- [X] Implement connection management
|
|
- [X] Create CLI interface for client with flag support
|
|
- [X] Add symmetric encode/decode to protocol package for client use
|
|
- [X] Update protocol to use separate connections per request-response
|
|
- [X] Write comprehensive slowloris protection integration tests
|
|
- [X] Verify server successfully handles slow reader attacks
|
|
- [X] Verify server successfully handles slow writer attacks
|
|
- [X] Test end-to-end client-server communication flow
|
|
|
|
## Phase 8: Server Instrumentation & Configuration
|
|
- [X] Add `/metrics` HTTP endpoint for Prometheus collection
|
|
- [X] Add `/debug/pprof` endpoint for performance profiling
|
|
- [X] Create Dockerfile to build server image
|
|
- [X] Implement configuration management using cleanenv library
|
|
- [X] Read configuration from file with environment variable support
|
|
|
|
|
|
## Directory Structure
|
|
```
|
|
/
|
|
├── cmd/
|
|
│ ├── server/ # Server application entry point
|
|
│ └── client/ # Client application entry point
|
|
├── internal/
|
|
│ ├── server/ # Server core logic
|
|
│ ├── protocol/ # Protocol implementation
|
|
│ ├── pow/ # Proof of Work implementation
|
|
│ ├── quotes/ # Quote management
|
|
│ ├── ratelimit/ # Rate limiting & DDOS protection
|
|
│ ├── config/ # Configuration management
|
|
│ ├── metrics/ # Metrics collection
|
|
│ └── logger/ # Structured logging
|
|
├── pkg/ # Public packages
|
|
├── test/ # Integration tests
|
|
├── docker/ # Docker configurations
|
|
├── deployments/ # Deployment configurations
|
|
└── docs/ # Additional documentation
|
|
```
|