Node Client

Purpose of Node Client

Node Client serves as the user-facing proxy endpoint in the Helium telecom system. It provides a crucial abstraction layer that enables flexible service delivery while maintaining efficient resource utilization.

Service Tier Differentiation

The primary purpose of Node Client is to enable different service tiers to utilize the same physical infrastructure while providing distinct user experiences. Consider this scenario:

Physical Infrastructure (Node Server):
├── High-performance server in US-West datacenter
│   ├── 10Gbps bandwidth capacity
│   └── Premium network routing

User-Facing Services (Node Clients):
├── "US Premium" (traffic_factor: 2.0, high-priority routing)
├── "US Standard" (traffic_factor: 1.0, standard routing)
└── "US Budget" (traffic_factor: 0.5, economy routing)

All three service tiers connect to the same physical density server, but users access them through different entry servers that provide different characteristics:

• Budget Plan: Uses cheaper entry server with higher latency to user, but same backend density server
• Premium Plan: Uses premium entry server with optimized routing, same backend density server
• Standard Plan: Balanced entry server performance, same backend density server

Business Value

This architecture enables:

1. Cost-Effective Infrastructure: One physical server supports multiple service tiers
2. Flexible Pricing Models: Different billing rates (traffic_factor) for same infrastructure
3. Access Control: User package groups control which nodes are accessible
4. Geographic Organization: Logical grouping by region while optimizing server placement
5. Service Quality Differentiation: Different route classes and metadata per service tier

Concept of Node Client

Architecture Overview

Node Client operates as the entry point of the proxy line - it’s what users see and configure in their proxy client applications.

User's Proxy Client → Node Client (User-facing) → Node Server (Infrastructure) → Internet

Key Relationships

Core Concepts

1. Server Relationship

pub struct NodeClient {
    pub server_id: i32,  // Points to the physical Node Server
    // ... other fields
}

Each Node Client must reference an existing Node Server. This creates a 1:N relationship where one physical server can support multiple user-facing endpoints.

2. Traffic Factor System

// Billing calculation:
// Billed Traffic = Actually Used Traffic × Traffic Factor
pub traffic_factor: Decimal,

Traffic factor enables flexible billing models:

• 0.5: Budget tier (user pays for half of actual usage)
• 1.0: Standard tier (user pays for actual usage)
• 2.0: Premium tier (user pays double, presumably for better service)

3. Access Control System

pub available_groups: Vec<i32>,  // Package groups that can access this node

Users can only access Node Clients if their active package belongs to one of the available_groups. This enables:

• Package-based access control: Different subscription tiers access different nodes
• Geographic restrictions: Certain packages only access specific regions
• Service level enforcement: Premium packages get access to premium nodes

4. Protocol Configuration

pub client_side_config: Json<NodeClientConfig>,

Node Client stores the client-side protocol configuration that determines how users connect. This includes protocol-specific settings for:

• VMess, VLess, Trojan, Shadowsocks, Hysteria2, WireGuard, etc.
• Connection parameters (hostname, port, encryption methods)
• Transport settings (WebSocket, gRPC, TCP, etc.)

5. Metadata System

pub struct NodeClientMetadata {
    pub country: Option<CountryCode>,      // Geographic identification
    pub location: Option<Locations>,       // Regional classification
    pub route_class: Option<RouteClass>,   // Service quality indicator
}

Route Classes define service quality expectations:

• SpecialCustom: Enterprise-grade infrastructure
• Premium: High-end infrastructure (IPLC, dedicated lines)
• Backbone: Standard backbone infrastructure (most common)
• GlobalAccess: International access nodes
• Budget: Cost-optimized infrastructure
• Experimental: Testing and development nodes

Configuration of Node Client

Core Configuration Fields

pub struct NodeClient {
    pub id: i32,                                          // Unique identifier
    pub server_id: i32,                                   // Physical server reference
    pub name: String,                                     // Display name for users
    pub traffic_factor: Decimal,                          // Billing multiplier
    pub display_order: i32,                               // Sort order in client apps
    pub client_side_config: Json<NodeClientConfig>,       // Protocol configuration
    pub available_groups: Vec<i32>,                       // Access control groups
    pub node_metadata: Json<NodeClientMetadata>,          // Geographic/quality metadata
    pub created_at: PrimitiveDateTime,                    // Creation timestamp
    pub updated_at: PrimitiveDateTime,                    // Last modification
}

Configuration Examples

These JSON examples show the API request format that frontend applications should use when creating Node Clients.

Creating a Premium VMess Node Client

