Fix Windows 11 port exhaustion issue with fallback port ranges and configurable ranges

[Copilot]

Problem

Windows 11 users were experiencing port allocation failures when starting games:

gabs.games_start({"gameId":"rimworld"})
Failed to start rimworld: failed to create bridge config: failed to find available port: no available ports in range 49152-65535

This occurs because Windows 11 systems with Hyper-V, WSL, Docker, or certain antivirus software reserve large portions of the default ephemeral port range (49152-65535), leaving no available ports for GABS.

Solution

Automatic Port Range Fallback

GABS now automatically tries multiple port ranges when the default range fails:

1. 49152-65535 (Default Windows/IANA ephemeral range)
2. 32768-49151 (Linux ephemeral range)
3. 8000-8999 (Common HTTP alternate ports)
4. 9000-9999 (Common application ports)
5. 10000-19999, 20000-29999, 30000-32767 (Additional safe ranges)

This requires no user configuration and should resolve the issue for most Windows 11 users automatically.

Configurable Port Ranges

For systems with specific port restrictions, users can now set custom port ranges via the GABS_PORT_RANGES environment variable:

# Windows Command Prompt
set GABS_PORT_RANGES=8000-8999,9000-9999
gabs server

# PowerShell
$env:GABS_PORT_RANGES="8000-8999,9000-9999"
gabs server

# Linux/Mac
export GABS_PORT_RANGES="8000-8999,9000-9999"
gabs server

Enhanced Error Messages

When all port ranges are exhausted, users now receive detailed troubleshooting guidance:

no available ports found in any range - this may be due to Windows system restrictions (Hyper-V, WSL, etc.) or firewall settings. Consider: 
1) Checking Windows reserved port ranges with 'netsh int ipv4 show excludedportrange protocol=tcp'
2) Disabling Hyper-V if not needed
3) Configuring your firewall/antivirus
4) Setting GABS_PORT_RANGES environment variable (e.g. 'GABS_PORT_RANGES=8000-8999,9000-9999')

Changes Made

• Core Logic: Modified WriteBridgeJSON() in internal/config/bridgecfg.go to use findAvailablePortWithFallback() instead of single range allocation
• Environment Support: Added getCustomPortRanges() function to parse GABS_PORT_RANGES environment variable
• Documentation: Created comprehensive docs/WINDOWS_TROUBLESHOOTING.md guide and updated README
• Testing: Added comprehensive tests for fallback logic, custom range parsing, and environment variable handling

Backward Compatibility

This change is fully backward compatible:

• Existing functionality is preserved
• No breaking changes to APIs or configuration
• Default behavior improved without requiring user action
• All existing tests continue to pass

Testing

The fix has been thoroughly tested with:

• Default fallback ranges on multiple systems
• Custom single and multiple port ranges
• Invalid configuration handling
• Environment variable parsing edge cases
• Concurrent port allocation scenarios

Windows 11 users should no longer experience port availability issues when starting games through GABS.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.