Skip to content

Commit bff08b8

Browse files
Anton-DodonovAnton-Dodonov
committed
integrations
1 parent 3741ff2 commit bff08b8

2 files changed

Lines changed: 280 additions & 0 deletions

File tree

‎flows/sdd-h2.core-integrations/01-requirements.md‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
# Requirements: h2.core Integrations
2+
3+
> Version: 1.0
4+
> Status: DRAFT
5+
> Last Updated: 2026-05-14
6+
7+
## Problem Statement
8+
9+
h2.core is currently a standalone CLI tool (`cmd/https-vpn`). To be useful in mobile apps, desktop applications, and as a library component, we need to expose h2.core's functionality through various integration interfaces.
10+
11+
Current state:
12+
- ✅ CLI binary (`https-vpn run`, `https-vpn init`)
13+
- ✅ Go API (`core.New()`, `core.Start()`, `core.Close()`)
14+
- ❌ No C-API for native bindings
15+
- ❌ No gomobile support for iOS/Android
16+
- ❌ No HTTP/gRPC control API
17+
- ❌ No library build (.so/.dylib/.a)
18+
19+
## User Stories
20+
21+
### Primary: Mobile Integration
22+
23+
**As a** mobile app developer using vpnclient_engine_flutter
24+
**I want** to integrate h2.core as a VPN core
25+
**So that** my users can connect via HTTPS VPN that evades DPI
26+
27+
### Secondary: Desktop Library
28+
29+
**As a** desktop application developer
30+
**I want** to link h2.core as a shared library
31+
**So that** I can embed HTTPS VPN functionality without process management
32+
33+
### Tertiary: Remote Management
34+
35+
**As a** system administrator
36+
**I want** an HTTP API to control h2.core instances
37+
**So that** I can manage VPN servers programmatically
38+
39+
## Integration Types
40+
41+
### 1. C-API (CGO Export)
42+
43+
Expose h2.core functions via C-compatible API for FFI bindings.
44+
45+
```c
46+
// Proposed C API
47+
typedef void* H2Instance;
48+
49+
H2Instance h2_create(const char* config_json);
50+
int h2_start(H2Instance instance);
51+
int h2_stop(H2Instance instance);
52+
void h2_destroy(H2Instance instance);
53+
const char* h2_version();
54+
const char* h2_get_stats(H2Instance instance);
55+
```
56+
57+
**Use cases:**
58+
- vpnclient_engine_flutter (via dart:ffi → C++)
59+
- Python bindings (via ctypes/cffi)
60+
- Ruby, Node.js FFI bindings
61+
62+
### 2. Gomobile Library
63+
64+
Build h2.core as iOS Framework / Android AAR via gomobile.
65+
66+
```go
67+
// Proposed gomobile-friendly API (mobile package)
68+
package mobile
69+
70+
func NewClient(configJSON string) (*Client, error)
71+
func (c *Client) Start() error
72+
func (c *Client) Stop() error
73+
func (c *Client) GetStats() string
74+
```
75+
76+
**Use cases:**
77+
- Native iOS apps (Swift/Objective-C)
78+
- Native Android apps (Kotlin/Java)
79+
- React Native (via native modules)
80+
- Flutter (via platform channels)
81+
82+
### 3. HTTP Control API
83+
84+
REST API for managing h2.core instances.
85+
86+
```
87+
POST /api/v1/start - Start VPN with config
88+
POST /api/v1/stop - Stop VPN
89+
GET /api/v1/status - Get current status
90+
GET /api/v1/stats - Get traffic statistics
91+
```
92+
93+
**Use cases:**
94+
- Remote management dashboards
95+
- Kubernetes/Docker orchestration
96+
- CLI tools communicating with daemon
97+
98+
### 4. Process-Based Integration (Current)
99+
100+
Spawn `https-vpn` binary as child process, communicate via:
101+
- Command-line arguments
102+
- stdout/stderr for logs
103+
- Unix signals for control
104+
105+
**Use cases:**
106+
- Quick integration without library compilation
107+
- Sandboxed execution
108+
- Crash isolation
109+
110+
## Acceptance Criteria
111+
112+
### Must Have
113+
114+
1. **C-API Export**
115+
- `h2_create()`, `h2_start()`, `h2_stop()`, `h2_destroy()` functions
116+
- Build as shared library (.so, .dylib)
117+
- Works with vpnclient_engine_flutter FFI
118+
119+
2. **Gomobile Build**
120+
- Build iOS Framework
121+
- Build Android AAR
122+
- Simple API suitable for mobile
123+
124+
3. **Version & Stats API**
125+
- `h2_version()` returns version string
126+
- `h2_get_stats()` returns JSON stats
127+
128+
### Should Have
129+
130+
4. **HTTP Control API**
131+
- Start/stop via HTTP
132+
- Status and stats endpoints
133+
- Optional TLS for control API
134+
135+
5. **Client Mode Support**
136+
- Not just server mode - client mode for mobile use
137+
- SOCKS5 local proxy interface
138+
139+
### Won't Have (This Iteration)
140+
141+
- gRPC API (HTTP sufficient for now)
142+
- Prometheus metrics endpoint
143+
- Hot config reload
144+
- Multiple simultaneous instances
145+
146+
## Constraints
147+
148+
- **Technical**: CGO required for C-API, adds build complexity
149+
- **Platform**: gomobile limits to iOS/Android; C-API works everywhere
150+
- **Size**: gomobile binaries tend to be large (~10-20MB)
151+
- **Compatibility**: Must maintain existing CLI interface
152+
153+
## Architecture
154+
155+
```
156+
┌─────────────────────────────────────────────────────────────────┐
157+
│ h2.core │
158+
├─────────────────────────────────────────────────────────────────┤
159+
│ core/ │ transport/ │ crypto/ │
160+
│ (Instance API) │ (H2Server,Client) │ (providers) │
161+
├─────────────────────────────────────────────────────────────────┤
162+
│ Integration Layer │
163+
├────────────┬────────────┬────────────┬────────────┬─────────────┤
164+
│ C-API │ gomobile │ HTTP API │ CLI │ (future) │
165+
│ (cgo/) │ (mobile/) │ (api/) │ (cmd/) │ │
166+
└────────────┴────────────┴────────────┴────────────┴─────────────┘
167+
│ │ │ │
168+
▼ ▼ ▼ ▼
169+
.so/.dylib .framework localhost subprocess
170+
FFI bindings /AAR :8080 mgmt
171+
```
172+
173+
## File Structure Proposal
174+
175+
```
176+
h2.core/
177+
├── core/ # Existing - main Instance API
178+
├── transport/ # Existing - H2Server, H2Client
179+
├── crypto/ # Existing - crypto providers
180+
├── infra/conf/ # Existing - config parsing
181+
├── cmd/https-vpn/ # Existing - CLI
182+
├── cgo/ # NEW - C-API exports
183+
│ ├── h2.go # CGO export functions
184+
│ └── h2.h # C header
185+
├── mobile/ # NEW - gomobile package
186+
│ ├── client.go # Mobile-friendly API
187+
│ └── doc.go # Package docs
188+
├── api/ # NEW - HTTP control API
189+
│ ├── server.go # HTTP server
190+
│ └── handlers.go # API handlers
191+
└── build/
192+
├── unix.sh # Existing
193+
├── cgo.sh # NEW - Build shared library
194+
└── mobile.sh # NEW - Build iOS/Android
195+
```
196+
197+
## Open Questions
198+
199+
- [ ] Should C-API support both client and server modes?
200+
- [ ] What stats should `h2_get_stats()` return? (bytes in/out, connections, etc.)
201+
- [ ] Should gomobile build include all crypto providers or be configurable?
202+
- [ ] HTTP API authentication mechanism?
203+
204+
## Priority Order
205+
206+
1. **C-API** (highest) - Required for vpnclient_engine_flutter
207+
2. **Gomobile** (high) - Required for native mobile apps
208+
3. **HTTP API** (medium) - Nice-to-have for management
209+
4. **Process-based** (existing) - Already works
210+
211+
## References
212+
213+
- h2.core README: `README.md`
214+
- vpnclient_engine_flutter: `engines/vpnclient_engine_flutter/`
215+
- gomobile docs: https://pkg.go.dev/golang.org/x/mobile/cmd/gomobile
216+
- CGO docs: https://pkg.go.dev/cmd/cgo
217+
218+
---
219+
220+
## Approval
221+
222+
- [ ] Reviewed by: User
223+
- [ ] Approved on: [date]
224+
- [ ] Notes: [any conditions or clarifications]

