Fetching Config

Overview

The Fetching Config system provides a subscription-based mechanism for users to dynamically retrieve proxy client configurations. This system allows users to get up-to-date proxy server configurations compatible with their preferred proxy clients without manual intervention.

The Concept of Subscribe Link

What is a Subscribe Link?

A subscribe link is a unique URL that allows users to fetch their personalized proxy configuration from the telecom service. Each user has a unique subscription token that grants access to their allowed proxy nodes based on their active package and permissions.

How Subscribe Links Work

1. Token Generation: Each user gets a unique subscription_link_key (UUID) stored in the nodes_token table
2. Template URLs: The system supports multiple subscribe endpoints configured via SubscribeLinkConfig
3. Dynamic Generation: The final subscribe URL is generated by replacing {SUBSCRIBE_TOKEN} placeholder with the user’s actual token
4. Access Control: Users can only access nodes their active package group allows

Subscribe Link Architecture

pub struct SubscribeLinkTemplate {
    pub url_template: String,    // e.g., "https://subscribe.congyu.moe/subscribe/{SUBSCRIBE_TOKEN}"
    pub endpoint_name: String,   // e.g., "default"
}

The default configuration provides a template like:

https://subscribe.congyu.moe/subscribe/{SUBSCRIBE_TOKEN}

Which becomes a working URL like:

https://subscribe.congyu.moe/subscribe/550e8400-e29b-41d4-a716-446655440000

Supported Proxy Clients

The system supports the following proxy clients through the libsubconv library:

Supported Client Types

Client Detection

The system automatically detects the client type using two methods:

1. Query Parameter: ?client=clash (explicit specification)
2. User-Agent Header: Automatic detection based on HTTP User-Agent string

The detection logic prioritizes explicit query parameters over User-Agent detection.

How Proxy Client Config is Generated

Generation Process Flow

1. Authentication: Validate the subscription token and retrieve user information
2. Node Filtering: Apply user’s package permissions and filter options
3. Node Retrieval: Fetch available nodes based on user’s active package group
4. Format Conversion: Convert node configurations to client-specific format
5. Response Generation: Generate final configuration with proper headers

Configuration Generation Steps

// 1. Validate subscription token
let token = FindNodesTokenBySubscribeId { subscribe_id };

// 2. Get user's active package and available nodes
let nodes = ListUserNodeClientConfigs {
    user_id: token.user_id,
    filter_option: NodeFilterOption { ... }
};

// 3. Convert to client-specific format
match client_name {
    ClientName::Clash => {
        let nodes = cores.into_iter()
            .filter_map(|c| c.to_clash_node())
            .collect();
        Clash::generate(nodes).stringify()
    },
    ClientName::SingBox => {
        let nodes = cores.into_iter()
            .filter_map(|c| c.to_singbox_node())
            .collect();
        SingBox::generate(nodes).stringify()
    },
    // ... other clients
}

Node Filtering Options

The system supports sophisticated filtering based on:

• Country Exclusion: exclude_country - List of country codes to exclude
• Location Filtering:
  • only_locations - Only include specific locations
  • exclude_locations - Exclude specific locations
• Route Class Filtering:
  • only_route_classes - Only include specific route classes
  • exclude_route_classes - Exclude specific route classes

Available Locations

pub enum Locations {
    NorthAmerica,
    SouthAmerica,
    Europe,
    EastAsia,
    SoutheastAsia,
    MiddleEast,
    Africa,
    Oceania,
    Antarctica,
}

Available Route Classes

pub enum RouteClass {
    /// Highest class, this kind of node is for enterprise customers.
    SpecialCustom,

    /// This class means the node is using high-end infrastructure like IPLC.
    Premium,

    /// This class means the node is using backbone infrastructure.
    Backbone,

    /// This class means the node is out of major countries and regions, provided for global access.
    GlobalAccess,

    /// This class means the node is a budget node, provided for budget sensitive customers.
    Budget,
}

RESTful API Reference

Get Subscribe Links

gRPC Endpoint: TelecomService.GetSubscribeLinks

Purpose: Retrieve available subscribe link templates for a user

Request:

message GetSubscribeLinksRequest {}

Response:

message GetSubscribeLinksReply {
    repeated SubscribeLink links = 1;
    string subscribe_token = 2;
}

message SubscribeLink {
    string url_template = 1;
    string endpoint_name = 2;
}

Fetch Subscribe Content

HTTP Endpoint: GET /subscribe/{token}

Purpose: Retrieve proxy configuration for a specific subscription token

Path Parameters

Query Parameters

Example Requests

Basic Request:

GET /subscribe/550e8400-e29b-41d4-a716-446655440000
User-Agent: Clash/1.0

With Filtering:

GET /subscribe/550e8400-e29b-41d4-a716-446655440000?client=clash&exclude_country=CN,RU&only_route_classes=premium,backbone

Force Client Type:

GET /subscribe/550e8400-e29b-41d4-a716-446655440000?client=singbox

Response Format

The response format varies by client type:

Headers:

• Content-Type: Varies by client (e.g., application/yaml for Clash, application/json for SingBox)
• Custom headers with subscription information (traffic limits, expiration, etc.)

Response Body: Client-specific configuration format

Error Responses

Configuration Management

Subscribe link endpoints are configured via the TelecomConfig:

pub struct SubscribeLinkConfig {
    pub endpoints: Vec<SubscribeLinkEndpoint>,
}

pub struct SubscribeLinkEndpoint {
    pub url_template: String,  // Template with {SUBSCRIBE_TOKEN} placeholder
    pub endpoint_name: String, // Human-readable endpoint name
}

Default Configuration:

{
  "subscribe_link": {
    "endpoints": [
      {
        "url_template": "https://subscribe.congyu.moe/subscribe/{SUBSCRIBE_TOKEN}",
        "endpoint_name": "default"
      }
    ]
  }
}

Implementation Notes

Security Considerations

1. Token Validation: All requests must include a valid subscription token
2. Package Verification: Users can only access nodes their package allows
3. Rate Limiting: Consider implementing rate limiting for subscribe endpoints
4. Token Rotation: Subscription tokens should be rotatable for security

Performance Considerations

1. Caching: Node configurations can be cached to reduce database load
2. Filtering: Client-side filtering is applied efficiently using database indexes
3. Conversion: Node format conversion is optimized per client type

Maintenance Tasks

1. Monitor Usage: Track subscribe link usage patterns
2. Update Templates: Manage subscribe link templates through configuration
3. Clean Up: Remove expired or unused subscription tokens
4. Client Support: Add support for new proxy clients as needed