# 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

## Phase 9: Documentation
- [X] Create comprehensive README.md with project overview and quick start
- [X] Document package structure and responsibilities
- [X] Document architecture choices and design decisions
- [X] Update production readiness assessment


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