Skip to content

Commit 22bcc7a

Browse files
Anton-DodonovAnton-Dodonov
committed
wrappers
1 parent eee2424 commit 22bcc7a

190 files changed

Lines changed: 10054 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CLAUDE.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Project Context: libh2
2+
3+
Library wrappers for h2.core HTTPS VPN.
4+
5+
## Structure
6+
7+
```
8+
libh2/
9+
├── wrappers/
10+
│ ├── gomobile/ # Go source for iOS/Android (H2Core.xcframework, h2core.aar)
11+
│ ├── cgo/ # C-API exports (libh2core.so)
12+
│ └── flutter_h2/ # Flutter plugin using gomobile wrappers
13+
├── build/
14+
│ └── gomobile.sh # Build script for mobile frameworks
15+
├── dist/ # Build outputs (not committed)
16+
└── flows/ # SDD flows for each wrapper
17+
```
18+
19+
## Responsibility
20+
21+
- **libh2**: Mobile/Flutter wrappers for h2.core
22+
- **h2.core**: Core code + CLI binaries (no wrappers)
23+
24+
## Active Flows
25+
26+
<!-- FLOWS_INDEX_START -->
27+
### SDD Flows (Spec-Driven)
28+
29+
| Name | Status File | Current Phase |
30+
|------|-------------|---------------|
31+
| `sdd-swift-h2` | `flows/sdd-swift-h2/_status.md` | IMPLEMENTATION (ready to build) |
32+
| `sdd-kotlin-h2` | `flows/sdd-kotlin-h2/_status.md` | IMPLEMENTATION (ready to build) |
33+
| `sdd-flutter-h2` | `flows/sdd-flutter-h2/_status.md` | COMPLETE |
34+
<!-- FLOWS_INDEX_END -->
35+
36+
## Build Commands
37+
38+
```bash
39+
# Build iOS framework
40+
./build/gomobile.sh ios
41+
42+
# Build Android AAR
43+
./build/gomobile.sh android
44+
45+
# Build both
46+
./build/gomobile.sh all
47+
```
48+
49+
## Dependencies
50+
51+
- h2.core (`../h2.core`) - via Go replace directive
52+
- gomobile - `go install golang.org/x/mobile/cmd/gomobile@latest`

‎flows/sdd-flutter-h2/01-requirements.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Requirements: flutter-h2
2+
3+
> Version: 1.0
4+
> Status: APPROVED
5+
> Last Updated: 2026-05-15
6+
7+
## Problem Statement
8+
9+
Flutter applications need a high-level API to use h2.core HTTPS VPN. The plugin should wrap the gomobile-compiled H2Core.xcframework (iOS) and h2core.aar (Android), providing a Dart API compatible with existing vpnclient_engine_flutter.
10+
11+
## User Stories
12+
13+
### Primary
14+
15+
**As a** Flutter developer
16+
**I want** a flutter_h2 plugin with same API as vpnclient_engine_flutter
17+
**So that** I can switch to h2.core by changing one import
18+
19+
**As a** Flutter developer
20+
**I want** access to the SOCKS5 proxy port
21+
**So that** I can configure HTTP clients to route traffic through h2.core
22+
23+
## Acceptance Criteria
24+
25+
### Must Have
26+
27+
1. **Given** flutter_h2 imported
28+
**When** accessing `VpnClientEngine.instance`
29+
**Then** singleton instance is returned
30+
31+
2. **Given** initialized engine
32+
**When** calling `connect()`
33+
**Then** SOCKS5 proxy starts and `getSocksPort()` returns port
34+
35+
3. **Given** active connection
36+
**When** subscribing to `statusStream`
37+
**Then** connection status updates are emitted
38+
39+
4. **Given** active connection
40+
**When** subscribing to `statsStream`
41+
**Then** traffic statistics are emitted
42+
43+
## API Compatibility
44+
45+
```dart
46+
// Same API as vpnclient_engine_flutter
47+
import 'package:flutter_h2/flutter_h2.dart';
48+
49+
final engine = VpnClientEngine.instance;
50+
51+
await engine.initialize(config);
52+
await engine.connect();
53+
54+
// H2-specific: get SOCKS5 port
55+
final port = engine.getSocksPort();
56+
// Configure HTTP: SOCKS5 127.0.0.1:$port
57+
58+
await engine.disconnect();
59+
```
60+
61+
## Constraints
62+
63+
- **iOS/Android only**: Desktop not supported
64+
- **SOCKS5 model**: Unlike TUN-based engines, provides local proxy
65+
- **No TUN**: App must configure HTTP client to use SOCKS5 proxy
66+
67+
## Dependencies
68+
69+
- H2Core.xcframework (from sdd-swift-h2)
70+
- h2core.aar (from sdd-kotlin-h2)
71+
72+
## References
73+
74+
- Implementation: `wrappers/flutter_h2/`
75+
- Tests: `wrappers/flutter_h2/test/`
76+
77+
---
78+
79+
## Approval
80+
81+
- [x] Reviewed by: User
82+
- [x] Approved on: 2026-05-15

