feat(client): serve getEnvs over runner IPC

wan9chi · wan9chi · commit 21b2fc298cdb · 2026-06-14T16:45:14.000+08:00
Motivation:
Tools need a bulk env read path for APIs like Vite loadEnv that discover an env prefix rather than a single name. Before this change, getEnvs existed on the JS surface but always returned an empty match set.

Scope:
Add the GetEnvs request/response frame, Rust client support, NAPI getEnvs implementation, server-side env glob matching, invalid-glob error surfacing, and print-only e2e coverage. This PR intentionally does not add getEnvs match sets to cache fingerprints.

Verification:
- cargo test -p vite_task_server --test integration
- UPDATE_SNAPSHOTS=1 cargo test -p vite_task_bin --test e2e_snapshots fetch_envs_reads_match_set -- --ignored
- cargo test -p vite_task_bin --test e2e_snapshots fetch_envs_reads_match_set -- --ignored
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,7 @@
 # Changelog
 
 - **Changed** Tracked environment values in task cache fingerprints are now stored only as SHA-256 digests, and env-related cache miss details report names without values.
+- **Added** Runner-aware `getEnvs` calls now return env values served by the runner for matching env glob patterns.
 - **Added** Runner-aware `getEnv` reads can now participate in task cache fingerprints, so changing a tool-served env value invalidates the cache and names the env var in the miss message.
 - **Added** Runner-aware tools can now opt the current task run out of caching through the new IPC channel; Vite dev server integration uses this automatically ([#441](https://github.com/voidzero-dev/vite-task/pull/441))
 - **Fixed** Prefix environment assignments like `PATH=... command` now affect executable lookup during task planning, so tools provided only by the prefixed `PATH` can be resolved correctly ([#440](https://github.com/voidzero-dev/vite-task/pull/440))
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/crates/native_str/src/lib.rs b/crates/native_str/src/lib.rs
@@ -37,7 +37,7 @@ use wincode::{
 /// **Not portable across platforms.** The binary representation is platform-specific.
 /// Deserializing a `NativeStr` serialized on a different platform leads to unspecified
 /// behavior (garbage data), but is not unsafe. Designed for same-platform IPC only.
-#[derive(TransparentWrapper, PartialEq, Eq)]
+#[derive(TransparentWrapper, PartialEq, Eq, Hash)]
 #[repr(transparent)]
 pub struct NativeStr {
     // On unix, this is the raw bytes of the OsStr.
diff --git a/crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/scripts/fetch_envs.mjs b/crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/scripts/fetch_envs.mjs
@@ -0,0 +1,8 @@
+import { getEnvs } from '@voidzero-dev/vite-task-client';
+
+const matches = getEnvs('PROBE_*');
+const sorted = Object.entries(matches).sort(([a], [b]) => a.localeCompare(b));
+
+for (const [key, value] of sorted) {
+  console.log(`${key}=${value}`);
+}
diff --git a/crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/snapshots.toml b/crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/snapshots.toml
@@ -200,3 +200,30 @@ steps = [
     ],
   ], comment = "cache hit: PROBE_ENV changed but was requested with tracked: false" },
 ]
+
+[[e2e]]
+name = "fetch_envs_reads_match_set"
+comment = """
+Exercises `getEnvs(pattern)`: the tool asks the runner for every env matching `PROBE_*` and prints the served match set. This verifies the bulk env IPC round trip before match sets are added to cache fingerprints.
+"""
+ignore = true
+steps = [
+  { argv = [
+    "vt",
+    "run",
+    "fetch-envs",
+  ], envs = [
+    [
+      "PROBE_A",
+      "a",
+    ],
+    [
+      "PROBE_B",
+      "b",
+    ],
+    [
+      "UNRELATED",
+      "noise",
+    ],
+  ], comment = "runner serves only envs matching PROBE_*" },
+]
diff --git a/crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/snapshots/fetch_envs_reads_match_set.md b/crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/snapshots/fetch_envs_reads_match_set.md
@@ -0,0 +1,13 @@
+# fetch_envs_reads_match_set
+
+Exercises `getEnvs(pattern)`: the tool asks the runner for every env matching `PROBE_*` and prints the served match set. This verifies the bulk env IPC round trip before match sets are added to cache fingerprints.
+
+## `PROBE_A=a PROBE_B=b UNRELATED=noise vt run fetch-envs`
+
+runner serves only envs matching PROBE_*
+
+```
+$ node scripts/fetch_envs.mjs
+PROBE_A=a
+PROBE_B=b
+```
diff --git a/crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/vite-task.json b/crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/vite-task.json
@@ -22,6 +22,10 @@
       "command": "node scripts/fetch_env.mjs --untracked PROBE_ENV",
       "cache": true
     },
+    "fetch-envs": {
+      "command": "node scripts/fetch_envs.mjs",
+      "cache": true
+    },
     "fetch-prefixed-env": {
       "command": "PREFIXED_ENV=from-command node scripts/fetch_env.mjs PREFIXED_ENV",
       "cache": true
diff --git a/crates/vite_task_client/Cargo.toml b/crates/vite_task_client/Cargo.toml
@@ -8,6 +8,7 @@ rust-version.workspace = true
 
 [dependencies]
 native_str = { workspace = true }
+rustc-hash = { workspace = true }
 vite_task_ipc_shared = { workspace = true }
 wincode = { workspace = true, features = ["derive"] }
 
diff --git a/crates/vite_task_client/src/lib.rs b/crates/vite_task_client/src/lib.rs
@@ -6,7 +6,8 @@ use std::{
 };
 
 use native_str::NativeStr;
-use vite_task_ipc_shared::{GetEnvResponse, IPC_ENV_NAME, Request};
+use rustc_hash::FxHashMap;
+use vite_task_ipc_shared::{GetEnvResponse, GetEnvsResponse, IPC_ENV_NAME, Request};
 use wincode::{SchemaRead, config::DefaultConfig};
 
 #[cfg(unix)]
@@ -73,6 +74,30 @@ impl Client {
             .map(|env_value| Arc::<OsStr>::from(env_value.to_cow_os_str().as_ref())))
     }
 
+    /// Requests every env whose name matches `pattern` from the runner. The
+    /// returned map is keyed by env name with its value.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the request or response fails, or if the server
+    /// rejects the pattern as an invalid glob.
+    // TODO(env-track): A later PR in this stack adds a tracked flag so matched
+    // env sets can participate in cache fingerprints instead of being IPC-only.
+    pub fn get_envs(&self, pattern: &str) -> io::Result<FxHashMap<Arc<OsStr>, Arc<OsStr>>> {
+        self.send(&Request::GetEnvs { pattern })?;
+        let response: GetEnvsResponse = self.recv()?;
+        Ok(response
+            .entries
+            .into_iter()
+            .map(|(name, value)| {
+                (
+                    Arc::<OsStr>::from(name.to_cow_os_str().as_ref()),
+                    Arc::<OsStr>::from(value.to_cow_os_str().as_ref()),
+                )
+            })
+            .collect())
+    }
+
     fn send(&self, request: &Request<'_>) -> io::Result<()> {
         let bytes = wincode::serialize(request)
             .map_err(|err| io::Error::new(io::ErrorKind::InvalidData, err))?;
diff --git a/crates/vite_task_client_napi/src/lib.rs b/crates/vite_task_client_napi/src/lib.rs
@@ -106,15 +106,20 @@ impl RunnerClient {
         })
     }
 
-    /// No-op for now: always returns an empty match-set — see
-    /// [`Self::get_env`].
     #[napi]
     pub fn get_envs(
         &self,
-        _pattern: String,
+        pattern: String,
         _options: Option<GetEnvOptions>,
     ) -> Result<HashMap<String, String>> {
-        Ok(HashMap::new())
+        let matches =
+            self.client.get_envs(&pattern).map_err(|err| err_string(vite_str::format!("{err}")))?;
+        // Entries whose name or value contains non-UTF-8 bytes can't cross
+        // the JS boundary as `String`; bulk fetch drops them silently.
+        Ok(matches
+            .into_iter()
+            .filter_map(|(k, v)| Some((k.to_str()?.to_owned(), v.to_str()?.to_owned())))
+            .collect())
     }
 }
 
