Group Lines - Routing Group Optimization Guide

Overview

Use the testLine and getGroupResult methods to efficiently manage multiple server routes, ensuring resources are allocated to the best-performing server and enabling dynamic route optimization.

⚠️ Important Notes

• When the return value is an empty string (""), be sure to implement a fallback mechanism to avoid errors or service interruptions.
• Each route in the returned result must be tested to ensure its availability. If a route is unavailable, switch to another available route or implement a fallback mechanism.
• The type and group parameters must match the group name configured via testLine; otherwise, performance data may not be retrieved correctly.

testLine( type, group, lines ) - Create a Routing Group

Description

The testLine method creates a new routing group with the specified group name. This is the starting point for dynamic route optimization.

Syntax

import JBLWebSocket from '@/assets/js/jbl.es.js';
const authorizationKey = '${Product authorization key}';

JBLWebSocket.connect(authorizationKey);
JBLWebSocket.testLine(type, group, lines);

Parameters

Parameter	Type	Description
type	String	Required: Specifies the type. Options are site or 3r for website or third-party services.
group	String	Required: Group name to identify the routing group.
lines	String	Required: Server route addresses, formatted as a comma-separated string (e.g., api.dome1.com,api.dome2.com).

Example

// Create a routing group named "Group1" with two server routes
JBLWebSocket.testLine('site', 'Group1', 'api.dome1.com,api.dome2.com');

// Set the type for a third-party service
JBLWebSocket.testLine('3r', 'ThirdPartyGroup', 'api.thirdparty.com,api.backup.com');

getGroupResult( type, group ) - Get the Best Route

Description

The getGroupResult method retrieves the latest server route performance data (speed and usage) for the specified type and group name. This is the key step for dynamically selecting the best route.

Why call testLine before getGroupResult?

Before calling getGroupResult, you must first execute testLine. This ensures the server has initialized and populated the routing group. Otherwise, getGroupResult may return empty or outdated data.

How does jblResult automatically update through WebSocket?

Reference-based data binding enables automatic updates When JBLWebSocket.getGroupResult(type, group) is called, it returns a reference to an object, rather than a static value. WebSocket continuously updates this object internally, which means even if developers do not manually listen to WebSocket events, jblResult will still receive real-time updates.

This allows developers to access jblResult directly without needing to repeatedly call getGroupResult() to refresh the data manually.

Syntax

import JBLWebSocket from '@/assets/js/jbl.es.js';
const authorizationKey = '${Product authorization key}';

await JBLWebSocket.connect(authorizationKey);
JBLWebSocket.testLine(type, group, lines);

let jblResult = await JBLWebSocket.getGroupResult('site', 'Group1');

Parameters

Parameter	Type	Description
type	String	Required: Specifies the type. Options are site or 3r for website or third-party services.
group	String	Required: Group name to identify the routing group.

Basic Example

import JBLWebSocket from '@/assets/js/jbl.es.js';

const authorizationKey = ${Product authorization key};

// Establish WebSocket connection
JBLWebSocket.connect(authorizationKey);
// Create a routing group named "Group1" with two server routes
JBLWebSocket.testLine('site', 'Group1', 'api.dome1.com,api.dome2.com');

// Retrieve `jblResult`, which maintains a reference to WebSocket's internal data
let jblResult = await JBLWebSocket.getGroupResult('site', 'Group1');

// Even without manually listening to WebSocket events,
// `jblResult` is a reference to WebSocket's internal data.
// Any changes pushed by WebSocket will directly update `jblResult`.
console.log('Initialized best server route:', jblResult);
// Example output: { site_Group1: 'api.dome1.com' }

🔍 WebSocket Group Routing Update Mechanism

1️⃣ Group Initialization and Delay for First Update

• If the server does not have an existing group configuration, it must first receive a group setup via testLine.
• After testLine is sent, the server requires approximately one minute before the results are updated and available in getGroupResult.
• During this waiting period, any calls to getGroupResult() may return empty data until the first update cycle completes.

2️⃣ Automatic Reset When Data Becomes Stale

• If the server receives no new data for the specified group over an extended period, it automatically clears the result.
• This prevents outdated or inaccurate routing information and allows the system to recalculate and provide the best route when new data arrives.

3️⃣ Periodic Updates and Auto-Clear Mechanism

• The server updates the group result every minute to ensure the latest routing data is available.
• If no updates occur within one minute, the server automatically clears the result until fresh data is received.
• If updates do occur within the one-minute window, the server retains the latest routing data and makes it available via getGroupResult().

Result Handling and Fallback Mechanism

When the return value is an empty string, you need to implement your own fallback mechanism to avoid potential errors. For example:

let jblResult = await JBLWebSocket.getGroupResult('site', 'Group1');

if (!jblResult || !jblResult.site_Group1) {
    console.error('No available server routes. Please implement a fallback mechanism.');
    // Add your fallback logic here
} else {
    console.log(`Best route: ${jblResult.site_Group1}`);

    // Test the availability of the route
    const fetchTestLine = async (url) => {
        try {
            const response = await fetch(url, { method: 'HEAD' });
            return response.ok;
        } catch (err) {
            console.error(`${url} test failed:`, err);
            return false;
        }
    };

    const isAvailable = await fetchTestLine(jblResult.site_Group1);

    if (!isAvailable) {
        console.error('Primary route unavailable, switching to fallback route...');
        // Add your fallback logic here
    }
}

This reorganization focuses on the key technical points while keeping the overall structure more fluid! 🚀 If you need any further adjustments, just let me know!