mirror of
https://github.com/EasyTier/EasyTier.git
synced 2026-08-06 04:29:52 +00:00
KKRainbow
d55e63b88e
Overhaul the WASI guest data plane for throughput and add the host capabilities it relies on. The externally driven Tokio runtime now runs its timer pre-turn only when a tracked deadline has expired, and all WASI-reachable timers (STUN, port mapping, WebClient, UDP flow cleanup) go through the portable time facade so conditional timer driving cannot starve them. Data plane: - Move read/write deadlines onto TCP and UDP resources with one ABI setter per direction, reuse a single expiration timer per resource, and drop timeout arguments from the four hot data-plane submissions (ABI v3). Checked absolute instants treat unrepresentable finite timeouts as unbounded instead of panicking. - Batch host traffic: vectored TCP frame writes combine queued slices into one host operation, and reads request a bounded 64 KiB while retaining excess bytes in the stream buffer. - Complete TCP writes inside the guest with cancellation-safe writes, reporting the completed prefix before honoring cancellation or timeout so hosts never replay bytes. - Repoll smoltcp egress immediately on zero poll delay, enlarge virtual UDP receive queues to 128 KiB payload with 128 metadata slots, and bound UDP session receive buffers to 8 KiB plus one byte while keeping oversized-datagram detection. Host integration: - Add optional algorithm-neutral AEAD seal/open imports with the ring backend as fallback, and pin the ring AES-128-GCM wire vector so the Go host stays interoperable. - Forward instance events to hosts through one best-effort, synchronous, non-blocking import. - Add a repository-owned build entry point for the Go host artifact: Binaryen 131 at -O4 with cached, SHA-256-verified official archives.
237 lines
5.5 KiB
Markdown
237 lines
5.5 KiB
Markdown
# Contributing to EasyTier
|
|
|
|
[中文版](CONTRIBUTING_zh.md)
|
|
|
|
Thank you for your interest in contributing to EasyTier! This document provides guidelines and instructions for contributing to the project.
|
|
|
|
## Table of Contents
|
|
|
|
- [Development Environment Setup](#development-environment-setup)
|
|
- [Prerequisites](#prerequisites)
|
|
- [Installation Steps](#installation-steps)
|
|
- [Project Structure](#project-structure)
|
|
- [Build Guide](#build-guide)
|
|
- [Building Core](#building-core)
|
|
- [Building GUI](#building-gui)
|
|
- [Building Mobile](#building-mobile)
|
|
- [Development Workflow](#development-workflow)
|
|
- [Testing Guidelines](#testing-guidelines)
|
|
- [Pull Request Guidelines](#pull-request-guidelines)
|
|
- [Additional Resources](#additional-resources)
|
|
|
|
## Development Environment Setup
|
|
|
|
### Prerequisites
|
|
|
|
#### Required Tools
|
|
- Node.js v21 or higher
|
|
- pnpm v9 or higher
|
|
- Rust toolchain (version 1.95)
|
|
- LLVM and Clang
|
|
- Protoc (Protocol Buffers compiler)
|
|
|
|
#### Platform-Specific Dependencies
|
|
|
|
**Linux (Ubuntu/Debian)**
|
|
```bash
|
|
# Core build dependencies
|
|
sudo apt-get update && sudo apt-get install -y \
|
|
musl-tools \
|
|
llvm \
|
|
clang \
|
|
protobuf-compiler
|
|
|
|
# GUI build dependencies
|
|
sudo apt install -y \
|
|
libwebkit2gtk-4.1-dev \
|
|
build-essential \
|
|
curl \
|
|
wget \
|
|
file \
|
|
libgtk-3-dev \
|
|
librsvg2-dev \
|
|
libxdo-dev \
|
|
libssl-dev \
|
|
libappindicator3-dev \
|
|
patchelf
|
|
|
|
# Testing dependencies
|
|
sudo apt install -y bridge-utils
|
|
```
|
|
|
|
**For Cross-Compilation**
|
|
- musl-cross toolchain (for MIPS and other architectures)
|
|
- Additional setup may be required (see `.github/workflows/` for details)
|
|
|
|
**For Android Development**
|
|
- Java 20
|
|
- Android SDK (Build Tools 34.0.0)
|
|
- Android NDK (26.0.10792818)
|
|
|
|
### Installation Steps
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone https://github.com/EasyTier/EasyTier.git
|
|
cd EasyTier
|
|
```
|
|
|
|
2. Install dependencies:
|
|
```bash
|
|
# Install Rust toolchain
|
|
rustup install 1.95
|
|
rustup default 1.95
|
|
|
|
# Install project dependencies
|
|
pnpm -r install
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
easytier/ # Core functionality and libraries
|
|
easytier-web/ # Web dashboard and frontend
|
|
easytier-gui/ # Desktop GUI application
|
|
.github/workflows/ # CI/CD configuration files
|
|
```
|
|
|
|
## Build Guide
|
|
|
|
### Building Core
|
|
|
|
```bash
|
|
# Standard build
|
|
cargo build --release
|
|
|
|
# Platform-specific builds
|
|
cargo build --release --target x86_64-unknown-linux-musl # Linux x86_64
|
|
cargo build --release --target aarch64-unknown-linux-musl # Linux ARM64
|
|
cargo build --release --target x86_64-apple-darwin # macOS x86_64
|
|
cargo build --release --target aarch64-apple-darwin # macOS M1/M2
|
|
cargo build --release --target x86_64-pc-windows-msvc # Windows x86_64
|
|
```
|
|
|
|
Build artifacts: `target/[target-triple]/release/`
|
|
|
|
### Building the WASI core
|
|
|
|
```bash
|
|
script/build-wasi-core.sh
|
|
```
|
|
|
|
This builds the `easytier-core` Go-host profile for `wasm32-wasip1`, then
|
|
optimizes it with the pinned official Binaryen release. Binaryen is downloaded
|
|
once into `target/binaryen/` and verified by SHA-256; set `WASM_OPT` to use an
|
|
existing matching binary.
|
|
|
|
### Building GUI
|
|
|
|
```bash
|
|
# 1. Build frontend
|
|
pnpm -r build
|
|
|
|
# 2. Build GUI application
|
|
cd easytier-gui
|
|
|
|
# Linux
|
|
pnpm tauri build --target x86_64-unknown-linux-gnu
|
|
|
|
# macOS
|
|
pnpm tauri build --target x86_64-apple-darwin # Intel
|
|
pnpm tauri build --target aarch64-apple-darwin # Apple Silicon
|
|
|
|
# Windows
|
|
pnpm tauri build --target x86_64-pc-windows-msvc # x64
|
|
```
|
|
|
|
Build artifacts: `easytier-gui/src-tauri/target/release/bundle/`
|
|
|
|
### Building Mobile
|
|
|
|
```bash
|
|
# 1. Install Android targets
|
|
rustup target add aarch64-linux-android
|
|
rustup target add armv7-linux-androideabi
|
|
rustup target add i686-linux-android
|
|
rustup target add x86_64-linux-android
|
|
|
|
# 2. Build Android application
|
|
cd easytier-gui
|
|
pnpm tauri android build
|
|
```
|
|
|
|
Build artifacts: `easytier-gui/src-tauri/gen/android/app/build/outputs/apk/universal/release/`
|
|
|
|
### Build Notes
|
|
|
|
1. Cross-compilation for ARM/MIPS requires additional setup
|
|
2. Windows builds need correct DLL files
|
|
3. Check `.github/workflows/` for detailed build configurations
|
|
|
|
## Development Workflow
|
|
|
|
1. Create a feature branch from `develop`:
|
|
```bash
|
|
git checkout develop
|
|
git checkout -b feature/your-feature-name
|
|
```
|
|
|
|
2. Make your changes following our coding standards
|
|
|
|
3. Write or update tests as needed
|
|
|
|
4. Use conventional commit messages:
|
|
```
|
|
feat: add new feature
|
|
fix: resolve bug
|
|
docs: update documentation
|
|
test: add tests
|
|
chore: update dependencies
|
|
```
|
|
|
|
5. Submit a pull request to `develop`
|
|
|
|
## Testing Guidelines
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Configure system (Linux)
|
|
sudo modprobe br_netfilter
|
|
sudo sysctl net.bridge.bridge-nf-call-iptables=0
|
|
sudo sysctl net.bridge.bridge-nf-call-ip6tables=0
|
|
|
|
# Run tests
|
|
cargo test --no-default-features --features=full --verbose
|
|
```
|
|
|
|
### Test Requirements
|
|
|
|
- Write tests for new features
|
|
- Maintain existing test coverage
|
|
- Tests should be isolated and repeatable
|
|
- Include both unit and integration tests
|
|
|
|
## Pull Request Guidelines
|
|
|
|
1. Target the `develop` branch
|
|
2. Ensure all tests pass
|
|
3. Include clear description and purpose
|
|
4. Reference related issues
|
|
5. Keep changes focused and atomic
|
|
6. Update documentation as needed
|
|
|
|
## Additional Resources
|
|
|
|
- [Issue Tracker](https://github.com/EasyTier/EasyTier/issues)
|
|
- [Project Documentation](https://github.com/EasyTier/EasyTier/wiki)
|
|
|
|
## Questions or Need Help?
|
|
|
|
Feel free to:
|
|
- Open an issue for questions
|
|
- Join our community discussions
|
|
- Reach out to maintainers
|
|
|
|
Thank you for contributing to EasyTier!
|