{
  "server_id": 1,
  "name": "🇺🇸 US Premium West",
  "traffic_factor": "2.0",
  "display_order": 100,
  "available_groups": [1, 2],
  "client_side_config": {
    "protocol": "Vmess",
    "v": 2,
    "hostname": "premium-us.example.com",
    "port": 443,
    "alter_id": 0,
    "encrypt_method": "auto",
    "network": "ws",
    "fake_type": "none",
    "host": "premium-us.example.com",
    "path": "/premium-path",
    "tls": "tls",
    "sni": "premium-us.example.com",
    "alpn": null,
    "fingerprint": null
  },
  "metadata": {
    "country": "US",
    "location": "north_america",
    "route_class": "premium"
  }
}

Key Configuration Points:

• server_id: References the physical Node Server (ID: 1)
• traffic_factor: “2.0” means users pay 2x actual usage (premium pricing)
• available_groups: [1, 2] restricts access to Premium and Enterprise packages
• protocol: “Vmess” specifies VMess protocol with WebSocket transport
• route_class: “premium” indicates high-end infrastructure

Creating a Budget Shadowsocks Node Client

{
  "server_id": 3,
  "name": "🇸🇬 Singapore Budget",
  "traffic_factor": "0.5",
  "display_order": 900,
  "available_groups": [3, 4],
  "client_side_config": {
    "protocol": "Ss",
    "server": "budget-asia.example.com",
    "port": 8080,
    "cipher": "aes-256-gcm",
    "server_key": null,
    "obfs": null,
    "plugin": null
  },
  "metadata": {
    "country": "SG",
    "location": "southeast_asia",
    "route_class": "budget"
  }
}

Key Configuration Points:

• server_id: References different physical server (ID: 3)
• traffic_factor: “0.5” means users pay half actual usage (budget pricing)
• available_groups: [3, 4] restricts access to Basic and Student packages
• protocol: “Ss” specifies Shadowsocks with AES-256-GCM encryption
• display_order: 900 (lower priority in client app display)

Creating a Hysteria2 High-Performance Node

{
  "server_id": 2,
  "name": "🇩🇪 Germany Hysteria2",
  "traffic_factor": "1.5",
  "display_order": 200,
  "available_groups": [1, 2, 5],
  "client_side_config": {
    "protocol": "Hy2",
    "server": "hy2-eu.example.com",
    "port": 443,
    "ports": "20000-55000",
    "obfs": "salamander",
    "obfs_password": "secret123",
    "alpn": ["h3"],
    "up": "100 Mbps",
    "down": "500 Mbps",
    "sni": "hy2-eu.example.com",
    "skip_cert_verify": false,
    "ca": null,
    "ca_str": null,
    "fingerprint": null,
    "cwnd": 32
  },
  "metadata": {
    "country": "DE",
    "location": "europe",
    "route_class": "backbone"
  }
}

Key Configuration Points:

• traffic_factor: “1.5” for premium protocol pricing
• available_groups: [1, 2, 5] for Premium, Enterprise, and Gaming packages
• protocol: “Hy2” specifies Hysteria2 with QUIC transport
• ports: Port range for UDP multiplexing
• obfs: “salamander” obfuscation method

Protocol Support

Node Client supports a comprehensive range of proxy protocols through the NodeClientConfig enum:

Configuration Validation

The system provides configuration validation through the gRPC management API:

gRPC Service: helium.telecom_manage.NodeClientManage
Method: VerifyNodeClientConfig

Request:

message VerifyNodeClientConfigRequest {
  string config = 1;
}

Response:

message VerifyReply {
  bool valid = 1;
}

Example gRPC call:

grpcurl -plaintext \
  -d '{"config": "{\"protocol\":\"Vmess\",\"hostname\":\"test.example.com\",\"port\":443}"}' \
  localhost:50051 \
  helium.telecom_manage.NodeClientManage/VerifyNodeClientConfig

Frontend applications should validate configurations before creating Node Clients to ensure proper protocol settings and prevent runtime errors.

JSON Schema Reference

For frontend developers, here are the key JSON structures:

Node Client Creation Request

{
  "server_id": "<integer>", // Required: Physical server ID
  "name": "<string>", // Required: Display name
  "traffic_factor": "<decimal_string>", // Required: Billing multiplier (e.g., "1.0", "2.5")
  "display_order": "<integer>", // Required: Sort order (higher = lower priority)
  "available_groups": ["<integer>"], // Required: Package group IDs
  "client_side_config": {
    // Required: Protocol configuration
    "protocol": "<protocol_name>" // Required: See Protocol Support table
    // Protocol-specific fields vary
  },
  "metadata": {
    // Optional: Geographic/quality metadata
    "country": "<iso_country_code>", // Optional: Two-letter country code
    "location": "<location_enum>", // Optional: Geographic region
    "route_class": "<route_class_enum>" // Optional: Service quality tier
  }
}

Location Enum Values

