perf: Two-phase HTTP client init to avoid macOS Keychain blocking

Build the reqwest HTTP client in two phases to remove ~200ms of macOS
Keychain enumeration from the critical path:

Phase 1 (instant): Build a client with bundled Mozilla CAs
(webpki-roots). Available immediately for any early callers.

Phase 2 (background): Build a full client with system Keychain CAs
(native-roots) on a background thread. Once ready, all subsequent
requests use this client, supporting corporate proxy CAs.

This is transparent to all users — standard HTTPS works immediately
via Phase 1, and corporate proxy environments get full CA support
once Phase 2 completes (~200ms later, well before any remote cache
or API request is made).

Author: anthonyshew

crates/turborepo-api-client/Cargo.toml

@@ -7,7 +7,10 @@ license = "MIT"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 [features]
 native-tls = ["reqwest/native-tls"]
-rustls-tls = ["reqwest/rustls-tls-native-roots"]
+rustls-tls = [
+  "reqwest/rustls-tls-native-roots",
+  "reqwest/rustls-tls-webpki-roots",
+]
 
 [dev-dependencies]
 anyhow = { workspace = true }

crates/turborepo-api-client/src/lib.rs

@@ -609,7 +609,30 @@ impl APIClient {
     /// resulting client.
     #[tracing::instrument(skip_all)]
     pub fn build_http_client(connect_timeout: Option<Duration>) -> Result<reqwest::Client> {
+        Self::build_http_client_with_native_roots(connect_timeout, true)
+    }
+
+    /// Builds an HTTP client using only the bundled Mozilla CA bundle
+    /// (webpki-roots). This is instant (~0ms) because no system Keychain
+    /// access is needed. Sufficient for all standard HTTPS connections.
+    #[tracing::instrument(skip_all)]
+    pub fn build_http_client_webpki_only(
+        connect_timeout: Option<Duration>,
+    ) -> Result<reqwest::Client> {
+        Self::build_http_client_with_native_roots(connect_timeout, false)
+    }
+
+    fn build_http_client_with_native_roots(
+        connect_timeout: Option<Duration>,
+        #[allow(unused_variables)] native_roots: bool,
+    ) -> Result<reqwest::Client> {
         let mut builder = reqwest::Client::builder();
+        #[cfg(feature = "rustls-tls")]
+        {
+            builder = builder
+                .tls_built_in_webpki_certs(true)
+                .tls_built_in_native_certs(native_roots);
+        }
         if let Some(dur) = connect_timeout {
             builder = builder.connect_timeout(dur);
         }

crates/turborepo-api-client/src/shared_http_client.rs

@@ -1,31 +1,44 @@
 use std::sync::{
-    Arc,
+    Arc, OnceLock,
     atomic::{AtomicBool, Ordering},
 };
 
-use tokio::sync::OnceCell;
-
 use crate::{APIClient, Error};
 
 /// Shared reqwest client initialization for all run-time network consumers.
 ///
-/// Call `activate()` as soon as a command knows it will need networking, then
-/// use `get_or_init()` at the actual point of use. This overlaps TLS/client
-/// setup with other startup work without constructing a client for commands
-/// that never touch the network.
-#[derive(Clone, Default)]
+/// Uses two-phase initialization to avoid blocking on macOS Keychain
+/// enumeration (~200ms). Phase 1 builds an instant client with bundled
+/// Mozilla CAs (webpki-roots). Phase 2 builds a full client with system
+/// CAs (native-roots) in the background. Consumers get whichever is
+/// best available at the time of use.
+#[derive(Clone)]
 pub struct SharedHttpClient {
-    cell: Arc<OnceCell<reqwest::Client>>,
+    /// Instant client with bundled Mozilla CAs only (~0ms to build).
+    fast_client: Arc<OnceLock<reqwest::Client>>,
+    /// Full client with system Keychain CAs (~200ms on macOS).
+    /// Built in the background; preferred once ready.
+    native_client: Arc<OnceLock<reqwest::Client>>,
     warming: Arc<AtomicBool>,
 }
 
+impl Default for SharedHttpClient {
+    fn default() -> Self {
+        Self {
+            fast_client: Arc::new(OnceLock::new()),
+            native_client: Arc::new(OnceLock::new()),
+            warming: Arc::new(AtomicBool::new(false)),
+        }
+    }
+}
+
 impl SharedHttpClient {
     pub fn new() -> Self {
         Self::default()
     }
 
     pub fn activate(&self) {
-        if self.cell.get().is_some() {
+        if self.native_client.get().is_some() {
             return;
         }
 
@@ -37,26 +50,54 @@ impl SharedHttpClient {
             return;
         }
 
-        let this = self.clone();
-        tokio::spawn(async move {
-            let _ = this.get_or_init().await;
-            this.warming.store(false, Ordering::Release);
+        // Phase 1: build fast client in background (webpki-roots only, ~0ms).
+        let fast = self.fast_client.clone();
+        tokio::task::spawn_blocking(move || {
+            let _span = tracing::info_span!("http_client_init_fast").entered();
+            let _ = fast.get_or_init(|| {
+                APIClient::build_http_client_webpki_only(None)
+                    .expect("failed to build webpki HTTP client")
+            });
+        });
+
+        // Phase 2: build full client in background (native-roots, ~200ms on macOS).
+        let native = self.native_client.clone();
+        let warming = self.warming.clone();
+        tokio::task::spawn_blocking(move || {
+            let _span = tracing::info_span!("http_client_init").entered();
+            let _ = native.get_or_init(|| {
+                let client =
+                    APIClient::build_http_client(None).expect("failed to build native HTTP client");
+                warming.store(false, Ordering::Release);
+                client
+            });
         });
     }
 
     pub async fn get_or_init(&self) -> Result<reqwest::Client, Error> {
-        let client = self
-            .cell
-            .get_or_try_init(|| async {
-                tokio::task::spawn_blocking(|| {
-                    let _span = tracing::info_span!("http_client_init").entered();
-                    APIClient::build_http_client(None)
-                })
-                .await
-                .map_err(|_| Error::HttpClientCancelled)?
+        // Prefer the full client (includes system CAs for corporate proxies)
+        if let Some(client) = self.native_client.get() {
+            return Ok(client.clone());
+        }
+
+        // If the fast client is ready, use it while native is still building
+        if let Some(client) = self.fast_client.get() {
+            return Ok(client.clone());
+        }
+
+        // Neither is ready — build the fast client synchronously as fallback
+        let fast = self.fast_client.clone();
+        let client = tokio::task::spawn_blocking(move || {
+            let _span = tracing::info_span!("http_client_init_fast").entered();
+            fast.get_or_init(|| {
+                APIClient::build_http_client_webpki_only(None)
+                    .expect("failed to build webpki HTTP client")
             })
-            .await?;
+            .clone()
+        })
+        .await
+        .map_err(|_| Error::HttpClientCancelled)?;
 
-        Ok(client.clone())
+        Ok(client)
     }
 }