feat(mini): add compact native EasyTier client (#2479)

Add a native EasyTier proof-of-concept binary with TCP and UDP transports, TUN, UDP hole punching, AES-GCM, and a read-only RPC portal. Introduce a release-derived mini profile and musl linker policy so x86_64, big-endian MIPS, and little-endian MIPS stay below the strict 5,000,000-byte target without UPX.
2026-09-02 17:15:43 +00:00 · 2026-08-09 19:43:30 +08:00
parent 1e40350c89
commit d375d7e455
47 changed files with 1688 additions and 302 deletions
@@ -0,0 +1,21 @@
+[package]
+name = "easytier-mini"
+description = "Minimal native EasyTier node with TCP/UDP tunnels, TUN and UDP hole punching."
+version = "2.6.4"
+edition.workspace = true
+rust-version.workspace = true
+license-file = "../../LICENSE"
+build = "build.rs"
+
+[dependencies]
+anyhow = "1.0"
+easytier = { path = "../../easytier", version = "2.6.4", default-features = false, features = [
+    "aes-gcm",
+    "dhcp-ipv4",
+    "logging",
+    "proxy-cidr-monitor",
+    "smoltcp",
+    "tun",
+    "web-client",
+] }
+tokio = { version = "1", default-features = false, features = ["macros", "rt", "signal"] }
@@ -0,0 +1,113 @@
+# easytier-mini
+
+`easytier-mini` is a native EasyTier POC binary. It shares EasyTier's TOML
+configuration model, peer protocol, TCP/UDP tunnel implementations, TUN,
+dynamic IPv4 allocation, the smoltcp userspace path and STUN/UDP hole-punching
+core with the full binary. It includes AES-GCM so its default encryption
+setting interoperates with the full binary's default configuration.
+
+Build it with:
+
+```sh
+cargo build --release -p easytier-mini
+```
+
+For the static size target used by this POC:
+
+```sh
+cargo build --profile mini --target x86_64-unknown-linux-musl -p easytier-mini
+```
+
+MIPS targets use the repository's existing musl-cross toolchains. The helper
+builds the standard library for size, applies immediate-abort only to the mini
+MIPS target graph, and can build either or both byte orders:
+
+```sh
+./easytier-contrib/easytier-mini/build-mips.sh all
+./easytier-contrib/easytier-mini/build-mips.sh mips
+./easytier-contrib/easytier-mini/build-mips.sh mipsel
+```
+
+The `mini` profile derives from `release` and applies `opt-level=z` to the
+entire compact binary dependency graph. Full EasyTier release builds retain
+their normal `opt-level=3` profile. The musl builds use a mini-only static
+linker policy to stay below 5,000,000 bytes on x86-64 and 5,500,000 bytes on
+MIPS without UPX or another executable compressor. The compact x86-64 linker
+policy retains static PIE, packs relative relocations and folds identical code.
+MIPS builds omit standard-library backtrace support and use immediate abort;
+normal workspace MIPS builds are not affected. Compact linker policies omit
+unwind tables.
+
+Start it with a normal EasyTier TOML file:
+
+```sh
+easytier-mini --config mini.toml
+```
+
+`-c` is accepted as the short form of `--config`.
+
+Start it as an EasyTier Web managed node with a complete config-server URL:
+
+```sh
+easytier-mini --config-server udp://config-server.easytier.cn:22020/TOKEN
+```
+
+`--machine-id`, `--hostname`, and `--secure-mode` match the full client's Web
+identity and transport options. `--config` and `--config-server` may be used
+together: the local instance remains static while Web-owned instances are
+created, updated, retained, and deleted independently.
+
+The node also exposes the native EasyTier management RPC protocol on
+`127.0.0.1:15888`, so the full `easytier-cli` can inspect it:
+
+```sh
+easytier-cli node info
+easytier-cli peer
+easytier-cli route
+easytier-cli connector list
+```
+
+For example:
+
+```toml
+instance_name = "mini"
+ipv4 = "10.147.0.2"
+listeners = ["tcp://0.0.0.0:11010", "udp://0.0.0.0:11010"]
+
+[network_identity]
+network_name = "mini-poc"
+network_secret = "change-me"
+
+[[peer]]
+uri = "tcp://example.net:11010"
+```
+
+Local TOML and Web configuration both retain the complete authoritative model.
+The compact runtime silently omits unsupported capabilities while normalizing
+that model into live runtime state. EasyTier Web therefore sees every accepted
+configuration value unchanged and its consistency checks converge. This also
+applies to hot patches: for example, a port-forward patch remains visible to
+the controller while no port-forward service starts in mini. ChaCha20 falls
+back to AES-GCM rather than plaintext.
+
+The compact runtime supports `tcp://` and `udp://` listener, mapped-listener
+and peer URLs. `no_tun = true` runs through smoltcp without an OS TUN device,
+and `dhcp = true` allocates the virtual IPv4 address dynamically.
+
+The mini feature set keeps STUN collection, UDP hole punching, Web heartbeats,
+Web instance lifecycle management and the config hot-patch RPC. It omits TCP
+hole punching, endpoint discovery (`http://`, `https://`, `txt://` and
+`srv://` peers), protobuf reflection, logger control and the rest of the full
+management surface. Unsupported connector URLs are accepted as no-ops. Its
+local RPC surface remains read-only for node, peer, route and connector
+queries. OSPF route messages keep their original protobuf wire data, so fields
+added by future EasyTier versions are forwarded without requiring
+`prost-reflect`.
+
+For size, this POC reads one file directly and does not support configuration
+from stdin or `${VAR}` expansion. It omits the process-management event journal,
+while the console logger still reports runtime events such as peer, connection,
+listener, TUN and DHCP changes. The RPC address is currently fixed, so only one
+mini process can use the default portal on a host. The x86-64 musl POC cannot
+provide reliable stack backtraces because its release binary has no unwind
+tables.
@@ -0,0 +1,61 @@
+#!/bin/sh
+set -eu
+
+# Cargo invokes this same file as a rustc wrapper during compact MIPS builds.
+# Applying immediate-abort here keeps the size policy scoped to easytier-mini;
+# normal MIPS builds elsewhere in the workspace retain their panic behavior.
+if [ "${EASYTIER_MINI_MIPS_RUSTC_WRAPPER:-}" = "1" ]; then
+    mini_rustc=$1
+    shift
+    for mini_rustc_arg in "$@"; do
+        case "$mini_rustc_arg" in
+            mips-unknown-linux-musl|mipsel-unknown-linux-musl)
+                exec "$mini_rustc" "$@" \
+                    -Zunstable-options \
+                    -Cpanic=immediate-abort
+                ;;
+        esac
+    done
+    exec "$mini_rustc" "$@"
+fi
+
+mini_script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+mini_repo_dir=$(CDPATH= cd -- "$mini_script_dir/../.." && pwd)
+mini_requested_target=${1:-all}
+cd "$mini_repo_dir"
+
+build_mips_target() {
+    mini_target=$1
+    mini_toolchain=$2
+    PATH="$mini_repo_dir/musl_gcc/$mini_toolchain/bin:$PATH" \
+        EASYTIER_MINI_MIPS_RUSTC_WRAPPER=1 \
+        RUSTC_BOOTSTRAP=1 \
+        RUSTC_WRAPPER="$mini_script_dir/build-mips.sh" \
+        cargo build \
+            --manifest-path "$mini_repo_dir/Cargo.toml" \
+            --profile mini \
+            --target "$mini_target" \
+            -Z build-std=std \
+            -Z build-std-features=optimize_for_size \
+            -p easytier-mini
+}
+
+case "$mini_requested_target" in
+    all)
+        build_mips_target mips-unknown-linux-musl mips-unknown-linux-muslsf
+        build_mips_target mipsel-unknown-linux-musl mipsel-unknown-linux-muslsf
+        ;;
+    mips|mips-unknown-linux-musl)
+        build_mips_target mips-unknown-linux-musl mips-unknown-linux-muslsf
+        ;;
+    mipsel|mipsel-unknown-linux-musl)
+        build_mips_target mipsel-unknown-linux-musl mipsel-unknown-linux-muslsf
+        ;;
+    -h|--help)
+        echo "usage: $0 [all|mips|mipsel]"
+        ;;
+    *)
+        echo "unsupported MIPS target: $mini_requested_target" >&2
+        exit 2
+        ;;
+esac
@@ -0,0 +1,32 @@
+use std::env;
+use std::path::PathBuf;
+
+fn main() {
+    let target = env::var("TARGET").unwrap_or_default();
+    let profile = env::var("PROFILE").unwrap_or_default();
+    if !matches!(profile.as_str(), "release" | "mini")
+        || !matches!(
+            target.as_str(),
+            "x86_64-unknown-linux-musl" | "mips-unknown-linux-musl" | "mipsel-unknown-linux-musl"
+        )
+    {
+        return;
+    }
+
+    let script =
+        PathBuf::from(env::var_os("CARGO_MANIFEST_DIR").unwrap()).join("easytier-mini-musl.ld");
+    println!("cargo:rerun-if-changed={}", script.display());
+    // The release-derived mini profile already aborts panics. Keep the compact
+    // binary's linker policy local so full EasyTier musl builds retain their
+    // normal PIE/unwind settings.
+    println!("cargo:rustc-link-arg-bin=easytier-mini=-Wl,--build-id=none");
+    if target == "x86_64-unknown-linux-musl" {
+        println!("cargo:rustc-link-arg-bin=easytier-mini=-Wl,--pack-dyn-relocs=relr");
+        println!("cargo:rustc-link-arg-bin=easytier-mini=-Wl,--icf=all");
+    }
+    println!("cargo:rustc-link-arg-bin=easytier-mini=-Wl,--no-eh-frame-hdr");
+    println!(
+        "cargo:rustc-link-arg-bin=easytier-mini=-Wl,-T,{}",
+        script.display()
+    );
+}
@@ -0,0 +1,14 @@
+SECTIONS
+{
+  .eh_frame :
+  {
+    KEEP(*crtbegin.o(.eh_frame))
+    KEEP(*crtend.o(.eh_frame))
+  }
+  /DISCARD/ :
+  {
+    *(EXCLUDE_FILE (*crtbegin.o *crtend.o) .eh_frame)
+    *(.eh_frame_hdr)
+  }
+}
+INSERT AFTER .data;
@@ -0,0 +1,264 @@
+use std::{ffi::OsString, path::PathBuf, sync::Arc};
+
+use anyhow::Context as _;
+use easytier::common::MachineIdOptions;
+use easytier::{
+    common::config::{ConfigFileControl, load_toml_config_from_path},
+    instance::factory::native_compact_instance_manager_with_runtime,
+    rpc_service::ReadOnlyApiRpcServer,
+    web_client::{WebClientHooks, parse_config_server_endpoint, run_web_client},
+};
+
+enum Command {
+    Run(RunOptions),
+    Exit,
+}
+
+#[derive(Debug, Default, PartialEq, Eq)]
+struct RunOptions {
+    config: Option<PathBuf>,
+    config_server: Option<String>,
+    machine_id: Option<String>,
+    hostname: Option<String>,
+    secure_mode: bool,
+}
+
+const USAGE: &str = "usage: easytier-mini [--config <FILE>] [--config-server <URL>] \
+                     [--machine-id <ID>] [--hostname <NAME>] [--secure-mode]";
+
+fn required_value(
+    args: &mut impl Iterator<Item = OsString>,
+    option: &str,
+) -> anyhow::Result<OsString> {
+    args.next()
+        .with_context(|| format!("{option} requires a value"))
+}
+
+fn parse_args(mut args: impl Iterator<Item = OsString>) -> anyhow::Result<Command> {
+    let mut options = RunOptions::default();
+    while let Some(arg) = args.next() {
+        if arg == "-h" || arg == "--help" {
+            println!(
+                "easytier-mini {}\n\nUsage: {USAGE}",
+                env!("CARGO_PKG_VERSION")
+            );
+            return Ok(Command::Exit);
+        }
+        if arg == "-V" || arg == "--version" {
+            println!("easytier-mini {}", env!("CARGO_PKG_VERSION"));
+            return Ok(Command::Exit);
+        }
+        if arg == "-c" || arg == "--config" {
+            if options.config.is_some() {
+                anyhow::bail!("--config may only be specified once");
+            }
+            options.config = Some(PathBuf::from(required_value(&mut args, "--config")?));
+            continue;
+        }
+        if arg == "-w" || arg == "--config-server" {
+            if options.config_server.is_some() {
+                anyhow::bail!("--config-server may only be specified once");
+            }
+            options.config_server = Some(
+                required_value(&mut args, "--config-server")?
+                    .into_string()
+                    .map_err(|_| anyhow::anyhow!("--config-server must be valid UTF-8"))?,
+            );
+            continue;
+        }
+        if arg == "--machine-id" {
+            options.machine_id = Some(
+                required_value(&mut args, "--machine-id")?
+                    .into_string()
+                    .map_err(|_| anyhow::anyhow!("--machine-id must be valid UTF-8"))?,
+            );
+            continue;
+        }
+        if arg == "--hostname" {
+            options.hostname = Some(
+                required_value(&mut args, "--hostname")?
+                    .into_string()
+                    .map_err(|_| anyhow::anyhow!("--hostname must be valid UTF-8"))?,
+            );
+            continue;
+        }
+        if arg == "--secure-mode" {
+            options.secure_mode = true;
+            continue;
+        }
+        anyhow::bail!("unknown argument {arg:?}; {USAGE}");
+    }
+    if options.config.is_none() && options.config_server.is_none() {
+        anyhow::bail!("either --config or --config-server is required; {USAGE}");
+    }
+    Ok(Command::Run(options))
+}
+
+fn require_tcp_or_udp(scheme: &str, source: &str) -> anyhow::Result<()> {
+    match scheme {
+        "tcp" | "udp" => Ok(()),
+        scheme => anyhow::bail!(
+            "{source} uses unsupported tunnel scheme {scheme:?}; easytier-mini supports only tcp:// and udp://"
+        ),
+    }
+}
+
+fn validate_config_server(config_server: &str) -> anyhow::Result<()> {
+    let endpoint = parse_config_server_endpoint(config_server)?;
+    require_tcp_or_udp(endpoint.connect_url().scheme(), "config server")
+}
+
+struct MiniWebClientHooks;
+
+impl WebClientHooks for MiniWebClientHooks {
+    fn manages_remote_config_instances(&self) -> bool {
+        true
+    }
+}
+
+#[tokio::main(flavor = "current_thread")]
+async fn main() -> anyhow::Result<()> {
+    let Command::Run(options) = parse_args(std::env::args_os().skip(1))? else {
+        return Ok(());
+    };
+    easytier::common::log::init_console()?;
+    let local_config = options
+        .config
+        .as_ref()
+        .map(|config_path| {
+            load_toml_config_from_path(config_path)
+                .with_context(|| format!("failed to load {}", config_path.display()))
+        })
+        .transpose()?;
+    if let Some(config_server) = options.config_server.as_deref() {
+        validate_config_server(config_server)?;
+    }
+
+    let instances = Arc::new(native_compact_instance_manager_with_runtime(
+        tokio::runtime::Handle::current(),
+    ));
+    let local_instance_id = local_config
+        .map(|config| instances.run_network_instance(config, ConfigFileControl::STATIC_CONFIG))
+        .transpose()?;
+    let _web_client = if let Some(config_server) = options.config_server.as_deref() {
+        Some(
+            run_web_client(
+                config_server,
+                MachineIdOptions {
+                    explicit_machine_id: options.machine_id,
+                    state_dir: None,
+                },
+                options.hostname,
+                options.secure_mode,
+                instances.clone(),
+                Some(Arc::new(MiniWebClientHooks)),
+            )
+            .await?,
+        )
+    } else {
+        None
+    };
+    let _rpc_server =
+        ReadOnlyApiRpcServer::new(Some("127.0.0.1:15888".to_owned()), None, instances.clone())?
+            .serve()
+            .await?;
+    eprintln!(
+        "easytier-mini started: local={local_instance_id:?}, web={}; RPC: 127.0.0.1:15888",
+        options.config_server.is_some()
+    );
+
+    let stopped_unexpectedly = tokio::select! {
+        signal = tokio::signal::ctrl_c() => {
+            signal.context("failed to listen for Ctrl-C")?;
+            false
+        },
+        _ = instances.wait() => true,
+    };
+
+    for instance in instances.instances() {
+        instance.stop().await;
+    }
+    if stopped_unexpectedly {
+        anyhow::bail!("EasyTier instance stopped unexpectedly");
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use easytier::common::config::{ConfigLoader as _, TomlConfigLoader};
+
+    #[test]
+    fn parses_minimal_config_argument() {
+        let Command::Run(options) =
+            parse_args([OsString::from("--config"), OsString::from("mini.toml")].into_iter())
+                .unwrap()
+        else {
+            panic!("expected run command");
+        };
+
+        assert_eq!(options.config, Some(PathBuf::from("mini.toml")));
+    }
+
+    #[test]
+    fn parses_web_client_arguments_without_a_local_config() {
+        let Command::Run(options) = parse_args(
+            [
+                OsString::from("--config-server"),
+                OsString::from("token"),
+                OsString::from("--machine-id"),
+                OsString::from("machine"),
+                OsString::from("--hostname"),
+                OsString::from("mini"),
+                OsString::from("--secure-mode"),
+            ]
+            .into_iter(),
+        )
+        .unwrap() else {
+            panic!("expected run command");
+        };
+
+        assert_eq!(options.config_server.as_deref(), Some("token"));
+        assert_eq!(options.machine_id.as_deref(), Some("machine"));
+        assert_eq!(options.hostname.as_deref(), Some("mini"));
+        assert!(options.secure_mode);
+    }
+
+    #[test]
+    fn rejects_unknown_arguments() {
+        let result = parse_args([OsString::from("extra")].into_iter());
+
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn accepts_tcp_udp_config_server() {
+        assert!(validate_config_server("udp://127.0.0.1:22020/token").is_ok());
+        assert!(validate_config_server("quic://127.0.0.1:22020/token").is_err());
+    }
+
+    #[tokio::test]
+    async fn compact_factory_accepts_unsupported_config_without_changing_it() {
+        let config = TomlConfigLoader::new_from_str(
+            r#"
+dhcp = true
+listeners = ["quic://127.0.0.1:11010"]
+proxy_network = [{ cidr = "10.20.0.0/16" }]
+
+[flags]
+encryption_algorithm = "chacha20"
+data_compress_algo = "Zstd"
+"#,
+        )
+        .unwrap();
+        config.get_id();
+        let before = config.dump();
+        let manager =
+            native_compact_instance_manager_with_runtime(tokio::runtime::Handle::current());
+
+        let instance = manager.create(config, ()).unwrap();
+
+        assert_eq!(instance.toml_config().unwrap().dump(), before);
+    }
+}