fix: address dns review issues

fix: address dns review feedback
fix: clear cargo audit vulnerabilities
2026-09-20 11:22:39 +00:00 · 2026-06-24 00:22:29 +08:00 · 2026-06-24 00:09:37 +08:00 · 2026-06-23 21:49:27 +08:00 · 2026-06-23 21:48:05 +08:00 · 2026-06-22 10:54:48 +08:00
578 changed files with 143060 additions and 25034 deletions
@@ -0,0 +1,3 @@
+[advisories]
+# openidconnect 4.0.1 depends on rsa 0.9.10, and RUSTSEC-2023-0071 has no fixed upgrade.
+ignore = ["RUSTSEC-2023-0071"]
@@ -1,77 +1,88 @@
-[target.x86_64-unknown-linux-musl]
-linker = "rust-lld"
-rustflags = ["-C", "linker-flavor=ld.lld"]
+# region Native
+
+[target.x86_64-unknown-linux-gnu]
+rustflags = ["-C", "link-arg=-fuse-ld=mold"]

 [target.aarch64-unknown-linux-gnu]
-linker = "aarch64-linux-gnu-gcc"
-
-[target.aarch64-unknown-linux-musl]
-linker = "aarch64-linux-musl-gcc"
-rustflags = ["-C", "target-feature=+crt-static"]
+rustflags = ["-C", "link-arg=-fuse-ld=mold"]

 [target.'cfg(all(windows, target_env = "msvc"))']
 rustflags = ["-C", "target-feature=+crt-static"]

-[target.mipsel-unknown-linux-musl]
-linker = "mipsel-linux-muslsf-gcc"
-rustflags = [
-    "-C",
-    "target-feature=+crt-static",
-    "-L",
-    "./musl_gcc/mipsel-linux-muslsf-cross/mipsel-linux-muslsf/lib",
-    "-L",
-    "./musl_gcc/mipsel-linux-muslsf-cross/lib/gcc/mipsel-linux-muslsf/11.2.1",
-    "-l",
-    "atomic",
-    "-l",
-    "ctz",
-]
+# region

-[target.mips-unknown-linux-musl]
-linker = "mips-linux-muslsf-gcc"
-rustflags = [
-    "-C",
-    "target-feature=+crt-static",
-    "-L",
-    "./musl_gcc/mips-linux-muslsf-cross/mips-linux-muslsf/lib",
-    "-L",
-    "./musl_gcc/mips-linux-muslsf-cross/lib/gcc/mips-linux-muslsf/11.2.1",
-    "-l",
-    "atomic",
-    "-l",
-    "ctz",
-]
+# region CI
+
+[target.x86_64-unknown-linux-musl]
+rustflags = ["-C", "target-feature=+crt-static"]
+
+[target.aarch64-unknown-linux-musl]
+rustflags = ["-C", "target-feature=+crt-static"]
+
+[target.riscv64gc-unknown-linux-musl]
+rustflags = ["-C", "target-feature=+crt-static"]

 [target.armv7-unknown-linux-musleabihf]
-linker = "armv7l-linux-musleabihf-gcc"
 rustflags = ["-C", "target-feature=+crt-static"]

 [target.armv7-unknown-linux-musleabi]
-linker = "armv7m-linux-musleabi-gcc"
 rustflags = ["-C", "target-feature=+crt-static"]

 [target.arm-unknown-linux-musleabihf]
-linker = "arm-linux-musleabihf-gcc"
-rustflags = [
-    "-C",
-    "target-feature=+crt-static",
-    "-L",
-    "./musl_gcc/arm-linux-musleabihf-cross/arm-linux-musleabihf/lib",
-    "-L",
-    "./musl_gcc/arm-linux-musleabihf-cross/lib/gcc/arm-linux-musleabihf/11.2.1",
-    "-l",
-    "atomic",
-]
+rustflags = ["-C", "target-feature=+crt-static"]

 [target.arm-unknown-linux-musleabi]
-linker = "arm-linux-musleabi-gcc"
+rustflags = ["-C", "target-feature=+crt-static"]
+
+[target.loongarch64-unknown-linux-musl]
+rustflags = ["-C", "target-feature=+crt-static"]
+
+[target.mipsel-unknown-linux-musl]
+linker = "mipsel-unknown-linux-muslsf-gcc"
 rustflags = [
    "-C",
    "target-feature=+crt-static",
    "-L",
-    "./musl_gcc/arm-linux-musleabi-cross/arm-linux-musleabi/lib",
+    "./musl_gcc/mipsel-unknown-linux-muslsf/mipsel-unknown-linux-muslsf/lib",
    "-L",
-    "./musl_gcc/arm-linux-musleabi-cross/lib/gcc/arm-linux-musleabi/11.2.1",
+    "./musl_gcc/mipsel-unknown-linux-muslsf/mipsel-unknown-linux-muslsf/sysroot/usr/lib",
+    "-L",
+    "./musl_gcc/mipsel-unknown-linux-muslsf/lib/gcc/mipsel-unknown-linux-muslsf/15.1.0",
    "-l",
    "atomic",
+    "-l",
+    "ctz",
+    "-l",
+    "gcc",
 ]
+
+[target.mips-unknown-linux-musl]
+linker = "mips-unknown-linux-muslsf-gcc"
+rustflags = [
+    "-C",
+    "target-feature=+crt-static",
+    "-L",
+    "./musl_gcc/mips-unknown-linux-muslsf/mips-unknown-linux-muslsf/lib",
+    "-L",
+    "./musl_gcc/mips-unknown-linux-muslsf/mips-unknown-linux-muslsf/sysroot/usr/lib",
+    "-L",
+    "./musl_gcc/mips-unknown-linux-muslsf/lib/gcc/mips-unknown-linux-muslsf/15.1.0",
+    "-l",
+    "atomic",
+    "-l",
+    "ctz",
+    "-l",
+    "gcc",
+]
+
+[target.aarch64-unknown-linux-ohos]
+ar = "/usr/local/ohos-sdk/linux/native/llvm/bin/llvm-ar"
+linker = "/home/runner/sdk/native/llvm/aarch64-unknown-linux-ohos-clang.sh"
+
+[target.aarch64-unknown-linux-ohos.env]
+PKG_CONFIG_PATH = "/usr/local/ohos-sdk/linux/native/sysroot/usr/lib/pkgconfig:/usr/local/ohos-sdk/linux/native/sysroot/usr/local/lib/pkgconfig"
+PKG_CONFIG_LIBDIR = "/usr/local/ohos-sdk/linux/native/sysroot/usr/lib:/usr/local/ohos-sdk/linux/native/sysroot/usr/local/lib"
+PKG_CONFIG_SYSROOT_DIR = "/usr/local/ohos-sdk/linux/native/sysroot"
+SYSROOT = "/usr/local/ohos-sdk/linux/native/sysroot"
+
+# endregion
@@ -0,0 +1,2 @@
+PROFILE=$(cat .flake-profile 2>/dev/null)
+use flake .#${PROFILE}
@@ -23,31 +23,113 @@ body:
  - type: textarea
    id: description
    attributes:
-      label: 描述问题 / Describe the bug
-      description: 对 bug 的明确描述。如果条件允许，请包括屏幕截图。 / A clear description of what the bug is. Include screenshots if applicable.
-      placeholder: 问题描述 / Bug description
+      label: 问题简要描述 / Brief Description
+      description: 对问题的简要描述，包括期望的行为和实际发生的情况。 / A brief description of the issue, including expected vs actual behavior.
+      placeholder: |
+        例如：节点 A 无法连接到节点 B，期望能够正常建立连接
+        Example: Node A cannot connect to Node B, expected to establish connection normally
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment-info
+    attributes:
+      label: 环境信息 / Environment Information
+      description: 请提供网络拓扑、节点信息和系统环境详情。 / Please provide network topology, node information and system environment details.
+      placeholder: |
+        **EasyTier 版本（非常重要）/ EasyTier Version (Very Important):** v1.2.0
+        
+        **网络拓扑 / Network Topology:**
+        - 节点 A (10.1.1.1): Windows 11 Pro 22H2, Wifi，有 IPV6 地址
+        - 节点 B (10.1.1.2): Ubuntu 22.04.3 LTS (Linux 5.15.0-72-generic), 公网 IP
+        - 节点 C (10.1.1.3): macOS Ventura 13.4.1, 5G 流量，无 IPV6 地址
+        
+        **Network Topology:**
+        - Node A (10.1.1.1): Windows 11 Pro 22H2, Wifi, has IPV6 address
+        - Node B (10.1.1.2): Ubuntu 22.04.3 LTS (Linux 5.15.0-72-generic), public IP
+        - Node C (10.1.1.3): macOS Ventura 13.4.1, 5G traffic, no IPV6 address
+    validations:
+      required: true
+
+  - type: textarea
+    id: node-configs
+    attributes:
+      label: 节点配置 / Node Configurations
+      description: 请提供每个节点的配置文件或启动参数。 / Please provide configuration files or startup parameters for each node.
+      placeholder: |
+        **节点 A 配置 / Node A Config:**
+        ```
+        easytier-core --config-file config.toml
+        ```
+        
+        **节点 B 配置 / Node B Config:**
+        ```
+        easytier-core --ipv4 10.1.1.2 --peers tcp://1.2.3.4:11010
+        ```
+        
+        请贴出完整的配置文件内容或命令行参数
+        Please paste complete configuration file contents or command line arguments
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: 日志信息 / Log Information
+      description: 请提供相关的日志信息，包括 GUI 的事件日志或命令行的控制台输出。 / Please provide relevant log information, including GUI event logs or command line console output.
+      placeholder: |
+        请粘贴相关的日志信息：
+        - GUI 用户：请提供事件日志中的错误信息
+        - 命令行用户：请提供控制台输出的详细日志
+        - 一般情况下，提供默认输出的事件日志即可
+        - 如果能提供 --file-log-level debug 输出的日志，会更方便 debug
+        
+        Please paste relevant log information:
+        - GUI users: Please provide error messages from event logs
+        - CLI users: Please provide detailed console output logs
+        - Default log output is usually sufficient
+        - If possible, logs with --file-log-level debug would be more helpful for debugging
+        
    validations:
      required: true

  - type: textarea
    id: reproduction
    attributes:
-      label: 重现步骤 / Reproduction
-      description: 能够重现行为的步骤或指向能够复现的存储库链接。 / A link to a reproduction repo or steps to reproduce the behaviour.
+      label: 重现步骤 / Reproduction Steps
+      description: 请提供详细的步骤来重现这个问题。 / Please provide detailed steps to reproduce this issue.
      placeholder: |
-        请提供一个最小化的复现示例或复现步骤，请参考这个指南 https://stackoverflow.com/help/minimal-reproducible-example
-        Please provide a minimal reproduction or steps to reproduce, see this guide https://stackoverflow.com/help/minimal-reproducible-example
-        为什么需要重现（问题）？请参阅这篇文章 https://antfu.me/posts/why-reproductions-are-required
-        Why reproduction is required? see this article https://antfu.me/posts/why-reproductions-are-required
+        1. 启动节点 A，使用配置 xxx / Start Node A with config xxx
+        2. 启动节点 B，使用配置 yyy / Start Node B with config yyy  
+        3. 尝试从节点 A ping 节点 B / Try to ping Node B from Node A
+        4. 观察到错误：xxx / Observe error: xxx
+        
+        请提供详细的操作步骤，以便我们能够重现问题
+        Please provide detailed steps so we can reproduce the issue
+    validations:
+      required: true

  - type: textarea
    id: expected-behavior
    attributes:
-      label: 预期结果 / Expected behavior
+      label: 预期结果 / Expected Behavior
      description: 清楚地描述您期望发生的事情。 / A clear description of what you expected to happen.
+      placeholder: |
+        例如：节点 A 应该能够成功 ping 通节点 B，延迟在 100ms 以内
+        Example: Node A should be able to ping Node B successfully with latency under 100ms

  - type: textarea
-    id: context
+    id: additional-context
    attributes:
-      label: 额外上下文 / Additional context 
-      description:  在这里添加关于问题的任何其他上下文。 / Add any other context about the problem here.
+      label: 额外信息 / Additional Context
+      description: 在这里添加关于问题的任何其他上下文信息。 / Add any other context about the problem here.
+      placeholder: |
+        例如：
+        - 这个问题是否在特定时间出现？
+        - 是否有网络环境的特殊配置？
+        - 是否尝试过其他解决方案？
+        
+        Example:
+        - Does this issue occur at specific times?
+        - Are there any special network environment configurations?
+        - Have you tried any other solutions?
@@ -3,36 +3,177 @@

 name: 💡 新功能请求 / Feature Request
 title: '[feat] '
-description: 提出一个想法 /  Suggest an idea
+description: 提出一个想法 / Suggest an idea
 labels: ['type: feature request']

 body:
-  - type: textarea
-    id: problem
+  - type: markdown
    attributes:
-      label: 描述问题 / Describe the problem
-      description: 明确描述此功能将解决的问题 / A clear description of the problem this feature would solve
-      placeholder: "我总是在...感觉困惑 / I'm always frustrated when..."
+      value: |
+        ## 提交功能请求前请注意 / Before Submitting
+        1. 请先搜索 [现有的功能请求](https://github.com/EasyTier/EasyTier/issues?q=is%3Aissue+label%3A%22type%3A+feature+request%22) 确保您的想法尚未被提出。
+        1. Please search [existing feature requests](https://github.com/EasyTier/EasyTier/issues?q=is%3Aissue+label%3A%22type%3A+feature+request%22) to ensure your idea hasn't been suggested already.
+        2. 请确保这个功能确实适合 EasyTier 项目的目标和范围。
+        2. Please ensure this feature fits within EasyTier's goals and scope.
+        3. 考虑这个功能是否能让更多用户受益，而不只是解决个人需求。
+        3. Consider whether this feature would benefit many users, not just personal needs.
+
+  - type: dropdown
+    id: feature-category
+    attributes:
+      label: 功能类别 / Feature Category
+      description: 请选择这个功能请求属于哪个类别 / Please select which category this feature request belongs to
+      options:
+        - 网络连接 / Network Connectivity
+        - 安全和加密 / Security & Encryption  
+        - 性能优化 / Performance Optimization
+        - 用户界面 / User Interface
+        - 配置管理 / Configuration Management
+        - 监控和日志 / Monitoring & Logging
+        - 平台支持 / Platform Support
+        - API 和集成 / API & Integration
+        - 其他 / Other
    validations:
      required: true

  - type: textarea
-    id: solution
+    id: use-case
    attributes:
-      label: "描述您想要的解决方案 / Describe the solution you'd like"
-      description: 明确说明您希望做出的改变 / A clear description of what change you would like
-      placeholder: '我希望... / I would like to...'
+      label: 使用场景 / Use Case
+      description: 描述您希望这个功能解决的具体使用场景或问题 / Describe the specific use case or problem you want this feature to solve
+      placeholder: |
+        例如：
+        - 作为企业用户，我需要在多个分支机构之间建立安全的网络连接
+        - 作为开发者，我希望能够通过 API 监控网络状态
+        - 作为系统管理员，我需要更详细的连接日志来排查问题
+        
+        Example:
+        - As an enterprise user, I need to establish secure network connections between multiple branch offices
+        - As a developer, I want to monitor network status through APIs
+        - As a system administrator, I need more detailed connection logs for troubleshooting
    validations:
      required: true

+  - type: textarea
+    id: current-limitations
+    attributes:
+      label: 当前限制 / Current Limitations
+      description: 描述当前 EasyTier 的哪些限制阻止了您实现这个使用场景 / Describe what current limitations in EasyTier prevent you from achieving this use case
+      placeholder: |
+        例如：
+        - 目前不支持基于用户角色的访问控制
+        - 缺少对 IPv6 的完整支持
+        - 没有提供 REST API 来获取网络状态
+        
+        Example:
+        - Currently lacks role-based access control
+        - Missing complete IPv6 support
+        - No REST API available for network status
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed-solution
+    attributes:
+      label: 建议的解决方案 / Proposed Solution
+      description: 详细描述您希望添加的功能以及它应该如何工作 / Describe in detail the feature you'd like to add and how it should work
+      placeholder: |
+        请描述：
+        - 功能的具体实现方式
+        - 用户界面或 API 设计
+        - 配置选项和参数
+        - 与现有功能的集成方式
+        
+        Please describe:
+        - Specific implementation approach
+        - User interface or API design
+        - Configuration options and parameters  
+        - Integration with existing features
+    validations:
+      required: true
+
+  - type: textarea
+    id: benefits
+    attributes:
+      label: 预期收益 / Expected Benefits
+      description: 说明这个功能会带来什么好处，会影响哪些用户群体 / Explain what benefits this feature would bring and which user groups it would affect
+      placeholder: |
+        例如：
+        - 提高网络连接的稳定性和性能
+        - 简化大规模部署的管理复杂度
+        - 增强企业用户的安全性需求
+        - 降低新用户的学习成本
+        
+        Example:
+        - Improve network connection stability and performance
+        - Simplify management complexity for large-scale deployments
+        - Enhance security requirements for enterprise users
+        - Reduce learning curve for new users
+
+  - type: textarea
+    id: technical-considerations
+    attributes:
+      label: 技术考虑 / Technical Considerations
+      description: 如果您了解技术细节，请分享相关的技术考虑或约束 / If you have technical knowledge, please share relevant technical considerations or constraints
+      placeholder: |
+        例如：
+        - 可能需要修改网络协议栈
+        - 需要考虑跨平台兼容性
+        - 可能影响现有性能
+        - 依赖第三方库或协议
+        
+        Example:
+        - May require modifications to network protocol stack
+        - Cross-platform compatibility needs consideration
+        - Potential impact on existing performance
+        - Dependencies on third-party libraries or protocols
+
  - type: textarea
    id: alternatives
    attributes:
-      label: 替代方案 / Alternatives considered
-      description: "您考虑过的任何替代解决方案 / Any alternative solutions you've considered"
+      label: 备选方案 / Alternative Solutions
+      description: 您是否考虑过其他解决方案？是否有现有的替代方案？ / Have you considered other solutions? Are there existing alternatives?
+      placeholder: |
+        例如：
+        - 使用第三方工具 X 可以部分解决，但缺少 Y 功能
+        - 通过脚本workaround可以实现，但不够优雅
+        - 其他类似项目 Z 有这个功能，可以参考其实现
+        
+        Example:
+        - Third-party tool X can partially solve this, but lacks Y functionality
+        - Can be achieved through script workarounds, but not elegant
+        - Similar project Z has this feature, could reference its implementation

  - type: textarea
-    id: context
+    id: implementation-priority
    attributes:
-      label: 额外上下文 / Additional context
-      description: 在此处添加有关问题的任何其他上下文。 / Add any other context about the problem here.
+      label: 实现优先级 / Implementation Priority
+      description: 这个功能对您有多重要？是否有时间要求？ / How important is this feature to you? Any time requirements?
+      placeholder: |
+        例如：
+        - 高优先级：阻碍了我们的生产部署
+        - 中优先级：会显著改善用户体验
+        - 低优先级：锦上添花的功能
+        
+        Example:
+        - High priority: Blocking our production deployment
+        - Medium priority: Would significantly improve user experience
+        - Low priority: Nice-to-have feature
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: 补充信息 / Additional Context
+      description: 添加任何其他相关信息，如截图、链接、参考资料等 / Add any other relevant information such as screenshots, links, or references
+      placeholder: |
+        例如：
+        - 相关的 RFC 或技术规范
+        - 其他项目的实现示例
+        - 用户调研或反馈数据
+        - 设计草图或流程图
+        
+        Example:
+        - Relevant RFCs or technical specifications
+        - Implementation examples from other projects
+        - User research or feedback data
+        - Design sketches or flowcharts
@@ -0,0 +1,90 @@
+name: prepare-build
+author: Luna
+description: Prepare build environment
+inputs:
+  target:
+    description: 'The target to build for'
+    required: false
+  pnpm:
+    description: 'Whether to run pnpm build'
+    required: true
+    default: 'true'
+  pnpm-build-filter:
+    description: 'The filter argument for pnpm build (e.g. ./easytier-web/*)'
+    required: false
+    default: './easytier-web/*'
+  gui:
+    description: 'Whether to prepare the GUI build environment'
+    required: true
+    default: 'true'
+  token:
+    description: 'GitHub token, used by setup-protoc action'
+    required: false
+runs:
+  using: 'composite'
+  steps:
+    - run: mkdir -p easytier-gui/dist
+      shell: bash
+
+    - name: Install dependencies
+      if: ${{ runner.os == 'Linux' }}
+      run: |
+        sudo apt-get update
+        sudo apt-get install -qqy build-essential mold musl-tools
+      shell: bash
+
+    - name: Setup Frontend Environment
+      if: ${{ inputs.pnpm == 'true' }}
+      uses: ./.github/actions/prepare-pnpm
+      with:
+        build-filter: ${{ inputs.pnpm-build-filter }}
+
+    - name: Install GUI dependencies (Linux)
+      if: ${{ inputs.gui == 'true' && runner.os == 'Linux' }}
+      run: |
+        sudo apt-get install -qq xdg-utils \
+        libappindicator3-dev \
+        libgtk-3-dev \
+        librsvg2-dev \
+        libwebkit2gtk-4.1-dev \
+        libxdo-dev
+      shell: bash
+
+    - uses: actions-rust-lang/setup-rust-toolchain@v1
+      with:
+        toolchain: 1.95
+        target: ${{ !contains(inputs.target, 'mips') && inputs.target || '' }}
+        components: ${{ contains(inputs.target, 'mips') && 'rust-src' || '' }}
+        cache: false
+        rustflags: ''
+
+    - name: Install Rust (MIPS)
+      if: ${{ contains(inputs.target, 'mips') }}
+      run: |
+        MUSL_TARGET=${{ inputs.target }}sf
+        mkdir -p ./musl_gcc
+        wget --inet4-only -c https://github.com/cross-tools/musl-cross/releases/download/20250520/${MUSL_TARGET}.tar.xz -P ./musl_gcc/
+        tar xf ./musl_gcc/${MUSL_TARGET}.tar.xz -C ./musl_gcc/
+        sudo ln -sf $(pwd)/musl_gcc/${MUSL_TARGET}/bin/*gcc /usr/bin/
+        sudo ln -sf $(pwd)/musl_gcc/${MUSL_TARGET}/include/ /usr/include/musl-cross
+        sudo ln -sf $(pwd)/musl_gcc/${MUSL_TARGET}/${MUSL_TARGET}/sysroot/ ./musl_gcc/sysroot
+        sudo chmod -R a+rwx ./musl_gcc
+
+        if [[ -d "./musl_gcc/sysroot" ]]; then
+          echo "BINDGEN_EXTRA_CLANG_ARGS=--sysroot=$(readlink -f ./musl_gcc/sysroot)" >> $GITHUB_ENV
+        fi
+
+        cd "$PWD/musl_gcc/${MUSL_TARGET}/lib/gcc/${MUSL_TARGET}/15.1.0" || exit 255
+        # for panic-abort
+        cp libgcc_eh.a libunwind.a
+        
+        # for mimalloc
+        ar x libgcc.a _ctzsi2.o _clz.o _bswapsi2.o
+        ar rcs libctz.a _ctzsi2.o _clz.o _bswapsi2.o
+      shell: bash
+
+    - name: Setup protoc
+      uses: arduino/setup-protoc@v3
+      with:
+        # GitHub repo token to use to avoid rate limiter
+        repo-token: ${{ inputs.token }}
@@ -0,0 +1,48 @@
+name: 'Setup pnpm'
+author: Luna
+description: 'Setup Node.js, pnpm, and install dependencies'
+
+inputs:
+  build-filter:
+    description: 'The filter argument for pnpm build (e.g. ./easytier-web/*)'
+    required: false
+    default: ''
+
+runs:
+  using: "composite"
+  steps:
+    - name: Setup Node.js
+      uses: actions/setup-node@v5
+      with:
+        node-version: 22
+
+    - name: Install pnpm
+      uses: pnpm/action-setup@v5
+      with:
+        version: 10
+        run_install: false
+
+    - name: Get pnpm store directory
+      shell: bash
+      run: |
+        echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
+    - name: Setup pnpm cache
+      uses: actions/cache@v5
+      with:
+        path: ${{ env.STORE_PATH }}
+        key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+        restore-keys: |
+          ${{ runner.os }}-pnpm-store-
+
+    - name: Install and build
+      shell: bash
+      run: |
+        pnpm -r install
+        if [ -n "${{ inputs.build-filter }}" ]; then
+          echo "Building with filter: ${{ inputs.build-filter }}"
+          pnpm -r --filter "${{ inputs.build-filter }}" build
+        else
+          echo "No build filter provided, building all packages"
+          pnpm -r build
+        fi
@@ -1,29 +1,35 @@
-FROM alpine:latest AS builder
+FROM alpine:latest AS base
+FROM base AS builder

 ARG TARGETPLATFORM

 COPY . /tmp/artifacts
-RUN mkdir -p /tmp/output; \
-    cd /tmp/artifacts; \
-    ARTIFACT_ARCH=""; \
+WORKDIR /tmp/output
+RUN ARTIFACT_ARCH=""; \
    if [ "$TARGETPLATFORM" = "linux/amd64" ]; then \
        ARTIFACT_ARCH="x86_64"; \
+    elif [ "$TARGETPLATFORM" = "linux/arm/v6" ]; then \
+        ARTIFACT_ARCH="armhf"; \
+    elif [ "$TARGETPLATFORM" = "linux/arm/v7" ]; then \
+        ARTIFACT_ARCH="armv7hf"; \
    elif [ "$TARGETPLATFORM" = "linux/arm64" ]; then \
        ARTIFACT_ARCH="aarch64"; \
+    elif [ "$TARGETPLATFORM" = "linux/riscv64" ]; then \
+        ARTIFACT_ARCH="riscv64"; \
    else \
-        echo "Unsupported architecture: $TARGETARCH"; \
+        echo "Unsupported architecture: $TARGETPLATFORM"; \
        exit 1; \
    fi; \
    cp /tmp/artifacts/easytier-linux-${ARTIFACT_ARCH}/* /tmp/output;

-FROM alpine:latest
+FROM base

-RUN apk add --no-cache tzdata
+RUN apk add --no-cache tzdata tini
 WORKDIR /app
 COPY --from=builder --chmod=755 /tmp/output/* /usr/local/bin

 # users can use "-e TZ=xxx" to adjust it
-ENV TZ Asia/Shanghai
+ENV TZ=Asia/Shanghai

 # tcp
 EXPOSE 11010/tcp
@@ -36,4 +42,7 @@ EXPOSE 11011/tcp
 # wss
 EXPOSE 11012/tcp

-ENTRYPOINT ["easytier-core"]
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=5 \
+    CMD ["/usr/local/bin/easytier-cli", "--rpc-portal", "127.0.0.1:15888", "--output", "json", "node", "info"]
+
+ENTRYPOINT ["/sbin/tini", "--", "easytier-core"]
@@ -2,9 +2,14 @@ name: EasyTier Core

 on:
  push:
-    branches: ["develop", "main", "releases/**"]
+    branches: [ "develop", "main", "releases/**" ]
  pull_request:
-    branches: ["develop", "main"]
+    branches: [ "develop", "main" ]
+    types: [ opened, synchronize, reopened, ready_for_review ]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true

 env:
  CARGO_TERM_COLOR: always
@@ -18,6 +23,7 @@ jobs:
  pre_job:
    # continue-on-error: true # Uncomment once integration is finished
    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
    # Map a step output to a job output
    outputs:
      # do not skip push on branch starts with releases/
@@ -30,37 +36,69 @@ jobs:
          concurrent_skipping: 'same_content_newer'
          skip_after_successful_duplicate: 'true'
          cancel_others: 'true'
-          paths: '["Cargo.toml", "Cargo.lock", "easytier/**", ".github/workflows/core.yml", ".github/workflows/install_rust.sh"]'
+          paths: '["Cargo.toml", "Cargo.lock", "easytier/**", ".github/workflows/core.yml", ".github/actions/**", "easytier-web/**"]'
+  build_web:
+    runs-on: ubuntu-latest
+    needs: pre_job
+    if: needs.pre_job.outputs.should_skip != 'true'
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Frontend Environment
+        uses: ./.github/actions/prepare-pnpm
+        with:
+          build-filter: './easytier-web/*'
+
+      - name: Archive artifact
+        uses: actions/upload-artifact@v5
+        with:
+          name: easytier-web-dashboard
+          path: |
+            easytier-web/frontend/dist/*
  build:
    strategy:
-      fail-fast: false
+      fail-fast: true
      matrix:
        include:
-          - TARGET: aarch64-unknown-linux-musl
-            OS: ubuntu-22.04
-            ARTIFACT_NAME: linux-aarch64
          - TARGET: x86_64-unknown-linux-musl
-            OS: ubuntu-22.04
+            OS: ubuntu-24.04
            ARTIFACT_NAME: linux-x86_64
-          - TARGET: mips-unknown-linux-musl
-            OS: ubuntu-22.04
-            ARTIFACT_NAME: linux-mips
-          - TARGET: mipsel-unknown-linux-musl
-            OS: ubuntu-22.04
-            ARTIFACT_NAME: linux-mipsel
+          - TARGET: aarch64-unknown-linux-musl
+            OS: ubuntu-24.04-arm
+            ARTIFACT_NAME: linux-aarch64
+
+          - TARGET: riscv64gc-unknown-linux-musl
+            OS: ubuntu-24.04
+            ARTIFACT_NAME: linux-riscv64
+          - TARGET: loongarch64-unknown-linux-musl
+            OS: ubuntu-24.04
+            ARTIFACT_NAME: linux-loongarch64
+
          - TARGET: armv7-unknown-linux-musleabihf # raspberry pi 2-3-4, not tested
-            OS: ubuntu-22.04
+            OS: ubuntu-24.04
            ARTIFACT_NAME: linux-armv7hf
          - TARGET: armv7-unknown-linux-musleabi # raspberry pi 2-3-4, not tested
-            OS: ubuntu-22.04
+            OS: ubuntu-24.04
            ARTIFACT_NAME: linux-armv7
          - TARGET: arm-unknown-linux-musleabihf # raspberry pi 0-1, not tested
-            OS: ubuntu-22.04
+            OS: ubuntu-24.04
            ARTIFACT_NAME: linux-armhf
          - TARGET: arm-unknown-linux-musleabi # raspberry pi 0-1, not tested
-            OS: ubuntu-22.04
+            OS: ubuntu-24.04
            ARTIFACT_NAME: linux-arm

+          - TARGET: mips-unknown-linux-musl
+            OS: ubuntu-24.04
+            ARTIFACT_NAME: linux-mips
+          - TARGET: mipsel-unknown-linux-musl
+            OS: ubuntu-24.04
+            ARTIFACT_NAME: linux-mipsel
+
+          - TARGET: x86_64-unknown-freebsd
+            OS: ubuntu-24.04
+            ARTIFACT_NAME: freebsd-13.2-x86_64
+            BSD_VERSION: 13.2
+
          - TARGET: x86_64-apple-darwin
            OS: macos-latest
            ARTIFACT_NAME: macos-x86_64
@@ -71,158 +109,193 @@ jobs:
          - TARGET: x86_64-pc-windows-msvc
            OS: windows-latest
            ARTIFACT_NAME: windows-x86_64
-
-          - TARGET: aarch64-pc-windows-msvc
+          - TARGET: i686-pc-windows-msvc
            OS: windows-latest
+            ARTIFACT_NAME: windows-i686
+          - TARGET: aarch64-pc-windows-msvc
+            OS: windows-11-arm
            ARTIFACT_NAME: windows-arm64

-          - TARGET: x86_64-unknown-freebsd
-            OS: ubuntu-22.04
-            ARTIFACT_NAME: freebsd-13.2-x86_64
-            BSD_VERSION: 13.2
-
    runs-on: ${{ matrix.OS }}
    env:
      NAME: easytier
      TARGET: ${{ matrix.TARGET }}
      OS: ${{ matrix.OS }}
      OSS_BUCKET: ${{ secrets.ALIYUN_OSS_BUCKET }}
-    needs: pre_job
+    needs:
+      - pre_job
+      - build_web
    if: needs.pre_job.outputs.should_skip != 'true'
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v5

      - name: Set current ref as env variable
        run: |
          echo "GIT_DESC=$(git log -1 --format=%cd.%h --date=format:%Y-%m-%d_%H:%M:%S)" >> $GITHUB_ENV

-      - name: Cargo cache
-        uses: actions/cache@v4
+      - name: Download web artifact
+        uses: actions/download-artifact@v4
        with:
-          path: |
-            ~/.cargo
-            ./target
-          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          name: easytier-web-dashboard
+          path: easytier-web/frontend/dist/

-      - name: Setup protoc
-        uses: arduino/setup-protoc@v2
+      - name: Prepare build environment
+        uses: ./.github/actions/prepare-build
        with:
-          # GitHub repo token to use to avoid rate limiter
-          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          target: ${{ matrix.TARGET }}
+          gui: true
+          pnpm: true
+          token: ${{ secrets.GITHUB_TOKEN }}

-      - name: Build Core & Cli
-        if: ${{ ! endsWith(matrix.TARGET, 'freebsd') }}
-        run: |
-          bash ./.github/workflows/install_rust.sh
-          if [[ $OS =~ ^ubuntu.*$ && $TARGET =~ ^mips.*$ ]]; then
-            cargo +nightly build -r --verbose --target $TARGET -Z build-std=std,panic_abort --no-default-features --features mips --package=easytier
+      - uses: Swatinem/rust-cache@v2
+        with:
+          # The prefix cache key, this can be changed to start a new cache manually.
+          # default: "v0-rust"
+          prefix-key: ""
+          shared-key: "core-registry"
+          cache-targets: "false"
+
+      - uses: mlugg/setup-zig@v2
+        if: ${{ contains(matrix.OS, 'ubuntu') }}
+        with:
+          version: 0.16.0
+          use-cache: true
+
+      - uses: taiki-e/install-action@v2
+        if: ${{ contains(matrix.OS, 'ubuntu') }}
+        with:
+          tool: cargo-zigbuild
+
+      - name: Build
+        if: ${{ !contains(matrix.TARGET, 'mips') }}
+        run: |          
+          if [[ "$TARGET" == *windows* ]]; then
+            SUFFIX=.exe
          else
-            cargo build --release --verbose --target $TARGET
+            SUFFIX=""
          fi

-      # Copied and slightly modified from @lmq8267 (https://github.com/lmq8267)
-      - name: Build Core & Cli (X86_64 FreeBSD)
-        uses: cross-platform-actions/action@v0.23.0
-        if: ${{ endsWith(matrix.TARGET, 'freebsd') }}
+          if [[ "$TARGET" =~ (x86_64-unknown-linux-musl|aarch64-unknown-linux-musl|windows|darwin) ]]; then
+            BUILD=build
+          else
+            BUILD=zigbuild
+          fi
+
+          if [[ "$TARGET" =~ ^(riscv64|loongarch64|aarch64).*$ || "$TARGET" =~ (freebsd|windows) ]]; then
+            FEATURES="mimalloc"
+          else
+            FEATURES="jemalloc"
+          fi
+          
+          cargo $BUILD --release --target $TARGET --package=easytier-web --features=embed
+          mv ./target/$TARGET/release/easytier-web"$SUFFIX" ./target/$TARGET/release/easytier-web-embed"$SUFFIX"
+          
+          cargo $BUILD --release --target $TARGET --features=$FEATURES
+
+      - name: Build (MIPS)
+        if: ${{ contains(matrix.TARGET, 'mips') }}
        env:
-          TARGET: ${{ matrix.TARGET }}
-        with:
-          operating_system: freebsd
-          environment_variables: TARGET
-          architecture: x86-64
-          version: ${{ matrix.BSD_VERSION }}
-          shell: bash
-          memory: 5G
-          cpu_count: 4
-          run: |
-            uname -a
-            echo $SHELL
-            pwd
-            ls -lah
-            whoami
-            env | sort
-
-            sudo pkg install -y git protobuf
-            curl --proto 'https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
-            source $HOME/.cargo/env
-
-            rustup set auto-self-update disable
-
-            rustup install 1.77
-            rustup default 1.77
-
-            export CC=clang
-            export CXX=clang++
-            export CARGO_TERM_COLOR=always
-
-            cargo build --release --verbose --target $TARGET
-
-      - name: Install UPX
-        if: ${{ matrix.OS != 'macos-latest' }}
-        uses: crazy-max/ghaction-upx@v3
-        with:
-          version: latest
-          install-only: true
+          RUSTC_BOOTSTRAP: 1
+        run: |
+          cargo build -r --target $TARGET -Z build-std=std,panic_abort --package=easytier --features=jemalloc

      - name: Compress
        run: |
          mkdir -p ./artifacts/objects/
+
          # windows is the only OS using a different convention for executable file name
-          if [[ $OS =~ ^windows.*$ && $TARGET =~ ^x86_64.*$ ]]; then
+          if [[ $OS =~ ^windows.*$ ]]; then
              SUFFIX=.exe
-              cp easytier/third_party/Packet.dll ./artifacts/objects/
-              cp easytier/third_party/wintun.dll ./artifacts/objects/
-          elif [[ $OS =~ ^windows.*$ && $TARGET =~ ^aarch64.*$ ]]; then
-              SUFFIX=.exe
-              cp easytier/third_party/arm64/Packet.dll ./artifacts/objects/
-              cp easytier/third_party/arm64/wintun.dll ./artifacts/objects/
+              case $TARGET in
+                  x86_64*)  ARCH_DIR=x86_64 ;;
+                  i686*)    ARCH_DIR=i686 ;;
+                  aarch64*) ARCH_DIR=arm64 ;;
+              esac
+              if [[ -n "$ARCH_DIR" ]]; then
+                  find "easytier/third_party/${ARCH_DIR}" -maxdepth 1 -type f \( -name "*.dll" -o -name "*.sys" \) -exec cp {} ./artifacts/objects/ \;
+              fi
          fi
+
          if [[ $GITHUB_REF_TYPE =~ ^tag$ ]]; then
            TAG=$GITHUB_REF_NAME
          else
            TAG=$GITHUB_SHA
          fi
+          
+          if [[ $OS =~ ^ubuntu.*$ && ! $TARGET =~ (loongarch|freebsd) ]]; then
+            HOST_ARCH=$(uname -m)
+            case $HOST_ARCH in
+              x86_64)  UPX_ARCH="amd64" ;;
+              aarch64) UPX_ARCH="arm64" ;;
+              *)       UPX_ARCH="amd64" ;;
+            esac

-          if [[ $OS =~ ^ubuntu.*$ && ! $TARGET =~ ^.*freebsd$ ]]; then
-            upx --lzma --best ./target/$TARGET/release/easytier-core"$SUFFIX"
-            upx --lzma --best ./target/$TARGET/release/easytier-cli"$SUFFIX"
+            UPX_VERSION=4.2.4
+            UPX_PKG="upx-${UPX_VERSION}-${UPX_ARCH}_linux"
+            curl -L "https://github.com/upx/upx/releases/download/v${UPX_VERSION}/${UPX_PKG}.tar.xz" -s | tar xJvf -
+            cp "${UPX_PKG}/upx" .
+            UPX_BIN=./upx
          fi

-          mv ./target/$TARGET/release/easytier-core"$SUFFIX" ./artifacts/objects/
-          mv ./target/$TARGET/release/easytier-cli"$SUFFIX" ./artifacts/objects/
-          if [[ ! $TARGET =~ ^mips.*$ ]]; then
-            mv ./target/$TARGET/release/easytier-web"$SUFFIX" ./artifacts/objects/
-          fi
+          for BIN in ./target/$TARGET/release/easytier-{core,cli,web,web-embed}"$SUFFIX"; do
+            if [[ -f "$BIN" ]]; then
+              if [[ -n "$UPX_BIN" ]]; then
+                $UPX_BIN --lzma --best "$BIN" || true
+              fi
+
+              mv "$BIN" ./artifacts/objects/
+            fi
+          done

          mv ./artifacts/objects/* ./artifacts/
          rm -rf ./artifacts/objects/

      - name: Archive artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v5
        with:
          name: easytier-${{ matrix.ARTIFACT_NAME }}
          path: |
            ./artifacts/*

-      - name: Upload OSS
-        if: ${{ env.OSS_BUCKET != '' }}
-        uses: Menci/upload-to-oss@main
-        with:
-          access-key-id: ${{ secrets.ALIYUN_OSS_ACCESS_ID }}
-          access-key-secret: ${{ secrets.ALIYUN_OSS_ACCESS_KEY }}
-          endpoint: ${{ secrets.ALIYUN_OSS_ENDPOINT }}
-          bucket: ${{ secrets.ALIYUN_OSS_BUCKET }}
-          local-path: ./artifacts/
-          remote-path: /easytier-releases/${{env.GIT_DESC}}/easytier-${{ matrix.ARTIFACT_NAME }}
-          no-delete-remote-files: true
-          retry: 5
-  core-result:
-    if: needs.pre_job.outputs.should_skip != 'true' && always()
+  build_magisk:
    runs-on: ubuntu-latest
-    needs:
-      - pre_job
-      - build
+    needs: [ pre_job, build_web, build ]
+    if: needs.pre_job.result == 'success' && needs.pre_job.outputs.should_skip != 'true' && !cancelled()
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v5  # 必须先检出代码才能获取模块配置
+
+      # 下载二进制文件到独立目录
+      - name: Download Linux aarch64 binaries
+        uses: actions/download-artifact@v4
+        with:
+          name: easytier-linux-aarch64
+          path: ./downloaded-binaries/  # 独立目录避免冲突
+
+      # 将二进制文件复制到 Magisk 模块目录
+      - name: Prepare binaries
+        run: |
+          mkdir -p ./easytier-contrib/easytier-magisk/
+          cp ./downloaded-binaries/easytier-core ./easytier-contrib/easytier-magisk/
+          cp ./downloaded-binaries/easytier-cli ./easytier-contrib/easytier-magisk/
+          cp ./downloaded-binaries/easytier-web ./easytier-contrib/easytier-magisk/
+
+      # 上传生成的模块
+      - name: Upload Magisk Module
+        uses: actions/upload-artifact@v5
+        with:
+          name: Easytier-Magisk
+          path: |
+            ./easytier-contrib/easytier-magisk
+            !./easytier-contrib/easytier-magisk/build.sh
+            !./easytier-contrib/easytier-magisk/magisk_update.json
+          if-no-files-found: error
+
+  core-result:
+    runs-on: ubuntu-latest
+    needs: [ pre_job, build_web, build, build_magisk ]
+    if: needs.pre_job.result == 'success' && needs.pre_job.outputs.should_skip != 'true' && !cancelled()
    steps:
      - name: Mark result as failed
-        if: needs.build.result != 'success'
+        if: contains(needs.*.result, 'failure')
        run: exit 1
@@ -11,13 +11,18 @@ on:
      image_tag:
        description: 'Tag for this image build'
        type: string
-        default: 'v1.2.0'
+        default: 'v2.6.4'
        required: true
      mark_latest:
        description: 'Mark this image as latest'
        type: boolean
        default: false
        required: true
+      mark_unstable:
+        description: 'Mark this image as unstable'
+        type: boolean
+        default: false
+        required: true

 jobs:
  docker:
@@ -26,7 +31,14 @@ jobs:
    steps:
      -
        name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
+      -
+        name: Validate inputs
+        run: |
+          if [[ "${{ inputs.mark_latest }}" == "true" && "${{ inputs.mark_unstable }}" == "true" ]]; then
+            echo "Error: mark_latest and mark_unstable cannot both be true"
+            exit 1
+          fi
      -
        name: Set up QEMU
        uses: docker/setup-qemu-action@v3
@@ -39,9 +51,15 @@ jobs:
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: login github container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Download artifact
        id: download-artifact
-        uses: dawidd6/action-download-artifact@v6
+        uses: dawidd6/action-download-artifact@v11
        with:
          github_token: ${{secrets.GITHUB_TOKEN}}
          run_id: ${{ inputs.run_id }}
@@ -50,12 +68,36 @@ jobs:
      - name: List files
        run: |
          ls -l -R .
+      - name: Prepare Docker tags
+        id: tags
+        run: |
+          # Base tags with version
+          DOCKERHUB_TAGS="easytier/easytier:${{ inputs.image_tag }}"
+          GHCR_TAGS="ghcr.io/easytier/easytier:${{ inputs.image_tag }}"
+
+          # Add latest tags if requested
+          if [[ "${{ inputs.mark_latest }}" == "true" ]]; then
+            DOCKERHUB_TAGS="${DOCKERHUB_TAGS},easytier/easytier:latest"
+            GHCR_TAGS="${GHCR_TAGS},ghcr.io/easytier/easytier:latest"
+          fi
+
+          # Add unstable tags if requested
+          if [[ "${{ inputs.mark_unstable }}" == "true" ]]; then
+            DOCKERHUB_TAGS="${DOCKERHUB_TAGS},easytier/easytier:unstable"
+            GHCR_TAGS="${GHCR_TAGS},ghcr.io/easytier/easytier:unstable"
+          fi
+
+          # Combine all tags
+          ALL_TAGS="${DOCKERHUB_TAGS},${GHCR_TAGS}"
+
+          echo "tags=${ALL_TAGS}" >> $GITHUB_OUTPUT
+          echo "Generated tags: ${ALL_TAGS}"
      -
        name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: ./docker_context
-          platforms: linux/amd64,linux/arm64
+          platforms: linux/amd64,linux/arm/v6,linux/arm/v7,linux/arm64,linux/riscv64
          push: true
          file: .github/workflows/Dockerfile
-          tags: easytier/easytier:${{ inputs.image_tag }}${{ inputs.mark_latest && ',easytier/easytier:latest' || '' }},
+          tags: ${{ steps.tags.outputs.tags }}
@@ -5,7 +5,12 @@ on:
    branches: ["develop", "main", "releases/**"]
  pull_request:
    branches: ["develop", "main"]
-      
+    types: [opened, synchronize, reopened, ready_for_review]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 env:
  CARGO_TERM_COLOR: always

@@ -18,6 +23,7 @@ jobs:
  pre_job:
    # continue-on-error: true # Uncomment once integration is finished
    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
    # Map a step output to a job output
    outputs:
      should_skip: ${{ steps.skip_check.outputs.should_skip == 'true' && !startsWith(github.ref_name, 'releases/') }}
@@ -29,20 +35,20 @@ jobs:
          concurrent_skipping: 'same_content_newer'
          skip_after_successful_duplicate: 'true'
          cancel_others: 'true'
-          paths: '["Cargo.toml", "Cargo.lock", "easytier/**", "easytier-gui/**", ".github/workflows/gui.yml", ".github/workflows/install_rust.sh"]'
+          paths: '["Cargo.toml", "Cargo.lock", "easytier/**", "easytier-gui/**", ".github/workflows/gui.yml", ".github/actions/**", "easytier-web/frontend-lib/**"]'
  build-gui:
    strategy:
-      fail-fast: false
+      fail-fast: true
      matrix:
        include:
-          - TARGET: aarch64-unknown-linux-musl
-            OS: ubuntu-22.04
-            GUI_TARGET: aarch64-unknown-linux-gnu
-            ARTIFACT_NAME: linux-aarch64
          - TARGET: x86_64-unknown-linux-musl
-            OS: ubuntu-22.04
+            OS: ubuntu-24.04
            GUI_TARGET: x86_64-unknown-linux-gnu
            ARTIFACT_NAME: linux-x86_64
+          - TARGET: aarch64-unknown-linux-musl
+            OS: ubuntu-24.04-arm
+            GUI_TARGET: aarch64-unknown-linux-gnu
+            ARTIFACT_NAME: linux-aarch64

          - TARGET: x86_64-apple-darwin
            OS: macos-latest
@@ -57,9 +63,12 @@ jobs:
            OS: windows-latest
            GUI_TARGET: x86_64-pc-windows-msvc
            ARTIFACT_NAME: windows-x86_64
-
-          - TARGET: aarch64-pc-windows-msvc
+          - TARGET: i686-pc-windows-msvc
            OS: windows-latest
+            GUI_TARGET: i686-pc-windows-msvc
+            ARTIFACT_NAME: windows-i686
+          - TARGET: aarch64-pc-windows-msvc
+            OS: windows-11-arm
            GUI_TARGET: aarch64-pc-windows-msvc
            ARTIFACT_NAME: windows-arm64

@@ -73,98 +82,39 @@ jobs:
    needs: pre_job
    if: needs.pre_job.outputs.should_skip != 'true'    
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v5

      - name: Set current ref as env variable
        run: |
          echo "GIT_DESC=$(git log -1 --format=%cd.%h --date=format:%Y-%m-%d_%H:%M:%S)" >> $GITHUB_ENV

-      - uses: actions/setup-node@v4
+      - name: Prepare build environment
+        uses: ./.github/actions/prepare-build
        with:
-          node-version: 21
+          target: ${{ matrix.TARGET }}
+          gui: true
+          pnpm: true
+          pnpm-build-filter: ''
+          token: ${{ secrets.GITHUB_TOKEN }}

-      - name: Install pnpm
-        uses: pnpm/action-setup@v3
+      - uses: Swatinem/rust-cache@v2
        with:
-          version: 9
-          run_install: false
-
-      - name: Get pnpm store directory
-        shell: bash
-        run: |
-          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
-
-      - name: Setup pnpm cache
-        uses: actions/cache@v4
-        with:
-          path: ${{ env.STORE_PATH }}
-          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
-          restore-keys: |
-            ${{ runner.os }}-pnpm-store-
-
-      - name: Install frontend dependencies
-        run: |
-          pnpm -r install
-          pnpm -r build
-
-      - name: Cargo cache
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cargo
-            ./target
-          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
-
-      - name: Install rust target
-        run: bash ./.github/workflows/install_rust.sh
-
-      - name: Setup protoc
-        uses: arduino/setup-protoc@v2
-        with:
-          # GitHub repo token to use to avoid rate limiter
-          repo-token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Install GUI cross compile (aarch64 only)
-        if: ${{ matrix.TARGET == 'aarch64-unknown-linux-musl' }}
-        run: |
-          # see https://tauri.app/v1/guides/building/linux/
-          echo "deb [arch=amd64] http://archive.ubuntu.com/ubuntu/ jammy main restricted" | sudo tee /etc/apt/sources.list
-          echo "deb [arch=amd64] http://archive.ubuntu.com/ubuntu/ jammy-updates main restricted" | sudo tee -a /etc/apt/sources.list
-          echo "deb [arch=amd64] http://archive.ubuntu.com/ubuntu/ jammy universe" | sudo tee -a /etc/apt/sources.list
-          echo "deb [arch=amd64] http://archive.ubuntu.com/ubuntu/ jammy-updates universe" | sudo tee -a /etc/apt/sources.list
-          echo "deb [arch=amd64] http://archive.ubuntu.com/ubuntu/ jammy multiverse" | sudo tee -a /etc/apt/sources.list
-          echo "deb [arch=amd64] http://archive.ubuntu.com/ubuntu/ jammy-updates multiverse" | sudo tee -a /etc/apt/sources.list
-          echo "deb [arch=amd64] http://archive.ubuntu.com/ubuntu/ jammy-backports main restricted universe multiverse" | sudo tee -a /etc/apt/sources.list
-          echo "deb [arch=amd64] http://security.ubuntu.com/ubuntu/ jammy-security main restricted" | sudo tee -a /etc/apt/sources.list
-          echo "deb [arch=amd64] http://security.ubuntu.com/ubuntu/ jammy-security universe" | sudo tee -a /etc/apt/sources.list
-          echo "deb [arch=amd64] http://security.ubuntu.com/ubuntu/ jammy-security multiverse" | sudo tee -a /etc/apt/sources.list
-
-          echo "deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy main restricted" | sudo tee -a /etc/apt/sources.list
-          echo "deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy-updates main restricted" | sudo tee -a /etc/apt/sources.list
-          echo "deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy universe" | sudo tee -a /etc/apt/sources.list
-          echo "deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy-updates universe" | sudo tee -a /etc/apt/sources.list
-          echo "deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy multiverse" | sudo tee -a /etc/apt/sources.list
-          echo "deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy-updates multiverse" | sudo tee -a /etc/apt/sources.list
-          echo "deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy-backports main restricted universe multiverse" | sudo tee -a /etc/apt/sources.list
-          echo "deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy-security main restricted" | sudo tee -a /etc/apt/sources.list
-          echo "deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy-security universe" | sudo tee -a /etc/apt/sources.list
-          echo "deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy-security multiverse" | sudo tee -a /etc/apt/sources.list
-
-          sudo dpkg --add-architecture arm64
-          sudo apt-get update
-          sudo apt-get install -y libgstreamer1.0-0:arm64 gstreamer1.0-plugins-base:arm64 gstreamer1.0-plugins-good:arm64 
-          sudo apt-get install -y libgstreamer-gl1.0-0:arm64 libgstreamer-plugins-base1.0-0:arm64 libgstreamer-plugins-good1.0-0:arm64 libwebkit2gtk-4.1-0:arm64
-          sudo apt install -f -o Dpkg::Options::="--force-overwrite" libwebkit2gtk-4.1-dev:arm64 libssl-dev:arm64 gcc-aarch64-linux-gnu
-          echo "PKG_CONFIG_SYSROOT_DIR=/usr/aarch64-linux-gnu/" >> "$GITHUB_ENV"
-          echo "PKG_CONFIG_PATH=/usr/lib/aarch64-linux-gnu/pkgconfig/" >> "$GITHUB_ENV"
+          # The prefix cache key, this can be changed to start a new cache manually.
+          # default: "v0-rust"
+          prefix-key: ""
+          shared-key: "gui-registry"
+          cache-targets: "false"

      - name: copy correct DLLs
-        if: ${{ matrix.OS == 'windows-latest' }}
+        if: ${{ contains(matrix.GUI_TARGET, 'windows') }}
        run: |
-          if [[ $GUI_TARGET =~ ^aarch64.*$ ]]; then
-            cp ./easytier/third_party/arm64/*.dll ./easytier-gui/src-tauri/
-          else
-            cp ./easytier/third_party/*.dll ./easytier-gui/src-tauri/
+          case $TARGET in
+              x86_64*)  ARCH_DIR=x86_64 ;;
+              i686*)    ARCH_DIR=i686 ;;
+              aarch64*) ARCH_DIR=arm64 ;;
+          esac
+          if [[ -n "$ARCH_DIR" ]]; then
+              find "./easytier/third_party/${ARCH_DIR}" -maxdepth 1 -type f \( -name "*.dll" -o -name "*.sys" \) -exec cp {} ./easytier-gui/src-tauri/ \;
          fi

      - name: Build GUI
@@ -172,10 +122,9 @@ jobs:
        uses: tauri-apps/tauri-action@v0
        with:
          projectPath: ./easytier-gui
-          # https://tauri.app/v1/guides/building/linux/#cross-compiling-tauri-applications-for-arm-based-devices
-          args: --verbose --target ${{ matrix.GUI_TARGET }} ${{ matrix.OS == 'ubuntu-22.04' && contains(matrix.TARGET, 'aarch64') && '--bundles deb' || ''  }}
+          args: --verbose --target ${{ matrix.GUI_TARGET }}

-      - name: Compress
+      - name: Collect artifact
        run: |
          mkdir -p ./artifacts/objects/
          
@@ -184,48 +133,33 @@ jobs:
          else
            TAG=$GITHUB_SHA
          fi
+
          # copy gui bundle, gui is built without specific target
-          if [[ $OS =~ ^windows.*$ ]]; then
+          if [[ $GUI_TARGET =~ windows ]]; then
              mv ./target/$GUI_TARGET/release/bundle/nsis/*.exe ./artifacts/objects/
-          elif [[ $OS =~ ^macos.*$ ]]; then
+          elif [[ $GUI_TARGET =~ darwin ]]; then
              mv ./target/$GUI_TARGET/release/bundle/dmg/*.dmg ./artifacts/objects/
-          elif [[ $OS =~ ^ubuntu.*$ && ! $TARGET =~ ^mips.*$ ]]; then
+          elif [[ $GUI_TARGET =~ linux ]]; then
              mv ./target/$GUI_TARGET/release/bundle/deb/*.deb ./artifacts/objects/
-              if [[ $GUI_TARGET =~ ^x86_64.*$ ]]; then
-                # currently only x86 appimage is supported
-                mv ./target/$GUI_TARGET/release/bundle/appimage/*.AppImage ./artifacts/objects/
-              fi
+              mv ./target/$GUI_TARGET/release/bundle/rpm/*.rpm ./artifacts/objects/
+              mv ./target/$GUI_TARGET/release/bundle/appimage/*.AppImage ./artifacts/objects/
          fi

          mv ./artifacts/objects/* ./artifacts/
          rm -rf ./artifacts/objects/

      - name: Archive artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v5
        with:
          name: easytier-gui-${{ matrix.ARTIFACT_NAME }}
          path: |
            ./artifacts/*

-      - name: Upload OSS
-        if: ${{ env.OSS_BUCKET != '' }}
-        uses: Menci/upload-to-oss@main
-        with:
-          access-key-id: ${{ secrets.ALIYUN_OSS_ACCESS_ID }}
-          access-key-secret: ${{ secrets.ALIYUN_OSS_ACCESS_KEY }}
-          endpoint: ${{ secrets.ALIYUN_OSS_ENDPOINT }}
-          bucket: ${{ secrets.ALIYUN_OSS_BUCKET }}
-          local-path: ./artifacts/
-          remote-path: /easytier-releases/${{env.GIT_DESC}}/easytier-gui-${{ matrix.ARTIFACT_NAME }}
-          no-delete-remote-files: true
-          retry: 5
  gui-result:
-    if: needs.pre_job.outputs.should_skip != 'true' && always()
    runs-on: ubuntu-latest
-    needs:
-      - pre_job
-      - build-gui
+    needs: [ pre_job, build-gui ]
+    if: needs.pre_job.result == 'success' && needs.pre_job.outputs.should_skip != 'true' && !cancelled()
    steps:
      - name: Mark result as failed
-        if: needs.build-gui.result != 'success'
+        if: contains(needs.*.result, 'failure')
        run: exit 1
@@ -1,87 +0,0 @@
-#!/usr/bin/env bash
-
-# env needed:
-# - TARGET
-# - GUI_TARGET
-# - OS
-
-# dependencies are only needed on ubuntu as that's the only place where
-# we make cross-compilation
-if [[ $OS =~ ^ubuntu.*$ ]]; then
-    sudo apt-get update && sudo apt-get install -qq crossbuild-essential-arm64 crossbuild-essential-armhf musl-tools libappindicator3-dev
-    # for easytier-gui
-    if [[ $GUI_TARGET != '' && $GUI_TARGET =~ ^x86_64.*$ ]]; then
-        sudo apt install -qq libwebkit2gtk-4.1-dev \
-            build-essential \
-            curl \
-            wget \
-            file \
-            libgtk-3-dev \
-            librsvg2-dev \
-            libxdo-dev \
-            libssl-dev \
-            patchelf
-    fi
-    #  curl -s musl.cc | grep mipsel
-    case $TARGET in
-    mipsel-unknown-linux-musl)
-        MUSL_URI=mipsel-linux-muslsf
-        ;;
-    mips-unknown-linux-musl)
-        MUSL_URI=mips-linux-muslsf
-        ;;
-    aarch64-unknown-linux-musl)
-        MUSL_URI=aarch64-linux-musl
-        ;;
-    armv7-unknown-linux-musleabihf)
-        MUSL_URI=armv7l-linux-musleabihf
-        ;;
-    armv7-unknown-linux-musleabi)
-        MUSL_URI=armv7m-linux-musleabi
-        ;;
-    arm-unknown-linux-musleabihf)
-        MUSL_URI=arm-linux-musleabihf
-        ;;
-    arm-unknown-linux-musleabi)
-        MUSL_URI=arm-linux-musleabi
-        ;;
-    esac
-
-    if [ -n "$MUSL_URI" ]; then
-        mkdir -p ./musl_gcc
-        wget -c https://musl.cc/${MUSL_URI}-cross.tgz -P ./musl_gcc/
-        tar zxf ./musl_gcc/${MUSL_URI}-cross.tgz -C ./musl_gcc/
-        sudo ln -s $(pwd)/musl_gcc/${MUSL_URI}-cross/bin/*gcc /usr/bin/
-    fi
-fi
-
-# see https://github.com/rust-lang/rustup/issues/3709
-rustup set auto-self-update disable
-rustup install 1.77
-rustup default 1.77
-
-# mips/mipsel cannot add target from rustup, need compile by ourselves
-if [[ $OS =~ ^ubuntu.*$ && $TARGET =~ ^mips.*$ ]]; then
-    cd "$PWD/musl_gcc/${MUSL_URI}-cross/lib/gcc/${MUSL_URI}/11.2.1" || exit 255
-    # for panic-abort
-    cp libgcc_eh.a libunwind.a
-
-    # for mimalloc
-    ar x libgcc.a _ctzsi2.o _clz.o _bswapsi2.o
-    ar rcs libctz.a _ctzsi2.o _clz.o _bswapsi2.o
-
-    rustup toolchain install nightly-x86_64-unknown-linux-gnu
-    rustup component add rust-src --toolchain nightly-x86_64-unknown-linux-gnu
-
-    # https://github.com/rust-lang/rust/issues/128808
-    # remove it after Cargo or rustc fix this.
-    RUST_LIB_SRC=$HOME/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/
-    if [[ -f $RUST_LIB_SRC/library/Cargo.lock && ! -f $RUST_LIB_SRC/Cargo.lock ]]; then 
-        cp -f $RUST_LIB_SRC/library/Cargo.lock $RUST_LIB_SRC/Cargo.lock
-    fi
-else
-    rustup target add $TARGET
-    if [[ $GUI_TARGET != '' ]]; then
-        rustup target add $GUI_TARGET
-    fi
-fi
@@ -5,7 +5,12 @@ on:
    branches: ["develop", "main", "releases/**"]
  pull_request:
    branches: ["develop", "main"]
-      
+    types: [opened, synchronize, reopened, ready_for_review]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 env:
  CARGO_TERM_COLOR: always

@@ -18,6 +23,7 @@ jobs:
  pre_job:
    # continue-on-error: true # Uncomment once integration is finished
    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
    # Map a step output to a job output
    outputs:
      should_skip: ${{ steps.skip_check.outputs.should_skip == 'true' && !startsWith(github.ref_name, 'releases/') }}
@@ -29,25 +35,30 @@ jobs:
          concurrent_skipping: 'same_content_newer'
          skip_after_successful_duplicate: 'true'
          cancel_others: 'true'
-          paths: '["Cargo.toml", "Cargo.lock", "easytier/**", "easytier-gui/**", "tauri-plugin-vpnservice/**", ".github/workflows/mobile.yml", ".github/workflows/install_rust.sh"]'
+          paths: '["Cargo.toml", "Cargo.lock", "easytier/**", "easytier-gui/**", "tauri-plugin-vpnservice/**", ".github/workflows/mobile.yml", ".github/actions/**"]'
  build-mobile:
    strategy:
-      fail-fast: false
+      fail-fast: true
      matrix:
        include:
-          - TARGET: android
-            OS: ubuntu-22.04
-            ARTIFACT_NAME: android
-    runs-on: ${{ matrix.OS }}
+          - TARGET: aarch64-linux-android
+            ARCH: aarch64
+          - TARGET: armv7-linux-androideabi
+            ARCH: armv7
+          - TARGET: i686-linux-android
+            ARCH: i686
+          - TARGET: x86_64-linux-android
+            ARCH: x86_64
+    runs-on: ubuntu-latest
    env:
      NAME: easytier
      TARGET: ${{ matrix.TARGET }}
-      OS: ${{ matrix.OS }}
+      ARCH: ${{ matrix.ARCH }}
      OSS_BUCKET: ${{ secrets.ALIYUN_OSS_BUCKET }}
    needs: pre_job
    if: needs.pre_job.outputs.should_skip != 'true'    
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v5

      - name: Set current ref as env variable
        run: |
@@ -56,79 +67,46 @@ jobs:
      - uses: actions/setup-java@v4
        with:
          distribution: 'oracle'
-          java-version: '20'
+          java-version: '21'

      - name: Setup Android SDK
        uses: android-actions/setup-android@v3
        with:
-          cmdline-tools-version: 11076708
-          packages: 'build-tools;34.0.0 ndk;26.0.10792818 tools platform-tools platforms;android-34 '
+          cmdline-tools-version: 12.0
+          packages: 'build-tools;34.0.0 ndk;26.0.10792818 platform-tools platforms;android-34 '

      - name: Setup Android Environment
        run: |
          echo "$ANDROID_HOME/platform-tools" >> $GITHUB_PATH
          echo "$ANDROID_HOME/ndk/26.0.10792818/toolchains/llvm/prebuilt/linux-x86_64/bin" >> $GITHUB_PATH
-          echo "NDK_HOME=$ANDROID_HOME/ndk/26.0.10792818/" > $GITHUB_ENV
+          echo "NDK_HOME=$ANDROID_HOME/ndk/26.0.10792818/" >> $GITHUB_ENV

-      - uses: actions/setup-node@v4
+      - name: Prepare build environment
+        uses: ./.github/actions/prepare-build
        with:
-          node-version: 21
+          target: ${{ matrix.TARGET }}
+          gui: false
+          pnpm: true
+          pnpm-build-filter: ''
+          token: ${{ secrets.GITHUB_TOKEN }}

-      - name: Install pnpm
-        uses: pnpm/action-setup@v3
+      - uses: Swatinem/rust-cache@v2
        with:
-          version: 9
-          run_install: false
+          # The prefix cache key, this can be changed to start a new cache manually.
+          # default: "v0-rust"
+          prefix-key: ""
+          shared-key: "gui-registry"
+          cache-targets: "false"

-      - name: Get pnpm store directory
-        shell: bash
-        run: |
-          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
-
-      - name: Setup pnpm cache
-        uses: actions/cache@v4
-        with:
-          path: ${{ env.STORE_PATH }}
-          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
-          restore-keys: |
-            ${{ runner.os }}-pnpm-store-
-
-      - name: Install frontend dependencies
-        run: |
-          pnpm -r install
-          pnpm -r build
-
-      - name: Cargo cache
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cargo
-            ./target
-          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
-
-      - name: Install rust target
-        run: |
-          bash ./.github/workflows/install_rust.sh
-          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
-
-      - name: Setup protoc
-        uses: arduino/setup-protoc@v2
-        with:
-          # GitHub repo token to use to avoid rate limiter
-          repo-token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Build Android
+      - name: Build
        run: |
          cd easytier-gui
-          pnpm tauri android build
+          pnpm tauri android build --apk --target "$ARCH" --split-per-abi

-      - name: Compress
+      - name: Collect artifact
        run: |
          mkdir -p ./artifacts/objects/
-          mv easytier-gui/src-tauri/gen/android/app/build/outputs/apk/universal/release/app-universal-release.apk ./artifacts/objects/
+          mv easytier-gui/src-tauri/gen/android/app/build/outputs/apk/*/release/*.apk ./artifacts/objects/
          
          if [[ $GITHUB_REF_TYPE =~ ^tag$ ]]; then
            TAG=$GITHUB_REF_NAME
@@ -136,35 +114,21 @@ jobs:
            TAG=$GITHUB_SHA
          fi

-          mv ./artifacts/objects/* ./artifacts
+          mv ./artifacts/objects/* ./artifacts/
          rm -rf ./artifacts/objects/

      - name: Archive artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v5
        with:
-          name: easytier-gui-${{ matrix.ARTIFACT_NAME }}
+          name: easytier-mobile-android-${{ matrix.ARCH }}
          path: |
            ./artifacts/*

-      - name: Upload OSS
-        if: ${{ env.OSS_BUCKET != '' }}
-        uses: Menci/upload-to-oss@main
-        with:
-          access-key-id: ${{ secrets.ALIYUN_OSS_ACCESS_ID }}
-          access-key-secret: ${{ secrets.ALIYUN_OSS_ACCESS_KEY }}
-          endpoint: ${{ secrets.ALIYUN_OSS_ENDPOINT }}
-          bucket: ${{ secrets.ALIYUN_OSS_BUCKET }}
-          local-path: ./artifacts/
-          remote-path: /easytier-releases/${{env.GIT_DESC}}/easytier-gui-${{ matrix.ARTIFACT_NAME }}
-          no-delete-remote-files: true
-          retry: 5
  mobile-result:
-    if: needs.pre_job.outputs.should_skip != 'true' && always()
    runs-on: ubuntu-latest
-    needs:
-      - pre_job
-      - build-mobile
+    needs: [ pre_job, build-mobile ]
+    if: needs.pre_job.result == 'success' && needs.pre_job.outputs.should_skip != 'true' && !cancelled()
    steps:
      - name: Mark result as failed
-        if: needs.build-mobile.result != 'success'
+        if: contains(needs.*.result, 'failure')
        run: exit 1
@@ -0,0 +1,44 @@
+name: Nix Check
+
+on:
+  push:
+    branches: ["main", "develop"]
+    paths:
+      - "**/*.nix"
+      - "flake.lock"
+      - "rust-toolchain.toml"
+  pull_request:
+    branches: ["main", "develop"]
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - "**/*.nix"
+      - "flake.lock"
+      - "rust-toolchain.toml"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check-full-shell:
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@v27
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+
+      - name: Magic Nix Cache
+        uses: DeterminateSystems/magic-nix-cache-action@v6
+
+      - name: Warm up full devShell
+        run: nix develop .#full --command true
+
+      - name: Cargo check in flake environment
+        run: nix develop .#full --command cargo check
+
+      - name: Cargo build in flake environment
+        run: nix develop .#full --command cargo build
@@ -0,0 +1,246 @@
+name: EasyTier OHOS
+
+on:
+  push:
+    branches: ["develop", "main", "releases/**"]
+    tags:
+      - 'v*'
+      - '!*-pre'
+  pull_request:
+    branches: ["develop", "main"]
+    types: [opened, synchronize, reopened, ready_for_review]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+
+defaults:
+  run:
+    # necessary for windows
+    shell: bash
+
+jobs:
+  cargo_fmt_check:
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Prepare build environment
+        uses: ./.github/actions/prepare-build
+        with:
+          gui: false
+          pnpm: false
+
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          components: rustfmt
+
+      - name: Check formatting
+        working-directory: ./easytier-contrib/easytier-ohrs
+        run: cargo fmt --all -- --check
+
+  pre_job:
+    # continue-on-error: true # Uncomment once integration is finished
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
+    # Map a step output to a job output
+    outputs:
+      # do not skip push on branch starts with releases/
+      should_skip: ${{ steps.skip_check.outputs.should_skip == 'true' && !startsWith(github.ref_name, 'releases/') }}
+    steps:
+      - id: skip_check
+        uses: fkirc/skip-duplicate-actions@v5
+        with:
+          # All of these options are optional, so you can remove them if you are happy with the defaults
+          concurrent_skipping: "same_content_newer"
+          skip_after_successful_duplicate: "true"
+          cancel_others: "true"
+          paths: '["Cargo.toml", "Cargo.lock", "easytier/**", "easytier-contrib/easytier-ohrs/**", ".github/workflows/ohos.yml", ".github/actions/**"]'
+
+  build-ohos:
+    runs-on: ubuntu-latest
+    needs: pre_job
+    env:
+      OHPM_PUBLISH_CODE: ${{ secrets.OHPM_PUBLISH_CODE }}
+    if: needs.pre_job.outputs.should_skip != 'true'
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -qq \
+            build-essential \
+            wget \
+            unzip \
+            git \
+            pkg-config curl libgl1-mesa-dev expect
+
+      - name: Resolve easytier version
+        run: |
+          set -e
+      
+          UPSTREAM_REPO="https://github.com/EasyTier/EasyTier.git"
+      
+          git remote add upstream "$UPSTREAM_REPO" 2>/dev/null || true
+          git fetch --unshallow upstream main || git fetch upstream main
+          git fetch --tags upstream --force
+      
+          # 读取 cargo 版本
+          CARGO_VERSION=$(cargo metadata --format-version 1 --no-deps --manifest-path easytier/Cargo.toml \
+            | jq -r '.packages[0].version')
+      
+          # 获取 upstream/main 最新 tag
+          LAST_TAG=$(git describe --tags --abbrev=0 upstream/main 2>/dev/null || echo "")
+          LAST_TAG_VERSION="${LAST_TAG#v}"
+      
+          # 语义版本比较
+          version_gt() {
+            [ "$(printf '%s\n' "$1" "$2" | sort -V | tail -n1)" = "$1" ] && [ "$1" != "$2" ]
+          }
+      
+          if [ -z "$LAST_TAG_VERSION" ]; then
+            BASE_VERSION="$CARGO_VERSION"
+            DIFF_COUNT=$(git rev-list --count upstream/main)
+          elif version_gt "$CARGO_VERSION" "$LAST_TAG_VERSION"; then
+            BASE_VERSION="$CARGO_VERSION"
+            DIFF_COUNT=0
+          else
+            BASE_VERSION="$LAST_TAG_VERSION"
+            DIFF_COUNT=$(git rev-list --count "${LAST_TAG}..upstream/main")
+          fi
+      
+          COMMIT_HASH=$(git rev-parse --short upstream/main)
+          EASYTIER_VERSION="${BASE_VERSION}-${DIFF_COUNT}-${COMMIT_HASH}"
+      
+          echo "EASYTIER_VERSION=$EASYTIER_VERSION"
+          echo "EASYTIER_VERSION=$EASYTIER_VERSION" >> $GITHUB_ENV
+      
+          cd ./easytier-contrib/easytier-ohrs/package
+          jq --arg v "$EASYTIER_VERSION" '.version = $v' oh-package.json5 > oh-package.tmp.json5
+          mv oh-package.tmp.json5 oh-package.json5
+
+
+      - name: Generate CHANGELOG.md for current commit
+        working-directory: ./easytier-contrib/easytier-ohrs/package
+        run: |
+          {
+            echo "## easytier-ohrs ${EASYTIER_VERSION}"
+            echo
+            git log -1 --pretty=format:"- %s"
+            echo
+          } > CHANGELOG.md
+
+      - name: Setup HarmonyOS CLI tools
+        uses: ErBWs/setup-ohos@v1
+
+      - name: Download and Extract Custom SDK
+        run: |
+          wget https://github.com/FrankHan052176/Easytier-OHOS-sdk/releases/download/v1/ohos-sdk.zip -O /tmp/ohos-sdk.zip
+          sudo unzip -o /tmp/ohos-sdk.zip -d /tmp/custom-sdk
+          sudo cp -rf /tmp/custom-sdk/linux/native/* $OHOS_NDK_HOME/native
+          echo "Custom SDK files deployed to $OHOS_NDK_HOME/native"
+          ls -a $OHOS_NDK_HOME/native
+
+      - name: Setup build environment
+        run: |
+          echo "TARGET_ARCH=aarch64-linux-ohos" >> $GITHUB_ENV
+
+          rustup install stable
+          rustup default stable
+
+          rustup target add aarch64-unknown-linux-ohos
+
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: ohrs
+
+      - name: Create clang wrapper script
+        run: |
+          sudo mkdir -p $OHOS_NDK_HOME/native/llvm
+          sudo tee $OHOS_NDK_HOME/native/llvm/aarch64-unknown-linux-ohos-clang.sh > /dev/null <<'EOF'
+          #!/bin/sh
+          exec $OHOS_NDK_HOME/native/llvm/bin/clang \
+            -target aarch64-linux-ohos \
+            --sysroot=$OHOS_NDK_HOME/native/sysroot \
+            -D__MUSL__ \
+            "$@"
+          EOF
+          sudo chmod +x $OHOS_NDK_HOME/native/llvm/aarch64-unknown-linux-ohos-clang.sh
+
+      - name: Build latest Har
+        working-directory: ./easytier-contrib/easytier-ohrs
+        run: |
+          sudo apt-get install -y llvm clang lldb lld
+          sudo apt-get install -y protobuf-compiler
+          source env.sh
+          ohrs doctor
+          ohrs build --release --arch aarch
+          ohrs artifact
+          mv package.har easytier-ohrs.har
+
+      - name: Build Release Package
+        if: startsWith(github.ref, 'refs/tags/')
+        working-directory: ./easytier-contrib/easytier-ohrs
+        run: |
+          echo "🎉 Official Release detected. Building easytier-release..."
+          TAG_NAME="${{ github.ref_name }}"
+          TAG_VERSION="${TAG_NAME#v}"
+          echo "Release Version: $TAG_VERSION"
+          cd package
+          jq --arg v "$TAG_VERSION" '.name = "easytier-release" | .version = $v' oh-package.json5 > oh-package.tmp.json5 && mv oh-package.tmp.json5 oh-package.json5
+          cd ..
+          ohrs build --release --arch aarch
+          cd dist/arm64-v8a
+          mv libeasytier_ohrs.so libeasytier_release.so
+          cd ../..
+          ohrs artifact
+          mv package.har easytier-release.har
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v5
+        with:
+          name: easytier-ohos
+          path: |
+            ./easytier-contrib/easytier-ohrs/easytier-ohrs.har
+          retention-days: 5
+          if-no-files-found: error
+
+      - name: Publish To Center Ohpm
+        working-directory: ./easytier-contrib/easytier-ohrs
+        env:
+          OHPM_PRIVATE_KEY: ${{ secrets.OHPM_PRIVATE_KEY }}
+          OHPM_KEY_PASSPHRASE: ${{ secrets.OHPM_KEY_PASSPHRASE }}
+        if: ${{ env.OHPM_PUBLISH_CODE != '' && github.event_name == 'push' }}
+        run: |
+          ohpm config set publish_id "$OHPM_PUBLISH_CODE"
+          ohpm config set publish_registry https://ohpm.openharmony.cn/ohpm
+          TMP_DIR=$(mktemp -d)
+          PRIVATE_KEY_FILE="$TMP_DIR/private_key"
+          printf '%s' "$OHPM_PRIVATE_KEY" > "$PRIVATE_KEY_FILE"
+          chmod 600 "$PRIVATE_KEY_FILE"
+          ohpm config set key_path $PRIVATE_KEY_FILE
+          unzip ohpm_crypto.zip -d /home/runner/work/
+          ohpm config set crypto_path /home/runner/work/ohpm_crypto
+          chmod 755 /home/runner/work/ohpm_crypto/*
+          PASSPHRASE="$(printf '%s' "$OHPM_KEY_PASSPHRASE" | tr -d '\r\n')"
+          ohpm config set key_passphrase "$PASSPHRASE"
+          ohpm publish easytier-ohrs.har
+          
+      - name: Publish To Private Ohpm
+        working-directory: ./easytier-contrib/easytier-ohrs
+        if: ${{ env.OHPM_PUBLISH_CODE != '' && github.event_name == 'push' }}
+        run: |
+          printf '%s' "${{ secrets.CODEARTS_PRIVATE_OHPM }}" > ~/.ohpm/.ohpmrc
+          ohpm config set strict_ssl false
+          ohpm publish easytier-ohrs.har
+          if [ -f "easytier-release.har" ]; then
+             echo "🚀 Publishing Release package..."
+             ohpm publish easytier-release.har
+          fi
+          curl --header "Content-Type: application/json" --request POST --data "{}" ${{ secrets.CODEARTS_WEBHOOKS }}
+
@@ -6,22 +6,19 @@ on:
      core_run_id:
        description: 'The run id of EasyTier-Core Action in EasyTier repo'
        type: number
-        default: 10322498549
        required: true
      gui_run_id:
        description: 'The run id of EasyTier-GUI Action in EasyTier repo'
        type: number
-        default: 10322498557
        required: true
      mobile_run_id:
        description: 'The run id of EasyTier-Mobile Action in EasyTier repo'
        type: number
-        default: 10322498555
        required: true
      version:
        description: 'Version for this release'
        type: string
-        default: 'v2.1.2'
+        default: 'v2.6.4'
        required: true
      make_latest:
        description: 'Mark this release as latest'
@@ -34,35 +31,34 @@ permissions:

 jobs:
  release:
-    if: contains('["KKRainbow"]', github.actor)
    runs-on: ubuntu-latest
    steps:
      -
        name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5

      - name: Download Core Artifact
-        uses: dawidd6/action-download-artifact@v6
+        uses: dawidd6/action-download-artifact@v11
        with:
          github_token: ${{secrets.GITHUB_TOKEN}}
          run_id: ${{ inputs.core_run_id }}
-          repo: EasyTier/EasyTier
+          repo: ${{ github.repository }}
          path: release_assets

      - name: Download GUI Artifact
-        uses: dawidd6/action-download-artifact@v6
+        uses: dawidd6/action-download-artifact@v11
        with:
          github_token: ${{secrets.GITHUB_TOKEN}}
          run_id: ${{ inputs.gui_run_id }}
-          repo: EasyTier/EasyTier
+          repo: ${{ github.repository }}
          path: release_assets_nozip

-      - name: Download GUI Artifact
-        uses: dawidd6/action-download-artifact@v6
+      - name: Download Mobile Artifact
+        uses: dawidd6/action-download-artifact@v11
        with:
          github_token: ${{secrets.GITHUB_TOKEN}}
          run_id: ${{ inputs.mobile_run_id }}
-          repo: EasyTier/EasyTier
+          repo: ${{ github.repository }}
          path: release_assets_nozip

      - name: Zip release assets
@@ -78,7 +74,14 @@ jobs:
          ls -l -R ./
          chmod -R 755 .
          for x in `ls`; do
-            zip ../zipped_assets/$x-${VERSION}.zip $x/*;
+            if [ "$x" = "Easytier-Magisk" ]; then
+              # for Easytier-Magisk, make sure files are in the root of the zip
+              cd $x;
+              zip -r ../../zipped_assets/$x-${VERSION}.zip .;
+              cd ..;
+            else
+              zip -r ../zipped_assets/$x-${VERSION}.zip $x;
+            fi
          done

      - name: Release
@@ -89,4 +92,4 @@ jobs:
          files: |
            ./zipped_assets/*
          token: ${{ secrets.GITHUB_TOKEN }}
-          tag_name: ${{ inputs.version }}
+          tag_name: ${{ inputs.version }}
@@ -2,12 +2,18 @@ name: EasyTier Test

 on:
  push:
-    branches: ["develop", "main"]
+    branches: [ "develop", "main" ]
  pull_request:
-    branches: ["develop", "main"]
+    branches: [ "develop", "main" ]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true

 env:
  CARGO_TERM_COLOR: always
+#  RUSTC_WRAPPER: "sccache"
+#  SCCACHE_GHA_ENABLED: "true"

 defaults:
  run:
@@ -28,40 +34,130 @@ jobs:
          # All of these options are optional, so you can remove them if you are happy with the defaults
          concurrent_skipping: 'never'
          skip_after_successful_duplicate: 'true'
-          paths: '["Cargo.toml", "Cargo.lock", "easytier/**", ".github/workflows/test.yml"]'
-  test:
-    runs-on: ubuntu-22.04
-    needs: pre_job
-    if: needs.pre_job.outputs.should_skip != 'true'    
-    steps:
-      - uses: actions/checkout@v3
+          paths: '["Cargo.toml", "Cargo.lock", "easytier/**", ".github/workflows/test.yml", ".github/actions/**"]'

-      - name: Setup protoc
-        uses: arduino/setup-protoc@v2
+  check:
+    name: Run linters & check
+    runs-on: ubuntu-latest
+    needs: pre_job
+    if: needs.pre_job.outputs.should_skip != 'true'
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Prepare build environment
+        uses: ./.github/actions/prepare-build
        with:
-          # GitHub repo token to use to avoid rate limiter
-          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          gui: true
+          pnpm: true
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          components: rustfmt,clippy
+          rustflags: ''
+
+      - uses: taiki-e/install-action@cargo-hack
+
+      - name: Check formatting
+        if: ${{ !cancelled() }}
+        run: cargo fmt --all -- --check
+
+      - name: Check Clippy
+        if: ${{ !cancelled() }}
+        run: cargo clippy --all-targets --features full --all -- -D warnings
+
+      - name: Check features
+        if: ${{ !cancelled() }}
+        run: cargo hack check --package easytier --each-feature --exclude-features macos-ne --verbose
+
+      - name: Check Cargo.lock is up to date
+        if: ${{ !cancelled() }}
+        run: |
+          if ! cargo metadata --format-version 1 --locked > /dev/null; then
+            echo "::error::Cargo.lock is out of date. Run cargo generate-lockfile or cargo build locally, then commit Cargo.lock."
+            exit 1
+          fi
+
+  pre-test:
+    name: Build test
+    runs-on: ubuntu-latest
+    needs: pre_job
+    if: needs.pre_job.outputs.should_skip != 'true'
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Prepare build environment
+        uses: ./.github/actions/prepare-build
+        with:
+          gui: true
+          pnpm: true
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: Swatinem/rust-cache@v2
+
+      - uses: taiki-e/install-action@nextest
+
+      - name: Archive test
+        run: cargo nextest archive --archive-file tests.tar.zst --package easytier --features full
+
+      - uses: actions/upload-artifact@v5
+        with:
+          name: tests
+          path: tests.tar.zst
+          retention-days: 1
+
+  test_matrix:
+    name: Test (${{ matrix.name }})
+    runs-on: ubuntu-latest
+    needs: [ pre_job, pre-test ]
+    if: needs.pre_job.outputs.should_skip != 'true'
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: "easytier"
+            opts: "-E 'not test(tests::three_node)' --test-threads 1 --no-fail-fast"
+
+          - name: "three_node"
+            opts: "-E 'test(tests::three_node) and not test(subnet_proxy_three_node_test)' --test-threads 1 --no-fail-fast"
+
+          - name: "three_node::subnet_proxy_three_node_test"
+            opts: "-E 'test(subnet_proxy_three_node_test)' --test-threads 1 --no-fail-fast"
+    steps:
+      - uses: actions/checkout@v5

      - name: Setup tools for test
        run: sudo apt install bridge-utils
+      - name: Setup upnpd for test
+        run: |
+          sudo apt-get update
+          sudo DEBIAN_FRONTEND=noninteractive apt-get install -y miniupnpd miniupnpd-iptables iptables

      - name: Setup system for test
        run: |
+          sudo modprobe br_netfilter
          sudo sysctl net.bridge.bridge-nf-call-iptables=0
          sudo sysctl net.bridge.bridge-nf-call-ip6tables=0
          sudo sysctl net.ipv6.conf.lo.disable_ipv6=0
          sudo ip addr add 2001:db8::2/64 dev lo

-      - name: Cargo cache
-        uses: actions/cache@v4
+      - uses: taiki-e/install-action@nextest
+
+      - name: Download tests
+        uses: actions/download-artifact@v4
        with:
-          path: |
-            ~/.cargo
-            ./target
-          key: ${{ runner.os }}-cargo-test-${{ hashFiles('**/Cargo.lock') }}
+          name: tests

      - name: Run tests
        run: |
-          sudo -E env "PATH=$PATH" cargo test --no-default-features --features=full --verbose
-          sudo chown -R $USER:$USER ./target
-          sudo chown -R $USER:$USER ~/.cargo
+          sudo prlimit --pid $$ --nofile=1048576:1048576
+          sudo -E env "PATH=$PATH" cargo nextest run --archive-file tests.tar.zst ${{ matrix.opts }}
+
+  test:
+    runs-on: ubuntu-latest
+    needs: [ pre_job, check, test_matrix ]
+    if: needs.pre_job.result == 'success' && needs.pre_job.outputs.should_skip != 'true' && !cancelled()
+    steps:
+      - name: Mark result as failed
+        if: contains(needs.*.result, 'failure')
+        run: exit 1
@@ -12,6 +12,7 @@ target-*/

 .vscode
 /.idea
+/.direnv/

 # perf & flamegraph
 perf.data
@@ -37,3 +38,11 @@ node_modules
 .vite

 easytier-gui/src-tauri/*.dll
+easytier-gui/src-tauri/*.sys
+/easytier-contrib/easytier-ohrs/dist/
+
+.direnv
+.flake-profile
+
+# contrib
+go.sum
@@ -0,0 +1,225 @@
+# 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 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! 
@@ -0,0 +1,233 @@
+# EasyTier 贡献指南
+
+[English Version](CONTRIBUTING.md)
+
+感谢您对 EasyTier 项目的关注！本文档提供了参与项目贡献的指南和说明。
+
+## 目录
+
+- [EasyTier 贡献指南](#easytier-贡献指南)
+  - [目录](#目录)
+  - [开发环境配置](#开发环境配置)
+    - [前置要求](#前置要求)
+      - [必需工具](#必需工具)
+      - [平台特定依赖](#平台特定依赖)
+    - [安装步骤](#安装步骤)
+  - [项目结构](#项目结构)
+  - [构建指南](#构建指南)
+    - [构建核心组件](#构建核心组件)
+    - [构建桌面应用](#构建桌面应用)
+    - [构建移动应用](#构建移动应用)
+    - [构建注意事项](#构建注意事项)
+  - [开发工作流](#开发工作流)
+  - [测试指南](#测试指南)
+    - [运行测试](#运行测试)
+    - [测试要求](#测试要求)
+  - [Pull Request 规范](#pull-request-规范)
+  - [其他资源](#其他资源)
+  - [需要帮助？](#需要帮助)
+
+## 开发环境配置
+
+### 前置要求
+
+#### 必需工具
+- Node.js v21 或更高版本
+- pnpm v9 或更高版本
+- Rust 工具链（版本 1.95）
+- LLVM 和 Clang
+- Protoc（Protocol Buffers 编译器）
+
+#### 平台特定依赖
+
+**Linux (Ubuntu/Debian)**
+```bash
+# 核心构建依赖
+sudo apt-get update && sudo apt-get install -y \
+    musl-tools \
+    llvm \
+    clang \
+    protobuf-compiler
+
+# GUI 构建依赖
+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
+
+# 测试依赖
+sudo apt install -y bridge-utils
+```
+
+**交叉编译依赖**
+- musl-cross 工具链（用于 MIPS 和其他架构）
+- 可能需要额外配置（详见 `.github/workflows/` 目录）
+
+**Android 开发依赖**
+- Java 20
+- Android SDK（Build Tools 34.0.0）
+- Android NDK（26.0.10792818）
+
+### 安装步骤
+
+1. 克隆仓库：
+   ```bash
+   git clone https://github.com/EasyTier/EasyTier.git
+   cd EasyTier
+   ```
+
+2. 安装依赖：
+   ```bash
+   # 安装 Rust 工具链
+   rustup install 1.95
+   rustup default 1.95
+
+   # 安装项目依赖
+   pnpm -r install
+   ```
+
+## 项目结构
+
+```
+easytier/          # 核心功能和库
+easytier-web/      # Web 仪表盘和前端
+easytier-gui/      # 桌面 GUI 应用
+.github/workflows/ # CI/CD 配置文件
+```
+
+## 构建指南
+
+### 构建核心组件
+
+```bash
+# 标准构建
+cargo build --release
+
+# 特定平台构建
+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
+```
+
+构建产物位置：`target/[target-triple]/release/`
+
+### 构建桌面应用
+
+```bash
+# 1. 构建前端
+pnpm -r build
+
+# 2. 构建 GUI 应用
+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
+```
+
+构建产物位置：`easytier-gui/src-tauri/target/release/bundle/`
+
+### 构建移动应用
+
+```bash
+# 1. 安装 Android 目标平台
+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. 构建 Android 应用
+cd easytier-gui
+pnpm tauri android build
+```
+
+构建产物位置：`easytier-gui/src-tauri/gen/android/app/build/outputs/apk/universal/release/`
+
+### 构建注意事项
+
+1. ARM/MIPS 的交叉编译需要额外配置
+2. Windows 构建需要正确的 DLL 文件
+3. 详细构建配置请参考 `.github/workflows/` 目录
+
+## 开发工作流
+
+1. 从 `develop` 分支创建特性分支：
+   ```bash
+   git checkout develop
+   git checkout -b feature/your-feature-name
+   ```
+
+2. 按照代码规范进行修改
+
+3. 编写或更新测试
+
+4. 使用规范的提交信息：
+   ```
+   feat: 添加新功能
+   fix: 修复问题
+   docs: 更新文档
+   test: 添加测试
+   chore: 更新依赖
+   ```
+
+5. 提交 Pull Request 到 `develop` 分支
+
+## 测试指南
+
+### 运行测试
+
+```bash
+# 配置系统（Linux）
+sudo modprobe br_netfilter
+sudo sysctl net.bridge.bridge-nf-call-iptables=0
+sudo sysctl net.bridge.bridge-nf-call-ip6tables=0
+
+# 运行测试
+cargo test --no-default-features --features=full --verbose
+```
+
+### 测试要求
+
+- 为新功能编写测试
+- 维护现有测试覆盖率
+- 测试应该是独立且可重复的
+- 包含单元测试和集成测试
+
+## Pull Request 规范
+
+1. 目标分支为 `develop`
+2. 确保所有测试通过
+3. 包含清晰的描述和目的
+4. 关联相关的 issues
+5. 保持变更的原子性和聚焦性
+6. 及时更新相关文档
+
+## 其他资源
+
+- [问题追踪](https://github.com/EasyTier/EasyTier/issues)
+- [项目文档](https://github.com/EasyTier/EasyTier/wiki)
+
+## 需要帮助？
+
+欢迎：
+- 提出问题
+- 参与社区讨论
+- 联系维护者
+
+感谢您为 EasyTier 做出贡献！ 
@@ -1,12 +1,29 @@
 [workspace]
 resolver = "2"
-members = ["easytier", "easytier-gui/src-tauri", "easytier-rpc-build", "easytier-web"]
+members = [
+    "easytier",
+    "easytier-gui/src-tauri",
+    "easytier-web",
+    "easytier-contrib/easytier-ffi",
+    "easytier-contrib/easytier-uptime",
+    "easytier-contrib/easytier-android-jni",
+]
 default-members = ["easytier", "easytier-web"]
+exclude = [
+    "easytier-contrib/easytier-ohrs", # it needs ohrs sdk
+]
+
+[workspace.package]
+edition = "2024"
+rust-version = "1.95"

 [profile.dev]
 panic = "unwind"
+debug = 2

 [profile.release]
 panic = "abort"
 lto = true
 codegen-units = 1
+opt-level = 3
+strip = true
@@ -3,13 +3,33 @@
 		{
 			"path": "."
 		},
+		{
+			"name": "core",
+			"path": "easytier"
+		},
 		{
 			"name": "gui",
 			"path": "easytier-gui"
 		},
 		{
-			"name": "core",
-			"path": "easytier"
+			"name": "web",
+			"path": "easytier-web"
+		},
+		{
+			"name": "ffi",
+			"path": "easytier-contrib/easytier-ffi"
+		},
+		{
+			"name": "magisk",
+			"path": "easytier-contrib/easytier-magisk"
+		},
+		{
+			"name": "openharmony",
+			"path": "easytier-contrib/easytier-ohrs"
+		},
+		{
+			"name": "uptime",
+			"path": "easytier-contrib/easytier-uptime"
 		},
 		{
 			"name": "vpnservice",
@@ -26,5 +46,12 @@
 		"i18n-ally.sortKeys": true,
 		// Disable the default formatter
 		"prettier.enable": false,
+		"editor.formatOnSave": true,
+		"editor.formatOnSaveMode": "modifications",
+		"editor.formatOnPaste": false,
+		"editor.formatOnType": true,
+		"[nix]": {
+			"editor.formatOnSave": false,
+		},
 	}
 }
@@ -1,73 +1,165 @@
-Apache License
-Version 2.0, January 2004
-http://www.apache.org/licenses/
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007

-TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.

-1. Definitions.

-"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.

-"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+  0. Additional Definitions.

-"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.

-"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.

-"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.

-"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".

-"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.

-"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.

-"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+  1. Exception to Section 3 of the GNU GPL.

-"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.

-2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+  2. Conveying Modified Versions.

-3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:

-4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or

-     (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.

-     (b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+  3. Object Code Incorporating Material from Library Header Files.

-     (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:

-     (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.

-     You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.

-5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+  4. Combined Works.

-6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:

-7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.

-8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.

-9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.

-END OF TERMS AND CONDITIONS
+   d) Do one of the following:

-APPENDIX: How to apply the Apache License to your work.
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.

-To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!)  The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.

-Copyright 2023 sunsijie
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)

-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
+  5. Combined Libraries.

-http://www.apache.org/licenses/LICENSE-2.0
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:

-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.
@@ -1,241 +1,247 @@
 # EasyTier

+[![Github release](https://img.shields.io/github/v/tag/EasyTier/EasyTier)](https://github.com/EasyTier/EasyTier/releases)
 [![GitHub](https://img.shields.io/github/license/EasyTier/EasyTier)](https://github.com/EasyTier/EasyTier/blob/main/LICENSE)
 [![GitHub last commit](https://img.shields.io/github/last-commit/EasyTier/EasyTier)](https://github.com/EasyTier/EasyTier/commits/main)
 [![GitHub issues](https://img.shields.io/github/issues/EasyTier/EasyTier)](https://github.com/EasyTier/EasyTier/issues)
 [![GitHub Core Actions](https://github.com/EasyTier/EasyTier/actions/workflows/core.yml/badge.svg)](https://github.com/EasyTier/EasyTier/actions/workflows/core.yml)
 [![GitHub GUI Actions](https://github.com/EasyTier/EasyTier/actions/workflows/gui.yml/badge.svg)](https://github.com/EasyTier/EasyTier/actions/workflows/gui.yml)
+[![GitHub Test Actions](https://github.com/EasyTier/EasyTier/actions/workflows/test.yml/badge.svg)](https://github.com/EasyTier/EasyTier/actions/workflows/test.yml)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/EasyTier/EasyTier)

 [简体中文](/README_CN.md) | [English](/README.md)

-**Please visit the [EasyTier Official Website](https://www.easytier.top/en/) to view the full documentation.**
-
-EasyTier is a simple, safe and decentralized VPN networking solution implemented with the Rust language and Tokio framework.
+> ✨ A simple, secure, decentralized virtual private network solution powered by Rust and Tokio

 <p align="center">
-<img src="assets/image-5.png" width="300">
-<img src="assets/image-4.png" width="300">
+<img src="assets/config-page.png" width="300" alt="config page">
+<img src="assets/running-page.png" width="300" alt="running page">
 </p>

+📚 **[Full Documentation](https://easytier.cn/en/)** | 🖥️ **[Web Console](https://easytier.cn/web)** | 📝 **[Download Releases](https://github.com/EasyTier/EasyTier/releases)** | 🧩 **[Third Party Tools](https://easytier.cn/en/guide/installation_gui.html#third-party-graphical-interfaces)** | ❤️ **[Sponsor](#sponsor)**
+
 ## Features

- **Decentralized**: No need to rely on centralized services, nodes are equal and independent.
- **Safe**: Use WireGuard protocol to encrypt data.
- **High Performance**: Full-link zero-copy, with performance comparable to mainstream networking software.
- **Cross-platform**: Supports MacOS/Linux/Windows/Android, will support IOS in the future. The executable file is statically linked, making deployment simple.
- **Networking without public IP**: Supports networking using shared public nodes, refer to [Configuration Guide](#Networking-without-public-IP)
- **NAT traversal**: Supports UDP-based NAT traversal, able to establish stable connections even in complex network environments.
- **Subnet Proxy (Point-to-Network)**: Nodes can expose accessible network segments as proxies to the VPN subnet, allowing other nodes to access these subnets through the node.
- **Smart Routing**: Selects links based on traffic to reduce latency and increase throughput.
- **TCP Support**: Provides reliable data transmission through concurrent TCP links when UDP is limited, optimizing performance.
- **High Availability**: Supports multi-path and switches to healthy paths when high packet loss or network errors are detected.
- **IPv6 Support**: Supports networking using IPv6.
- **Multiple Protocol Types**: Supports communication between nodes using protocols such as WebSocket and QUIC.
- **Web Management Interface**: Provides a [web-based management](https://easytier.cn/web) interface for easy configuration and monitoring.
+### Core Features

-## Installation
+- 🔒 **Decentralized**: Nodes are equal and independent, no centralized services required  
+- 🚀 **Easy to Use**: Multiple operation methods via web, client, and command line  
+- 🌍 **Cross-Platform**: Supports Win/MacOS/Linux/FreeBSD/Android and X86/ARM/MIPS architectures  
+- 🔐 **Secure**: AES-GCM or WireGuard encryption, prevents man-in-the-middle attacks  

-1. **Download the precompiled binary file**
+### Advanced Capabilities

-    Visit the [GitHub Release page](https://github.com/EasyTier/EasyTier/releases) to download the binary file suitable for your operating system. Release includes both command-line programs and GUI programs in the compressed package.
+- 🔌 **Efficient NAT Traversal**: Supports UDP and IPv6 traversal, works with NAT4-NAT4 networks  
+- 🌐 **Subnet Proxy**: Nodes can share subnets for other nodes to access  
+- 🔄 **Intelligent Routing**: Latency priority and automatic route selection for best network experience  
+- ⚡ **High Performance**: Zero-copy throughout the entire link, supports TCP/UDP/WSS/WG protocols  

-2. **Install via crates.io**
+### Network Optimization

-    ```sh
-    cargo install easytier
-    ```
-
-3. **Install from source code**
-
-    ```sh
-    cargo install --git https://github.com/EasyTier/EasyTier.git easytier
-    ```
-
-4. **Install by Docker Compose**
-
-    Please visit the [EasyTier Official Website](https://www.easytier.cn/en/) to view the full documentation.
-
-5. **Install by script (For Linux Only)**
-
-    ```sh
-    wget -O /tmp/easytier.sh "https://raw.githubusercontent.com/EasyTier/EasyTier/main/script/install.sh" && bash /tmp/easytier.sh install
-    ```
-
-    You can also uninstall/update Easytier by the command "uninstall" or "update" of this script
-
-6. **Install by Homebrew (For MacOS Only)**
-
-    ```sh
-    brew tap brewforge/chinese
-    brew install --cask easytier
-    ```
+- 📊 **UDP Loss Resistance**: KCP/QUIC proxy optimizes latency and bandwidth in high packet loss environments  
+- 🔧 **Web Management**: Easy configuration and monitoring through web interface  
+- 🛠️ **Zero Config**: Simple deployment with statically linked executables  

 ## Quick Start

-> The following text only describes the use of the command-line tool; the GUI program can be configured by referring to the following concepts.
+### 📥 Installation

-Make sure EasyTier is installed according to the [Installation Guide](#Installation), and both easytier-core and easytier-cli commands are available.
+Choose the installation method that best suits your needs:

-### Two-node Networking
+Linux (Recommended):
+```bash
+curl -fsSL "https://github.com/EasyTier/EasyTier/blob/main/script/install.sh?raw=true" | sudo bash -s install
+```

-Assuming the network topology of the two nodes is as follows
+Homebrew (MacOS/Linux):
+```bash
+brew tap brewforge/chinese
+brew install --cask easytier-gui
+```
+
+Windows (Recommended, run with administrator privileges):
+```powershell
+irm "https://github.com/EasyTier/EasyTier/blob/main/script/install.ps1?raw=true" | iex
+```
+
+Install via cargo (Latest development version): 
+```bash
+cargo install --git https://github.com/EasyTier/EasyTier.git easytier
+```
+
+[Install pre-built binary](https://github.com/EasyTier/EasyTier/releases) (Recommended, All platforms supported)
+
+[Install via Docker](https://easytier.cn/en/guide/installation.html#installation-methods)
+
+[Install OpenWrt ipk package](https://github.com/EasyTier/luci-app-easytier)
+
+Additional steps:
+
+[One-Click Register Service](https://easytier.cn/en/guide/network/oneclick-install-as-service.html) (Automatically start when the system boots and run in the background)
+
+### 🚀 Basic Usage
+
+#### Quick Networking with Shared Nodes
+
+EasyTier supports quick networking using shared public nodes. When you don't have a public IP, you can use the free shared nodes provided by the EasyTier community. Nodes will automatically attempt NAT traversal and establish P2P connections. When P2P fails, data will be relayed through shared nodes.
+
+When using shared nodes, each node entering the network needs to provide the same `--network-name` and `--network-secret` parameters as the unique identifier of the network.
+
+Taking two nodes as an example (Please use more complex network name to avoid conflicts):
+
+1. Run on Node A:
+
+```bash
+# Run with administrator privileges
+sudo easytier-core -d --network-name abc --network-secret abc -p tcp://<SharedNodeIP>:11010
+```
+
+2. Run on Node B:
+
+```bash
+# Run with administrator privileges
+sudo easytier-core -d --network-name abc --network-secret abc -p tcp://<SharedNodeIP>:11010
+```
+
+After successful execution, you can check the network status using `easytier-cli`:
+
+```text
+| ipv4         | hostname       | cost  | lat_ms | loss_rate | rx_bytes | tx_bytes | tunnel_proto | nat_type | id         | version         |
+| ------------ | -------------- | ----- | ------ | --------- | -------- | -------- | ------------ | -------- | ---------- | --------------- |
+| 10.126.126.1 | abc-1          | Local | *      | *         | *        | *        | udp          | FullCone | 439804259  | 2.6.2-70e69a38~ |
+| 10.126.126.2 | abc-2          | p2p   | 3.452  | 0         | 17.33 kB | 20.42 kB | udp          | FullCone | 390879727  | 2.6.2-70e69a38~ |
+|              | PublicServer_a | p2p   | 27.796 | 0.000     | 50.01 kB | 67.46 kB | tcp          | Unknown  | 3771642457 | 2.6.2-70e69a38~ |
+```
+
+You can test connectivity between nodes:
+
+```bash
+# Test connectivity
+ping 10.126.126.1
+ping 10.126.126.2
+```
+
+Note: If you cannot ping through, it may be that the firewall is blocking incoming traffic. Please turn off the firewall or add allow rules.
+
+To improve availability, you can connect to multiple shared nodes simultaneously:
+
+```bash
+# Connect to multiple shared nodes
+sudo easytier-core -d --network-name abc --network-secret abc -p tcp://<SharedNodeIP1>:11010 -p udp://<SharedNodeIP2>:11010
+```
+
+Once your network is set up successfully, you can easily configure it to start automatically on system boot. Refer to the [One-Click Register Service guide](https://easytier.cn/en/guide/network/oneclick-install-as-service.html) for step-by-step instructions on registering EasyTier as a system service.
+
+#### Decentralized Networking
+
+EasyTier is fundamentally decentralized, with no distinction between server and client. As long as one device can communicate with any node in the virtual network, it can join the virtual network. Here's how to set up a decentralized network:
+
+1. Start First Node (Node A):
+
+```bash
+# Start the first node
+sudo easytier-core -i 10.144.144.1
+```
+
+After startup, this node will listen on the following ports by default:
+- TCP: 11010
+- UDP: 11010
+- WebSocket: 11011
+- WebSocket SSL: 11012
+- WireGuard: 11013
+
+2. Connect Second Node (Node B):
+
+```bash
+# Connect to the first node using its public IP
+sudo easytier-core -i 10.144.144.2 -p udp://FIRST_NODE_PUBLIC_IP:11010
+```
+
+3. Verify Connection:
+
+```bash
+# Test connectivity
+ping 10.144.144.2
+
+# View connected peers
+easytier-cli peer
+
+# View routing information
+easytier-cli route
+
+# View local node information
+easytier-cli node
+```
+
+For more nodes to join the network, they can connect to any existing node in the network using the `-p` parameter:
+
+```bash
+# Connect to any existing node using its public IP
+sudo easytier-core -i 10.144.144.3 -p udp://ANY_EXISTING_NODE_PUBLIC_IP:11010
+```
+
+### 🔍 Advanced Features
+
+#### Subnet Proxy
+
+Assuming the network topology is as follows, Node B wants to share its accessible subnet 10.1.1.0/24 with other nodes:

 ```mermaid
 flowchart LR

-subgraph Node A IP 22.1.1.1
-nodea[EasyTier\n10.144.144.1]
+subgraph Node A Public IP 22.1.1.1
+nodea[EasyTier<br/>10.144.144.1]
 end

 subgraph Node B
-nodeb[EasyTier\n10.144.144.2]
-end
-
-nodea <-----> nodeb
-
-```
-
-1. Execute on Node A:
-
-    ```sh
-    sudo easytier-core --ipv4 10.144.144.1
-    ```
-
-    Successful execution of the command will print the following.
-
-    ![alt text](/assets/image-2.png)
-
-2. Execute on Node B
-
-    ```sh
-    sudo easytier-core --ipv4 10.144.144.2 --peers udp://22.1.1.1:11010
-    ```
-
-3. Test Connectivity
-
-    The two nodes should connect successfully and be able to communicate within the virtual subnet
-
-    ```sh
-    ping 10.144.144.2
-    ```
-
-    Use easytier-cli to view node information in the subnet
-
-    ```sh
-    easytier-cli peer
-    ```
-
-    ![alt text](/assets/image.png)
-
-    ```sh
-    easytier-cli route
-    ```
-
-    ![alt text](/assets/image-1.png)
-
-
-    ```sh
-    easytier-cli node
-    ```
-
-    ![alt text](assets/image-10.png)
-
---
-
-### Multi-node Networking
-
-Based on the two-node networking example just now, if more nodes need to join the virtual network, you can use the following command.
-
-```sh
-sudo easytier-core --ipv4 10.144.144.2 --peers udp://22.1.1.1:11010
-```
-
-The `--peers` parameter can fill in the listening address of any node already in the virtual network.
-
---
-
-### Subnet Proxy (Point-to-Network) Configuration
-
-Assuming the network topology is as follows, Node B wants to share its accessible subnet 10.1.1.0/24 with other nodes.
-
-```mermaid
-flowchart LR
-
-subgraph Node A IP 22.1.1.1
-nodea[EasyTier\n10.144.144.1]
-end
-
-subgraph Node B
-nodeb[EasyTier\n10.144.144.2]
+nodeb[EasyTier<br/>10.144.144.2]
 end

 id1[[10.1.1.0/24]]

 nodea <--> nodeb <-.-> id1
-
 ```

-Then the startup parameters for Node B's easytier are (new -n parameter)
+To share a subnet, add the `-n` parameter when starting EasyTier:

-```sh
-sudo easytier-core --ipv4 10.144.144.2 -n 10.1.1.0/24
+```bash
+# Share subnet 10.1.1.0/24 with other nodes
+sudo easytier-core -i 10.144.144.2 -n 10.1.1.0/24
 ```

-Subnet proxy information will automatically sync to each node in the virtual network, and each node will automatically configure the corresponding route. Node A can check whether the subnet proxy is effective through the following command.
+Subnet proxy information will automatically sync to each node in the virtual network, and each node will automatically configure the corresponding route. You can verify the subnet proxy setup:

-1. Check whether the routing information has been synchronized, the proxy_cidrs column shows the proxied subnets.
+1. Check if the routing information has been synchronized (the proxy_cidrs column shows the proxied subnets):

-    ```sh
-    easytier-cli route
-    ```
-
-   ![alt text](/assets/image-3.png)
-
-2. Test whether Node A can access nodes under the proxied subnet
-
-    ```sh
-    ping 10.1.1.2
-    ```
-
---
-
-### Networking without Public IP
-
-EasyTier supports networking using shared public nodes. The currently deployed shared public node is ``tcp://public.easytier.cn:11010``.
-
-When using shared nodes, each node entering the network needs to provide the same ``--network-name`` and ``--network-secret`` parameters as the unique identifier of the network.
-
-Taking two nodes as an example, Node A executes:
-
-```sh
-sudo easytier-core -i 10.144.144.1 --network-name abc --network-secret abc -p tcp://public.easytier.cn:11010
+```bash
+# View routing information
+easytier-cli route
 ```

-Node B executes
+![Routing Information](/assets/image-3.png)

-```sh
-sudo easytier-core --ipv4 10.144.144.2 --network-name abc --network-secret abc -p tcp://public.easytier.cn:11010
+2. Test if you can access nodes in the proxied subnet:
+
+```bash
+# Test connectivity to proxied subnet
+ping 10.1.1.2
 ```

-After the command is successfully executed, Node A can access Node B through the virtual IP 10.144.144.2.
+#### WireGuard Integration

-### Use EasyTier with WireGuard Client
-
-EasyTier can be used as a WireGuard server to allow any device with WireGuard client installed to access the EasyTier network. For platforms currently unsupported by EasyTier (such as iOS, Android, etc.), this method can be used to connect to the EasyTier network.
-
-Assuming the network topology is as follows:
+EasyTier can act as a WireGuard server, allowing any device with a WireGuard client (including iOS and Android) to access the EasyTier network. Here's an example setup:

 ```mermaid
 flowchart LR

-ios[[iPhone \n WireGuard Installed]]
+ios[[iPhone<br/>WireGuard Installed]]

-subgraph Node A IP 22.1.1.1
-nodea[EasyTier\n10.144.144.1]
+subgraph Node A Public IP 22.1.1.1
+nodea[EasyTier<br/>10.144.144.1]
 end

 subgraph Node B
-nodeb[EasyTier\n10.144.144.2]
+nodeb[EasyTier<br/>10.144.144.2]
 end

 id1[[10.1.1.0/24]]
@@ -243,86 +249,78 @@ id1[[10.1.1.0/24]]
 ios <-.-> nodea <--> nodeb <-.-> id1
 ```

-To enable an iPhone to access the EasyTier network through Node A, the following configuration can be applied:
+1. Start EasyTier with WireGuard portal enabled:

-Include the --vpn-portal parameter in the easytier-core command on Node A to specify the port that the WireGuard service listens on and the subnet used by the WireGuard network.
-
-```sh
-# The following parameters mean: listen on port 0.0.0.0:11013, and use the 10.14.14.0/24 subnet for WireGuard
-sudo easytier-core --ipv4 10.144.144.1 --vpn-portal wg://0.0.0.0:11013/10.14.14.0/24
+```bash
+# Listen on 0.0.0.0:11013 and use 10.14.14.0/24 subnet for WireGuard clients
+sudo easytier-core -i 10.144.144.1 --vpn-portal wg://0.0.0.0:11013/10.14.14.0/24
 ```

-After successfully starting easytier-core, use easytier-cli to obtain the WireGuard client configuration.
+2. Get WireGuard client configuration:

-```sh
-$> easytier-cli vpn-portal
-portal_name: wireguard
-
-############### client_config_start ###############
-
-[Interface]
-PrivateKey = 9VDvlaIC9XHUvRuE06hD2CEDrtGF+0lDthgr9SZfIho=
-Address = 10.14.14.0/32 # should assign an ip from this cidr manually
-
-[Peer]
-PublicKey = zhrZQg4QdPZs8CajT3r4fmzcNsWpBL9ImQCUsnlXyGM=
-AllowedIPs = 10.144.144.0/24,10.14.14.0/24
-Endpoint = 0.0.0.0:11013 # should be the public ip(or domain) of the vpn server
-PersistentKeepalive = 25
-
-############### client_config_end ###############
-
-connected_clients:
-[]
+```bash
+# Get WireGuard client configuration
+easytier-cli vpn-portal
 ```

-Before using the Client Config, you need to modify the Interface Address and Peer Endpoint to the client's IP and the IP of the EasyTier node, respectively. Import the configuration file into the WireGuard client to access the EasyTier network.
+3. In the output configuration:
+   - Set `Interface.Address` to an available IP from the WireGuard subnet
+   - Set `Peer.Endpoint` to the public IP/domain of your EasyTier node
+   - Import the modified configuration into your WireGuard client

-### Self-Hosted Public Server
+#### Self-Hosted Public Shared Node

-Every virtual network (with same network name and secret) can act as a public server cluster. Nodes of other network can connect to arbitrary nodes in public server cluster to discover each other without public IP.
+You can run your own public shared node to help other nodes discover each other. A public shared node is just a regular EasyTier network (with same network name and secret) that other networks can connect to.

-Run you own public server cluster is exactly same as running an virtual network, except that you can skip config the ipv4 addr.
+To run a public shared node:

-You can also join the official public server cluster with following command:
-
-```
-sudo easytier-core --network-name easytier --network-secret easytier -p tcp://public.easytier.cn:11010
+```bash
+# No need to specify IPv4 address for public shared nodes
+sudo easytier-core --network-name mysharednode --network-secret mysharednode
 ```

-
-### Configurations
-
-You can use ``easytier-core --help`` to view all configuration items
-
-## Roadmap
-
- [ ] Support features such TCP hole punching, KCP, FEC etc.
- [ ] Support iOS.
-
-## Community and Contribution
-
-We welcome and encourage community contributions! If you want to get involved, please submit a [GitHub PR](https://github.com/EasyTier/EasyTier/pulls). Detailed contribution guidelines can be found in [CONTRIBUTING.md](https://github.com/EasyTier/EasyTier/blob/main/CONTRIBUTING.md).
-
-## Related Projects and Resources
+## Related Projects

 - [ZeroTier](https://www.zerotier.com/): A global virtual network for connecting devices.
 - [TailScale](https://tailscale.com/): A VPN solution aimed at simplifying network configuration.
- [vpncloud](https://github.com/dswd/vpncloud): A P2P Mesh VPN
- [Candy](https://github.com/lanthora/candy): A reliable, low-latency, and anti-censorship virtual private network
+
+### Contact Us
+
+- 💬 **[Telegram Group](https://t.me/easytier)**
+- 👥 **[QQ Group]**
+  - No.1 [949700262](https://qm.qq.com/q/wFoTUChqZW)
+  - No.2 [837676408](https://qm.qq.com/q/4V33DrfgHe)
+  - No.3 [957189589](https://qm.qq.com/q/YNyTQjwlai)

 ## License

-EasyTier is released under the [Apache License 2.0](https://github.com/EasyTier/EasyTier/blob/main/LICENSE).
-
-## Contact
-
- Ask questions or report problems: [GitHub Issues](https://github.com/EasyTier/EasyTier/issues)
- Discussion and exchange: [GitHub Discussions](https://github.com/EasyTier/EasyTier/discussions)
- Telegram：https://t.me/easytier
- QQ Group: 949700262
+EasyTier is released under the [LGPL-3.0](https://github.com/EasyTier/EasyTier/blob/main/LICENSE).

 ## Sponsor

-<img src="assets/image-8.png" width="300">
-<img src="assets/image-9.png" width="300">
+CDN acceleration and security protection for this project are sponsored by Tencent EdgeOne.
+
+<p align="center">
+  <a href="https://edgeone.ai/?from=github" target="_blank">
+    <img src="assets/edgeone.png" width="200" alt="EdgeOne Logo">
+  </a>
+</p>
+
+Special thanks to [Langlang Cloud](https://langlangy.cn/?i26c5a5)  and [RainCloud](https://www.rainyun.com/NjM0NzQ1_) for sponsoring our public servers.
+
+<p align="center">
+<a href="https://langlangy.cn/?i26c5a5" target="_blank">
+<img src="assets/langlang.png" width="200">
+</a>
+<a href="https://langlangy.cn/?i26c5a5" target="_blank">
+<img src="assets/raincloud.png" width="200">
+</a>
+</p>
+
+
+If you find EasyTier helpful, please consider sponsoring us. Software development and maintenance require a lot of time and effort, and your sponsorship will help us better maintain and improve EasyTier.
+
+<p align="center">
+<img src="assets/wechat.png" width="200">
+<img src="assets/alipay.png" width="200">
+</p>
@@ -1,242 +1,245 @@
 # EasyTier

+[![Github release](https://img.shields.io/github/v/tag/EasyTier/EasyTier)](https://github.com/EasyTier/EasyTier/releases)
 [![GitHub](https://img.shields.io/github/license/EasyTier/EasyTier)](https://github.com/EasyTier/EasyTier/blob/main/LICENSE)
 [![GitHub last commit](https://img.shields.io/github/last-commit/EasyTier/EasyTier)](https://github.com/EasyTier/EasyTier/commits/main)
 [![GitHub issues](https://img.shields.io/github/issues/EasyTier/EasyTier)](https://github.com/EasyTier/EasyTier/issues)
 [![GitHub Core Actions](https://github.com/EasyTier/EasyTier/actions/workflows/core.yml/badge.svg)](https://github.com/EasyTier/EasyTier/actions/workflows/core.yml)
 [![GitHub GUI Actions](https://github.com/EasyTier/EasyTier/actions/workflows/gui.yml/badge.svg)](https://github.com/EasyTier/EasyTier/actions/workflows/gui.yml)
+[![GitHub Test Actions](https://github.com/EasyTier/EasyTier/actions/workflows/test.yml/badge.svg)](https://github.com/EasyTier/EasyTier/actions/workflows/test.yml)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/EasyTier/EasyTier)

 [简体中文](/README_CN.md) | [English](/README.md)

-**请访问 [EasyTier 官网](https://www.easytier.cn/) 以查看完整的文档。**
-
-一个简单、安全、去中心化的内网穿透 VPN 组网方案，使用 Rust 语言和 Tokio 框架实现。
+> ✨ 一个由 Rust 和 Tokio 驱动的简单、安全、去中心化的异地组网方案

 <p align="center">
-<img src="assets/image-6.png" width="300">
-<img src="assets/image-7.png" width="300">
+<img src="assets/config-page.png" width="300" alt="配置页面">
+<img src="assets/running-page.png" width="300" alt="运行页面">
 </p>

-## 特点
+📚 **[完整文档](https://easytier.cn)** | 🖥️ **[Web 控制台](https://easytier.cn/web)** | 📝 **[下载发布版本](https://github.com/EasyTier/EasyTier/releases)** | 🧩 **[第三方工具](https://easytier.cn/guide/installation_gui.html#%E7%AC%AC%E4%B8%89%E6%96%B9%E5%9B%BE%E5%BD%A2%E7%95%8C%E9%9D%A2)** | ❤️ **[赞助](#赞助)**

- **去中心化**：无需依赖中心化服务，节点平等且独立。
- **安全**：支持利用 WireGuard 加密通信，也支持 AES-GCM 加密保护中转流量。
- **高性能**：全链路零拷贝，性能与主流组网软件相当。
- **跨平台**：支持 MacOS/Linux/Windows/Android，未来将支持 IOS。可执行文件静态链接，部署简单。
- **无公网 IP 组网**：支持利用共享的公网节点组网，可参考 [配置指南](#无公网IP组网)
- **NAT 穿透**：支持基于 UDP 的 NAT 穿透，即使在复杂的网络环境下也能建立稳定的连接。
- **子网代理（点对网）**：节点可以将可访问的网段作为代理暴露给 VPN 子网，允许其他节点通过该节点访问这些子网。
- **智能路由**：根据流量智能选择链路，减少延迟，提高吞吐量。
- **TCP 支持**：在 UDP 受限的情况下，通过并发 TCP 链接提供可靠的数据传输，优化性能。
- **高可用性**：支持多路径和在检测到高丢包率或网络错误时切换到健康路径。
- **IPV6 支持**：支持利用 IPV6 组网。
- **多协议类型**: 支持使用 WebSocket、QUIC 等协议进行节点间通信。
- **Web 管理界面**：支持通过 [Web 界面](https://easytier.cn)管理节点。
+## 特性

-## 安装
+### 核心特性

-1. **下载预编译的二进制文件**
+- 🔒 **去中心化**：节点平等且独立，无需中心化服务
+- 🚀 **易于使用**：支持通过网页、客户端和命令行多种操作方式
+- 🌍 **跨平台**：支持 Win/MacOS/Linux/FreeBSD/Android 和 X86/ARM/MIPS 架构
+- 🔐 **安全**：AES-GCM 或 WireGuard 加密，防止中间人攻击

-    访问 [GitHub Release 页面](https://github.com/EasyTier/EasyTier/releases) 下载适用于您操作系统的二进制文件。Release 压缩包中同时包含命令行程序和图形界面程序。
+### 高级功能

-2. **通过 crates.io 安装**
+- 🔌 **高效 NAT 穿透**：支持 UDP 和 IPv6 穿透，可在 NAT4-NAT4 网络中工作
+- 🌐 **子网代理**：节点可以共享子网供其他节点访问
+- 🔄 **智能路由**：延迟优先和自动路由选择，提供最佳网络体验
+- ⚡ **高性能**：整个链路零拷贝，支持 TCP/UDP/WSS/WG 协议

-    ```sh
-    cargo install easytier
-    ```
+### 网络优化

-3. **通过源码安装**
-
-    ```sh
-    cargo install --git https://github.com/EasyTier/EasyTier.git easytier
-    ```
-
-4. **通过Docker Compose安装**
-
-    请访问 [EasyTier 官网](https://www.easytier.cn/) 以查看完整的文档。
-
-5. **使用一键脚本安装 (仅适用于 Linux)**
-
-    ```sh
-    wget -O /tmp/easytier.sh "https://raw.githubusercontent.com/EasyTier/EasyTier/main/script/install.sh" && bash /tmp/easytier.sh install
-    ```
-
-    使用本脚本安装的 Easytier 可以使用脚本的 uninstall/update 对其卸载/升级
-
-6. **使用 Homebrew 安装 (仅适用于 MacOS)**
-
-    ```sh
-    brew tap brewforge/chinese
-    brew install --cask easytier
-    ```
+- 📊 **UDP 丢包抗性**：KCP/QUIC 代理在高丢包环境下优化延迟和带宽
+- 🔧 **Web 管理**：通过 Web 界面轻松配置和监控
+- 🛠️ **零配置**：静态链接的可执行文件，简单部署

 ## 快速开始

-> 下文仅描述命令行工具的使用，图形界面程序可参考下述概念自行配置。
+### 📥 安装

-确保已按照 [安装指南](#安装) 安装 EasyTier，并且 easytier-core 和 easytier-cli 两个命令都已经可用。
+选择最适合您需求的安装方式：

-### 双节点组网
+Linux（推荐）：
+```bash
+curl -fsSL "https://github.com/EasyTier/EasyTier/blob/main/script/install.sh?raw=true" | sudo bash -s install
+```

-假设双节点的网络拓扑如下
+Homebrew（MacOS/Linux）：
+```bash
+brew tap brewforge/chinese
+brew install --cask easytier-gui
+```
+
+Windows（推荐，请以管理员权限运行）：
+```powershell
+irm "https://github.com/EasyTier/EasyTier/blob/main/script/install.ps1?raw=true" | iex
+```
+
+通过 cargo 安装（最新开发版本）：
+```bash
+cargo install --git https://github.com/EasyTier/EasyTier.git easytier
+```
+
+[下载预编译文件](https://github.com/EasyTier/EasyTier/releases)（推荐，支持所有平台）
+
+[通过 Docker 安装](https://easytier.cn/guide/installation.html#%E5%AE%89%E8%A3%85%E6%96%B9%E5%BC%8F)
+
+[安装 OpenWrt ipk 软件包](https://github.com/EasyTier/luci-app-easytier)
+
+附加步骤：
+
+[一键注册系统服务](https://easytier.cn/guide/network/oneclick-install-as-service.html)（系统启动时自动后台运行）
+
+### 🚀 基本用法
+
+#### 使用共享节点快速组网
+
+EasyTier 支持使用共享节点快速组网。当您没有公网 IP 时，可以使用公共共享节点。节点会自动尝试 NAT 穿透并建立 P2P 连接。当 P2P 失败时，数据将通过共享节点中继。
+
+使用共享节点时，每个进入网络的节点需要提供相同的 `--network-name` 和 `--network-secret` 参数作为网络的唯一标识符。
+
+以两个节点为例（请使用更复杂的网络名称以避免冲突）：
+
+1. 在节点 A 上运行：
+
+```bash
+# 以管理员权限运行
+sudo easytier-core -d --network-name abc --network-secret abc -p tcp://<共享节点IP>:11010
+```
+
+2. 在节点 B 上运行：
+
+```bash
+# 以管理员权限运行
+sudo easytier-core -d --network-name abc --network-secret abc -p tcp://<共享节点IP>:11010
+```
+
+执行成功后，可以使用 `easytier-cli` 检查网络状态：
+
+```text
+| ipv4         | hostname       | cost  | lat_ms | loss_rate | rx_bytes | tx_bytes | tunnel_proto | nat_type | id         | version         |
+| ------------ | -------------- | ----- | ------ | --------- | -------- | -------- | ------------ | -------- | ---------- | --------------- |
+| 10.126.126.1 | abc-1          | Local | *      | *         | *        | *        | udp          | FullCone | 439804259  | 2.6.2-70e69a38~ |
+| 10.126.126.2 | abc-2          | p2p   | 3.452  | 0         | 17.33 kB | 20.42 kB | udp          | FullCone | 390879727  | 2.6.2-70e69a38~ |
+|              | PublicServer_a | p2p   | 27.796 | 0.000     | 50.01 kB | 67.46 kB | tcp          | Unknown  | 3771642457 | 2.6.2-70e69a38~ |
+```
+
+您可以测试节点之间的连通性：
+
+```bash
+# 测试连通性
+ping 10.126.126.1
+ping 10.126.126.2
+```
+
+注意：如果无法 ping 通，可能是防火墙阻止了入站流量。请关闭防火墙或添加允许规则。
+
+为了提高可用性，您可以同时连接多个共享节点：
+
+```bash
+# 连接多个共享节点
+sudo easytier-core -d --network-name abc --network-secret abc -p tcp://<公共节点IP>:11010 -p udp://<公共节点IP>:11010
+```
+
+#### 去中心化组网
+
+EasyTier 本质上是去中心化的，没有服务器和客户端的区分。只要一个设备能与虚拟网络中的任何节点通信，它就可以加入虚拟网络。以下是如何设置去中心化网络：
+
+1. 启动第一个节点（节点 A）：
+
+```bash
+# 启动第一个节点
+sudo easytier-core -i 10.144.144.1
+```
+
+启动后，该节点将默认监听以下端口：
+- TCP：11010
+- UDP：11010
+- WebSocket：11011
+- WebSocket SSL：11012
+- WireGuard：11013
+
+2. 连接第二个节点（节点 B）：
+
+```bash
+# 使用第一个节点的公网 IP 连接
+sudo easytier-core -i 10.144.144.2 -p udp://第一个节点的公网IP:11010
+```
+
+3. 验证连接：
+
+```bash
+# 测试连通性
+ping 10.144.144.2
+
+# 查看已连接的对等节点
+easytier-cli peer
+
+# 查看路由信息
+easytier-cli route
+
+# 查看本地节点信息
+easytier-cli node
+```
+
+更多节点要加入网络，可以使用 `-p` 参数连接到网络中的任何现有节点：
+
+```bash
+# 使用任何现有节点的公网 IP 连接
+sudo easytier-core -i 10.144.144.3 -p udp://任何现有节点的公网IP:11010
+```
+
+### 🔍 高级功能
+
+#### 子网代理
+
+假设网络拓扑如下，节点 B 想要与其他节点共享其可访问的子网 10.1.1.0/24：

 ```mermaid
 flowchart LR

-subgraph 节点 A IP 22.1.1.1
-nodea[EasyTier\n10.144.144.1]
+subgraph 节点 A 公网 IP 22.1.1.1
+nodea[EasyTier<br/>10.144.144.1]
 end

 subgraph 节点 B
-nodeb[EasyTier\n10.144.144.2]
-end
-
-nodea <-----> nodeb
-
-```
-
-1. 在节点 A 上执行：
-
-    ```sh
-    sudo easytier-core --ipv4 10.144.144.1
-    ```
-
-    命令执行成功会有如下打印。
-
-    ![alt text](/assets/image-2.png)
-
-2. 在节点 B 执行
-
-    ```sh
-    sudo easytier-core --ipv4 10.144.144.2 --peers udp://22.1.1.1:11010
-    ```
-
-3. 测试联通性
-
-    两个节点应成功连接并能够在虚拟子网内通信
-
-    ```sh
-    ping 10.144.144.2
-    ```
-
-    使用 easytier-cli 查看子网中的节点信息
-
-    ```sh
-    easytier-cli peer
-    ```
-
-    ![alt text](/assets/image.png)
-
-    ```sh
-    easytier-cli route
-    ```
-
-    ![alt text](/assets/image-1.png)
-
-    ```sh
-    easytier-cli node
-    ```
-
-    ![alt text](assets/image-10.png)
-
---
-
-### 多节点组网
-
-基于刚才的双节点组网例子，如果有更多的节点需要加入虚拟网络，可以使用如下命令。
-
-```sh
-sudo easytier-core --ipv4 10.144.144.2 --peers udp://22.1.1.1:11010
-```
-
-其中 `--peers` 参数可以填写任意一个已经在虚拟网络中的节点的监听地址。
-
---
-
-### 子网代理（点对网）配置
-
-假设网络拓扑如下，节点 B 想将其可访问的子网 10.1.1.0/24 共享给其他节点。
-
-```mermaid
-flowchart LR
-
-subgraph 节点 A IP 22.1.1.1
-nodea[EasyTier\n10.144.144.1]
-end
-
-subgraph 节点 B
-nodeb[EasyTier\n10.144.144.2]
+nodeb[EasyTier<br/>10.144.144.2]
 end

 id1[[10.1.1.0/24]]

 nodea <--> nodeb <-.-> id1
-
 ```

-则节点 B 的 easytier 启动参数为（新增 -n 参数）
+要共享子网，在启动 EasyTier 时添加 `-n` 参数：

-```sh
-sudo easytier-core --ipv4 10.144.144.2 -n 10.1.1.0/24
+```bash
+# 与其他节点共享子网 10.1.1.0/24
+sudo easytier-core -i 10.144.144.2 -n 10.1.1.0/24
 ```

-子网代理信息会自动同步到虚拟网络的每个节点，各个节点会自动配置相应的路由，节点 A 可以通过如下命令检查子网代理是否生效。
+子网代理信息将自动同步到虚拟网络中的每个节点，每个节点将自动配置相应的路由。您可以验证子网代理设置：

-1. 检查路由信息是否已经同步，proxy_cidrs 列展示了被代理的子网。
+1. 检查路由信息是否已同步（proxy_cidrs 列显示代理的子网）：

-    ```sh
-    easytier-cli route
-    ```
-
-    ![alt text](/assets/image-3.png)
-
-2. 测试节点 A 是否可访问被代理子网下的节点
-
-    ```sh
-    ping 10.1.1.2
-    ```
-
---
-
-### 无公网IP组网
-
-EasyTier 支持共享公网节点进行组网。目前已部署共享的公网节点 ``tcp://public.easytier.cn:11010``。
-
-使用共享节点时，需要每个入网节点提供相同的 ``--network-name`` 和 ``--network-secret`` 参数，作为网络的唯一标识。
-
-以双节点为例，节点 A 执行：
-
-```sh
-sudo easytier-core -i 10.144.144.1 --network-name abc --network-secret abc -p tcp://public.easytier.cn:11010
+```bash
+# 查看路由信息
+easytier-cli route
 ```

-节点 B 执行
+![路由信息](/assets/image-3.png)

-```sh
-sudo easytier-core --ipv4 10.144.144.2 --network-name abc --network-secret abc -p tcp://public.easytier.cn:11010
+2. 测试是否可以访问代理子网中的节点：
+
+```bash
+# 测试到代理子网的连通性
+ping 10.1.1.2
 ```

-命令执行成功后，节点 A 即可通过虚拟 IP 10.144.144.2 访问节点 B。
+#### WireGuard 集成

---
-
-### 使用 WireGuard 客户端接入
-
-EasyTier 可以用作 WireGuard 服务端，让任意安装了 WireGuard 客户端的设备访问 EasyTier 网络。对于目前 EasyTier 不支持的平台 （如 iOS、Android 等），可以使用这种方式接入 EasyTier 网络。
-
-假设网络拓扑如下：
+EasyTier 可以作为 WireGuard 服务器，允许任何安装了 WireGuard 客户端的设备（包括 iOS 和 Android）访问 EasyTier 网络。以下是设置示例：

 ```mermaid
 flowchart LR

-ios[[iPhone \n 安装 WireGuard]]
+ios[[iPhone<br/>已安装 WireGuard]]

-subgraph 节点 A IP 22.1.1.1
-nodea[EasyTier\n10.144.144.1]
+subgraph 节点 A 公网 IP 22.1.1.1
+nodea[EasyTier<br/>10.144.144.1]
 end

 subgraph 节点 B
-nodeb[EasyTier\n10.144.144.2]
+nodeb[EasyTier<br/>10.144.144.2]
 end

 id1[[10.1.1.0/24]]
@@ -244,88 +247,79 @@ id1[[10.1.1.0/24]]
 ios <-.-> nodea <--> nodeb <-.-> id1
 ```

-我们需要 iPhone 通过节点 A 访问 EasyTier 网络，则可进行如下配置：
+1. 启动启用 WireGuard 门户的 EasyTier：

-在节点 A 的 easytier-core 命令中，加入 --vpn-portal 参数，指定 WireGuard 服务监听的端口，以及 WireGuard 网络使用的网段。
-
-```sh
-# 以下参数的含义为： 监听 0.0.0.0:11013 端口，WireGuard 使用 10.14.14.0/24 网段
-sudo easytier-core --ipv4 10.144.144.1 --vpn-portal wg://0.0.0.0:11013/10.14.14.0/24
+```bash
+# 在 0.0.0.0:11013 上监听，并使用 10.14.14.0/24 子网作为 WireGuard 客户端
+sudo easytier-core -i 10.144.144.1 --vpn-portal wg://0.0.0.0:11013/10.14.14.0/24
 ```

-easytier-core 启动成功后，使用 easytier-cli 获取 WireGuard Client 的配置。
+2. 获取 WireGuard 客户端配置：

-```sh
-$> easytier-cli vpn-portal
-portal_name: wireguard
-
-############### client_config_start ###############
-
-[Interface]
-PrivateKey = 9VDvlaIC9XHUvRuE06hD2CEDrtGF+0lDthgr9SZfIho=
-Address = 10.14.14.0/32 # should assign an ip from this cidr manually
-
-[Peer]
-PublicKey = zhrZQg4QdPZs8CajT3r4fmzcNsWpBL9ImQCUsnlXyGM=
-AllowedIPs = 10.144.144.0/24,10.14.14.0/24
-Endpoint = 0.0.0.0:11013 # should be the public ip(or domain) of the vpn server
-PersistentKeepalive = 25
-
-############### client_config_end ###############
-
-connected_clients:
-[]
+```bash
+# 获取 WireGuard 客户端配置
+easytier-cli vpn-portal
 ```

-使用 Client Config 前，需要将 Interface Address 和 Peer Endpoint 分别修改为客户端的 IP 和 EasyTier 节点的 IP。将配置文件导入 WireGuard 客户端，即可访问 EasyTier 网络。
+3. 在输出配置中：
+   - 将 `Interface.Address` 设置为 WireGuard 子网中的可用 IP
+   - 将 `Peer.Endpoint` 设置为您的 EasyTier 节点的公网 IP/域名
+   - 将修改后的配置导入到您的 WireGuard 客户端

---
+#### 自建公共共享节点

-### 自建公共中转服务器
+您可以运行自己的公共共享节点来帮助其他节点相互发现。公共共享节点只是一个普通的 EasyTier 网络（具有相同的网络名称和密钥），其他网络可以连接到它。

-每个虚拟网络（通过相同的网络名称和密钥建链）都可以充当公共服务器集群。其他网络的节点可以连接到公共服务器集群中的任意节点，无需公共 IP 即可发现彼此。
+要运行公共共享节点：

-运行自建的公共服务器集群与运行虚拟网络完全相同，不过可以跳过配置 ipv4 地址。
-
-也可以使用以下命令加入官方公共服务器集群，后续将实现公共服务器集群的节点间负载均衡：
-
-```
-sudo easytier-core --network-name easytier --network-secret easytier -p tcp://public.easytier.cn:11010
+```bash
+# 公共共享节点无需指定 IPv4 地址
+sudo easytier-core --network-name mysharednode --network-secret mysharednode
 ```

-### 其他配置
+网络设置成功后，您可以轻松配置它以在系统启动时自动启动。请参阅 [一键注册服务指南](https://easytier.cn/en/guide/network/oneclick-install-as-service.html) 了解如何将 EasyTier 注册为系统服务。

-可使用 ``easytier-core --help`` 查看全部配置项
+## 相关项目

-## 路线图
+- [ZeroTier](https://www.zerotier.com/)：用于连接设备的全球虚拟网络。
+- [TailScale](https://tailscale.com/)：旨在简化网络配置的 VPN 解决方案。

- [ ] 完善文档和用户指南。
- [ ] 支持 TCP 打洞、KCP、FEC 等特性。
- [ ] 支持 iOS。
+### 联系我们

-## 社区和贡献
-
-我们欢迎并鼓励社区贡献！如果你想参与进来，请提交 [GitHub PR](https://github.com/EasyTier/EasyTier/pulls)。详细的贡献指南可以在 [CONTRIBUTING.md](https://github.com/EasyTier/EasyTier/blob/main/CONTRIBUTING.md) 中找到。
-
-## 相关项目和资源
-
- [ZeroTier](https://www.zerotier.com/): 一个全球虚拟网络，用于连接设备。
- [TailScale](https://tailscale.com/): 一个旨在简化网络配置的 VPN 解决方案。
- [vpncloud](https://github.com/dswd/vpncloud): 一个 P2P Mesh VPN
- [Candy](https://github.com/lanthora/candy): 可靠、低延迟、抗审查的虚拟专用网络
+- 💬 **[Telegram 群组](https://t.me/easytier)**
+- 👥 **QQ 群**
+  - 一群 [949700262](https://qm.qq.com/q/wFoTUChqZW)
+  - 二群 [837676408](https://qm.qq.com/q/4V33DrfgHe)
+  - 三群 [957189589](https://qm.qq.com/q/YNyTQjwlai)

 ## 许可证

-EasyTier 根据 [Apache License 2.0](https://github.com/EasyTier/EasyTier/blob/main/LICENSE) 许可证发布。
-
-## 联系方式
-
- 提问或报告问题：[GitHub Issues](https://github.com/EasyTier/EasyTier/issues)
- 讨论和交流：[GitHub Discussions](https://github.com/EasyTier/EasyTier/discussions)
- QQ 群： 949700262
- Telegram：https://t.me/easytier
+EasyTier 在 [LGPL-3.0](https://github.com/EasyTier/EasyTier/blob/main/LICENSE) 许可下发布。

 ## 赞助

-<img src="assets/image-8.png" width="300">
-<img src="assets/image-9.png" width="300">
+本项目的 CDN 加速和安全防护由腾讯云 EdgeOne 赞助。
+
+<p align="center">
+<a href="https://edgeone.ai/?from=github" target="_blank">
+<img src="assets/edgeone.png" width="200">
+</a>
+</p>
+
+特别感谢 [浪浪云](https://langlangy.cn/?i26c5a5) 和 [雨云](https://www.rainyun.com/NjM0NzQ1_) 赞助我们的公共服务器。
+
+<p align="center">
+<a href="https://langlangy.cn/?i26c5a5" target="_blank">
+<img src="assets/langlang.png" width="200">
+</a>
+<a href="https://langlangy.cn/?i26c5a5" target="_blank">
+<img src="assets/raincloud.png" width="200">
+</a>
+</p>
+
+如果您觉得 EasyTier 有帮助，请考虑赞助我们。软件开发和维护需要大量的时间和精力，您的赞助将帮助我们更好地维护和改进 EasyTier。
+
+<p align="center">
+<img src="assets/wechat.png" width="200">
+<img src="assets/alipay.png" width="200">
+</p>
@@ -0,0 +1,116 @@
+# Android build environment
+{
+  pkgs,
+  nixpkgs,
+  system,
+}:
+
+let
+  androidEnv = pkgs.callPackage "${nixpkgs}/pkgs/development/mobile/androidenv" {
+    inherit pkgs;
+    licenseAccepted = true;
+  };
+
+  includeAuto = pkgs.stdenv.hostPlatform.isx86_64 || pkgs.stdenv.hostPlatform.isDarwin;
+  ndkVersion = "26.1.10909125";
+  ndkVersions = [ ndkVersion ];
+
+  sdkArgs = {
+    includeNDK = true;
+    includeSources = true;
+    includeSystemImages = false;
+    includeEmulator = false;
+    inherit ndkVersions;
+    useGoogleAPIs = true;
+    useGoogleTVAddOns = true;
+    buildToolsVersions = [ "34.0.0" ];
+    numLatestPlatformVersions = 10;
+    includeExtras = [
+      "extras;google;gcm"
+    ]
+    ++ pkgs.lib.optionals includeAuto [
+      "extras;google;auto"
+    ];
+    extraLicenses = [
+      "android-sdk-preview-license"
+      "android-googletv-license"
+      "android-sdk-arm-dbt-license"
+      "google-gdk-license"
+      "intel-android-extra-license"
+      "intel-android-sysimage-license"
+      "mips-android-sysimage-license"
+    ];
+  };
+
+  androidComposition = androidEnv.composeAndroidPackages sdkArgs;
+  androidSdk = androidComposition.androidsdk;
+  platformTools = androidComposition.platform-tools;
+  cmake = androidComposition.cmake;
+  ndkHostTag =
+    if pkgs.stdenv.isLinux then
+      "linux-x86_64"
+    else if pkgs.stdenv.isDarwin then
+      "darwin-x86_64"
+    else
+      "";
+  ndkToolchain = "${androidSdk}/libexec/android-sdk/ndk/${ndkVersion}/toolchains/llvm/prebuilt/${ndkHostTag}";
+in
+{
+  inherit
+    androidSdk
+    platformTools
+    cmake
+    ndkToolchain
+    ndkVersion
+    ;
+
+  # List of packages required for Android development
+  packages = [
+    pkgs.jdk # openjdk 21
+    androidSdk
+    platformTools
+    cmake
+    pkgs.glibc_multi.dev
+  ];
+
+  # Provide Rust extensions/targets for use by the upper-level flake
+  rust = {
+    extensions = [ "rust-std" ];
+    targets = [
+      "aarch64-linux-android"
+      "armv7-linux-androideabi"
+      "i686-linux-android"
+      "x86_64-linux-android"
+    ];
+  };
+
+  # Android environment variables and shellHook
+  envVars = {
+    LANG = "C.UTF-8";
+    LC_ALL = "C.UTF-8";
+    JAVA_HOME = "${pkgs.jdk}/lib/openjdk";
+    ANDROID_SDK_ROOT = "${androidSdk}/libexec/android-sdk";
+    ANDROID_NDK_ROOT = "\${ANDROID_SDK_ROOT}/ndk-bundle";
+    NDK_HOME = "${androidSdk}/libexec/android-sdk/ndk/${ndkVersion}";
+    LIBCLANG_PATH = "${ndkToolchain}/lib";
+    KCP_SYS_EXTRA_HEADER_PATH = "${ndkToolchain}/lib/clang/19/include:${pkgs.glibc_multi.dev}/include";
+    ZSTD_SYS_STATIC = "1";
+    BINDGEN_EXTRA_CLANG_ARGS = "--sysroot=${ndkToolchain}/sysroot -I${ndkToolchain}/lib/clang/17/include ";
+
+    shellHook = ''
+      echo "Android environment activated"
+      export GRADLE_OPTS="-Dorg.gradle.project.android.aapt2FromMavenOverride=$(echo "$ANDROID_SDK_ROOT/build-tools/"*"/aapt2")"
+      cmake_root="$(echo "$ANDROID_SDK_ROOT/cmake/"*/)"
+      export PATH="$cmake_root/bin:$PATH"
+
+      unset NIX_CFLAGS_COMPILE
+      unset NIX_CFLAGS_COMPILE_FOR_BUILD
+
+      cat <<EOF > easytier-gui/local.properties
+      sdk.dir=$ANDROID_SDK_ROOT
+      ndk.dir=$ANDROID_NDK_ROOT
+      cmake.dir=$cmake_root
+      EOF
+    '';
+  };
+}
@@ -0,0 +1,17 @@
+[package]
+name = "easytier-android-jni"
+version = "0.1.0"
+edition.workspace = true
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+jni = "0.21"
+once_cell = "1.18.0"
+log = "0.4"
+android_logger = "0.13"
+serde = { version = "1.0.220", features = ["derive"] }
+serde_json = "1.0"
+easytier = { path = "../../easytier" }
+easytier-ffi = { path = "../easytier-ffi", default-features = false, features = ["ffi-dataplane"] }
@@ -0,0 +1,282 @@
+# EasyTier Android JNI
+
+这是 EasyTier 的 Android JNI 绑定库，允许 Android 应用程序调用 EasyTier 的网络功能。
+
+## 功能特性
+
+- 🚀 完整的 EasyTier FFI 接口封装
+- 📱 原生 Android JNI 支持
+- 🔧 支持多种 Android 架构 (arm64-v8a, armeabi-v7a, x86, x86_64)
+- 🛡️ 类型安全的 Java 接口
+- 🔌 支持通过 JSON 调用已暴露的 EasyTier RPC 查询/管理接口
+- 📝 详细的错误处理和日志记录
+
+## 支持的架构
+
+- `arm64-v8a` (aarch64-linux-android)
+- `armeabi-v7a` (armv7-linux-androideabi)
+- `x86` (i686-linux-android)
+- `x86_64` (x86_64-linux-android)
+
+## 构建要求
+
+### 系统要求
+
+- Rust 1.70+
+- Android NDK r21+
+- Linux/macOS 开发环境
+
+### 环境设置
+
+1. **安装 Rust**
+   ```bash
+   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+   source ~/.cargo/env
+   ```
+
+2. **安装 Android NDK**
+   - 下载 Android NDK: https://developer.android.com/ndk/downloads
+   - 解压到合适的目录
+   - 设置环境变量:
+     ```bash
+     export ANDROID_NDK_ROOT=/path/to/android-ndk
+     ```
+
+3. **添加 Android 目标**
+   ```bash
+   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
+   ```
+
+## 构建步骤
+
+1. **克隆项目并进入目录**
+   ```bash
+   cd /path/to/EasyTier/easytier-contrib/easytier-android-jni
+   ```
+
+2. **运行构建脚本**
+   ```bash
+   ./build.sh
+   ```
+
+3. **构建完成后，库文件将生成在 `target/android/` 目录下**
+   ```
+   target/android/
+   ├── arm64-v8a/
+   │   └── libeasytier_android_jni.so
+   ├── armeabi-v7a/
+   │   └── libeasytier_android_jni.so
+   ├── x86/
+   │   └── libeasytier_android_jni.so
+   └── x86_64/
+       └── libeasytier_android_jni.so
+   ```
+
+## Android 项目集成
+
+### 1. 复制库文件
+
+将生成的 `.so` 文件复制到您的 Android 项目中：
+
+```
+your-android-project/
+└── src/main/
+    ├── jniLibs/
+    │   ├── arm64-v8a/
+    │   │   └── libeasytier_android_jni.so
+    │   ├── armeabi-v7a/
+    │   │   └── libeasytier_android_jni.so
+    │   ├── x86/
+    │   │   └── libeasytier_android_jni.so
+    │   └── x86_64/
+    │       └── libeasytier_android_jni.so
+    └── java/
+        └── com/easytier/jni/
+            └── EasyTierJNI.java
+```
+
+### 2. 复制 Java 接口
+
+将 `java/com/easytier/jni/EasyTierJNI.java` 复制到您的 Android 项目的相应包路径下。
+
+### 3. 添加权限
+
+在 `AndroidManifest.xml` 中添加必要的权限：
+
+```xml
+<uses-permission android:name="android.permission.INTERNET" />
+<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
+```
+
+## 使用示例
+
+### 基本使用
+
+```java
+import com.easytier.jni.EasyTierJNI;
+import java.util.Map;
+
+public class EasyTierManager {
+    
+    // 初始化网络实例
+    public void startNetwork() {
+        String config = """
+            inst_name = "my_instance"
+            network = "my_network"
+            """; 
+        
+        try {
+            // 解析配置
+            int result = EasyTierJNI.parseConfig(config);
+            if (result != 0) {
+                String error = EasyTierJNI.getLastError();
+                throw new RuntimeException("配置解析失败: " + error);
+            }
+            
+            // 启动网络实例
+            result = EasyTierJNI.runNetworkInstance(config);
+            if (result != 0) {
+                String error = EasyTierJNI.getLastError();
+                throw new RuntimeException("网络实例启动失败: " + error);
+            }
+            
+            System.out.println("EasyTier 网络实例启动成功");
+            
+        } catch (RuntimeException e) {
+            System.err.println("启动失败: " + e.getMessage());
+        }
+    }
+    
+    // 获取网络信息
+    public void getNetworkInfo() {
+        try {
+            Map<String, String> infos = EasyTierJNI.collectNetworkInfosAsMap(10);
+            for (Map.Entry<String, String> entry : infos.entrySet()) {
+                System.out.println(entry.getKey() + ": " + entry.getValue());
+            }
+        } catch (RuntimeException e) {
+            System.err.println("获取网络信息失败: " + e.getMessage());
+        }
+    }
+    
+    // 停止所有实例
+    public void stopNetwork() {
+        try {
+            int result = EasyTierJNI.stopAllInstances();
+            if (result == 0) {
+                System.out.println("所有网络实例已停止");
+            }
+        } catch (RuntimeException e) {
+            System.err.println("停止网络失败: " + e.getMessage());
+        }
+    }
+}
+```
+
+### 通用 JSON RPC
+
+`EasyTierJNI.callJsonRpc(serviceName, methodName, domainName, payloadJson)` 可以调用已暴露的
+EasyTier RPC 服务，payload 和返回值均为 protobuf JSON。该接口不支持
+`api.manage.WebClientService`；实例启动、保留、删除、信息收集仍使用专用 JNI API。
+
+```java
+String response = EasyTierJNI.callJsonRpc(
+    "api.logger.LoggerRpcService",
+    "get_logger_config",
+    "{}"
+);
+```
+
+### VPN 服务集成
+
+如果您要在 Android VPN 服务中使用：
+
+```java
+public class EasyTierVpnService extends VpnService {
+    
+    @Override
+    public int onStartCommand(Intent intent, int flags, int startId) {
+        // 建立 VPN 连接
+        ParcelFileDescriptor vpnInterface = establishVpnInterface();
+        
+        if (vpnInterface != null) {
+            int fd = vpnInterface.getFd();
+            
+            // 设置 TUN 文件描述符
+            try {
+                EasyTierJNI.setTunFd("my_instance", fd);
+            } catch (RuntimeException e) {
+                Log.e("EasyTier", "设置 TUN FD 失败", e);
+            }
+        }
+        
+        return START_STICKY;
+    }
+    
+    private ParcelFileDescriptor establishVpnInterface() {
+        Builder builder = new Builder();
+        builder.setMtu(1500);
+        builder.addAddress("10.0.0.2", 24);
+        builder.addRoute("0.0.0.0", 0);
+        builder.setSession("EasyTier VPN");
+        
+        return builder.establish();
+    }
+}
+```
+
+## API 参考
+
+### EasyTierJNI 类方法
+
+| 方法 | 描述 | 参数 | 返回值 |
+|------|------|------|--------|
+| `parseConfig(String config)` | 解析 TOML 配置 | config: 配置字符串 | 0=成功, -1=失败 |
+| `runNetworkInstance(String config)` | 启动网络实例 | config: 配置字符串 | 0=成功, -1=失败 |
+| `setTunFd(String instanceName, int fd)` | 设置 TUN 文件描述符 | instanceName: 实例名, fd: 文件描述符 | 0=成功, -1=失败 |
+| `retainNetworkInstance(String[] names)` | 保留指定实例 | names: 实例名数组 | 0=成功, -1=失败 |
+| `collectNetworkInfos(int maxLength)` | 收集网络信息 | maxLength: 最大条目数 | 信息字符串数组 |
+| `collectNetworkInfosAsMap(int maxLength)` | 收集网络信息为 Map | maxLength: 最大条目数 | Map<String, String> |
+| `getLastError()` | 获取最后错误 | 无 | 错误消息字符串 |
+| `stopAllInstances()` | 停止所有实例 | 无 | 0=成功, -1=失败 |
+| `retainSingleInstance(String name)` | 保留单个实例 | name: 实例名 | 0=成功, -1=失败 |
+
+## 故障排除
+
+### 常见问题
+
+1. **构建失败: "Android NDK not found"**
+   - 确保设置了 `ANDROID_NDK_ROOT` 环境变量
+   - 检查 NDK 路径是否正确
+
+2. **运行时错误: "java.lang.UnsatisfiedLinkError"**
+   - 确保 `.so` 文件放在正确的 `jniLibs` 目录下
+   - 检查目标架构是否匹配
+
+3. **配置解析失败**
+   - 检查 TOML 配置格式是否正确
+   - 使用 `getLastError()` 获取详细错误信息
+
+### 调试技巧
+
+- 启用 Android 日志查看 JNI 层的日志输出
+- 使用 `adb logcat -s EasyTier-JNI` 查看相关日志
+- 检查 `getLastError()` 返回的错误信息
+
+## 许可证
+
+本项目遵循与 EasyTier 主项目相同的许可证。
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request 来改进这个项目。
+
+## 相关链接
+
+- [EasyTier 主项目](https://github.com/EasyTier/EasyTier)
+- [Android NDK 文档](https://developer.android.com/ndk)
+- [Rust JNI 文档](https://docs.rs/jni/)
@@ -0,0 +1,17 @@
+use std::{env, path::PathBuf};
+
+fn main() {
+    let target_os = env::var("CARGO_CFG_TARGET_OS").unwrap_or_default();
+    if !matches!(target_os.as_str(), "android" | "linux") {
+        return;
+    }
+
+    let manifest_dir = PathBuf::from(env::var("CARGO_MANIFEST_DIR").unwrap());
+    let exports = manifest_dir.join("exports.map");
+    println!("cargo:rerun-if-changed={}", exports.display());
+    println!(
+        "cargo:rustc-cdylib-link-arg=-Wl,--version-script={}",
+        exports.display()
+    );
+    println!("cargo:rustc-cdylib-link-arg=-Wl,--exclude-libs,ALL");
+}
@@ -0,0 +1,129 @@
+#!/bin/bash
+
+# EasyTier Android JNI 构建脚本
+# 用于编译适用于 Android 平台的 JNI 库
+# 使用 cargo-ndk 工具简化 Android 编译过程
+
+set -e
+
+# 颜色输出
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+REPO_ROOT=$(git rev-parse --show-toplevel)
+
+echo -e "${GREEN}EasyTier Android JNI 构建脚本 (使用 cargo-ndk)${NC}"
+echo "=============================================="
+
+# 检查 Rust 是否安装
+if ! command -v rustc &> /dev/null; then
+    echo -e "${RED}错误: 未找到 Rust 编译器，请先安装 Rust${NC}"
+    exit 1
+fi
+
+# 检查 cargo 是否安装
+if ! command -v cargo &> /dev/null; then
+    echo -e "${RED}错误: 未找到 Cargo，请先安装 Rust 工具链${NC}"
+    exit 1
+fi
+
+# 检查 cargo-ndk 是否安装
+if ! cargo ndk --version &> /dev/null; then
+    echo -e "${YELLOW}cargo-ndk 未安装，正在安装...${NC}"
+    cargo install cargo-ndk
+    if ! cargo ndk --version &> /dev/null; then
+        echo -e "${RED}错误: cargo-ndk 安装失败${NC}"
+        exit 1
+    fi
+fi
+
+echo -e "${GREEN}cargo-ndk 版本: $(cargo ndk --version)${NC}"
+
+# Android 目标架构映射 (cargo-ndk 使用的架构名称)
+# ANDROID_TARGETS=("arm64-v8a" "armeabi-v7a" "x86" "x86_64")
+ANDROID_TARGETS=("arm64-v8a")
+
+# Android 架构到 Rust target 的映射
+declare -A TARGET_MAP
+TARGET_MAP["arm64-v8a"]="aarch64-linux-android"
+TARGET_MAP["armeabi-v7a"]="armv7-linux-androideabi"
+TARGET_MAP["x86"]="i686-linux-android"
+TARGET_MAP["x86_64"]="x86_64-linux-android"
+
+# 检查并安装所需的 Rust target
+echo -e "${YELLOW}检查并安装 Android 目标架构...${NC}"
+for android_target in "${ANDROID_TARGETS[@]}"; do
+    rust_target="${TARGET_MAP[$android_target]}"
+    if ! rustup target list --installed | grep -q "$rust_target"; then
+        echo -e "${YELLOW}安装目标架构: $rust_target (for $android_target)${NC}"
+        rustup target add "$rust_target"
+    else
+        echo -e "${GREEN}目标架构已安装: $rust_target (for $android_target)${NC}"
+    fi
+done
+
+# 创建输出目录
+OUTPUT_DIR="./target/android"
+mkdir -p "$OUTPUT_DIR"
+
+# 构建函数
+build_for_target() {
+    local android_target=$1
+    echo -e "${YELLOW}构建目标: $android_target${NC}"
+    
+    # 首先构建 easytier-ffi
+    echo -e "${YELLOW}构建 easytier-ffi for $android_target${NC}"
+    (cd $REPO_ROOT/easytier-contrib/easytier-ffi && cargo ndk -t $android_target build --release)
+    
+    # 构建 JNI 库
+    cargo ndk -t $android_target build --release
+    
+    # 复制库文件到输出目录
+    # cargo-ndk 使用 Rust target 名称作为目录名，而不是 Android 架构名称
+    rust_target="${TARGET_MAP[$android_target]}"
+    mkdir -p "$OUTPUT_DIR/$android_target"
+    cp "$REPO_ROOT/target/$rust_target/release/libeasytier_android_jni.so" "$OUTPUT_DIR/$android_target/"
+    cp "$REPO_ROOT/target/$rust_target/release/libeasytier_ffi.so" "$OUTPUT_DIR/$android_target/"
+    echo -e "${GREEN}库文件已复制到: $OUTPUT_DIR/$android_target/${NC}"
+}
+
+# 检查 Android NDK (cargo-ndk 会自动处理 NDK 路径)
+if [ -z "$ANDROID_NDK_ROOT" ] && [ -z "$ANDROID_NDK_HOME" ] && [ -z "$NDK_HOME" ]; then
+    echo -e "${YELLOW}警告: 未设置 Android NDK 环境变量${NC}"
+    echo "cargo-ndk 将尝试自动检测 NDK 路径"
+    echo "如果构建失败，请设置以下环境变量之一:"
+    echo "  - ANDROID_NDK_ROOT"
+    echo "  - ANDROID_NDK_HOME" 
+    echo "  - NDK_HOME"
+else
+    if [ -n "$ANDROID_NDK_ROOT" ]; then
+        echo -e "${GREEN}使用 Android NDK: $ANDROID_NDK_ROOT${NC}"
+    elif [ -n "$ANDROID_NDK_HOME" ]; then
+        echo -e "${GREEN}使用 Android NDK: $ANDROID_NDK_HOME${NC}"
+    elif [ -n "$NDK_HOME" ]; then
+        echo -e "${GREEN}使用 Android NDK: $NDK_HOME${NC}"
+    fi
+fi
+
+# 构建所有目标
+echo -e "${YELLOW}开始构建所有目标架构...${NC}"
+for target in "${ANDROID_TARGETS[@]}"; do
+    build_for_target "$target"
+done
+
+echo -e "${GREEN}构建完成！${NC}"
+echo -e "${GREEN}所有库文件已生成到: $OUTPUT_DIR${NC}"
+echo ""
+echo "目录结构:"
+ls -la "$OUTPUT_DIR"/*/
+
+echo ""
+echo -e "${YELLOW}使用说明:${NC}"
+echo "1. 将生成的 .so 文件复制到您的 Android 项目的 src/main/jniLibs/ 目录下"
+echo "2. 将 java/com/easytier/jni/EasyTierJNI.java 复制到您的 Android 项目中"
+echo "3. 在您的 Android 代码中调用 EasyTierJNI 类的方法"
+echo ""
+echo -e "${GREEN}注意: 此脚本使用 cargo-ndk 工具，无需手动设置复杂的环境变量${NC}"
+echo -e "${GREEN}cargo-ndk 会自动处理交叉编译所需的工具链配置${NC}"
@@ -0,0 +1,56 @@
+# EasyTier Android JNI 示例配置文件
+# 这是一个基本的配置示例，展示如何配置 EasyTier 网络实例
+
+# 实例名称 (必需)
+inst_name = "android_instance"
+
+# 网络名称 (必需)
+network = "my_easytier_network"
+
+# 网络密钥 (可选，用于网络加密)
+# network_secret = "your_secret_key_here"
+
+# 监听地址 (可选)
+# listeners = ["tcp://0.0.0.0:11010", "udp://0.0.0.0:11010"]
+
+# 对等节点地址 (可选)
+# peers = ["tcp://peer1.example.com:11010", "udp://peer2.example.com:11010"]
+
+# 虚拟 IP 地址 (可选)
+# ipv4 = "10.144.144.1"
+
+# 主机名 (可选)
+# hostname = "android-device"
+
+# 启用 IPv6 (可选)
+# ipv6 = "fd00::1"
+
+# 代理网络 (可选)
+# proxy_networks = ["192.168.1.0/24"]
+
+# 退出节点 (可选)
+# exit_nodes = ["peer1"]
+
+# 启用加密 (可选)
+# enable_encryption = true
+
+# 启用 IPv4 转发 (可选)
+# enable_ipv4 = true
+
+# 启用 IPv6 转发 (可选)
+# enable_ipv6 = false
+
+# MTU 设置 (可选)
+# mtu = 1420
+
+# 日志级别 (可选: error, warn, info, debug, trace)
+# log_level = "info"
+
+# 禁用 P2P (可选)
+# disable_p2p = false
+
+# 使用多路径 (可选)
+# use_multi_path = true
+
+# 延迟优先 (可选)
+# latency_first = false
@@ -0,0 +1,7 @@
+{
+    global:
+        Java_com_easytier_jni_EasyTierJNI_*;
+        Java_com_easytier_jni_EasyTierDataPlaneJNI_*;
+    local:
+        *;
+};
@@ -0,0 +1,451 @@
+package com.easytier.jni
+
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.currentCoroutineContext
+import kotlinx.coroutines.ensureActive
+import kotlinx.coroutines.withContext
+
+/**
+ * EasyTier data-plane API for Android.
+ *
+ * Dataplane APIs do not create or start an EasyTier instance by themselves.
+ * Start an instance with [EasyTierJNI.runNetworkInstance] first, then pass the
+ * same `instanceName` to [EasyTierDataPlane.tcpConnect],
+ * [EasyTierDataPlane.tcpBind], or [EasyTierDataPlane.udpBind]. If that instance
+ * is not running, the native start call fails and the coroutine wrapper throws
+ * the last EasyTier FFI error.
+ *
+ * Typical setup:
+ * ```
+ * val instanceName = "android-dataplane-demo"
+ * val config = """
+ *     instance_name = "$instanceName"
+ *     ipv4 = "10.144.0.1"
+ *     listeners = ["tcp://0.0.0.0:11010"]
+ *
+ *     [network_identity]
+ *     network_name = "android-dataplane-demo"
+ *     network_secret = "replace-with-a-real-secret"
+ *
+ *     [[peer]]
+ *     uri = "tcp://peer.example.com:11010"
+ *
+ *     [flags]
+ *     no_tun = true
+ *     bind_device = false
+ * """.trimIndent()
+ *
+ * EasyTierJNI.runNetworkInstance(config)
+ * ```
+ *
+ * After the instance is running, most callers should use [EasyTierDataPlane]
+ * and the socket/stream classes below. [EasyTierDataPlaneJNI] is the low-level
+ * native op-handle ABI used by the coroutine wrappers.
+ *
+ * TCP client usage:
+ * ```
+ * val stream = EasyTierDataPlane.tcpConnect(instanceName, "10.144.0.2", 8080, 5_000)
+ * try {
+ *     stream.write("ping".toByteArray(), 5_000)
+ *     val reply = stream.read(4096, 5_000)
+ * } finally {
+ *     stream.close()
+ * }
+ * ```
+ *
+ * TCP server usage:
+ * ```
+ * val listener = EasyTierDataPlane.tcpBind(instanceName, 8080, 5_000)
+ * try {
+ *     val stream = listener.accept(30_000)
+ *     try {
+ *         stream.write(stream.read(4096, 5_000), 5_000)
+ *     } finally {
+ *         stream.close()
+ *     }
+ * } finally {
+ *     listener.close()
+ * }
+ * ```
+ *
+ * UDP usage:
+ * ```
+ * val socket = EasyTierDataPlane.udpBind(instanceName, 0, 5_000)
+ * try {
+ *     socket.sendTo("10.144.0.2", 9000, "ping".toByteArray(), 5_000)
+ *     val packet = socket.recvFrom(4096, 5_000)
+ * } finally {
+ *     socket.close()
+ * }
+ * ```
+ *
+ * Operation model:
+ * - Each suspend function starts one native async op, waits on Dispatchers.IO,
+ *   then consumes the op with the matching finish call.
+ * - Coroutine cancellation cancels and frees the native op.
+ * - Returned stream/listener/socket handles must be closed by the caller.
+ * - Input ByteArray data is copied by the native start call; output data is
+ *   copied into Kotlin ByteArray before the native buffer is freed.
+ */
+
+/** Data-plane IPv4/port pair returned by EasyTier FFI. */
+data class DataPlaneSocketAddress(val ip: String, val port: Int)
+
+/** Result of a completed TCP connect op. */
+data class DataPlaneTcpConnectResult(val handle: Long, val localAddress: DataPlaneSocketAddress)
+
+/** Result of a completed TCP bind op. */
+data class DataPlaneTcpBindResult(val handle: Long, val localAddress: DataPlaneSocketAddress)
+
+/** Result of a completed TCP accept op. */
+data class DataPlaneTcpAcceptResult(
+        val handle: Long,
+        val localAddress: DataPlaneSocketAddress,
+        val peerAddress: DataPlaneSocketAddress
+)
+
+/** Result of a completed TCP read op. */
+data class DataPlaneTcpReadResult(val data: ByteArray)
+
+/** Result of a completed UDP bind op. */
+data class DataPlaneUdpBindResult(val handle: Long, val localAddress: DataPlaneSocketAddress)
+
+/** Result of a completed UDP recv_from op. */
+data class DataPlaneUdpRecvResult(
+        val data: ByteArray,
+        val peerAddress: DataPlaneSocketAddress
+)
+
+/** TCP data-plane stream handle. Call [close] when the stream is no longer needed. */
+class DataPlaneTcpStream(
+        val handle: Long,
+        val localAddress: DataPlaneSocketAddress? = null,
+        val peerAddress: DataPlaneSocketAddress? = null
+) {
+    /** Read up to [maxLength] bytes, waiting at most [timeoutMs] in native code. */
+    suspend fun read(maxLength: Int, timeoutMs: Long): ByteArray =
+            EasyTierDataPlane.tcpRead(this, maxLength, timeoutMs)
+
+    /** Write [data], waiting at most [timeoutMs] in native code. */
+    suspend fun write(data: ByteArray, timeoutMs: Long): Int =
+            EasyTierDataPlane.tcpWrite(this, data, timeoutMs)
+
+    /** Close the native TCP stream handle. */
+    fun close(): Int = EasyTierDataPlaneJNI.dataPlaneTcpClose(handle)
+}
+
+/** TCP data-plane listener handle. Call [close] when the listener is no longer needed. */
+class DataPlaneTcpListener(val handle: Long, val localAddress: DataPlaneSocketAddress) {
+    /** Accept one TCP data-plane stream. */
+    suspend fun accept(timeoutMs: Long): DataPlaneTcpStream =
+            EasyTierDataPlane.tcpAccept(this, timeoutMs)
+
+    /** Close the native TCP listener handle. */
+    fun close(): Int = EasyTierDataPlaneJNI.dataPlaneTcpListenerClose(handle)
+}
+
+/** UDP data-plane socket handle. Call [close] when the socket is no longer needed. */
+class DataPlaneUdpSocket(val handle: Long, val localAddress: DataPlaneSocketAddress) {
+    /** Send one UDP datagram to [dstIp]:[dstPort]. */
+    suspend fun sendTo(
+            dstIp: String,
+            dstPort: Int,
+            data: ByteArray,
+            timeoutMs: Long
+    ): Int = EasyTierDataPlane.udpSendTo(this, dstIp, dstPort, data, timeoutMs)
+
+    /** Receive one UDP datagram and its peer address. */
+    suspend fun recvFrom(maxLength: Int, timeoutMs: Long): DataPlaneUdpRecvResult =
+            EasyTierDataPlane.udpRecvFrom(this, maxLength, timeoutMs)
+
+    /** Close the native UDP socket handle. */
+    fun close(): Int = EasyTierDataPlaneJNI.dataPlaneUdpClose(handle)
+}
+
+/**
+ * Low-level native data-plane JNI entry points.
+ *
+ * These functions mirror the Rust FFI op-handle ABI directly. They are exposed
+ * for completeness, but most Android callers should use [EasyTierDataPlane]
+ * instead so coroutine cancellation and op cleanup are handled consistently.
+ */
+object EasyTierDataPlaneJNI {
+    init {
+        System.loadLibrary("easytier_android_jni")
+    }
+
+    @JvmStatic external fun dataPlaneAsyncOpStatus(handle: Long): Int
+
+    @JvmStatic external fun dataPlaneAsyncOpWait(handle: Long, timeoutMs: Long): Int
+
+    @JvmStatic external fun dataPlaneAsyncOpCancel(handle: Long): Int
+
+    @JvmStatic external fun dataPlaneAsyncOpFree(handle: Long): Int
+
+    @JvmStatic
+    external fun dataPlaneTcpConnectStart(
+            instanceName: String,
+            dstIp: String,
+            dstPort: Int,
+            timeoutMs: Long
+    ): Long
+
+    @JvmStatic external fun dataPlaneTcpConnectFinish(op: Long): DataPlaneTcpConnectResult?
+
+    @JvmStatic
+    external fun dataPlaneTcpBindStart(
+            instanceName: String,
+            localPort: Int,
+            timeoutMs: Long
+    ): Long
+
+    @JvmStatic external fun dataPlaneTcpBindFinish(op: Long): DataPlaneTcpBindResult?
+
+    @JvmStatic external fun dataPlaneTcpAcceptStart(handle: Long, timeoutMs: Long): Long
+
+    @JvmStatic external fun dataPlaneTcpAcceptFinish(op: Long): DataPlaneTcpAcceptResult?
+
+    @JvmStatic external fun dataPlaneTcpReadStart(handle: Long, maxLength: Int, timeoutMs: Long): Long
+
+    @JvmStatic external fun dataPlaneTcpReadFinish(op: Long): DataPlaneTcpReadResult?
+
+    @JvmStatic external fun dataPlaneTcpWriteStart(handle: Long, data: ByteArray, timeoutMs: Long): Long
+
+    @JvmStatic external fun dataPlaneTcpWriteFinish(op: Long): Int
+
+    @JvmStatic
+    external fun dataPlaneUdpBindStart(
+            instanceName: String,
+            localPort: Int,
+            timeoutMs: Long
+    ): Long
+
+    @JvmStatic external fun dataPlaneUdpBindFinish(op: Long): DataPlaneUdpBindResult?
+
+    @JvmStatic
+    external fun dataPlaneUdpSendToStart(
+            handle: Long,
+            dstIp: String,
+            dstPort: Int,
+            data: ByteArray,
+            timeoutMs: Long
+    ): Long
+
+    @JvmStatic external fun dataPlaneUdpSendToFinish(op: Long): Int
+
+    @JvmStatic external fun dataPlaneUdpRecvFromStart(handle: Long, maxLength: Int, timeoutMs: Long): Long
+
+    @JvmStatic external fun dataPlaneUdpRecvFromFinish(op: Long): DataPlaneUdpRecvResult?
+
+    @JvmStatic external fun dataPlaneTcpClose(handle: Long): Int
+
+    @JvmStatic external fun dataPlaneTcpListenerClose(handle: Long): Int
+
+    @JvmStatic external fun dataPlaneUdpClose(handle: Long): Int
+}
+
+/** Coroutine-friendly Android data-plane API. */
+object EasyTierDataPlane {
+    private const val DATA_PLANE_OP_PENDING = 0
+    private const val DATA_PLANE_OP_READY = 1
+    private const val DATA_PLANE_OP_FAILED = -1
+    private const val DATA_PLANE_OP_INVALID = -2
+    private const val DATA_PLANE_WAIT_SLICE_MS = 50L
+
+    /** Connect to a TCP endpoint through the named EasyTier instance. */
+    @JvmStatic
+    suspend fun tcpConnect(
+            instanceName: String,
+            dstIp: String,
+            dstPort: Int,
+            timeoutMs: Long
+    ): DataPlaneTcpStream {
+        val op =
+                requireOp(
+                        EasyTierDataPlaneJNI.dataPlaneTcpConnectStart(
+                                instanceName,
+                                dstIp,
+                                dstPort,
+                                timeoutMs
+                        )
+                )
+        val result = awaitOp(op) {
+            EasyTierDataPlaneJNI.dataPlaneTcpConnectFinish(it) ?: throw lastDataPlaneException()
+        }
+        return DataPlaneTcpStream(result.handle, result.localAddress)
+    }
+
+    /** Bind a TCP data-plane listener on [localPort]. Port 0 asks EasyTier to allocate one. */
+    @JvmStatic
+    suspend fun tcpBind(
+            instanceName: String,
+            localPort: Int,
+            timeoutMs: Long
+    ): DataPlaneTcpListener {
+        val op =
+                requireOp(
+                        EasyTierDataPlaneJNI.dataPlaneTcpBindStart(
+                                instanceName,
+                                localPort,
+                                timeoutMs
+                        )
+                )
+        val result = awaitOp(op) {
+            EasyTierDataPlaneJNI.dataPlaneTcpBindFinish(it) ?: throw lastDataPlaneException()
+        }
+        return DataPlaneTcpListener(result.handle, result.localAddress)
+    }
+
+    /** Accept one TCP stream from [listener]. */
+    @JvmStatic
+    suspend fun tcpAccept(listener: DataPlaneTcpListener, timeoutMs: Long): DataPlaneTcpStream {
+        val op =
+                requireOp(
+                        EasyTierDataPlaneJNI.dataPlaneTcpAcceptStart(listener.handle, timeoutMs)
+                )
+        val result = awaitOp(op) {
+            EasyTierDataPlaneJNI.dataPlaneTcpAcceptFinish(it) ?: throw lastDataPlaneException()
+        }
+        return DataPlaneTcpStream(result.handle, result.localAddress, result.peerAddress)
+    }
+
+    /** Read up to [maxLength] bytes from [stream]. */
+    @JvmStatic
+    suspend fun tcpRead(
+            stream: DataPlaneTcpStream,
+            maxLength: Int,
+            timeoutMs: Long
+    ): ByteArray {
+        val op =
+                requireOp(
+                        EasyTierDataPlaneJNI.dataPlaneTcpReadStart(
+                                stream.handle,
+                                maxLength,
+                                timeoutMs
+                        )
+                )
+        return awaitOp(op) {
+            EasyTierDataPlaneJNI.dataPlaneTcpReadFinish(it)?.data
+                    ?: throw lastDataPlaneException()
+        }
+    }
+
+    /** Write [data] to [stream]. */
+    @JvmStatic
+    suspend fun tcpWrite(stream: DataPlaneTcpStream, data: ByteArray, timeoutMs: Long): Int {
+        val op =
+                requireOp(
+                        EasyTierDataPlaneJNI.dataPlaneTcpWriteStart(
+                                stream.handle,
+                                data,
+                                timeoutMs
+                        )
+                )
+        return awaitOp(op) { EasyTierDataPlaneJNI.dataPlaneTcpWriteFinish(it) }
+    }
+
+    /** Bind a UDP data-plane socket on [localPort]. Port 0 asks EasyTier to allocate one. */
+    @JvmStatic
+    suspend fun udpBind(
+            instanceName: String,
+            localPort: Int,
+            timeoutMs: Long
+    ): DataPlaneUdpSocket {
+        val op =
+                requireOp(
+                        EasyTierDataPlaneJNI.dataPlaneUdpBindStart(
+                                instanceName,
+                                localPort,
+                                timeoutMs
+                        )
+                )
+        val result = awaitOp(op) {
+            EasyTierDataPlaneJNI.dataPlaneUdpBindFinish(it) ?: throw lastDataPlaneException()
+        }
+        return DataPlaneUdpSocket(result.handle, result.localAddress)
+    }
+
+    /** Send one UDP datagram through [socket]. */
+    @JvmStatic
+    suspend fun udpSendTo(
+            socket: DataPlaneUdpSocket,
+            dstIp: String,
+            dstPort: Int,
+            data: ByteArray,
+            timeoutMs: Long
+    ): Int {
+        val op =
+                requireOp(
+                        EasyTierDataPlaneJNI.dataPlaneUdpSendToStart(
+                                socket.handle,
+                                dstIp,
+                                dstPort,
+                                data,
+                                timeoutMs
+                        )
+                )
+        return awaitOp(op) { EasyTierDataPlaneJNI.dataPlaneUdpSendToFinish(it) }
+    }
+
+    /** Receive one UDP datagram through [socket]. */
+    @JvmStatic
+    suspend fun udpRecvFrom(
+            socket: DataPlaneUdpSocket,
+            maxLength: Int,
+            timeoutMs: Long
+    ): DataPlaneUdpRecvResult {
+        val op =
+                requireOp(
+                        EasyTierDataPlaneJNI.dataPlaneUdpRecvFromStart(
+                                socket.handle,
+                                maxLength,
+                                timeoutMs
+                        )
+                )
+        return awaitOp(op) {
+            EasyTierDataPlaneJNI.dataPlaneUdpRecvFromFinish(it) ?: throw lastDataPlaneException()
+        }
+    }
+
+    private fun requireOp(op: Long): Long {
+        if (op == 0L) {
+            throw lastDataPlaneException()
+        }
+        return op
+    }
+
+    private suspend fun <T> awaitOp(op: Long, finish: (Long) -> T): T =
+            withContext(Dispatchers.IO) {
+                var consumed = false
+                try {
+                    awaitReady(op)
+                    val result = finish(op)
+                    consumed = true
+                    result
+                } catch (e: CancellationException) {
+                    EasyTierDataPlaneJNI.dataPlaneAsyncOpCancel(op)
+                    throw e
+                } finally {
+                    if (!consumed) {
+                        EasyTierDataPlaneJNI.dataPlaneAsyncOpFree(op)
+                    }
+                }
+            }
+
+    private suspend fun awaitReady(op: Long) {
+        while (true) {
+            currentCoroutineContext().ensureActive()
+            when (EasyTierDataPlaneJNI.dataPlaneAsyncOpWait(op, DATA_PLANE_WAIT_SLICE_MS)) {
+                DATA_PLANE_OP_READY, DATA_PLANE_OP_FAILED -> return
+                DATA_PLANE_OP_PENDING -> Unit
+                DATA_PLANE_OP_INVALID -> throw RuntimeException("Data-plane async operation is invalid")
+                else -> throw RuntimeException("Unknown data-plane async operation status")
+            }
+        }
+    }
+
+    private fun lastDataPlaneException(): RuntimeException {
+        return RuntimeException(EasyTierJNI.getLastError() ?: "EasyTier data-plane call failed")
+    }
+}
@@ -0,0 +1,147 @@
+package com.easytier.jni
+
+fun interface ConfigServerEventCallback {
+    fun onEvent(eventJson: String)
+}
+
+/** EasyTier JNI 接口类 提供 Android 应用调用 EasyTier 核心网络功能的接口 */
+object EasyTierJNI {
+    init {
+        // 加载本地库
+        System.loadLibrary("easytier_android_jni")
+    }
+
+    /**
+     * 设置 TUN 文件描述符
+     * @param instanceName 实例名称
+     * @param fd TUN 文件描述符
+     * @return 0 表示成功，-1 表示失败
+     * @throws RuntimeException 当操作失败时抛出异常
+     */
+    @JvmStatic external fun setTunFd(instanceName: String, fd: Int): Int
+
+    /**
+     * 解析配置字符串
+     * @param config TOML 格式的配置字符串
+     * @return 0 表示成功，-1 表示失败
+     * @throws RuntimeException 当配置解析失败时抛出异常
+     */
+    @JvmStatic external fun parseConfig(config: String): Int
+
+    /**
+     * 运行网络实例
+     * @param config TOML 格式的配置字符串
+     * @return 0 表示成功，-1 表示失败
+     * @throws RuntimeException 当实例启动失败时抛出异常
+     */
+    @JvmStatic external fun runNetworkInstance(config: String): Int
+
+    /**
+     * 启动配置服务器客户端
+     * @param url 配置服务器 URL
+     * @param hostname 主机名，传入 null 使用系统主机名
+     * @param machineId 稳定机器 ID，由调用方负责持久化
+     * @param secureMode 是否启用 secure mode
+     * @param callback 远程配置应用/删除事件回调
+     * @return 0 表示成功，-1 表示失败
+     * @throws RuntimeException 当客户端启动失败时抛出异常
+     */
+    @JvmStatic
+    external fun startConfigServerClient(
+            url: String,
+            hostname: String?,
+            machineId: String,
+            secureMode: Boolean,
+            callback: ConfigServerEventCallback?
+    ): Int
+
+    /**
+     * 停止配置服务器客户端
+     * @return 0 表示成功，-1 表示失败
+     * @throws RuntimeException 当客户端停止失败时抛出异常
+     */
+    @JvmStatic external fun stopConfigServerClient(): Int
+
+    /** 查询配置服务器客户端是否已连接 */
+    @JvmStatic external fun isConfigServerClientConnected(): Boolean
+
+    /**
+     * 保留指定的网络实例，停止其他实例
+     * @param instanceNames 要保留的实例名称数组，传入 null 或空数组将停止所有实例
+     * @return 0 表示成功，-1 表示失败
+     * @throws RuntimeException 当操作失败时抛出异常
+     */
+    @JvmStatic external fun retainNetworkInstance(instanceNames: Array<String>?): Int
+
+    /**
+     * 收集网络信息
+     * @param maxLength 最大返回条目数
+     * @return 包含网络信息的 JSON 字符串
+     * @throws RuntimeException 当操作失败时抛出异常
+     */
+    @JvmStatic external fun collectNetworkInfos(maxLength: Int): String?
+
+    /**
+     * 列出当前运行的实例名称和实例 ID。
+     * @param maxLength 最大返回条目数
+     * @return JSON 对象，key 为 instance name，value 为 instance id
+     * @throws RuntimeException 当操作失败时抛出异常
+     */
+    @JvmStatic external fun listInstances(maxLength: Int): String?
+
+    /**
+     * 调用暴露的 EasyTier RPC 方法，输入和输出均为 protobuf JSON 字符串。
+     *
+     * 不支持 api.manage.WebClientService；实例启动、保留、删除、信息收集请继续使用专用 JNI API。
+     * payloadJson 需要包含目标 RPC 所需的 instance selector。
+     *
+     * @param serviceName RPC 服务名，例如 api.instance.PeerManageRpcService
+     * @param methodName RPC 方法名，支持 snake_case 或 proto 方法名
+     * @param domainName 仅 TcpProxyRpcService 使用；传 null 或空字符串默认 tcp
+     * @param payloadJson protobuf JSON 请求体
+     * @return protobuf JSON 响应体
+     * @throws RuntimeException 当 RPC 调用失败时抛出异常
+     */
+    @JvmStatic
+    external fun callJsonRpc(
+            serviceName: String,
+            methodName: String,
+            domainName: String?,
+            payloadJson: String
+    ): String?
+
+    /**
+     * 调用不需要 domainName 的 EasyTier RPC 方法。
+     */
+    @JvmStatic
+    fun callJsonRpc(serviceName: String, methodName: String, payloadJson: String): String? {
+        return callJsonRpc(serviceName, methodName, null, payloadJson)
+    }
+
+    /**
+     * 获取最后的错误消息
+     * @return 错误消息字符串，如果没有错误则返回 null
+     */
+    @JvmStatic external fun getLastError(): String?
+
+    /**
+     * 便利方法：停止所有网络实例
+     * @return 0 表示成功，-1 表示失败
+     * @throws RuntimeException 当操作失败时抛出异常
+     */
+    @JvmStatic
+    fun stopAllInstances(): Int {
+        return retainNetworkInstance(null)
+    }
+
+    /**
+     * 便利方法：停止指定实例外的所有实例
+     * @param instanceName 要保留的实例名称
+     * @return 0 表示成功，-1 表示失败
+     * @throws RuntimeException 当操作失败时抛出异常
+     */
+    @JvmStatic
+    fun retainSingleInstance(instanceName: String): Int {
+        return retainNetworkInstance(arrayOf(instanceName))
+    }
+}
@@ -0,0 +1,252 @@
+package com.easytier.jni
+
+import android.app.Activity
+import android.content.Intent
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import com.squareup.moshi.Moshi
+import com.squareup.wire.WireJsonAdapterFactory
+import common.Ipv4Inet
+import web.NetworkInstanceRunningInfoMap
+
+fun parseIpv4InetToString(inet: Ipv4Inet?): String? {
+    val addr = inet?.address?.addr ?: return null
+    val networkLength = inet.network_length
+
+    // 将 int32 转换为 IPv4 字符串
+    val ip =
+            String.format(
+                    "%d.%d.%d.%d",
+                    (addr shr 24) and 0xFF,
+                    (addr shr 16) and 0xFF,
+                    (addr shr 8) and 0xFF,
+                    addr and 0xFF
+            )
+
+    return "$ip/$networkLength"
+}
+
+/** EasyTier 管理类 负责管理 EasyTier 实例的生命周期、监控网络状态变化、控制 VpnService */
+class EasyTierManager(
+        private val activity: Activity,
+        private val instanceName: String,
+        private val networkConfig: String
+) {
+    companion object {
+        private const val TAG = "EasyTierManager"
+        private const val MONITOR_INTERVAL = 3000L // 3秒监控间隔
+    }
+
+    private val handler = Handler(Looper.getMainLooper())
+    private var isRunning = false
+    private var currentIpv4: String? = null
+    private var currentProxyCidrs: List<String> = emptyList()
+    private var vpnServiceIntent: Intent? = null
+
+    // JSON 解析器
+    private val moshi = Moshi.Builder().add(WireJsonAdapterFactory()).build()
+    private val adapter = moshi.adapter(NetworkInstanceRunningInfoMap::class.java)
+
+    // 监控任务
+    private val monitorRunnable =
+            object : Runnable {
+                override fun run() {
+                    if (isRunning) {
+                        monitorNetworkStatus()
+                        handler.postDelayed(this, MONITOR_INTERVAL)
+                    }
+                }
+            }
+
+    /** 启动 EasyTier 实例和监控 */
+    fun start() {
+        if (isRunning) {
+            Log.w(TAG, "EasyTier 实例已经在运行中")
+            return
+        }
+
+        try {
+            // 启动 EasyTier 实例
+            val result = EasyTierJNI.runNetworkInstance(networkConfig)
+            if (result == 0) {
+                isRunning = true
+                Log.i(TAG, "EasyTier 实例启动成功: $instanceName")
+
+                // 开始监控网络状态
+                handler.post(monitorRunnable)
+            } else {
+                Log.e(TAG, "EasyTier 实例启动失败: $result")
+                val error = EasyTierJNI.getLastError()
+                Log.e(TAG, "错误信息: $error")
+            }
+        } catch (e: Exception) {
+            Log.e(TAG, "启动 EasyTier 实例时发生异常", e)
+        }
+    }
+
+    /** 停止 EasyTier 实例和监控 */
+    fun stop() {
+        if (!isRunning) {
+            Log.w(TAG, "EasyTier 实例未在运行")
+            return
+        }
+
+        isRunning = false
+
+        // 停止监控任务
+        handler.removeCallbacks(monitorRunnable)
+
+        try {
+            // 停止 VpnService
+            stopVpnService()
+
+            // 停止 EasyTier 实例
+            EasyTierJNI.stopAllInstances()
+            Log.i(TAG, "EasyTier 实例已停止: $instanceName")
+
+            // 重置状态
+            currentIpv4 = null
+            currentProxyCidrs = emptyList()
+        } catch (e: Exception) {
+            Log.e(TAG, "停止 EasyTier 实例时发生异常", e)
+        }
+    }
+
+    /** 监控网络状态 */
+    private fun monitorNetworkStatus() {
+        try {
+            val infosJson = EasyTierJNI.collectNetworkInfos(10)
+            if (infosJson.isNullOrEmpty()) {
+                Log.d(TAG, "未获取到网络信息")
+                return
+            }
+
+            val networkInfoMap = parseNetworkInfo(infosJson)
+            val networkInfo = networkInfoMap?.map?.get(instanceName)
+
+            if (networkInfo == null) {
+                Log.d(TAG, "未找到实例 $instanceName 的网络信息")
+                return
+            }
+
+            Log.d(TAG, "网络信息: $networkInfo")
+
+            // 检查实例是否正在运行
+            if (!networkInfo.running) {
+                Log.w(TAG, "EasyTier 实例未运行: ${networkInfo.error_msg}")
+                return
+            }
+
+            val newIpv4Inet = networkInfo.my_node_info?.virtual_ipv4
+
+            if (newIpv4Inet == null) {
+                Log.w(TAG, "EasyTier No Ipv4: $networkInfo")
+                return
+            }
+
+            // 获取当前节点的 IPv4 地址
+            val newIpv4 = parseIpv4InetToString(newIpv4Inet)
+
+            // 获取所有节点的 proxy_cidrs
+            val newProxyCidrs = mutableListOf<String>()
+            networkInfo.routes?.forEach { route ->
+                route.proxy_cidrs?.let { cidrs -> newProxyCidrs.addAll(cidrs) }
+            }
+
+            // 检查是否有变化
+            val ipv4Changed = newIpv4 != currentIpv4
+            val proxyCidrsChanged = newProxyCidrs != currentProxyCidrs
+
+            if (ipv4Changed || proxyCidrsChanged) {
+                Log.i(TAG, "网络状态发生变化:")
+                Log.i(TAG, "  IPv4: $currentIpv4 -> $newIpv4")
+                Log.i(TAG, "  Proxy CIDRs: $currentProxyCidrs -> $newProxyCidrs")
+
+                // 更新状态
+                currentIpv4 = newIpv4
+                currentProxyCidrs = newProxyCidrs.toList()
+
+                // 重启 VpnService
+                if (newIpv4 != null) {
+                    restartVpnService(newIpv4, newProxyCidrs)
+                }
+            } else {
+                Log.d(TAG, "网络状态无变化 - IPv4: $currentIpv4, Proxy CIDRs: ${currentProxyCidrs.size} 个")
+            }
+        } catch (e: Exception) {
+            Log.e(TAG, "监控网络状态时发生异常", e)
+        }
+    }
+
+    /** 解析网络信息 JSON */
+    private fun parseNetworkInfo(jsonString: String): NetworkInstanceRunningInfoMap? {
+        return try {
+            adapter.fromJson(jsonString)
+        } catch (e: Exception) {
+            Log.e(TAG, "解析网络信息失败", e)
+            null
+        }
+    }
+
+    /** 重启 VpnService */
+    private fun restartVpnService(ipv4: String, proxyCidrs: List<String>) {
+        try {
+            // 先停止现有的 VpnService
+            stopVpnService()
+
+            // 启动新的 VpnService
+            startVpnService(ipv4, proxyCidrs)
+        } catch (e: Exception) {
+            Log.e(TAG, "重启 VpnService 时发生异常", e)
+        }
+    }
+
+    /** 启动 VpnService */
+    private fun startVpnService(ipv4: String, proxyCidrs: List<String>) {
+        try {
+            val intent = Intent(activity, EasyTierVpnService::class.java)
+            intent.putExtra("ipv4_address", ipv4)
+            intent.putStringArrayListExtra("proxy_cidrs", ArrayList(proxyCidrs))
+            intent.putExtra("instance_name", instanceName)
+
+            activity.startService(intent)
+            vpnServiceIntent = intent
+
+            Log.i(TAG, "VpnService 已启动 - IPv4: $ipv4, Proxy CIDRs: $proxyCidrs")
+        } catch (e: Exception) {
+            Log.e(TAG, "启动 VpnService 时发生异常", e)
+        }
+    }
+
+    /** 停止 VpnService */
+    private fun stopVpnService() {
+        try {
+            vpnServiceIntent?.let { intent ->
+                activity.stopService(intent)
+                Log.i(TAG, "VpnService 已停止")
+            }
+            vpnServiceIntent = null
+        } catch (e: Exception) {
+            Log.e(TAG, "停止 VpnService 时发生异常", e)
+        }
+    }
+
+    /** 获取当前状态信息 */
+    fun getStatus(): EasyTierStatus {
+        return EasyTierStatus(
+                isRunning = isRunning,
+                instanceName = instanceName,
+                currentIpv4 = currentIpv4,
+                currentProxyCidrs = currentProxyCidrs.toList()
+        )
+    }
+
+    /** 状态数据类 */
+    data class EasyTierStatus(
+            val isRunning: Boolean,
+            val instanceName: String,
+            val currentIpv4: String?,
+            val currentProxyCidrs: List<String>
+    )
+}
@@ -0,0 +1,143 @@
+package com.easytier.jni
+
+import android.content.Intent
+import android.net.VpnService
+import android.os.ParcelFileDescriptor
+import android.util.Log
+import kotlin.concurrent.thread
+
+class EasyTierVpnService : VpnService() {
+
+    private var vpnInterface: ParcelFileDescriptor? = null
+    private var isRunning = false
+    private var instanceName: String? = null
+
+    companion object {
+        private const val TAG = "EasyTierVpnService"
+    }
+
+    override fun onCreate() {
+        super.onCreate()
+        Log.d(TAG, "VPN Service created")
+    }
+
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        // 获取传入的参数
+        val ipv4Address = intent?.getStringExtra("ipv4_address")
+        val proxyCidrs = intent?.getStringArrayListExtra("proxy_cidrs") ?: arrayListOf()
+        instanceName = intent?.getStringExtra("instance_name")
+
+        if (ipv4Address == null || instanceName == null) {
+            Log.e(TAG, "缺少必要参数: ipv4Address=$ipv4Address, instanceName=$instanceName")
+            stopSelf()
+            return START_NOT_STICKY
+        }
+
+        Log.i(
+                TAG,
+                "启动 VPN Service - IPv4: $ipv4Address, Proxy CIDRs: $proxyCidrs, Instance: $instanceName"
+        )
+
+        thread {
+            try {
+                setupVpnInterface(ipv4Address, proxyCidrs)
+            } catch (t: Throwable) {
+                Log.e(TAG, "VPN 设置失败", t)
+                stopSelf()
+            }
+        }
+
+        return START_STICKY
+    }
+
+    private fun setupVpnInterface(ipv4Address: String, proxyCidrs: List<String>) {
+        try {
+            // 解析 IPv4 地址和网络长度
+            val (ip, networkLength) = parseIpv4Address(ipv4Address)
+
+            // 1. 准备 VpnService.Builder
+            val builder = Builder()
+            builder.setSession("EasyTier VPN")
+                    .addAddress(ip, networkLength)
+                    .addDnsServer("223.5.5.5")
+                    .addDnsServer("114.114.114.114")
+                    .addDisallowedApplication("com.easytier.easytiervpn")
+
+            // 2. 添加路由表 - 为每个 proxy CIDR 添加路由
+            proxyCidrs.forEach { cidr ->
+                try {
+                    val (routeIp, routeLength) = parseCidr(cidr)
+                    builder.addRoute(routeIp, routeLength)
+                    Log.d(TAG, "添加路由: $routeIp/$routeLength")
+                } catch (e: Exception) {
+                    Log.w(TAG, "解析 CIDR 失败: $cidr", e)
+                }
+            }
+
+            // 3. 构建虚拟网络接口
+            vpnInterface = builder.establish()
+
+            if (vpnInterface == null) {
+                Log.e(TAG, "创建 VPN 接口失败")
+                return
+            }
+
+            Log.i(TAG, "VPN 接口创建成功")
+
+            // 4. 将 TUN 文件描述符传递给 EasyTier
+            instanceName?.let { name ->
+                val fd = vpnInterface!!.fd
+                val result = EasyTierJNI.setTunFd(name, fd)
+                if (result == 0) {
+                    Log.i(TAG, "TUN 文件描述符设置成功: $fd")
+                } else {
+                    Log.e(TAG, "TUN 文件描述符设置失败: $result")
+                }
+            }
+
+            isRunning = true
+
+            // 5. 保持服务运行
+            while (isRunning && vpnInterface != null) {
+                Thread.sleep(1000)
+            }
+        } catch (t: Throwable) {
+            Log.e(TAG, "VPN 接口设置过程中发生错误", t)
+        } finally {
+            cleanup()
+        }
+    }
+
+    /** 解析 IPv4 地址，返回 IP 和网络长度 */
+    private fun parseIpv4Address(ipv4Address: String): Pair<String, Int> {
+        return if (ipv4Address.contains("/")) {
+            val parts = ipv4Address.split("/")
+            Pair(parts[0], parts[1].toInt())
+        } else {
+            // 默认使用 /24 网络
+            Pair(ipv4Address, 24)
+        }
+    }
+
+    /** 解析 CIDR，返回 IP 和网络长度 */
+    private fun parseCidr(cidr: String): Pair<String, Int> {
+        val parts = cidr.split("/")
+        if (parts.size != 2) {
+            throw IllegalArgumentException("无效的 CIDR 格式: $cidr")
+        }
+        return Pair(parts[0], parts[1].toInt())
+    }
+
+    private fun cleanup() {
+        isRunning = false
+        vpnInterface?.close()
+        vpnInterface = null
+        Log.i(TAG, "VPN 接口已清理")
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+        Log.d(TAG, "VPN Service destroyed")
+        cleanup()
+    }
+}
@@ -0,0 +1,41 @@
+# 使用说明
+
+1. 需要将 proto 文件放入 app/src/main/proto
+2. android/gradle/libs.versions.toml 中加入依赖
+
+```
+# Wire 核心运行时
+android-wire-runtime = { group = "com.squareup.wire", name = "wire-runtime", version = "5.3.11" }
+moshi = { module = "com.squareup.moshi:moshi", version.ref = "moshi" }
+android-wire-moshi-adapter = { group = "com.squareup.wire", name = "wire-moshi-adapter", version = "5.3.11" }
+kotlinx-serialization-json = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-json", version = "1.9.0" }
+```
+
+3. build.gradle.kts 中加入
+
+```
+plugins {
+    ...
+    alias(libs.plugins.wire)
+}
+
+dependencies {
+    ...
+    implementation(libs.android.wire.runtime)
+    implementation(libs.android.wire.moshi.adapter)
+    implementation(libs.moshi)
+}
+
+...
+
+wire {
+    kotlin {
+        rpcRole = "none"
+    }
+}
+```
+
+4. 调用 easytier-contrib/easytier-android-jni/build.sh 生成 jni 和 ffi 的 so 文件。
+并将生成的 so 文件放到 android/app/src/main/jniLibs/arm64-v8a 目录下。
+
+5. 使用 EasyTierManager 可以拉起 EasyTier 实例并启动 Android VpnService 组件。
@@ -0,0 +1,124 @@
+use std::{
+    ffi::{CStr, c_char, c_void},
+    sync::{Arc, Mutex, MutexGuard},
+};
+
+use easytier_ffi::ConfigServerEventCallback;
+use jni::JNIEnv;
+use jni::objects::{GlobalRef, JObject, JValue};
+use once_cell::sync::Lazy;
+
+use crate::error;
+
+pub(crate) struct JniConfigServerCallback {
+    java_vm: jni::JavaVM,
+    callback: GlobalRef,
+}
+
+static CONFIG_SERVER_CALLBACK: Lazy<Mutex<Option<Arc<JniConfigServerCallback>>>> =
+    Lazy::new(|| Mutex::new(None));
+
+pub(crate) fn lock_callback_storage()
+-> Result<MutexGuard<'static, Option<Arc<JniConfigServerCallback>>>, String> {
+    CONFIG_SERVER_CALLBACK
+        .lock()
+        .map_err(|e| format!("Failed to lock config server callback: {}", e))
+}
+
+pub(crate) fn new_callback(
+    env: &mut JNIEnv,
+    callback: &JObject,
+) -> Result<Arc<JniConfigServerCallback>, String> {
+    let java_vm = env
+        .get_java_vm()
+        .map_err(|e| format!("Failed to get JavaVM: {:?}", e))?;
+    let callback = env
+        .new_global_ref(callback)
+        .map_err(|e| format!("Failed to create callback global ref: {:?}", e))?;
+    Ok(Arc::new(JniConfigServerCallback { java_vm, callback }))
+}
+
+pub(crate) fn callback_fn(
+    callback: &Option<Arc<JniConfigServerCallback>>,
+) -> ConfigServerEventCallback {
+    callback
+        .as_ref()
+        .map(|_| config_server_event_callback as unsafe extern "C" fn(*const c_char, *mut c_void))
+}
+
+pub(crate) fn user_data(callback: &Option<Arc<JniConfigServerCallback>>) -> *mut c_void {
+    callback
+        .as_ref()
+        .map(|callback| Arc::as_ptr(callback) as *mut c_void)
+        .unwrap_or(std::ptr::null_mut())
+}
+
+impl JniConfigServerCallback {
+    fn clear_pending_exception(
+        env: &mut JNIEnv,
+        context: &str,
+        error: &dyn std::fmt::Debug,
+    ) -> String {
+        match env.exception_check() {
+            Ok(true) => {
+                if let Err(clear_err) = env.exception_clear() {
+                    return format!(
+                        "{}: {:?}; failed to clear pending Java exception: {:?}",
+                        context, error, clear_err
+                    );
+                }
+            }
+            Ok(false) => {}
+            Err(check_err) => {
+                return format!(
+                    "{}: {:?}; failed to check pending Java exception: {:?}",
+                    context, error, check_err
+                );
+            }
+        }
+
+        format!("{}: {:?}", context, error)
+    }
+
+    fn on_event(&self, event_json: *const c_char) -> Result<(), String> {
+        let event_json = unsafe { CStr::from_ptr(event_json) }
+            .to_str()
+            .map_err(|e| format!("Invalid config server event JSON: {:?}", e))?;
+        let mut env = self
+            .java_vm
+            .attach_current_thread()
+            .map_err(|e| format!("Failed to attach callback thread: {:?}", e))?;
+        let event_json = env.new_string(event_json).map_err(|e| {
+            Self::clear_pending_exception(&mut env, "Failed to create event string", &e)
+        })?;
+
+        if let Err(e) = env.call_method(
+            self.callback.as_obj(),
+            "onEvent",
+            "(Ljava/lang/String;)V",
+            &[JValue::from(&event_json)],
+        ) {
+            return Err(Self::clear_pending_exception(
+                &mut env,
+                "Failed to call config server callback",
+                &e,
+            ));
+        }
+        Ok(())
+    }
+}
+
+unsafe extern "C" fn config_server_event_callback(
+    event_json: *const c_char,
+    user_data: *mut c_void,
+) {
+    if event_json.is_null() || user_data.is_null() {
+        return;
+    }
+
+    let callback = unsafe { &*(user_data as *const JniConfigServerCallback) };
+
+    if let Err(error) = callback.on_event(event_json) {
+        error::set_callback_error(error);
+    }
+}
@@ -0,0 +1,140 @@
+use std::ptr;
+
+use easytier_ffi::{
+    in_config_server_callback, is_config_server_client_connected, start_config_server_client,
+    stop_config_server_client,
+};
+use jni::JNIEnv;
+use jni::objects::{JClass, JObject, JString};
+use jni::sys::{JNI_FALSE, JNI_TRUE, jboolean, jint};
+
+use crate::{
+    callback, error,
+    strings::{jstring_to_cstring, optional_jstring_to_cstring},
+};
+
+pub(crate) fn start_config_server_client_jni(
+    env: &mut JNIEnv,
+    config_server_url: JString,
+    hostname: JString,
+    machine_id: JString,
+    secure_mode: jboolean,
+    callback_obj: JObject,
+) -> jint {
+    if in_config_server_callback() {
+        error::throw_exception(
+            env,
+            "Cannot start config server client from config server callback",
+        );
+        return -1;
+    }
+
+    let config_server_url = match jstring_to_cstring(env, &config_server_url) {
+        Ok(cstr) => cstr,
+        Err(e) => {
+            error::throw_exception(env, &format!("Invalid config server URL: {}", e));
+            return -1;
+        }
+    };
+    let hostname = match optional_jstring_to_cstring(env, &hostname) {
+        Ok(cstr) => cstr,
+        Err(e) => {
+            error::throw_exception(env, &format!("Invalid hostname: {}", e));
+            return -1;
+        }
+    };
+    let machine_id = match jstring_to_cstring(env, &machine_id) {
+        Ok(cstr) => cstr,
+        Err(e) => {
+            error::throw_exception(env, &format!("Invalid machine ID: {}", e));
+            return -1;
+        }
+    };
+
+    let callback_ref = if callback_obj.is_null() {
+        None
+    } else {
+        match callback::new_callback(env, &callback_obj) {
+            Ok(state) => Some(state),
+            Err(e) => {
+                error::throw_exception(env, &e);
+                return -1;
+            }
+        }
+    };
+
+    let mut callback_guard = match callback::lock_callback_storage() {
+        Ok(guard) => guard,
+        Err(e) => {
+            error::throw_exception(env, &e);
+            return -1;
+        }
+    };
+    if callback_guard.is_none() {
+        error::clear_callback_error();
+    }
+
+    let callback_fn = callback::callback_fn(&callback_ref);
+    let user_data = callback::user_data(&callback_ref);
+    let result = unsafe {
+        start_config_server_client(
+            config_server_url.as_ptr(),
+            hostname
+                .as_ref()
+                .map(|value| value.as_ptr())
+                .unwrap_or(ptr::null()),
+            machine_id.as_ptr(),
+            secure_mode == JNI_TRUE,
+            callback_fn,
+            user_data,
+        )
+    };
+    if result != 0 {
+        if let Some(error_msg) = error::get_last_error() {
+            error::throw_exception(env, &error_msg);
+        }
+        return result;
+    }
+
+    *callback_guard = callback_ref;
+    result
+}
+
+pub(crate) fn stop_config_server_client_jni(mut env: JNIEnv, _class: JClass) -> jint {
+    if in_config_server_callback() {
+        let result = stop_config_server_client();
+        if result != 0
+            && let Some(error_msg) = error::get_last_error()
+        {
+            error::throw_exception(&mut env, &error_msg);
+        }
+        return result;
+    }
+
+    let mut callback_guard = match callback::lock_callback_storage() {
+        Ok(guard) => guard,
+        Err(e) => {
+            error::throw_exception(&mut env, &e);
+            return -1;
+        }
+    };
+
+    let result = stop_config_server_client();
+    if result != 0 {
+        if let Some(error_msg) = error::get_last_error() {
+            error::throw_exception(&mut env, &error_msg);
+        }
+        return result;
+    }
+
+    *callback_guard = None;
+    result
+}
+
+pub(crate) fn is_config_server_client_connected_jni(_env: JNIEnv, _class: JClass) -> jboolean {
+    if is_config_server_client_connected() != 0 {
+        JNI_TRUE
+    } else {
+        JNI_FALSE
+    }
+}
@@ -0,0 +1,673 @@
+use std::{
+    ffi::{CStr, c_char},
+    ptr,
+};
+
+use easytier_ffi::{
+    data_plane_async_op_cancel, data_plane_async_op_free, data_plane_async_op_status,
+    data_plane_async_op_wait, data_plane_free_bytes, data_plane_tcp_accept_finish,
+    data_plane_tcp_accept_start, data_plane_tcp_bind_finish, data_plane_tcp_bind_start,
+    data_plane_tcp_close, data_plane_tcp_connect_finish, data_plane_tcp_connect_start,
+    data_plane_tcp_listener_close, data_plane_tcp_read_finish, data_plane_tcp_read_start,
+    data_plane_tcp_write_finish, data_plane_tcp_write_start, data_plane_udp_bind_finish,
+    data_plane_udp_bind_start, data_plane_udp_close, data_plane_udp_recv_from_finish,
+    data_plane_udp_recv_from_start, data_plane_udp_send_to_finish, data_plane_udp_send_to_start,
+    free_string,
+};
+use jni::{
+    JNIEnv,
+    objects::{JByteArray, JClass, JObject, JString, JValue},
+    sys::{jint, jlong, jobject},
+};
+
+use crate::{
+    error::{get_last_error, throw_exception},
+    strings::jstring_to_cstring,
+};
+
+const SOCKET_ADDR_CLASS: &str = "com/easytier/jni/DataPlaneSocketAddress";
+const TCP_CONNECT_RESULT_CLASS: &str = "com/easytier/jni/DataPlaneTcpConnectResult";
+const TCP_BIND_RESULT_CLASS: &str = "com/easytier/jni/DataPlaneTcpBindResult";
+const TCP_ACCEPT_RESULT_CLASS: &str = "com/easytier/jni/DataPlaneTcpAcceptResult";
+const TCP_READ_RESULT_CLASS: &str = "com/easytier/jni/DataPlaneTcpReadResult";
+const UDP_BIND_RESULT_CLASS: &str = "com/easytier/jni/DataPlaneUdpBindResult";
+const UDP_RECV_RESULT_CLASS: &str = "com/easytier/jni/DataPlaneUdpRecvResult";
+
+fn timeout_from_jlong(timeout_ms: jlong) -> u64 {
+    timeout_ms.max(0) as u64
+}
+
+fn port_from_jint(env: &mut JNIEnv, value: jint, name: &str) -> Option<u16> {
+    match u16::try_from(value) {
+        Ok(port) => Some(port),
+        Err(_) => {
+            throw_exception(env, &format!("Invalid {}: {}", name, value));
+            None
+        }
+    }
+}
+
+fn len_from_jint(env: &mut JNIEnv, value: jint, name: &str) -> Option<u32> {
+    match u32::try_from(value) {
+        Ok(len) => Some(len),
+        Err(_) => {
+            throw_exception(env, &format!("Invalid {}: {}", name, value));
+            None
+        }
+    }
+}
+
+fn throw_last(env: &mut JNIEnv) {
+    let message = get_last_error().unwrap_or_else(|| "EasyTier data-plane call failed".to_string());
+    throw_exception(env, &message);
+}
+
+unsafe fn take_ffi_string(ptr: *const c_char) -> String {
+    if ptr.is_null() {
+        return String::new();
+    }
+    let value = unsafe { CStr::from_ptr(ptr) }
+        .to_string_lossy()
+        .into_owned();
+    free_string(ptr);
+    value
+}
+
+fn new_socket_addr<'local>(
+    env: &mut JNIEnv<'local>,
+    ip: String,
+    port: u16,
+) -> Option<JObject<'local>> {
+    let class = match env.find_class(SOCKET_ADDR_CLASS) {
+        Ok(class) => class,
+        Err(err) => {
+            throw_exception(
+                env,
+                &format!("Failed to find socket address class: {:?}", err),
+            );
+            return None;
+        }
+    };
+    let ip = match env.new_string(ip) {
+        Ok(ip) => ip,
+        Err(err) => {
+            throw_exception(env, &format!("Failed to create IP string: {:?}", err));
+            return None;
+        }
+    };
+    match env.new_object(
+        class,
+        "(Ljava/lang/String;I)V",
+        &[JValue::Object(&ip), JValue::Int(port as jint)],
+    ) {
+        Ok(addr) => Some(addr),
+        Err(err) => {
+            throw_exception(env, &format!("Failed to create socket address: {:?}", err));
+            None
+        }
+    }
+}
+
+fn new_handle_addr_result(
+    env: &mut JNIEnv,
+    class_name: &str,
+    handle: u64,
+    ip: String,
+    port: u16,
+) -> jobject {
+    let Some(addr) = new_socket_addr(env, ip, port) else {
+        return ptr::null_mut();
+    };
+    let class = match env.find_class(class_name) {
+        Ok(class) => class,
+        Err(err) => {
+            throw_exception(env, &format!("Failed to find result class: {:?}", err));
+            return ptr::null_mut();
+        }
+    };
+    let sig = format!("(JL{};)V", SOCKET_ADDR_CLASS);
+    match env.new_object(
+        class,
+        sig.as_str(),
+        &[JValue::Long(handle as jlong), JValue::Object(&addr)],
+    ) {
+        Ok(result) => result.into_raw(),
+        Err(err) => {
+            throw_exception(env, &format!("Failed to create result object: {:?}", err));
+            ptr::null_mut()
+        }
+    }
+}
+
+fn close_tcp_stream_on_null(result: jobject, handle: u64) -> jobject {
+    if result.is_null() {
+        let _ = data_plane_tcp_close(handle);
+    }
+    result
+}
+
+fn close_tcp_listener_on_null(result: jobject, handle: u64) -> jobject {
+    if result.is_null() {
+        let _ = data_plane_tcp_listener_close(handle);
+    }
+    result
+}
+
+fn close_udp_socket_on_null(result: jobject, handle: u64) -> jobject {
+    if result.is_null() {
+        let _ = data_plane_udp_close(handle);
+    }
+    result
+}
+
+fn read_owned_bytes(ptr: *const u8, len: u32) -> Vec<u8> {
+    if ptr.is_null() || len == 0 {
+        return Vec::new();
+    }
+    let bytes = unsafe { std::slice::from_raw_parts(ptr, len as usize) }.to_vec();
+    data_plane_free_bytes(ptr, len);
+    bytes
+}
+
+pub(crate) fn async_op_status_jni(_env: JNIEnv, _class: JClass, handle: jlong) -> jint {
+    data_plane_async_op_status(handle as u64)
+}
+
+pub(crate) fn async_op_wait_jni(
+    _env: JNIEnv,
+    _class: JClass,
+    handle: jlong,
+    timeout_ms: jlong,
+) -> jint {
+    data_plane_async_op_wait(handle as u64, timeout_ms.max(0) as u64)
+}
+
+pub(crate) fn async_op_cancel_jni(_env: JNIEnv, _class: JClass, handle: jlong) -> jint {
+    data_plane_async_op_cancel(handle as u64)
+}
+
+pub(crate) fn async_op_free_jni(_env: JNIEnv, _class: JClass, handle: jlong) -> jint {
+    data_plane_async_op_free(handle as u64)
+}
+
+pub(crate) fn tcp_connect_start_jni(
+    mut env: JNIEnv,
+    _class: JClass,
+    inst_name: JString,
+    dst_ip: JString,
+    dst_port: jint,
+    timeout_ms: jlong,
+) -> jlong {
+    let inst_name = match jstring_to_cstring(&mut env, &inst_name) {
+        Ok(value) => value,
+        Err(err) => {
+            throw_exception(&mut env, &format!("Invalid instance name: {}", err));
+            return 0;
+        }
+    };
+    let dst_ip = match jstring_to_cstring(&mut env, &dst_ip) {
+        Ok(value) => value,
+        Err(err) => {
+            throw_exception(&mut env, &format!("Invalid destination IP: {}", err));
+            return 0;
+        }
+    };
+    let Some(dst_port) = port_from_jint(&mut env, dst_port, "destination port") else {
+        return 0;
+    };
+    let op = unsafe {
+        data_plane_tcp_connect_start(
+            inst_name.as_ptr(),
+            dst_ip.as_ptr(),
+            dst_port,
+            timeout_ms.max(0) as u64,
+        )
+    };
+    if op == 0 {
+        throw_last(&mut env);
+    }
+    op as jlong
+}
+
+pub(crate) fn tcp_connect_finish_jni(mut env: JNIEnv, _class: JClass, op: jlong) -> jobject {
+    let mut ip: *const c_char = ptr::null();
+    let mut port = 0u16;
+    let handle = unsafe { data_plane_tcp_connect_finish(op as u64, &mut ip, &mut port) };
+    if handle == 0 {
+        throw_last(&mut env);
+        return ptr::null_mut();
+    }
+    close_tcp_stream_on_null(
+        new_handle_addr_result(
+            &mut env,
+            TCP_CONNECT_RESULT_CLASS,
+            handle,
+            unsafe { take_ffi_string(ip) },
+            port,
+        ),
+        handle,
+    )
+}
+
+pub(crate) fn tcp_bind_start_jni(
+    mut env: JNIEnv,
+    _class: JClass,
+    inst_name: JString,
+    local_port: jint,
+    timeout_ms: jlong,
+) -> jlong {
+    let inst_name = match jstring_to_cstring(&mut env, &inst_name) {
+        Ok(value) => value,
+        Err(err) => {
+            throw_exception(&mut env, &format!("Invalid instance name: {}", err));
+            return 0;
+        }
+    };
+    let Some(local_port) = port_from_jint(&mut env, local_port, "local port") else {
+        return 0;
+    };
+    let op = unsafe {
+        data_plane_tcp_bind_start(
+            inst_name.as_ptr(),
+            local_port,
+            timeout_from_jlong(timeout_ms),
+        )
+    };
+    if op == 0 {
+        throw_last(&mut env);
+    }
+    op as jlong
+}
+
+pub(crate) fn tcp_bind_finish_jni(mut env: JNIEnv, _class: JClass, op: jlong) -> jobject {
+    let mut ip: *const c_char = ptr::null();
+    let mut port = 0u16;
+    let handle = unsafe { data_plane_tcp_bind_finish(op as u64, &mut ip, &mut port) };
+    if handle == 0 {
+        throw_last(&mut env);
+        return ptr::null_mut();
+    }
+    close_tcp_listener_on_null(
+        new_handle_addr_result(
+            &mut env,
+            TCP_BIND_RESULT_CLASS,
+            handle,
+            unsafe { take_ffi_string(ip) },
+            port,
+        ),
+        handle,
+    )
+}
+
+pub(crate) fn tcp_accept_start_jni(
+    mut env: JNIEnv,
+    _class: JClass,
+    handle: jlong,
+    timeout_ms: jlong,
+) -> jlong {
+    let op = unsafe { data_plane_tcp_accept_start(handle as u64, timeout_from_jlong(timeout_ms)) };
+    if op == 0 {
+        throw_last(&mut env);
+    }
+    op as jlong
+}
+
+pub(crate) fn tcp_accept_finish_jni(mut env: JNIEnv, _class: JClass, op: jlong) -> jobject {
+    let mut local_ip: *const c_char = ptr::null();
+    let mut local_port = 0u16;
+    let mut peer_ip: *const c_char = ptr::null();
+    let mut peer_port = 0u16;
+    let handle = unsafe {
+        data_plane_tcp_accept_finish(
+            op as u64,
+            &mut local_ip,
+            &mut local_port,
+            &mut peer_ip,
+            &mut peer_port,
+        )
+    };
+    if handle == 0 {
+        throw_last(&mut env);
+        return ptr::null_mut();
+    }
+    let Some(local_addr) =
+        new_socket_addr(&mut env, unsafe { take_ffi_string(local_ip) }, local_port)
+    else {
+        free_string(peer_ip);
+        let _ = data_plane_tcp_close(handle);
+        return ptr::null_mut();
+    };
+    let Some(peer_addr) = new_socket_addr(&mut env, unsafe { take_ffi_string(peer_ip) }, peer_port)
+    else {
+        let _ = data_plane_tcp_close(handle);
+        return ptr::null_mut();
+    };
+    let class = match env.find_class(TCP_ACCEPT_RESULT_CLASS) {
+        Ok(class) => class,
+        Err(err) => {
+            throw_exception(
+                &mut env,
+                &format!("Failed to find accept result class: {:?}", err),
+            );
+            let _ = data_plane_tcp_close(handle);
+            return ptr::null_mut();
+        }
+    };
+    let sig = format!("(JL{};L{};)V", SOCKET_ADDR_CLASS, SOCKET_ADDR_CLASS);
+    let result = match env.new_object(
+        class,
+        sig.as_str(),
+        &[
+            JValue::Long(handle as jlong),
+            JValue::Object(&local_addr),
+            JValue::Object(&peer_addr),
+        ],
+    ) {
+        Ok(result) => result.into_raw(),
+        Err(err) => {
+            throw_exception(
+                &mut env,
+                &format!("Failed to create accept result: {:?}", err),
+            );
+            ptr::null_mut()
+        }
+    };
+    close_tcp_stream_on_null(result, handle)
+}
+
+pub(crate) fn tcp_read_start_jni(
+    mut env: JNIEnv,
+    _class: JClass,
+    handle: jlong,
+    max_len: jint,
+    timeout_ms: jlong,
+) -> jlong {
+    let Some(max_len) = len_from_jint(&mut env, max_len, "max length") else {
+        return 0;
+    };
+    let op = unsafe {
+        data_plane_tcp_read_start(handle as u64, max_len, timeout_from_jlong(timeout_ms))
+    };
+    if op == 0 {
+        throw_last(&mut env);
+    }
+    op as jlong
+}
+
+pub(crate) fn tcp_read_finish_jni(mut env: JNIEnv, _class: JClass, op: jlong) -> jobject {
+    let mut ptr: *const u8 = ptr::null();
+    let mut len = 0u32;
+    let ret = unsafe { data_plane_tcp_read_finish(op as u64, &mut ptr, &mut len) };
+    if ret < 0 {
+        throw_last(&mut env);
+        return ptr::null_mut();
+    }
+    let bytes = read_owned_bytes(ptr, len);
+    let array = match env.byte_array_from_slice(&bytes) {
+        Ok(array) => array,
+        Err(err) => {
+            throw_exception(&mut env, &format!("Failed to create byte array: {:?}", err));
+            return ptr::null_mut();
+        }
+    };
+    let class = match env.find_class(TCP_READ_RESULT_CLASS) {
+        Ok(class) => class,
+        Err(err) => {
+            throw_exception(
+                &mut env,
+                &format!("Failed to find read result class: {:?}", err),
+            );
+            return ptr::null_mut();
+        }
+    };
+    match env.new_object(class, "([B)V", &[JValue::Object(&array)]) {
+        Ok(result) => result.into_raw(),
+        Err(err) => {
+            throw_exception(
+                &mut env,
+                &format!("Failed to create read result: {:?}", err),
+            );
+            ptr::null_mut()
+        }
+    }
+}
+
+pub(crate) fn tcp_write_start_jni(
+    mut env: JNIEnv,
+    _class: JClass,
+    handle: jlong,
+    data: JByteArray,
+    timeout_ms: jlong,
+) -> jlong {
+    let data = match env.convert_byte_array(&data) {
+        Ok(data) => data,
+        Err(err) => {
+            throw_exception(&mut env, &format!("Invalid write buffer: {:?}", err));
+            return 0;
+        }
+    };
+    let ptr = if data.is_empty() {
+        ptr::null()
+    } else {
+        data.as_ptr()
+    };
+    let op = unsafe {
+        data_plane_tcp_write_start(
+            handle as u64,
+            ptr,
+            data.len() as u32,
+            timeout_from_jlong(timeout_ms),
+        )
+    };
+    if op == 0 {
+        throw_last(&mut env);
+    }
+    op as jlong
+}
+
+pub(crate) fn tcp_write_finish_jni(mut env: JNIEnv, _class: JClass, op: jlong) -> jint {
+    let ret = data_plane_tcp_write_finish(op as u64);
+    if ret < 0 {
+        throw_last(&mut env);
+    }
+    ret
+}
+
+pub(crate) fn udp_bind_start_jni(
+    mut env: JNIEnv,
+    _class: JClass,
+    inst_name: JString,
+    local_port: jint,
+    timeout_ms: jlong,
+) -> jlong {
+    let inst_name = match jstring_to_cstring(&mut env, &inst_name) {
+        Ok(value) => value,
+        Err(err) => {
+            throw_exception(&mut env, &format!("Invalid instance name: {}", err));
+            return 0;
+        }
+    };
+    let Some(local_port) = port_from_jint(&mut env, local_port, "local port") else {
+        return 0;
+    };
+    let op = unsafe {
+        data_plane_udp_bind_start(
+            inst_name.as_ptr(),
+            local_port,
+            timeout_from_jlong(timeout_ms),
+        )
+    };
+    if op == 0 {
+        throw_last(&mut env);
+    }
+    op as jlong
+}
+
+pub(crate) fn udp_bind_finish_jni(mut env: JNIEnv, _class: JClass, op: jlong) -> jobject {
+    let mut ip: *const c_char = ptr::null();
+    let mut port = 0u16;
+    let handle = unsafe { data_plane_udp_bind_finish(op as u64, &mut ip, &mut port) };
+    if handle == 0 {
+        throw_last(&mut env);
+        return ptr::null_mut();
+    }
+    close_udp_socket_on_null(
+        new_handle_addr_result(
+            &mut env,
+            UDP_BIND_RESULT_CLASS,
+            handle,
+            unsafe { take_ffi_string(ip) },
+            port,
+        ),
+        handle,
+    )
+}
+
+pub(crate) fn udp_send_to_start_jni(
+    mut env: JNIEnv,
+    _class: JClass,
+    handle: jlong,
+    dst_ip: JString,
+    dst_port: jint,
+    data: JByteArray,
+    timeout_ms: jlong,
+) -> jlong {
+    let dst_ip = match jstring_to_cstring(&mut env, &dst_ip) {
+        Ok(value) => value,
+        Err(err) => {
+            throw_exception(&mut env, &format!("Invalid destination IP: {}", err));
+            return 0;
+        }
+    };
+    let Some(dst_port) = port_from_jint(&mut env, dst_port, "destination port") else {
+        return 0;
+    };
+    let data = match env.convert_byte_array(&data) {
+        Ok(data) => data,
+        Err(err) => {
+            throw_exception(&mut env, &format!("Invalid UDP send buffer: {:?}", err));
+            return 0;
+        }
+    };
+    let ptr = if data.is_empty() {
+        ptr::null()
+    } else {
+        data.as_ptr()
+    };
+    let op = unsafe {
+        data_plane_udp_send_to_start(
+            handle as u64,
+            dst_ip.as_ptr(),
+            dst_port,
+            ptr,
+            data.len() as u32,
+            timeout_from_jlong(timeout_ms),
+        )
+    };
+    if op == 0 {
+        throw_last(&mut env);
+    }
+    op as jlong
+}
+
+pub(crate) fn udp_send_to_finish_jni(mut env: JNIEnv, _class: JClass, op: jlong) -> jint {
+    let ret = data_plane_udp_send_to_finish(op as u64);
+    if ret < 0 {
+        throw_last(&mut env);
+    }
+    ret
+}
+
+pub(crate) fn udp_recv_from_start_jni(
+    mut env: JNIEnv,
+    _class: JClass,
+    handle: jlong,
+    max_len: jint,
+    timeout_ms: jlong,
+) -> jlong {
+    let Some(max_len) = len_from_jint(&mut env, max_len, "max length") else {
+        return 0;
+    };
+    let op = unsafe {
+        data_plane_udp_recv_from_start(handle as u64, max_len, timeout_from_jlong(timeout_ms))
+    };
+    if op == 0 {
+        throw_last(&mut env);
+    }
+    op as jlong
+}
+
+pub(crate) fn udp_recv_from_finish_jni(mut env: JNIEnv, _class: JClass, op: jlong) -> jobject {
+    let mut ptr: *const u8 = ptr::null();
+    let mut len = 0u32;
+    let mut ip: *const c_char = ptr::null();
+    let mut port = 0u16;
+    let ret = unsafe {
+        data_plane_udp_recv_from_finish(op as u64, &mut ptr, &mut len, &mut ip, &mut port)
+    };
+    if ret < 0 {
+        throw_last(&mut env);
+        return ptr::null_mut();
+    }
+    let bytes = read_owned_bytes(ptr, len);
+    let array = match env.byte_array_from_slice(&bytes) {
+        Ok(array) => array,
+        Err(err) => {
+            free_string(ip);
+            throw_exception(&mut env, &format!("Failed to create byte array: {:?}", err));
+            return ptr::null_mut();
+        }
+    };
+    let Some(peer_addr) = new_socket_addr(&mut env, unsafe { take_ffi_string(ip) }, port) else {
+        return ptr::null_mut();
+    };
+    let class = match env.find_class(UDP_RECV_RESULT_CLASS) {
+        Ok(class) => class,
+        Err(err) => {
+            throw_exception(
+                &mut env,
+                &format!("Failed to find UDP recv result class: {:?}", err),
+            );
+            return ptr::null_mut();
+        }
+    };
+    let sig = format!("([BL{};)V", SOCKET_ADDR_CLASS);
+    match env.new_object(
+        class,
+        sig.as_str(),
+        &[JValue::Object(&array), JValue::Object(&peer_addr)],
+    ) {
+        Ok(result) => result.into_raw(),
+        Err(err) => {
+            throw_exception(
+                &mut env,
+                &format!("Failed to create UDP recv result: {:?}", err),
+            );
+            ptr::null_mut()
+        }
+    }
+}
+
+pub(crate) fn tcp_close_jni(mut env: JNIEnv, _class: JClass, handle: jlong) -> jint {
+    let ret = data_plane_tcp_close(handle as u64);
+    if ret != 0 {
+        throw_last(&mut env);
+    }
+    ret
+}
+
+pub(crate) fn tcp_listener_close_jni(mut env: JNIEnv, _class: JClass, handle: jlong) -> jint {
+    let ret = data_plane_tcp_listener_close(handle as u64);
+    if ret != 0 {
+        throw_last(&mut env);
+    }
+    ret
+}
+
+pub(crate) fn udp_close_jni(mut env: JNIEnv, _class: JClass, handle: jlong) -> jint {
+    let ret = data_plane_udp_close(handle as u64);
+    if ret != 0 {
+        throw_last(&mut env);
+    }
+    ret
+}
@@ -0,0 +1,74 @@
+use std::{
+    ffi::{CStr, c_char},
+    ptr,
+    sync::Mutex,
+};
+
+use easytier_ffi::{free_string, get_error_msg};
+use jni::JNIEnv;
+use jni::objects::JClass;
+use jni::sys::jstring;
+use once_cell::sync::Lazy;
+
+static JNI_CALLBACK_ERROR: Lazy<Mutex<Option<String>>> = Lazy::new(|| Mutex::new(None));
+
+pub(crate) fn set_callback_error(error: String) {
+    log::error!("{}", error);
+    if let Ok(mut guard) = JNI_CALLBACK_ERROR.lock() {
+        *guard = Some(error);
+    }
+}
+
+pub(crate) fn clear_callback_error() {
+    if let Ok(mut guard) = JNI_CALLBACK_ERROR.lock() {
+        *guard = None;
+    }
+}
+
+fn take_callback_error() -> Option<String> {
+    JNI_CALLBACK_ERROR
+        .lock()
+        .ok()
+        .and_then(|mut guard| guard.take())
+}
+
+fn get_ffi_last_error() -> Option<String> {
+    unsafe {
+        let mut error_ptr: *const c_char = ptr::null();
+        get_error_msg(&mut error_ptr);
+        if error_ptr.is_null() {
+            None
+        } else {
+            let error_cstr = CStr::from_ptr(error_ptr);
+            let error_str = error_cstr.to_string_lossy().into_owned();
+            free_string(error_ptr);
+            Some(error_str)
+        }
+    }
+}
+
+pub(crate) fn get_last_error() -> Option<String> {
+    match (get_ffi_last_error(), take_callback_error()) {
+        (Some(ffi_error), Some(callback_error)) => Some(format!(
+            "{}; config server callback error: {}",
+            ffi_error, callback_error
+        )),
+        (Some(ffi_error), None) => Some(ffi_error),
+        (None, Some(callback_error)) => Some(callback_error),
+        (None, None) => None,
+    }
+}
+
+pub(crate) fn throw_exception(env: &mut JNIEnv, message: &str) {
+    let _ = env.throw_new("java/lang/RuntimeException", message);
+}
+
+pub(crate) fn get_last_error_jni(env: JNIEnv, _class: JClass) -> jstring {
+    match get_last_error() {
+        Some(error) => match env.new_string(&error) {
+            Ok(jstr) => jstr.into_raw(),
+            Err(_) => ptr::null_mut(),
+        },
+        None => ptr::null_mut(),
+    }
+}
@@ -0,0 +1,91 @@
+use std::{
+    ffi::{CStr, c_char},
+    ptr,
+};
+
+use easytier_ffi::{call_json_rpc, free_string};
+use jni::JNIEnv;
+use jni::objects::{JClass, JString};
+use jni::sys::jstring;
+
+use crate::{
+    error::{get_last_error, throw_exception},
+    strings::{jstring_to_cstring, optional_jstring_to_cstring},
+};
+
+pub(crate) fn call_json_rpc_jni(
+    mut env: JNIEnv,
+    _class: JClass,
+    service_name: JString,
+    method_name: JString,
+    domain_name: JString,
+    payload_json: JString,
+) -> jstring {
+    let service_name_cstr = match jstring_to_cstring(&mut env, &service_name) {
+        Ok(cstr) => cstr,
+        Err(e) => {
+            throw_exception(&mut env, &format!("Invalid service name: {}", e));
+            return ptr::null_mut();
+        }
+    };
+    let method_name_cstr = match jstring_to_cstring(&mut env, &method_name) {
+        Ok(cstr) => cstr,
+        Err(e) => {
+            throw_exception(&mut env, &format!("Invalid method name: {}", e));
+            return ptr::null_mut();
+        }
+    };
+    let domain_name_cstr = match optional_jstring_to_cstring(&mut env, &domain_name) {
+        Ok(cstr) => cstr,
+        Err(e) => {
+            throw_exception(&mut env, &format!("Invalid domain name: {}", e));
+            return ptr::null_mut();
+        }
+    };
+    let payload_json_cstr = match jstring_to_cstring(&mut env, &payload_json) {
+        Ok(cstr) => cstr,
+        Err(e) => {
+            throw_exception(&mut env, &format!("Invalid payload JSON: {}", e));
+            return ptr::null_mut();
+        }
+    };
+
+    let domain_name_ptr = domain_name_cstr
+        .as_ref()
+        .map_or(ptr::null(), |cstr| cstr.as_ptr());
+    let mut response_ptr: *const c_char = ptr::null();
+    let result = unsafe {
+        call_json_rpc(
+            service_name_cstr.as_ptr(),
+            method_name_cstr.as_ptr(),
+            domain_name_ptr,
+            payload_json_cstr.as_ptr(),
+            &mut response_ptr,
+        )
+    };
+
+    if result != 0 {
+        if let Some(error) = get_last_error() {
+            throw_exception(&mut env, &error);
+        }
+        return ptr::null_mut();
+    }
+
+    if response_ptr.is_null() {
+        throw_exception(&mut env, "JSON RPC returned a null response");
+        return ptr::null_mut();
+    }
+
+    let response = unsafe { CStr::from_ptr(response_ptr) }
+        .to_string_lossy()
+        .into_owned();
+    free_string(response_ptr);
+
+    match env.new_string(&response) {
+        Ok(jstr) => jstr.into_raw(),
+        Err(_) => {
+            throw_exception(&mut env, "Failed to create JSON RPC response string");
+            ptr::null_mut()
+        }
+    }
+}
@@ -0,0 +1,777 @@
+//! JNI facade for Android callers of EasyTier.
+//!
+//! This file intentionally lists every Java-visible native method exported by
+//! `libeasytier_android_jni.so`. The implementation details live in sibling
+//! modules so this facade stays readable as an API map.
+//!
+//! Network management APIs:
+//! - `setTunFd(instanceName, fd)`: attach an Android TUN fd to an instance.
+//! - `parseConfig(config)`: validate TOML config text.
+//! - `runNetworkInstance(config)`: start a local network instance.
+//! - `retainNetworkInstance(instanceNames)`: retain named instances and stop the rest.
+//! - `listInstances()`: return running instance names and IDs as JSON.
+//! - `collectNetworkInfos()`: return running instance info as a JSON string.
+//! - `callJsonRpc(...)`: call an exposed EasyTier RPC service with JSON payload.
+//!
+//! Config server client APIs:
+//! - `startConfigServerClient(url, hostname, machineId, secureMode, callback)`:
+//!   start the managed remote config client.
+//! - `stopConfigServerClient()`: stop the managed client and release its Java callback.
+//! - `isConfigServerClientConnected()`: return whether the managed client is connected.
+//!
+//! Error API:
+//! - `getLastError()`: return the latest FFI/JNI error string for the calling thread.
+//!
+//! Data-plane APIs:
+//! - `EasyTierDataPlaneJNI.*`: low-level async op-handle data-plane JNI.
+//! - `EasyTierJNI.dataPlane*`: compatibility exports for older callers.
+
+mod callback;
+mod config_server_api;
+mod data_plane_api;
+mod error;
+mod json_rpc_api;
+mod logger;
+mod network_api;
+mod strings;
+
+use jni::JNIEnv;
+use jni::objects::{JByteArray, JClass, JObject, JObjectArray, JString};
+use jni::sys::{jboolean, jint, jlong, jobject, jstring};
+
+/// Attach a TUN file descriptor to an EasyTier network instance.
+///
+/// Java signature:
+/// `EasyTierJNI.setTunFd(instanceName: String, fd: Int): Int`
+///
+/// `instanceName` must name an instance known to the shared FFI instance cache.
+/// The `fd` must be a valid Android TUN file descriptor. On failure this
+/// returns `-1` and throws `RuntimeException` with the FFI error message when
+/// one is available.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_setTunFd(
+    env: JNIEnv,
+    class: JClass,
+    inst_name: JString,
+    fd: jint,
+) -> jint {
+    logger::init();
+    network_api::set_tun_fd_jni(env, class, inst_name, fd)
+}
+
+/// Validate a TOML network config string.
+///
+/// Java signature:
+/// `EasyTierJNI.parseConfig(config: String): Int`
+///
+/// This only validates the config text; it does not start or mutate any
+/// instance. On failure this returns `-1` and throws `RuntimeException`.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_parseConfig(
+    env: JNIEnv,
+    class: JClass,
+    config: JString,
+) -> jint {
+    logger::init();
+    network_api::parse_config_jni(env, class, config)
+}
+
+/// Start one local EasyTier network instance from TOML config text.
+///
+/// Java signature:
+/// `EasyTierJNI.runNetworkInstance(config: String): Int`
+///
+/// The instance name in the config must be unique in the FFI instance cache.
+/// On failure this returns `-1` and throws `RuntimeException`.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_runNetworkInstance(
+    env: JNIEnv,
+    class: JClass,
+    config: JString,
+) -> jint {
+    logger::init();
+    network_api::run_network_instance_jni(env, class, config)
+}
+
+/// Retain the named network instances and stop all other instances.
+///
+/// Java signature:
+/// `EasyTierJNI.retainNetworkInstance(instanceNames: Array<String>?): Int`
+///
+/// Passing `null` or an empty array stops all instances. Null elements inside a
+/// non-empty array are invalid. On failure this returns `-1` and throws
+/// `RuntimeException`.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_retainNetworkInstance(
+    env: JNIEnv,
+    class: JClass,
+    instance_names: JObjectArray,
+) -> jint {
+    logger::init();
+    network_api::retain_network_instance_jni(env, class, instance_names)
+}
+
+/// Collect running network instance information.
+///
+/// Java signature:
+/// `EasyTierJNI.collectNetworkInfos(maxLength: Int): String?`
+///
+/// Returns a JSON string containing `NetworkInstanceRunningInfoMap`, or null if
+/// collection fails. `maxLength` limits how many FFI entries are collected. On
+/// failure this throws `RuntimeException` when an error message is available.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_collectNetworkInfos(
+    env: JNIEnv,
+    class: JClass,
+    max_length: jint,
+) -> jstring {
+    logger::init();
+    network_api::collect_network_infos_jni(env, class, max_length)
+}
+
+/// List running network instance names and IDs.
+///
+/// Java signature:
+/// `EasyTierJNI.listInstances(maxLength: Int): String?`
+///
+/// Returns a JSON object whose keys are instance names and whose values are
+/// instance ID strings. On failure this returns null and throws
+/// `RuntimeException`.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_listInstances(
+    env: JNIEnv,
+    class: JClass,
+    max_length: jint,
+) -> jstring {
+    logger::init();
+    network_api::list_instances_jni(env, class, max_length)
+}
+
+/// Call an exposed EasyTier RPC method using protobuf JSON.
+///
+/// Java signature:
+/// `EasyTierJNI.callJsonRpc(serviceName, methodName, domainName, payloadJson): String?`
+///
+/// Instance lifecycle management RPCs are intentionally not exposed here. Use
+/// the dedicated EasyTierJNI instance APIs for start/retain/delete/collect.
+/// `payloadJson` must include any `instance` selector required by the target
+/// RPC. On failure this returns null and throws `RuntimeException`.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_callJsonRpc(
+    env: JNIEnv,
+    class: JClass,
+    service_name: JString,
+    method_name: JString,
+    domain_name: JString,
+    payload_json: JString,
+) -> jstring {
+    logger::init();
+    json_rpc_api::call_json_rpc_jni(
+        env,
+        class,
+        service_name,
+        method_name,
+        domain_name,
+        payload_json,
+    )
+}
+
+/// Return the latest FFI/JNI error string for the calling thread.
+///
+/// Java signature:
+/// `EasyTierJNI.getLastError(): String?`
+///
+/// This combines the FFI thread-local error with any pending config-server Java
+/// callback error. It returns null when no error is available.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_getLastError(
+    env: JNIEnv,
+    class: JClass,
+) -> jstring {
+    error::get_last_error_jni(env, class)
+}
+
+/// Start the managed config-server client.
+///
+/// Java signature:
+/// `EasyTierJNI.startConfigServerClient(url, hostname, machineId, secureMode, callback): Int`
+///
+/// JNI only converts Java values and keeps the Java callback alive. The FFI
+/// layer owns singleton lifecycle, config-server/data-plane mutual exclusion,
+/// remote instance tracking, and callback event timing. If `callback` is
+/// non-null, each remote apply/delete event is delivered to
+/// `ConfigServerEventCallback.onEvent(eventJson)`.
+///
+/// On failure this returns `-1` and throws `RuntimeException`.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_startConfigServerClient(
+    mut env: JNIEnv,
+    _class: JClass,
+    config_server_url: JString,
+    hostname: JString,
+    machine_id: JString,
+    secure_mode: jboolean,
+    callback: JObject,
+) -> jint {
+    logger::init();
+    config_server_api::start_config_server_client_jni(
+        &mut env,
+        config_server_url,
+        hostname,
+        machine_id,
+        secure_mode,
+        callback,
+    )
+}
+
+/// Stop the managed config-server client.
+///
+/// Java signature:
+/// `EasyTierJNI.stopConfigServerClient(): Int`
+///
+/// The FFI layer performs the actual stop and managed instance cleanup. JNI
+/// releases the Java callback reference after FFI stop succeeds. On failure
+/// this returns `-1` and throws `RuntimeException`.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_stopConfigServerClient(
+    env: JNIEnv,
+    class: JClass,
+) -> jint {
+    logger::init();
+    config_server_api::stop_config_server_client_jni(env, class)
+}
+
+/// Report whether the managed config-server client is connected.
+///
+/// Java signature:
+/// `EasyTierJNI.isConfigServerClientConnected(): Boolean`
+///
+/// Returns `JNI_TRUE` only when the FFI config-server client exists and reports
+/// connected.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_isConfigServerClientConnected(
+    env: JNIEnv,
+    class: JClass,
+) -> jboolean {
+    logger::init();
+    config_server_api::is_config_server_client_connected_jni(env, class)
+}
+
+macro_rules! export_data_plane_jni {
+    (
+        $op_status:ident,
+        $op_wait:ident,
+        $op_cancel:ident,
+        $op_free:ident,
+        $tcp_connect_start:ident,
+        $tcp_connect_finish:ident,
+        $tcp_bind_start:ident,
+        $tcp_bind_finish:ident,
+        $tcp_accept_start:ident,
+        $tcp_accept_finish:ident,
+        $tcp_read_start:ident,
+        $tcp_read_finish:ident,
+        $tcp_write_start:ident,
+        $tcp_write_finish:ident,
+        $udp_bind_start:ident,
+        $udp_bind_finish:ident,
+        $udp_send_to_start:ident,
+        $udp_send_to_finish:ident,
+        $udp_recv_from_start:ident,
+        $udp_recv_from_finish:ident,
+        $tcp_close:ident,
+        $tcp_listener_close:ident,
+        $udp_close:ident
+    ) => {
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $op_status(env: JNIEnv, class: JClass, handle: jlong) -> jint {
+            logger::init();
+            data_plane_api::async_op_status_jni(env, class, handle)
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $op_wait(
+            env: JNIEnv,
+            class: JClass,
+            handle: jlong,
+            timeout_ms: jlong,
+        ) -> jint {
+            logger::init();
+            data_plane_api::async_op_wait_jni(env, class, handle, timeout_ms)
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $op_cancel(env: JNIEnv, class: JClass, handle: jlong) -> jint {
+            logger::init();
+            data_plane_api::async_op_cancel_jni(env, class, handle)
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $op_free(env: JNIEnv, class: JClass, handle: jlong) -> jint {
+            logger::init();
+            data_plane_api::async_op_free_jni(env, class, handle)
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $tcp_connect_start(
+            env: JNIEnv,
+            class: JClass,
+            inst_name: JString,
+            dst_ip: JString,
+            dst_port: jint,
+            timeout_ms: jlong,
+        ) -> jlong {
+            logger::init();
+            data_plane_api::tcp_connect_start_jni(
+                env, class, inst_name, dst_ip, dst_port, timeout_ms,
+            )
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $tcp_connect_finish(
+            env: JNIEnv,
+            class: JClass,
+            op: jlong,
+        ) -> jobject {
+            logger::init();
+            data_plane_api::tcp_connect_finish_jni(env, class, op)
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $tcp_bind_start(
+            env: JNIEnv,
+            class: JClass,
+            inst_name: JString,
+            local_port: jint,
+            timeout_ms: jlong,
+        ) -> jlong {
+            logger::init();
+            data_plane_api::tcp_bind_start_jni(env, class, inst_name, local_port, timeout_ms)
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $tcp_bind_finish(env: JNIEnv, class: JClass, op: jlong) -> jobject {
+            logger::init();
+            data_plane_api::tcp_bind_finish_jni(env, class, op)
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $tcp_accept_start(
+            env: JNIEnv,
+            class: JClass,
+            handle: jlong,
+            timeout_ms: jlong,
+        ) -> jlong {
+            logger::init();
+            data_plane_api::tcp_accept_start_jni(env, class, handle, timeout_ms)
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $tcp_accept_finish(
+            env: JNIEnv,
+            class: JClass,
+            op: jlong,
+        ) -> jobject {
+            logger::init();
+            data_plane_api::tcp_accept_finish_jni(env, class, op)
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $tcp_read_start(
+            env: JNIEnv,
+            class: JClass,
+            handle: jlong,
+            max_len: jint,
+            timeout_ms: jlong,
+        ) -> jlong {
+            logger::init();
+            data_plane_api::tcp_read_start_jni(env, class, handle, max_len, timeout_ms)
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $tcp_read_finish(env: JNIEnv, class: JClass, op: jlong) -> jobject {
+            logger::init();
+            data_plane_api::tcp_read_finish_jni(env, class, op)
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $tcp_write_start(
+            env: JNIEnv,
+            class: JClass,
+            handle: jlong,
+            data: JByteArray,
+            timeout_ms: jlong,
+        ) -> jlong {
+            logger::init();
+            data_plane_api::tcp_write_start_jni(env, class, handle, data, timeout_ms)
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $tcp_write_finish(env: JNIEnv, class: JClass, op: jlong) -> jint {
+            logger::init();
+            data_plane_api::tcp_write_finish_jni(env, class, op)
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $udp_bind_start(
+            env: JNIEnv,
+            class: JClass,
+            inst_name: JString,
+            local_port: jint,
+            timeout_ms: jlong,
+        ) -> jlong {
+            logger::init();
+            data_plane_api::udp_bind_start_jni(env, class, inst_name, local_port, timeout_ms)
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $udp_bind_finish(env: JNIEnv, class: JClass, op: jlong) -> jobject {
+            logger::init();
+            data_plane_api::udp_bind_finish_jni(env, class, op)
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $udp_send_to_start(
+            env: JNIEnv,
+            class: JClass,
+            handle: jlong,
+            dst_ip: JString,
+            dst_port: jint,
+            data: JByteArray,
+            timeout_ms: jlong,
+        ) -> jlong {
+            logger::init();
+            data_plane_api::udp_send_to_start_jni(
+                env, class, handle, dst_ip, dst_port, data, timeout_ms,
+            )
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $udp_send_to_finish(env: JNIEnv, class: JClass, op: jlong) -> jint {
+            logger::init();
+            data_plane_api::udp_send_to_finish_jni(env, class, op)
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $udp_recv_from_start(
+            env: JNIEnv,
+            class: JClass,
+            handle: jlong,
+            max_len: jint,
+            timeout_ms: jlong,
+        ) -> jlong {
+            logger::init();
+            data_plane_api::udp_recv_from_start_jni(env, class, handle, max_len, timeout_ms)
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $udp_recv_from_finish(
+            env: JNIEnv,
+            class: JClass,
+            op: jlong,
+        ) -> jobject {
+            logger::init();
+            data_plane_api::udp_recv_from_finish_jni(env, class, op)
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $tcp_close(env: JNIEnv, class: JClass, handle: jlong) -> jint {
+            logger::init();
+            data_plane_api::tcp_close_jni(env, class, handle)
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $tcp_listener_close(
+            env: JNIEnv,
+            class: JClass,
+            handle: jlong,
+        ) -> jint {
+            logger::init();
+            data_plane_api::tcp_listener_close_jni(env, class, handle)
+        }
+
+        #[unsafe(no_mangle)]
+        pub extern "system" fn $udp_close(env: JNIEnv, class: JClass, handle: jlong) -> jint {
+            logger::init();
+            data_plane_api::udp_close_jni(env, class, handle)
+        }
+    };
+}
+
+export_data_plane_jni!(
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneAsyncOpStatus,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneAsyncOpWait,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneAsyncOpCancel,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneAsyncOpFree,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneTcpConnectStart,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneTcpConnectFinish,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneTcpBindStart,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneTcpBindFinish,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneTcpAcceptStart,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneTcpAcceptFinish,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneTcpReadStart,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneTcpReadFinish,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneTcpWriteStart,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneTcpWriteFinish,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneUdpBindStart,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneUdpBindFinish,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneUdpSendToStart,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneUdpSendToFinish,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneUdpRecvFromStart,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneUdpRecvFromFinish,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneTcpClose,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneTcpListenerClose,
+    Java_com_easytier_jni_EasyTierDataPlaneJNI_dataPlaneUdpClose
+);
+
+// Compatibility exports for older Kotlin/Java callers that used EasyTierJNI
+// directly for data-plane operations.
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneAsyncOpStatus(
+    env: JNIEnv,
+    class: JClass,
+    handle: jlong,
+) -> jint {
+    logger::init();
+    data_plane_api::async_op_status_jni(env, class, handle)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneAsyncOpWait(
+    env: JNIEnv,
+    class: JClass,
+    handle: jlong,
+    timeout_ms: jlong,
+) -> jint {
+    logger::init();
+    data_plane_api::async_op_wait_jni(env, class, handle, timeout_ms)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneAsyncOpCancel(
+    env: JNIEnv,
+    class: JClass,
+    handle: jlong,
+) -> jint {
+    logger::init();
+    data_plane_api::async_op_cancel_jni(env, class, handle)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneAsyncOpFree(
+    env: JNIEnv,
+    class: JClass,
+    handle: jlong,
+) -> jint {
+    logger::init();
+    data_plane_api::async_op_free_jni(env, class, handle)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneTcpConnectStart(
+    env: JNIEnv,
+    class: JClass,
+    inst_name: JString,
+    dst_ip: JString,
+    dst_port: jint,
+    timeout_ms: jlong,
+) -> jlong {
+    logger::init();
+    data_plane_api::tcp_connect_start_jni(env, class, inst_name, dst_ip, dst_port, timeout_ms)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneTcpConnectFinish(
+    env: JNIEnv,
+    class: JClass,
+    op: jlong,
+) -> jobject {
+    logger::init();
+    data_plane_api::tcp_connect_finish_jni(env, class, op)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneTcpBindStart(
+    env: JNIEnv,
+    class: JClass,
+    inst_name: JString,
+    local_port: jint,
+    timeout_ms: jlong,
+) -> jlong {
+    logger::init();
+    data_plane_api::tcp_bind_start_jni(env, class, inst_name, local_port, timeout_ms)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneTcpBindFinish(
+    env: JNIEnv,
+    class: JClass,
+    op: jlong,
+) -> jobject {
+    logger::init();
+    data_plane_api::tcp_bind_finish_jni(env, class, op)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneTcpAcceptStart(
+    env: JNIEnv,
+    class: JClass,
+    handle: jlong,
+    timeout_ms: jlong,
+) -> jlong {
+    logger::init();
+    data_plane_api::tcp_accept_start_jni(env, class, handle, timeout_ms)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneTcpAcceptFinish(
+    env: JNIEnv,
+    class: JClass,
+    op: jlong,
+) -> jobject {
+    logger::init();
+    data_plane_api::tcp_accept_finish_jni(env, class, op)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneTcpReadStart(
+    env: JNIEnv,
+    class: JClass,
+    handle: jlong,
+    max_len: jint,
+    timeout_ms: jlong,
+) -> jlong {
+    logger::init();
+    data_plane_api::tcp_read_start_jni(env, class, handle, max_len, timeout_ms)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneTcpReadFinish(
+    env: JNIEnv,
+    class: JClass,
+    op: jlong,
+) -> jobject {
+    logger::init();
+    data_plane_api::tcp_read_finish_jni(env, class, op)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneTcpWriteStart(
+    env: JNIEnv,
+    class: JClass,
+    handle: jlong,
+    data: JByteArray,
+    timeout_ms: jlong,
+) -> jlong {
+    logger::init();
+    data_plane_api::tcp_write_start_jni(env, class, handle, data, timeout_ms)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneTcpWriteFinish(
+    env: JNIEnv,
+    class: JClass,
+    op: jlong,
+) -> jint {
+    logger::init();
+    data_plane_api::tcp_write_finish_jni(env, class, op)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneUdpBindStart(
+    env: JNIEnv,
+    class: JClass,
+    inst_name: JString,
+    local_port: jint,
+    timeout_ms: jlong,
+) -> jlong {
+    logger::init();
+    data_plane_api::udp_bind_start_jni(env, class, inst_name, local_port, timeout_ms)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneUdpBindFinish(
+    env: JNIEnv,
+    class: JClass,
+    op: jlong,
+) -> jobject {
+    logger::init();
+    data_plane_api::udp_bind_finish_jni(env, class, op)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneUdpSendToStart(
+    env: JNIEnv,
+    class: JClass,
+    handle: jlong,
+    dst_ip: JString,
+    dst_port: jint,
+    data: JByteArray,
+    timeout_ms: jlong,
+) -> jlong {
+    logger::init();
+    data_plane_api::udp_send_to_start_jni(env, class, handle, dst_ip, dst_port, data, timeout_ms)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneUdpSendToFinish(
+    env: JNIEnv,
+    class: JClass,
+    op: jlong,
+) -> jint {
+    logger::init();
+    data_plane_api::udp_send_to_finish_jni(env, class, op)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneUdpRecvFromStart(
+    env: JNIEnv,
+    class: JClass,
+    handle: jlong,
+    max_len: jint,
+    timeout_ms: jlong,
+) -> jlong {
+    logger::init();
+    data_plane_api::udp_recv_from_start_jni(env, class, handle, max_len, timeout_ms)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneUdpRecvFromFinish(
+    env: JNIEnv,
+    class: JClass,
+    op: jlong,
+) -> jobject {
+    logger::init();
+    data_plane_api::udp_recv_from_finish_jni(env, class, op)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneTcpClose(
+    env: JNIEnv,
+    class: JClass,
+    handle: jlong,
+) -> jint {
+    logger::init();
+    data_plane_api::tcp_close_jni(env, class, handle)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneTcpListenerClose(
+    env: JNIEnv,
+    class: JClass,
+    handle: jlong,
+) -> jint {
+    logger::init();
+    data_plane_api::tcp_listener_close_jni(env, class, handle)
+}
+
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_dataPlaneUdpClose(
+    env: JNIEnv,
+    class: JClass,
+    handle: jlong,
+) -> jint {
+    logger::init();
+    data_plane_api::udp_close_jni(env, class, handle)
+}
@@ -0,0 +1,13 @@
+use once_cell::sync::Lazy;
+
+static LOGGER_INIT: Lazy<()> = Lazy::new(|| {
+    android_logger::init_once(
+        android_logger::Config::default()
+            .with_max_level(log::LevelFilter::Debug)
+            .with_tag("EasyTier-JNI"),
+    );
+});
+
+pub(crate) fn init() {
+    Lazy::force(&LOGGER_INIT);
+}
@@ -0,0 +1,261 @@
+use std::{ffi::CStr, ptr};
+
+use easytier::proto::api::manage::{NetworkInstanceRunningInfo, NetworkInstanceRunningInfoMap};
+use easytier_ffi::{
+    KeyValuePair, collect_network_infos, free_string, list_instance, parse_config,
+    retain_network_instance, run_network_instance, set_tun_fd,
+};
+use jni::JNIEnv;
+use jni::objects::{JClass, JObjectArray, JString};
+use jni::sys::{jint, jstring};
+
+use crate::{
+    error::{get_last_error, throw_exception},
+    strings::jstring_to_cstring,
+};
+
+pub(crate) fn set_tun_fd_jni(
+    mut env: JNIEnv,
+    _class: JClass,
+    inst_name: JString,
+    fd: jint,
+) -> jint {
+    let inst_name_cstr = match jstring_to_cstring(&mut env, &inst_name) {
+        Ok(cstr) => cstr,
+        Err(e) => {
+            throw_exception(&mut env, &format!("Invalid instance name: {}", e));
+            return -1;
+        }
+    };
+    unsafe {
+        let result = set_tun_fd(inst_name_cstr.as_ptr(), fd);
+        if result != 0
+            && let Some(error) = get_last_error()
+        {
+            throw_exception(&mut env, &error);
+        }
+        result
+    }
+}
+
+pub(crate) fn parse_config_jni(mut env: JNIEnv, _class: JClass, config: JString) -> jint {
+    let config_cstr = match jstring_to_cstring(&mut env, &config) {
+        Ok(cstr) => cstr,
+        Err(e) => {
+            throw_exception(&mut env, &format!("Invalid config string: {}", e));
+            return -1;
+        }
+    };
+    unsafe {
+        let result = parse_config(config_cstr.as_ptr());
+        if result != 0
+            && let Some(error) = get_last_error()
+        {
+            throw_exception(&mut env, &error);
+        }
+        result
+    }
+}
+
+pub(crate) fn run_network_instance_jni(mut env: JNIEnv, _class: JClass, config: JString) -> jint {
+    let config_cstr = match jstring_to_cstring(&mut env, &config) {
+        Ok(cstr) => cstr,
+        Err(e) => {
+            throw_exception(&mut env, &format!("Invalid config string: {}", e));
+            return -1;
+        }
+    };
+    unsafe {
+        let result = run_network_instance(config_cstr.as_ptr());
+        if result != 0
+            && let Some(error) = get_last_error()
+        {
+            throw_exception(&mut env, &error);
+        }
+        result
+    }
+}
+
+pub(crate) fn retain_network_instance_jni(
+    mut env: JNIEnv,
+    _class: JClass,
+    instance_names: JObjectArray,
+) -> jint {
+    if instance_names.is_null() {
+        return retain_all(&mut env);
+    }
+
+    let array_length = match env.get_array_length(&instance_names) {
+        Ok(len) => len as usize,
+        Err(e) => {
+            throw_exception(&mut env, &format!("Failed to get array length: {:?}", e));
+            return -1;
+        }
+    };
+
+    if array_length == 0 {
+        return retain_all(&mut env);
+    }
+
+    let mut c_strings = Vec::with_capacity(array_length);
+    let mut c_string_ptrs = Vec::with_capacity(array_length);
+
+    for i in 0..array_length {
+        let java_string = match env.get_object_array_element(&instance_names, i as i32) {
+            Ok(obj) => obj,
+            Err(e) => {
+                throw_exception(
+                    &mut env,
+                    &format!("Failed to get array element {}: {:?}", i, e),
+                );
+                return -1;
+            }
+        };
+
+        if java_string.is_null() {
+            throw_exception(
+                &mut env,
+                &format!("Invalid instance name at index {}: null", i),
+            );
+            return -1;
+        }
+
+        let jstring = JString::from(java_string);
+        let c_string = match jstring_to_cstring(&mut env, &jstring) {
+            Ok(cstr) => cstr,
+            Err(e) => {
+                throw_exception(
+                    &mut env,
+                    &format!("Invalid instance name at index {}: {}", i, e),
+                );
+                return -1;
+            }
+        };
+
+        c_string_ptrs.push(c_string.as_ptr());
+        c_strings.push(c_string);
+    }
+
+    unsafe {
+        let result = retain_network_instance(c_string_ptrs.as_ptr(), c_string_ptrs.len());
+        if result != 0
+            && let Some(error) = get_last_error()
+        {
+            throw_exception(&mut env, &error);
+        }
+        result
+    }
+}
+
+fn retain_all(env: &mut JNIEnv) -> jint {
+    unsafe {
+        let result = retain_network_instance(ptr::null(), 0);
+        if result != 0
+            && let Some(error) = get_last_error()
+        {
+            throw_exception(env, &error);
+        }
+        result
+    }
+}
+
+pub(crate) fn collect_network_infos_jni(
+    mut env: JNIEnv,
+    _class: JClass,
+    max_length: jint,
+) -> jstring {
+    let max_length = max_length.max(0) as usize;
+    let mut infos = vec![
+        KeyValuePair {
+            key: ptr::null(),
+            value: ptr::null(),
+        };
+        max_length
+    ];
+
+    unsafe {
+        let count = collect_network_infos(infos.as_mut_ptr(), max_length);
+        if count < 0 {
+            if let Some(error) = get_last_error() {
+                throw_exception(&mut env, &error);
+            }
+            return ptr::null_mut();
+        }
+
+        let mut ret = NetworkInstanceRunningInfoMap::default();
+        for info in infos.iter().take(count as usize) {
+            let key_ptr = info.key;
+            let val_ptr = info.value;
+            if key_ptr.is_null() || val_ptr.is_null() {
+                break;
+            }
+
+            let key = CStr::from_ptr(key_ptr).to_string_lossy().into_owned();
+            let val = CStr::from_ptr(val_ptr).to_string_lossy().into_owned();
+            free_string(key_ptr);
+            free_string(val_ptr);
+            let value = match serde_json::from_str::<NetworkInstanceRunningInfo>(&val) {
+                Ok(v) => v,
+                Err(_) => {
+                    throw_exception(&mut env, "Failed to parse JSON");
+                    continue;
+                }
+            };
+            ret.map.insert(key, value);
+        }
+
+        let json_str = serde_json::to_string(&ret).unwrap_or_else(|_| "{}".to_string());
+        match env.new_string(&json_str) {
+            Ok(jstr) => jstr.into_raw(),
+            Err(_) => {
+                throw_exception(&mut env, "Failed to create JSON string");
+                ptr::null_mut()
+            }
+        }
+    }
+}
+
+pub(crate) fn list_instances_jni(mut env: JNIEnv, _class: JClass, max_length: jint) -> jstring {
+    let max_length = max_length.max(0) as usize;
+    let mut infos = vec![
+        KeyValuePair {
+            key: ptr::null(),
+            value: ptr::null(),
+        };
+        max_length
+    ];
+
+    unsafe {
+        let count = list_instance(infos.as_mut_ptr(), max_length);
+        if count < 0 {
+            if let Some(error) = get_last_error() {
+                throw_exception(&mut env, &error);
+            }
+            return ptr::null_mut();
+        }
+
+        let mut ret = serde_json::Map::new();
+        for info in infos.iter().take(count as usize) {
+            let key_ptr = info.key;
+            let val_ptr = info.value;
+            if key_ptr.is_null() || val_ptr.is_null() {
+                break;
+            }
+
+            let key = CStr::from_ptr(key_ptr).to_string_lossy().into_owned();
+            let val = CStr::from_ptr(val_ptr).to_string_lossy().into_owned();
+            free_string(key_ptr);
+            free_string(val_ptr);
+            ret.insert(key, serde_json::Value::String(val));
+        }
+
+        let json_str = serde_json::Value::Object(ret).to_string();
+        match env.new_string(&json_str) {
+            Ok(jstr) => jstr.into_raw(),
+            Err(_) => {
+                throw_exception(&mut env, "Failed to create instance list JSON string");
+                ptr::null_mut()
+            }
+        }
+    }
+}
@@ -0,0 +1,23 @@
+use std::ffi::CString;
+
+use jni::JNIEnv;
+use jni::objects::JString;
+
+pub(crate) fn jstring_to_cstring(env: &mut JNIEnv, jstr: &JString) -> Result<CString, String> {
+    let java_str = env
+        .get_string(jstr)
+        .map_err(|e| format!("Failed to get string: {:?}", e))?;
+    let rust_str = java_str.to_str().map_err(|_| "Invalid UTF-8".to_string())?;
+    CString::new(rust_str).map_err(|_| "String contains null byte".to_string())
+}
+
+pub(crate) fn optional_jstring_to_cstring(
+    env: &mut JNIEnv,
+    jstr: &JString,
+) -> Result<Option<CString>, String> {
+    if jstr.is_null() {
+        return Ok(None);
+    }
+
+    jstring_to_cstring(env, jstr).map(Some)
+}
@@ -0,0 +1,28 @@
+[package]
+name = "easytier-ffi"
+version = "0.1.0"
+edition.workspace = true
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[features]
+default = ["c-abi", "ffi-dataplane"]
+c-abi = []
+ffi-dataplane = ["easytier/ffi-dataplane"]
+
+[dependencies]
+easytier = { path = "../../easytier" }
+
+once_cell = "1.18.0"
+dashmap = "6.0"
+tokio = { version = "1", features = ["rt-multi-thread", "io-util", "time", "sync", "macros"] }
+async-trait = "0.1"
+log = "0.4"
+percent-encoding = "2.3"
+url = "2"
+
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1"
+uuid = "1.17.0"
+tokio-util = "0.7"
@@ -0,0 +1,159 @@
+public class EasyTierFFI
+{
+    // 导入 DLL 函数
+    private const string DllName = "easytier_ffi.dll";
+
+    [DllImport(DllName, CallingConvention = CallingConvention.Cdecl)]
+    private static extern int parse_config([MarshalAs(UnmanagedType.LPStr)] string cfgStr);
+
+    [DllImport(DllName, CallingConvention = CallingConvention.Cdecl)]
+    private static extern int run_network_instance([MarshalAs(UnmanagedType.LPStr)] string cfgStr);
+
+    [DllImport(DllName, CallingConvention = CallingConvention.Cdecl)]
+    private static extern int retain_network_instance(IntPtr instNames, int length);
+
+    [DllImport(DllName, CallingConvention = CallingConvention.Cdecl)]
+    private static extern int collect_network_infos(IntPtr infos, int maxLength);
+
+    [DllImport(DllName, CallingConvention = CallingConvention.Cdecl)]
+    private static extern void get_error_msg(out IntPtr errorMsg);
+
+    [DllImport(DllName, CallingConvention = CallingConvention.Cdecl)]
+    private static extern void free_string(IntPtr str);
+
+    // 定义 KeyValuePair 结构体
+    [StructLayout(LayoutKind.Sequential)]
+    public struct KeyValuePair
+    {
+        public IntPtr Key;
+        public IntPtr Value;
+    }
+
+    // 解析配置
+    public static void ParseConfig(string config)
+    {
+        if (string.IsNullOrEmpty(config))
+        {
+            throw new ArgumentException("Configuration string cannot be null or empty.");
+        }
+
+        int result = parse_config(config);
+        if (result < 0)
+        {
+            throw new Exception(GetErrorMessage());
+        }
+    }
+
+    // 启动网络实例
+    public static void RunNetworkInstance(string config)
+    {
+        if (string.IsNullOrEmpty(config))
+        {
+            throw new ArgumentException("Configuration string cannot be null or empty.");
+        }
+
+        int result = run_network_instance(config);
+        if (result < 0)
+        {
+            throw new Exception(GetErrorMessage());
+        }
+    }
+
+    // 保留网络实例
+    public static void RetainNetworkInstances(string[] instanceNames)
+    {
+        IntPtr[] namePointers = null;
+        IntPtr namesPtr = IntPtr.Zero;
+
+        try
+        {
+            if (instanceNames != null && instanceNames.Length > 0)
+            {
+                namePointers = new IntPtr[instanceNames.Length];
+                for (int i = 0; i < instanceNames.Length; i++)
+                {
+                    if (string.IsNullOrEmpty(instanceNames[i]))
+                    {
+                        throw new ArgumentException("Instance name cannot be null or empty.");
+                    }
+                    namePointers[i] = Marshal.StringToHGlobalAnsi(instanceNames[i]);
+                }
+
+                namesPtr = Marshal.AllocHGlobal(Marshal.SizeOf<IntPtr>() * namePointers.Length);
+                Marshal.Copy(namePointers, 0, namesPtr, namePointers.Length);
+            }
+
+            int result = retain_network_instance(namesPtr, instanceNames?.Length ?? 0);
+            if (result < 0)
+            {
+                throw new Exception(GetErrorMessage());
+            }
+        }
+        finally
+        {
+            if (namePointers != null)
+            {
+                foreach (var ptr in namePointers)
+                {
+                    if (ptr != IntPtr.Zero)
+                    {
+                        Marshal.FreeHGlobal(ptr);
+                    }
+                }
+            }
+
+            if (namesPtr != IntPtr.Zero)
+            {
+                Marshal.FreeHGlobal(namesPtr);
+            }
+        }
+    }
+
+    // 收集网络信息
+    public static KeyValuePair<string, string>[] CollectNetworkInfos(int maxLength)
+    {
+        IntPtr buffer = Marshal.AllocHGlobal(Marshal.SizeOf<KeyValuePair>() * maxLength);
+        try
+        {
+            int count = collect_network_infos(buffer, maxLength);
+            if (count < 0)
+            {
+                throw new Exception(GetErrorMessage());
+            }
+
+            var result = new KeyValuePair<string, string>[count];
+            for (int i = 0; i < count; i++)
+            {
+                var kv = Marshal.PtrToStructure<KeyValuePair>(buffer + i * Marshal.SizeOf<KeyValuePair>());
+                string key = Marshal.PtrToStringAnsi(kv.Key);
+                string value = Marshal.PtrToStringAnsi(kv.Value);
+
+                // 释放由 FFI 分配的字符串内存
+                free_string(kv.Key);
+                free_string(kv.Value);
+
+                result[i] = new KeyValuePair<string, string>(key, value);
+            }
+
+            return result;
+        }
+        finally
+        {
+            Marshal.FreeHGlobal(buffer);
+        }
+    }
+
+    // 获取错误信息
+    private static string GetErrorMessage()
+    {
+        get_error_msg(out IntPtr errorMsgPtr);
+        if (errorMsgPtr == IntPtr.Zero)
+        {
+            return "Unknown error";
+        }
+
+        string errorMsg = Marshal.PtrToStringAnsi(errorMsgPtr);
+        free_string(errorMsgPtr); // 释放错误信息字符串
+        return errorMsg;
+    }
+}
@@ -0,0 +1,429 @@
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define DATA_PLANE_OP_PENDING 0
+#define DATA_PLANE_OP_READY 1
+#define DATA_PLANE_OP_FAILED -1
+#define DATA_PLANE_OP_INVALID -2
+
+extern int run_network_instance(const char *cfg_str);
+extern void get_error_msg(const char **out);
+extern void free_string(const char *s);
+
+extern int data_plane_async_op_status(uint64_t op);
+extern int data_plane_async_op_wait(uint64_t op, uint64_t timeout_ms);
+extern int data_plane_async_op_cancel(uint64_t op);
+extern int data_plane_async_op_free(uint64_t op);
+extern void data_plane_free_bytes(const uint8_t *ptr, uint32_t len);
+
+extern uint64_t data_plane_tcp_connect_start(
+    const char *inst_name,
+    const char *dst_ip,
+    uint16_t dst_port,
+    uint64_t timeout_ms);
+extern uint64_t data_plane_tcp_connect_finish(
+    uint64_t op,
+    const char **out_local_ip,
+    uint16_t *out_local_port);
+extern uint64_t data_plane_tcp_bind_start(
+    const char *inst_name,
+    uint16_t local_port,
+    uint64_t timeout_ms);
+extern uint64_t data_plane_tcp_bind_finish(
+    uint64_t op,
+    const char **out_local_ip,
+    uint16_t *out_local_port);
+extern uint64_t data_plane_tcp_accept_start(uint64_t listener, uint64_t timeout_ms);
+extern uint64_t data_plane_tcp_accept_finish(
+    uint64_t op,
+    const char **out_local_ip,
+    uint16_t *out_local_port,
+    const char **out_peer_ip,
+    uint16_t *out_peer_port);
+extern uint64_t data_plane_tcp_read_start(
+    uint64_t stream,
+    uint32_t max_len,
+    uint64_t timeout_ms);
+extern int data_plane_tcp_read_finish(
+    uint64_t op,
+    const uint8_t **out_buf,
+    uint32_t *out_len);
+extern uint64_t data_plane_tcp_write_start(
+    uint64_t stream,
+    const uint8_t *buf,
+    uint32_t len,
+    uint64_t timeout_ms);
+extern int data_plane_tcp_write_finish(uint64_t op);
+extern int data_plane_tcp_close(uint64_t stream);
+extern int data_plane_tcp_listener_close(uint64_t listener);
+
+extern uint64_t data_plane_udp_bind_start(
+    const char *inst_name,
+    uint16_t local_port,
+    uint64_t timeout_ms);
+extern uint64_t data_plane_udp_bind_finish(
+    uint64_t op,
+    const char **out_local_ip,
+    uint16_t *out_local_port);
+extern uint64_t data_plane_udp_send_to_start(
+    uint64_t socket,
+    const char *dst_ip,
+    uint16_t dst_port,
+    const uint8_t *buf,
+    uint32_t len,
+    uint64_t timeout_ms);
+extern int data_plane_udp_send_to_finish(uint64_t op);
+extern uint64_t data_plane_udp_recv_from_start(
+    uint64_t socket,
+    uint32_t max_len,
+    uint64_t timeout_ms);
+extern int data_plane_udp_recv_from_finish(
+    uint64_t op,
+    const uint8_t **out_buf,
+    uint32_t *out_len,
+    const char **out_ip,
+    uint16_t *out_port);
+extern int data_plane_udp_close(uint64_t socket);
+
+static void print_last_error(const char *prefix) {
+    const char *err = NULL;
+    get_error_msg(&err);
+    if (err) {
+        fprintf(stderr, "%s: %s\n", prefix, err);
+        free_string(err);
+    } else {
+        fprintf(stderr, "%s\n", prefix);
+    }
+}
+
+static int parse_ip_port(const char *value, char *ip, size_t ip_len, uint16_t *port) {
+    const char *colon = strrchr(value, ':');
+    if (!colon || colon == value || !colon[1]) {
+        fprintf(stderr, "expected IPv4 target in IP:PORT form, got %s\n", value);
+        return -1;
+    }
+    size_t host_len = (size_t)(colon - value);
+    if (host_len >= ip_len) {
+        fprintf(stderr, "IP address is too long: %s\n", value);
+        return -1;
+    }
+    char *end = NULL;
+    long parsed_port = strtol(colon + 1, &end, 10);
+    if (!end || *end != '\0' || parsed_port < 0 || parsed_port > 65535) {
+        fprintf(stderr, "invalid port in %s\n", value);
+        return -1;
+    }
+    memcpy(ip, value, host_len);
+    ip[host_len] = '\0';
+    *port = (uint16_t)parsed_port;
+    return 0;
+}
+
+static int wait_op(uint64_t op, uint64_t timeout_ms) {
+    uint64_t waited = 0;
+    while (waited < timeout_ms) {
+        int status = data_plane_async_op_wait(op, 50);
+        if (status != DATA_PLANE_OP_PENDING) {
+            return status;
+        }
+        waited += 50;
+    }
+    return data_plane_async_op_status(op);
+}
+
+static int wait_or_cancel(uint64_t op, uint64_t timeout_ms, const char *what) {
+    int status = wait_op(op, timeout_ms);
+    if (status == DATA_PLANE_OP_READY || status == DATA_PLANE_OP_FAILED) {
+        return status;
+    }
+    if (status == DATA_PLANE_OP_PENDING) {
+        fprintf(stderr, "%s did not finish within %llu ms\n", what, (unsigned long long)timeout_ms);
+        data_plane_async_op_cancel(op);
+        data_plane_async_op_free(op);
+        return DATA_PLANE_OP_INVALID;
+    }
+    fprintf(stderr, "%s returned invalid op status %d\n", what, status);
+    return status;
+}
+
+static int async_tcp_read_once(uint64_t stream, uint64_t timeout_ms) {
+    uint64_t op = data_plane_tcp_read_start(stream, 512, timeout_ms);
+    if (!op) {
+        print_last_error("tcp read start failed");
+        return -1;
+    }
+    if (wait_or_cancel(op, timeout_ms + 1000, "tcp read") == DATA_PLANE_OP_INVALID) {
+        return -1;
+    }
+
+    const uint8_t *buf = NULL;
+    uint32_t len = 0;
+    int ret = data_plane_tcp_read_finish(op, &buf, &len);
+    if (ret < 0) {
+        print_last_error("tcp read finish failed");
+        return -1;
+    }
+    printf("tcp read %d bytes: %.*s\n", ret, ret, buf ? (const char *)buf : "");
+    data_plane_free_bytes(buf, len);
+    return 0;
+}
+
+static int async_tcp_write_all(uint64_t stream, const char *data, uint64_t timeout_ms) {
+    uint64_t op = data_plane_tcp_write_start(
+        stream,
+        (const uint8_t *)data,
+        (uint32_t)strlen(data),
+        timeout_ms);
+    if (!op) {
+        print_last_error("tcp write start failed");
+        return -1;
+    }
+    if (wait_or_cancel(op, timeout_ms + 1000, "tcp write") == DATA_PLANE_OP_INVALID) {
+        return -1;
+    }
+    int ret = data_plane_tcp_write_finish(op);
+    if (ret < 0) {
+        print_last_error("tcp write finish failed");
+        return -1;
+    }
+    printf("tcp wrote %d bytes\n", ret);
+    return 0;
+}
+
+static int run_tcp_connect_demo(const char *inst, const char *target) {
+    char ip[128];
+    uint16_t port = 0;
+    if (parse_ip_port(target, ip, sizeof(ip), &port) != 0) {
+        return -1;
+    }
+
+    uint64_t op = data_plane_tcp_connect_start(inst, ip, port, 30000);
+    if (!op) {
+        print_last_error("tcp connect start failed");
+        return -1;
+    }
+    if (wait_or_cancel(op, 31000, "tcp connect") == DATA_PLANE_OP_INVALID) {
+        return -1;
+    }
+
+    const char *local_ip = NULL;
+    uint16_t local_port = 0;
+    uint64_t stream = data_plane_tcp_connect_finish(op, &local_ip, &local_port);
+    if (!stream) {
+        print_last_error("tcp connect finish failed");
+        return -1;
+    }
+    printf("tcp connected from %s:%u to %s:%u, handle=%llu\n",
+           local_ip,
+           local_port,
+           ip,
+           port,
+           (unsigned long long)stream);
+    free_string(local_ip);
+
+    int ret = async_tcp_read_once(stream, 10000);
+    data_plane_tcp_close(stream);
+    return ret;
+}
+
+static int run_tcp_listen_demo(const char *inst, const char *port_text) {
+    uint16_t port = (uint16_t)strtoul(port_text, NULL, 10);
+    uint64_t op = data_plane_tcp_bind_start(inst, port, 30000);
+    if (!op) {
+        print_last_error("tcp bind start failed");
+        return -1;
+    }
+    if (wait_or_cancel(op, 31000, "tcp bind") == DATA_PLANE_OP_INVALID) {
+        return -1;
+    }
+
+    const char *local_ip = NULL;
+    uint16_t local_port = 0;
+    uint64_t listener = data_plane_tcp_bind_finish(op, &local_ip, &local_port);
+    if (!listener) {
+        print_last_error("tcp bind finish failed");
+        return -1;
+    }
+    printf("tcp listening on %s:%u, handle=%llu\n",
+           local_ip,
+           local_port,
+           (unsigned long long)listener);
+    free_string(local_ip);
+
+    op = data_plane_tcp_accept_start(listener, 60000);
+    if (!op) {
+        print_last_error("tcp accept start failed");
+        data_plane_tcp_listener_close(listener);
+        return -1;
+    }
+    if (wait_or_cancel(op, 61000, "tcp accept") == DATA_PLANE_OP_INVALID) {
+        data_plane_tcp_listener_close(listener);
+        return -1;
+    }
+
+    const char *peer_ip = NULL;
+    uint16_t peer_port = 0;
+    local_ip = NULL;
+    local_port = 0;
+    uint64_t stream = data_plane_tcp_accept_finish(
+        op,
+        &local_ip,
+        &local_port,
+        &peer_ip,
+        &peer_port);
+    data_plane_tcp_listener_close(listener);
+    if (!stream) {
+        print_last_error("tcp accept finish failed");
+        return -1;
+    }
+    printf("tcp accepted %s:%u -> %s:%u, stream=%llu\n",
+           peer_ip,
+           peer_port,
+           local_ip,
+           local_port,
+           (unsigned long long)stream);
+    free_string(local_ip);
+    free_string(peer_ip);
+
+    int ret = async_tcp_read_once(stream, 10000);
+    if (ret == 0) {
+        ret = async_tcp_write_all(stream, "pong", 10000);
+    }
+    data_plane_tcp_close(stream);
+    return ret;
+}
+
+static int run_udp_demo(const char *inst, const char *target) {
+    char ip[128];
+    uint16_t port = 0;
+    if (parse_ip_port(target, ip, sizeof(ip), &port) != 0) {
+        return -1;
+    }
+
+    uint64_t op = data_plane_udp_bind_start(inst, 0, 30000);
+    if (!op) {
+        print_last_error("udp bind start failed");
+        return -1;
+    }
+    if (wait_or_cancel(op, 31000, "udp bind") == DATA_PLANE_OP_INVALID) {
+        return -1;
+    }
+
+    const char *local_ip = NULL;
+    uint16_t local_port = 0;
+    uint64_t socket = data_plane_udp_bind_finish(op, &local_ip, &local_port);
+    if (!socket) {
+        print_last_error("udp bind finish failed");
+        return -1;
+    }
+    printf("udp bound on %s:%u, handle=%llu\n",
+           local_ip,
+           local_port,
+           (unsigned long long)socket);
+    free_string(local_ip);
+
+    const char payload[] = "ping";
+    op = data_plane_udp_send_to_start(
+        socket,
+        ip,
+        port,
+        (const uint8_t *)payload,
+        (uint32_t)strlen(payload),
+        10000);
+    if (!op) {
+        print_last_error("udp send start failed");
+        data_plane_udp_close(socket);
+        return -1;
+    }
+    if (wait_or_cancel(op, 11000, "udp send") == DATA_PLANE_OP_INVALID) {
+        data_plane_udp_close(socket);
+        return -1;
+    }
+    int sent = data_plane_udp_send_to_finish(op);
+    if (sent < 0) {
+        print_last_error("udp send finish failed");
+        data_plane_udp_close(socket);
+        return -1;
+    }
+    printf("udp sent %d bytes to %s:%u\n", sent, ip, port);
+
+    op = data_plane_udp_recv_from_start(socket, 512, 30000);
+    if (!op) {
+        print_last_error("udp recv start failed");
+        data_plane_udp_close(socket);
+        return -1;
+    }
+    if (wait_or_cancel(op, 31000, "udp recv") == DATA_PLANE_OP_INVALID) {
+        data_plane_udp_close(socket);
+        return -1;
+    }
+
+    const uint8_t *buf = NULL;
+    uint32_t len = 0;
+    const char *peer_ip = NULL;
+    uint16_t peer_port = 0;
+    int ret = data_plane_udp_recv_from_finish(op, &buf, &len, &peer_ip, &peer_port);
+    if (ret < 0) {
+        print_last_error("udp recv finish failed");
+        data_plane_udp_close(socket);
+        return -1;
+    }
+    printf("udp received %d bytes from %s:%u: %.*s\n",
+           ret,
+           peer_ip,
+           peer_port,
+           ret,
+           buf ? (const char *)buf : "");
+    data_plane_free_bytes(buf, len);
+    free_string(peer_ip);
+    data_plane_udp_close(socket);
+    return 0;
+}
+
+static void print_usage(void) {
+    printf("Set EASYTIER_FFI_CONFIG and EASYTIER_FFI_INSTANCE to run the async data-plane demo.\n");
+    printf("Optional demos:\n");
+    printf("  EASYTIER_FFI_TARGET=10.0.0.2:22          async TCP connect/read\n");
+    printf("  EASYTIER_FFI_LISTEN_PORT=12345           async TCP bind/accept/read/write\n");
+    printf("  EASYTIER_FFI_UDP_TARGET=10.0.0.2:9000    async UDP bind/send_to/recv_from\n");
+}
+
+int main(void) {
+    const char *config = getenv("EASYTIER_FFI_CONFIG");
+    const char *instance = getenv("EASYTIER_FFI_INSTANCE");
+    if (!config || !instance) {
+        print_usage();
+        return 0;
+    }
+
+    if (run_network_instance(config) != 0) {
+        print_last_error("run_network_instance failed");
+        return 1;
+    }
+    printf("network instance started: %s\n", instance);
+
+    int failed = 0;
+    const char *target = getenv("EASYTIER_FFI_TARGET");
+    if (target) {
+        failed |= run_tcp_connect_demo(instance, target) != 0;
+    }
+
+    const char *listen_port = getenv("EASYTIER_FFI_LISTEN_PORT");
+    if (listen_port) {
+        failed |= run_tcp_listen_demo(instance, listen_port) != 0;
+    }
+
+    const char *udp_target = getenv("EASYTIER_FFI_UDP_TARGET");
+    if (udp_target) {
+        failed |= run_udp_demo(instance, udp_target) != 0;
+    }
+
+    if (!target && !listen_port && !udp_target) {
+        printf("No dataplane demo env var was set; nothing else to run.\n");
+        print_usage();
+    }
+
+    return failed ? 1 : 0;
+}
@@ -0,0 +1,100 @@
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <stdbool.h>
+#include <unistd.h> // for sleep
+
+// FFI struct and function declarations
+typedef struct {
+    const char* key;
+    const char* value;
+} KeyValuePair;
+
+typedef void (*config_server_event_callback)(
+    const char* event_json,
+    void* user_data
+);
+
+extern int parse_config(const char* cfg_str);
+extern int run_network_instance(const char* cfg_str);
+extern void get_error_msg(const char** out);
+extern void free_string(const char* s);
+extern int collect_network_infos(KeyValuePair* infos, size_t max_length);
+extern int start_config_server_client(
+    const char* config_server_url,
+    const char* hostname,
+    const char* machine_id,
+    bool secure_mode,
+    config_server_event_callback callback,
+    void* user_data
+);
+extern int stop_config_server_client(void);
+extern int is_config_server_client_connected(void);
+
+static void on_config_server_event(const char* event_json, void* user_data) {
+    (void)user_data;
+    printf("config server event: %s\n", event_json);
+}
+
+int main() {
+    const char* config = "inst_name = \"test\"\nnetwork = \"test_network\"\n";
+    int ret;
+
+    // 调用 parse_config
+    ret = parse_config(config);
+    if (ret != 0) {
+        const char* err = NULL;
+        get_error_msg(&err);
+        if (err) {
+            printf("parse_config error: %s\n", err);
+            free_string(err);
+        }
+        return 1;
+    }
+    printf("parse_config success\n");
+
+    // 调用 run_network_instance
+    ret = run_network_instance(config);
+    if (ret != 0) {
+        const char* err = NULL;
+        get_error_msg(&err);
+        if (err) {
+            printf("run_network_instance error: %s\n", err);
+            free_string(err);
+        }
+        return 1;
+    }
+    printf("run_network_instance success\n");
+
+    // 周期性调用 collect_network_infos 并打印
+    const size_t max_infos = 8;
+    KeyValuePair* infos = (KeyValuePair*)malloc(sizeof(KeyValuePair) * max_infos);
+    if (!infos) {
+        fprintf(stderr, "malloc failed\n");
+        return 1;
+    }
+
+    for (int i = 0; i < 5; ++i) { // 循环5次作为示例
+        memset(infos, 0, sizeof(KeyValuePair) * max_infos);
+        int count = collect_network_infos(infos, max_infos);
+        if (count < 0) {
+            const char* err = NULL;
+            get_error_msg(&err);
+            if (err) {
+                printf("collect_network_infos error: %s\n", err);
+                free_string(err);
+            }
+            break;
+        }
+        printf("collect_network_infos: %d instance(s)\n", count);
+        for (int j = 0; j < count; ++j) {
+            printf("  [%d] key: %s\n      value: %s\n", j, infos[j].key, infos[j].value);
+            free_string(infos[j].key);
+            free_string(infos[j].value);
+        }
+        sleep(1);
+    }
+    free(infos);
+
+    return 0;
+}
@@ -0,0 +1,138 @@
+# 1. Go FFI Demo
+
+This demo wraps EasyTier FFI data-plane TCP as Go `net.Conn` and `net.Listener`.
+It can connect to an SSH server through EasyTier and read its banner, or accept a
+TCP connection from another EasyTier peer and run a small ping/pong exchange.
+The async op-handle wrapper is in `easytier_async.go`; the original synchronous
+wrapper stays in `easytier.go`.
+
+## 1.1. Build the FFI library
+
+Run from the repository root:
+
+```sh
+cargo build -p easytier-ffi --features ffi-dataplane
+```
+
+The demo loads the debug library by default:
+
+```text
+target/debug/libeasytier_ffi.so
+```
+
+To use another library path, export `EASYTIER_FFI_LIB=/path/to/libeasytier_ffi.so`.
+
+## 1.2. Configure the EasyTier config
+
+`EASYTIER_FFI_CONFIG` is a string of the EasyTier config in TOML format which is passed to the FFI library. For example:
+
+```sh
+export EASYTIER_FFI_CONFIG='instance_name = "default"
+ipv4 = "10.0.0.1"
+
+[network_identity]
+network_name = "testnet"
+network_secret = "mysecret"
+
+[flags]
+no_tun = true # disable tun device to avoid permission issues.
+bind_device = false # allow loopback peers in local examples.
+
+[[peer]]
+uri = "tcp://123.123.123.123:11010"
+'
+```
+
+You should configure with your own real values.
+
+Set the local instance name and a SSH server target to connect through EasyTier:
+
+```sh
+export EASYTIER_FFI_INSTANCE=default
+export EASYTIER_FFI_TARGET=10.0.0.2:22
+```
+
+To run the TCP listen integration test in the same `go test` process as the SSH
+test, use a separate instance name and config:
+
+```sh
+export EASYTIER_FFI_LISTEN_CONFIG='instance_name = "listener"
+ipv4 = "10.0.0.3"
+
+[network_identity]
+network_name = "testnet"
+network_secret = "mysecret"
+
+[flags]
+no_tun = true
+bind_device = false
+
+[[peer]]
+uri = "tcp://123.123.123.123:11010"
+'
+export EASYTIER_FFI_LISTEN_INSTANCE=listener
+export EASYTIER_FFI_LISTEN_PORT=12345
+```
+
+## 1.3. Run the demo
+
+`goffi` is built without cgo on Linux, so run the tests with `CGO_ENABLED=0`:
+
+```sh
+cd easytier-contrib/easytier-ffi/examples/go
+CGO_ENABLED=0 go test -v ./...
+```
+
+The synchronous tests use the environment variables above. The async Go tests
+are self-contained: they start two local EasyTier instances in the same test
+process with `no_tun = true` and `bind_device = false`, then run TCP and UDP
+ping/pong over the async data-plane API.
+
+The synchronous wrapper also exposes `CallJSONRPC(service, method, domain,
+payload)` for non-lifecycle EasyTier RPCs. For example,
+`CallJSONRPC("api.logger.LoggerRpcService", "get_logger_config", "", "{}")`
+returns the logger config as protobuf JSON. Instance lifecycle management RPCs
+are intentionally filtered; use the dedicated FFI APIs for starting and
+stopping instances.
+
+To run only the async tests:
+
+```sh
+cd easytier-contrib/easytier-ffi/examples/go
+CGO_ENABLED=0 go test -run 'TestAsync' -v ./...
+```
+
+When the SSH integration environment variables are set, expected synchronous
+test output includes an SSH banner similar to:
+
+```text
+attempt 1: got banner "SSH-2.0-..."
+PASS
+```
+
+For `TestTCPListenIntegration`, connect from another EasyTier peer to the local
+EasyTier IPv4 address and `EASYTIER_FFI_LISTEN_PORT`, send `ping`, and expect
+`pong` in response.
+
+The async test output should include local TCP bind/connect log lines and finish
+with `PASS` without any extra environment variables.
+
+## 1.4. C async example
+
+The C async example is kept separate from the basic C example:
+
+```sh
+cargo build -p easytier-ffi --features ffi-dataplane
+cc -Wall -Wextra -pedantic \
+  ../example_data_plane_async.c \
+  -L ../../../../target/debug -leasytier_ffi \
+  -Wl,-rpath,../../../../target/debug \
+  -o /tmp/easytier_data_plane_async
+
+/tmp/easytier_data_plane_async
+```
+
+Without environment variables it prints usage and exits successfully. With
+`EASYTIER_FFI_CONFIG`, `EASYTIER_FFI_INSTANCE`, and one of
+`EASYTIER_FFI_TARGET`, `EASYTIER_FFI_LISTEN_PORT`, or `EASYTIER_FFI_UDP_TARGET`,
+it runs the corresponding async data-plane flow.
@@ -0,0 +1,593 @@
+package easytierffi
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"os"
+	"runtime"
+	"strconv"
+	"strings"
+	"sync/atomic"
+	"time"
+	"unsafe"
+
+	"github.com/go-webgpu/goffi/ffi"
+	"github.com/go-webgpu/goffi/types"
+)
+
+const defaultTimeout = 30 * time.Second
+
+type Native struct {
+	lib unsafe.Pointer
+
+	runNetworkInstance symCall
+	callJSONRPC        symCall
+	getErrorMsg        symCall
+	freeString         symCall
+	tcpConnect         symCall
+	tcpBind            symCall
+	tcpAccept          symCall
+	tcpRead            symCall
+	tcpWrite           symCall
+	tcpClose           symCall
+	tcpListenerClose   symCall
+}
+
+type Conn struct {
+	native *Native
+	handle uint64
+	local  net.Addr
+	remote net.Addr
+	closed atomic.Bool
+	rd     atomicDeadline
+	wd     atomicDeadline
+}
+
+type Listener struct {
+	native *Native
+	handle uint64
+	addr   net.Addr
+	closed atomic.Bool
+}
+
+type symCall struct {
+	fn  unsafe.Pointer
+	cif types.CallInterface
+}
+
+type atomicDeadline struct{ v atomic.Int64 }
+
+type timeoutError string
+
+func Open(path string) (*Native, error) {
+	lib, err := ffi.LoadLibrary(path)
+	if err != nil {
+		return nil, err
+	}
+	n := &Native{lib: lib}
+	if err := n.bind(); err != nil {
+		ffi.FreeLibrary(lib)
+		return nil, err
+	}
+	return n, nil
+}
+
+func (n *Native) Close() error {
+	if n.lib == nil {
+		return nil
+	}
+	ffi.FreeLibrary(n.lib)
+	n.lib = nil
+	return nil
+}
+
+func (n *Native) RunNetworkInstance(config string) error {
+	defer pinErrorThread()()
+	cfg := cString(config)
+	cfgPtr := unsafe.Pointer(&cfg[0])
+	var ret int32
+	err := n.runNetworkInstance.call(unsafe.Pointer(&ret), unsafe.Pointer(&cfgPtr))
+	runtime.KeepAlive(cfg)
+	if err != nil {
+		return err
+	}
+	if ret != 0 {
+		return n.lastError()
+	}
+	return nil
+}
+
+func (n *Native) CallJSONRPC(serviceName, methodName, domainName, payloadJSON string) (string, error) {
+	defer pinErrorThread()()
+	service := cString(serviceName)
+	method := cString(methodName)
+	payload := cString(payloadJSON)
+	servicePtr := unsafe.Pointer(&service[0])
+	methodPtr := unsafe.Pointer(&method[0])
+	payloadPtr := unsafe.Pointer(&payload[0])
+	var domain []byte
+	var domainPtr unsafe.Pointer
+	if domainName != "" {
+		domain = cString(domainName)
+		domainPtr = unsafe.Pointer(&domain[0])
+	}
+	var response unsafe.Pointer
+	responseArg := unsafe.Pointer(&response)
+	var ret int32
+	err := n.callJSONRPC.call(
+		unsafe.Pointer(&ret),
+		unsafe.Pointer(&servicePtr),
+		unsafe.Pointer(&methodPtr),
+		unsafe.Pointer(&domainPtr),
+		unsafe.Pointer(&payloadPtr),
+		unsafe.Pointer(&responseArg),
+	)
+	runtime.KeepAlive(service)
+	runtime.KeepAlive(method)
+	runtime.KeepAlive(domain)
+	runtime.KeepAlive(payload)
+	if err != nil {
+		return "", err
+	}
+	if ret != 0 {
+		return "", n.lastError()
+	}
+	if response == nil {
+		return "", errors.New("easytier ffi JSON RPC returned nil response")
+	}
+	defer func() { _ = n.freeCString(response) }()
+	return readCString(response), nil
+}
+
+func (n *Native) DialContext(ctx context.Context, instance, network, address string) (net.Conn, error) {
+	if network != "tcp" && network != "tcp4" && network != "tcp6" {
+		return nil, net.UnknownNetworkError(network)
+	}
+	ip, port, err := parseIPPort(address)
+	if err != nil {
+		return nil, err
+	}
+	timeout := defaultTimeout
+	if deadline, ok := ctx.Deadline(); ok {
+		timeout = time.Until(deadline)
+	}
+	if timeout <= 0 {
+		return nil, context.DeadlineExceeded
+	}
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	handle, local, err := n.tcpConnectTo(instance, ip.String(), uint16(port), timeout)
+	if err != nil {
+		return nil, err
+	}
+	return &Conn{native: n, handle: handle, local: local, remote: &net.TCPAddr{IP: ip, Port: port}}, nil
+}
+
+func (n *Native) ListenContext(ctx context.Context, instance, network, address string) (net.Listener, error) {
+	if network != "tcp" && network != "tcp4" && network != "tcp6" {
+		return nil, net.UnknownNetworkError(network)
+	}
+	port, err := parseListenPort(address)
+	if err != nil {
+		return nil, err
+	}
+	timeout := defaultTimeout
+	if deadline, ok := ctx.Deadline(); ok {
+		timeout = time.Until(deadline)
+	}
+	if timeout <= 0 {
+		return nil, context.DeadlineExceeded
+	}
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	handle, local, err := n.tcpBindTo(instance, uint16(port), timeout)
+	if err != nil {
+		return nil, err
+	}
+	return &Listener{native: n, handle: handle, addr: local}, nil
+}
+
+func (c *Conn) Read(b []byte) (int, error) {
+	if c.closed.Load() {
+		return 0, net.ErrClosed
+	}
+	n, err := c.native.tcpReadFrom(c.handle, b, c.rd.timeout(defaultTimeout))
+	if err != nil {
+		return 0, opError("read", c.remote, err)
+	}
+	if n == 0 {
+		return 0, io.EOF
+	}
+	return n, nil
+}
+
+func (c *Conn) Write(b []byte) (int, error) {
+	if c.closed.Load() {
+		return 0, net.ErrClosed
+	}
+	n, err := c.native.tcpWriteTo(c.handle, b, c.wd.timeout(defaultTimeout))
+	if err != nil {
+		return 0, opError("write", c.remote, err)
+	}
+	return n, nil
+}
+
+func (c *Conn) Close() error {
+	if !c.closed.CompareAndSwap(false, true) {
+		return net.ErrClosed
+	}
+	return c.native.tcpCloseHandle(c.handle)
+}
+
+func (c *Conn) LocalAddr() net.Addr                { return c.local }
+func (c *Conn) RemoteAddr() net.Addr               { return c.remote }
+func (c *Conn) SetDeadline(t time.Time) error      { c.rd.set(t); c.wd.set(t); return nil }
+func (c *Conn) SetReadDeadline(t time.Time) error  { c.rd.set(t); return nil }
+func (c *Conn) SetWriteDeadline(t time.Time) error { c.wd.set(t); return nil }
+
+func (l *Listener) Accept() (net.Conn, error) {
+	if l.closed.Load() {
+		return nil, net.ErrClosed
+	}
+	for {
+		handle, local, peer, err := l.native.tcpAcceptFrom(l.handle, defaultTimeout)
+		if err == nil {
+			return &Conn{native: l.native, handle: handle, local: local, remote: peer}, nil
+		}
+		if l.closed.Load() {
+			return nil, net.ErrClosed
+		}
+		var netErr net.Error
+		if errors.As(err, &netErr) && netErr.Timeout() {
+			continue
+		}
+		return nil, opError("accept", l.addr, err)
+	}
+}
+
+func (l *Listener) Close() error {
+	if !l.closed.CompareAndSwap(false, true) {
+		return net.ErrClosed
+	}
+	return l.native.tcpListenerCloseHandle(l.handle)
+}
+
+func (l *Listener) Addr() net.Addr { return l.addr }
+
+func (n *Native) bind() error {
+	return errors.Join(
+		n.bindSym(&n.runNetworkInstance, "run_network_instance", types.SInt32TypeDescriptor, types.PointerTypeDescriptor),
+		n.bindSym(&n.callJSONRPC, "call_json_rpc", types.SInt32TypeDescriptor, types.PointerTypeDescriptor, types.PointerTypeDescriptor, types.PointerTypeDescriptor, types.PointerTypeDescriptor, types.PointerTypeDescriptor),
+		n.bindSym(&n.getErrorMsg, "get_error_msg", types.VoidTypeDescriptor, types.PointerTypeDescriptor),
+		n.bindSym(&n.freeString, "free_string", types.VoidTypeDescriptor, types.PointerTypeDescriptor),
+		n.bindSym(&n.tcpConnect, "data_plane_tcp_connect", types.UInt64TypeDescriptor, types.PointerTypeDescriptor, types.PointerTypeDescriptor, types.UInt16TypeDescriptor, types.UInt64TypeDescriptor, types.PointerTypeDescriptor, types.PointerTypeDescriptor),
+		n.bindSym(&n.tcpBind, "data_plane_tcp_bind", types.UInt64TypeDescriptor, types.PointerTypeDescriptor, types.UInt16TypeDescriptor, types.UInt64TypeDescriptor, types.PointerTypeDescriptor, types.PointerTypeDescriptor),
+		n.bindSym(&n.tcpAccept, "data_plane_tcp_accept", types.UInt64TypeDescriptor, types.UInt64TypeDescriptor, types.UInt64TypeDescriptor, types.PointerTypeDescriptor, types.PointerTypeDescriptor, types.PointerTypeDescriptor, types.PointerTypeDescriptor),
+		n.bindSym(&n.tcpRead, "data_plane_tcp_read", types.SInt32TypeDescriptor, types.UInt64TypeDescriptor, types.PointerTypeDescriptor, types.UInt32TypeDescriptor, types.UInt64TypeDescriptor),
+		n.bindSym(&n.tcpWrite, "data_plane_tcp_write", types.SInt32TypeDescriptor, types.UInt64TypeDescriptor, types.PointerTypeDescriptor, types.UInt32TypeDescriptor, types.UInt64TypeDescriptor),
+		n.bindSym(&n.tcpClose, "data_plane_tcp_close", types.SInt32TypeDescriptor, types.UInt64TypeDescriptor),
+		n.bindSym(&n.tcpListenerClose, "data_plane_tcp_listener_close", types.SInt32TypeDescriptor, types.UInt64TypeDescriptor),
+	)
+}
+
+func (n *Native) bindSym(dst *symCall, name string, ret *types.TypeDescriptor, args ...*types.TypeDescriptor) error {
+	sym, err := ffi.GetSymbol(n.lib, name)
+	if err != nil {
+		return err
+	}
+	if err := ffi.PrepareCallInterface(&dst.cif, types.DefaultCall, ret, args); err != nil {
+		return err
+	}
+	dst.fn = sym
+	return nil
+}
+
+func (s *symCall) call(ret unsafe.Pointer, args ...unsafe.Pointer) error {
+	// `ffi.CallFunction` and libffi `ffi_call` are safe to invoke concurrently
+	// because `cif` is prepared once during binding and only read afterwards.
+	return ffi.CallFunction(&s.cif, s.fn, ret, args)
+}
+
+func (n *Native) tcpConnectTo(instance, ip string, port uint16, timeout time.Duration) (uint64, *net.TCPAddr, error) {
+	defer pinErrorThread()()
+	inst := cString(instance)
+	dst := cString(ip)
+	instPtr := unsafe.Pointer(&inst[0])
+	dstPtr := unsafe.Pointer(&dst[0])
+	timeoutMS := uint64(timeout / time.Millisecond)
+	var handle uint64
+	var outIP unsafe.Pointer
+	outIPArg := unsafe.Pointer(&outIP)
+	var outPort uint16
+	outPortArg := unsafe.Pointer(&outPort)
+	err := n.tcpConnect.call(
+		unsafe.Pointer(&handle),
+		unsafe.Pointer(&instPtr),
+		unsafe.Pointer(&dstPtr),
+		unsafe.Pointer(&port),
+		unsafe.Pointer(&timeoutMS),
+		unsafe.Pointer(&outIPArg),
+		unsafe.Pointer(&outPortArg),
+	)
+	runtime.KeepAlive(inst)
+	runtime.KeepAlive(dst)
+	if err != nil {
+		return 0, nil, err
+	}
+	if handle == 0 {
+		return 0, nil, n.lastError()
+	}
+	return handle, n.takeTCPAddr(outIP, outPort), nil
+}
+
+func (n *Native) tcpBindTo(instance string, port uint16, timeout time.Duration) (uint64, *net.TCPAddr, error) {
+	defer pinErrorThread()()
+	inst := cString(instance)
+	instPtr := unsafe.Pointer(&inst[0])
+	timeoutMS := uint64(timeout / time.Millisecond)
+	var handle uint64
+	var outIP unsafe.Pointer
+	outIPArg := unsafe.Pointer(&outIP)
+	var outPort uint16
+	outPortArg := unsafe.Pointer(&outPort)
+	err := n.tcpBind.call(
+		unsafe.Pointer(&handle),
+		unsafe.Pointer(&instPtr),
+		unsafe.Pointer(&port),
+		unsafe.Pointer(&timeoutMS),
+		unsafe.Pointer(&outIPArg),
+		unsafe.Pointer(&outPortArg),
+	)
+	runtime.KeepAlive(inst)
+	if err != nil {
+		return 0, nil, err
+	}
+	if handle == 0 {
+		return 0, nil, n.lastError()
+	}
+	return handle, n.takeTCPAddr(outIP, outPort), nil
+}
+
+func (n *Native) tcpAcceptFrom(handle uint64, timeout time.Duration) (uint64, *net.TCPAddr, *net.TCPAddr, error) {
+	defer pinErrorThread()()
+	timeoutMS := uint64(timeout / time.Millisecond)
+	var stream uint64
+	var outLocalIP unsafe.Pointer
+	outLocalIPArg := unsafe.Pointer(&outLocalIP)
+	var outLocalPort uint16
+	outLocalPortArg := unsafe.Pointer(&outLocalPort)
+	var outPeerIP unsafe.Pointer
+	outPeerIPArg := unsafe.Pointer(&outPeerIP)
+	var outPeerPort uint16
+	outPeerPortArg := unsafe.Pointer(&outPeerPort)
+	err := n.tcpAccept.call(
+		unsafe.Pointer(&stream),
+		unsafe.Pointer(&handle),
+		unsafe.Pointer(&timeoutMS),
+		unsafe.Pointer(&outLocalIPArg),
+		unsafe.Pointer(&outLocalPortArg),
+		unsafe.Pointer(&outPeerIPArg),
+		unsafe.Pointer(&outPeerPortArg),
+	)
+	if err != nil {
+		return 0, nil, nil, err
+	}
+	if stream == 0 {
+		return 0, nil, nil, n.lastError()
+	}
+	return stream, n.takeTCPAddr(outLocalIP, outLocalPort), n.takeTCPAddr(outPeerIP, outPeerPort), nil
+}
+
+func (n *Native) tcpReadFrom(handle uint64, buf []byte, timeout time.Duration) (int, error) {
+	if len(buf) == 0 {
+		return 0, nil
+	}
+	defer pinErrorThread()()
+	var ret int32
+	bufPtr := unsafe.Pointer(&buf[0])
+	length := uint32(len(buf))
+	timeoutMS := uint64(timeout / time.Millisecond)
+	err := n.tcpRead.call(unsafe.Pointer(&ret), unsafe.Pointer(&handle), unsafe.Pointer(&bufPtr), unsafe.Pointer(&length), unsafe.Pointer(&timeoutMS))
+	runtime.KeepAlive(buf)
+	if err != nil {
+		return 0, err
+	}
+	if ret < 0 {
+		return 0, n.lastError()
+	}
+	return int(ret), nil
+}
+
+func (n *Native) tcpWriteTo(handle uint64, buf []byte, timeout time.Duration) (int, error) {
+	if len(buf) == 0 {
+		return 0, nil
+	}
+	defer pinErrorThread()()
+	var ret int32
+	bufPtr := unsafe.Pointer(&buf[0])
+	length := uint32(len(buf))
+	timeoutMS := uint64(timeout / time.Millisecond)
+	err := n.tcpWrite.call(unsafe.Pointer(&ret), unsafe.Pointer(&handle), unsafe.Pointer(&bufPtr), unsafe.Pointer(&length), unsafe.Pointer(&timeoutMS))
+	runtime.KeepAlive(buf)
+	if err != nil {
+		return 0, err
+	}
+	if ret < 0 {
+		return 0, n.lastError()
+	}
+	return int(ret), nil
+}
+
+func (n *Native) tcpCloseHandle(handle uint64) error {
+	defer pinErrorThread()()
+	var ret int32
+	if err := n.tcpClose.call(unsafe.Pointer(&ret), unsafe.Pointer(&handle)); err != nil {
+		return err
+	}
+	if ret != 0 {
+		return n.lastError()
+	}
+	return nil
+}
+
+func (n *Native) tcpListenerCloseHandle(handle uint64) error {
+	defer pinErrorThread()()
+	var ret int32
+	if err := n.tcpListenerClose.call(unsafe.Pointer(&ret), unsafe.Pointer(&handle)); err != nil {
+		return err
+	}
+	if ret != 0 {
+		return n.lastError()
+	}
+	return nil
+}
+
+// pinErrorThread ties an FFI op to the get_error_msg that reads its result: the
+// Rust side stores the last error in a thread-local, so the goroutine must not
+// migrate to another OS thread between the two calls. Use as `defer pinErrorThread()()`
+// at the start of any wrapper that reports failures through lastError.
+func pinErrorThread() func() {
+	runtime.LockOSThread()
+	return runtime.UnlockOSThread
+}
+
+func (n *Native) lastError() error {
+	var out unsafe.Pointer
+	outArg := unsafe.Pointer(&out)
+	if err := n.getErrorMsg.call(nil, unsafe.Pointer(&outArg)); err != nil {
+		return err
+	}
+	if out == nil {
+		return errors.New("easytier ffi call failed")
+	}
+	msg := readCString(out)
+	_ = n.freeCString(out)
+	if strings.Contains(msg, "timed out") {
+		return timeoutError(msg)
+	}
+	return errors.New(msg)
+}
+
+func (n *Native) freeCString(ptr unsafe.Pointer) error {
+	if ptr == nil {
+		return nil
+	}
+	return n.freeString.call(nil, unsafe.Pointer(&ptr))
+}
+
+func (n *Native) takeTCPAddr(ipPtr unsafe.Pointer, port uint16) *net.TCPAddr {
+	if ipPtr == nil {
+		return nil
+	}
+	ip := net.ParseIP(readCString(ipPtr))
+	_ = n.freeCString(ipPtr)
+	return &net.TCPAddr{IP: ip, Port: int(port)}
+}
+
+func (d *atomicDeadline) set(t time.Time) {
+	if t.IsZero() {
+		d.v.Store(0)
+		return
+	}
+	d.v.Store(t.UnixNano())
+}
+
+func (d *atomicDeadline) timeout(fallback time.Duration) time.Duration {
+	ns := d.v.Load()
+	if ns == 0 {
+		return fallback
+	}
+	remaining := time.Until(time.Unix(0, ns))
+	if remaining <= 0 {
+		return time.Millisecond
+	}
+	return remaining
+}
+
+func (e timeoutError) Error() string   { return string(e) }
+func (e timeoutError) Timeout() bool   { return true }
+func (e timeoutError) Temporary() bool { return true }
+
+func opError(op string, addr net.Addr, err error) error {
+	return &net.OpError{Op: op, Net: "easytier", Addr: addr, Err: err}
+}
+
+func parseIPPort(address string) (net.IP, int, error) {
+	host, portStr, err := net.SplitHostPort(address)
+	if err != nil {
+		return nil, 0, err
+	}
+	ip := net.ParseIP(host)
+	if ip == nil {
+		return nil, 0, fmt.Errorf("easytier ffi requires an IP address, got %q", host)
+	}
+	port, err := strconv.ParseUint(portStr, 10, 16)
+	if err != nil {
+		return nil, 0, err
+	}
+	return ip, int(port), nil
+}
+
+func parseListenPort(address string) (int, error) {
+	host, portStr, err := net.SplitHostPort(address)
+	if err != nil {
+		return 0, err
+	}
+	if host != "" {
+		ip := net.ParseIP(host)
+		if ip == nil {
+			return 0, fmt.Errorf("easytier ffi requires an IP address, got %q", host)
+		}
+		if !ip.IsUnspecified() {
+			return 0, fmt.Errorf("easytier ffi listen address must be unspecified, got %q", host)
+		}
+	}
+	port, err := strconv.ParseUint(portStr, 10, 16)
+	if err != nil {
+		return 0, err
+	}
+	return int(port), nil
+}
+
+func cString(s string) []byte {
+	if strings.ContainsRune(s, 0) {
+		panic("easytier ffi string contains NUL")
+	}
+	return append([]byte(s), 0)
+}
+
+func readCString(ptr unsafe.Pointer) string {
+	if ptr == nil {
+		return ""
+	}
+	var b []byte
+	for p := uintptr(ptr); ; p++ {
+		c := *(*byte)(unsafe.Pointer(p))
+		if c == 0 {
+			return string(b)
+		}
+		b = append(b, c)
+	}
+}
+
+func defaultLibraryPath() string {
+	if p := os.Getenv("EASYTIER_FFI_LIB"); p != "" {
+		return p
+	}
+	switch runtime.GOOS {
+	case "darwin":
+		return "../../../../target/debug/libeasytier_ffi.dylib"
+	case "windows":
+		return "..\\..\\..\\..\\target\\debug\\easytier_ffi.dll"
+	default:
+		return "../../../../target/debug/libeasytier_ffi.so"
+	}
+}
+
+var _ net.Conn = (*Conn)(nil)
+var _ net.Listener = (*Listener)(nil)
@@ -0,0 +1,360 @@
+package easytierffi
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net"
+	"os"
+	"strconv"
+	"testing"
+	"time"
+)
+
+const asyncLocalTestTimeout = 120 * time.Second
+
+func TestAsyncSymbolBinding(t *testing.T) {
+	n := openAsyncForTest(t)
+
+	status, err := n.opWaitStatus(0, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if status != dataPlaneOpInvalid {
+		t.Fatalf("expected invalid status for op 0, got %d", status)
+	}
+}
+
+func TestAsyncLocalTwoNodeTCPAndUDP(t *testing.T) {
+	n := openAsyncForTest(t)
+	topology := startLocalAsyncTopology(t, n)
+
+	ctx, cancel := context.WithTimeout(context.Background(), asyncLocalTestTimeout)
+	defer cancel()
+
+	runAsyncTCPPingPong(t, ctx, n, topology)
+	runAsyncUDPPingPong(t, ctx, n, topology)
+}
+
+type localAsyncTopology struct {
+	dialerInstance   string
+	listenerInstance string
+	listenerIP       string
+}
+
+func openAsyncForTest(t *testing.T) *AsyncNative {
+	t.Helper()
+
+	libraryPath := defaultLibraryPath()
+	if _, err := os.Stat(libraryPath); err != nil {
+		if os.IsNotExist(err) {
+			t.Skipf("build easytier-ffi with ffi-dataplane before running async tests: %v", err)
+		}
+		t.Fatalf("stat async ffi library: %v", err)
+	}
+
+	n, err := OpenAsync(libraryPath)
+	if err != nil {
+		t.Fatalf("open async ffi library: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := n.Close(); err != nil {
+			t.Errorf("close async native: %v", err)
+		}
+	})
+	return n
+}
+
+func startLocalAsyncTopology(t *testing.T, n *AsyncNative) localAsyncTopology {
+	t.Helper()
+
+	suffix := strconv.FormatInt(time.Now().UnixNano(), 10)
+	networkName := "ffi-async-" + suffix
+	networkSecret := "ffi-async-secret-" + suffix
+	listenerInstance := "ffi-async-listener-" + suffix
+	dialerInstance := "ffi-async-dialer-" + suffix
+	listenerIP := "10.251.1.2"
+	dialerIP := "10.251.1.1"
+	listenerPort := freeLocalTCPPort(t)
+	listenerEndpoint := fmt.Sprintf("tcp://127.0.0.1:%d", listenerPort)
+	t.Cleanup(func() {
+		if err := n.deleteNetworkInstances([]string{dialerInstance, listenerInstance}); err != nil {
+			t.Errorf("cleanup async test EasyTier instances: %v", err)
+		}
+	})
+
+	listenerConfig := localAsyncConfig(
+		listenerInstance,
+		listenerIP,
+		networkName,
+		networkSecret,
+		[]string{listenerEndpoint},
+		nil,
+	)
+	dialerConfig := localAsyncConfig(
+		dialerInstance,
+		dialerIP,
+		networkName,
+		networkSecret,
+		nil,
+		[]string{listenerEndpoint},
+	)
+
+	if err := n.RunNetworkInstance(listenerConfig); err != nil {
+		t.Fatalf("start listener instance: %v", err)
+	}
+	if err := n.RunNetworkInstance(dialerConfig); err != nil {
+		t.Fatalf("start dialer instance: %v", err)
+	}
+
+	return localAsyncTopology{
+		dialerInstance:   dialerInstance,
+		listenerInstance: listenerInstance,
+		listenerIP:       listenerIP,
+	}
+}
+
+func localAsyncConfig(instance, ipv4, networkName, networkSecret string, listeners, peers []string) string {
+	config := fmt.Sprintf(`instance_name = %s
+ipv4 = %s
+listeners = %s
+
+[network_identity]
+network_name = %s
+network_secret = %s
+
+[flags]
+no_tun = true
+bind_device = false
+`,
+		strconv.Quote(instance),
+		strconv.Quote(ipv4),
+		tomlStringList(listeners),
+		strconv.Quote(networkName),
+		strconv.Quote(networkSecret),
+	)
+	for _, peer := range peers {
+		config += fmt.Sprintf("\n[[peer]]\nuri = %s\n", strconv.Quote(peer))
+	}
+	return config
+}
+
+func tomlStringList(values []string) string {
+	if len(values) == 0 {
+		return "[]"
+	}
+
+	out := "["
+	for i, value := range values {
+		if i > 0 {
+			out += ", "
+		}
+		out += strconv.Quote(value)
+	}
+	return out + "]"
+}
+
+func freeLocalTCPPort(t *testing.T) int {
+	t.Helper()
+
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("allocate local tcp port: %v", err)
+	}
+	defer listener.Close()
+	return listener.Addr().(*net.TCPAddr).Port
+}
+
+func runAsyncTCPPingPong(t *testing.T, ctx context.Context, n *AsyncNative, topology localAsyncTopology) {
+	t.Helper()
+
+	listener, listenerAddr := eventuallyTCPListen(t, ctx, n, topology.listenerInstance)
+
+	tcpCtx, cancel := context.WithCancel(ctx)
+	accepted := make(chan error, 1)
+	defer waitForAsyncHelper(t, accepted, "tcp accept helper")
+	defer cancel()
+	defer listener.Close()
+	go func() {
+		conn, err := listener.Accept()
+		if err != nil {
+			accepted <- fmt.Errorf("accept tcp stream: %w", err)
+			return
+		}
+		defer conn.Close()
+		_ = conn.SetDeadline(time.Now().Add(30 * time.Second))
+
+		payload := make([]byte, len("ping"))
+		if _, err := io.ReadFull(conn, payload); err != nil {
+			accepted <- fmt.Errorf("read tcp ping: %w", err)
+			return
+		}
+		if string(payload) != "ping" {
+			accepted <- fmt.Errorf("expected tcp ping, got %q", string(payload))
+			return
+		}
+		if _, err := conn.Write([]byte("pong")); err != nil {
+			accepted <- fmt.Errorf("write tcp pong: %w", err)
+			return
+		}
+		accepted <- nil
+	}()
+
+	conn, err := eventuallyTCPDial(t, tcpCtx, n, topology.dialerInstance, topology.listenerIP, listenerAddr.Port)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+	_ = conn.SetDeadline(time.Now().Add(30 * time.Second))
+
+	if _, err := conn.Write([]byte("ping")); err != nil {
+		t.Fatalf("write tcp ping: %v", err)
+	}
+	payload := make([]byte, len("pong"))
+	if _, err := io.ReadFull(conn, payload); err != nil {
+		t.Fatalf("read tcp pong: %v", err)
+	}
+	if string(payload) != "pong" {
+		t.Fatalf("expected tcp pong, got %q", string(payload))
+	}
+}
+
+func eventuallyTCPListen(t *testing.T, ctx context.Context, n *AsyncNative, instance string) (net.Listener, *net.TCPAddr) {
+	t.Helper()
+
+	var lastErr error
+	for attempt := 1; ctx.Err() == nil; attempt++ {
+		attemptCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
+		listener, err := n.ListenContext(attemptCtx, instance, "tcp", "0.0.0.0:0")
+		cancel()
+		if err == nil {
+			addr := listener.Addr().(*net.TCPAddr)
+			t.Logf("async tcp bind succeeded on attempt %d at %s", attempt, addr)
+			return listener, addr
+		}
+
+		lastErr = err
+		t.Logf("attempt %d: async tcp bind failed: %v", attempt, err)
+		waitForRetry(ctx, 500*time.Millisecond)
+	}
+	t.Fatalf("async tcp bind never succeeded: %v", lastErr)
+	panic("unreachable")
+}
+
+func eventuallyTCPDial(t *testing.T, ctx context.Context, n *AsyncNative, instance, ip string, port int) (net.Conn, error) {
+	t.Helper()
+
+	address := net.JoinHostPort(ip, strconv.Itoa(port))
+	var lastErr error
+	for attempt := 1; ctx.Err() == nil; attempt++ {
+		attemptCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
+		conn, err := n.DialContext(attemptCtx, instance, "tcp", address)
+		cancel()
+		if err == nil {
+			t.Logf("async tcp connect succeeded on attempt %d to %s", attempt, address)
+			return conn, nil
+		}
+
+		lastErr = err
+		t.Logf("attempt %d: async tcp connect failed: %v", attempt, err)
+		waitForRetry(ctx, 500*time.Millisecond)
+	}
+	return nil, fmt.Errorf("async tcp connect never succeeded: %w", lastErr)
+}
+
+func runAsyncUDPPingPong(t *testing.T, ctx context.Context, n *AsyncNative, topology localAsyncTopology) {
+	t.Helper()
+
+	dialerSocket, err := n.UDPBindContext(ctx, topology.dialerInstance, 0)
+	if err != nil {
+		t.Fatalf("bind dialer udp socket: %v", err)
+	}
+
+	listenerSocket, err := n.UDPBindContext(ctx, topology.listenerInstance, 0)
+	if err != nil {
+		t.Fatalf("bind listener udp socket: %v", err)
+	}
+
+	udpCtx, cancel := context.WithCancel(ctx)
+	warmupDone := make(chan error, 1)
+	received := make(chan error, 1)
+	defer waitForAsyncHelper(t, received, "udp receive helper")
+	defer cancel()
+	defer listenerSocket.Close()
+	defer dialerSocket.Close()
+
+	go func() {
+		if _, err := listenerSocket.SendTo(udpCtx, []byte("warmup"), dialerSocket.LocalAddr()); err != nil {
+			err = fmt.Errorf("send udp warmup: %w", err)
+			warmupDone <- err
+			received <- err
+			return
+		}
+		warmupDone <- nil
+
+		payload, from, err := listenerSocket.RecvFrom(udpCtx, 512)
+		if err != nil {
+			received <- fmt.Errorf("recv udp ping: %w", err)
+			return
+		}
+		if string(payload) != "ping" {
+			received <- fmt.Errorf("expected udp ping, got %q", string(payload))
+			return
+		}
+		if _, err := listenerSocket.SendTo(udpCtx, []byte("pong"), from); err != nil {
+			received <- fmt.Errorf("send udp pong: %w", err)
+			return
+		}
+		received <- nil
+	}()
+
+	select {
+	case err := <-warmupDone:
+		if err != nil {
+			t.Fatal(err)
+		}
+	case <-udpCtx.Done():
+		t.Fatal(udpCtx.Err())
+	}
+
+	target := &net.UDPAddr{IP: net.ParseIP(topology.listenerIP), Port: listenerSocket.LocalAddr().Port}
+	if _, err := dialerSocket.SendTo(udpCtx, []byte("ping"), target); err != nil {
+		t.Fatalf("send udp ping: %v", err)
+	}
+	for {
+		payload, from, err := dialerSocket.RecvFrom(udpCtx, 512)
+		if err != nil {
+			t.Fatalf("recv udp pong: %v", err)
+		}
+		if string(payload) == "pong" {
+			if !from.IP.Equal(target.IP) || from.Port != target.Port {
+				t.Fatalf("expected udp pong from %s, got %s", target, from)
+			}
+			break
+		}
+		t.Logf("skipping udp datagram from %s: %q", from, string(payload))
+	}
+}
+
+func waitForAsyncHelper(t *testing.T, done <-chan error, name string) {
+	t.Helper()
+
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Errorf("%s: %v", name, err)
+		}
+	case <-time.After(10 * time.Second):
+		t.Errorf("%s did not stop", name)
+	}
+}
+
+func waitForRetry(ctx context.Context, delay time.Duration) {
+	timer := time.NewTimer(delay)
+	defer timer.Stop()
+
+	select {
+	case <-timer.C:
+	case <-ctx.Done():
+	}
+}
@@ -0,0 +1,140 @@
+package easytierffi
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net"
+	"os"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestSSHIntegration(t *testing.T) {
+	config := os.Getenv("EASYTIER_FFI_CONFIG")
+	instance := os.Getenv("EASYTIER_FFI_INSTANCE")
+	target := os.Getenv("EASYTIER_FFI_TARGET")
+	if config == "" || instance == "" || target == "" {
+		t.Skip("set EASYTIER_FFI_CONFIG, EASYTIER_FFI_INSTANCE and EASYTIER_FFI_TARGET to run integration test")
+	}
+
+	n, err := Open(defaultLibraryPath())
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer n.Close()
+
+	if err := n.RunNetworkInstance(config); err != nil {
+		t.Fatal(err)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)
+	defer cancel()
+
+	var lastErr error
+	for attempt := 1; ctx.Err() == nil; attempt++ {
+		conn, err := n.DialContext(ctx, instance, "tcp", target)
+		if err != nil {
+			lastErr = err
+			t.Logf("attempt %d: dial failed: %v", attempt, err)
+			time.Sleep(3 * time.Second)
+			continue
+		}
+
+		_ = conn.SetReadDeadline(time.Now().Add(10 * time.Second))
+		buf := make([]byte, 128)
+		nn, err := conn.Read(buf)
+		_ = conn.Close()
+		if err != nil {
+			lastErr = err
+			t.Logf("attempt %d: read failed: %v", attempt, err)
+			time.Sleep(3 * time.Second)
+			continue
+		}
+		banner := string(buf[:nn])
+		if !strings.HasPrefix(banner, "SSH-") {
+			t.Fatalf("attempt %d: expected SSH banner, got %q", attempt, banner)
+		}
+		t.Logf("attempt %d: got banner %q", attempt, strings.TrimRight(banner, "\r\n"))
+		return
+	}
+	t.Fatalf("never got SSH banner, last err: %v", lastErr)
+}
+
+func TestTCPListenIntegration(t *testing.T) {
+	config := os.Getenv("EASYTIER_FFI_LISTEN_CONFIG")
+	instance := os.Getenv("EASYTIER_FFI_LISTEN_INSTANCE")
+	listenPort := os.Getenv("EASYTIER_FFI_LISTEN_PORT")
+	if config == "" || instance == "" || listenPort == "" {
+		t.Skip("set EASYTIER_FFI_LISTEN_CONFIG, EASYTIER_FFI_LISTEN_INSTANCE and EASYTIER_FFI_LISTEN_PORT to run integration test")
+	}
+	port, err := strconv.ParseUint(listenPort, 10, 16)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	n, err := Open(defaultLibraryPath())
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer n.Close()
+
+	if err := n.RunNetworkInstance(config); err != nil {
+		t.Fatal(err)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)
+	defer cancel()
+
+	// Data-plane readiness is asynchronous: the instance must finish starting
+	// before the data plane accepts binds. Retry until ready or ctx expires.
+	var listener net.Listener
+	for attempt := 1; ; attempt++ {
+		listener, err = n.ListenContext(ctx, instance, "tcp", net.JoinHostPort("0.0.0.0", strconv.Itoa(int(port))))
+		if err == nil {
+			break
+		}
+		if ctx.Err() != nil {
+			t.Fatalf("bind never succeeded, last err: %v", err)
+		}
+		t.Logf("attempt %d: bind failed: %v", attempt, err)
+		time.Sleep(3 * time.Second)
+	}
+	t.Logf("listening on %s; connect from another EasyTier peer and send ping", listener.Addr())
+
+	accepted := make(chan error, 1)
+	go func() {
+		conn, err := listener.Accept()
+		if err != nil {
+			accepted <- err
+			return
+		}
+		defer conn.Close()
+
+		_ = conn.SetDeadline(time.Now().Add(10 * time.Second))
+		buf := make([]byte, 4)
+		if _, err := io.ReadFull(conn, buf); err != nil {
+			accepted <- err
+			return
+		}
+		if string(buf) != "ping" {
+			accepted <- fmt.Errorf("expected %q, got %q", "ping", string(buf))
+			return
+		}
+		_, err = conn.Write([]byte("pong"))
+		accepted <- err
+	}()
+
+	select {
+	case err := <-accepted:
+		_ = listener.Close()
+		if err != nil {
+			t.Fatal(err)
+		}
+	case <-ctx.Done():
+		_ = listener.Close()
+		t.Fatal(ctx.Err())
+	}
+}
@@ -0,0 +1,5 @@
+module easytierffi-example
+
+go 1.25
+
+require github.com/go-webgpu/goffi v0.4.1
@@ -0,0 +1,2 @@
+github.com/go-webgpu/goffi v0.4.1 h1:2hQH5XXloxTyTtIleYv+Rajlwzp6UOETURhSZ5+zJxU=
+github.com/go-webgpu/goffi v0.4.1/go.mod h1:wfoxNsJkU+5RFbV1kNN1kunhc1lFHuJKK3zpgx08/uM=
@@ -0,0 +1,575 @@
+use std::{
+    cell::Cell,
+    collections::HashSet,
+    ffi::{CString, c_char, c_int, c_void},
+    sync::{
+        Arc, Mutex,
+        atomic::{AtomicBool, Ordering},
+    },
+};
+
+use easytier::{
+    common::{
+        MachineIdOptions,
+        config::{ConfigLoader as _, TomlConfigLoader},
+    },
+    tunnel::TunnelScheme,
+    web_client::{WebClient, WebClientHooks, run_web_client},
+};
+use uuid::Uuid;
+
+use crate::{
+    data_plane::remove_data_plane_handles_by_instance_ids,
+    error::set_error_msg,
+    state::{
+        ASYNC_RUNTIME, INSTANCE_MANAGER, INSTANCE_MUTATION_LOCK, INSTANCE_NAME_ID_MAP,
+        lock_remote_instance_mutation, remove_instance_name_ids,
+    },
+    strings::{c_str_to_string, optional_c_str_to_string},
+    types::ConfigServerEventCallback,
+};
+
+thread_local! {
+    static IN_CONFIG_SERVER_CALLBACK: Cell<bool> = const { Cell::new(false) };
+}
+
+static CONFIG_SERVER_CLIENT: once_cell::sync::Lazy<Mutex<Option<ManagedConfigServerClient>>> =
+    once_cell::sync::Lazy::new(|| Mutex::new(None));
+static CONFIG_SERVER_CLIENT_ACTIVE: once_cell::sync::Lazy<AtomicBool> =
+    once_cell::sync::Lazy::new(|| AtomicBool::new(false));
+static CONFIG_SERVER_CLIENT_STOPPING: once_cell::sync::Lazy<AtomicBool> =
+    once_cell::sync::Lazy::new(|| AtomicBool::new(false));
+static LAST_CONFIG_SERVER_CALLBACK_ERROR: once_cell::sync::Lazy<Mutex<Option<String>>> =
+    once_cell::sync::Lazy::new(|| Mutex::new(None));
+
+pub(crate) struct ConfigServerCallbackScope;
+
+impl ConfigServerCallbackScope {
+    pub(crate) fn enter() -> Self {
+        IN_CONFIG_SERVER_CALLBACK.with(|in_callback| in_callback.set(true));
+        Self
+    }
+}
+
+impl Drop for ConfigServerCallbackScope {
+    fn drop(&mut self) {
+        IN_CONFIG_SERVER_CALLBACK.with(|in_callback| in_callback.set(false));
+    }
+}
+
+pub fn in_config_server_callback() -> bool {
+    IN_CONFIG_SERVER_CALLBACK.with(Cell::get)
+}
+
+fn config_server_machine_id_options(machine_id: String) -> MachineIdOptions {
+    MachineIdOptions {
+        explicit_machine_id: Some(machine_id),
+        state_dir: None,
+    }
+}
+
+pub fn validate_config_server_client_options(
+    config_server_url_s: &str,
+    machine_id: &str,
+) -> Result<(), String> {
+    if machine_id.trim().is_empty() {
+        return Err("machine_id is empty".to_string());
+    }
+
+    let config_server_url = match url::Url::parse(config_server_url_s) {
+        Ok(url) => url,
+        Err(_) => format!(
+            "udp://config-server.easytier.cn:22020/{}",
+            config_server_url_s
+        )
+        .parse()
+        .map_err(|err| format!("failed to parse config server URL: {}", err))?,
+    };
+
+    TunnelScheme::try_from(&config_server_url).map_err(|_| {
+        format!(
+            "unsupported config server scheme: {}",
+            config_server_url.scheme()
+        )
+    })?;
+
+    let token = config_server_url
+        .path_segments()
+        .and_then(|mut segments| segments.next_back())
+        .map(|segment| percent_encoding::percent_decode_str(segment).decode_utf8())
+        .transpose()
+        .map_err(|err| format!("failed to decode config server token: {}", err))?
+        .map(|token| token.to_string())
+        .unwrap_or_default();
+
+    if token.is_empty() {
+        return Err("empty token".to_string());
+    }
+
+    Ok(())
+}
+
+struct ManagedConfigServerClient {
+    client: WebClient,
+    hooks: Arc<ManagedConfigServerClientHooks>,
+}
+
+pub(crate) struct ManagedConfigServerClientHooks {
+    pub(crate) instance_ids: Mutex<HashSet<Uuid>>,
+    callback_delivery: Mutex<()>,
+    stopping: AtomicBool,
+    callback: ConfigServerEventCallback,
+    user_data: usize,
+}
+
+impl ManagedConfigServerClientHooks {
+    pub(crate) fn new(callback: ConfigServerEventCallback, user_data: *mut c_void) -> Self {
+        Self {
+            instance_ids: Mutex::new(HashSet::new()),
+            callback_delivery: Mutex::new(()),
+            stopping: AtomicBool::new(false),
+            callback,
+            user_data: user_data as usize,
+        }
+    }
+
+    #[cfg(test)]
+    pub(crate) fn tracked_instance_ids(&self) -> Vec<Uuid> {
+        self.instance_ids
+            .lock()
+            .map(|guard| guard.iter().copied().collect())
+            .unwrap_or_default()
+    }
+
+    fn remove_tracked_instance_ids(&self, ids: &[Uuid]) -> Result<Vec<Uuid>, String> {
+        let mut guard = self.instance_ids.lock().map_err(|err| err.to_string())?;
+        Ok(ids
+            .iter()
+            .filter_map(|id| guard.remove(id).then_some(*id))
+            .collect())
+    }
+
+    fn validate_instance_name(&self, inst_name: &str, inst_id: Uuid) -> Result<(), String> {
+        if let Some(existing_id) = INSTANCE_NAME_ID_MAP.get(inst_name).map(|id| *id)
+            && existing_id != inst_id
+        {
+            return Err(format!("instance name {} already exists", inst_name));
+        }
+
+        Ok(())
+    }
+
+    fn commit_instance_name(&self, inst_name: String, inst_id: Uuid) -> Result<(), String> {
+        INSTANCE_NAME_ID_MAP.retain(|_, existing_id| *existing_id != inst_id);
+        self.validate_instance_name(&inst_name, inst_id)?;
+        INSTANCE_NAME_ID_MAP.insert(inst_name, inst_id);
+        Ok(())
+    }
+
+    pub(crate) fn start_stopping(&self) -> Vec<Uuid> {
+        let _delivery_guard = if in_config_server_callback() {
+            None
+        } else {
+            self.callback_delivery.lock().ok()
+        };
+        let mut guard = match self.instance_ids.lock() {
+            Ok(guard) => guard,
+            Err(_) => return Vec::new(),
+        };
+        self.stopping.store(true, Ordering::Release);
+        guard.drain().collect()
+    }
+
+    pub(crate) fn note_callback_error(&self, error: String) {
+        log::warn!("config server event callback failed: {}", error);
+        if let Ok(mut guard) = LAST_CONFIG_SERVER_CALLBACK_ERROR.lock() {
+            *guard = Some(error);
+        }
+    }
+
+    fn emit_event_with_delivery_locked(
+        &self,
+        event: &str,
+        instance_id: Uuid,
+    ) -> Result<(), String> {
+        if self.stopping.load(Ordering::Acquire) {
+            return Ok(());
+        }
+
+        let Some(callback) = self.callback else {
+            return Ok(());
+        };
+        let instance_name = INSTANCE_MANAGER
+            .get_instance_name(&instance_id)
+            .unwrap_or_default();
+        let network_name = INSTANCE_MANAGER
+            .get_network_name(&instance_id)
+            .unwrap_or_default();
+        let event_json = serde_json::json!({
+            "event": event,
+            "success": true,
+            "instance_id": instance_id.to_string(),
+            "instance_name": instance_name,
+            "network_name": network_name,
+            "error": null,
+        })
+        .to_string();
+        let event_json = CString::new(event_json).map_err(|err| err.to_string())?;
+        let _callback_scope = ConfigServerCallbackScope::enter();
+        unsafe {
+            callback(event_json.as_ptr(), self.user_data as *mut c_void);
+        }
+        Ok(())
+    }
+
+    fn emit_event(&self, event: &str, instance_id: Uuid) -> Result<(), String> {
+        let _delivery_guard = self
+            .callback_delivery
+            .lock()
+            .map_err(|err| err.to_string())?;
+        self.emit_event_with_delivery_locked(event, instance_id)
+    }
+
+    fn wait_for_callback_delivery(&self) {
+        if in_config_server_callback() {
+            return;
+        }
+
+        if let Ok(guard) = self.callback_delivery.lock() {
+            drop(guard);
+        }
+    }
+}
+
+#[async_trait::async_trait]
+impl WebClientHooks for ManagedConfigServerClientHooks {
+    fn manages_remote_config_instances(&self) -> bool {
+        true
+    }
+
+    async fn pre_run_network_instance(&self, cfg: &TomlConfigLoader) -> Result<(), String> {
+        if self.stopping.load(Ordering::Acquire) {
+            return Err("config server client is stopping".to_string());
+        }
+
+        let inst_name = cfg.get_inst_name();
+        let inst_id = cfg.get_id();
+
+        self.validate_instance_name(&inst_name, inst_id)
+    }
+
+    async fn post_run_network_instance(&self, id: &Uuid) -> Result<(), String> {
+        let _delivery_guard = self
+            .callback_delivery
+            .lock()
+            .map_err(|err| err.to_string())?;
+        let Some(inst_name) = INSTANCE_MANAGER.get_instance_name(id) else {
+            if !self.stopping.load(Ordering::Acquire) {
+                return Err(format!("instance {} not found after start", id));
+            }
+            return Ok(());
+        };
+
+        {
+            let _mutation_guard = INSTANCE_MUTATION_LOCK
+                .lock()
+                .map_err(|err| err.to_string())?;
+            if INSTANCE_MANAGER.get_instance_name(id).is_none() {
+                if !self.stopping.load(Ordering::Acquire) {
+                    return Err(format!("instance {} not found after start", id));
+                }
+                return Ok(());
+            }
+
+            let should_delete = {
+                let mut guard = self.instance_ids.lock().map_err(|err| err.to_string())?;
+                if self.stopping.load(Ordering::Acquire) {
+                    true
+                } else {
+                    guard.insert(*id);
+                    false
+                }
+            };
+
+            if should_delete {
+                if let Err(err) = INSTANCE_MANAGER.delete_network_instance(vec![*id]) {
+                    return Err(err.to_string());
+                }
+                remove_instance_name_ids(&[*id]);
+                return Ok(());
+            }
+
+            if self.stopping.load(Ordering::Acquire) {
+                self.remove_tracked_instance_ids(&[*id])?;
+                remove_instance_name_ids(&[*id]);
+                return Ok(());
+            }
+
+            if let Err(err) = self.commit_instance_name(inst_name.clone(), *id) {
+                self.remove_tracked_instance_ids(&[*id])?;
+                if let Err(delete_err) = INSTANCE_MANAGER.delete_network_instance(vec![*id]) {
+                    return Err(format!(
+                        "{}; failed to delete duplicate instance: {}",
+                        err, delete_err
+                    ));
+                }
+                return Err(err);
+            }
+
+            if self.stopping.load(Ordering::Acquire) {
+                self.remove_tracked_instance_ids(&[*id])?;
+                remove_instance_name_ids(&[*id]);
+                return Ok(());
+            }
+            if INSTANCE_MANAGER.get_instance_name(id).is_none() {
+                self.remove_tracked_instance_ids(&[*id])?;
+                remove_instance_name_ids(&[*id]);
+                return Err(format!(
+                    "instance {} was removed before post-run completed",
+                    id
+                ));
+            }
+        }
+
+        remove_data_plane_handles_by_instance_ids(&[*id]);
+
+        if let Err(err) = self.emit_event_with_delivery_locked("run_network_instance", *id) {
+            self.note_callback_error(err);
+        }
+        Ok(())
+    }
+
+    async fn post_remove_network_instances(&self, ids: &[Uuid]) -> Result<(), String> {
+        let removed_ids = {
+            let _mutation_guard = INSTANCE_MUTATION_LOCK
+                .lock()
+                .map_err(|err| err.to_string())?;
+            let removed_ids = self.remove_tracked_instance_ids(ids)?;
+            remove_instance_name_ids(ids);
+            remove_data_plane_handles_by_instance_ids(&removed_ids);
+            removed_ids
+        };
+
+        for id in removed_ids {
+            if let Err(err) = self.emit_event("delete_network_instance", id) {
+                self.note_callback_error(err);
+            }
+        }
+        Ok(())
+    }
+}
+
+pub(crate) fn remove_config_server_tracked_instance_ids(ids: &[Uuid]) {
+    if ids.is_empty() {
+        return;
+    }
+
+    if let Ok(guard) = CONFIG_SERVER_CLIENT.lock()
+        && let Some(managed) = guard.as_ref()
+        && let Err(err) = managed.hooks.remove_tracked_instance_ids(ids)
+    {
+        log::warn!("failed to remove config server tracked ids: {}", err);
+    }
+}
+
+pub(crate) fn wait_for_config_server_delivery() {
+    let hooks = CONFIG_SERVER_CLIENT
+        .lock()
+        .ok()
+        .and_then(|guard| guard.as_ref().map(|managed| managed.hooks.clone()));
+    if let Some(hooks) = hooks {
+        hooks.wait_for_callback_delivery();
+    }
+}
+
+pub(crate) fn last_callback_error() -> Option<String> {
+    LAST_CONFIG_SERVER_CALLBACK_ERROR
+        .lock()
+        .ok()
+        .and_then(|guard| guard.clone())
+}
+
+pub(crate) fn clear_last_callback_error() {
+    if let Ok(mut guard) = LAST_CONFIG_SERVER_CALLBACK_ERROR.lock() {
+        *guard = None;
+    }
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn is_config_server_active_or_stopping() -> bool {
+    CONFIG_SERVER_CLIENT_ACTIVE.load(Ordering::Acquire)
+        || CONFIG_SERVER_CLIENT_STOPPING.load(Ordering::Acquire)
+}
+
+#[cfg(test)]
+pub(crate) fn set_active_for_test(active: bool) {
+    CONFIG_SERVER_CLIENT_ACTIVE.store(active, Ordering::Release);
+}
+
+/// # Safety
+/// Start the config server client.
+///
+/// `config_server_url` must be a valid null-terminated UTF-8 string.
+/// `hostname` may be null; if non-null it must be a valid null-terminated UTF-8 string.
+/// `machine_id` must be a valid null-terminated UTF-8 string.
+/// `event_json` passed to `callback` is valid only during that callback invocation.
+pub(crate) unsafe fn start_config_server_client(
+    config_server_url: *const c_char,
+    hostname: *const c_char,
+    machine_id: *const c_char,
+    secure_mode: bool,
+    callback: ConfigServerEventCallback,
+    user_data: *mut c_void,
+) -> c_int {
+    if in_config_server_callback() {
+        set_error_msg("cannot start config server client from config server callback");
+        return -1;
+    }
+
+    let config_server_url = match unsafe { c_str_to_string(config_server_url, "config_server_url") }
+    {
+        Ok(value) => value,
+        Err(err) => {
+            set_error_msg(&err);
+            return -1;
+        }
+    };
+    let hostname = match unsafe { optional_c_str_to_string(hostname, "hostname") } {
+        Ok(value) => value,
+        Err(err) => {
+            set_error_msg(&err);
+            return -1;
+        }
+    };
+    let machine_id = match unsafe { c_str_to_string(machine_id, "machine_id") } {
+        Err(err) => {
+            set_error_msg(&err);
+            return -1;
+        }
+        Ok(value) => value,
+    };
+    if let Err(err) = validate_config_server_client_options(&config_server_url, &machine_id) {
+        set_error_msg(&err);
+        return -1;
+    }
+
+    let mut guard = match CONFIG_SERVER_CLIENT.lock() {
+        Ok(guard) => guard,
+        Err(err) => {
+            set_error_msg(&format!("failed to lock config server client: {}", err));
+            return -1;
+        }
+    };
+
+    if guard.is_some() {
+        set_error_msg("config server client already exists");
+        return -1;
+    }
+    if CONFIG_SERVER_CLIENT_STOPPING.load(Ordering::Acquire) {
+        set_error_msg("config server client is stopping");
+        return -1;
+    }
+    clear_last_callback_error();
+
+    #[cfg(feature = "ffi-dataplane")]
+    let data_plane_usage_guard = match crate::data_plane::lock_for_config_server_start() {
+        Ok(guard) => guard,
+        Err(err) => {
+            set_error_msg(&err);
+            return -1;
+        }
+    };
+
+    CONFIG_SERVER_CLIENT_ACTIVE.store(true, Ordering::Release);
+    #[cfg(feature = "ffi-dataplane")]
+    drop(data_plane_usage_guard);
+
+    let hooks = Arc::new(ManagedConfigServerClientHooks::new(callback, user_data));
+    let client = match ASYNC_RUNTIME.block_on(run_web_client(
+        &config_server_url,
+        config_server_machine_id_options(machine_id),
+        hostname,
+        secure_mode,
+        INSTANCE_MANAGER.clone(),
+        Some(hooks.clone()),
+    )) {
+        Ok(client) => client,
+        Err(err) => {
+            CONFIG_SERVER_CLIENT_ACTIVE.store(false, Ordering::Release);
+            set_error_msg(&format!("failed to start config server client: {}", err));
+            return -1;
+        }
+    };
+
+    *guard = Some(ManagedConfigServerClient { client, hooks });
+    0
+}
+
+pub(crate) fn stop_config_server_client() -> c_int {
+    if in_config_server_callback() {
+        set_error_msg("cannot stop config server client from config server callback");
+        return -1;
+    }
+
+    let mut guard = match CONFIG_SERVER_CLIENT.lock() {
+        Ok(guard) => guard,
+        Err(err) => {
+            set_error_msg(&format!("failed to lock config server client: {}", err));
+            return -1;
+        }
+    };
+
+    let Some(managed) = guard.as_ref() else {
+        CONFIG_SERVER_CLIENT_ACTIVE.store(false, Ordering::Release);
+        return 0;
+    };
+    if CONFIG_SERVER_CLIENT_STOPPING.swap(true, Ordering::AcqRel) {
+        set_error_msg("config server client is stopping");
+        return -1;
+    }
+    let hooks = managed.hooks.clone();
+    let managed = guard.take().expect("config server client exists");
+    drop(guard);
+
+    let _remote_mutation_guard = lock_remote_instance_mutation();
+    let tracked_ids = hooks.start_stopping();
+    drop(managed);
+
+    let _mutation_guard = match INSTANCE_MUTATION_LOCK.lock() {
+        Ok(guard) => guard,
+        Err(err) => {
+            hooks.wait_for_callback_delivery();
+            CONFIG_SERVER_CLIENT_ACTIVE.store(false, Ordering::Release);
+            CONFIG_SERVER_CLIENT_STOPPING.store(false, Ordering::Release);
+            set_error_msg(&format!("failed to lock instance mutation: {}", err));
+            return -1;
+        }
+    };
+    let delete_result = INSTANCE_MANAGER.delete_network_instance(tracked_ids.clone());
+    if delete_result.is_ok() {
+        remove_instance_name_ids(&tracked_ids);
+        remove_data_plane_handles_by_instance_ids(&tracked_ids);
+    }
+    drop(_mutation_guard);
+    hooks.wait_for_callback_delivery();
+    CONFIG_SERVER_CLIENT_ACTIVE.store(false, Ordering::Release);
+    CONFIG_SERVER_CLIENT_STOPPING.store(false, Ordering::Release);
+
+    if let Err(err) = delete_result {
+        set_error_msg(&format!(
+            "failed to delete config server instances: {}",
+            err
+        ));
+        return -1;
+    }
+    0
+}
+
+pub(crate) fn is_config_server_client_connected() -> c_int {
+    CONFIG_SERVER_CLIENT
+        .lock()
+        .ok()
+        .and_then(|guard| guard.as_ref().map(|managed| managed.client.is_connected()))
+        .map(i32::from)
+        .unwrap_or(0)
+}
@@ -0,0 +1,928 @@
+#[cfg(feature = "ffi-dataplane")]
+use std::{
+    future::Future,
+    net::{IpAddr, SocketAddr},
+    sync::{
+        Arc, RwLock,
+        atomic::{AtomicU64, Ordering},
+    },
+    time::Duration,
+};
+
+#[cfg(feature = "ffi-dataplane")]
+use dashmap::DashMap;
+#[cfg(feature = "ffi-dataplane")]
+use easytier::launcher::{DataPlaneTcpListener, DataPlaneTcpStream, DataPlaneUdpSocket};
+#[cfg(feature = "ffi-dataplane")]
+use tokio::io::{AsyncReadExt, AsyncWriteExt, ReadHalf, WriteHalf};
+#[cfg(feature = "ffi-dataplane")]
+use tokio_util::sync::CancellationToken;
+#[cfg(feature = "ffi-dataplane")]
+use uuid::Uuid;
+
+#[cfg(feature = "ffi-dataplane")]
+use crate::{
+    config_server::{in_config_server_callback, is_config_server_active_or_stopping},
+    error::{free_string, set_error_msg},
+    state::{INSTANCE_MANAGER, INSTANCE_NAME_ID_MAP},
+};
+
+#[cfg(feature = "ffi-dataplane")]
+static NEXT_DATA_PLANE_HANDLE: AtomicU64 = AtomicU64::new(1);
+#[cfg(feature = "ffi-dataplane")]
+static DATA_PLANE_HANDLES: once_cell::sync::Lazy<DashMap<u64, DataPlaneHandle>> =
+    once_cell::sync::Lazy::new(DashMap::new);
+#[cfg(feature = "ffi-dataplane")]
+static DATA_PLANE_USAGE_LOCK: once_cell::sync::Lazy<RwLock<()>> =
+    once_cell::sync::Lazy::new(|| RwLock::new(()));
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) struct DataPlaneHandle {
+    pub(crate) instance_id: uuid::Uuid,
+    pub(crate) runtime: tokio::runtime::Handle,
+    // Cancelled by close() to wake any in-flight op on this handle.
+    pub(crate) close_token: CancellationToken,
+    pub(crate) resource: DataPlaneResource,
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) struct TcpHalves {
+    pub(crate) read: tokio::sync::Mutex<ReadHalf<DataPlaneTcpStream>>,
+    pub(crate) write: tokio::sync::Mutex<WriteHalf<DataPlaneTcpStream>>,
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) enum DataPlaneResource {
+    Tcp(Arc<TcpHalves>),
+    TcpListener(Arc<tokio::sync::Mutex<DataPlaneTcpListener>>),
+    Udp(Arc<DataPlaneUdpSocket>),
+}
+
+// Several helper functions for FFI data plane operations to facilitate logic reuse.
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn next_handle() -> u64 {
+    NEXT_DATA_PLANE_HANDLE.fetch_add(1, Ordering::Relaxed)
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn timeout_duration(timeout_ms: u64) -> Duration {
+    Duration::from_millis(timeout_ms)
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) unsafe fn cstr_to_string(ptr: *const std::ffi::c_char, name: &str) -> Option<String> {
+    if ptr.is_null() {
+        set_error_msg(&format!("{} is null", name));
+        return None;
+    }
+    Some(
+        unsafe { std::ffi::CStr::from_ptr(ptr) }
+            .to_string_lossy()
+            .into_owned(),
+    )
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn get_instance_id(inst_name: &str) -> Option<uuid::Uuid> {
+    INSTANCE_NAME_ID_MAP.get(inst_name).map(|id| *id.value())
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn parse_socket_addr(host: &str, port: u16) -> Option<SocketAddr> {
+    let ip = match host.parse::<IpAddr>() {
+        Ok(ip) => ip,
+        Err(e) => {
+            set_error_msg(&format!("failed to parse ip address: {}", e));
+            return None;
+        }
+    };
+    Some(SocketAddr::new(ip, port))
+}
+
+/// Encode an IP address for FFI return. Returns `*mut c_char` to match
+/// `CString::into_raw`; caller releases it via `free_string`.
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn into_ffi_ip_cstring(ip: IpAddr) -> Option<*mut std::ffi::c_char> {
+    match std::ffi::CString::new(ip.to_string()) {
+        Ok(s) => Some(s.into_raw()),
+        Err(e) => {
+            set_error_msg(&format!("failed to encode ip: {}", e));
+            None
+        }
+    }
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn get_runtime_handle(
+    inst_id: &uuid::Uuid,
+    deadline: std::time::Instant,
+) -> Option<tokio::runtime::Handle> {
+    let remaining = deadline.saturating_duration_since(std::time::Instant::now());
+    let Some(rt) = INSTANCE_MANAGER.data_plane_wait_runtime_handle(inst_id, remaining) else {
+        set_error_msg("instance runtime is not ready");
+        return None;
+    };
+    Some(rt)
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn insert_tcp_stream_handle(
+    instance_id: uuid::Uuid,
+    runtime: tokio::runtime::Handle,
+    stream: DataPlaneTcpStream,
+) -> u64 {
+    let (rd, wr) = tokio::io::split(stream);
+    let handle = next_handle();
+    DATA_PLANE_HANDLES.insert(
+        handle,
+        DataPlaneHandle {
+            instance_id,
+            runtime,
+            close_token: CancellationToken::new(),
+            resource: DataPlaneResource::Tcp(Arc::new(TcpHalves {
+                read: tokio::sync::Mutex::new(rd),
+                write: tokio::sync::Mutex::new(wr),
+            })),
+        },
+    );
+    handle
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn insert_tcp_listener_handle(
+    instance_id: uuid::Uuid,
+    runtime: tokio::runtime::Handle,
+    listener: DataPlaneTcpListener,
+) -> u64 {
+    let handle = next_handle();
+    DATA_PLANE_HANDLES.insert(
+        handle,
+        DataPlaneHandle {
+            instance_id,
+            runtime,
+            close_token: CancellationToken::new(),
+            resource: DataPlaneResource::TcpListener(Arc::new(tokio::sync::Mutex::new(listener))),
+        },
+    );
+    handle
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn insert_udp_socket_handle(
+    instance_id: uuid::Uuid,
+    runtime: tokio::runtime::Handle,
+    socket: DataPlaneUdpSocket,
+) -> u64 {
+    let handle = next_handle();
+    DATA_PLANE_HANDLES.insert(
+        handle,
+        DataPlaneHandle {
+            instance_id,
+            runtime,
+            close_token: CancellationToken::new(),
+            resource: DataPlaneResource::Udp(Arc::new(socket)),
+        },
+    );
+    handle
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn get_tcp_stream(
+    handle: u64,
+) -> Option<(Arc<TcpHalves>, tokio::runtime::Handle, CancellationToken)> {
+    get_tcp_stream_with_instance(handle)
+        .map(|(halves, runtime, close_token, _)| (halves, runtime, close_token))
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn get_tcp_stream_with_instance(
+    handle: u64,
+) -> Option<(
+    Arc<TcpHalves>,
+    tokio::runtime::Handle,
+    CancellationToken,
+    uuid::Uuid,
+)> {
+    let Some(h) = DATA_PLANE_HANDLES.get(&handle) else {
+        set_error_msg("tcp stream handle not found");
+        return None;
+    };
+    match &h.resource {
+        DataPlaneResource::Tcp(halves) => Some((
+            halves.clone(),
+            h.runtime.clone(),
+            h.close_token.clone(),
+            h.instance_id,
+        )),
+        DataPlaneResource::TcpListener(_) | DataPlaneResource::Udp(_) => {
+            set_error_msg("handle is not a tcp stream");
+            None
+        }
+    }
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn get_tcp_listener(
+    handle: u64,
+) -> Option<(
+    Arc<tokio::sync::Mutex<DataPlaneTcpListener>>,
+    tokio::runtime::Handle,
+    CancellationToken,
+    uuid::Uuid,
+)> {
+    let Some(h) = DATA_PLANE_HANDLES.get(&handle) else {
+        set_error_msg("tcp listener handle not found");
+        return None;
+    };
+    match &h.resource {
+        DataPlaneResource::TcpListener(listener) => Some((
+            listener.clone(),
+            h.runtime.clone(),
+            h.close_token.clone(),
+            h.instance_id,
+        )),
+        DataPlaneResource::Tcp(_) | DataPlaneResource::Udp(_) => {
+            set_error_msg("handle is not a tcp listener");
+            None
+        }
+    }
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn get_udp_socket(
+    handle: u64,
+) -> Option<(
+    Arc<DataPlaneUdpSocket>,
+    tokio::runtime::Handle,
+    CancellationToken,
+)> {
+    get_udp_socket_with_instance(handle)
+        .map(|(socket, runtime, close_token, _)| (socket, runtime, close_token))
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn get_udp_socket_with_instance(
+    handle: u64,
+) -> Option<(
+    Arc<DataPlaneUdpSocket>,
+    tokio::runtime::Handle,
+    CancellationToken,
+    uuid::Uuid,
+)> {
+    let Some(h) = DATA_PLANE_HANDLES.get(&handle) else {
+        set_error_msg("udp socket handle not found");
+        return None;
+    };
+    match &h.resource {
+        DataPlaneResource::Udp(socket) => Some((
+            socket.clone(),
+            h.runtime.clone(),
+            h.close_token.clone(),
+            h.instance_id,
+        )),
+        DataPlaneResource::Tcp(_) | DataPlaneResource::TcpListener(_) => {
+            set_error_msg("handle is not a udp socket");
+            None
+        }
+    }
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn remove_data_plane_handles_by_instance_ids(ids: &[Uuid]) {
+    if ids.is_empty() {
+        return;
+    }
+
+    let _data_plane_usage_guard = DATA_PLANE_USAGE_LOCK
+        .write()
+        .unwrap_or_else(|err| err.into_inner());
+
+    DATA_PLANE_HANDLES.retain(|_, handle| {
+        if ids.contains(&handle.instance_id) {
+            handle.close_token.cancel();
+            false
+        } else {
+            true
+        }
+    });
+    crate::data_plane_async::remove_ops_by_instance_ids(ids);
+}
+
+#[cfg(not(feature = "ffi-dataplane"))]
+pub(crate) fn remove_data_plane_handles_by_instance_ids(_ids: &[uuid::Uuid]) {}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn data_plane_rejected() -> bool {
+    if in_config_server_callback() {
+        set_error_msg("cannot use data plane from config server callback");
+        true
+    } else if is_config_server_active_or_stopping() {
+        set_error_msg("cannot use data plane while config server client is active");
+        true
+    } else {
+        false
+    }
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn enter_data_plane_operation() -> Option<std::sync::RwLockReadGuard<'static, ()>> {
+    if data_plane_rejected() {
+        return None;
+    }
+
+    let guard = match DATA_PLANE_USAGE_LOCK.read() {
+        Ok(guard) => guard,
+        Err(err) => {
+            set_error_msg(&format!("failed to lock data plane usage: {}", err));
+            return None;
+        }
+    };
+    if data_plane_rejected() {
+        return None;
+    }
+    Some(guard)
+}
+
+/// Run an IO op on the resource's owning runtime, supporting
+/// timeout and cancellation.
+#[cfg(feature = "ffi-dataplane")]
+async fn run_with_cancel<T, F>(
+    close_token: &CancellationToken,
+    timeout_ms: u64,
+    error_prefix: &str,
+    op: F,
+) -> Option<Result<T, std::io::Error>>
+where
+    F: Future<Output = Result<T, std::io::Error>>,
+{
+    tokio::select! {
+        biased;
+        _ = close_token.cancelled() => {
+            set_error_msg(&format!("{}: handle closed", error_prefix));
+            None
+        }
+        res = tokio::time::timeout(timeout_duration(timeout_ms), op) => match res {
+            Ok(r) => Some(r),
+            Err(_) => {
+                set_error_msg(&format!("{} timed out", error_prefix));
+                None
+            }
+        }
+    }
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn lock_for_config_server_start()
+-> Result<std::sync::RwLockWriteGuard<'static, ()>, String> {
+    let guard = DATA_PLANE_USAGE_LOCK
+        .write()
+        .map_err(|err| format!("failed to lock data plane usage: {}", err))?;
+    if !DATA_PLANE_HANDLES.is_empty() || crate::data_plane_async::has_live_ops() {
+        return Err("cannot start config server client while data plane is in use".to_string());
+    }
+    Ok(guard)
+}
+/// # Safety
+/// Open a TCP stream through an EasyTier instance data plane. Returns 0 on
+/// failure. On success, writes the local socket address chosen for this
+/// connection into `out_local_ip` (a heap-allocated C string the caller must
+/// release via `free_string`) and `out_local_port`. Both out pointers must be
+/// non-null.
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) unsafe fn data_plane_tcp_connect(
+    inst_name: *const std::ffi::c_char,
+    dst_ip: *const std::ffi::c_char,
+    dst_port: std::ffi::c_ushort,
+    timeout_ms: u64,
+    out_local_ip: *mut *const std::ffi::c_char,
+    out_local_port: *mut std::ffi::c_ushort,
+) -> u64 {
+    let _data_plane_usage_guard = match enter_data_plane_operation() {
+        Some(guard) => guard,
+        None => return 0,
+    };
+    if out_local_ip.is_null() || out_local_port.is_null() {
+        set_error_msg("output pointer is null");
+        return 0;
+    }
+    let Some(inst_name) = (unsafe { cstr_to_string(inst_name, "inst_name") }) else {
+        return 0;
+    };
+    let Some(dst_ip) = (unsafe { cstr_to_string(dst_ip, "dst_ip") }) else {
+        return 0;
+    };
+    let Some(inst_id) = get_instance_id(&inst_name) else {
+        set_error_msg("instance not found");
+        return 0;
+    };
+    let Some(dst_addr) = parse_socket_addr(&dst_ip, dst_port) else {
+        return 0;
+    };
+    let deadline = std::time::Instant::now() + timeout_duration(timeout_ms);
+    let Some(runtime) = get_runtime_handle(&inst_id, deadline) else {
+        return 0;
+    };
+
+    let remaining = deadline.saturating_duration_since(std::time::Instant::now());
+    let result =
+        runtime.block_on(INSTANCE_MANAGER.data_plane_tcp_connect(&inst_id, dst_addr, remaining));
+    match result {
+        Ok(stream) => {
+            let local_addr = stream.local_addr();
+            let Some(local_ip) = into_ffi_ip_cstring(local_addr.ip()) else {
+                return 0;
+            };
+            let handle = insert_tcp_stream_handle(inst_id, runtime, stream);
+            unsafe {
+                *out_local_ip = local_ip as *const std::ffi::c_char;
+                *out_local_port = local_addr.port();
+            }
+            handle
+        }
+        Err(e) => {
+            set_error_msg(&format!("failed to connect tcp data plane: {}", e));
+            0
+        }
+    }
+}
+
+/// # Safety
+/// Bind a TCP listener through an EasyTier instance data plane. Returns 0 on
+/// failure. The local address actually bound is written into `out_local_ip` /
+/// `out_local_port`; the caller must release `*out_local_ip` via `free_string`.
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) unsafe fn data_plane_tcp_bind(
+    inst_name: *const std::ffi::c_char,
+    local_port: std::ffi::c_ushort,
+    timeout_ms: u64,
+    out_local_ip: *mut *const std::ffi::c_char,
+    out_local_port: *mut std::ffi::c_ushort,
+) -> u64 {
+    let _data_plane_usage_guard = match enter_data_plane_operation() {
+        Some(guard) => guard,
+        None => return 0,
+    };
+    if out_local_ip.is_null() || out_local_port.is_null() {
+        set_error_msg("output pointer is null");
+        return 0;
+    }
+    let Some(inst_name) = (unsafe { cstr_to_string(inst_name, "inst_name") }) else {
+        return 0;
+    };
+    let Some(inst_id) = get_instance_id(&inst_name) else {
+        set_error_msg("instance not found");
+        return 0;
+    };
+    let deadline = std::time::Instant::now() + timeout_duration(timeout_ms);
+    let Some(runtime) = get_runtime_handle(&inst_id, deadline) else {
+        return 0;
+    };
+
+    let remaining = deadline.saturating_duration_since(std::time::Instant::now());
+    let result =
+        runtime.block_on(INSTANCE_MANAGER.data_plane_tcp_bind(&inst_id, local_port, remaining));
+    match result {
+        Ok(listener) => {
+            let local_addr = listener.local_addr();
+            let Some(local_ip) = into_ffi_ip_cstring(local_addr.ip()) else {
+                return 0;
+            };
+            let handle = insert_tcp_listener_handle(inst_id, runtime, listener);
+            unsafe {
+                *out_local_ip = local_ip as *const std::ffi::c_char;
+                *out_local_port = local_addr.port();
+            }
+            handle
+        }
+        Err(e) => {
+            set_error_msg(&format!("failed to bind tcp data plane: {}", e));
+            0
+        }
+    }
+}
+
+/// # Safety
+/// Accept one connection from a TCP data-plane listener. Returns a TCP stream
+/// handle, or 0 on failure. Local and peer addresses are written into out
+/// parameters; returned IP strings must be released via `free_string`.
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) unsafe fn data_plane_tcp_accept(
+    handle: u64,
+    timeout_ms: u64,
+    out_local_ip: *mut *const std::ffi::c_char,
+    out_local_port: *mut std::ffi::c_ushort,
+    out_peer_ip: *mut *const std::ffi::c_char,
+    out_peer_port: *mut std::ffi::c_ushort,
+) -> u64 {
+    let _data_plane_usage_guard = match enter_data_plane_operation() {
+        Some(guard) => guard,
+        None => return 0,
+    };
+    if out_local_ip.is_null()
+        || out_local_port.is_null()
+        || out_peer_ip.is_null()
+        || out_peer_port.is_null()
+    {
+        set_error_msg("output pointer is null");
+        return 0;
+    }
+    let Some((listener, runtime, close_token, instance_id)) = get_tcp_listener(handle) else {
+        return 0;
+    };
+
+    let ret = runtime.block_on(async move {
+        let mut listener = listener.lock().await;
+        run_with_cancel(
+            &close_token,
+            timeout_ms,
+            "tcp data plane accept",
+            listener.accept(),
+        )
+        .await
+    });
+
+    match ret {
+        Some(Ok((stream, peer_addr))) => {
+            let local_addr = stream.local_addr();
+            let Some(local_ip) = into_ffi_ip_cstring(local_addr.ip()) else {
+                return 0;
+            };
+            let Some(peer_ip) = into_ffi_ip_cstring(peer_addr.ip()) else {
+                free_string(local_ip);
+                return 0;
+            };
+            let stream_handle = insert_tcp_stream_handle(instance_id, runtime, stream);
+            unsafe {
+                *out_local_ip = local_ip as *const std::ffi::c_char;
+                *out_local_port = local_addr.port();
+                *out_peer_ip = peer_ip as *const std::ffi::c_char;
+                *out_peer_port = peer_addr.port();
+            }
+            stream_handle
+        }
+        Some(Err(e)) => {
+            set_error_msg(&format!("failed to accept tcp data plane: {}", e));
+            0
+        }
+        None => 0,
+    }
+}
+
+/// # Safety
+/// Read from a TCP data-plane stream.
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) unsafe fn data_plane_tcp_read(
+    handle: u64,
+    buf: *mut std::ffi::c_uchar,
+    len: u32,
+    timeout_ms: u64,
+) -> std::ffi::c_int {
+    let _data_plane_usage_guard = match enter_data_plane_operation() {
+        Some(guard) => guard,
+        None => return -1,
+    };
+    if buf.is_null() {
+        set_error_msg("buf is null");
+        return -1;
+    }
+    let Some((halves, runtime, close_token)) = get_tcp_stream(handle) else {
+        return -1;
+    };
+    // Safety: caller-owned buffer outlives this blocking call.
+    let buf = unsafe { std::slice::from_raw_parts_mut(buf, len as usize) };
+    runtime.block_on(async move {
+        let mut rd = halves.read.lock().await;
+        match run_with_cancel(
+            &close_token,
+            timeout_ms,
+            "failed to read tcp data plane",
+            rd.read(buf),
+        )
+        .await
+        {
+            Some(Ok(n)) => n as std::ffi::c_int,
+            Some(Err(e)) => {
+                set_error_msg(&format!("failed to read tcp data plane: {}", e));
+                -1
+            }
+            None => -1,
+        }
+    })
+}
+
+/// # Safety
+/// Write to a TCP data-plane stream.
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) unsafe fn data_plane_tcp_write(
+    handle: u64,
+    buf: *const std::ffi::c_uchar,
+    len: u32,
+    timeout_ms: u64,
+) -> std::ffi::c_int {
+    let _data_plane_usage_guard = match enter_data_plane_operation() {
+        Some(guard) => guard,
+        None => return -1,
+    };
+    if buf.is_null() {
+        set_error_msg("buf is null");
+        return -1;
+    }
+    let Some((halves, runtime, close_token)) = get_tcp_stream(handle) else {
+        return -1;
+    };
+    let total = len as usize;
+    // Safety: caller-owned buffer outlives this blocking call.
+    let buf = unsafe { std::slice::from_raw_parts(buf, total) };
+    runtime.block_on(async move {
+        let mut wr = halves.write.lock().await;
+        // Use `write_all` to honor `net.Conn::Write` semantics on the Go side
+        // (must write everything or return an error); single `write()` can
+        // silently short-write and corrupt streams that the caller assumes are
+        // fully written.
+        match run_with_cancel(
+            &close_token,
+            timeout_ms,
+            "failed to write tcp data plane",
+            wr.write_all(buf),
+        )
+        .await
+        {
+            Some(Ok(())) => total as std::ffi::c_int,
+            Some(Err(e)) => {
+                set_error_msg(&format!("failed to write tcp data plane: {}", e));
+                -1
+            }
+            None => -1,
+        }
+    })
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn data_plane_tcp_close(handle: u64) -> std::ffi::c_int {
+    let _data_plane_usage_guard = match enter_data_plane_operation() {
+        Some(guard) => guard,
+        None => return -1,
+    };
+    crate::data_plane_async::cancel_ops_for_handle(handle);
+    let Some((_, h)) = DATA_PLANE_HANDLES.remove_if(&handle, |_, e| {
+        matches!(e.resource, DataPlaneResource::Tcp(_))
+    }) else {
+        set_error_msg(if DATA_PLANE_HANDLES.contains_key(&handle) {
+            "handle is not a tcp stream"
+        } else {
+            "tcp stream handle not found"
+        });
+        return -1;
+    };
+    h.close_token.cancel();
+    if let DataPlaneResource::Tcp(halves) = h.resource {
+        // Best-effort half-close; if write half is in use, the in-flight call
+        // observes the cancel token and releases the lock shortly after.
+        h.runtime.spawn(async move {
+            if let Ok(mut wr) = halves.write.try_lock() {
+                let _ = wr.shutdown().await;
+            }
+        });
+    }
+    0
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn data_plane_tcp_listener_close(handle: u64) -> std::ffi::c_int {
+    let _data_plane_usage_guard = match enter_data_plane_operation() {
+        Some(guard) => guard,
+        None => return -1,
+    };
+    crate::data_plane_async::cancel_ops_for_handle(handle);
+    let Some((_, h)) = DATA_PLANE_HANDLES.remove_if(&handle, |_, e| {
+        matches!(e.resource, DataPlaneResource::TcpListener(_))
+    }) else {
+        set_error_msg(if DATA_PLANE_HANDLES.contains_key(&handle) {
+            "handle is not a tcp listener"
+        } else {
+            "tcp listener handle not found"
+        });
+        return -1;
+    };
+    h.close_token.cancel();
+    0
+}
+
+/// # Safety
+/// Bind a UDP socket through an EasyTier instance data plane. Returns 0 on
+/// failure. The local address actually bound (which may differ from the
+/// requested port when `local_port == 0`) is written into `out_local_ip` /
+/// `out_local_port`; the caller must release `*out_local_ip` via `free_string`.
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) unsafe fn data_plane_udp_bind(
+    inst_name: *const std::ffi::c_char,
+    local_port: std::ffi::c_ushort,
+    timeout_ms: u64,
+    out_local_ip: *mut *const std::ffi::c_char,
+    out_local_port: *mut std::ffi::c_ushort,
+) -> u64 {
+    let _data_plane_usage_guard = match enter_data_plane_operation() {
+        Some(guard) => guard,
+        None => return 0,
+    };
+    if out_local_ip.is_null() || out_local_port.is_null() {
+        set_error_msg("output pointer is null");
+        return 0;
+    }
+    let Some(inst_name) = (unsafe { cstr_to_string(inst_name, "inst_name") }) else {
+        return 0;
+    };
+    let Some(inst_id) = get_instance_id(&inst_name) else {
+        set_error_msg("instance not found");
+        return 0;
+    };
+    let deadline = std::time::Instant::now() + timeout_duration(timeout_ms);
+    let Some(runtime) = get_runtime_handle(&inst_id, deadline) else {
+        return 0;
+    };
+
+    let remaining = deadline.saturating_duration_since(std::time::Instant::now());
+    let result =
+        runtime.block_on(INSTANCE_MANAGER.data_plane_udp_bind(&inst_id, local_port, remaining));
+    match result {
+        Ok(socket) => {
+            let local_addr = socket.local_addr();
+            let Some(local_ip) = into_ffi_ip_cstring(local_addr.ip()) else {
+                return 0;
+            };
+            let handle = insert_udp_socket_handle(inst_id, runtime, socket);
+            unsafe {
+                *out_local_ip = local_ip as *const std::ffi::c_char;
+                *out_local_port = local_addr.port();
+            }
+            handle
+        }
+        Err(e) => {
+            set_error_msg(&format!("failed to bind udp data plane: {}", e));
+            0
+        }
+    }
+}
+
+/// # Safety
+/// Send a datagram through a UDP data-plane socket.
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) unsafe fn data_plane_udp_send_to(
+    handle: u64,
+    dst_ip: *const std::ffi::c_char,
+    dst_port: std::ffi::c_ushort,
+    buf: *const std::ffi::c_uchar,
+    len: u32,
+    timeout_ms: u64,
+) -> std::ffi::c_int {
+    let _data_plane_usage_guard = match enter_data_plane_operation() {
+        Some(guard) => guard,
+        None => return -1,
+    };
+    if buf.is_null() {
+        set_error_msg("buf is null");
+        return -1;
+    }
+    let Some(dst_ip) = (unsafe { cstr_to_string(dst_ip, "dst_ip") }) else {
+        return -1;
+    };
+    let Some(dst_addr) = parse_socket_addr(&dst_ip, dst_port) else {
+        return -1;
+    };
+    let Some((socket, runtime, close_token)) = get_udp_socket(handle) else {
+        return -1;
+    };
+    let total = len as usize;
+    // Safety: caller-owned buffer outlives this blocking call.
+    let buf = unsafe { std::slice::from_raw_parts(buf, total) };
+    runtime.block_on(async move {
+        match run_with_cancel(
+            &close_token,
+            timeout_ms,
+            "failed to send udp data plane",
+            socket.send_to(buf, dst_addr),
+        )
+        .await
+        {
+            Some(Ok(n)) => n as std::ffi::c_int,
+            Some(Err(e)) => {
+                set_error_msg(&format!("failed to send udp data plane: {}", e));
+                -1
+            }
+            None => -1,
+        }
+    })
+}
+
+/// # Safety
+/// Receive a datagram from a UDP data-plane socket.
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) unsafe fn data_plane_udp_recv_from(
+    handle: u64,
+    buf: *mut std::ffi::c_uchar,
+    len: u32,
+    out_ip: *mut *const std::ffi::c_char,
+    out_port: *mut std::ffi::c_ushort,
+    timeout_ms: u64,
+) -> std::ffi::c_int {
+    let _data_plane_usage_guard = match enter_data_plane_operation() {
+        Some(guard) => guard,
+        None => return -1,
+    };
+    if buf.is_null() || out_ip.is_null() || out_port.is_null() {
+        set_error_msg("output pointer is null");
+        return -1;
+    }
+    let Some((socket, runtime, close_token)) = get_udp_socket(handle) else {
+        return -1;
+    };
+    let total = len as usize;
+    // Safety: caller-owned buffer outlives this blocking call.
+    let buf = unsafe { std::slice::from_raw_parts_mut(buf, total) };
+    let ret = runtime.block_on(run_with_cancel(
+        &close_token,
+        timeout_ms,
+        "udp data plane receive",
+        socket.recv_from(buf),
+    ));
+
+    match ret {
+        Some(Ok((n, addr))) => {
+            // The returned ip pointer must be released by the caller via
+            // `free_string` (which calls `CString::from_raw`, matching
+            // `CString::into_raw` here).
+            let Some(ip_cstr) = into_ffi_ip_cstring(addr.ip()) else {
+                return -1;
+            };
+            unsafe {
+                *out_ip = ip_cstr as *const std::ffi::c_char;
+                *out_port = addr.port() as std::ffi::c_ushort;
+            }
+            n as std::ffi::c_int
+        }
+        Some(Err(e)) => {
+            set_error_msg(&format!("failed to receive udp data plane: {}", e));
+            -1
+        }
+        None => -1,
+    }
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn data_plane_udp_close(handle: u64) -> std::ffi::c_int {
+    let _data_plane_usage_guard = match enter_data_plane_operation() {
+        Some(guard) => guard,
+        None => return -1,
+    };
+    crate::data_plane_async::cancel_ops_for_handle(handle);
+    let Some((_, h)) = DATA_PLANE_HANDLES.remove_if(&handle, |_, e| {
+        matches!(e.resource, DataPlaneResource::Udp(_))
+    }) else {
+        set_error_msg(if DATA_PLANE_HANDLES.contains_key(&handle) {
+            "handle is not a udp socket"
+        } else {
+            "udp socket handle not found"
+        });
+        return -1;
+    };
+    h.close_token.cancel();
+    0
+}
+
+#[cfg(all(test, feature = "ffi-dataplane"))]
+mod tests {
+    use super::*;
+    use std::{sync::mpsc, time::Duration};
+
+    #[test]
+    fn config_server_start_waits_for_data_plane_operation() {
+        let read_guard = DATA_PLANE_USAGE_LOCK.read().unwrap();
+        let (done_tx, done_rx) = mpsc::channel();
+        let waiter = std::thread::spawn(move || {
+            let _write_guard = lock_for_config_server_start().unwrap();
+            done_tx.send(()).unwrap();
+        });
+
+        assert!(done_rx.recv_timeout(Duration::from_millis(100)).is_err());
+        drop(read_guard);
+        done_rx.recv_timeout(Duration::from_secs(5)).unwrap();
+        waiter.join().unwrap();
+    }
+
+    #[test]
+    fn instance_cleanup_waits_for_data_plane_operation() {
+        let read_guard = DATA_PLANE_USAGE_LOCK.read().unwrap();
+        let instance_id = Uuid::new_v4();
+        let (done_tx, done_rx) = mpsc::channel();
+        let cleaner = std::thread::spawn(move || {
+            remove_data_plane_handles_by_instance_ids(&[instance_id]);
+            done_tx.send(()).unwrap();
+        });
+
+        assert!(done_rx.recv_timeout(Duration::from_millis(100)).is_err());
+        drop(read_guard);
+        done_rx.recv_timeout(Duration::from_secs(5)).unwrap();
+        cleaner.join().unwrap();
+    }
+}
@@ -0,0 +1,65 @@
+use std::{
+    cell::RefCell,
+    ffi::{CString, c_char},
+};
+
+thread_local! {
+    // # Thread Safety
+    // set_error_msg and get_error_msg must be called on the same thread to
+    // get correct error. And since `Handle::block_on` polls the top-level
+    // future on the calling thread, set_error_msg always runs on the same
+    // thread as the corresponding get_error_msg.
+    static ERROR_MSG: RefCell<Vec<u8>> = const { RefCell::new(Vec::new()) };
+}
+
+pub(crate) fn set_error_msg(msg: &str) {
+    ERROR_MSG.with(|cell| {
+        let mut buf = cell.borrow_mut();
+        buf.clear();
+        buf.extend_from_slice(msg.as_bytes());
+    });
+}
+
+fn thread_local_error_msg() -> Option<String> {
+    ERROR_MSG.with(|cell| {
+        let buf = cell.borrow();
+        if buf.is_empty() {
+            None
+        } else {
+            Some(String::from_utf8_lossy(&buf).into_owned())
+        }
+    })
+}
+
+pub(crate) unsafe fn get_error_msg(out: *mut *const c_char) {
+    let msg = match (
+        thread_local_error_msg(),
+        crate::config_server::last_callback_error(),
+    ) {
+        (Some(error), Some(callback_error)) => Some(format!(
+            "{}; config server callback error: {}",
+            error, callback_error
+        )),
+        (Some(error), None) => Some(error),
+        (None, Some(callback_error)) => {
+            Some(format!("config server callback error: {}", callback_error))
+        }
+        (None, None) => None,
+    };
+    let cstr = msg.and_then(|msg| CString::new(msg).ok());
+    unsafe {
+        *out = match cstr {
+            Some(s) => s.into_raw() as *const c_char,
+            None => std::ptr::null(),
+        };
+    }
+}
+
+pub(crate) fn free_string(s: *const c_char) {
+    if s.is_null() {
+        return;
+    }
+    unsafe {
+        let _ = CString::from_raw(s as *mut c_char);
+    }
+}
@@ -0,0 +1,366 @@
+use std::ffi::{CString, c_char, c_int};
+
+use easytier::common::config::{ConfigFileControl, ConfigLoader as _, TomlConfigLoader};
+
+use crate::{
+    config_server::{
+        in_config_server_callback, remove_config_server_tracked_instance_ids,
+        wait_for_config_server_delivery,
+    },
+    data_plane::remove_data_plane_handles_by_instance_ids,
+    error::set_error_msg,
+    state::{
+        INSTANCE_MANAGER, INSTANCE_MUTATION_LOCK, INSTANCE_NAME_ID_MAP, instance_name_exists,
+        lock_remote_instance_mutation,
+    },
+    types::KeyValuePair,
+};
+
+/// # Safety
+/// Set the tun fd
+pub(crate) unsafe fn set_tun_fd(inst_name: *const c_char, fd: c_int) -> c_int {
+    let inst_name = unsafe {
+        assert!(!inst_name.is_null());
+        std::ffi::CStr::from_ptr(inst_name)
+            .to_string_lossy()
+            .into_owned()
+    };
+    if !INSTANCE_NAME_ID_MAP.contains_key(&inst_name) {
+        return -1;
+    }
+
+    let inst_id = *INSTANCE_NAME_ID_MAP
+        .get(&inst_name)
+        .as_ref()
+        .unwrap()
+        .value();
+
+    match INSTANCE_MANAGER.set_tun_fd(&inst_id, fd) {
+        Ok(_) => 0,
+        Err(_) => -1,
+    }
+}
+
+/// # Safety
+/// Parse the config
+pub(crate) unsafe fn parse_config(cfg_str: *const std::ffi::c_char) -> std::ffi::c_int {
+    let cfg_str = unsafe {
+        assert!(!cfg_str.is_null());
+        std::ffi::CStr::from_ptr(cfg_str)
+            .to_string_lossy()
+            .into_owned()
+    };
+
+    if let Err(e) = TomlConfigLoader::new_from_str(&cfg_str) {
+        set_error_msg(&format!("failed to parse config: {:?}", e));
+        return -1;
+    }
+
+    0
+}
+
+/// # Safety
+/// Run the network instance
+pub(crate) unsafe fn run_network_instance(cfg_str: *const std::ffi::c_char) -> std::ffi::c_int {
+    if in_config_server_callback() {
+        set_error_msg("cannot run network instance from config server callback");
+        return -1;
+    }
+
+    let cfg_str = unsafe {
+        assert!(!cfg_str.is_null());
+        std::ffi::CStr::from_ptr(cfg_str)
+            .to_string_lossy()
+            .into_owned()
+    };
+    let cfg = match TomlConfigLoader::new_from_str(&cfg_str) {
+        Ok(cfg) => cfg,
+        Err(e) => {
+            set_error_msg(&format!("failed to parse config: {}", e));
+            return -1;
+        }
+    };
+
+    let inst_name = cfg.get_inst_name();
+
+    wait_for_config_server_delivery();
+    let _remote_mutation_guard = lock_remote_instance_mutation();
+    let _mutation_guard = match INSTANCE_MUTATION_LOCK.lock() {
+        Ok(guard) => guard,
+        Err(err) => {
+            set_error_msg(&format!("failed to lock instance mutation: {}", err));
+            return -1;
+        }
+    };
+
+    if instance_name_exists(&inst_name) {
+        set_error_msg("instance already exists");
+        return -1;
+    }
+
+    let instance_id =
+        match INSTANCE_MANAGER.run_network_instance(cfg, false, ConfigFileControl::STATIC_CONFIG) {
+            Ok(id) => id,
+            Err(e) => {
+                set_error_msg(&format!("failed to start instance: {}", e));
+                return -1;
+            }
+        };
+
+    INSTANCE_NAME_ID_MAP.insert(inst_name, instance_id);
+
+    0
+}
+
+unsafe fn parse_instance_names(
+    inst_names: *const *const c_char,
+    length: usize,
+) -> Option<Vec<String>> {
+    if length == 0 {
+        return Some(Vec::new());
+    }
+    if inst_names.is_null() {
+        set_error_msg("inst_names is null");
+        return None;
+    }
+
+    let names = unsafe { std::slice::from_raw_parts(inst_names, length) };
+    let mut parsed = Vec::with_capacity(length);
+    for (index, &name) in names.iter().enumerate() {
+        if name.is_null() {
+            set_error_msg(&format!("inst_names[{}] is null", index));
+            return None;
+        }
+        parsed.push(
+            unsafe { std::ffi::CStr::from_ptr(name) }
+                .to_string_lossy()
+                .into_owned(),
+        );
+    }
+    Some(parsed)
+}
+
+/// # Safety
+/// Retain the network instance
+pub(crate) unsafe fn retain_network_instance(
+    inst_names: *const *const std::ffi::c_char,
+    length: usize,
+) -> std::ffi::c_int {
+    if in_config_server_callback() {
+        set_error_msg("cannot retain network instances from config server callback");
+        return -1;
+    }
+
+    wait_for_config_server_delivery();
+    let _remote_mutation_guard = lock_remote_instance_mutation();
+    let _mutation_guard = match INSTANCE_MUTATION_LOCK.lock() {
+        Ok(guard) => guard,
+        Err(err) => {
+            set_error_msg(&format!("failed to lock instance mutation: {}", err));
+            return -1;
+        }
+    };
+
+    if length == 0 {
+        let removed_ids = INSTANCE_MANAGER.list_network_instance_ids();
+        if let Err(e) = INSTANCE_MANAGER.delete_network_instance(removed_ids.clone()) {
+            set_error_msg(&format!("failed to delete instances: {}", e));
+            return -1;
+        }
+        remove_config_server_tracked_instance_ids(&removed_ids);
+        remove_data_plane_handles_by_instance_ids(&removed_ids);
+        INSTANCE_NAME_ID_MAP.clear();
+        return 0;
+    }
+
+    let Some(inst_names) = (unsafe { parse_instance_names(inst_names, length) }) else {
+        return -1;
+    };
+
+    let removed_ids = INSTANCE_MANAGER
+        .list_network_instance_ids()
+        .into_iter()
+        .filter(|id| {
+            INSTANCE_MANAGER
+                .get_instance_name(id)
+                .is_none_or(|name| !inst_names.contains(&name))
+        })
+        .collect::<Vec<_>>();
+
+    if let Err(e) = INSTANCE_MANAGER.delete_network_instance(removed_ids.clone()) {
+        set_error_msg(&format!("failed to delete instances: {}", e));
+        return -1;
+    }
+
+    remove_config_server_tracked_instance_ids(&removed_ids);
+    remove_data_plane_handles_by_instance_ids(&removed_ids);
+    INSTANCE_NAME_ID_MAP.retain(|k, _| inst_names.contains(k));
+
+    0
+}
+
+/// # Safety
+/// Delete named network instances.
+pub(crate) unsafe fn delete_network_instance(
+    inst_names: *const *const std::ffi::c_char,
+    length: usize,
+) -> std::ffi::c_int {
+    if in_config_server_callback() {
+        set_error_msg("cannot delete network instances from config server callback");
+        return -1;
+    }
+
+    wait_for_config_server_delivery();
+    let _remote_mutation_guard = lock_remote_instance_mutation();
+    let _mutation_guard = match INSTANCE_MUTATION_LOCK.lock() {
+        Ok(guard) => guard,
+        Err(err) => {
+            set_error_msg(&format!("failed to lock instance mutation: {}", err));
+            return -1;
+        }
+    };
+
+    if length == 0 {
+        return 0;
+    }
+
+    let Some(inst_names) = (unsafe { parse_instance_names(inst_names, length) }) else {
+        return -1;
+    };
+
+    let removed_ids = inst_names
+        .iter()
+        .filter_map(|name| INSTANCE_NAME_ID_MAP.get(name).map(|id| *id.value()))
+        .collect::<Vec<_>>();
+
+    if let Err(e) = INSTANCE_MANAGER.delete_network_instance(removed_ids.clone()) {
+        set_error_msg(&format!("failed to delete instances: {}", e));
+        return -1;
+    }
+
+    remove_config_server_tracked_instance_ids(&removed_ids);
+    remove_data_plane_handles_by_instance_ids(&removed_ids);
+    for name in inst_names {
+        INSTANCE_NAME_ID_MAP.remove(&name);
+    }
+
+    0
+}
+
+/// # Safety
+/// Collect the network infos
+pub(crate) unsafe fn collect_network_infos(
+    infos: *mut KeyValuePair,
+    max_length: usize,
+) -> std::ffi::c_int {
+    if in_config_server_callback() {
+        set_error_msg("cannot collect network infos from config server callback");
+        return -1;
+    }
+
+    if max_length == 0 {
+        return 0;
+    }
+
+    let infos = unsafe {
+        assert!(!infos.is_null());
+        std::slice::from_raw_parts_mut(infos, max_length)
+    };
+
+    let collected_infos = match INSTANCE_MANAGER.collect_network_infos_sync() {
+        Ok(infos) => infos,
+        Err(e) => {
+            set_error_msg(&format!("failed to collect network infos: {}", e));
+            return -1;
+        }
+    };
+
+    let mut index = 0;
+    for (instance_id, value) in collected_infos.iter() {
+        if index >= max_length {
+            break;
+        }
+        let Some(key) = INSTANCE_MANAGER.get_instance_name(instance_id) else {
+            continue;
+        };
+        // convert value to json string
+        let value = match serde_json::to_string(&value) {
+            Ok(value) => value,
+            Err(e) => {
+                set_error_msg(&format!("failed to serialize instance info: {}", e));
+                return -1;
+            }
+        };
+
+        infos[index] = KeyValuePair {
+            key: std::ffi::CString::new(key).unwrap().into_raw(),
+            value: std::ffi::CString::new(value).unwrap().into_raw(),
+        };
+        index += 1;
+    }
+
+    index as std::ffi::c_int
+}
+
+/// # Safety
+/// List the instance names and IDs known by the FFI instance manager.
+pub(crate) unsafe fn list_instance(infos: *mut KeyValuePair, max_length: usize) -> std::ffi::c_int {
+    if in_config_server_callback() {
+        set_error_msg("cannot list instances from config server callback");
+        return -1;
+    }
+
+    if max_length == 0 {
+        return 0;
+    }
+
+    if infos.is_null() {
+        set_error_msg("infos is null");
+        return -1;
+    }
+
+    let infos = unsafe { std::slice::from_raw_parts_mut(infos, max_length) };
+    let mut instances = INSTANCE_MANAGER
+        .list_network_instance_ids()
+        .into_iter()
+        .filter_map(|id| {
+            INSTANCE_MANAGER
+                .get_instance_name(&id)
+                .map(|name| (name, id))
+        })
+        .collect::<Vec<_>>();
+    instances.sort_by(|(left_name, left_id), (right_name, right_id)| {
+        left_name
+            .cmp(right_name)
+            .then_with(|| left_id.to_string().cmp(&right_id.to_string()))
+    });
+
+    let encoded_instances = match instances
+        .into_iter()
+        .take(max_length)
+        .map(|(name, id)| {
+            let key = CString::new(name)
+                .map_err(|err| format!("failed to encode instance name: {}", err))?;
+            let value = CString::new(id.to_string())
+                .map_err(|err| format!("failed to encode instance id: {}", err))?;
+            Ok((key, value))
+        })
+        .collect::<Result<Vec<_>, String>>()
+    {
+        Ok(value) => value,
+        Err(err) => {
+            set_error_msg(&err);
+            return -1;
+        }
+    };
+
+    let count = encoded_instances.len();
+    for (index, (key, value)) in encoded_instances.into_iter().enumerate() {
+        infos[index] = KeyValuePair {
+            key: key.into_raw(),
+            value: value.into_raw(),
+        };
+    }
+
+    count as std::ffi::c_int
+}
@@ -0,0 +1,100 @@
+use std::ffi::{CString, c_char, c_int};
+
+use crate::{
+    config_server::in_config_server_callback,
+    error::set_error_msg,
+    state::{ASYNC_RUNTIME, INSTANCE_MANAGER},
+    strings::{c_str_to_string, optional_c_str_to_string},
+};
+
+/// # Safety
+/// See `crate::call_json_rpc`.
+pub(crate) unsafe fn call_json_rpc(
+    service_name: *const c_char,
+    method_name: *const c_char,
+    domain_name: *const c_char,
+    payload_json: *const c_char,
+    out_response_json: *mut *const c_char,
+) -> c_int {
+    if out_response_json.is_null() {
+        set_error_msg("out_response_json is null");
+        return -1;
+    }
+    unsafe {
+        *out_response_json = std::ptr::null();
+    }
+
+    if in_config_server_callback() {
+        set_error_msg("cannot call JSON RPC from config server callback");
+        return -1;
+    }
+
+    let service_name = match unsafe { c_str_to_string(service_name, "service_name") } {
+        Ok(value) => value,
+        Err(err) => {
+            set_error_msg(&err);
+            return -1;
+        }
+    };
+    let method_name = match unsafe { c_str_to_string(method_name, "method_name") } {
+        Ok(value) => value,
+        Err(err) => {
+            set_error_msg(&err);
+            return -1;
+        }
+    };
+    let domain_name = match unsafe { optional_c_str_to_string(domain_name, "domain_name") } {
+        Ok(value) => value,
+        Err(err) => {
+            set_error_msg(&err);
+            return -1;
+        }
+    };
+    let payload_json = match unsafe { c_str_to_string(payload_json, "payload_json") } {
+        Ok(value) => value,
+        Err(err) => {
+            set_error_msg(&err);
+            return -1;
+        }
+    };
+    let payload = match serde_json::from_str::<serde_json::Value>(&payload_json) {
+        Ok(value) => value,
+        Err(err) => {
+            set_error_msg(&format!("failed to parse payload_json: {}", err));
+            return -1;
+        }
+    };
+
+    let response = match ASYNC_RUNTIME.block_on(easytier::rpc_service::call_json_rpc(
+        &INSTANCE_MANAGER,
+        &service_name,
+        &method_name,
+        domain_name.as_deref(),
+        payload,
+    )) {
+        Ok(value) => value,
+        Err(err) => {
+            set_error_msg(&format!("RPC Error: {}", err));
+            return -1;
+        }
+    };
+    let response_json = match serde_json::to_string(&response) {
+        Ok(value) => value,
+        Err(err) => {
+            set_error_msg(&format!("failed to serialize RPC response: {}", err));
+            return -1;
+        }
+    };
+    let response_json = match CString::new(response_json) {
+        Ok(value) => value,
+        Err(err) => {
+            set_error_msg(&format!("failed to allocate RPC response: {}", err));
+            return -1;
+        }
+    };
+
+    unsafe {
+        *out_response_json = response_json.into_raw();
+    }
+    0
+}
@@ -0,0 +1,974 @@
+//! C ABI facade for EasyTier.
+//!
+//! The exported API is intentionally kept in this file so C users and JNI
+//! bindings can see the full callable surface without reading the internal
+//! implementation modules.
+//!
+//! Network management APIs:
+//! - `parse_config`: validate a TOML network config string.
+//! - `run_network_instance`: start one local network instance from TOML.
+//! - `retain_network_instance`: keep named instances and stop all others.
+//! - `delete_network_instance`: stop named local network instances.
+//! - `list_instance`: list running instance names and IDs.
+//! - `collect_network_infos`: collect running instance info as key/value pairs.
+//! - `set_tun_fd`: attach a TUN file descriptor to a named instance.
+//! - `call_json_rpc`: call an exposed EasyTier RPC service with JSON payload.
+//!
+//! Config server client APIs:
+//! - `start_config_server_client`: start the managed remote config client.
+//! - `stop_config_server_client`: stop the remote config client and its managed instances.
+//! - `is_config_server_client_connected`: report whether the client is connected.
+//!
+//! Data plane APIs, enabled by the `ffi-dataplane` feature:
+//! - `data_plane_tcp_connect`: open an outbound TCP data-plane stream.
+//! - `data_plane_tcp_bind`: bind a TCP data-plane listener.
+//! - `data_plane_tcp_accept`: accept a TCP data-plane connection.
+//! - `data_plane_tcp_read`: read from a TCP data-plane stream.
+//! - `data_plane_tcp_write`: write to a TCP data-plane stream.
+//! - `data_plane_tcp_close`: close a TCP data-plane stream.
+//! - `data_plane_tcp_listener_close`: close a TCP data-plane listener.
+//! - `data_plane_udp_bind`: bind a UDP data-plane socket.
+//! - `data_plane_udp_send_to`: send one UDP data-plane datagram.
+//! - `data_plane_udp_recv_from`: receive one UDP data-plane datagram.
+//! - `data_plane_udp_close`: close a UDP data-plane socket.
+//! - `data_plane_*_start` / `data_plane_*_finish`: asynchronous data-plane operations.
+//! - `data_plane_async_op_*`: poll, wait, cancel, and free asynchronous operations.
+//!
+//! Shared FFI helper APIs:
+//! - `get_error_msg`: copy the last FFI or config-server callback error message.
+//! - `free_string`: release strings allocated by this library.
+
+mod config_server;
+mod data_plane;
+#[cfg(feature = "ffi-dataplane")]
+mod data_plane_async;
+mod error;
+mod instance_api;
+mod json_rpc;
+mod state;
+mod strings;
+mod types;
+
+#[cfg(test)]
+mod tests;
+
+pub use config_server::{in_config_server_callback, validate_config_server_client_options};
+pub use types::{ConfigServerEventCallback, KeyValuePair};
+
+use std::ffi::{c_char, c_int, c_void};
+#[cfg(feature = "ffi-dataplane")]
+use std::ffi::{c_uchar, c_ushort};
+
+// ===== Network Management API =====
+
+/// Validate a TOML network config string.
+///
+/// This only parses and validates the config. It does not start an instance and
+/// does not change global FFI state.
+///
+/// # Safety
+/// `cfg_str` must be a non-null pointer to a null-terminated UTF-8 string.
+///
+/// # Return
+/// Returns `0` if the config parses successfully, or `-1` on failure. On
+/// failure, call `get_error_msg` on the same thread to retrieve details.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn parse_config(cfg_str: *const c_char) -> c_int {
+    unsafe { instance_api::parse_config(cfg_str) }
+}
+
+/// Start one local EasyTier network instance from a TOML config string.
+///
+/// The config's `inst_name` must be unique among instances started through this
+/// FFI layer. This API is mutually exclusive with config-server callback
+/// execution and will fail if called from a config-server event callback.
+///
+/// # Safety
+/// `cfg_str` must be a non-null pointer to a null-terminated UTF-8 string.
+///
+/// # Return
+/// Returns `0` after the instance is started and registered in the FFI name
+/// cache, or `-1` on failure. On failure, call `get_error_msg` on the same
+/// thread to retrieve details.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn run_network_instance(cfg_str: *const c_char) -> c_int {
+    unsafe { instance_api::run_network_instance(cfg_str) }
+}
+
+/// Keep the named network instances and stop all other instances.
+///
+/// Passing `length == 0` stops all instances. When `length > 0`, `inst_names`
+/// must point to an array of `length` non-null C strings. Instances that are not
+/// retained are removed from the FFI name cache and any related data-plane
+/// handles are closed.
+///
+/// This API fails if called from a config-server event callback.
+///
+/// # Safety
+/// If `length > 0`, `inst_names` must be a non-null pointer to an array of
+/// `length` non-null pointers to null-terminated UTF-8 strings.
+///
+/// # Return
+/// Returns `0` on success, or `-1` on failure. On failure, call
+/// `get_error_msg` on the same thread to retrieve details.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn retain_network_instance(
+    inst_names: *const *const c_char,
+    length: usize,
+) -> c_int {
+    unsafe { instance_api::retain_network_instance(inst_names, length) }
+}
+
+/// Stop the named network instances.
+///
+/// Passing `length == 0` is a no-op. When `length > 0`, `inst_names` must point
+/// to an array of `length` non-null C strings. Unknown names are ignored.
+/// Removed instances are also removed from the FFI name cache and any related
+/// data-plane handles are closed.
+///
+/// This API fails if called from a config-server event callback.
+///
+/// # Safety
+/// If `length > 0`, `inst_names` must be a non-null pointer to an array of
+/// `length` non-null pointers to null-terminated UTF-8 strings.
+///
+/// # Return
+/// Returns `0` on success, or `-1` on failure. On failure, call
+/// `get_error_msg` on the same thread to retrieve details.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn delete_network_instance(
+    inst_names: *const *const c_char,
+    length: usize,
+) -> c_int {
+    unsafe { instance_api::delete_network_instance(inst_names, length) }
+}
+
+/// List running network instance names and IDs.
+///
+/// Writes up to `max_length` entries into `infos`. Each returned key is the
+/// instance name and each returned value is the instance ID string. Returned
+/// key/value strings are allocated by this library and must be released with
+/// `free_string`.
+///
+/// This API fails if called from a config-server event callback.
+///
+/// # Safety
+/// If `max_length > 0`, `infos` must be a non-null pointer to writable storage
+/// for at least `max_length` `KeyValuePair` values.
+///
+/// # Return
+/// Returns the number of entries written, or `-1` on failure. On failure, call
+/// `get_error_msg` on the same thread to retrieve details.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn list_instance(infos: *mut KeyValuePair, max_length: usize) -> c_int {
+    unsafe { instance_api::list_instance(infos, max_length) }
+}
+
+/// Collect running network instance information.
+///
+/// Writes up to `max_length` entries into `infos`. Each returned key is the
+/// instance name and each returned value is a JSON string containing that
+/// instance's running information. Returned key/value strings are allocated by
+/// this library and must be released with `free_string`.
+///
+/// This API fails if called from a config-server event callback.
+///
+/// # Safety
+/// If `max_length > 0`, `infos` must be a non-null pointer to writable storage
+/// for at least `max_length` `KeyValuePair` values.
+///
+/// # Return
+/// Returns the number of entries written, or `-1` on failure. On failure, call
+/// `get_error_msg` on the same thread to retrieve details.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn collect_network_infos(
+    infos: *mut KeyValuePair,
+    max_length: usize,
+) -> c_int {
+    unsafe { instance_api::collect_network_infos(infos, max_length) }
+}
+
+/// Attach a TUN file descriptor to a named network instance.
+///
+/// The instance must already have been registered in the FFI name cache by
+/// `run_network_instance` or by a managed config-server remote start event.
+///
+/// # Safety
+/// `inst_name` must be a non-null pointer to a null-terminated UTF-8 string.
+/// `fd` must be a valid TUN file descriptor owned by the caller.
+///
+/// # Return
+/// Returns `0` if the descriptor is accepted by the instance, or `-1` on
+/// failure.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn set_tun_fd(inst_name: *const c_char, fd: c_int) -> c_int {
+    unsafe { instance_api::set_tun_fd(inst_name, fd) }
+}
+
+/// Call an exposed EasyTier RPC method using protobuf JSON.
+///
+/// This generic bridge intentionally excludes instance lifecycle management
+/// RPCs. Use the dedicated FFI APIs for starting, retaining, deleting, and
+/// collecting instances. `payload_json` must contain the protobuf JSON request,
+/// including any `instance` selector required by the target RPC.
+///
+/// `domain_name` may be null or empty. It is only used by
+/// `api.instance.TcpProxyRpcService`; null or empty defaults to `tcp`, and the
+/// only accepted explicit values are `tcp`, `kcp_src`, `kcp_dst`, `quic_src`,
+/// and `quic_dst`.
+///
+/// On success, writes a newly allocated JSON response string to
+/// `out_response_json`. The caller must release it with `free_string`.
+///
+/// This API fails if called from a config-server event callback.
+///
+/// # Safety
+/// `service_name`, `method_name`, `payload_json`, and `out_response_json` must
+/// be non-null. String pointers must point to null-terminated UTF-8 strings.
+/// `domain_name` may be null.
+///
+/// # Return
+/// Returns `0` on success, or `-1` on failure. On failure, call
+/// `get_error_msg` on the same thread to retrieve details.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn call_json_rpc(
+    service_name: *const c_char,
+    method_name: *const c_char,
+    domain_name: *const c_char,
+    payload_json: *const c_char,
+    out_response_json: *mut *const c_char,
+) -> c_int {
+    unsafe {
+        json_rpc::call_json_rpc(
+            service_name,
+            method_name,
+            domain_name,
+            payload_json,
+            out_response_json,
+        )
+    }
+}
+
+// ===== Config Server Client API =====
+
+/// Start the managed config-server client.
+///
+/// The client reuses EasyTier's web-client path and applies remote config
+/// changes through the shared `NetworkInstanceManager`. Successful remote run
+/// and delete operations are delivered to `callback` as JSON event strings, one
+/// callback per affected instance. The event string is valid only for the
+/// duration of the callback; callers must copy it if they need to keep it.
+///
+/// The config-server client is mutually exclusive with the FFI data plane. If a
+/// data-plane handle exists or is being created, this function returns `-1`.
+///
+/// # Safety
+/// `config_server_url` and `machine_id` must be non-null pointers to
+/// null-terminated UTF-8 strings. `hostname` may be null; when non-null it must
+/// also point to a null-terminated UTF-8 string. `user_data` is passed back to
+/// `callback` unchanged and must remain valid for the callback's expectations.
+///
+/// # Return
+/// Returns `0` after the client starts successfully, or `-1` on failure. On
+/// failure, call `get_error_msg` on the same thread to retrieve details.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn start_config_server_client(
+    config_server_url: *const c_char,
+    hostname: *const c_char,
+    machine_id: *const c_char,
+    secure_mode: bool,
+    callback: ConfigServerEventCallback,
+    user_data: *mut c_void,
+) -> c_int {
+    unsafe {
+        config_server::start_config_server_client(
+            config_server_url,
+            hostname,
+            machine_id,
+            secure_mode,
+            callback,
+            user_data,
+        )
+    }
+}
+
+/// Stop the managed config-server client.
+///
+/// This stops the client, removes instances tracked as remote config-server
+/// instances, waits for in-flight callback delivery when safe to do so, and
+/// releases the config-server/data-plane mutual exclusion state.
+///
+/// # Return
+/// Returns `0` if no client exists or if the active client is stopped
+/// successfully. Returns `-1` on failure. On failure, call `get_error_msg` on
+/// the same thread to retrieve details.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub extern "C" fn stop_config_server_client() -> c_int {
+    config_server::stop_config_server_client()
+}
+
+/// Report whether the managed config-server client is currently connected.
+///
+/// # Return
+/// Returns `1` when a client exists and reports connected, otherwise returns
+/// `0`.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub extern "C" fn is_config_server_client_connected() -> c_int {
+    config_server::is_config_server_client_connected()
+}
+
+// ===== Data Plane API =====
+
+/// Open an outbound TCP stream through an EasyTier instance data plane.
+///
+/// On success, writes the local address selected for the connection into
+/// `out_local_ip` and `out_local_port`. The returned IP string is allocated by
+/// this library and must be released with `free_string`.
+///
+/// The data plane is mutually exclusive with the config-server client. This
+/// function returns `0` if the config-server client is active or stopping.
+///
+/// # Safety
+/// `inst_name`, `dst_ip`, `out_local_ip`, and `out_local_port` must be non-null.
+/// String pointers must point to null-terminated UTF-8 strings.
+///
+/// # Return
+/// Returns a non-zero TCP stream handle on success, or `0` on failure. On
+/// failure, call `get_error_msg` on the same thread to retrieve details.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_connect(
+    inst_name: *const c_char,
+    dst_ip: *const c_char,
+    dst_port: c_ushort,
+    timeout_ms: u64,
+    out_local_ip: *mut *const c_char,
+    out_local_port: *mut c_ushort,
+) -> u64 {
+    unsafe {
+        data_plane::data_plane_tcp_connect(
+            inst_name,
+            dst_ip,
+            dst_port,
+            timeout_ms,
+            out_local_ip,
+            out_local_port,
+        )
+    }
+}
+
+/// Bind a TCP listener through an EasyTier instance data plane.
+///
+/// On success, writes the bound local address into `out_local_ip` and
+/// `out_local_port`. The returned IP string is allocated by this library and
+/// must be released with `free_string`.
+///
+/// # Safety
+/// `inst_name`, `out_local_ip`, and `out_local_port` must be non-null.
+/// `inst_name` must point to a null-terminated UTF-8 string.
+///
+/// # Return
+/// Returns a non-zero TCP listener handle on success, or `0` on failure. On
+/// failure, call `get_error_msg` on the same thread to retrieve details.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_bind(
+    inst_name: *const c_char,
+    local_port: c_ushort,
+    timeout_ms: u64,
+    out_local_ip: *mut *const c_char,
+    out_local_port: *mut c_ushort,
+) -> u64 {
+    unsafe {
+        data_plane::data_plane_tcp_bind(
+            inst_name,
+            local_port,
+            timeout_ms,
+            out_local_ip,
+            out_local_port,
+        )
+    }
+}
+
+/// Accept one connection from a TCP data-plane listener.
+///
+/// On success, writes both local and peer socket addresses to the output
+/// pointers. Returned IP strings are allocated by this library and must be
+/// released with `free_string`.
+///
+/// # Safety
+/// All output pointers must be non-null and writable. `handle` must be a valid
+/// TCP listener handle returned by `data_plane_tcp_bind`.
+///
+/// # Return
+/// Returns a non-zero TCP stream handle on success, or `0` on failure. On
+/// failure, call `get_error_msg` on the same thread to retrieve details.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_accept(
+    handle: u64,
+    timeout_ms: u64,
+    out_local_ip: *mut *const c_char,
+    out_local_port: *mut c_ushort,
+    out_peer_ip: *mut *const c_char,
+    out_peer_port: *mut c_ushort,
+) -> u64 {
+    unsafe {
+        data_plane::data_plane_tcp_accept(
+            handle,
+            timeout_ms,
+            out_local_ip,
+            out_local_port,
+            out_peer_ip,
+            out_peer_port,
+        )
+    }
+}
+
+/// Read bytes from a TCP data-plane stream.
+///
+/// # Safety
+/// `handle` must be a valid TCP stream handle returned by
+/// `data_plane_tcp_connect` or `data_plane_tcp_accept`. `buf` must be non-null
+/// and writable for `len` bytes.
+///
+/// # Return
+/// Returns the number of bytes read, or `-1` on failure. On failure, call
+/// `get_error_msg` on the same thread to retrieve details.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_read(
+    handle: u64,
+    buf: *mut c_uchar,
+    len: u32,
+    timeout_ms: u64,
+) -> c_int {
+    unsafe { data_plane::data_plane_tcp_read(handle, buf, len, timeout_ms) }
+}
+
+/// Write bytes to a TCP data-plane stream.
+///
+/// This function attempts to write exactly `len` bytes before returning
+/// success.
+///
+/// # Safety
+/// `handle` must be a valid TCP stream handle returned by
+/// `data_plane_tcp_connect` or `data_plane_tcp_accept`. `buf` must be non-null
+/// and readable for `len` bytes.
+///
+/// # Return
+/// Returns `len` on success, or `-1` on failure. On failure, call
+/// `get_error_msg` on the same thread to retrieve details.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_write(
+    handle: u64,
+    buf: *const c_uchar,
+    len: u32,
+    timeout_ms: u64,
+) -> c_int {
+    unsafe { data_plane::data_plane_tcp_write(handle, buf, len, timeout_ms) }
+}
+
+/// Close a TCP data-plane stream handle.
+///
+/// # Return
+/// Returns `0` on success, or `-1` if the handle is missing, is not a TCP stream
+/// handle, or data-plane calls are currently rejected.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub extern "C" fn data_plane_tcp_close(handle: u64) -> c_int {
+    data_plane::data_plane_tcp_close(handle)
+}
+
+/// Close a TCP data-plane listener handle.
+///
+/// # Return
+/// Returns `0` on success, or `-1` if the handle is missing, is not a TCP
+/// listener handle, or data-plane calls are currently rejected.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub extern "C" fn data_plane_tcp_listener_close(handle: u64) -> c_int {
+    data_plane::data_plane_tcp_listener_close(handle)
+}
+
+/// Bind a UDP socket through an EasyTier instance data plane.
+///
+/// On success, writes the bound local address into `out_local_ip` and
+/// `out_local_port`. The returned IP string is allocated by this library and
+/// must be released with `free_string`.
+///
+/// # Safety
+/// `inst_name`, `out_local_ip`, and `out_local_port` must be non-null.
+/// `inst_name` must point to a null-terminated UTF-8 string.
+///
+/// # Return
+/// Returns a non-zero UDP socket handle on success, or `0` on failure. On
+/// failure, call `get_error_msg` on the same thread to retrieve details.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_udp_bind(
+    inst_name: *const c_char,
+    local_port: c_ushort,
+    timeout_ms: u64,
+    out_local_ip: *mut *const c_char,
+    out_local_port: *mut c_ushort,
+) -> u64 {
+    unsafe {
+        data_plane::data_plane_udp_bind(
+            inst_name,
+            local_port,
+            timeout_ms,
+            out_local_ip,
+            out_local_port,
+        )
+    }
+}
+
+/// Send one UDP datagram through a data-plane socket.
+///
+/// # Safety
+/// `handle` must be a valid UDP socket handle returned by
+/// `data_plane_udp_bind`. `dst_ip` must be non-null and point to a
+/// null-terminated UTF-8 string. `buf` must be non-null and readable for `len`
+/// bytes.
+///
+/// # Return
+/// Returns the number of bytes sent, or `-1` on failure. On failure, call
+/// `get_error_msg` on the same thread to retrieve details.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_udp_send_to(
+    handle: u64,
+    dst_ip: *const c_char,
+    dst_port: c_ushort,
+    buf: *const c_uchar,
+    len: u32,
+    timeout_ms: u64,
+) -> c_int {
+    unsafe { data_plane::data_plane_udp_send_to(handle, dst_ip, dst_port, buf, len, timeout_ms) }
+}
+
+/// Receive one UDP datagram from a data-plane socket.
+///
+/// On success, writes the peer address into `out_ip` and `out_port`. The
+/// returned IP string is allocated by this library and must be released with
+/// `free_string`.
+///
+/// # Safety
+/// `handle` must be a valid UDP socket handle returned by
+/// `data_plane_udp_bind`. `buf`, `out_ip`, and `out_port` must be non-null.
+/// `buf` must be writable for `len` bytes.
+///
+/// # Return
+/// Returns the number of bytes received, or `-1` on failure. On failure, call
+/// `get_error_msg` on the same thread to retrieve details.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_udp_recv_from(
+    handle: u64,
+    buf: *mut c_uchar,
+    len: u32,
+    out_ip: *mut *const c_char,
+    out_port: *mut c_ushort,
+    timeout_ms: u64,
+) -> c_int {
+    unsafe { data_plane::data_plane_udp_recv_from(handle, buf, len, out_ip, out_port, timeout_ms) }
+}
+
+/// Close a UDP data-plane socket handle.
+///
+/// # Return
+/// Returns `0` on success, or `-1` if the handle is missing, is not a UDP
+/// socket handle, or data-plane calls are currently rejected.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub extern "C" fn data_plane_udp_close(handle: u64) -> c_int {
+    data_plane::data_plane_udp_close(handle)
+}
+
+// ===== Async Data Plane API =====
+
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub extern "C" fn data_plane_async_op_status(handle: u64) -> c_int {
+    data_plane_async::data_plane_async_op_status(handle)
+}
+
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub extern "C" fn data_plane_async_op_wait(handle: u64, timeout_ms: u64) -> c_int {
+    data_plane_async::data_plane_async_op_wait(handle, timeout_ms)
+}
+
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub extern "C" fn data_plane_async_op_cancel(handle: u64) -> c_int {
+    data_plane_async::data_plane_async_op_cancel(handle)
+}
+
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub extern "C" fn data_plane_async_op_free(handle: u64) -> c_int {
+    data_plane_async::data_plane_async_op_free(handle)
+}
+
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub extern "C" fn data_plane_free_bytes(ptr: *const c_uchar, len: u32) {
+    data_plane_async::data_plane_free_bytes(ptr, len)
+}
+
+/// Start an asynchronous TCP data-plane connection.
+///
+/// # Safety
+/// `inst_name` and `dst_ip` must be non-null pointers to null-terminated UTF-8
+/// strings. The strings only need to remain valid for the duration of this
+/// call.
+///
+/// # Return
+/// Returns a non-zero async operation handle on success, or `0` on failure.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_connect_start(
+    inst_name: *const c_char,
+    dst_ip: *const c_char,
+    dst_port: c_ushort,
+    timeout_ms: u64,
+) -> u64 {
+    unsafe {
+        data_plane_async::data_plane_tcp_connect_start(inst_name, dst_ip, dst_port, timeout_ms)
+    }
+}
+
+/// Finish an asynchronous TCP data-plane connection.
+///
+/// On success, writes the stream local address into `out_local_ip` and
+/// `out_local_port`. The returned IP string is allocated by this library and
+/// must be released with `free_string`.
+///
+/// # Safety
+/// `out_local_ip` and `out_local_port` must be non-null pointers to writable
+/// storage.
+///
+/// # Return
+/// Returns a non-zero TCP stream handle on success, or `0` on failure.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_connect_finish(
+    op_handle: u64,
+    out_local_ip: *mut *const c_char,
+    out_local_port: *mut c_ushort,
+) -> u64 {
+    unsafe {
+        data_plane_async::data_plane_tcp_connect_finish(op_handle, out_local_ip, out_local_port)
+    }
+}
+
+/// Start an asynchronous TCP data-plane bind.
+///
+/// # Safety
+/// `inst_name` must be a non-null pointer to a null-terminated UTF-8 string.
+/// The string only needs to remain valid for the duration of this call.
+///
+/// # Return
+/// Returns a non-zero async operation handle on success, or `0` on failure.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_bind_start(
+    inst_name: *const c_char,
+    local_port: c_ushort,
+    timeout_ms: u64,
+) -> u64 {
+    unsafe { data_plane_async::data_plane_tcp_bind_start(inst_name, local_port, timeout_ms) }
+}
+
+/// Finish an asynchronous TCP data-plane bind.
+///
+/// On success, writes the listener local address into `out_local_ip` and
+/// `out_local_port`. The returned IP string is allocated by this library and
+/// must be released with `free_string`.
+///
+/// # Safety
+/// `out_local_ip` and `out_local_port` must be non-null pointers to writable
+/// storage.
+///
+/// # Return
+/// Returns a non-zero TCP listener handle on success, or `0` on failure.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_bind_finish(
+    op_handle: u64,
+    out_local_ip: *mut *const c_char,
+    out_local_port: *mut c_ushort,
+) -> u64 {
+    unsafe { data_plane_async::data_plane_tcp_bind_finish(op_handle, out_local_ip, out_local_port) }
+}
+
+/// Start an asynchronous TCP data-plane accept on a listener handle.
+///
+/// # Safety
+/// `handle` must be a valid TCP listener handle returned by
+/// `data_plane_tcp_bind` or `data_plane_tcp_bind_finish`.
+///
+/// # Return
+/// Returns a non-zero async operation handle on success, or `0` on failure.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_accept_start(handle: u64, timeout_ms: u64) -> u64 {
+    unsafe { data_plane_async::data_plane_tcp_accept_start(handle, timeout_ms) }
+}
+
+/// Finish an asynchronous TCP data-plane accept.
+///
+/// On success, writes the accepted stream local address into `out_local_ip` and
+/// `out_local_port`, and the peer address into `out_peer_ip` and
+/// `out_peer_port`. Returned IP strings are allocated by this library and must
+/// be released with `free_string`.
+///
+/// # Safety
+/// `out_local_ip`, `out_local_port`, `out_peer_ip`, and `out_peer_port` must be
+/// non-null pointers to writable storage.
+///
+/// # Return
+/// Returns a non-zero TCP stream handle on success, or `0` on failure.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_accept_finish(
+    op_handle: u64,
+    out_local_ip: *mut *const c_char,
+    out_local_port: *mut c_ushort,
+    out_peer_ip: *mut *const c_char,
+    out_peer_port: *mut c_ushort,
+) -> u64 {
+    unsafe {
+        data_plane_async::data_plane_tcp_accept_finish(
+            op_handle,
+            out_local_ip,
+            out_local_port,
+            out_peer_ip,
+            out_peer_port,
+        )
+    }
+}
+
+/// Start an asynchronous TCP data-plane read.
+///
+/// # Safety
+/// `handle` must be a valid TCP stream handle returned by
+/// `data_plane_tcp_connect_finish` or `data_plane_tcp_accept_finish`.
+///
+/// # Return
+/// Returns a non-zero async operation handle on success, or `0` on failure.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_read_start(
+    handle: u64,
+    max_len: u32,
+    timeout_ms: u64,
+) -> u64 {
+    unsafe { data_plane_async::data_plane_tcp_read_start(handle, max_len, timeout_ms) }
+}
+
+/// Finish an asynchronous TCP data-plane read.
+///
+/// On success, writes the received buffer pointer and length into `out_buf` and
+/// `out_len`. The returned buffer is allocated by this library and must be
+/// released with `data_plane_free_bytes`.
+///
+/// # Safety
+/// `out_buf` and `out_len` must be non-null pointers to writable storage.
+///
+/// # Return
+/// Returns the number of bytes read, or `-1` on failure.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_read_finish(
+    op_handle: u64,
+    out_buf: *mut *const c_uchar,
+    out_len: *mut u32,
+) -> c_int {
+    unsafe { data_plane_async::data_plane_tcp_read_finish(op_handle, out_buf, out_len) }
+}
+
+/// Start an asynchronous TCP data-plane write.
+///
+/// The input bytes are copied before this function returns.
+///
+/// # Safety
+/// `handle` must be a valid TCP stream handle returned by
+/// `data_plane_tcp_connect_finish` or `data_plane_tcp_accept_finish`. If `len`
+/// is non-zero, `buf` must be non-null and readable for `len` bytes.
+///
+/// # Return
+/// Returns a non-zero async operation handle on success, or `0` on failure.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_write_start(
+    handle: u64,
+    buf: *const c_uchar,
+    len: u32,
+    timeout_ms: u64,
+) -> u64 {
+    unsafe { data_plane_async::data_plane_tcp_write_start(handle, buf, len, timeout_ms) }
+}
+
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub extern "C" fn data_plane_tcp_write_finish(op_handle: u64) -> c_int {
+    data_plane_async::data_plane_tcp_write_finish(op_handle)
+}
+
+/// Start an asynchronous UDP data-plane bind.
+///
+/// # Safety
+/// `inst_name` must be a non-null pointer to a null-terminated UTF-8 string.
+/// The string only needs to remain valid for the duration of this call.
+///
+/// # Return
+/// Returns a non-zero async operation handle on success, or `0` on failure.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_udp_bind_start(
+    inst_name: *const c_char,
+    local_port: c_ushort,
+    timeout_ms: u64,
+) -> u64 {
+    unsafe { data_plane_async::data_plane_udp_bind_start(inst_name, local_port, timeout_ms) }
+}
+
+/// Finish an asynchronous UDP data-plane bind.
+///
+/// On success, writes the socket local address into `out_local_ip` and
+/// `out_local_port`. The returned IP string is allocated by this library and
+/// must be released with `free_string`.
+///
+/// # Safety
+/// `out_local_ip` and `out_local_port` must be non-null pointers to writable
+/// storage.
+///
+/// # Return
+/// Returns a non-zero UDP socket handle on success, or `0` on failure.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_udp_bind_finish(
+    op_handle: u64,
+    out_local_ip: *mut *const c_char,
+    out_local_port: *mut c_ushort,
+) -> u64 {
+    unsafe { data_plane_async::data_plane_udp_bind_finish(op_handle, out_local_ip, out_local_port) }
+}
+
+/// Start an asynchronous UDP data-plane send.
+///
+/// The input bytes are copied before this function returns.
+///
+/// # Safety
+/// `handle` must be a valid UDP socket handle returned by
+/// `data_plane_udp_bind_finish`. `dst_ip` must be a non-null pointer to a
+/// null-terminated UTF-8 string. If `len` is non-zero, `buf` must be non-null
+/// and readable for `len` bytes.
+///
+/// # Return
+/// Returns a non-zero async operation handle on success, or `0` on failure.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_udp_send_to_start(
+    handle: u64,
+    dst_ip: *const c_char,
+    dst_port: c_ushort,
+    buf: *const c_uchar,
+    len: u32,
+    timeout_ms: u64,
+) -> u64 {
+    unsafe {
+        data_plane_async::data_plane_udp_send_to_start(
+            handle, dst_ip, dst_port, buf, len, timeout_ms,
+        )
+    }
+}
+
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub extern "C" fn data_plane_udp_send_to_finish(op_handle: u64) -> c_int {
+    data_plane_async::data_plane_udp_send_to_finish(op_handle)
+}
+
+/// Start an asynchronous UDP data-plane receive.
+///
+/// # Safety
+/// `handle` must be a valid UDP socket handle returned by
+/// `data_plane_udp_bind_finish`.
+///
+/// # Return
+/// Returns a non-zero async operation handle on success, or `0` on failure.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_udp_recv_from_start(
+    handle: u64,
+    max_len: u32,
+    timeout_ms: u64,
+) -> u64 {
+    unsafe { data_plane_async::data_plane_udp_recv_from_start(handle, max_len, timeout_ms) }
+}
+
+/// Finish an asynchronous UDP data-plane receive.
+///
+/// On success, writes the received buffer into `out_buf` and `out_len`, and
+/// the peer address into `out_ip` and `out_port`. The returned buffer is
+/// allocated by this library and must be released with `data_plane_free_bytes`;
+/// the returned IP string must be released with `free_string`.
+///
+/// # Safety
+/// `out_buf`, `out_len`, `out_ip`, and `out_port` must be non-null pointers to
+/// writable storage.
+///
+/// # Return
+/// Returns the number of bytes received, or `-1` on failure.
+#[cfg(feature = "ffi-dataplane")]
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_udp_recv_from_finish(
+    op_handle: u64,
+    out_buf: *mut *const c_uchar,
+    out_len: *mut u32,
+    out_ip: *mut *const c_char,
+    out_port: *mut c_ushort,
+) -> c_int {
+    unsafe {
+        data_plane_async::data_plane_udp_recv_from_finish(
+            op_handle, out_buf, out_len, out_ip, out_port,
+        )
+    }
+}
+
+// ===== Shared FFI Helper API =====
+
+/// Return the last FFI error message.
+///
+/// Synchronous API failures are stored in a thread-local buffer, so call this
+/// on the same thread that received `-1` or `0` from another API. Config-server
+/// callback delivery failures may happen on a runtime thread; those are stored
+/// globally and are included here so direct FFI callers can still retrieve the
+/// last callback error. If there is no error message, this writes a null pointer
+/// to `out`.
+///
+/// The returned string is allocated by this library and must be released with
+/// `free_string`.
+///
+/// # Safety
+/// `out` must be a non-null pointer to writable storage for one C string
+/// pointer.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn get_error_msg(out: *mut *const c_char) {
+    unsafe { error::get_error_msg(out) }
+}
+
+/// Release a C string allocated by this library.
+///
+/// Use this for strings returned through `get_error_msg`,
+/// `collect_network_infos`, and data-plane address output parameters. Passing a
+/// null pointer is allowed and has no effect.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub extern "C" fn free_string(s: *const c_char) {
+    error::free_string(s)
+}
@@ -0,0 +1,54 @@
+use std::sync::{Arc, Mutex};
+
+use dashmap::DashMap;
+use easytier::instance_manager::NetworkInstanceManager;
+use tokio::runtime::{Builder, Runtime};
+use uuid::Uuid;
+
+pub(crate) static INSTANCE_NAME_ID_MAP: once_cell::sync::Lazy<DashMap<String, Uuid>> =
+    once_cell::sync::Lazy::new(DashMap::new);
+pub(crate) static INSTANCE_MANAGER: once_cell::sync::Lazy<Arc<NetworkInstanceManager>> =
+    once_cell::sync::Lazy::new(|| Arc::new(NetworkInstanceManager::new()));
+pub(crate) static ASYNC_RUNTIME: once_cell::sync::Lazy<Runtime> =
+    once_cell::sync::Lazy::new(|| {
+        Builder::new_multi_thread()
+            .enable_all()
+            .build()
+            .expect("tokio runtime for easytier-ffi")
+    });
+pub(crate) static INSTANCE_MUTATION_LOCK: once_cell::sync::Lazy<Mutex<()>> =
+    once_cell::sync::Lazy::new(|| Mutex::new(()));
+
+pub(crate) fn remove_instance_name_ids(ids: &[Uuid]) {
+    if ids.is_empty() {
+        return;
+    }
+
+    INSTANCE_NAME_ID_MAP.retain(|_, instance_id| !ids.contains(instance_id));
+}
+
+pub(crate) fn lock_remote_instance_mutation() -> tokio::sync::OwnedMutexGuard<()> {
+    INSTANCE_MANAGER
+        .remote_mutation_lock()
+        .blocking_lock_owned()
+}
+
+pub(crate) fn instance_name_exists(inst_name: &str) -> bool {
+    find_instance_id_by_name(inst_name).is_some()
+}
+
+pub(crate) fn find_instance_id_by_name(inst_name: &str) -> Option<Uuid> {
+    INSTANCE_NAME_ID_MAP
+        .get(inst_name)
+        .map(|id| *id)
+        .or_else(|| {
+            INSTANCE_MANAGER
+                .list_network_instance_ids()
+                .into_iter()
+                .find(|id| {
+                    INSTANCE_MANAGER
+                        .get_instance_name(id)
+                        .is_some_and(|name| name == inst_name)
+                })
+        })
+}
@@ -0,0 +1,23 @@
+use std::ffi::{CStr, c_char};
+
+pub(crate) unsafe fn c_str_to_string(ptr: *const c_char, name: &str) -> Result<String, String> {
+    if ptr.is_null() {
+        return Err(format!("{} is null", name));
+    }
+
+    unsafe { CStr::from_ptr(ptr) }
+        .to_str()
+        .map(|value| value.to_string())
+        .map_err(|err| format!("{} is not valid UTF-8: {}", name, err))
+}
+
+pub(crate) unsafe fn optional_c_str_to_string(
+    ptr: *const c_char,
+    name: &str,
+) -> Result<Option<String>, String> {
+    if ptr.is_null() {
+        return Ok(None);
+    }
+
+    unsafe { c_str_to_string(ptr, name) }.map(Some)
+}
@@ -0,0 +1,766 @@
+use crate::{
+    config_server::{
+        ConfigServerCallbackScope, ManagedConfigServerClientHooks, set_active_for_test,
+    },
+    state::{
+        INSTANCE_MANAGER, INSTANCE_NAME_ID_MAP, find_instance_id_by_name,
+        lock_remote_instance_mutation, remove_instance_name_ids,
+    },
+    *,
+};
+use easytier::{
+    common::config::{ConfigFileControl, ConfigLoader as _, TomlConfigLoader},
+    web_client::WebClientHooks,
+};
+use serde_json::Value;
+use std::{
+    collections::HashSet,
+    ffi::{CStr, CString, c_char, c_void},
+    sync::{Mutex, mpsc},
+    time::Duration,
+};
+use uuid::Uuid;
+
+#[test]
+fn test_parse_config() {
+    let cfg_str = r#"
+            inst_name = "test"
+            network = "test_network"
+        "#;
+    let cstr = std::ffi::CString::new(cfg_str).unwrap();
+    unsafe {
+        assert_eq!(parse_config(cstr.as_ptr()), 0);
+    }
+}
+
+#[test]
+fn test_run_network_instance() {
+    let cfg_str = r#"
+            inst_name = "test"
+            network = "test_network"
+        "#;
+    let cstr = std::ffi::CString::new(cfg_str).unwrap();
+    unsafe {
+        assert_eq!(run_network_instance(cstr.as_ptr()), 0);
+    }
+}
+
+#[test]
+fn get_error_msg_returns_config_server_callback_error() {
+    let hooks = ManagedConfigServerClientHooks::new(None, std::ptr::null_mut());
+    let callback_error = format!("callback delivery failed {}", Uuid::new_v4());
+    crate::config_server::clear_last_callback_error();
+    hooks.note_callback_error(callback_error.clone());
+
+    unsafe {
+        let mut error_ptr: *const c_char = std::ptr::null();
+        get_error_msg(&mut error_ptr);
+        assert!(!error_ptr.is_null());
+        let error_msg = CStr::from_ptr(error_ptr).to_string_lossy().into_owned();
+        free_string(error_ptr);
+        assert!(error_msg.contains(&callback_error));
+    }
+
+    crate::config_server::clear_last_callback_error();
+}
+
+unsafe extern "C" fn record_config_server_event(event_json: *const c_char, user_data: *mut c_void) {
+    let events = unsafe { &*(user_data as *const Mutex<Vec<String>>) };
+    events.lock().unwrap().push(
+        unsafe { CStr::from_ptr(event_json) }
+            .to_string_lossy()
+            .into_owned(),
+    );
+}
+
+fn take_last_error() -> Option<String> {
+    unsafe {
+        let mut error_ptr: *const c_char = std::ptr::null();
+        get_error_msg(&mut error_ptr);
+        if error_ptr.is_null() {
+            None
+        } else {
+            let error = CStr::from_ptr(error_ptr).to_string_lossy().into_owned();
+            free_string(error_ptr);
+            Some(error)
+        }
+    }
+}
+
+fn free_key_value_pairs(infos: &[KeyValuePair]) {
+    for info in infos {
+        free_string(info.key);
+        free_string(info.value);
+    }
+}
+
+#[test]
+fn list_instance_returns_instance_names_and_ids() {
+    let instance_id = Uuid::new_v4();
+    let instance_name = format!("list-instance-{}", instance_id);
+    let cfg = TomlConfigLoader::default();
+    cfg.set_id(instance_id);
+    cfg.set_inst_name(instance_name.clone());
+    INSTANCE_MANAGER
+        .run_network_instance(cfg, false, ConfigFileControl::STATIC_CONFIG)
+        .unwrap();
+    INSTANCE_NAME_ID_MAP.insert(instance_name.clone(), instance_id);
+
+    let mut infos = vec![
+        KeyValuePair {
+            key: std::ptr::null(),
+            value: std::ptr::null(),
+        };
+        16
+    ];
+    let count = unsafe { list_instance(infos.as_mut_ptr(), infos.len()) };
+    assert!(count > 0);
+
+    let mut found = false;
+    for info in infos.iter().take(count as usize) {
+        let key = unsafe { CStr::from_ptr(info.key) }.to_string_lossy();
+        let value = unsafe { CStr::from_ptr(info.value) }.to_string_lossy();
+        if key == instance_name {
+            assert_eq!(value, instance_id.to_string());
+            found = true;
+        }
+    }
+
+    free_key_value_pairs(&infos[..count as usize]);
+    INSTANCE_MANAGER
+        .delete_network_instance(vec![instance_id])
+        .unwrap();
+    remove_instance_name_ids(&[instance_id]);
+    assert!(found);
+}
+
+#[test]
+fn list_instance_allows_zero_length() {
+    assert_eq!(unsafe { list_instance(std::ptr::null_mut(), 0) }, 0);
+}
+
+#[test]
+fn list_instance_rejects_null_output_pointer() {
+    assert_eq!(unsafe { list_instance(std::ptr::null_mut(), 1) }, -1);
+    assert!(take_last_error().unwrap().contains("infos is null"));
+}
+
+#[test]
+fn call_json_rpc_returns_logger_response() {
+    let service = CString::new("api.logger.LoggerRpcService").unwrap();
+    let method = CString::new("get_logger_config").unwrap();
+    let payload = CString::new("{}").unwrap();
+    let mut response_ptr: *const c_char = std::ptr::null();
+
+    assert_eq!(
+        unsafe {
+            call_json_rpc(
+                service.as_ptr(),
+                method.as_ptr(),
+                std::ptr::null(),
+                payload.as_ptr(),
+                &mut response_ptr,
+            )
+        },
+        0
+    );
+    assert!(!response_ptr.is_null());
+    let response = unsafe { CStr::from_ptr(response_ptr) }
+        .to_string_lossy()
+        .into_owned();
+    free_string(response_ptr);
+    let response: Value = serde_json::from_str(&response).unwrap();
+    assert!(response.get("level").is_some());
+}
+
+#[test]
+fn call_json_rpc_rejects_instance_management_service() {
+    let service = CString::new("api.manage.WebClientService").unwrap();
+    let method = CString::new("list_network_instance").unwrap();
+    let payload = CString::new("{}").unwrap();
+    let mut response_ptr: *const c_char = std::ptr::null();
+
+    assert_eq!(
+        unsafe {
+            call_json_rpc(
+                service.as_ptr(),
+                method.as_ptr(),
+                std::ptr::null(),
+                payload.as_ptr(),
+                &mut response_ptr,
+            )
+        },
+        -1
+    );
+    assert!(response_ptr.is_null());
+    assert!(take_last_error().unwrap().contains("not exposed"));
+}
+
+#[test]
+fn call_json_rpc_rejects_malformed_payload_json() {
+    let service = CString::new("api.logger.LoggerRpcService").unwrap();
+    let method = CString::new("get_logger_config").unwrap();
+    let payload = CString::new("{").unwrap();
+    let mut response_ptr: *const c_char = std::ptr::null();
+
+    assert_eq!(
+        unsafe {
+            call_json_rpc(
+                service.as_ptr(),
+                method.as_ptr(),
+                std::ptr::null(),
+                payload.as_ptr(),
+                &mut response_ptr,
+            )
+        },
+        -1
+    );
+    assert!(response_ptr.is_null());
+    assert!(
+        take_last_error()
+            .unwrap()
+            .contains("failed to parse payload_json")
+    );
+}
+
+#[test]
+fn call_json_rpc_rejects_null_output_pointer() {
+    let service = CString::new("api.logger.LoggerRpcService").unwrap();
+    let method = CString::new("get_logger_config").unwrap();
+    let payload = CString::new("{}").unwrap();
+
+    assert_eq!(
+        unsafe {
+            call_json_rpc(
+                service.as_ptr(),
+                method.as_ptr(),
+                std::ptr::null(),
+                payload.as_ptr(),
+                std::ptr::null_mut(),
+            )
+        },
+        -1
+    );
+    assert!(
+        take_last_error()
+            .unwrap()
+            .contains("out_response_json is null")
+    );
+}
+
+#[tokio::test]
+async fn config_server_hooks_emit_run_event() {
+    let events: Mutex<Vec<String>> = Mutex::new(Vec::new());
+    let hooks = ManagedConfigServerClientHooks::new(
+        Some(record_config_server_event),
+        &events as *const _ as *mut c_void,
+    );
+    let instance_id = Uuid::new_v4();
+    let cfg = TomlConfigLoader::default();
+    cfg.set_id(instance_id);
+    let inst_name = format!("test-{}", instance_id);
+    cfg.set_inst_name(inst_name.clone());
+    hooks.pre_run_network_instance(&cfg).await.unwrap();
+    INSTANCE_MANAGER
+        .run_network_instance(cfg, false, ConfigFileControl::STATIC_CONFIG)
+        .unwrap();
+
+    hooks.post_run_network_instance(&instance_id).await.unwrap();
+
+    let duplicate_cfg = TomlConfigLoader::default();
+    duplicate_cfg.set_inst_name(inst_name);
+    duplicate_cfg.set_id(Uuid::new_v4());
+    assert!(
+        hooks
+            .pre_run_network_instance(&duplicate_cfg)
+            .await
+            .is_err()
+    );
+
+    assert_eq!(hooks.tracked_instance_ids(), vec![instance_id]);
+    let events = events.lock().unwrap();
+    assert_eq!(events.len(), 1);
+    let event: Value = serde_json::from_str(&events[0]).unwrap();
+    assert_eq!(event["event"], "run_network_instance");
+    assert_eq!(event["success"], true);
+    assert_eq!(event["instance_id"], instance_id.to_string());
+    assert!(event["error"].is_null());
+    INSTANCE_MANAGER
+        .delete_network_instance(vec![instance_id])
+        .unwrap();
+    remove_instance_name_ids(&[instance_id]);
+}
+
+#[tokio::test]
+async fn config_server_hooks_emit_delete_events_for_tracked_instances() {
+    let events: Mutex<Vec<String>> = Mutex::new(Vec::new());
+    let hooks = ManagedConfigServerClientHooks::new(
+        Some(record_config_server_event),
+        &events as *const _ as *mut c_void,
+    );
+    let instance_id_1 = Uuid::new_v4();
+    let instance_id_2 = Uuid::new_v4();
+    let unknown_instance_id = Uuid::new_v4();
+    for id in [instance_id_1, instance_id_2] {
+        let cfg = TomlConfigLoader::default();
+        cfg.set_id(id);
+        cfg.set_inst_name(format!("test-{}", id));
+        hooks.pre_run_network_instance(&cfg).await.unwrap();
+        INSTANCE_MANAGER
+            .run_network_instance(cfg, false, ConfigFileControl::STATIC_CONFIG)
+            .unwrap();
+    }
+
+    hooks
+        .post_run_network_instance(&instance_id_1)
+        .await
+        .unwrap();
+    hooks
+        .post_run_network_instance(&instance_id_2)
+        .await
+        .unwrap();
+    events.lock().unwrap().clear();
+
+    hooks
+        .post_remove_network_instances(&[instance_id_1, unknown_instance_id, instance_id_2])
+        .await
+        .unwrap();
+
+    assert!(hooks.tracked_instance_ids().is_empty());
+    let events = events.lock().unwrap();
+    assert_eq!(events.len(), 2);
+    let event_ids = events
+        .iter()
+        .map(|event| {
+            let event: Value = serde_json::from_str(event).unwrap();
+            assert_eq!(event["event"], "delete_network_instance");
+            assert_eq!(event["success"], true);
+            assert!(event["error"].is_null());
+            event["instance_id"].as_str().unwrap().to_string()
+        })
+        .collect::<HashSet<_>>();
+    assert_eq!(
+        event_ids,
+        HashSet::from([instance_id_1.to_string(), instance_id_2.to_string()])
+    );
+    INSTANCE_MANAGER
+        .delete_network_instance(vec![instance_id_1, instance_id_2])
+        .unwrap();
+    remove_instance_name_ids(&[instance_id_1, instance_id_2]);
+}
+
+#[tokio::test]
+async fn config_server_hooks_remove_untracked_name_mapping_without_event() {
+    let events: Mutex<Vec<String>> = Mutex::new(Vec::new());
+    let hooks = ManagedConfigServerClientHooks::new(
+        Some(record_config_server_event),
+        &events as *const _ as *mut c_void,
+    );
+    let local_id = Uuid::new_v4();
+    let inst_name = format!("local-{}", local_id);
+    INSTANCE_NAME_ID_MAP.insert(inst_name.clone(), local_id);
+
+    hooks
+        .post_remove_network_instances(&[local_id])
+        .await
+        .unwrap();
+
+    assert!(INSTANCE_NAME_ID_MAP.get(&inst_name).is_none());
+    assert!(events.lock().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn config_server_hooks_reject_duplicate_instance_name() {
+    let hooks = ManagedConfigServerClientHooks::new(None, std::ptr::null_mut());
+    let inst_name = format!("test-{}", Uuid::new_v4());
+    let existing_id = Uuid::new_v4();
+    let new_id = Uuid::new_v4();
+    INSTANCE_NAME_ID_MAP.insert(inst_name.clone(), existing_id);
+
+    let cfg = TomlConfigLoader::default();
+    cfg.set_inst_name(inst_name.clone());
+    cfg.set_id(new_id);
+
+    assert!(hooks.pre_run_network_instance(&cfg).await.is_err());
+    assert_eq!(*INSTANCE_NAME_ID_MAP.get(&inst_name).unwrap(), existing_id);
+    INSTANCE_NAME_ID_MAP.remove(&inst_name);
+}
+
+#[tokio::test]
+async fn config_server_hooks_remove_overwritten_id_before_duplicate_name_error() {
+    let events: Mutex<Vec<String>> = Mutex::new(Vec::new());
+    let hooks = ManagedConfigServerClientHooks::new(
+        Some(record_config_server_event),
+        &events as *const _ as *mut c_void,
+    );
+    let old_name = format!("old-{}", Uuid::new_v4());
+    let duplicate_name = format!("duplicate-{}", Uuid::new_v4());
+    let overwritten_id = Uuid::new_v4();
+    let duplicate_id = Uuid::new_v4();
+    hooks.instance_ids.lock().unwrap().insert(overwritten_id);
+    INSTANCE_NAME_ID_MAP.insert(old_name.clone(), overwritten_id);
+    INSTANCE_NAME_ID_MAP.insert(duplicate_name.clone(), duplicate_id);
+
+    hooks
+        .post_remove_network_instances(&[overwritten_id])
+        .await
+        .unwrap();
+
+    let cfg = TomlConfigLoader::default();
+    cfg.set_inst_name(duplicate_name.clone());
+    cfg.set_id(overwritten_id);
+
+    assert!(hooks.pre_run_network_instance(&cfg).await.is_err());
+    assert!(hooks.tracked_instance_ids().is_empty());
+    assert!(INSTANCE_NAME_ID_MAP.get(&old_name).is_none());
+    assert_eq!(
+        *INSTANCE_NAME_ID_MAP.get(&duplicate_name).unwrap(),
+        duplicate_id
+    );
+    assert_eq!(events.lock().unwrap().len(), 1);
+    INSTANCE_NAME_ID_MAP.remove(&duplicate_name);
+}
+
+#[tokio::test]
+async fn config_server_hooks_remove_tracked_state_before_overwrite_retry() {
+    let hooks = ManagedConfigServerClientHooks::new(None, std::ptr::null_mut());
+    let inst_name = format!("test-{}", Uuid::new_v4());
+    let instance_id = Uuid::new_v4();
+    hooks.instance_ids.lock().unwrap().insert(instance_id);
+    INSTANCE_NAME_ID_MAP.insert(inst_name.clone(), instance_id);
+
+    let cfg = TomlConfigLoader::default();
+    cfg.set_inst_name(inst_name.clone());
+    cfg.set_id(instance_id);
+
+    hooks
+        .post_remove_network_instances(&[instance_id])
+        .await
+        .unwrap();
+    hooks.pre_run_network_instance(&cfg).await.unwrap();
+
+    assert!(hooks.tracked_instance_ids().is_empty());
+    assert!(INSTANCE_NAME_ID_MAP.get(&inst_name).is_none());
+}
+
+#[tokio::test]
+async fn config_server_hooks_reject_post_run_after_external_delete() {
+    let hooks = ManagedConfigServerClientHooks::new(None, std::ptr::null_mut());
+    let instance_id = Uuid::new_v4();
+    let cfg = TomlConfigLoader::default();
+    cfg.set_id(instance_id);
+    cfg.set_inst_name(format!("test-{}", instance_id));
+    hooks.pre_run_network_instance(&cfg).await.unwrap();
+    INSTANCE_MANAGER
+        .run_network_instance(cfg, false, ConfigFileControl::STATIC_CONFIG)
+        .unwrap();
+    INSTANCE_MANAGER
+        .delete_network_instance(vec![instance_id])
+        .unwrap();
+
+    assert!(hooks.post_run_network_instance(&instance_id).await.is_err());
+}
+
+#[test]
+fn find_instance_id_by_name_resolves_uncommitted_manager_instance_name() {
+    let instance_id = Uuid::new_v4();
+    let inst_name = format!("test-{}", instance_id);
+    let cfg = TomlConfigLoader::default();
+    cfg.set_id(instance_id);
+    cfg.set_inst_name(inst_name.clone());
+    INSTANCE_MANAGER
+        .run_network_instance(cfg, false, ConfigFileControl::STATIC_CONFIG)
+        .unwrap();
+
+    assert_eq!(find_instance_id_by_name(&inst_name), Some(instance_id));
+    INSTANCE_MANAGER
+        .delete_network_instance(vec![instance_id])
+        .unwrap();
+    remove_instance_name_ids(&[instance_id]);
+}
+
+#[test]
+fn delete_network_instance_removes_only_named_instances() {
+    let keep_id = Uuid::new_v4();
+    let delete_id = Uuid::new_v4();
+    let keep_name = format!("keep-{}", keep_id);
+    let delete_name = format!("delete-{}", delete_id);
+
+    for (id, name) in [
+        (keep_id, keep_name.clone()),
+        (delete_id, delete_name.clone()),
+    ] {
+        let cfg = TomlConfigLoader::default();
+        cfg.set_id(id);
+        cfg.set_inst_name(name.clone());
+        INSTANCE_MANAGER
+            .run_network_instance(cfg, false, ConfigFileControl::STATIC_CONFIG)
+            .unwrap();
+        INSTANCE_NAME_ID_MAP.insert(name, id);
+    }
+
+    let delete_name = CString::new(delete_name.clone()).unwrap();
+    let inst_names = [delete_name.as_ptr()];
+    assert_eq!(
+        unsafe { delete_network_instance(inst_names.as_ptr(), inst_names.len()) },
+        0
+    );
+
+    assert_eq!(find_instance_id_by_name(&keep_name), Some(keep_id));
+    assert!(find_instance_id_by_name(delete_name.to_str().unwrap()).is_none());
+
+    INSTANCE_MANAGER
+        .delete_network_instance(vec![keep_id])
+        .unwrap();
+    remove_instance_name_ids(&[keep_id]);
+}
+
+#[test]
+fn retain_and_delete_network_instance_reject_invalid_name_pointers() {
+    assert_eq!(unsafe { retain_network_instance(std::ptr::null(), 1) }, -1);
+    assert_eq!(unsafe { delete_network_instance(std::ptr::null(), 1) }, -1);
+
+    let inst_names = [std::ptr::null()];
+    assert_eq!(
+        unsafe { retain_network_instance(inst_names.as_ptr(), inst_names.len()) },
+        -1
+    );
+    assert_eq!(
+        unsafe { delete_network_instance(inst_names.as_ptr(), inst_names.len()) },
+        -1
+    );
+}
+
+#[test]
+fn ffi_remote_mutation_lock_uses_manager_lock() {
+    let manager_guard = INSTANCE_MANAGER
+        .remote_mutation_lock()
+        .blocking_lock_owned();
+    let (done_tx, done_rx) = mpsc::channel();
+    let waiter = std::thread::spawn(move || {
+        let _ffi_guard = lock_remote_instance_mutation();
+        done_tx.send(()).unwrap();
+    });
+
+    assert!(done_rx.recv_timeout(Duration::from_millis(100)).is_err());
+    drop(manager_guard);
+    done_rx.recv_timeout(Duration::from_secs(5)).unwrap();
+    waiter.join().unwrap();
+}
+
+#[tokio::test]
+async fn config_server_hooks_suppress_late_run_events_while_stopping() {
+    let events: Mutex<Vec<String>> = Mutex::new(Vec::new());
+    let hooks = ManagedConfigServerClientHooks::new(
+        Some(record_config_server_event),
+        &events as *const _ as *mut c_void,
+    );
+    hooks.start_stopping();
+
+    hooks
+        .post_run_network_instance(&Uuid::new_v4())
+        .await
+        .unwrap();
+
+    assert!(hooks.tracked_instance_ids().is_empty());
+    assert!(events.lock().unwrap().is_empty());
+}
+
+#[test]
+fn config_server_callback_context_rejects_nested_blocking_ffi_calls() {
+    let _callback_scope = ConfigServerCallbackScope::enter();
+    assert_eq!(is_config_server_client_connected(), 0);
+    let service = CString::new("api.logger.LoggerRpcService").unwrap();
+    let method = CString::new("get_logger_config").unwrap();
+    let payload = CString::new("{}").unwrap();
+    let mut response_ptr: *const c_char = std::ptr::null();
+    assert_eq!(
+        unsafe {
+            call_json_rpc(
+                service.as_ptr(),
+                method.as_ptr(),
+                std::ptr::null(),
+                payload.as_ptr(),
+                &mut response_ptr,
+            )
+        },
+        -1
+    );
+    assert!(response_ptr.is_null());
+    assert_eq!(
+        unsafe { collect_network_infos(std::ptr::null_mut(), 0) },
+        -1
+    );
+    assert_eq!(unsafe { list_instance(std::ptr::null_mut(), 0) }, -1);
+    let cfg = CString::new("inst_name = \"callback-test\"\nlisteners = []").unwrap();
+    assert_eq!(unsafe { run_network_instance(cfg.as_ptr()) }, -1);
+    assert_eq!(unsafe { retain_network_instance(std::ptr::null(), 0) }, -1);
+    assert_eq!(unsafe { delete_network_instance(std::ptr::null(), 0) }, -1);
+    let url = CString::new("ring://test/token").unwrap();
+    let machine_id = CString::new("test-machine").unwrap();
+    assert_eq!(
+        unsafe {
+            start_config_server_client(
+                url.as_ptr(),
+                std::ptr::null(),
+                machine_id.as_ptr(),
+                false,
+                None,
+                std::ptr::null_mut(),
+            )
+        },
+        -1
+    );
+    assert_eq!(stop_config_server_client(), -1);
+
+    #[cfg(feature = "ffi-dataplane")]
+    {
+        assert_eq!(
+            unsafe {
+                data_plane_tcp_connect(
+                    std::ptr::null(),
+                    std::ptr::null(),
+                    0,
+                    0,
+                    std::ptr::null_mut(),
+                    std::ptr::null_mut(),
+                )
+            },
+            0
+        );
+        assert_eq!(
+            unsafe {
+                data_plane_tcp_bind(
+                    std::ptr::null(),
+                    0,
+                    0,
+                    std::ptr::null_mut(),
+                    std::ptr::null_mut(),
+                )
+            },
+            0
+        );
+        assert_eq!(
+            unsafe {
+                data_plane_tcp_accept(
+                    0,
+                    0,
+                    std::ptr::null_mut(),
+                    std::ptr::null_mut(),
+                    std::ptr::null_mut(),
+                    std::ptr::null_mut(),
+                )
+            },
+            0
+        );
+        assert_eq!(
+            unsafe { data_plane_tcp_read(0, std::ptr::null_mut(), 0, 0) },
+            -1
+        );
+        assert_eq!(
+            unsafe { data_plane_tcp_write(0, std::ptr::null(), 0, 0) },
+            -1
+        );
+        assert_eq!(data_plane_tcp_close(0), -1);
+        assert_eq!(data_plane_tcp_listener_close(0), -1);
+        assert_eq!(
+            unsafe {
+                data_plane_udp_bind(
+                    std::ptr::null(),
+                    0,
+                    0,
+                    std::ptr::null_mut(),
+                    std::ptr::null_mut(),
+                )
+            },
+            0
+        );
+        assert_eq!(
+            unsafe { data_plane_udp_send_to(0, std::ptr::null(), 0, std::ptr::null(), 0, 0) },
+            -1
+        );
+        assert_eq!(
+            unsafe {
+                data_plane_udp_recv_from(
+                    0,
+                    std::ptr::null_mut(),
+                    0,
+                    std::ptr::null_mut(),
+                    std::ptr::null_mut(),
+                    0,
+                )
+            },
+            -1
+        );
+        assert_eq!(data_plane_udp_close(0), -1);
+        assert_eq!(data_plane_async_op_status(0), -2);
+        assert_eq!(data_plane_async_op_wait(0, 0), -2);
+        assert_eq!(data_plane_async_op_cancel(0), -2);
+        assert_eq!(data_plane_async_op_free(0), -2);
+        data_plane_free_bytes(std::ptr::null(), 0);
+        assert_eq!(
+            unsafe { data_plane_tcp_connect_start(std::ptr::null(), std::ptr::null(), 0, 0) },
+            0
+        );
+        assert_eq!(
+            unsafe { data_plane_tcp_bind_start(std::ptr::null(), 0, 0) },
+            0
+        );
+        assert_eq!(unsafe { data_plane_tcp_accept_start(0, 0) }, 0);
+        assert_eq!(unsafe { data_plane_tcp_read_start(0, 0, 0) }, 0);
+        assert_eq!(
+            unsafe { data_plane_tcp_write_start(0, std::ptr::null(), 0, 0) },
+            0
+        );
+        assert_eq!(
+            unsafe { data_plane_udp_bind_start(std::ptr::null(), 0, 0) },
+            0
+        );
+        assert_eq!(
+            unsafe { data_plane_udp_send_to_start(0, std::ptr::null(), 0, std::ptr::null(), 0, 0) },
+            0
+        );
+        assert_eq!(unsafe { data_plane_udp_recv_from_start(0, 0, 0) }, 0);
+    }
+}
+
+#[cfg(feature = "ffi-dataplane")]
+#[test]
+fn active_config_server_rejects_data_plane() {
+    set_active_for_test(true);
+
+    assert_eq!(
+        unsafe {
+            data_plane_tcp_connect(
+                std::ptr::null(),
+                std::ptr::null(),
+                0,
+                0,
+                std::ptr::null_mut(),
+                std::ptr::null_mut(),
+            )
+        },
+        0
+    );
+    assert_eq!(
+        unsafe { data_plane_tcp_read(0, std::ptr::null_mut(), 0, 0) },
+        -1
+    );
+    assert_eq!(
+        unsafe { data_plane_tcp_connect_start(std::ptr::null(), std::ptr::null(), 0, 0) },
+        0
+    );
+    assert_eq!(unsafe { data_plane_tcp_read_start(0, 0, 0) }, 0);
+
+    set_active_for_test(false);
+}
+
+#[cfg(feature = "ffi-dataplane")]
+#[test]
+fn async_op_invalid_handle_helpers_are_stable() {
+    assert_eq!(data_plane_async_op_status(u64::MAX), -2);
+    assert_eq!(data_plane_async_op_wait(u64::MAX, 1), -2);
+    assert_eq!(data_plane_async_op_cancel(u64::MAX), -2);
+    assert_eq!(data_plane_async_op_free(u64::MAX), -2);
+    data_plane_free_bytes(std::ptr::null(), 0);
+}
@@ -0,0 +1,10 @@
+use std::ffi::{c_char, c_void};
+
+#[repr(C)]
+#[derive(Clone, Copy)]
+pub struct KeyValuePair {
+    pub key: *const c_char,
+    pub value: *const c_char,
+}
+
+pub type ConfigServerEventCallback = Option<unsafe extern "C" fn(*const c_char, *mut c_void)>;
@@ -0,0 +1,33 @@
+#!/sbin/sh
+
+#################
+# Initialization
+#################
+
+umask 022
+
+# echo before loading util_functions
+ui_print() { echo "$1"; }
+
+require_new_magisk() {
+  ui_print "********************************"
+  ui_print " Please install Magisk v20.4+! "
+  ui_print "********************************"
+  exit 1
+}
+
+#########################
+# Load util_functions.sh
+#########################
+
+OUTFD=$2
+ZIPFILE=$3
+
+mount /data 2>/dev/null
+
+[ -f /data/adb/magisk/util_functions.sh ] || require_new_magisk
+. /data/adb/magisk/util_functions.sh
+[ $MAGISK_VER_CODE -lt 20400 ] && require_new_magisk
+
+install_module
+exit 0
@@ -0,0 +1 @@
+#MAGISK
@@ -0,0 +1,6 @@
+# easytier_magisk版模块
+magisk安装后重启
+
+目录位置:/data/adb/modules/easytier_magisk
+配置文件位置://data/adb/modules/easytier_magisk/config/config.toml
+修改config.conf即可，修改后配置文件后去magisk app重新开关模块即可生效
@@ -0,0 +1,74 @@
+#!/data/adb/magisk/busybox sh
+MODDIR=${0%/*}
+MODULE_PROP="${MODDIR}/module.prop"
+IP_RULE_SCRIPT="${MODDIR}/hotspot_iprule.sh"
+
+ET_STATUS=""
+REDIR_STATUS=""
+IS_RUNNING=false
+
+# 确保辅助脚本有执行权限
+chmod +x "${IP_RULE_SCRIPT}" 2>/dev/null
+
+# 更新 module.prop 文件中的 description
+update_module_description() {
+    local status_message=$1
+    # 检查 module.prop 文件存在且 description 发生变化了再写入
+    if [ -f "${MODULE_PROP}" ]; then
+        local current_desc=$(grep "^description=" "${MODULE_PROP}")
+        local new_desc="description=[状态] ${status_message}"
+        if [ "${current_desc}" != "${new_desc}" ]; then
+            sed -i "s#^description=.*#${new_desc}#" "${MODULE_PROP}"
+        fi
+    fi
+}
+
+# 判断程序启动状态
+if [ -f "${MODDIR}/disable" ]; then
+    IS_RUNNING=false
+    ET_STATUS="主程序已关闭"
+
+elif pgrep -f "${MODDIR}/easytier-core" >/dev/null; then
+    IS_RUNNING=true
+    if [ -f "${MODDIR}/config/command_args" ]; then
+        ET_STATUS="主程序正在运行（启动参数模式）"
+    else
+        ET_STATUS="主程序正在运行（配置文件模式）"
+    fi
+    
+elif [ -z "$ET_STATUS" ]; then
+    # 既没 disable 也没运行，说明是异常停止或未启动
+    ET_STATUS="主程序启动失败或未运行"
+fi
+
+# 无论主程序是否运行，都允许切换“开关文件”的状态，以便下次生效
+if [ -f "${MODDIR}/enable_IP_rule" ]; then
+    rm -f "${MODDIR}/enable_IP_rule"
+    
+    "${IP_RULE_SCRIPT}" del >/dev/null 2>&1
+    
+    REDIR_STATUS="转发已禁用"
+    echo "热点子网转发已禁用"
+    echo "[ET-NAT] Action: IP rule disabled." >> "${MODDIR}/log.log"
+else
+    touch "${MODDIR}/enable_IP_rule"
+
+    if [ "$IS_RUNNING" = true ]; then
+        "${IP_RULE_SCRIPT}" del >/dev/null 2>&1
+        "${IP_RULE_SCRIPT}" add_once
+        echo "转发规则将立即生效，无需重启"
+    else
+        echo "主程序未运行，转发规则将在下次启动时生效"
+    fi
+    
+    REDIR_STATUS="转发已激活"
+    echo "----------------------------------"
+    echo "热点子网转发已激活"
+    echo "热点开启后将自动将热点加入转发网络"
+    echo "需要在配置中提前配置好 cidr 参数"
+    echo "----------------------------------"
+    echo "[ET-NAT] Action: IP rule enabled." >> "${MODDIR}/log.log"
+fi
+
+sync
+update_module_description "${ET_STATUS}| ${REDIR_STATUS}"
@@ -0,0 +1,25 @@
+#!/bin/sh
+
+version=$(cat module.prop | grep 'version=' | awk -F '=' '{print $2}' | sed 's/ (.*//')
+
+version='v'$(grep '^version =' ../../easytier/Cargo.toml | cut -d '"' -f 2)
+
+if [ -z "$version" ]; then
+    echo "Error: 版本号不存在."
+    exit 1
+fi
+
+filename="easytier_magisk_${version}.zip"
+echo $version  
+
+
+if [ -f "./easytier-core" ] && [ -f "./easytier-cli" ] && [ -f "./easytier-web" ]; then
+    zip -r -o -X "$filename" ./ -x '.git/*' -x '.github/*' -x 'folder/*' -x 'build.sh' -x 'magisk_update.json'
+else
+    wget -O "easytier_last.zip" https://github.com/EasyTier/EasyTier/releases/download/"$version"/easytier-linux-aarch64-"$version".zip
+    unzip -o easytier_last.zip -d ./
+    mv ./easytier-linux-aarch64/* ./
+    rm -rf ./easytier_last.zip
+    rm -rf ./easytier-linux-aarch64
+    zip -r -o -X "$filename" ./ -x '.git/*' -x '.github/*' -x 'folder/*' -x 'build.sh' -x 'magisk_update.json'
+fi
@@ -0,0 +1 @@
+--config-server udp://127.0.0.1:22020/admin --machine-id easytier-magisk
@@ -0,0 +1,38 @@
+instance_name = "default"
+dhcp = false
+#ipv4="本机ip"
+listeners = [
+    "tcp://0.0.0.0:11010",
+    "udp://0.0.0.0:11010",
+    "wg://0.0.0.0:11011",
+    "ws://0.0.0.0:11011/",
+    "wss://0.0.0.0:11012/",
+]
+mapped_listeners = []
+exit_nodes = []
+rpc_portal = "0.0.0.0:15888"
+
+[network_identity]
+network_name = "default"
+network_secret = ""
+
+[[peer]]
+#uri = "协议://中转ip:端口"
+
+[flags]
+default_protocol = "tcp"
+dev_name = ""
+enable_encryption = true
+enable_ipv6 = true
+mtu = 1380
+latency_first = false
+enable_exit_node = false
+no_tun = false
+use_smoltcp = false
+foreign_network_whitelist = "*"
+disable_p2p = false
+relay_all_peer_rpc = false
+disable_udp_hole_punching = false
+disable_tcp_hole_punching = false
+
+
@@ -0,0 +1,19 @@
+SKIPMOUNT=false
+PROPFILE=true
+POSTFSDATA=true
+LATESTARTSERVICE=true
+
+set_perm_recursive $MODPATH 0 0 0777 0777
+
+ui_print "系统架构为：$ARCH"
+ui_print "系统 SDK 版本：$API"
+ui_print "EasyTier 安装位置：/data/adb/modules/easytier_magisk"
+ui_print "配置文件位置：/data/adb/modules/easytier_magisk/config/config.toml"
+ui_print "如需使用启动参数模式，请将 /data/adb/modules/easytier_magisk/config/command_args_sample 重命名为 command_args，并修改其中的内容"
+ui_print "config 目录中存在 command_args 文件时，模块会自动忽略 config.toml 文件"
+ui_print "----------------------------------"
+ui_print "注意！启动参数文件中不能存在 \" 和 '，配置文件则没有这个限制"
+ui_print "----------------------------------"
+ui_print "修改配置后无需重启设备，在 Magisk 中禁用 EasyTier 模块，等待 10 秒后重新启用即可让新配置生效"
+ui_print "点击 Magisk 中模块左下角的“操作”按钮可以禁用或激活热点子网转发，使用该功能前需要在配置中提前配置好 cidr 参数"
+ui_print "模块安装完成，重启设备生效"
@@ -0,0 +1,112 @@
+#!/system/bin/sh
+
+MODDIR=${0%/*}
+CONFIG_FILE="${MODDIR}/config/config.toml"
+COMMAND_ARGS="${MODDIR}/config/command_args"
+LOG_FILE="${MODDIR}/log.log"
+MODULE_PROP="${MODDIR}/module.prop"
+EASYTIER="${MODDIR}/easytier-core"
+
+# 处理获取到的设备型号中可能出现的空格
+BRAND=$(getprop ro.product.brand | tr ' ' '-')
+MODEL=$(getprop ro.product.model | tr ' ' '-')
+DEVICE_HOSTNAME="${BRAND}-${MODEL}"
+REDIR_STATUS=""
+
+# 更新 module.prop 文件中的 description
+update_module_description() {
+    local status_message=$1
+    # 检查 module.prop 文件存在且 description 发生变化了再写入
+    if [ -f "${MODULE_PROP}" ]; then
+        local current_desc=$(grep "^description=" "${MODULE_PROP}")
+        local new_desc="description=[状态] ${status_message}"
+        if [ "${current_desc}" != "${new_desc}" ]; then
+            sed -i "s#^description=.*#${new_desc}#" "${MODULE_PROP}"
+        fi
+    fi
+}
+
+# 检查并初始化 TUN 设备
+if [ ! -e /dev/net/tun ]; then
+    if [ ! -d /dev/net ]; then
+        mkdir -p /dev/net
+    fi
+    
+    ln -s /dev/tun /dev/net/tun
+fi
+
+while true; do
+    # 获取子网转发激活状态
+    if [ -f "${MODDIR}/enable_IP_rule" ]; then
+        REDIR_STATUS="转发已激活"
+    else
+        REDIR_STATUS="转发已禁用"
+    fi
+
+    # 检查模块是否被禁用
+    if [ -f "${MODDIR}/disable" ]; then
+        update_module_description "主程序已关闭 | ${REDIR_STATUS}"
+        if pgrep -f "${EASYTIER}" >/dev/null; then
+            echo "开关控制 $(date "+%Y-%m-%d %H:%M:%S") 进程已存在，正在关闭"
+            pkill -f "${EASYTIER}"
+        fi
+        sleep 10s
+        continue
+    fi
+    
+    # 检查进程是否已经在运行
+    if pgrep -f "${EASYTIER}" >/dev/null; then
+        sleep 10s
+        continue
+    fi
+    
+    # 检查配置文件是否存在
+    if [ ! -f "${CONFIG_FILE}" ] && [ ! -f "${COMMAND_ARGS}" ]; then
+        update_module_description "缺少配置文件或启动参数文件"
+        sleep 10s
+        continue
+    fi
+    
+    # 如果 config 目录下存在 command_args 文件，则读取其中的内容作为启动参数
+    if [ -f "${COMMAND_ARGS}" ]; then
+        # 启动参数模式
+        CMD_CONTENT=$(tr '\r\n' ' ' < "${COMMAND_ARGS}")
+        
+        if echo "${CMD_CONTENT}" | grep -q "\-\-hostname"; then
+            FINAL_ARGS="${CMD_CONTENT}"
+        else
+            FINAL_ARGS="${CMD_CONTENT} --hostname ${DEVICE_HOSTNAME}"
+        fi
+        
+        TZ=Asia/Shanghai "${EASYTIER}" ${FINAL_ARGS} > "${LOG_FILE}" 2>&1 &
+        STR_MODE="启动参数模式"
+        
+        # 否则读取 config.toml 的内容作为启动参数
+    else
+        # 配置文件模式
+        if grep -q "^[[:space:]]*hostname[[:space:]]*=" "${CONFIG_FILE}"; then
+            TZ=Asia/Shanghai "${EASYTIER}" -c "${CONFIG_FILE}" > "${LOG_FILE}" 2>&1 &
+        else
+            TZ=Asia/Shanghai "${EASYTIER}" -c "${CONFIG_FILE}" --hostname "${DEVICE_HOSTNAME}" > "${LOG_FILE}" 2>&1 &
+        fi
+        
+        STR_MODE="配置文件模式"
+    fi
+    
+    # 等待进程启动
+    sleep 5s
+    
+    # 启动后的扫尾工作
+    if pgrep -f "${EASYTIER}" >/dev/null; then
+        
+        if ! ip rule show | grep -qE '^[0-9]+:[[:space:]]+from all lookup main$'; then
+            ip rule add from all lookup main
+        fi
+        
+        update_module_description "主程序正在运行（${STR_MODE}）| ${REDIR_STATUS}"
+    else
+        update_module_description "主程序启动失败，请检查配置文件或启动参数"
+    fi
+    
+    sleep 10s
+done
@@ -0,0 +1,104 @@
+#!/system/bin/sh
+MODDIR=${0%/*}
+CONFIG_FILE="${MODDIR}/config/config.toml"
+LOG_FILE="${MODDIR}/log.log"
+ACTION="$1"  # 参数：add add_once del
+
+
+# 获取接口/IP
+get_et_iface() {
+    awk '
+        BEGIN { IGNORECASE = 1 }
+        /^[[:space:]]*dev_name[[:space:]]*=/ {
+            val = $0
+            sub(/^[^=]*=[[:space:]]*/, "", val)
+            gsub(/[" \t]/, "", val)
+            print val
+            exit
+        }
+    ' "$CONFIG_FILE"
+}
+get_tun_iface() {
+    ip link | awk -F': ' '/ tun[[:alnum:]]+/ {print $2; exit}'
+}
+get_hot_iface() {
+    ip link | awk -F': ' '/(^| )(swlan[[:alnum:]_]*|softap[[:alnum:]_]*|p2p-wlan[[:alnum:]_]*|ap[[:alnum:]_]*)\:/ {print $2; exit}' | cut -d'@' -f1 | head -n1
+}
+get_usb_iface() {
+    ip link | awk -F': ' '/(^| )(usb[[:alnum:]_]*|rndis[[:alnum:]_]*|eth[[:alnum:]_]*)\:/ {print $2; exit}' | cut -d'@' -f1 | head -n1
+}
+get_hot_cidr() {
+    ip -4 addr show dev "$1" | awk '/inet /{print $2; exit}'
+}
+
+
+set_nat_rules() {
+    ET_IFACE=$(get_et_iface)
+    [ -z "$ET_IFACE" ] && ET_IFACE="$(get_tun_iface)"
+    HOT_IFACE=$(get_hot_iface)
+    USB_IFACE=$(get_usb_iface)
+    HOT_CIDR=$(get_hot_cidr "$HOT_IFACE")
+    USB_CIDR=$(get_hot_cidr "$USB_IFACE")
+
+    # 如果热点关闭就删除自定义链
+   [ -n "$ET_IFACE" ] && { [ -n "$HOT_CIDR" ] || [ -n "$USB_CIDR" ]; } || return 1
+
+    # 创建自定义链（如不存在）
+    iptables -t nat -N ET_NAT 2>/dev/null
+    iptables -N ET_FWD 2>/dev/null
+
+    # 确保主链首条跳转到自定义链
+    iptables -t nat -C POSTROUTING -j ET_NAT 2>/dev/null || \
+        iptables -t nat -I POSTROUTING 1 -j ET_NAT
+    iptables -C FORWARD -j ET_FWD 2>/dev/null || \
+        iptables -I FORWARD 1 -j ET_FWD
+
+    # 添加规则
+    if [ -n "$HOT_CIDR" ]; then
+        iptables -t nat -A ET_NAT -s "$HOT_CIDR" -o "$ET_IFACE" -j MASQUERADE
+        iptables -A ET_FWD -i "$HOT_IFACE" -o "$ET_IFACE" \
+            -m state --state NEW,ESTABLISHED,RELATED -j ACCEPT
+        iptables -A ET_FWD -i "$ET_IFACE" -o "$HOT_IFACE" \
+            -m state --state ESTABLISHED,RELATED -j ACCEPT
+        echo "[ET-NAT] Rules applied: $HOT_IFACE $HOT_CIDR ↔ $ET_IFACE" >> "$LOG_FILE"
+    fi
+    if [ -n "$USB_CIDR" ]; then
+        iptables -t nat -A ET_NAT -s "$USB_CIDR" -o "$ET_IFACE" -j MASQUERADE
+        iptables -A ET_FWD -i "$USB_IFACE" -o "$ET_IFACE" \
+            -m state --state NEW,ESTABLISHED,RELATED -j ACCEPT
+        iptables -A ET_FWD -i "$ET_IFACE" -o "$USB_IFACE" \
+            -m state --state ESTABLISHED,RELATED -j ACCEPT
+        echo "[ET-NAT] Rules applied: $USB_IFACE $USB_CIDR ↔ $ET_IFACE" >> "$LOG_FILE"
+    fi
+}
+
+flush_rules() {
+    iptables -t nat -F ET_NAT 2>/dev/null
+    iptables -F ET_FWD 2>/dev/null
+    echo "[ET-NAT] Custom chains flushed." >> "$LOG_FILE"
+}
+
+case "$ACTION" in
+    add)
+        set_nat_rules
+        echo "[ET-NAT] Guard started." >> "$LOG_FILE"
+        ip monitor link addr | while read -r _; do
+            if [ -f "${MODDIR}/enable_IP_rule" ]; then
+                flush_rules
+                set_nat_rules
+            fi
+        done
+        ;;
+    add_once)
+        flush_rules
+        set_nat_rules
+        echo "[ET-NAT] One-time rules applied." >> "$LOG_FILE"
+        ;;
+    del)
+        flush_rules
+        ;;
+    *)
+        echo "Usage: $0 [add|del]"
+        exit 1
+        ;;
+esac
@@ -0,0 +1,6 @@
+{
+    "version": "v1.0",
+    "versionCode": 1,
+    "zipUrl": "",
+    "changelog": ""
+}
@@ -0,0 +1,7 @@
+id=easytier_magisk
+name=EasyTier_Magisk
+version=v2.6.4
+versionCode=1
+author=EasyTier
+description=easytier magisk module @EasyTier(https://github.com/EasyTier/EasyTier)
+updateJson=https://raw.githubusercontent.com/EasyTier/EasyTier/refs/heads/main/easytier-contrib/easytier-magisk/magisk_update.json
@@ -0,0 +1,24 @@
+#!/data/adb/magisk/busybox sh
+MODDIR=${0%/*}
+# MODDIR="$(dirname $(readlink -f "$0"))"
+chmod 755 ${MODDIR}/*
+
+# 等待系统启动成功
+while [ "$(getprop sys.boot_completed)" != "1" ]; do
+  sleep 5s
+done
+
+# 防止系统挂起
+echo "PowerManagerService.noSuspend" > /sys/power/wake_lock
+
+# 修改模块描述
+sed -i 's/$(description=)$[^"]*/\1[状态]关闭中/' "$MODDIR/module.prop"
+
+# 等待 3 秒
+sleep 3s
+
+"${MODDIR}/easytier_core.sh" &
+"${MODDIR}/hotspot_iprule.sh" add &
+
+# easytier_core.sh 和 hotspot_iprule.sh 都有内部循环做守护，
+# 所以这里不需要再做守护了
@@ -0,0 +1,2 @@
+nameserver 114.114.114.114
+nameserver 223.5.5.5
@@ -0,0 +1,5 @@
+MODDIR=${0%/*}
+pkill -f "${MODDIR}/easytier-core"
+
+# 使用 ${MODDIR:?} 确保变量非空，避免执行 rm -rf /*
+rm -rf "${MODDIR:?}/"*
@@ -0,0 +1,9 @@
+dist/
+target/
+.DS_Store
+.idea/
+package/libs
+
+*.har
+
+Cargo.lock
@@ -0,0 +1,60 @@
+[package]
+name = "easytier-ohrs"
+version = "0.1.0"
+edition = "2024"
+
+[lib]
+crate-type=["cdylib"]
+
+[dependencies]
+async-trait = "0.1"
+base64 = "0.22"
+flate2 = "1.1"
+gethostname = "1.1"
+easytier = { path = "../../easytier" }
+napi-derive-ohos = "1.1"
+napi-ohos = { version = "1.1", default-features = false, features = [
+    "serde-json",
+    "latin1",
+    "chrono_date",
+    "object_indexmap",
+    "tokio",
+    "async",
+    "tokio_rt",
+    "tokio_macros",
+    "tokio_io_util",
+    "deferred_trace",
+    "napi8",
+    "node_version_detect",
+    "web_stream",
+] }
+once_cell = "1.21.3"
+ipnet = "2.10"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0.125"
+prost-reflect = { version = "0.14.5", default-features = false, features = ["derive"] }
+rusqlite = { version = "0.32", features = ["bundled"] }
+tracing-subscriber = "0.3.19"
+tracing-core = "0.1.33"
+tracing = "0.1.41"
+tokio = { version = "1", features = ["rt-multi-thread", "sync", "time"] }
+url = "2.5"
+uuid = { version = "1.5.0", features = [
+    "v4",
+    "fast-rng",
+    "macro-diagnostics",
+    "serde",
+] }
+
+[build-dependencies]
+napi-build-ohos = "1.1"
+[profile.dev]
+panic = "unwind"
+debug = true
+
+[profile.release]
+panic = "abort"
+lto = true
+codegen-units = 1
+opt-level = 3
+strip = true
@@ -0,0 +1,65 @@
+# OpenHarmonyOS 项目构建说明
+
+本项目需要 OpenHarmonyOS SDK 和多个基础库支持才能成功编译。请按照以下步骤准备构建环境。
+如存在任何编译问题，请前往[Easytier for OHOS](https://github.com/FrankHan052176/EasyTier)
+
+## 前置要求
+
+### 1. 安装 OpenHarmonyOS SDK
+
+**SDK 下载链接**：  
+[OpenHarmony 每日构建版本](https://ci.openharmony.cn/workbench/cicd/dailybuild/dailylist)
+
+**版本要求**：  
+请选择版本号 **小于 OpenHarmony_5.1.0.58** 的 ohos-sdk-full 版本
+
+下载后请解压到适当位置（如 `/usr/local/ohos-sdk`），并记下安装路径。
+
+### 2. 编译依赖库
+在编译本项目前，需要先自行编译以下四个基础库：
+
+- glib
+- libffi
+- pcre2
+- zlib
+
+这些库需要使用 OpenHarmonyOS 的工具链进行交叉编译。
+
+## 环境配置
+
+### 1. 设置环境变量
+创建并运行以下脚本设置环境变量（请根据您的实际 SDK 安装路径修改）：
+
+```bash
+#!/bin/bash
+# 请修改为您的实际 SDK 路径
+export OHOS_SDK_PATH="/usr/local/ohos-sdk/linux"
+export OHOS_TOOLCHAIN_DIR="${OHOS_SDK_PATH}/native/llvm"
+export TARGET_ARCH="aarch64-linux-ohos"
+export OHOS_SYSROOT="${OHOS_SDK_PATH}/native/sysroot"
+export CC="${OHOS_TOOLCHAIN_DIR}/bin/aarch64-unknown-linux-ohos-clang"
+export CXX="${OHOS_TOOLCHAIN_DIR}/bin/aarch64-unknown-linux-ohos-clang++"
+export AS="${OHOS_TOOLCHAIN_DIR}/bin/llvm-as"
+export AR="${OHOS_TOOLCHAIN_DIR}/bin/llvm-ar"
+export LD="${OHOS_TOOLCHAIN_DIR}/bin/ld.lld"
+export RANLIB="${OHOS_TOOLCHAIN_DIR}/bin/llvm-ranlib"
+export STRIP="${OHOS_TOOLCHAIN_DIR}/bin/llvm-strip"
+export OBJDUMP="${OHOS_TOOLCHAIN_DIR}/bin/llvm-objdump"
+export OBJCOPY="${OHOS_TOOLCHAIN_DIR}/bin/llvm-objcopy"
+export NM="${OHOS_TOOLCHAIN_DIR}/bin/llvm-nm"
+export CFLAGS="-fPIC -D__MUSL__=1 -march=armv8-a --target=${TARGET_ARCH} -Wno-error --sysroot=${OHOS_SYSROOT} -I${OHOS_SYSROOT}/usr/include/${TARGET_ARCH}"
+export CXXFLAGS="${CFLAGS}"
+export LDFLAGS="--sysroot=${OHOS_SYSROOT} -L${OHOS_SYSROOT}/usr/lib/${TARGET_ARCH} -fuse-ld=${LD}"
+export PKG_CONFIG_PATH="${OHOS_SYSROOT}/usr/lib/pkgconfig:${OHOS_SYSROOT}/usr/local/lib/pkgconfig"
+export PKG_CONFIG_LIBDIR="${OHOS_SYSROOT}/usr/lib:${OHOS_SYSROOT}/usr/local/lib"
+export PKG_CONFIG_SYSROOT_DIR="${OHOS_SYSROOT}"
+export HOST_TRIPLET="${TARGET_ARCH}"
+export BUILD_TRIPLET="$(dpkg-architecture -qDEB_BUILD_GNU_TYPE)"
+export PATH="${OHOS_TOOLCHAIN_DIR}/bin:${PATH}"
+
+echo "OpenHarmonyOS 环境变量已设置:"
+echo "OHOS_SDK_PATH: ${OHOS_SDK_PATH}"
+echo "OHOS_TOOLCHAIN_DIR: ${OHOS_TOOLCHAIN_DIR}"
+echo "OHOS_SYSROOT: ${OHOS_SYSROOT}"
+echo "PKG_CONFIG_PATH: ${PKG_CONFIG_PATH}"
+echo "PATH: ${PATH}"
@@ -0,0 +1,3 @@
+fn main() {
+    napi_build_ohos::setup();
+}
@@ -0,0 +1,31 @@
+#!/bin/bash
+# 请修改为您的实际 SDK 路径
+export OHOS_TOOLCHAIN_DIR="${OHOS_NDK_HOME}/native/llvm"
+export TARGET_ARCH="aarch64-linux-ohos"
+export OHOS_SYSROOT="${OHOS_NDK_HOME}/native/sysroot"
+export CC="${OHOS_TOOLCHAIN_DIR}/bin/aarch64-unknown-linux-ohos-clang"
+export CXX="${OHOS_TOOLCHAIN_DIR}/bin/aarch64-unknown-linux-ohos-clang++"
+export AS="${OHOS_TOOLCHAIN_DIR}/bin/llvm-as"
+export AR="${OHOS_TOOLCHAIN_DIR}/bin/llvm-ar"
+export LD="${OHOS_TOOLCHAIN_DIR}/bin/ld.lld"
+export RANLIB="${OHOS_TOOLCHAIN_DIR}/bin/llvm-ranlib"
+export STRIP="${OHOS_TOOLCHAIN_DIR}/bin/llvm-strip"
+export OBJDUMP="${OHOS_TOOLCHAIN_DIR}/bin/llvm-objdump"
+export OBJCOPY="${OHOS_TOOLCHAIN_DIR}/bin/llvm-objcopy"
+export NM="${OHOS_TOOLCHAIN_DIR}/bin/llvm-nm"
+export CFLAGS="-fPIC -D__MUSL__=1 -march=armv8-a --target=${TARGET_ARCH} -Wno-error --sysroot=${OHOS_SYSROOT} -I${OHOS_SYSROOT}/usr/include/${TARGET_ARCH}"
+export CXXFLAGS="${CFLAGS}"
+export LDFLAGS="--sysroot=${OHOS_SYSROOT} -L${OHOS_SYSROOT}/usr/lib/${TARGET_ARCH} -fuse-ld=${LD}"
+export PKG_CONFIG_PATH="${OHOS_SYSROOT}/usr/lib/pkgconfig:${OHOS_SYSROOT}/usr/local/lib/pkgconfig"
+export PKG_CONFIG_LIBDIR="${OHOS_SYSROOT}/usr/lib:${OHOS_SYSROOT}/usr/local/lib"
+export PKG_CONFIG_SYSROOT_DIR="${OHOS_SYSROOT}"
+export HOST_TRIPLET="${TARGET_ARCH}"
+export BUILD_TRIPLET="$(dpkg-architecture -qDEB_BUILD_GNU_TYPE)"
+export PATH="${OHOS_TOOLCHAIN_DIR}/bin:${PATH}"
+
+echo "OpenHarmonyOS 环境变量已设置:"
+echo "OHOS_SDK_PATH: ${OHOS_NDK_HOME}"
+echo "OHOS_TOOLCHAIN_DIR: ${OHOS_TOOLCHAIN_DIR}"
+echo "OHOS_SYSROOT: ${OHOS_SYSROOT}"
+echo "PKG_CONFIG_PATH: ${PKG_CONFIG_PATH}"
+echo "PATH: ${PATH}"
@@ -0,0 +1,2 @@
+# 0.0.1
+- init package
--- a/Show More
+++ b/Show More
				`@@ -0,0 +1 @@`
				`--config-server udp://127.0.0.1:22020/admin --machine-id easytier-magisk`