Tunnely 1.2.0 - Regional Relay Network Update

Release Date: October 1, 2025
Minecraft Version: 1.20.1
Loaders: Fabric, Forge

---

Major Features

Multi-Regional Relay Network

• 3 Global Relay Servers:
  • NA 1 - Atlanta, USA (Serving North & South America)
  • EU 1 - Frankfurt, Germany (Serving Europe, Middle East & Africa)
  • APAC 1 - Singapore (Serving Asia-Pacific)
• Automatic Relay Selection: Measures latency to all relays and connects to the fastest one
• Intelligent Failover: Automatically switches to next-best relay if primary fails
• Zero Configuration: Works out of the box with optimal relay selection

Database-Backed Relay Discovery

• Relay list fetched from central database (with config fallback)
• Dynamic relay updates without client mod updates
• Priority-based relay selection
• Maintenance mode support (relays can be temporarily disabled)

Regional Filtering in Public Lobby

• Region Badges: Each server displays its relay region (🌎 NA, 🌎 EU, 🌎 APAC)
• Dynamic Region Filter: Cycle through regions that have active servers
  • Filter adapts automatically: if SA relay is down, SA option is hidden
  • Filter options: ALL → (detected regions only, sorted alphabetically)
• Status Display: Shows total servers and compatible count

---

UI/UX Improvements

Public Lobbies Screen

• Fixed: "Show only compatible" checkbox now works reliably
  • Instant client-side filtering (no refetch required)
  • Cached server data for responsive toggling
• Fixed: Button unresponsiveness after clicking Refresh
  • Proper focus management on server list
  • UI state properly restored after async load
• Fixed: Concurrent load protection
  • Load-in-progress guard prevents overlapping requests
  • Controls disabled during load, re-enabled on completion
• Improved: Server list layout
  • Increased spacing from bottom controls to prevent click overlap
  • Better visual separation between list and buttons

Compatibility Filtering

• Checkbox toggles instantly without network delay
• Smooth transitions when filtering servers
• Clear visual feedback on filter state

---

Technical Improvements

Relay Server Enhancements

• Configurable Public Endpoint:
  • RELAY_PUBLIC_HOST and RELAY_PUBLIC_PORT environment variables
  • No more hardcoded IPs in source code
  • Easy deployment behind reverse proxies
• Health Endpoint Metadata:
  • /health now includes region and relayId
  • Used by clients for latency-based selection
• Updated Rate Limiting:
  • Token refill rate increased to 1000/sec for better gameplay experience

Client-Side Architecture

• Relay Discovery Flow:
  1. Fetch active relays from database via getAvailableRelays()
  2. Merge with config-based backup relays
  3. Ping all relays' /health endpoints (2s timeout)
  4. Sort by latency and store for failover
  5. Connect to fastest relay
• Server Registration:
  • Stores relay metadata (relay_id, relay_region, relay_url) in database
  • Enables region display and filtering in public lobby
• Failover Logic:
  • Attempts connection to sorted relay list in order
  • Logs detailed failover attempts for debugging
  • Graceful degradation to config fallback

---

️ Database Schema Changes

New Tables

• relays table:
  • id (text, PK): Unique relay identifier
  • region (text): Geographic region code
  • url (text): WebSocket URL
  • status (text): active/maintenance/disabled
  • priority (integer): Lower = higher priority
  • metadata (jsonb): Extensible field for future features
  • Indexes on status, region, priority for fast queries

Updated Tables

• servers table:
  • Added relay_id (text): ID of relay used by server
  • Added relay_region (text): Region of relay used by server
  • Added relay_url (text): URL of relay used by server
  • Indexes added for efficient region filtering

Row-Level Security

• Anyone can read active relays (required for discovery)
• Only service role can modify relay records

---

Configuration Changes

Client Config (tunnelyrefab.json)

• New field: relays (array of RelayEndpoint objects)
  • Each entry: {id: string, region: string, url: string}
  • Used as backup if database fetch fails
  • Backward compatible with single relayServerUrl

Relay Server Config (.env)

• New variables:
  • RELAY_ID - Unique identifier for relay instance
  • RELAY_REGION - Geographic region code (NA/EU/APAC/SA)
  • RELAY_PUBLIC_HOST - Public hostname/IP for endpoint generation
  • RELAY_PUBLIC_PORT - Public port for endpoint generation

---

Documentation

New Documentation

• MULTI-RELAY-SETUP.md - Comprehensive guide for:
  • Deploying multi-relay infrastructure
  • Database migration steps
  • Relay server configuration
  • Troubleshooting common issues
  • Best practices for relay management

Updated Documentation

• modrinth.md - Added Multi-Regional Relay Network section
• relay-server/.env.example - Added new environment variables with comments

---

Bug Fixes

• Fixed checkbox unresponsiveness in public lobby after multiple clicks
• Fixed button focus issues after async server list reload
• Fixed region filter sometimes showing empty regions
• Fixed concurrent load requests causing UI state corruption
• Fixed server list overlapping bottom control buttons

---

Security & Performance

• Maintained all existing security features (JWT auth, HMAC handshake, TLS encryption)
• No new security surface area introduced
• Improved performance: client-side filtering eliminates redundant network calls
• Reduced database load: cached server list for instant filter toggling

---

⚙ Deployment Notes

For Self-Hosters

1. Run new SQL migrations:
   • supabase/add-relay-fields.sql
   • supabase/create-relays-table.sql
2. Update relay server .env files with new variables
3. Insert relay records into database
4. Optional: Add backup relays to client config

For Users (Default Infrastructure)

• No action required - Update automatically uses regional relay network
• Existing config files remain compatible
• Automatic relay selection works out of the box

---

Acknowledgments

Thank you to all users who reported UI issues and suggested regional relay support. Your feedback directly shaped this release!

---

Download

• Fabric: tunnelyrefab-fabric-1.2-SNAPSHOT.jar
• Forge: tunnelyrefab-forge-1.2-SNAPSHOT.jar
• Requires: Architectury API (dependency)

---

What's Next?

Future updates may include:

• Additional relay regions (South America, Middle East)
• Relay performance metrics dashboard
• Advanced filtering options in public lobby
• Custom relay server support for organizations

---

Support

• Discord: Join our community
• Documentation: See README.md and MULTI-RELAY-SETUP.md
• Ko-fi: Support infrastructure costs

---