Skip to main content
GET
/
route
curl -X GET "http://localhost:5001/route?intranet=0"
{
  "tcp_addr": "127.0.0.1:5100",
  "ws_addr": "ws://127.0.0.1:5200",
  "wss_addr": "wss://127.0.0.1:5300"
}

Documentation Index

Fetch the complete documentation index at: https://wukong.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Overview

Get the IM connection address for users, including TCP, WebSocket, and WebSocket Secure addresses.

Query Parameters

intranet
integer
default:0
Whether to return intranet address
  • 0 - Return external network address
  • 1 - Return internal network address
curl -X GET "http://localhost:5001/route?intranet=0"
{
  "tcp_addr": "127.0.0.1:5100",
  "ws_addr": "ws://127.0.0.1:5200",
  "wss_addr": "wss://127.0.0.1:5300"
}

Response Fields

tcp_addr
string
required
TCP connection address, format: host:port
ws_addr
string
required
WebSocket connection address, format: ws://host:port
wss_addr
string
required
WebSocket Secure connection address, format: wss://host:port

Status Codes

Status CodeDescription
200Successfully retrieved IM connection address
500Internal server error

Use Cases

Client Connection Setup

Dynamic Connection Discovery:
// Get connection addresses and establish connection
async function connectToWuKongIM() {
    try {
        // Get connection addresses
        const addresses = await fetch('/route?intranet=0').then(r => r.json());
        
        // Choose appropriate connection type based on environment
        let connectionUrl;
        if (window.location.protocol === 'https:') {
            connectionUrl = addresses.wss_addr;
        } else {
            connectionUrl = addresses.ws_addr;
        }
        
        // Establish WebSocket connection
        const ws = new WebSocket(connectionUrl);
        
        ws.onopen = () => {
            console.log('Connected to WuKongIM:', connectionUrl);
        };
        
        return ws;
    } catch (error) {
        console.error('Failed to connect to WuKongIM:', error);
    }
}

Load Balancing

Multiple Server Discovery:
// Get addresses from multiple servers for load balancing
async function discoverWuKongIMServers(serverList) {
    const availableServers = [];
    
    for (const server of serverList) {
        try {
            const response = await fetch(`${server}/route?intranet=0`);
            const addresses = await response.json();
            
            availableServers.push({
                server: server,
                addresses: addresses,
                priority: calculateServerPriority(server)
            });
        } catch (error) {
            console.warn(`Server ${server} is not available:`, error);
        }
    }
    
    // Sort by priority and return best server
    availableServers.sort((a, b) => b.priority - a.priority);
    return availableServers[0]?.addresses;
}

Environment-based Connection

Internal vs External Network:
// Choose connection type based on network environment
async function getOptimalConnection() {
    try {
        // Try internal network first (faster)
        const internalAddresses = await fetch('/route?intranet=1').then(r => r.json());
        
        // Test internal connectivity
        const isInternalReachable = await testConnectivity(internalAddresses.ws_addr);
        
        if (isInternalReachable) {
            return internalAddresses;
        } else {
            // Fallback to external network
            const externalAddresses = await fetch('/route?intranet=0').then(r => r.json());
            return externalAddresses;
        }
    } catch (error) {
        console.error('Failed to get optimal connection:', error);
        throw error;
    }
}

async function testConnectivity(wsUrl) {
    return new Promise((resolve) => {
        const testWs = new WebSocket(wsUrl);
        const timeout = setTimeout(() => {
            testWs.close();
            resolve(false);
        }, 3000);
        
        testWs.onopen = () => {
            clearTimeout(timeout);
            testWs.close();
            resolve(true);
        };
        
        testWs.onerror = () => {
            clearTimeout(timeout);
            resolve(false);
        };
    });
}

Connection Failover

Automatic Failover:
class WuKongIMConnector {
    constructor(serverUrls) {
        this.serverUrls = serverUrls;
        this.currentServerIndex = 0;
        this.connection = null;
    }
    
    async connect() {
        for (let i = 0; i < this.serverUrls.length; i++) {
            try {
                const serverUrl = this.serverUrls[this.currentServerIndex];
                const addresses = await this.getAddresses(serverUrl);
                
                this.connection = await this.establishConnection(addresses);
                console.log(`Connected to server: ${serverUrl}`);
                return this.connection;
                
            } catch (error) {
                console.warn(`Failed to connect to server ${this.currentServerIndex}:`, error);
                this.currentServerIndex = (this.currentServerIndex + 1) % this.serverUrls.length;
            }
        }
        
        throw new Error('Failed to connect to any WuKongIM server');
    }
    
    async getAddresses(serverUrl) {
        const response = await fetch(`${serverUrl}/route?intranet=0`);
        return await response.json();
    }
    
    async establishConnection(addresses) {
        return new Promise((resolve, reject) => {
            const ws = new WebSocket(addresses.ws_addr);
            
            ws.onopen = () => resolve(ws);
            ws.onerror = (error) => reject(error);
            
            setTimeout(() => reject(new Error('Connection timeout')), 5000);
        });
    }
}

// Usage
const connector = new WuKongIMConnector([
    'http://server1.example.com:5001',
    'http://server2.example.com:5001',
    'http://server3.example.com:5001'
]);

const connection = await connector.connect();

Mobile App Integration

Platform-specific Connection:
// React Native example
import { Platform } from 'react-native';

async function getMobileConnection() {
    try {
        const addresses = await fetch('/route?intranet=0').then(r => r.json());
        
        // Use appropriate connection for mobile platforms
        if (Platform.OS === 'ios' || Platform.OS === 'android') {
            // Mobile apps typically use WebSocket
            return addresses.ws_addr;
        } else {
            // Web apps use secure WebSocket if available
            return window.location.protocol === 'https:' 
                ? addresses.wss_addr 
                : addresses.ws_addr;
        }
    } catch (error) {
        console.error('Failed to get mobile connection:', error);
        throw error;
    }
}

Best Practices

  1. Connection Type Selection: Choose appropriate connection type based on environment (HTTP/HTTPS)
  2. Failover Strategy: Implement failover mechanism for high availability
  3. Network Detection: Detect internal vs external network for optimal performance
  4. Connection Testing: Test connectivity before establishing full connection
  5. Caching: Cache connection addresses to reduce API calls
  6. Error Handling: Handle network errors gracefully with retry logic
  7. Security: Use secure connections (WSS) in production environments