Networking with Xray-core

Relevant source files

The following files were used as context for generating this wiki page:

• main.js
• utils.js
• renderer.js
• setup.js
• README.md
• package.json

GeekEZ Browser integrates the powerful and versatile Xray-core as its fundamental networking engine. This integration is central to the browser's ability to provide strict network isolation for each profile, ensuring that all traffic is routed through user-defined proxies. By leveraging Xray-core, the browser supports a wide array of modern proxy protocols and advanced transport mechanisms, offering flexibility and robust security for multi-account management.

The networking architecture is designed around a "one profile, one proxy process" model. When a user launches a browser profile, a dedicated Xray-core instance is spawned in the background. This instance is configured with the specific proxy settings for that profile and exposes a local SOCKS5 proxy. The browser instance for that profile is then launched and forced to route all its traffic through this dedicated local port, achieving complete network segregation from other profiles and the host system.

Sources: README.md, main.js:410-415, utils.js:1-5

Initial Setup and Updates

The Xray-core binary is not bundled directly but is downloaded during the initial setup process to ensure the correct version for the user's operating system and architecture.

Sources: package.json:7, setup.js

Automated Download

The setup.js script, executed via the postinstall command in package.json, handles the acquisition of the Xray-core binary.

1. Platform Detection: The script determines the user's OS (win32, darwin, linux) and architecture (x64, arm64, etc.) to construct the correct asset name.
2. Network Check: It checks for global network connectivity. If direct access to GitHub is unavailable (e.g., in China), it prepends a mirror URL (GH_PROXY) to the download link.
3. Download & Extraction: The script downloads the specified version of the Xray-core release asset from GitHub, saves it as xray.zip, extracts the binary into the resources/bin directory, and sets the necessary executable permissions on macOS/Linux.

Sources: setup.js:10-14, setup.js:83-91, setup.js:132-149

This diagram illustrates the initial setup flow for the Xray-core binary.

Automatic Updates

The application includes a mechanism to check for and apply updates to the Xray-core binary.

• Update Check: The check-xray-update IPC handler in main.js fetches the latest release information from the Xray-core GitHub repository API. It compares the remote version with the locally installed version.
• Download: If an update is found, the download-xray-update handler is invoked. It downloads the new version, stops any running Xray processes, replaces the old binary with the new one, and cleans up temporary files.

Sources: main.js:145-156, main.js:157-227

Profile Launch and Network Isolation

The core of GeekEZ Browser's networking lies in how it launches and manages an isolated Xray instance for each browser profile.

Sources: main.js:410-547

Launch Sequence

When a user clicks "Launch" on a profile, the launch-profile IPC handler in main.js executes the following sequence:

1. Port Acquisition: An available local TCP port is acquired using the get-port library. This port will serve as the SOCKS5 entry point for the browser.
2. Configuration Generation: The generateXrayConfig function is called with the profile's proxy link (proxyStr) and the acquired local port. This function produces a complete Xray JSON configuration file.
3. Xray Process Spawn: A new Xray process is spawned using child_process.spawn. It is pointed to the generated config.json file. All logs are redirected to xray_run.log within the profile's data directory.
4. Browser Launch: A Puppeteer browser instance is launched with specific arguments. Crucially, the --proxy-server=socks5://127.0.0.1:<localPort> argument forces all browser traffic through the newly created Xray process.
5. Lifecycle Management: The Xray process ID (xrayPid) and the browser instance are stored in the activeProcesses object. When the browser is closed (disconnected event), the corresponding Xray process is forcefully terminated to free up resources.

This diagram shows the sequence of events when a profile is launched.

Proxy Configuration

Proxy configurations are derived from user-provided proxy links. The utils.js file contains the logic to parse these links and translate them into valid Xray outbound configurations.

Sources: utils.js

Supported Protocols

The system can parse a variety of common proxy link formats.

Protocol	Example Format	Source File
VMess	vmess://... (Base64 encoded JSON)	utils.js:23-50
VLESS	vless://uuid@host:port?params...	utils.js:51-99
Trojan	trojan://password@host:port?params...	utils.js:100-112
Shadowsocks	ss://method:pass@host:port or ss://base64...	utils.js:113-172
SOCKS	socks5://user:pass@host:port	utils.js:173-177
HTTP	http://user:pass@host:port	utils.js:178-182

The parser also supports advanced transport options specified in the link parameters, such as WebSocket (ws), gRPC, REALITY, and more.

Sources: README.md, utils.js:23-184

Configuration Generation

The generateXrayConfig function in utils.js assembles the final JSON configuration written to disk. A typical configuration includes:

• inbounds: A single SOCKS inbound listening on 127.0.0.1 at the dynamically assigned localPort.
• outbounds: An array containing the main proxy outbound (tagged proxy_main) and a direct connection outbound (tagged direct). If a chain proxy is used, a pre-proxy outbound (tagged proxy_pre) is also included.
• routing: A simple rule that routes all traffic (port: "0-65535") to the proxy_main outbound tag.

Sources: utils.js:187-213

Chain Proxy (Pre-Proxy)

GeekEZ Browser supports proxy chaining, referred to as "Pre-Proxy" in the UI. This allows users to route their main proxy's traffic through another proxy, effectively hiding their real IP from the final proxy server.

The data flow for a chain proxy is: [Browser] -> [Local Xray] -> [Pre-Proxy] -> [Main Proxy] -> [Target Website].

Sources: README.md, renderer.js:18-22, main.js:433-446

This is achieved by setting the proxySettings property on the main outbound object in the Xray configuration.

This diagram shows the difference between a standard and a chained proxy setup.

Management and Modes

Chain proxy settings are managed in the "Proxy Chain" modal in the UI. Users can add proxies manually or via subscriptions. The system supports several operational modes for the pre-proxy pool:

Mode	Description	Source
Single	Manually select one specific pre-proxy to use for all connections.	renderer.js:1012-1013, main.js:441
Load Balance	Randomly select a pre-proxy from the active pool for each new profile launch.	renderer.js:1014, main.js:442
Failover	Always use the first pre-proxy in the active list. (Implementation implies this, though not explicitly for failover logic).	renderer.js:1015, main.js:443

Sources: renderer.js:779-782, main.js:433-446

Network Utilities

Latency Testing

The application provides a utility to test the latency of proxy nodes.

1. The user clicks a "Test" button in the UI (renderer.js).
2. An IPC call to test-proxy-latency is made with the target proxy link.
3. The main.js handler spawns a temporary, minimal Xray instance configured only with the proxy to be tested.
4. It then makes an HTTP GET request to http://cp.cloudflare.com/generate_204 through this temporary instance using socks-proxy-agent.
5. The time taken for a successful response (HTTP 204) is measured and returned as the latency. The temporary Xray process is then terminated.

Sources: main.js:122-143, renderer.js:974-982

Subscription Management

Users can add proxy subscriptions to automatically populate the pre-proxy list. The system fetches the URL, decodes the Base64 content, and parses each line as a new proxy link. It also supports periodic automatic updates of these subscriptions.

Sources: renderer.js:907-930, renderer.js:446-460