Skip to content

Commit 3ab78e5

Browse files
Anton-DodonovAnton-Dodonov
committed
Update LibXray integration and dependencies
1 parent 536e050 commit 3ab78e5

10 files changed

Lines changed: 795 additions & 79 deletions

File tree

‎.gitattributes‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1 @@
11
ios/Frameworks/LibXray.xcframework/**/LibXray filter=lfs diff=lfs merge=lfs -text
2-
*.apk filter=lfs diff=lfs merge=lfs -text
3-
*.so filter=lfs diff=lfs merge=lfs -text

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,9 @@ app.*.map.json
4848
**/android/.gradle/
4949
**/android/local.properties
5050
**/android/captures/
51+
*.apk
52+
*.aab
53+
*.so
5154

5255
# =============================================================================
5356
# IOS RELATED

‎LIBXRAY_INTEGRATION.md‎

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
1+
# LibXray Integration for Android
2+
3+
This document describes the libXray integration with vpnclient_engine_flutter for Android.
4+
5+
## Overview
6+
7+
The libXray integration provides native Xray-core functionality for Android through a Flutter plugin. This implementation uses gomobile to build the libXray Go library into an Android AAR file, which is then integrated into the Flutter plugin.
8+
9+
## Architecture
10+
11+
```
12+
Flutter App
13+
↓
14+
VPN Client Engine Flutter Plugin
15+
↓
16+
Android Native Layer (Kotlin)
17+
↓
18+
LibXray AAR (Go + gomobile)
19+
↓
20+
Xray-core
21+
```
22+
23+
## Components
24+
25+
### 1. LibXray AAR
26+
- Built from the libXray Go library using gomobile
27+
- Located at: `android/libs/libXray.aar`
28+
- Provides Go functions accessible from Android/Kotlin
29+
30+
### 2. LibXrayVpnService
31+
- Android VPN service that manages the VPN connection
32+
- Integrates with libXray to start/stop Xray-core
33+
- Handles socket protection and VPN interface management
34+
- Located at: `android/src/main/kotlin/.../LibXrayVpnService.kt`
35+
36+
### 3. VpnclientEngineFlutterPlugin
37+
- Main Flutter plugin class for Android
38+
- Handles method calls from Dart and communicates with LibXrayVpnService
39+
- Located at: `android/src/main/kotlin/.../VpnclientEngineFlutterPlugin.kt`
40+
41+
### 4. Android Platform Implementation
42+
- Dart implementation that calls native Android methods
43+
- Located at: `lib/platforms/android.dart`
44+
45+
### 5. LibXray Engine
46+
- High-level Dart API for libXray functionality
47+
- Located at: `lib/vpnclient_engine/engines/libxray_engine.dart`
48+
49+
## Features Implemented
50+
51+
### Core VPN Functionality
52+
- ✅ Connect with Xray configuration
53+
- ✅ Disconnect from VPN
54+
- ✅ Get connection status
55+
- ✅ VPN permission handling
56+
57+
### Additional Features
58+
- ✅ Test Xray configuration
59+
- ✅ Ping server with configuration
60+
- ✅ Get libXray version
61+
- ✅ Socket protection for Android VPN service
62+
63+
### Data Files
64+
- ✅ GeoIP and GeoSite data files included in assets
65+
- ✅ Automatic data directory setup
66+
67+
## Usage Example
68+
69+
```dart
70+
import 'package:vpnclient_engine_flutter/vpnclient_engine_flutter.dart';
71+
72+
// Create libXray engine
73+
final engine = EngineFactory.createEngine(EngineType.libxray);
74+
75+
// Request VPN permissions
76+
final permissionsGranted = await engine.requestPermissions();
77+
if (!permissionsGranted) {
78+
print('VPN permissions not granted');
79+
return;
80+
}
81+
82+
// Test configuration
83+
final configValid = await engine.testConfig(xrayConfigJson);
84+
if (!configValid) {
85+
print('Invalid configuration');
86+
return;
87+
}
88+
89+
// Connect to VPN
90+
final connected = await engine.connect(xrayConfigJson);
91+
if (connected) {
92+
print('Connected successfully');
93+
} else {
94+
print('Connection failed');
95+
}
96+
97+
// Check status
98+
final status = await engine.getConnectionStatus();
99+
print('Current status: $status');
100+
101+
// Disconnect
102+
await engine.disconnect();
103+
```
104+
105+
## Configuration Format
106+
107+
The libXray integration expects Xray configuration in JSON format. Example:
108+
109+
```json
110+
{
111+
"log": {
112+
"loglevel": "warning"
113+
},
114+
"inbounds": [
115+
{
116+
"port": 10808,
117+
"listen": "127.0.0.1",
118+
"protocol": "socks",
119+
"settings": {
120+
"udp": true
121+
}
122+
}
123+
],
124+
"outbounds": [
125+
{
126+
"protocol": "vless",
127+
"settings": {
128+
"vnext": [
129+
{
130+
"address": "example.com",
131+
"port": 443,
132+
"users": [
133+
{
134+
"id": "your-uuid-here",
135+
"encryption": "none",
136+
"flow": "xtls-rprx-vision"
137+
}
138+
]
139+
}
140+
]
141+
},
142+
"streamSettings": {
143+
"network": "tcp",
144+
"security": "tls",
145+
"tlsSettings": {
146+
"serverName": "example.com",
147+
"allowInsecure": false
148+
}
149+
}
150+
}
151+
]
152+
}
153+
```
154+
155+
## Android Permissions
156+
157+
The following permissions are required in your app's `AndroidManifest.xml`:
158+
159+
```xml
160+
<uses-permission android:name="android.permission.INTERNET" />
161+
<uses-permission android:name="android.permission.BIND_VPN_SERVICE" />
162+
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
163+
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
164+
```
165+
166+
## Build Requirements
167+
168+
### Prerequisites
169+
- Go 1.21 or later
170+
- gomobile tool
171+
- Android SDK and NDK
172+
173+
### Building libXray AAR
174+
175+
1. Navigate to the libXray directory:
176+
```bash
177+
cd libXray
178+
```
179+
180+
2. Install gomobile (if not already installed):
181+
```bash
182+
go install golang.org/x/mobile/cmd/gomobile@latest
183+
export PATH=$PATH:$(go env GOPATH)/bin
184+
gomobile init
185+
```
186+
187+
3. Build the AAR:
188+
```bash
189+
gomobile bind -target android -androidapi 21 -o libXray.aar .
190+
```
191+
192+
4. Copy to the Flutter plugin:
193+
```bash
194+
cp libXray.aar ../VPNclient-engine-flutter/android/libs/
195+
```
196+
197+
## Files Structure
198+
199+
```
200+
VPNclient-engine-flutter/
201+
├── android/
202+
│ ├── libs/
203+
│ │ └── libXray.aar # Built libXray library
204+
│ ├── src/main/
205+
│ │ ├── AndroidManifest.xml # Android manifest with permissions
206+
│ │ ├── assets/
207+
│ │ │ ├── geoip.dat # GeoIP data file
208+
│ │ │ └── geosite.dat # GeoSite data file
209+
│ │ └── kotlin/.../
210+
│ │ ├── LibXrayVpnService.kt # VPN service implementation
211+
│ │ └── VpnclientEngineFlutterPlugin.kt # Main plugin class
212+
│ └── build.gradle # Android build configuration
213+
├── lib/
214+
│ ├── platforms/
215+
│ │ └── android.dart # Android platform implementation
216+
│ └── vpnclient_engine/engines/
217+
│ └── libxray_engine.dart # LibXray engine implementation
218+
└── example/
219+
└── lib/
220+
└── libxray_example.dart # Usage example
221+
```
222+
223+
## Troubleshooting
224+
225+
### Common Issues
226+
227+
1. **Build Errors**
228+
- Ensure Go version is compatible (1.21+)
229+
- Check that gomobile is properly installed and in PATH
230+
- Verify Android SDK and NDK are properly configured
231+
232+
2. **VPN Permission Issues**
233+
- Make sure your app requests VPN permissions properly
234+
- Check that `android.permission.BIND_VPN_SERVICE` is declared in manifest
235+
236+
3. **Connection Issues**
237+
- Verify Xray configuration is valid JSON
238+
- Check that geo data files are properly included in assets
239+
- Ensure the VPN service has proper foreground service permissions
240+
241+
4. **Service Issues**
242+
- Check that the LibXrayVpnService is properly declared in AndroidManifest.xml
243+
- Verify socket protection is working correctly
244+
245+
### Debugging
246+
247+
Enable debug logging by checking Android Studio logs for messages tagged with:
248+
- `VpnclientEngineFlutterPlugin`
249+
- `LibXrayVpnService`
250+
- `AndroidVpnclientEngineFlutter`
251+
252+
## Future Improvements
253+
254+
- [ ] Implement real ping functionality using libXray
255+
- [ ] Add traffic statistics monitoring
256+
- [ ] Improve error handling and reporting
257+
- [ ] Add configuration validation
258+
- [ ] Implement connection status callbacks
259+
- [ ] Add support for custom geo data files
260+
261+
## Dependencies
262+
263+
- libXray (Go library)
264+
- Xray-core
265+
- gomobile
266+
- Android VPN API
267+
- Flutter method channels

‎android/src/main/AndroidManifest.xml‎

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,26 @@
11
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
2-
package="click.vpnclient.engine.flutter.vpnclient_engine_flutter">
3-
</manifest>
2+
package="click.vpnclient.engine.flutter.vpnclient_engine_flutter">
3+
4+
<!-- Permissions required for VPN functionality -->
5+
<uses-permission android:name="android.permission.INTERNET" />
6+
<uses-permission android:name="android.permission.BIND_VPN_SERVICE" />
7+
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
8+
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
9+
10+
<application>
11+
<!-- LibXray VPN Service -->
12+
<service
13+
android:name=".LibXrayVpnService"
14+
android:enabled="true"
15+
android:exported="false"
16+
android:permission="android.permission.BIND_VPN_SERVICE"
17+
android:foregroundServiceType="specialUse">
18+
<intent-filter>
19+
<action android:name="android.net.VpnService" />
20+
</intent-filter>
21+
<property
22+
android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE"
23+
android:value="vpn" />
24+
</service>
25+
</application>
26+
</manifest>

‎example/ios/Pods/Manifest.lock‎

Lines changed: 0 additions & 34 deletions
This file was deleted.

0 commit comments

Comments
 (0)