‎flows/sdd-h2.core-integrations/_status.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Status: sdd-h2.core-integrations
2+
3+
## Current Phase
4+
5+
REQUIREMENTS
6+
7+
## Phase Status
8+
9+
DRAFTING
10+
11+
## Last Updated
12+
13+
2026-05-14 by Claude
14+
15+
## Blockers
16+
17+
- None
18+
19+
## Progress
20+
21+
- [x] Requirements drafted
22+
- [ ] Requirements approved
23+
- [ ] Specifications drafted
24+
- [ ] Specifications approved
25+
- [ ] Plan drafted
26+
- [ ] Plan approved
27+
- [ ] Implementation started
28+
- [ ] Implementation complete
29+
30+
## Context Notes
31+
32+
Key decisions and context for resuming:
33+
34+
- h2.core is currently CLI-only (cmd/https-vpn)
35+
- No C-API/CGO exports exist - pure Go binary
36+
- Has both server (H2Server) and client (H2Client) components
37+
- Client implements net.Dialer interface via DialContext
38+
- Need to add integration layer for external consumers
39+
40+
## Integration Targets Identified
41+
42+
1. **vpnclient_engine_flutter** - Flutter VPN client engine
43+
2. **gomobile** - iOS/Android library via gomobile
44+
3. **C-API** - For native integration (CGO exports)
45+
4. **HTTP API** - For remote control/management
46+
47+
## Fork History
48+
49+
- Not forked
50+
- Created fresh for integration planning
51+
52+
## Next Actions
53+
54+
1. Complete requirements elicitation
55+
2. Get user approval on requirements
56+
3. Draft specifications for each integration type

0 commit comments

Comments
 (0)