Merge pull request #65 from loss-and-quick/feat/proxy-mode

feat(desktop): proxy mode selection (tun / proxy-only / system / pac)

Author: loss-and-quick

crates/kasumi-backend/src/commands.rs

@@ -229,14 +229,15 @@ pub(crate) async fn build_profile_config(
         .find(|p| p.meta().id == id)
         .ok_or_else(|| err(format!("profile not found: {id}")))?;
     let srs_dir = paths.srs_dir.to_str().unwrap_or("");
-    let mut built = build_core_config(
-        profile,
-        &state.settings,
-        &state.routing_rules,
-        &profiles,
-        srs_dir,
-    )
-    .map_err(err)?;
+    let mut settings = state.settings;
+    if !platform.supports_proxy_modes() {
+        // A platform that always runs tun (the Android root module) must not have
+        // its tun inbound stripped by a non-tun proxyMode — e.g. one restored from
+        // a desktop backup.
+        settings.proxy_mode = kasumi_core::state::ProxyMode::Tun;
+    }
+    let mut built = build_core_config(profile, &settings, &state.routing_rules, &profiles, srs_dir)
+        .map_err(err)?;
     platform.tune_config(built.engine, &mut built.config);
     Ok(built)
 }

crates/kasumi-backend/src/lifecycle.rs

@@ -12,10 +12,10 @@ use regex::Regex;
 use tokio::process::Child;
 
 use kasumi_core::core::default_tun_for;
-use kasumi_core::enums::{CoreEngine, TunEngine, tun_from_marker};
+use kasumi_core::enums::{CoreEngine, NO_TUN_MARKER, TunEngine, tun_from_marker};
 use kasumi_core::hev_config::build_hev_config;
 use kasumi_core::singbox_config::build_singbox_bridge_config;
-use kasumi_core::state::{AppState, DEFAULT_LOCAL_SOCKS_PORT};
+use kasumi_core::state::{AppState, DEFAULT_LOCAL_SOCKS_PORT, ProxyMode};
 use kasumi_core::tun2socks_config::build_tun2socks_config;
 // Aliased: `tun` alone would shadow the many `tun: TunEngine` params here.
 use kasumi_core::tun as tun_addr;
@@ -24,7 +24,7 @@ use kasumi_core::tun::TunOptions;
 use crate::commands::{CommandError, build_profile_config};
 use crate::fs::{exists, read_text, remove_file, write_text};
 use crate::fsjson::{read_json, write_text_atomic};
-use crate::platform::{Engine, Platform};
+use crate::platform::{Platform, StartDataPath};
 use crate::proc::{RunOpts, pid_matches_bin, run, spawn_logged};
 
 /// Map a hex digit to a consonant so the interface name starts with a letter
@@ -58,12 +58,12 @@ pub fn random_tun_iface() -> String {
 }
 
 /// Build the config for `profile_id` (else the active profile), write it and the