[
  "north_america",
  "south_america",
  "europe",
  "east_asia",
  "southeast_asia",
  "south_asia",
  "middle_east",
  "africa",
  "oceania",
  "arctic",
  "antarctic"
]

Route Class Enum Values

[
  "special_custom",
  "premium",
  "backbone",
  "global_access",
  "budget",
  "experimental"
]

Common Protocol Configurations

VMess Protocol:

{
  "protocol": "Vmess",
  "v": 2,
  "hostname": "<hostname>",
  "port": "<integer>",
  "alter_id": "<integer>",
  "encrypt_method": "<string|null>",
  "network": "<string|null>",
  "fake_type": "<string|null>",
  "host": "<string|null>",
  "path": "<string|null>",
  "tls": "<string|null>",
  "sni": "<string|null>",
  "alpn": "<string[]|null>",
  "fingerprint": "<string|null>"
}

Shadowsocks Protocol:

{
  "protocol": "Ss",
  "server": "<hostname>",
  "port": "<integer>",
  "cipher": "<string>",
  "server_key": "<string|null>",
  "obfs": "<object|null>",
  "plugin": "<object|null>"
}

Hysteria2 Protocol:

{
  "protocol": "Hy2",
  "server": "<hostname>",
  "port": "<integer>",
  "ports": "<string|null>",
  "obfs": "<string|null>",
  "obfs_password": "<string|null>",
  "alpn": "<string[]|null>",
  "up": "<string|null>",
  "down": "<string|null>",
  "sni": "<string|null>",
  "skip_cert_verify": "<boolean>",
  "ca": "<string|null>",
  "ca_str": "<string|null>",
  "fingerprint": "<string|null>",
  "cwnd": "<integer|null>"
}

Administrative Management

Node Client management requires administrator privileges with role-based access control:

When to Use Node Client vs Node Server

For a comprehensive comparison of when to use Node Client versus Node Server, including decision matrices, workflow examples, and use case scenarios, see the Node Server vs Node Client Usage Guide.

Quick Decision Guide for Node Client

Use Node Client when you need:

• User-facing service tiers (Premium, Standard, Budget)
• Service differentiation with same physical infrastructure
• Flexible billing models via traffic factors
• Package-based access control
• Geographic service organization
• Protocol-specific client configurations

Node Client Specific Examples

The following examples demonstrate Node Client’s unique capabilities:

1. Creating User-Facing Service Tiers

Scenario: Same physical server (ID: 1), multiple service levels

Premium Tier:

{
  "server_id": 1,
  "name": "🏆 US Premium Plus",
  "traffic_factor": "2.0",
  "available_groups": [1],
  "client_side_config": {
    "protocol": "Vmess",
    "hostname": "premium.example.com",
    "port": 443,
    "network": "ws",
    "tls": "tls"
  },
  "metadata": {
    "route_class": "premium"
  }
}

Standard Tier:

{
  "server_id": 1,
  "name": "⚡ US Standard",
  "traffic_factor": "1.0",
  "available_groups": [2, 3],
  "client_side_config": {
    "protocol": "Vmess",
    "hostname": "standard.example.com",
    "port": 443,
    "network": "tcp"
  },
  "metadata": {
    "route_class": "backbone"
  }
}

Budget Tier:

{
  "server_id": 1,
  "name": "💰 US Economy",
  "traffic_factor": "0.5",
  "available_groups": [4],
  "client_side_config": {
    "protocol": "Ss",
    "server": "budget.example.com",
    "port": 8080,
    "cipher": "aes-256-gcm"
  },
  "metadata": {
    "route_class": "budget"
  }
}

2. Implementing Geographic Service Organization

Physical servers in strategic locations:

• EU Server (ID: 2): Frankfurt datacenter
• Asia Server (ID: 3): Singapore datacenter

UK Node Client (uses Frankfurt server):

{
  "server_id": 2,
  "name": "🇬🇧 United Kingdom",
  "traffic_factor": "1.0",
  "available_groups": [1, 2, 3],
  "client_side_config": {
    "protocol": "Vless",
    "hostname": "uk.example.com",
    "port": 443,
    "encrypt_method": "none",
    "network": "ws",
    "tls": "tls"
  },
  "metadata": {
    "country": "GB",
    "location": "europe",
    "route_class": "premium"
  }
}

Singapore Node Client (uses Singapore server):

{
  "server_id": 3,
  "name": "🇸🇬 Singapore",
  "traffic_factor": "1.0",
  "available_groups": [1, 2, 3],
  "client_side_config": {
    "protocol": "Vless",
    "hostname": "sg.example.com",
    "port": 443,
    "encrypt_method": "none",
    "network": "tcp"
  },
  "metadata": {
    "country": "SG",
    "location": "southeast_asia",
    "route_class": "backbone"
  }
}

3. Protocol Differentiation for Same Server

