Proxy Support

Connect through SOCKS5 and HTTP proxies with authentication and validation

LiquidBounce includes built-in proxy support for connecting to Minecraft servers through proxy servers, useful for bypassing network restrictions or protecting your IP address.

Supported Proxy Types

The ProxyManager (features/misc/proxy/ProxyManager.kt:42) supports:

• SOCKS5 - Full protocol support with authentication
• HTTP - HTTP proxy protocol with authentication

Only SOCKS5 and HTTP proxies are supported. SOCKS4 is not supported.

Proxy Configuration

Proxy Data Structure

data class Proxy(
    val host: String,
    val port: Int,
    val credentials: Credentials?,
    val type: Type?,
    var forwardAuthentication: Boolean = false,
    var ipInfo: IpInfoApi.IpData? = null,
    var favorite: Boolean = false
)

Creating a Proxy

Proxies support multiple input formats:

// Basic format
host:port

// With credentials (@ notation)
username:password@host:port

// With credentials (colon notation)
host:port:username:password
username:password:host:port

// With type prefix
http://host:port
socks5://host:port
socks5h://host:port

The parser automatically detects the format (Proxy.kt:78-124).

Proxy Validation

Before use, proxies are validated by connecting to a Minecraft ping server:

ProxyManager.validateProxy(proxy, 
    index = null,  // null = add new, index = replace existing
    checkOnly = false  // true = don't add to list
)

1. Send Query Request

   Attempts to connect to the Minecraft Ping Server through the proxy (ProxyManager.kt:75)

2. Validate Connection

   Ensures the proxy works for Minecraft protocol, not just HTTP(S)

3. Store or Update

   On success, adds the proxy to the list or updates an existing one (ProxyManager.kt:84-95)

4. Fire Event

   Triggers ProxyCheckResultEvent with success or error message (ProxyManager.kt:78-99)

Using Proxies

Setting Active Proxy

ProxyManager.proxy = myProxy

The active proxy is automatically used for all server connections (ProxyManager.kt:46-48).

Current Proxy

Get the current active proxy (validates it’s configured):

val currentProxy = ProxyManager.currentProxy
// Returns null if proxy host is blank or port is invalid

Implementation (ProxyManager.kt:54-55):

val currentProxy
    get() = proxy.takeIf { proxy -> proxy.host.isNotBlank() && proxy.port > 0 }

Network Integration

Pipeline Handler

Proxies are automatically injected into the Netty pipeline:

private val pipelineHandler = handler<PipelineEvent> { event ->
    // Skip local servers
    if (event.local) {
        return@handler
    }
    
    val pipeline = event.channelPipeline
    
    // Add proxy handler if not already present
    if (pipeline.get("proxy") == null) {
        pipeline.addFirst("proxy", currentProxy?.handler() ?: return@handler)
    }
}

Local servers (localhost/LAN) automatically bypass the proxy (ProxyManager.kt:112).

Proxy Handler Creation

The handler is created based on proxy type (Proxy.kt:47-58):

fun handler() = when (type ?: Type.SOCKS5) {
    Type.HTTP -> if (credentials == null) {
        HttpProxyHandler(address)
    } else {
        HttpProxyHandler(address, credentials.username, credentials.password)
    }
    Type.SOCKS5 -> if (credentials == null) {
        Socks5ProxyHandler(address)
    } else {
        Socks5ProxyHandler(address, credentials.username, credentials.password)
    }
}

Proxy Management

Storing Proxies

Proxies are saved in the config system:

internal val proxies by list(name, mutableListOf<Proxy>(), valueType = ValueType.PROXY)

Changes are automatically persisted (ProxyManager.kt:47, 91).

Connection Tracking

The manager tracks validation connections for proper cleanup:

internal fun addClientConnection(connection: Connection) = mc.execute {
    clientConnections.add(connection)
}

Connections are ticked and cleaned up automatically (ProxyManager.kt:129-138).

Advanced Features

Forward Authentication

The forwardAuthentication flag can be used to control whether credentials are forwarded to the destination server.

IP Information

Proxies can store associated IP information from IpInfo API:

var ipInfo: IpInfoApi.IpData? = null

This can include:

• Geographic location
• ISP information
• Connection details

Favorites

Mark frequently used proxies as favorites:

proxy.favorite = true

Error Handling

Validation failures trigger events with error messages:

failure = {
    logger.error("Failed to check proxy", it)
    EventManager.callEvent(
        ProxyCheckResultEvent(proxy, error = it.message ?: "Unknown error")
    )
}

Best Practices

Always Validate Proxies

Use validateProxy() before adding proxies to ensure they work with Minecraft’s protocol, not just HTTP.

Handle Local Connections

The system automatically skips proxies for local servers. Don’t manually bypass this behavior.

Secure Credentials

Proxy credentials are stored in the config. Ensure your config files are properly secured.

Monitor Events

Listen to ProxyCheckResultEvent to provide user feedback on proxy validation results.

Configuration Example

{
  "selectedProxy": {
    "host": "proxy.example.com",
    "port": 1080,
    "credentials": {
      "username": "user",
      "password": "pass"
    },
    "type": "SOCKS5",
    "favorite": true
  },
  "proxies": [
    // List of saved proxies
  ]
}