-/// engine marker, and return the engine + resolved TUN engine + external-engine
-/// tuning + local SOCKS port.
+/// engine marker, and return the resolved [`StartDataPath`] (engine, TUN engine,
+/// external-engine tuning, SOCKS port, proxy mode).
 pub async fn resolve_and_write_config(
     platform: &dyn Platform,
     profile_id: Option<&str>,
-) -> Result<(Engine, TunEngine, TunOptions, u16), CommandError> {
+) -> Result<StartDataPath, CommandError> {
     let paths = platform.paths();
     let state = read_json::<AppState>(&paths.app_state).await;
     let id = profile_id
@@ -91,7 +91,20 @@ pub async fn resolve_and_write_config(
         .local_socks_port
         .unwrap_or(DEFAULT_LOCAL_SOCKS_PORT);
     let tun_opts = settings.tun_options();
-    Ok((engine, tun, tun_opts, socks_port))
+    // Same normalization as the config build: a platform without proxy-mode
+    // support always starts in tun mode.
+    let mode = if platform.supports_proxy_modes() {
+        settings.proxy_mode
+    } else {
+        ProxyMode::Tun
+    };
+    Ok(StartDataPath {
+        engine,
+        tun,
+        tun_opts,
+        socks_port,
+        mode,
+    })
 }
 
 /// The core engine's on-disk label (written to `paths.engine_file` at config
@@ -130,6 +143,11 @@ pub fn running_external_engine(
     marker: Option<&str>,
     engine_label: Option<&str>,
 ) -> Option<TunEngine> {
+    // A no-tun data-path (proxy-only/system/pac) runs no helper whatever the
+    // core — never fall back to the engine default there.
+    if marker.map(str::trim) == Some(NO_TUN_MARKER) {
+        return None;
+    }
     let core = engine_label.and_then(core_from_label);
     if let Some(tun) = marker.map(str::trim).and_then(tun_from_marker) {
         // Native only when we're sure it's the sing-box core with its own tun; an
@@ -522,6 +540,16 @@ mod tests {
             running_external_engine(Some("  \n"), Some("xray")),
             Some(TunEngine::Tun2socks)
         );
+        // A no-tun data-path expects no helper, even for xray (no engine-default
+        // fallback).
+        assert_eq!(
+            running_external_engine(Some(NO_TUN_MARKER), Some("xray")),
+            None
+        );
+        assert_eq!(
+            running_external_engine(Some("no-tun\n"), Some("sing-box")),
+            None
+        );
     }
 
     #[test]
@@ -572,10 +600,12 @@ mod tests {
             .unwrap();
 
         // No explicit id → uses active_id.
-        let (engine, tun, _tun_opts, socks) = resolve_and_write_config(&p, None).await.unwrap();
-        assert_eq!(engine, CoreEngine::Xray);
-        assert_eq!(tun, TunEngine::Tun2socks);
-        assert_eq!(socks, 11080);
+        let opts = resolve_and_write_config(&p, None).await.unwrap();
+        assert_eq!(opts.engine, CoreEngine::Xray);
+        assert_eq!(opts.tun, TunEngine::Tun2socks);
+        assert_eq!(opts.socks_port, 11080);
+        // TestPlatform doesn't support proxy modes → always normalized to tun.
+        assert_eq!(opts.mode, ProxyMode::Tun);
         assert_eq!(
             read_text(&p.paths().engine_file).await.as_deref(),
             Some("xray")

crates/kasumi-backend/src/platform.rs

@@ -10,6 +10,7 @@ use tokio::sync::mpsc;
 
 use kasumi_core::contract::{LogTarget, ServiceState};
 use kasumi_core::enums::{CoreEngine, TunEngine};
+use kasumi_core::state::ProxyMode;
 use kasumi_core::tun::TunOptions;
 
 use crate::lifecycle::spawn_core;
@@ -127,12 +128,17 @@ pub struct StartDataPath {
     pub engine: Engine,
     /// The resolved TUN engine. `SingboxTun` uses the core's own tun (native for
     /// sing-box); `Tun2socks`/`Hev` front a socks-only core with an external tun.
+    /// Ignored when `mode` runs no tun.
     pub tun: TunEngine,
     /// External-engine tuning (mtu, buffers, timeouts, …), resolved once from the
     /// settings so the data-path owner (incl. the desktop root helper, across the
     /// privilege boundary) needn't re-read the settings schema.
     pub tun_opts: TunOptions,
     pub socks_port: u16,
+    /// How to capture traffic: `tun` brings up the tun device + routing; the other
+    /// modes run the core on its local socks/http inbound alone. Already
+    /// normalized to `Tun` for platforms without proxy-mode support.
+    pub mode: ProxyMode,
 }
 
 /// Options for [`Platform::stop_data_path`].
@@ -162,13 +168,34 @@ pub trait Platform: Send + Sync {
         Ok(())
     }
 
+    /// Whether this platform honours the non-tun proxy modes (proxy-only / system /
+    /// pac). Where it doesn't (the Android root module), config build and start
+    /// normalize `proxyMode` to `tun` — so e.g. a restored desktop backup carrying
+    /// a non-tun mode can't strip the tun inbound out from under the data path.
+    fn supports_proxy_modes(&self) -> bool {
+        false
+    }
+
     /// Spawn the core for `engine` from the on-disk config and route traffic through
     /// it. Resolves once the core is confirmed up, or errors with a reason.
     async fn start_data_path(&self, opts: StartDataPath) -> anyhow::Result<()>;
 
     /// Stop the core/helpers and remove all routing. Idempotent.
     async fn stop_data_path(&self, opts: StopDataPath) -> anyhow::Result<()>;
 
+    /// Align the OS-level proxy with `mode` after a successful data-path start:
+    /// point the OS at the core's local inbound where the mode asks for it
+    /// (`system`/`pac`), clear any previously-set one otherwise — so a mode switch
+    /// can't leave a stale OS proxy behind. Runs in the client process (GUI /
+    /// daemon), never the privileged helper: the OS proxy lives in the logged-in
+    /// user's session (gsettings / D-Bus / HKCU), which the helper's isn't.
+    /// Default: no-op for platforms without an OS-proxy integration.
+    async fn set_os_proxy(&self, _mode: ProxyMode, _engine: Engine, _socks_port: u16) {}
+
+    /// Clear any OS-level proxy [`Platform::set_os_proxy`] may have set. Idempotent;
+    /// called on every data-path stop whatever the mode. Default: no-op.
+    async fn clear_os_proxy(&self) {}
+
     /// Current data-path status (liveness + traffic counters).
     async fn service_state(&self) -> anyhow::Result<ServiceState>;
 

crates/kasumi-backend/src/service.rs

@@ -22,7 +22,7 @@ use crate::fs::read_text;
 use crate::fsjson::read_json;
 use crate::lifecycle::resolve_and_write_config;
 use crate::net::{FetchUrlOptions, fetch_url};
-use crate::platform::{Platform, StartDataPath, StopDataPath};
+use crate::platform::{Platform, StopDataPath};
 use crate::sub_update::{self, LifecycleControl};
 
 /// Result of the latest end-to-end connectivity probe (a fetch through the active
@@ -149,25 +149,29 @@ impl Service {
                     })
                     .await
                     .map_err(|e| e.to_string())?;
-                let (engine, tun, tun_opts, socks_port) =
-                    resolve_and_write_config(&*self.platform, id.as_deref())
-                        .await
-                        .map_err(|e| e.0)?;
+                let opts = resolve_and_write_config(&*self.platform, id.as_deref())
+                    .await
+                    .map_err(|e| e.0)?;
+                let (mode, engine, socks_port) = (opts.mode, opts.engine, opts.socks_port);
+                if let Err(e) = self.platform.start_data_path(opts).await {
+                    // A failed bring-up must not leave a previously-set OS proxy
+                    // pointing at a dead port.
+                    self.platform.clear_os_proxy().await;
+                    return Err(e.to_string());
+                }
+                // With the data-path up, align the OS proxy with the mode (set for
+                // system/pac, cleared otherwise — covers mode switches).
+                self.platform.set_os_proxy(mode, engine, socks_port).await;
+                Ok(())
+            }
+            LifecycleCmd::Stop => {
+                // A stopped core must never leave the OS pointed at a dead port.
+                self.platform.clear_os_proxy().await;
                 self.platform
-                    .start_data_path(StartDataPath {
-                        engine,
-                        tun,
-                        tun_opts,
-                        socks_port,
-                    })
+                    .stop_data_path(StopDataPath::default())
                     .await
                     .map_err(|e| e.to_string())
             }
-            LifecycleCmd::Stop => self
-                .platform
-                .stop_data_path(StopDataPath::default())
-                .await
-                .map_err(|e| e.to_string()),
             LifecycleCmd::ReloadAppFilter => {
                 // xray reloads per-uid rules live; sing-box bakes them into the
                 // config and needs a full restart.
@@ -182,17 +186,11 @@ impl Service {
                         })
                         .await
                         .map_err(|e| e.to_string())?;
-                    let (engine, tun, tun_opts, socks_port) =
-                        resolve_and_write_config(&*self.platform, None)
-                            .await
-                            .map_err(|e| e.0)?;
+                    let opts = resolve_and_write_config(&*self.platform, None)
+                        .await
+                        .map_err(|e| e.0)?;
                     self.platform
-                        .start_data_path(StartDataPath {
-                            engine,
-                            tun,
-                            tun_opts,
-                            socks_port,
-                        })
+                        .start_data_path(opts)
                         .await
                         .map_err(|e| e.to_string())
                 } else if let Some(f) = self.platform.app_filter() {

crates/kasumi-core/src/core_config.rs

@@ -8,7 +8,7 @@ use crate::core::{resolve_core, resolve_tun};
 use crate::enums::{CoreEngine, TunEngine};
 use crate::profile::Profile;
 use crate::singbox_config::{SingboxBuildOpts, build_singbox_config};
-use crate::state::{AdvancedSettings, RoutingRule};
+use crate::state::{AdvancedSettings, ProxyMode, RoutingRule};
 use crate::xray_config::build_xray_config;
 
 /// Engine + TUN engine + config JSON for a profile, mirroring what the core is
@@ -42,9 +42,11 @@ pub fn build_core_config(
             routing_rules,
             profiles,
             SingboxBuildOpts {
-                // An external tun engine fronts sing-box → build it socks-only
-                // (no native tun inbound). SingboxTun keeps the native tun.
-                no_tun: tun != TunEngine::SingboxTun,
+                // Socks-only (no native tun inbound) when an external tun engine
+                // fronts sing-box, or when the proxy mode runs no tun at all
+                // (proxy-only/system/pac). SingboxTun in tun mode keeps the native
+                // tun. Xray is already inbound-only either way.
+                no_tun: settings.proxy_mode != ProxyMode::Tun || tun != TunEngine::SingboxTun,
                 srs_dir,
             },
         )?,
@@ -118,6 +120,24 @@ mod tests {
         );
     }
 
+    #[test]
+    fn non_tun_proxy_mode_is_socks_only() {
+        let sb = parse_share_link("tuic://u:pw@t.ex:443?sni=t.ex", None).unwrap();
+        // Any non-tun mode drops the native tun inbound even for SingboxTun; the
+        // local mixed inbound stays as the whole data path.
+        for mode in [ProxyMode::ProxyOnly, ProxyMode::System, ProxyMode::Pac] {
+            let s = AdvancedSettings {
+                proxy_mode: mode,
+                ..Default::default()
+            };
+            let c = build_core_config(&sb, &s, &[], std::slice::from_ref(&sb), "").unwrap();
+            assert_eq!(c.tun, TunEngine::SingboxTun);
+            let inbounds = c.config["inbounds"].as_array().unwrap();
+            assert!(inbounds.iter().all(|i| i["type"] != "tun"), "{mode:?}");
+            assert!(inbounds.iter().any(|i| i["type"] == "mixed"), "{mode:?}");
+        }
+    }
+
     #[test]
     fn change_detection() {
         let s = AdvancedSettings::default();

crates/kasumi-core/src/enums.rs

@@ -57,6 +57,13 @@ pub fn tun_from_marker(s: &str) -> Option<TunEngine> {
     serde_json::from_value(serde_json::Value::String(s.trim().to_owned())).ok()
 }
 
+/// Marker label recorded when the data-path runs with no tun at all (the
+/// proxy-only/system/pac modes) — deliberately not a [`TunEngine`] variant, since
+/// no engine is involved and no helper process is expected. Watchdog/teardown
+/// readers must treat it as "no helper" rather than falling back to an engine
+/// default.
+pub const NO_TUN_MARKER: &str = "no-tun";
+
 /// Whether a TUN engine reads the userspace tuning knobs (connect / read-write
 /// timeouts, buffer sizes) the settings UI surfaces. Only the hev engine consumes
 /// them today; a new engine must opt in here (exhaustive match), so the UI can't

crates/kasumi-core/src/state.rs

@@ -140,6 +140,23 @@ pub enum RoutingMode {
     Rules,
 }
 
+/// How the data path captures traffic. `tun` (default) brings up a system-wide
+/// tun device and rewrites OS routing — it needs the privileged data-path. The
+/// other modes run the core with only its local socks/http inbound: `proxy-only`
+/// leaves the OS untouched (the user points apps at the port), `system` sets the
+/// OS proxy to that inbound, `pac` serves a PAC the OS is pointed at. These are
+/// mutually exclusive — there is no "tun + system proxy" combination, since the
+/// tun already captures everything.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default, specta::Type)]
+#[serde(rename_all = "kebab-case")]
+pub enum ProxyMode {
+    #[default]
+    Tun,
+    ProxyOnly,
+    System,
+    Pac,
+}
+
 /// Xray domain resolution strategy.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default, specta::Type)]
 pub enum DomainStrategy {
@@ -214,6 +231,9 @@ pub enum AppFilterMode {
 #[serde(rename_all = "camelCase", default)]
 pub struct AdvancedSettings {
     pub routing_mode: RoutingMode,
+    /// How the data path captures traffic (tun vs proxy-only/system/pac). Desktop
+    /// only; platforms without proxy-mode support (Android) always run tun.
+    pub proxy_mode: ProxyMode,
     pub domain_sniffing: bool,
     pub route_only: bool,
     pub domain_strategy: DomainStrategy,
@@ -292,6 +312,7 @@ impl Default for AdvancedSettings {
     fn default() -> Self {
         Self {
             routing_mode: RoutingMode::Global,
+            proxy_mode: ProxyMode::Tun,
             domain_sniffing: true,
             route_only: false,
             domain_strategy: DomainStrategy::IpIfNonMatch,

crates/kasumi-daemon/src/android/platform.rs

@@ -515,11 +515,14 @@ impl Platform for AndroidPlatform {
     }
 
     async fn start_data_path(&self, opts: StartDataPath) -> anyhow::Result<()> {
+        // `mode` is ignored: this platform reports no proxy-mode support, so it is
+        // always normalized to tun upstream.
         let StartDataPath {
             engine,
             tun,
             tun_opts,
             socks_port,
+            ..
         } = opts;
         set_service_state("connecting").await;
         let _ = write_text(SOCKS_PORT_FILE, &socks_port.to_string()).await;