Multi-protocol capable server (ID: 4):

VMess Endpoint:

{
  "server_id": 4,
  "name": "VMess - US West",
  "traffic_factor": "1.0",
  "display_order": 100,
  "available_groups": [2, 3, 4],
  "client_side_config": {
    "protocol": "Vmess",
    "v": 2,
    "hostname": "vmess.example.com",
    "port": 443,
    "alter_id": 0,
    "network": "ws",
    "tls": "tls"
  }
}

Hysteria2 Endpoint (same server, faster protocol):

{
  "server_id": 4,
  "name": "Hysteria2 - US West",
  "traffic_factor": "1.2",
  "display_order": 150,
  "available_groups": [1, 2],
  "client_side_config": {
    "protocol": "Hy2",
    "server": "hy2.example.com",
    "port": 443,
    "obfs": "salamander",
    "up": "50 Mbps",
    "down": "200 Mbps"
  }
}

4. Access Control and Package Management

Enterprise Dedicated Node (restricted access):

{
  "server_id": 1,
  "name": "🏢 Enterprise Dedicated",
  "traffic_factor": "3.0",
  "available_groups": [1],
  "client_side_config": {
    "protocol": "Vless",
    "hostname": "enterprise.example.com",
    "port": 443,
    "encrypt_method": "none",
    "network": "grpc",
    "tls": "tls"
  },
  "metadata": {
    "route_class": "special_custom"
  }
}

Consumer Standard Node (broader access):

{
  "server_id": 1,
  "name": "👤 Consumer Standard",
  "traffic_factor": "1.0",
  "available_groups": [2, 3, 4],
  "client_side_config": {
    "protocol": "Vmess",
    "v": 2,
    "hostname": "consumer.example.com",
    "port": 443,
    "alter_id": 0,
    "network": "ws"
  },
  "metadata": {
    "route_class": "backbone"
  }
}

Node Server Use Cases

For complete Node Server use cases and detailed infrastructure examples, see the Node Server documentation.

1. Setting Up Physical Infrastructure

Node Server setup focuses on backend infrastructure configuration:

{
  "server_side_config": {
    "compatibility": "newv2b"
    // UniProxy protocol configuration for actual proxy server
    // Backend-specific settings not visible to end users
  },
  "speed_limit": 10000000000
}

Key Focus:

• Server-side proxy protocol configuration
• Physical infrastructure capacity (10GB/s total)
• Backend performance tuning
• Not visible to end users

2. Configuring Backend Proxy Behavior

• Protocol selection (UniProxy vs SSPanel compatibility)
• Server-side performance settings
• Traffic processing configuration
• Capacity and resource limits

3. Physical Resource Management

• Server capacity planning
• Geographic server deployment
• Infrastructure health monitoring
• Hardware resource allocation

4. Backend System Administration

• Server heartbeat monitoring
• Traffic aggregation processing
• System maintenance operations
• Infrastructure-level configuration

Decision Matrix

Development Workflow

For the complete development workflow including infrastructure setup, service configuration, and monitoring phases, see the Development Workflow Guide in the Node Server documentation.

Node Client Management APIs

For Node Client specific operations, use these gRPC endpoints:

Create Node Client:

// helium.telecom_manage.NodeClientManage/CreateNodeClient
message CreateNodeClientRequest {
  int32 server_id = 1;
  string name = 2;
  string traffic_factor = 3;
  int32 display_order = 4;
  string client_side_config = 5;
  repeated int32 available_groups = 6;
  optional helium.telecom.NodeMetadata metadata = 7;
}

Edit Access Groups:

// helium.telecom_manage.NodeClientManage/EditNodeClientGroups
message EditNodeClientGroupsRequest {
  int32 id = 1;
  repeated int32 available_groups = 2;
}

List Node Clients:

// helium.telecom_manage.NodeClientManage/ListNodeClients
message ListNodeClientsRequest {}

message ListNodeClientsReply {
  repeated NodeClientAdminGlance nodes = 1;
}

See Also: Node Server gRPC APIs for server management operations.

Node Client Best Practices

1. Service Tier Strategy: Use Node Client to create multiple service tiers (Premium, Standard, Budget) on the same physical infrastructure
2. Traffic Factor Planning: Set appropriate billing multipliers:
   • 0.5 for budget tiers
   • 1.0 for standard service
   • 2.0+ for premium tiers
3. Access Control: Always configure available_groups to enforce package-based restrictions
4. User Experience: Use meaningful names, emojis, and proper display_order for client applications
5. Geographic Metadata: Include country codes and location metadata to help users choose optimal endpoints
6. Protocol Selection: Choose appropriate protocols based on target user base and technical requirements

For comprehensive best practices covering both Node Client and Node Server management, see the Best Practices Guide in the Node Server documentation.