Update README.md

README.md

@@ -11,6 +11,7 @@ The Hash of Wisdom server requires clients to solve computational puzzles (proof
 ### Prerequisites
 - Go 1.24.3+
 - Docker (optional)
+- [Task](https://taskfile.dev/) (optional, but recommended)
 
 ### Building
 ```bash
@@ -22,6 +23,29 @@ go build -o client ./cmd/client
 ```
 
 ### Running
+
+#### Using Task (Recommended)
+```bash
+# Most useful command - run all checks
+task check
+
+# Start server
+task server -- -config config.yaml
+
+# Connect client
+task client -- --addr=localhost:8080
+
+# Run tests
+task test
+
+# See coverage
+task test-coverage
+
+# See all available commands
+task --list
+```
+
+#### Manual Commands
 ```bash
 # Start server (uses config.yaml by default)
 ./hash-of-wisdom
@@ -31,6 +55,9 @@ go build -o client ./cmd/client
 
 # Connect with client
 ./client -addr localhost:8080
+
+# Run tests
+go test ./...
 ```
 
 ### Using Docker
@@ -50,38 +77,10 @@ docker run -p 8080:8080 -p 8081:8081 hash-of-wisdom
 
 ### Protocol & Implementation
 - [Protocol Specification](docs/PROTOCOL.md) - Binary protocol definition
+- [PoW Algorithm Analysis](docs/POW_ANALYSIS.md) - Algorithm selection rationale and comparison
 - [Implementation Plan](docs/IMPLEMENTATION.md) - Development phases and progress
 - [Package Structure](docs/PACKAGES.md) - Code organization and package responsibilities
 - [Architecture Choices](docs/ARCHITECTURE.md) - Design decisions and patterns
 
 ### Production Readiness
 - [Production Readiness Guide](docs/PRODUCTION_READINESS.md) - Requirements for production deployment
-
-## Algorithm Choice
-
-The server uses **SHA-256 based proof-of-work** with leading zero bits difficulty:
-- **Why SHA-256**: Cryptographically secure, well-tested, hardware-optimized
-- **Leading Zero Bits**: Simple difficulty scaling, easy verification
-- **HMAC Authentication**: Prevents challenge tampering and replay attacks
-- **Configurable Difficulty**: Adaptive to different threat levels (4-30 bits)
-
-This approach provides strong DDoS protection while remaining computationally reasonable for legitimate clients.
-
-## Current Status
-
-✅ **Complete**: Core functionality, TCP server, client, metrics, containerization  
-🔄 **In Progress**: Documentation (Phase 9)  
-📋 **Planned**: See [Production Readiness Guide](docs/PRODUCTION_READINESS.md) for production deployment requirements
-
-## Testing
-
-```bash
-# Run all tests
-go test ./...
-
-# Run integration tests
-go test ./test/integration/...
-
-# Benchmarks
-go test -bench=. ./internal/pow/...
-```

Taskfile.yml

@@ -93,3 +93,41 @@ tasks:
     desc: Alias for cpu-burner
     cmds:
       - task: cpu-burner
+
+  server:
+    desc: Build and run the server
+    cmds:
+      - go build -o hash-of-wisdom ./cmd/server
+      - ./hash-of-wisdom {{.CLI_ARGS}}
+
+  server-config:
+    desc: Build and run the server with custom config
+    cmds:
+      - go build -o hash-of-wisdom ./cmd/server
+      - ./hash-of-wisdom -config {{.CONFIG | default "config.yaml"}}
+
+  client:
+    desc: Build and run the client
+    cmds:
+      - go build -o client ./cmd/client
+      - ./client {{.CLI_ARGS | default "-addr localhost:8080"}}
+
+  docker-build:
+    desc: Build Docker image
+    cmds:
+      - docker build -t hash-of-wisdom .
+
+  docker-run:
+    desc: Run Docker container
+    cmds:
+      - docker run -p 8080:8080 -p 8081:8081 hash-of-wisdom
+
+  metrics:
+    desc: Check metrics endpoint
+    cmds:
+      - curl -s http://localhost:8081/metrics
+
+  integration:
+    desc: Run integration tests only
+    cmds:
+      - go test -v ./test/integration/...

internal/protocol/requests.go

@@ -7,7 +7,6 @@ import (
 	"hash-of-wisdom/internal/pow/challenge"
 )
 
-
 // ChallengeRequest is empty (no payload for challenge requests)
 type ChallengeRequest struct{}
 

internal/protocol/responses.go

@@ -8,7 +8,6 @@ import (
 	"hash-of-wisdom/internal/quotes"
 )
 
-
 // ChallengeResponse represents a challenge response
 type ChallengeResponse struct {
 	Challenge *challenge.Challenge

internal/protocol/roundtrip_test.go

@@ -113,7 +113,6 @@ func TestChallengeRequest_EmptyPayload(t *testing.T) {
 	require.NoError(t, err)
 }
 
-
 func TestPayloadStream_LimitedRead(t *testing.T) {
 	decoder := NewMessageDecoder()
 

internal/server/tcp.go

@@ -30,7 +30,6 @@ type TCPServer struct {
 // Option is a functional option for configuring TCPServer
 type option func(*TCPServer)
 
-
 // WithLogger sets a custom logger
 func WithLogger(logger *slog.Logger) option {
 	return func(s *TCPServer) {
@@ -54,7 +53,6 @@ func NewTCPServer(wisdomService *service.WisdomService, config *Config, opts ...
 	return server
 }
 
-
 // Start starts the TCP server
 func (s *TCPServer) Start(ctx context.Context) error {
 	listener, err := net.Listen("tcp", s.config.Address)

test/integration/helpers_test.go

@@ -0,0 +1,56 @@
+package integration
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"hash-of-wisdom/internal/lib/sl"
+	"hash-of-wisdom/internal/pow/challenge"
+	"hash-of-wisdom/internal/quotes"
+	"hash-of-wisdom/internal/server"
+	"hash-of-wisdom/internal/service"
+
+	"github.com/stretchr/testify/require"
+)
+
+// testQuoteService provides static quotes for testing
+type testQuoteService struct{}
+
+func (s *testQuoteService) GetRandomQuote(ctx context.Context) (*quotes.Quote, error) {
+	return &quotes.Quote{
+		Text:   "Test quote for integration testing",
+		Author: "Test Author",
+	}, nil
+}
+
+func setupTestServerWithConfig(t *testing.T, serverConfig *server.Config) *server.TCPServer {
+	// Create test components
+	challengeConfig := challenge.TestConfig()
+	generator := challenge.NewGenerator(challengeConfig)
+	verifier := challenge.NewVerifier(challengeConfig)
+
+	// Create a simple test quote service
+	quoteService := &testQuoteService{}
+
+	// Wire up service
+	genAdapter := service.NewGeneratorAdapter(generator)
+	wisdomService := service.NewWisdomService(genAdapter, verifier, quoteService)
+
+	// Create server with custom config using functional options
+	logger := sl.NewMockLogger()
+	srv := server.NewTCPServer(wisdomService, serverConfig,
+		server.WithLogger(logger))
+
+	// Start server
+	ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
+	defer cancel()
+
+	err := srv.Start(ctx)
+	require.NoError(t, err)
+
+	// Give server time to start
+	time.Sleep(100 * time.Millisecond)
+
+	return srv
+}

test/integration/slowloris_test.go

@@ -5,7 +5,6 @@ import (
 	"testing"
 	"time"
 
-	"hash-of-wisdom/internal/protocol"
 	"hash-of-wisdom/internal/server"
 
 	"github.com/stretchr/testify/assert"
@@ -48,43 +47,6 @@ func TestSlowlorisProtection_SlowReader(t *testing.T) {
 	assert.Error(t, err, "Connection should be closed due to slow reading")
 }
 
-func TestSlowlorisProtection_SlowWriter(t *testing.T) {
-	// Setup server with very short write timeout for testing
-	serverConfig := &server.Config{
-		Address:  ":0",
-		Timeouts: server.TimeoutConfig{
-			Read:       5 * time.Second,
-			Write:      100 * time.Millisecond,
-			Connection: 15 * time.Second,
-		},
-	}
-
-	srv := setupTestServerWithConfig(t, serverConfig)
-	defer srv.Stop()
-
-	// Connect to server but don't read responses (simulate slow writer client)
-	conn, err := net.Dial("tcp", srv.Address())
-	require.NoError(t, err)
-	defer conn.Close()
-
-	// Send a complete challenge request
-	challengeReq := &protocol.ChallengeRequest{}
-	err = challengeReq.Encode(conn)
-	require.NoError(t, err)
-
-	// Don't read the response - this should trigger write timeout
-	time.Sleep(200 * time.Millisecond)
-
-	// Try to write again - connection should be timed out
-	_, err = conn.Write([]byte{0x01})
-
-	// Verify connection is closed
-	buffer := make([]byte, 1024)
-	conn.SetReadDeadline(time.Now().Add(500 * time.Millisecond))
-	_, err = conn.Read(buffer)
-	assert.Error(t, err, "Connection should be closed due to slow writing")
-}
-
 func TestSlowlorisProtection_SlowConnectionTimeout(t *testing.T) {
 	// Setup server with very short connection timeout for testing
 	serverConfig := &server.Config{
@@ -150,86 +112,3 @@ func TestSlowlorisProtection_MultipleSlowClients(t *testing.T) {
 		conn.Close()
 	}
 }
-
-func TestSlowlorisProtection_AttackMitigation(t *testing.T) {
-	// Test that server can still serve legitimate clients during an attack
-	serverConfig := &server.Config{
-		Address:  ":0",
-		Timeouts: server.TimeoutConfig{
-			Read:       500 * time.Millisecond,
-			Write:      500 * time.Millisecond,
-			Connection: 1 * time.Second,
-		},
-	}
-
-	srv := setupTestServerWithConfig(t, serverConfig)
-	defer srv.Stop()
-
-	// Start slowloris attack - multiple slow connections
-	var attackConnections []net.Conn
-	for i := 0; i < 3; i++ {
-		conn, err := net.Dial("tcp", srv.Address())
-		require.NoError(t, err)
-		attackConnections = append(attackConnections, conn)
-		// Send partial data
-		conn.Write([]byte{0x01})
-	}
-
-	// Meanwhile, legitimate client should still work
-	legitimateConn, err := net.Dial("tcp", srv.Address())
-	require.NoError(t, err)
-	defer legitimateConn.Close()
-
-	// Send complete request quickly
-	challengeReq := &protocol.ChallengeRequest{}
-	err = challengeReq.Encode(legitimateConn)
-	require.NoError(t, err)
-
-	// Should receive response despite ongoing attack
-	decoder := protocol.NewMessageDecoder()
-	msg, err := decoder.Decode(legitimateConn)
-	assert.NoError(t, err)
-	assert.Equal(t, protocol.ChallengeResponseType, msg.Type)
-
-	// Clean up attack connections
-	for _, conn := range attackConnections {
-		conn.Close()
-	}
-}
-
-func TestSlowlorisProtection_SlowChunkReading(t *testing.T) {
-	// Test protection against clients that read responses very slowly
-	serverConfig := &server.Config{
-		Address:  ":0",
-		Timeouts: server.TimeoutConfig{
-			Read:       5 * time.Second,
-			Write:      200 * time.Millisecond,
-			Connection: 10 * time.Second,
-		},
-	}
-
-	srv := setupTestServerWithConfig(t, serverConfig)
-	defer srv.Stop()
-
-	// Connect and send valid request
-	conn, err := net.Dial("tcp", srv.Address())
-	require.NoError(t, err)
-	defer conn.Close()
-
-	challengeReq := &protocol.ChallengeRequest{}
-	err = challengeReq.Encode(conn)
-	require.NoError(t, err)
-
-	// Read only first byte of response very slowly
-	buffer := make([]byte, 1)
-	_, err = conn.Read(buffer)
-	require.NoError(t, err)
-
-	// Wait longer than write timeout before reading more
-	time.Sleep(300 * time.Millisecond)
-
-	// Try to read more - connection should be closed due to slow reading
-	conn.SetReadDeadline(time.Now().Add(500 * time.Millisecond))
-	_, err = conn.Read(buffer)
-	assert.Error(t, err, "Connection should be closed due to slow chunk reading")
-}

test/integration/timeout_test.go

@@ -1,18 +1,12 @@
 package integration
 
 import (
-	"context"
 	"net"
 	"testing"
 	"time"
 
-	"hash-of-wisdom/internal/config"
-	"hash-of-wisdom/internal/lib/sl"
-	"hash-of-wisdom/internal/pow/challenge"
 	"hash-of-wisdom/internal/protocol"
-	"hash-of-wisdom/internal/quotes"
 	"hash-of-wisdom/internal/server"
-	"hash-of-wisdom/internal/service"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -55,7 +49,6 @@ func TestTCPServer_TimeoutProtection_SlowReader(t *testing.T) {
 
 func TestTCPServer_TimeoutProtection_ConnectionTimeout(t *testing.T) {
 	// Setup server with very short connection timeout
-	_ = config.Load
 	serverConfig := &server.Config{
 		Address: ":0",
 		Timeouts: server.TimeoutConfig{
@@ -105,7 +98,6 @@ func TestTCPServer_NormalOperation_WithinTimeouts(t *testing.T) {
 }
 
 func TestTCPServer_MultipleConnections_IndependentTimeouts(t *testing.T) {
-	_ = config.Load
 	serverConfig := &server.Config{
 		Address: ":0",
 		Timeouts: server.TimeoutConfig{
@@ -167,43 +159,3 @@ func setupTestServer(t *testing.T) *server.TCPServer {
 }
 
 // Helper function to create test server with custom config
-func setupTestServerWithConfig(t *testing.T, serverConfig *server.Config) *server.TCPServer {
-	// Create test components
-	challengeConfig := challenge.TestConfig()
-	generator := challenge.NewGenerator(challengeConfig)
-	verifier := challenge.NewVerifier(challengeConfig)
-
-	// Create a simple test quote service
-	quoteService := &testQuoteService{}
-
-	// Wire up service
-	genAdapter := service.NewGeneratorAdapter(generator)
-	wisdomService := service.NewWisdomService(genAdapter, verifier, quoteService)
-
-	// Create server with custom config using functional options
-	logger := sl.NewMockLogger()
-	srv := server.NewTCPServer(wisdomService, serverConfig,
-		server.WithLogger(logger))
-
-	// Start server
-	ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
-	defer cancel()
-
-	err := srv.Start(ctx)
-	require.NoError(t, err)
-
-	// Give server time to start
-	time.Sleep(100 * time.Millisecond)
-
-	return srv
-}
-
-// testQuoteService provides test quotes
-type testQuoteService struct{}
-
-func (s *testQuoteService) GetRandomQuote(ctx context.Context) (*quotes.Quote, error) {
-	return &quotes.Quote{
-		Text:   "Test quote for integration testing",
-		Author: "Test Author",
-	}, nil
-}