diff --git a/crates/vite_task_ipc_shared/Cargo.toml b/crates/vite_task_ipc_shared/Cargo.toml
@@ -8,6 +8,7 @@ rust-version.workspace = true
 
 [dependencies]
 native_str = { workspace = true }
+rustc-hash = { workspace = true }
 wincode = { workspace = true, features = ["derive"] }
 
 [lints]
diff --git a/crates/vite_task_ipc_shared/src/lib.rs b/crates/vite_task_ipc_shared/src/lib.rs
@@ -1,4 +1,5 @@
 use native_str::NativeStr;
+use rustc_hash::FxHashMap;
 use wincode::{SchemaRead, SchemaWrite};
 
 pub const IPC_ENV_NAME: &str = "VP_RUN_IPC_NAME";
@@ -16,8 +17,8 @@ pub const NODE_CLIENT_PATH_ENV_NAME: &str = "VP_RUN_NODE_CLIENT_PATH";
 /// IPC request frame sent by tools to the runner.
 ///
 /// `DisableCache` is fire-and-forget: the runner processes it when it
-/// arrives and never writes a response. `GetEnv` is a round-trip and pairs
-/// with [`GetEnvResponse`].
+/// arrives and never writes a response. `GetEnv` and `GetEnvs` are
+/// round-trips and pair with the matching response types below.
 ///
 /// Fire-and-forget is safe because nothing in the runner observes individual
 /// IPC events live — the recorded set is only consumed *after* the per-task