‎flows/sdd-flutter-h2/_status.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# SDD Flow Status: flutter-h2
2+
3+
## Current Phase: COMPLETE
4+
## Status: DONE
5+
6+
## Progress
7+
8+
- [x] Requirements documented
9+
- [x] Requirements approved
10+
- [x] Specifications documented
11+
- [x] Specifications approved
12+
- [x] Plan created
13+
- [x] Plan approved
14+
- [x] Implementation complete
15+
16+
## Summary
17+
18+
Flutter plugin wrapping H2Core.xcframework (iOS) and h2core.aar (Android).
19+
Drop-in replacement for vpnclient_engine_flutter with same API.
20+
21+
## Related Files
22+
23+
- Implementation: `wrappers/flutter_h2/`
24+
- iOS plugin: `wrappers/flutter_h2/ios/Classes/FlutterH2Plugin.swift`
25+
- Android plugin: `wrappers/flutter_h2/android/.../FlutterH2Plugin.kt`
26+
- Dart API: `wrappers/flutter_h2/lib/src/vpnclient_engine.dart`
27+
28+
## Notes
29+
30+
- Started: 2026-05-15
31+
- Completed: 2026-05-15
32+
- 12/12 unit tests passing
33+
- SOCKS5 proxy model (not TUN)

‎flows/sdd-kotlin-h2/01-requirements.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Requirements: kotlin-h2
2+
3+
> Version: 1.0
4+
> Status: APPROVED
5+
> Last Updated: 2026-05-16
6+
7+
## Problem Statement
8+
9+
Android applications need to use h2.core HTTPS VPN. Since h2.core is written in Go, we need a gomobile wrapper that produces an Android-compatible AAR library (h2core.aar).
10+
11+
## User Stories
12+
13+
### Primary
14+
15+
**As an** Android developer
16+
**I want** an h2core.aar library
17+
**So that** I can integrate h2.core HTTPS VPN into my Android app
18+
19+
**As a** Flutter plugin developer
20+
**I want** h2core.aar with a simple API
21+
**So that** flutter_h2 can call it via platform channels
22+
23+
## Acceptance Criteria
24+
25+
### Must Have
26+
27+
1. **Given** gomobile installed
28+
**When** running `build/gomobile.sh android`
29+
**Then** h2core.aar is produced in `dist/`
30+
31+
2. **Given** the AAR library
32+
**When** imported in Kotlin
33+
**Then** `Mobile.newClient(serverAddr, cryptoProvider)` is available
34+
35+
3. **Given** a Client instance
36+
**When** calling `client.start()`
37+
**Then** returns local SOCKS5 port number
38+
39+
4. **Given** a running client
40+
**When** calling `client.stop()`
41+
**Then** cleanly shuts down the connection
42+
43+
## API Surface
44+
45+
```kotlin
46+
import mobile.Mobile
47+
48+
// Create client
49+
val client = Mobile.newClient("vpn.example.com:443", "us")
50+
51+
// Connect - returns SOCKS5 port
52+
val port = client.start()
53+
54+
// Check status
55+
val running = client.isRunning
56+
57+
// Get stats JSON
58+
val stats = client.statsJSON
59+
60+
// Disconnect
61+
client.stop()
62+
```
63+
64+
## Constraints
65+
66+
- **Gomobile types only**: String, Long, Boolean, ByteArray, Exception
67+
- **No complex types**: No maps, channels, or interfaces in public API
68+
- **Thread-safe**: All methods must be safe to call from any thread
69+
- **Min SDK**: Android API 21+ (Android 5.0)
70+
71+
## Dependencies
72+
73+
- h2.core: `github.com/vpnclient/https-vpn`
74+
- gomobile: `golang.org/x/mobile/cmd/gomobile`
75+
- Android NDK (for gomobile bind)
76+
77+
## References
78+
79+
- Source: `wrappers/gomobile/client.go`
80+
- Build: `build/gomobile.sh`
81+
82+
---
83+
84+
## Approval
85+
86+
- [x] Reviewed by: User
87+
- [x] Approved on: 2026-05-16

0 commit comments

Comments
 (0)