running-process 4.3.0__tar.gz → 4.4.0__tar.gz

{running_process-4.3.0 → running_process-4.4.0}/Cargo.lock

@@ -1085,7 +1085,7 @@ checksum = "dc897dd8d9e8bd1ed8cdad82b5966c3e0ecae09fb1907d58efaa013543185d0a"
 
 [[package]]
 name = "running-process"
-version = "4.3.0"
+version = "4.4.0"
 dependencies = [
  "anyhow",
  "blake3",
@@ -1120,7 +1120,7 @@ dependencies = [
 
 [[package]]
 name = "running-process-py"
-version = "4.3.0"
+version = "4.4.0"
 dependencies = [
  "interprocess",
  "libc",

{running_process-4.3.0 → running_process-4.4.0}/Cargo.toml

@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/running-process", "crates/running-process-py", "crates/test-watchdog"]
 
 [workspace.package]
-version = "4.3.0"
+version = "4.4.0"
 edition = "2021"
 rust-version = "1.85"
 license = "BSD-3-Clause"

{running_process-4.3.0 → running_process-4.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: running_process
-Version: 4.3.0
+Version: 4.4.0
 License-File: LICENSE
 Summary: A Rust-backed subprocess wrapper with split stdout/stderr streaming
 Home-Page: https://github.com/zackees/running-process

{running_process-4.3.0 → running_process-4.4.0}/crates/running-process/src/broker/adopt.rs

@@ -104,6 +104,103 @@ impl BrokerSession {
     pub fn into_client(self) -> FrameClient {
         self.client
     }
+
+    /// Consume the session and hand back the live negotiated socket as an
+    /// owned OS handle (#720).
+    ///
+    /// After adoption has driven the broker handshake to completion, a
+    /// consumer that wants to stop speaking the FrameV1 request/response wire
+    /// and run its own protocol over the same connection calls this to take
+    /// ownership of the raw socket. On Unix the result wraps an
+    /// `OwnedFd`; the Windows `OwnedHandle` path is deferred, so this returns
+    /// `IntoBackendIoError::WindowsUnsupported` there for now.
+    ///
+    /// Fails with [`IntoBackendIoError::BufferedResidual`] if the frame
+    /// reader has buffered response bytes the bare socket would not carry —
+    /// which never happens on a freshly adopted session that has issued no
+    /// [`request`](Self::request).
+    pub fn into_backend_io(self) -> Result<OwnedBackendIo, IntoBackendIoError> {
+        let buffered = self.client.buffered_len();
+        if buffered != 0 {
+            return Err(IntoBackendIoError::BufferedResidual { buffered });
+        }
+        OwnedBackendIo::from_local_socket_stream(self.client.into_stream())
+    }
+}
+
+/// A live negotiated backend socket handed back as an owned OS handle (#720).
+///
+/// Produced by [`BrokerSession::into_backend_io`] /
+/// `AsyncBrokerSession::into_backend_io`. On Unix it owns an `OwnedFd` the
+/// consumer can wrap in its own transport (e.g.
+/// `std::os::unix::net::UnixStream::from`); the Windows `OwnedHandle` path is
+/// deferred (#720), so the type is never constructed on Windows.
+#[derive(Debug)]
+pub struct OwnedBackendIo {
+    // The Windows handle path is deferred (#720). The type still exists so the
+    // `into_backend_io` signature is platform-stable, but it carries no handle
+    // on Windows and is only ever returned as `Err(WindowsUnsupported)`.
+    #[cfg(unix)]
+    fd: std::os::fd::OwnedFd,
+}
+
+impl OwnedBackendIo {
+    #[cfg(unix)]
+    fn from_local_socket_stream(
+        stream: interprocess::local_socket::Stream,
+    ) -> Result<Self, IntoBackendIoError> {
+        match stream {
+            interprocess::local_socket::Stream::UdSocket(uds) => Ok(Self {
+                fd: std::os::fd::OwnedFd::from(uds),
+            }),
+        }
+    }
+
+    #[cfg(windows)]
+    fn from_local_socket_stream(
+        _stream: interprocess::local_socket::Stream,
+    ) -> Result<Self, IntoBackendIoError> {
+        Err(IntoBackendIoError::WindowsUnsupported)
+    }
+
+    /// Consume and return the raw owned file descriptor.
+    #[cfg(unix)]
+    pub fn into_owned_fd(self) -> std::os::fd::OwnedFd {
+        self.fd
+    }
+}
+
+#[cfg(unix)]
+impl std::os::fd::AsFd for OwnedBackendIo {
+    fn as_fd(&self) -> std::os::fd::BorrowedFd<'_> {
+        self.fd.as_fd()
+    }
+}
+
+/// Errors from [`BrokerSession::into_backend_io`] /
+/// [`AsyncBrokerSession::into_backend_io`].
+#[derive(Debug, thiserror::Error)]
+pub enum IntoBackendIoError {
+    /// The frame reader still holds buffered response bytes that the bare
+    /// socket would not carry, so the raw handle cannot be taken without
+    /// losing them.
+    #[error(
+        "frame client has {buffered} buffered response byte(s); cannot hand off the raw socket without losing them"
+    )]
+    BufferedResidual {
+        /// Number of bytes buffered by the frame reader.
+        buffered: usize,
+    },
+    /// The async frame client was poisoned by a prior request panic, so its
+    /// inner blocking client is gone.
+    #[cfg(feature = "client-async")]
+    #[error("async frame client was poisoned by a prior request panic")]
+    Poisoned,
+    /// `into_backend_io()` is not yet supported on Windows; the `OwnedHandle`
+    /// path is deferred (#720).
+    #[cfg(windows)]
+    #[error("into_backend_io() is not yet supported on Windows; the OwnedHandle path is deferred (#720)")]
+    WindowsUnsupported,
 }
 
 /// Errors from [`BrokerSession::adopt`] / [`AsyncBrokerSession::adopt`].
@@ -270,4 +367,24 @@ impl AsyncBrokerSession {
     pub fn into_client(self) -> crate::broker::backend_sdk::AsyncFrameClient {
         self.client
     }
+
+    /// Consume the session and hand back the live negotiated socket as an
+    /// owned OS handle (#720).
+    ///
+    /// Async twin of [`BrokerSession::into_backend_io`]. No `.await` is
+    /// needed: the inner blocking client already owns the connected socket, so
+    /// taking the raw handle out is a synchronous unwrap. Fails with
+    /// [`IntoBackendIoError::Poisoned`] if a prior [`request`](Self::request)
+    /// panicked inside `spawn_blocking` and left the client slot empty.
+    pub fn into_backend_io(self) -> Result<OwnedBackendIo, IntoBackendIoError> {
+        let client = self
+            .client
+            .into_blocking()
+            .ok_or(IntoBackendIoError::Poisoned)?;
+        let buffered = client.buffered_len();
+        if buffered != 0 {
+            return Err(IntoBackendIoError::BufferedResidual { buffered });
+        }
+        OwnedBackendIo::from_local_socket_stream(client.into_stream())
+    }
 }

{running_process-4.3.0 → running_process-4.4.0}/crates/running-process/src/broker/backend_sdk/frame_client.rs

@@ -108,6 +108,29 @@ impl FrameClient {
     pub fn next_request_id(&self) -> u64 {
         self.next_request_id
     }
+
+    /// Bytes the internal frame reader has buffered but not yet consumed.
+    ///
+    /// Zero on a client that has issued no [`Self::request`]. A consumer that
+    /// wants to take the raw socket back out via [`Self::into_stream`] checks
+    /// this first: nonzero means there is response data the bare socket would
+    /// not carry, so the take must be refused.
+    pub fn buffered_len(&self) -> usize {
+        self.stream.buffer().len()
+    }
+
+    /// Consume the client and return the underlying local-socket stream.
+    ///
+    /// Hands the negotiated socket back to a consumer that will speak its own
+    /// wire over it (see [`BrokerSession::into_backend_io`]). Any bytes still
+    /// buffered by the frame reader are dropped, so callers must verify
+    /// [`Self::buffered_len`] is zero before calling — which it always is on a
+    /// freshly adopted session that has issued no request.
+    ///
+    /// [`BrokerSession::into_backend_io`]: crate::broker::adopt::BrokerSession::into_backend_io
+    pub fn into_stream(self) -> interprocess::local_socket::Stream {
+        self.stream.into_inner()
+    }
 }
 
 /// Errors returned by [`FrameClient`].

{running_process-4.3.0 → running_process-4.4.0}/crates/running-process/src/broker/backend_sdk/frame_client_async.rs

@@ -167,6 +167,17 @@ impl AsyncFrameClient {
     pub fn next_request_id(&self) -> Option<u64> {
         self.inner.as_ref().map(FrameClient::next_request_id)
     }
+
+    /// Recover the owned blocking [`FrameClient`], or `None` if a prior
+    /// request panicked inside `spawn_blocking` and poisoned the slot.
+    ///
+    /// Used by [`AsyncBrokerSession::into_backend_io`] to take the
+    /// negotiated socket back out without crossing another async hop.
+    ///
+    /// [`AsyncBrokerSession::into_backend_io`]: crate::broker::adopt::AsyncBrokerSession::into_backend_io
+    pub fn into_blocking(self) -> Option<FrameClient> {
+        self.inner
+    }
 }
 
 fn join_error_to_client(join_err: tokio::task::JoinError) -> FrameClientError {

{running_process-4.3.0 → running_process-4.4.0}/crates/running-process/src/broker/protocol/mod.rs

@@ -34,6 +34,6 @@ pub use framing::{
 };
 pub use registry::{
     ADMIN_PAYLOAD_PROTOCOL, BACKEND_HANDLE_PROBE_PAYLOAD_PROTOCOL, CONTROL_PAYLOAD_PROTOCOL,
-    HANDOFF_PAYLOAD_PROTOCOL, PROTOCOL_VERSION, ZCCACHE_PAYLOAD_PROTOCOL,
+    FBUILD_PAYLOAD_PROTOCOL, HANDOFF_PAYLOAD_PROTOCOL, PROTOCOL_VERSION, ZCCACHE_PAYLOAD_PROTOCOL,
 };
 pub use validate::{validate_frame_envelope, FrameValidationError};

{running_process-4.3.0 → running_process-4.4.0}/crates/running-process/src/broker/protocol/registry.rs

@@ -43,6 +43,7 @@
 //! |----------|------------------------------|------------------------------------------------------------------|
 //! | `0x7A63` | [`ZCCACHE_PAYLOAD_PROTOCOL`] | zccache (`"zc"` in ASCII; zccache FrameV1 request/response lane) |
 //! | `0x7C4C` | [`CLUD_PAYLOAD_PROTOCOL`]    | clud (`0x7C4C` = `"|L"`; clud daemon Frame v1 request/response lane) |
+//! | `0x7EB1` | [`FBUILD_PAYLOAD_PROTOCOL`]  | fbuild (FastLED/fbuild daemon Frame v1 request/response lane) |
 //!
 //! Use [`crate::register_payload_protocol!`] in consumer crates to pin
 //! the chosen ID with compile-time range and collision checks.
@@ -112,6 +113,12 @@ pub const ZCCACHE_PAYLOAD_PROTOCOL: u32 = 0x7A63;
 /// authoritative registration lives here.
 pub const CLUD_PAYLOAD_PROTOCOL: u32 = 0x7C4C;
 
+/// Registered consumer ID: fbuild's opaque Frame v1 request/response lane
+/// (FastLED/fbuild daemon control plane; zackees/running-process#437). fbuild
+/// pins this value on its side with [`crate::register_payload_protocol!`]; the
+/// authoritative registration lives here.
+pub const FBUILD_PAYLOAD_PROTOCOL: u32 = 0x7EB1;
+
 /// All first-party payload-protocol IDs, in registry-table order.
 ///
 /// Used by [`is_first_party`] and the consumer-side collision checks
@@ -239,7 +246,7 @@ mod tests {
     fn frozen_consumer_registry_values() {
         use super::{
             is_first_party, is_private_use_id, is_registered_consumer_id, CLUD_PAYLOAD_PROTOCOL,
-            CONSUMER_PAYLOAD_PROTOCOL_MAX, CONSUMER_PAYLOAD_PROTOCOL_MIN,
+            CONSUMER_PAYLOAD_PROTOCOL_MAX, CONSUMER_PAYLOAD_PROTOCOL_MIN, FBUILD_PAYLOAD_PROTOCOL,
             PRIVATE_USE_PAYLOAD_PROTOCOL_MAX, PRIVATE_USE_PAYLOAD_PROTOCOL_MIN,
             ZCCACHE_PAYLOAD_PROTOCOL,
         };
@@ -250,7 +257,10 @@ mod tests {
         assert_eq!(PRIVATE_USE_PAYLOAD_PROTOCOL_MAX, 0xFFFF);
         assert_eq!(ZCCACHE_PAYLOAD_PROTOCOL, 0x7A63);
         assert_eq!(CLUD_PAYLOAD_PROTOCOL, 0x7C4C);
+        assert_eq!(FBUILD_PAYLOAD_PROTOCOL, 0x7EB1);
         assert_ne!(CLUD_PAYLOAD_PROTOCOL, ZCCACHE_PAYLOAD_PROTOCOL);
+        assert_ne!(FBUILD_PAYLOAD_PROTOCOL, ZCCACHE_PAYLOAD_PROTOCOL);
+        assert_ne!(FBUILD_PAYLOAD_PROTOCOL, CLUD_PAYLOAD_PROTOCOL);
 
         assert!(is_registered_consumer_id(ZCCACHE_PAYLOAD_PROTOCOL));
         assert!(!is_first_party(ZCCACHE_PAYLOAD_PROTOCOL));
@@ -260,6 +270,10 @@ mod tests {
         assert!(!is_first_party(CLUD_PAYLOAD_PROTOCOL));
         assert!(!is_private_use_id(CLUD_PAYLOAD_PROTOCOL));
 
+        assert!(is_registered_consumer_id(FBUILD_PAYLOAD_PROTOCOL));
+        assert!(!is_first_party(FBUILD_PAYLOAD_PROTOCOL));
+        assert!(!is_private_use_id(FBUILD_PAYLOAD_PROTOCOL));
+
         // First-party IDs must never drift into the consumer range.
         for id in super::FIRST_PARTY_PAYLOAD_PROTOCOLS {
             assert!(is_first_party(id));

running_process-4.4.0/crates/running-process/tests/broker/into_backend_io.rs

@@ -0,0 +1,208 @@
+//! End-to-end coverage for [`BrokerSession::into_backend_io`] (#720).
+//!
+//! A consumer adopts through the broker, then — instead of speaking the
+//! FrameV1 request/response wire — takes ownership of the live negotiated
+//! socket and runs its own raw protocol over it. On Unix the handed-back
+//! [`OwnedFd`](std::os::fd::OwnedFd) is wrapped in a
+//! [`std::os::unix::net::UnixStream`] and proven live with a raw echo
+//! round-trip. On Windows the `OwnedHandle` path is deferred, so
+//! `into_backend_io()` reports [`IntoBackendIoError::WindowsUnsupported`].
+
+use std::io::{self, Read, Write};
+use std::sync::mpsc;
+use std::thread;
+
+use interprocess::local_socket::traits::Listener as _;
+use running_process::broker::adopt::BrokerSession;
+#[cfg(all(unix, feature = "client-async"))]
+use running_process::broker::adopt::{AsyncBrokerSession, OwnedConnectRequest};
+use running_process::broker::client::{BackendConnectionRoute, ConnectBackendRequest};
+use running_process::broker::protocol::{BrokerIsolation, ServiceDefinition};
+use running_process::broker::server::{
+    handle_hello_connection, HelloHandler, PeerIdentity, RegisteredBackend,
+};
+
+use crate::socket_common::{
+    await_test_socket_ready, bind_ready_test_socket, cleanup_test_socket, unique_socket_name,
+};
+
+const IO_SERVICE: &str = "io-test";
+const IO_VERSION: &str = "1.0.0";
+
+fn io_service_definition() -> ServiceDefinition {
+    ServiceDefinition {
+        service_name: IO_SERVICE.into(),
+        binary_path: "/usr/local/bin/io-test".into(),
+        isolation: BrokerIsolation::SharedBroker as i32,
+        explicit_instance: String::new(),
+        per_version_binary_dir: String::new(),
+        min_version: "1.0.0".into(),
+        version_allow_list: vec![IO_VERSION.into()],
+        labels: Default::default(),
+    }
+}
+
+/// Broker that negotiates one Hello and points the client at `backend_socket`.
+fn spawn_broker(
+    broker_socket: String,
+    backend_socket: String,
+) -> thread::JoinHandle<io::Result<()>> {
+    let display = broker_socket.clone();
+    let (ready_tx, ready_rx) = mpsc::channel();
+    let handle = thread::spawn(move || {
+        let listener = bind_ready_test_socket(&broker_socket, &ready_tx)?;
+        let handler = HelloHandler::new()
+            .with_backend(RegisteredBackend {
+                service_definition: io_service_definition(),
+                daemon_version: IO_VERSION.into(),
+                backend_pipe: backend_socket.clone(),
+                server_capabilities: 0x01,
+            })
+            .map_err(|err| io::Error::other(err.to_string()))?;
+        let mut stream = listener.accept()?;
+        let peer = PeerIdentity {
+            pid: std::process::id(),
+            uid_or_sid: "io-peer".into(),
+        };
+        handle_hello_connection(&mut stream, &handler, peer)
+            .map_err(|err| io::Error::other(err.to_string()))?;
+        cleanup_test_socket(&broker_socket);
+        Ok(())
+    });
+    await_test_socket_ready(&ready_rx, &display);
+    handle
+}
+
+/// Backend that accepts one connection and echoes raw bytes until EOF.
+///
+/// Unlike the [`BackendEndpointMux`](running_process::broker::backend_sdk::BackendEndpointMux)
+/// app daemons, this speaks no frame wire: it proves the socket handed back by
+/// `into_backend_io()` is the live negotiated connection by mirroring whatever
+/// the consumer writes over it directly.
+fn spawn_raw_echo_backend(backend_socket: String) -> thread::JoinHandle<io::Result<()>> {
+    let display = backend_socket.clone();
+    let (ready_tx, ready_rx) = mpsc::channel();
+    let handle = thread::spawn(move || {
+        let listener = bind_ready_test_socket(&backend_socket, &ready_tx)?;
+        let mut stream = listener.accept()?;
+        let mut chunk = [0u8; 4096];
+        loop {
+            let read = stream.read(&mut chunk)?;
+            if read == 0 {
+                break;
+            }
+            stream.write_all(&chunk[..read])?;
+            stream.flush()?;
+        }
+        cleanup_test_socket(&backend_socket);
+        Ok(())
+    });
+    await_test_socket_ready(&ready_rx, &display);
+    handle
+}
+
+#[cfg(unix)]
+#[test]
+fn into_backend_io_hands_off_live_unix_socket() {
+    use std::os::unix::net::UnixStream;
+
+    let broker_socket = unique_socket_name("io-broker");
+    let backend_socket = unique_socket_name("io-backend");
+
+    let backend = spawn_raw_echo_backend(backend_socket.clone());
+    let broker = spawn_broker(broker_socket.clone(), backend_socket.clone());
+
+    let request = ConnectBackendRequest::new(&broker_socket, IO_SERVICE, IO_VERSION, IO_VERSION);
+    let session = BrokerSession::adopt(request).expect("broker session adopt");
+    assert_eq!(session.route(), BackendConnectionRoute::BrokerNegotiated);
+    assert_eq!(session.endpoint(), backend_socket);
+
+    let io = session.into_backend_io().expect("into_backend_io on unix");
+    let fd = io.into_owned_fd();
+    let mut raw = UnixStream::from(fd);
+
+    let proof = b"live-socket-proof";
+    raw.write_all(proof).expect("write over raw socket");
+    raw.flush().expect("flush");
+    let mut echoed = vec![0u8; proof.len()];
+    raw.read_exact(&mut echoed).expect("read raw echo");
+    assert_eq!(
+        &echoed, proof,
+        "raw socket must echo over the live connection"
+    );
+
+    drop(raw);
+    broker.join().unwrap().unwrap();
+    backend.join().unwrap().unwrap();
+}
+
+#[cfg(windows)]
+#[test]
+fn into_backend_io_is_unsupported_on_windows() {
+    use running_process::broker::adopt::IntoBackendIoError;
+
+    let broker_socket = unique_socket_name("io-broker-win");
+    let backend_socket = unique_socket_name("io-backend-win");
+
+    let backend = spawn_raw_echo_backend(backend_socket.clone());
+    let broker = spawn_broker(broker_socket.clone(), backend_socket.clone());
+
+    let request = ConnectBackendRequest::new(&broker_socket, IO_SERVICE, IO_VERSION, IO_VERSION);
+    let session = BrokerSession::adopt(request).expect("broker session adopt");
+    assert_eq!(session.route(), BackendConnectionRoute::BrokerNegotiated);
+
+    let err = session
+        .into_backend_io()
+        .expect_err("into_backend_io must be unsupported on Windows for now");
+    assert!(
+        matches!(err, IntoBackendIoError::WindowsUnsupported),
+        "expected WindowsUnsupported, got {err:?}"
+    );
+
+    broker.join().unwrap().unwrap();
+    backend.join().unwrap().unwrap();
+}
+
+#[cfg(all(unix, feature = "client-async"))]
+#[test]
+fn async_into_backend_io_hands_off_live_unix_socket() {
+    use std::os::unix::net::UnixStream;
+
+    let broker_socket = unique_socket_name("io-broker-async");
+    let backend_socket = unique_socket_name("io-backend-async");
+
+    let backend = spawn_raw_echo_backend(backend_socket.clone());
+    let broker = spawn_broker(broker_socket.clone(), backend_socket.clone());
+
+    let runtime = tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .expect("tokio runtime");
+    let fd = runtime.block_on(async {
+        let request =
+            OwnedConnectRequest::new(broker_socket.clone(), IO_SERVICE, IO_VERSION, IO_VERSION);
+        let session = AsyncBrokerSession::adopt(request)
+            .await
+            .expect("async broker session adopt");
+        assert_eq!(session.route(), BackendConnectionRoute::BrokerNegotiated);
+        session
+            .into_backend_io()
+            .expect("async into_backend_io on unix")
+            .into_owned_fd()
+    });
+
+    let mut raw = UnixStream::from(fd);
+    let proof = b"async-live-socket-proof";
+    raw.write_all(proof).expect("write over raw socket");
+    raw.flush().expect("flush");
+    let mut echoed = vec![0u8; proof.len()];
+    raw.read_exact(&mut echoed).expect("read raw echo");
+    assert_eq!(
+        &echoed, proof,
+        "raw socket must echo over the live connection"
+    );
+
+    drop(raw);
+    broker.join().unwrap().unwrap();
+    backend.join().unwrap().unwrap();
+}

{running_process-4.3.0 → running_process-4.4.0}/crates/running-process/tests/broker/main.rs

@@ -64,6 +64,7 @@ mod hello_version_blocked;
 mod idle_coord;
 mod instance;
 mod instance_isolation;
+mod into_backend_io;
 mod lifecycle_event_size;
 mod manifest_atomic;
 mod manifest_boot_id;

{running_process-4.3.0 → running_process-4.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "running_process"
-version = "4.3.0"
+version = "4.4.0"
 description = "A Rust-backed subprocess wrapper with split stdout/stderr streaming"
 readme = "README.md"
 requires-python = ">=3.10"

{running_process-4.3.0 → running_process-4.4.0}/src/running_process/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-__version__ = "4.3.0"
+__version__ = "4.4.0"
 
 from running_process._native import (
     ContainedProcessGroup,