@@ -27,10 +28,20 @@ pub const NODE_CLIENT_PATH_ENV_NAME: &str = "VP_RUN_NODE_CLIENT_PATH";
 #[derive(Debug, SchemaWrite, SchemaRead)]
 pub enum Request<'a> {
     GetEnv { name: &'a NativeStr, tracked: bool },
+    // TODO(env-track): A later PR in this stack adds a tracked flag once the
+    // runner records served env glob reads into the post-run cache fingerprint.
+    GetEnvs { pattern: &'a str },
     DisableCache,
 }
 
 #[derive(Debug, SchemaWrite, SchemaRead)]
 pub struct GetEnvResponse {
     pub env_value: Option<Box<NativeStr>>,
 }
+
+#[derive(Debug, SchemaWrite, SchemaRead)]
+pub struct GetEnvsResponse {
+    /// Match snapshot for the glob pattern. Keys/values are byte-faithful
+    /// (`NativeStr`) so non-UTF-8 env values are preserved over the wire.
+    pub entries: FxHashMap<Box<NativeStr>, Box<NativeStr>>,
+}
diff --git a/crates/vite_task_server/Cargo.toml b/crates/vite_task_server/Cargo.toml
@@ -14,6 +14,7 @@ thiserror = { workspace = true }
 tokio = { workspace = true, features = ["io-util", "net", "rt", "macros"] }
 tokio-util = { workspace = true }
 tracing = { workspace = true }
+vite_glob = { workspace = true }
 vite_task_ipc_shared = { workspace = true }
 wincode = { workspace = true, features = ["derive"] }
 
diff --git a/crates/vite_task_server/src/lib.rs b/crates/vite_task_server/src/lib.rs
@@ -9,12 +9,21 @@ use futures::{FutureExt, StreamExt, future::LocalBoxFuture, stream::FuturesUnord
 use rustc_hash::FxHashMap;
 use tokio::io::{AsyncReadExt, AsyncWriteExt};
 use tokio_util::sync::CancellationToken;
-use vite_task_ipc_shared::{GetEnvResponse, IPC_ENV_NAME, Request};
+use vite_task_ipc_shared::{GetEnvResponse, GetEnvsResponse, IPC_ENV_NAME, Request};
 use wincode::{SchemaWrite, config::DefaultConfig};
 
 pub trait Handler {
     fn disable_cache(&mut self);
     fn get_env(&mut self, name: &OsStr, tracked: bool) -> Option<Arc<OsStr>>;
+    /// Returns the subset of the env map whose names match `pattern` as a glob.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if `pattern` fails to parse as a glob.
+    fn get_envs(
+        &mut self,
+        pattern: &str,
+    ) -> Result<FxHashMap<Arc<OsStr>, Arc<OsStr>>, vite_glob::env::EnvGlobError>;
 }
 
 /// A protocol-level failure observed while servicing a client.
@@ -31,6 +40,16 @@ pub enum Error {
 
     #[error("failed to send response to the task")]
     WriteResponse(#[source] io::Error),
+
+    #[error("invalid glob pattern from the task: {:?}", .0.pattern)]
+    InvalidGlob(Box<InvalidGlob>),
+}
+
+/// Payload for [`Error::InvalidGlob`]. Boxed so the `Error` enum stays small.
+#[derive(Debug)]
+pub struct InvalidGlob {
+    pub pattern: Box<str>,
+    pub source: vite_glob::env::EnvGlobError,
 }
 
 /// A [`Handler`] that records every report and resolves `get_env` against
@@ -94,6 +113,25 @@ impl Handler for Recorder {
             }
         }
     }
+
+    fn get_envs(
+        &mut self,
+        pattern: &str,
+    ) -> Result<FxHashMap<Arc<OsStr>, Arc<OsStr>>, vite_glob::env::EnvGlobError> {
+        let glob = vite_glob::env::EnvGlob::new(pattern)?;
+        Ok(self
+            .envs
+            .iter()
+            .filter_map(|(name, value)| {
+                let name_str = name.to_str()?;
+                if glob.is_match(name_str) {
+                    Some((Arc::clone(name), Arc::clone(value)))
+                } else {
+                    None
+                }
+            })
+            .collect())
+    }
 }
 
 /// Handle to a running IPC server.
