feat: add strategy support to lite mode

[BorisP1234]

Overview

Add comprehensive load balancing strategies to Gate Lite mode, enabling intelligent traffic distribution across multiple backend servers.

Co-authored-by: @okeanosthedev
Co-authored-by: @robinbraemer

Features Added

Load Balancing Strategies

• Random (default): Secure random backend selection
• Round-Robin: Fair sequential distribution across backends
• Least-Connections: Performance-optimized routing to least-loaded servers
• Lowest-Latency: Latency-optimized routing based on status ping measurements

Configuration

lite:
  routes:
    - host: play.example.com
      backend: [server1:25565, server2:25565, server3:25565]
      strategy: least-connections  # NEW: Load balancing strategy

Major Improvements Made

Architecture Refactoring (Addressed Review Feedback)

Problem: Original implementation used global state variables that would break multiple Gate instances.

Solution: Complete architecture overhaul

• Eliminated all global variables (roundRobinIndex, leastConnectionCounter, latencyCache)
• Created Lite struct to encapsulate all lite mode functionality
• Per-instance StrategyManager for isolated state management
• Removed unnecessary proxy ID complexity

// Before: Global state (broken)
var roundRobinIndex sync.Map  // Shared across instances

// After: Per-instance state (clean)  
type Proxy struct {
    lite *lite.Lite  // Instance-isolated
}

Performance Optimizations

Problem: Aggressive health checking was causing 25+ second delays.

Solution: Smart lazy failure detection

• Removed blocking checkBackend() - eliminated 5-second TCP timeouts per backend
• Immediate strategy selection - strategies return instantly
• Natural failure handling - tryBackends handles failures efficiently
• Up to 25+ second performance improvement for routes with multiple backends

Better Latency Measurement

Problem: Using dial time for latency measurement was inaccurate.

Solution: Status ping latency measurement

• Moved from dial time to status ping time - more representative of server performance
• Measures full Minecraft server response instead of just connection setup
• Feeds into lowest-latency strategy for accurate routing decisions
• 3-minute intelligent caching of latency measurements

Thread Safety Improvements

Problem: Race conditions in connection counting.

Solution: Proper atomic operations

• Atomic counters for least-connections strategy
• Thread-safe state management across all strategies
• Proper increment/decrement on connection establishment/teardown
• Race condition elimination verified with go test -race

Type Safety

Problem: Strategy configuration used plain strings.

Solution: Typed constants with validation

• Strategy type instead of plain strings
• Const definitions with proper documentation
• Better IDE support and code completion
• Enhanced validation with detailed error messages

Professional Documentation

Problem: Basic documentation with incorrect grammar.

Solution: Comprehensive professional guide

• Complete strategy guide with comparison table and algorithms
• Real-world examples - gaming networks, development environments
• Performance characteristics explained for each strategy
• Professional tone - cleaned up excessive emojis
• Configuration links in config.yml and config-lite.yml

Technical Details

Strategy Selection Flow

1. Strategy configured → StrategyManager.GetNextBackend() called
2. Immediate backend selection → No blocking health checks
3. Connection attempt → tryBackends handles actual dialing
4. Success → Connection established, metrics updated
5. Failure → Automatically retry next backend

Connection Tracking (Least-Connections)

• Increment: counter.Add(1) when connection established
• Decrement: defer counter.Add(^uint32(0)) when connection closes
• Thread-safe: Atomic operations prevent race conditions
• Real-time: Instant updates for accurate load balancing

Latency Measurement (Lowest-Latency)

• Measurement: Status ping response time (not dial time)
• Caching: 3-minute TTL for latency data
• Learning: Automatically adapts to changing network conditions
• Accuracy: Full Minecraft server response measurement

Testing

• Comprehensive test suite for all strategies and configuration validation
• Instance isolation tests - verify multi-instance support
• Atomic counter tests - verify thread-safe increment/decrement
• Type safety tests - validate Strategy constants and config parsing
• Performance verified - no blocking operations in critical path

Breaking Changes

None - All changes are backward compatible. Existing configurations continue to work with random strategy as default.

Migration

No migration required - new strategy field is optional and defaults to random behavior.

# Before (still works)  
lite:
  routes:
    - host: example.com
      backend: [server1, server2]
      
# After (enhanced)
lite:
  routes:
    - host: example.com
      backend: [server1, server2]
      strategy: least-connections  # NEW: Optional load balancing

[okeanosthedev]

For the second issue, I used it myself and made sure all were working. You sure the count isn't working correctly?

[BorisP1234]

For the second issue, I used it myself and made sure all were working. You sure the count isn't working correctly?

It does work and it correctly sends connections to the backend with the lowest connection count. But when a player disconnects from the backend, the count is not updated, so the proxy still thinks there are players there and it will send connections to a backend which may have actually more players.

[BorisP1234]

I also changed it so instead of having a connection counted when it gives the backend with the least connections, it counts whenever a connection is forwarded and a player actually joins.

[okeanosthedev]

Pretty solid doc and code. Would you be able to send a friend request to my discord for us to further on this case. Discord: okeanosthedev

[BorisP1234]

@okeanosthedev @robinbraemer Should we also cache checking backends? How long should the cache stay?

[okeanosthedev]

@okeanosthedev @robinbraemer Should we also cache checking backends? How long should the cache stay?

I don't think it is needed that much, it wont make a significant change.

[BorisP1234]

@robinbraemer although having the check backend logic altered, which is much faster, it does create a couple problems that were fixed before:

1. When the targeted backend is not reachable the console gets spammed with logs.
2. Even though there is a second backend which is reachable, with your implementation it will always choose for the first backend, even though it will fail.
3. It doesn't show the fallback in the ping, when every backend is not reachable.

Maybe there is a better way to handle. A semi way which instead of checking every time per backend, it uses a cache. Or we could use the connection that is created when the backend is checked, instead of ignoring it.

This better, but indeed slower, method could maybe be an extra option in the config, for users that have backends that frequently are not reachable.