hash-of-wisdom/docs/IMPLEMENTATION.md

Word of Wisdom Server - Implementation Plan

Phase 1: Proof of Work Package Implementation

Goal: Create standalone, testable PoW package with HMAC-signed stateless challenges

• Project Setup

  • Initialize Go module and basic project structure
  • Create PoW challenge structure and types
  • Set up testing framework and utilities

• Challenge Generation & HMAC Security

  • Implement HMAC-signed challenge generation (stateless)
  • Create challenge authenticity verification
  • Add timestamp validation for replay protection (5 minutes TTL)
  • Implement canonical challenge field ordering for HMAC
  • Add Base64URL encoding for HMAC signatures (JSON handles this)
  • Implement challenge string construction (quotes:timestamp:difficulty:random)

• PoW Algorithm Implementation

  • Implement SHA-256 based PoW solution algorithm
  • Implement leading zero bit counting for difficulty
  • Create nonce iteration and solution finding
  • Add difficulty scaling (3-10 bits range)
  • Create challenge string format: quotes:timestamp:difficulty:random:nonce
  • Implement hash verification for submitted solutions

• Verification & Validation

  • Create challenge verification logic with HMAC validation
  • Add solution validation against original challenge
  • Test HMAC tamper detection and validation
  • Add difficulty adjustment mechanisms (config-based)

• Testing & Performance

  • Unit tests for challenge generation and verification
  • Unit tests for HMAC signing and validation
  • Unit tests for PoW solution finding and verification
  • Benchmark tests for different difficulty levels
  • Test edge cases (expired challenges, invalid HMAC, wrong difficulty)
  • Performance tests for concurrent challenge operations

Phase 2: Quote Handler

Goal: Simple quote service with public API using resty

• Add resty dependency to go.mod
• Create quote service package
• Implement quote fetching with HTTP client
• Add basic error handling

Phase 3: Service Layer Implementation

Goal: Complete service layer with DI for handling requests (untied from TCP presentation)

• Create service layer interfaces and contracts
• Implement quote request service workflow
• Integrate PoW challenge generation and verification
• Set up simple dependency wiring
• Implement full request-response cycle
• Add comprehensive service layer tests
• Add error handling and validation
• Create public concrete WisdomService type
• Add workflow tests with real PoW implementations
• Add unsuccessful flow tests for invalid solutions

Phase 4: Binary Protocol Implementation

• Implement binary message protocol codec with Reader/Writer abstraction
• Create protocol message types and structures
• Add message serialization/deserialization (JSON)
• Implement protocol parsing with proper error handling
• Create message validation and bounds checking
• Write unit tests for protocol components

Phase 5: Binary Protocol Reworking & Application Layer Integration

• Refactor protocol codec into streaming MessageDecoder
• Implement streaming message processing with io.Reader
• Create request/response encoding and decoding methods
• Add comprehensive round-trip testing for protocol validation
• Update application layer to use streaming Message interface
• Fix application tests for new protocol design

Phase 6: TCP Server & Connection Management

• Implement TCP server with connection handling
• Add dual timeout protection:
  • Connection timeout (max total connection time)
  • Read timeout (max idle time between bytes - slowloris protection)
• Implement proper connection lifecycle management
• Create protocol state machine for request/response flow
• Add graceful connection cleanup and error handling
• Add slog structured logging to TCP server
• Implement functional options pattern for server configuration
• Update cmd/server to use new TCP server with logging

Phase 7: Client Implementation

• Create client application structure
• Implement PoW solver algorithm on client side
• Create client-side protocol implementation
• Add retry logic and error handling
• Implement connection management
• Create CLI interface for client with flag support
• Add symmetric encode/decode to protocol package for client use
• Update protocol to use separate connections per request-response
• Write comprehensive slowloris protection integration tests
• Verify server successfully handles slow reader attacks
• Verify server successfully handles slow writer attacks
• Test end-to-end client-server communication flow

Phase 8: Server Instrumentation & Configuration

• Add /metrics HTTP endpoint for Prometheus collection
• Add /debug/pprof endpoint for performance profiling
• Create Dockerfile to build server image
• Implement configuration management using cleanenv library
• 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