@@ -322,6 +360,18 @@ async fn handle_client<H: Handler>(mut stream: Stream, handler: &RefCell<H>) ->
                 let response = GetEnvResponse { env_value: value.as_deref().map(Into::into) };
                 write_response(&mut stream, &response).await.map_err(Error::WriteResponse)?;
             }
+            Request::GetEnvs { pattern } => {
+                let matches = handler.borrow_mut().get_envs(pattern).map_err(|source| {
+                    Error::InvalidGlob(Box::new(InvalidGlob {
+                        pattern: Box::<str>::from(pattern),
+                        source,
+                    }))
+                })?;
+                let response = GetEnvsResponse {
+                    entries: matches.iter().map(|(k, v)| ((&**k).into(), (&**v).into())).collect(),
+                };
+                write_response(&mut stream, &response).await.map_err(Error::WriteResponse)?;
+            }
         }
     }
 }
diff --git a/crates/vite_task_server/tests/integration.rs b/crates/vite_task_server/tests/integration.rs
@@ -1,5 +1,6 @@
 use std::{
     ffi::{OsStr, OsString},
+    io,
     sync::Arc,
     thread,
 };
@@ -130,3 +131,56 @@ fn concurrent_clients() {
     assert!(shared.tracked);
     assert_eq!(shared.value.as_deref(), Some(OsStr::new("value")));
 }
+
+#[test]
+fn get_envs_returns_matching_entries() {
+    let reports = run_with_server(
+        env_map(&[("PROBE_A", "alpha"), ("PROBE_B", "beta"), ("UNRELATED", "noise")]),
+        |envs| {
+            let client = connect(&envs);
+            let matches = client.get_envs("PROBE_*").unwrap();
+            assert_eq!(matches.len(), 2);
+            assert_eq!(
+                matches.get(OsStr::new("PROBE_A")).map(AsRef::as_ref),
+                Some(OsStr::new("alpha"))
+            );
+            assert_eq!(
+                matches.get(OsStr::new("PROBE_B")).map(AsRef::as_ref),
+                Some(OsStr::new("beta"))
+            );
+            assert!(!matches.contains_key(OsStr::new("UNRELATED")));
+        },
+    )
+    .expect("driver returned error");
+
+    assert!(!reports.cache_disabled);
+}
+
+#[test]
+fn get_envs_empty_match_set_is_returned() {
+    let reports = run_with_server(env_map(&[("FOO", "x"), ("BAR", "y")]), |envs| {
+        let client = connect(&envs);
+        let matches = client.get_envs("PROBE_*").unwrap();
+        assert!(matches.is_empty());
+    })
+    .expect("driver returned error");
+
+    assert!(!reports.cache_disabled);
+}
+
+#[test]
+fn get_envs_invalid_pattern_surfaces_error() {
+    let err = run_with_server(env_map(&[]), |envs| {
+        let client = connect(&envs);
+        let send_err = client.get_envs("{unclosed").expect_err("server should reject");
+        assert_eq!(send_err.kind(), io::ErrorKind::UnexpectedEof);
+    })
+    .expect_err("driver should surface the protocol error");
+
+    match err {
+        Error::InvalidGlob(inner) => {
+            assert_eq!(inner.pattern.as_ref(), "{unclosed");
+        }
+        other => panic!("unexpected error variant: {other:?}"),
+    }
+}
