From 194ff526d23e3d13f0a5dca9c0fce08b0a6be6ee Mon Sep 17 00:00:00 2001 From: Jeremy Rose Date: Wed, 10 Jun 2026 10:55:29 -0700 Subject: [PATCH] Harden streamed file handle lifecycle --- .../src/protocol/common.rs | 30 +- codex-rs/app-server/README.md | 4 +- .../src/request_processors/fs_processor.rs | 10 +- .../exec-server/src/file_handle_manager.rs | 256 ++++++++++++------ .../src/file_handle_manager_tests.rs | 146 ++++++++-- codex-rs/exec-server/src/lib.rs | 2 +- codex-rs/exec-server/src/local_file_system.rs | 112 ++++++-- .../src/local_file_system_streaming_tests.rs | 40 +++ .../exec-server/src/remote_file_system.rs | 62 +++-- .../src/server/file_system_handler.rs | 10 +- codex-rs/file-system/src/lib.rs | 12 +- file-streaming-api.md | 9 +- 12 files changed, 534 insertions(+), 159 deletions(-) create mode 100644 codex-rs/exec-server/src/local_file_system_streaming_tests.rs diff --git a/codex-rs/app-server-protocol/src/protocol/common.rs b/codex-rs/app-server-protocol/src/protocol/common.rs index 7ec2c80e2e..ac3816a622 100644 --- a/codex-rs/app-server-protocol/src/protocol/common.rs +++ b/codex-rs/app-server-protocol/src/protocol/common.rs @@ -735,7 +735,7 @@ client_request_definitions! { }, FsReadFileClose => "fs/readFile/close" { params: v2::FsReadFileCloseParams, - serialization: None, + serialization: file_handle_id(params.handle_id), response: v2::FsReadFileCloseResponse, }, FsWriteFileOpen => "fs/writeFile/open" { @@ -750,7 +750,7 @@ client_request_definitions! { }, FsWriteFileClose => "fs/writeFile/close" { params: v2::FsWriteFileCloseParams, - serialization: None, + serialization: file_handle_id(params.handle_id), response: v2::FsWriteFileCloseResponse, }, FsCreateDirectory => "fs/createDirectory" { @@ -1789,6 +1789,32 @@ mod tests { }) ); + let read_file_close = ClientRequest::FsReadFileClose { + request_id: request_id(), + params: v2::FsReadFileCloseParams { + handle_id: "file-1".to_string(), + }, + }; + assert_eq!( + read_file_close.serialization_scope(), + Some(ClientRequestSerializationScope::FileHandle { + handle_id: "file-1".to_string() + }) + ); + + let write_file_close = ClientRequest::FsWriteFileClose { + request_id: request_id(), + params: v2::FsWriteFileCloseParams { + handle_id: "file-1".to_string(), + }, + }; + assert_eq!( + write_file_close.serialization_scope(), + Some(ClientRequestSerializationScope::FileHandle { + handle_id: "file-1".to_string() + }) + ); + let plugin_install = ClientRequest::PluginInstall { request_id: request_id(), params: v2::PluginInstallParams { diff --git a/codex-rs/app-server/README.md b/codex-rs/app-server/README.md index 0c6d1bfac9..857e03f150 100644 --- a/codex-rs/app-server/README.md +++ b/codex-rs/app-server/README.md @@ -1160,11 +1160,11 @@ All filesystem paths in this section must be absolute. - `fs/createDirectory` defaults `recursive` to `true` when omitted. - `fs/remove` defaults both `recursive` and `force` to `true` when omitted. - `fs/readFile` always returns base64 bytes via `dataBase64`, and `fs/writeFile` always expects base64 bytes in `dataBase64`. -- Streaming file handles use caller-supplied `handleId` values scoped to one connection. The server advertises a 262144-byte decoded chunk limit from each open response. +- Streaming file handles use caller-supplied `handleId` values scoped to one connection. Each connection may have at most 64 opening or open file handles. The server advertises a 262144-byte decoded chunk limit from each open response. - `fs/readFile/read` is positional: pass an absolute byte `offset` and optional `maxBytes`. `eof` reports whether more bytes were available at that read; a growing file may later return more data. - `fs/readFile/stat` reads metadata from the opened file object, so it remains valid if the original path is renamed or replaced. - Opening a streamed write creates or truncates the destination immediately. Completed chunks are visible immediately, and cancellation, disconnection, or an I/O error may leave a partially written file. Existing file identity and metadata are preserved like `fs/writeFile`. -- `fs/readFile/close` and `fs/writeFile/close` are idempotent cancellation operations. Disconnecting closes all handles owned by that connection. +- `fs/readFile/close` and `fs/writeFile/close` are idempotent and serialized with other operations for the same handle. Close waits for an active operation to finish and prevents a pending open from becoming live. Disconnecting closes all handles owned by that connection. - `fs/copy` handles both file copies and directory-tree copies; it requires `recursive: true` when `sourcePath` is a directory. Recursive copies traverse regular files, directories, and symlinks; other entry types are skipped. ### Example: Filesystem watch diff --git a/codex-rs/app-server/src/request_processors/fs_processor.rs b/codex-rs/app-server/src/request_processors/fs_processor.rs index 88a6c4cbe0..aa2ffb0c2b 100644 --- a/codex-rs/app-server/src/request_processors/fs_processor.rs +++ b/codex-rs/app-server/src/request_processors/fs_processor.rs @@ -193,7 +193,10 @@ impl FsRequestProcessor { params: FsReadFileCloseParams, ) -> Result { if let Some(handles) = self.existing_handles(connection_id).await { - handles.close(¶ms.handle_id).await; + handles + .close(¶ms.handle_id) + .await + .map_err(map_file_handle_error)?; } Ok(FsReadFileCloseResponse {}) } @@ -244,7 +247,10 @@ impl FsRequestProcessor { params: FsWriteFileCloseParams, ) -> Result { if let Some(handles) = self.existing_handles(connection_id).await { - handles.close(¶ms.handle_id).await; + handles + .close(¶ms.handle_id) + .await + .map_err(map_file_handle_error)?; } Ok(FsWriteFileCloseResponse {}) } diff --git a/codex-rs/exec-server/src/file_handle_manager.rs b/codex-rs/exec-server/src/file_handle_manager.rs index 76b05318ce..f02e933a18 100644 --- a/codex-rs/exec-server/src/file_handle_manager.rs +++ b/codex-rs/exec-server/src/file_handle_manager.rs @@ -3,25 +3,34 @@ use std::io; use std::sync::Arc; use codex_file_system::ExecutorFileSystem; +use codex_file_system::FileReadChunk; use codex_file_system::FileReadHandle; use codex_file_system::FileSystemSandboxContext; use codex_file_system::FileWriteHandle; use codex_file_system::OpenFileMetadata; use codex_utils_absolute_path::AbsolutePathBuf; use tokio::sync::Mutex; +use tokio::sync::Semaphore; use tokio_util::sync::CancellationToken; -#[derive(Debug, Clone, Eq, PartialEq)] -pub struct FileReadChunk { - pub data: Vec, - pub eof: bool, -} +pub const MAX_OPEN_FILE_HANDLES: usize = 64; -#[derive(Clone, Default)] +#[derive(Clone)] pub struct FileHandleManager { handles: Arc>>, + max_handles: usize, } +impl Default for FileHandleManager { + fn default() -> Self { + Self { + handles: Arc::new(Mutex::new(HashMap::new())), + max_handles: MAX_OPEN_FILE_HANDLES, + } + } +} + +#[derive(Clone)] enum FileHandle { Opening(Arc), Read(Arc), @@ -30,21 +39,32 @@ enum FileHandle { struct OpeningHandleEntry { cancellation: CancellationToken, + completed: CancellationToken, } struct ReadHandleEntry { handle: Box, cancellation: CancellationToken, + operation: Semaphore, max_chunk_bytes: usize, } struct WriteHandleEntry { handle: Box, cancellation: CancellationToken, + operation: Semaphore, max_chunk_bytes: usize, } impl FileHandleManager { + #[cfg(test)] + fn with_max_handles(max_handles: usize) -> Self { + Self { + handles: Arc::new(Mutex::new(HashMap::new())), + max_handles, + } + } + pub async fn open_read( &self, file_system: Arc, @@ -53,6 +73,7 @@ impl FileHandleManager { sandbox: Option<&FileSystemSandboxContext>, ) -> io::Result { let opening = self.reserve_opening(&handle_id).await?; + let _completion = OpeningCompletionGuard(opening.completed.clone()); let handle = match file_system.open_file_for_read(path, sandbox).await { Ok(handle) => handle, Err(err) => { @@ -68,10 +89,16 @@ impl FileHandleManager { let entry = FileHandle::Read(Arc::new(ReadHandleEntry { handle, cancellation: opening.cancellation.clone(), + operation: Semaphore::new(1), max_chunk_bytes, })); - self.promote_opening(handle_id, &opening, entry).await?; - Ok(max_chunk_bytes) + match self.promote_opening(handle_id, &opening, entry).await { + Ok(()) => Ok(max_chunk_bytes), + Err(handle) => { + let _ = close_file_handle(handle).await; + Err(cancelled_handle_error()) + } + } } pub async fn read( @@ -90,33 +117,16 @@ impl FileHandleManager { "file read max bytes must be greater than zero", )); } - let result = tokio::select! { - _ = entry.cancellation.cancelled() => Err(cancelled_handle_error()), - result = entry.handle.read(offset, max_bytes) => result, - }; + let operation = acquire_operation(&entry.operation).await?; + if entry.cancellation.is_cancelled() { + return Err(cancelled_handle_error()); + } + let result = entry.handle.read(offset, max_bytes).await; + drop(operation); match result { - Ok(data) => { - let eof = if data.len() < max_bytes { - true - } else { - let metadata = tokio::select! { - _ = entry.cancellation.cancelled() => Err(cancelled_handle_error()), - result = entry.handle.metadata() => result, - }; - match metadata { - Ok(metadata) => { - offset.saturating_add(data.len() as u64) >= metadata.size_bytes - } - Err(err) => { - self.remove_if_read(handle_id, &entry).await; - return Err(err); - } - } - }; - Ok(FileReadChunk { data, eof }) - } + Ok(chunk) => Ok(chunk), Err(err) => { - self.remove_if_read(handle_id, &entry).await; + self.remove_and_close_read(handle_id, &entry).await; Err(err) } } @@ -124,12 +134,14 @@ impl FileHandleManager { pub async fn stat_read(&self, handle_id: &str) -> io::Result { let entry = self.read_entry(handle_id).await?; - let result = tokio::select! { - _ = entry.cancellation.cancelled() => Err(cancelled_handle_error()), - result = entry.handle.metadata() => result, - }; + let operation = acquire_operation(&entry.operation).await?; + if entry.cancellation.is_cancelled() { + return Err(cancelled_handle_error()); + } + let result = entry.handle.metadata().await; + drop(operation); if result.is_err() { - self.remove_if_read(handle_id, &entry).await; + self.remove_and_close_read(handle_id, &entry).await; } result } @@ -142,6 +154,7 @@ impl FileHandleManager { sandbox: Option<&FileSystemSandboxContext>, ) -> io::Result { let opening = self.reserve_opening(&handle_id).await?; + let _completion = OpeningCompletionGuard(opening.completed.clone()); let handle = match file_system.open_file_for_write(path, sandbox).await { Ok(handle) => handle, Err(err) => { @@ -157,10 +170,16 @@ impl FileHandleManager { let entry = FileHandle::Write(Arc::new(WriteHandleEntry { handle, cancellation: opening.cancellation.clone(), + operation: Semaphore::new(1), max_chunk_bytes, })); - self.promote_opening(handle_id, &opening, entry).await?; - Ok(max_chunk_bytes) + match self.promote_opening(handle_id, &opening, entry).await { + Ok(()) => Ok(max_chunk_bytes), + Err(handle) => { + let _ = close_file_handle(handle).await; + Err(cancelled_handle_error()) + } + } } pub async fn write(&self, handle_id: &str, data: &[u8]) -> io::Result<()> { @@ -174,34 +193,33 @@ impl FileHandleManager { ), )); } - let result = tokio::select! { - _ = entry.cancellation.cancelled() => Err(cancelled_handle_error()), - result = entry.handle.write(data) => result, - }; + let operation = acquire_operation(&entry.operation).await?; + if entry.cancellation.is_cancelled() { + return Err(cancelled_handle_error()); + } + let result = entry.handle.write(data).await; + drop(operation); if result.is_err() { - self.remove_if_write(handle_id, &entry).await; + self.remove_and_close_write(handle_id, &entry).await; } result } - pub async fn close(&self, handle_id: &str) { - let handle = self.handles.lock().await.remove(handle_id); - match handle { - Some(FileHandle::Opening(entry)) => entry.cancellation.cancel(), - Some(FileHandle::Read(entry)) => entry.cancellation.cancel(), - Some(FileHandle::Write(entry)) => entry.cancellation.cancel(), - None => {} - } + pub async fn close(&self, handle_id: &str) -> io::Result<()> { + let handle = self.handles.lock().await.get(handle_id).cloned(); + let Some(handle) = handle else { + return Ok(()); + }; + let result = close_file_handle(handle.clone()).await; + self.remove_if_handle(handle_id, &handle).await; + result } pub async fn close_all(&self) { - let handles = std::mem::take(&mut *self.handles.lock().await); - for handle in handles.into_values() { - match handle { - FileHandle::Opening(entry) => entry.cancellation.cancel(), - FileHandle::Read(entry) => entry.cancellation.cancel(), - FileHandle::Write(entry) => entry.cancellation.cancel(), - } + let handles = self.handles.lock().await.clone(); + for (handle_id, handle) in handles { + let _ = close_file_handle(handle.clone()).await; + self.remove_if_handle(&handle_id, &handle).await; } } @@ -219,8 +237,15 @@ impl FileHandleManager { format!("file handle `{handle_id}` is already open"), )); } + if handles.len() >= self.max_handles { + return Err(io::Error::new( + io::ErrorKind::InvalidInput, + format!("open file handle limit of {} reached", self.max_handles), + )); + } let opening = Arc::new(OpeningHandleEntry { cancellation: CancellationToken::new(), + completed: CancellationToken::new(), }); handles.insert( handle_id.to_string(), @@ -234,17 +259,14 @@ impl FileHandleManager { handle_id: String, opening: &Arc, handle: FileHandle, - ) -> io::Result<()> { + ) -> Result<(), FileHandle> { let mut handles = self.handles.lock().await; let owns_reservation = matches!( handles.get(&handle_id), Some(FileHandle::Opening(current)) if Arc::ptr_eq(current, opening) ); if opening.cancellation.is_cancelled() || !owns_reservation { - if owns_reservation { - handles.remove(&handle_id); - } - return Err(cancelled_handle_error()); + return Err(handle); } handles.insert(handle_id, handle); Ok(()) @@ -278,27 +300,105 @@ impl FileHandleManager { } } - async fn remove_if_read(&self, handle_id: &str, expected: &Arc) { + async fn remove_if_handle(&self, handle_id: &str, expected: &FileHandle) { let mut handles = self.handles.lock().await; - if matches!( - handles.get(handle_id), - Some(FileHandle::Read(entry)) if Arc::ptr_eq(entry, expected) - ) { + if handles + .get(handle_id) + .is_some_and(|current| current.ptr_eq(expected)) + { handles.remove(handle_id); - expected.cancellation.cancel(); } } - async fn remove_if_write(&self, handle_id: &str, expected: &Arc) { - let mut handles = self.handles.lock().await; - if matches!( - handles.get(handle_id), - Some(FileHandle::Write(entry)) if Arc::ptr_eq(entry, expected) - ) { - handles.remove(handle_id); + async fn remove_and_close_read(&self, handle_id: &str, expected: &Arc) { + let handle = FileHandle::Read(Arc::clone(expected)); + let owns_handle = self + .handles + .lock() + .await + .get(handle_id) + .is_some_and(|current| current.ptr_eq(&handle)); + if owns_handle { expected.cancellation.cancel(); + let Ok(operation) = acquire_operation(&expected.operation).await else { + return; + }; + let _ = expected.handle.close().await; + drop(operation); + self.remove_if_handle(handle_id, &handle).await; } } + + async fn remove_and_close_write(&self, handle_id: &str, expected: &Arc) { + let handle = FileHandle::Write(Arc::clone(expected)); + let owns_handle = self + .handles + .lock() + .await + .get(handle_id) + .is_some_and(|current| current.ptr_eq(&handle)); + if owns_handle { + expected.cancellation.cancel(); + let Ok(operation) = acquire_operation(&expected.operation).await else { + return; + }; + let _ = expected.handle.close().await; + drop(operation); + self.remove_if_handle(handle_id, &handle).await; + } + } +} + +impl FileHandle { + fn ptr_eq(&self, other: &Self) -> bool { + match (self, other) { + (Self::Opening(left), Self::Opening(right)) => Arc::ptr_eq(left, right), + (Self::Read(left), Self::Read(right)) => Arc::ptr_eq(left, right), + (Self::Write(left), Self::Write(right)) => Arc::ptr_eq(left, right), + (Self::Opening(_), Self::Read(_) | Self::Write(_)) + | (Self::Read(_), Self::Opening(_) | Self::Write(_)) + | (Self::Write(_), Self::Opening(_) | Self::Read(_)) => false, + } + } +} + +async fn close_file_handle(handle: FileHandle) -> io::Result<()> { + match handle { + FileHandle::Opening(entry) => { + entry.cancellation.cancel(); + entry.completed.cancelled().await; + Ok(()) + } + FileHandle::Read(entry) => { + entry.cancellation.cancel(); + let operation = acquire_operation(&entry.operation).await?; + let result = entry.handle.close().await; + drop(operation); + result + } + FileHandle::Write(entry) => { + entry.cancellation.cancel(); + let operation = acquire_operation(&entry.operation).await?; + let result = entry.handle.close().await; + drop(operation); + result + } + } +} + +async fn acquire_operation(operation: &Semaphore) -> io::Result> { + operation + .acquire() + .await + .map_err(|_| io::Error::new(io::ErrorKind::BrokenPipe, "file handle is closed")) +} + +struct OpeningCompletionGuard(CancellationToken); + +impl Drop for OpeningCompletionGuard { + fn drop(&mut self) { + self.0.cancel(); + } } fn unknown_handle_error(handle_id: &str) -> io::Error { diff --git a/codex-rs/exec-server/src/file_handle_manager_tests.rs b/codex-rs/exec-server/src/file_handle_manager_tests.rs index 3c10fbfd9e..2f5c8a65d6 100644 --- a/codex-rs/exec-server/src/file_handle_manager_tests.rs +++ b/codex-rs/exec-server/src/file_handle_manager_tests.rs @@ -5,6 +5,7 @@ use codex_file_system::CreateDirectoryOptions; use codex_file_system::FileMetadata; use codex_file_system::ReadDirectoryEntry; use codex_file_system::RemoveOptions; +use pretty_assertions::assert_eq; use std::path::Path; use std::sync::atomic::AtomicBool; use std::sync::atomic::Ordering; @@ -161,9 +162,15 @@ impl FileReadHandle for TestReadHandle { fn read( &self, _offset: u64, - _max_bytes: usize, - ) -> std::pin::Pin>> + Send + '_>> { - unreachable!("read is not used by these tests") + max_bytes: usize, + ) -> std::pin::Pin> + Send + '_>> + { + Box::pin(async move { + Ok(FileReadChunk { + data: vec![b'x'; max_bytes], + eof: true, + }) + }) } fn metadata( @@ -173,6 +180,12 @@ impl FileReadHandle for TestReadHandle { > { unreachable!("metadata is not used by these tests") } + + fn close( + &self, + ) -> std::pin::Pin> + Send + '_>> { + Box::pin(async { Ok(()) }) + } } impl Drop for TestReadHandle { @@ -196,6 +209,12 @@ impl FileWriteHandle for TestWriteHandle { ) -> std::pin::Pin> + Send + 'a>> { unreachable!("write is not used by these tests") } + + fn close( + &self, + ) -> std::pin::Pin> + Send + '_>> { + Box::pin(async { Ok(()) }) + } } impl Drop for TestWriteHandle { @@ -220,7 +239,12 @@ async fn close_during_read_open_prevents_handle_from_becoming_live() { }; file_system.read_started.notified().await; - manager.close("read-1").await; + let close = { + let manager = manager.clone(); + tokio::spawn(async move { manager.close("read-1").await }) + }; + tokio::task::yield_now().await; + assert!(!close.is_finished()); file_system.read_release.add_permits(1); let err = open @@ -228,6 +252,7 @@ async fn close_during_read_open_prevents_handle_from_becoming_live() { .expect("join read open") .expect_err("closed read open should fail"); assert_eq!(err.kind(), io::ErrorKind::Interrupted); + close.await.expect("join read close").expect("close read"); assert!(file_system.read_handle_dropped.load(Ordering::SeqCst)); assert_eq!( manager @@ -255,7 +280,12 @@ async fn close_during_write_open_prevents_handle_from_becoming_live() { }; file_system.write_started.notified().await; - manager.close("write-1").await; + let close = { + let manager = manager.clone(); + tokio::spawn(async move { manager.close("write-1").await }) + }; + tokio::task::yield_now().await; + assert!(!close.is_finished()); file_system.write_release.add_permits(1); let err = open @@ -263,6 +293,7 @@ async fn close_during_write_open_prevents_handle_from_becoming_live() { .expect("join write open") .expect_err("closed write open should fail"); assert_eq!(err.kind(), io::ErrorKind::Interrupted); + close.await.expect("join write close").expect("close write"); assert!(file_system.write_handle_dropped.load(Ordering::SeqCst)); assert_eq!( manager @@ -275,7 +306,7 @@ async fn close_during_write_open_prevents_handle_from_becoming_live() { } #[tokio::test] -async fn delayed_open_cannot_overwrite_reused_handle_id() { +async fn closing_open_reserves_handle_id_until_cleanup_finishes() { let manager = FileHandleManager::default(); let first_file_system = Arc::new(BlockingFileSystem::default()); let path = AbsolutePathBuf::from_absolute_path(std::env::temp_dir()).expect("absolute path"); @@ -291,9 +322,36 @@ async fn delayed_open_cannot_overwrite_reused_handle_id() { }; first_file_system.read_started.notified().await; - manager.close("read-1").await; + let close = { + let manager = manager.clone(); + tokio::spawn(async move { manager.close("read-1").await }) + }; + tokio::task::yield_now().await; let second_file_system = Arc::new(BlockingFileSystem::default()); + assert_eq!( + manager + .open_read( + second_file_system.clone(), + "read-1".to_string(), + &path, + None, + ) + .await + .expect_err("closing handle id should remain reserved") + .kind(), + io::ErrorKind::AlreadyExists + ); + + first_file_system.read_release.add_permits(1); + let err = first_open + .await + .expect("join first read open") + .expect_err("closed first read open should fail"); + assert_eq!(err.kind(), io::ErrorKind::Interrupted); + close.await.expect("join read close").expect("close read"); + assert!(first_file_system.read_handle_dropped.load(Ordering::SeqCst)); + let second_open = { let manager = manager.clone(); let file_system = Arc::clone(&second_file_system); @@ -313,19 +371,73 @@ async fn delayed_open_cannot_overwrite_reused_handle_id() { 16 ); - first_file_system.read_release.add_permits(1); - let err = first_open - .await - .expect("join first read open") - .expect_err("closed first read open should fail"); - assert_eq!(err.kind(), io::ErrorKind::Interrupted); - assert!(first_file_system.read_handle_dropped.load(Ordering::SeqCst)); - assert!(manager.read_entry("read-1").await.is_ok()); - - manager.close("read-1").await; + manager.close("read-1").await.expect("close second read"); assert!( second_file_system .read_handle_dropped .load(Ordering::SeqCst) ); } + +#[tokio::test] +async fn read_uses_handle_authoritative_eof() { + let manager = FileHandleManager::default(); + let file_system = Arc::new(BlockingFileSystem::default()); + let path = AbsolutePathBuf::from_absolute_path(std::env::temp_dir()).expect("absolute path"); + let open = { + let manager = manager.clone(); + let file_system = Arc::clone(&file_system); + tokio::spawn(async move { + manager + .open_read(file_system, "read-1".to_string(), &path, None) + .await + }) + }; + + file_system.read_started.notified().await; + file_system.read_release.add_permits(1); + open.await + .expect("join read open") + .expect("open read handle"); + + assert_eq!( + manager.read("read-1", 0, Some(16)).await.expect("read"), + FileReadChunk { + data: vec![b'x'; 16], + eof: true, + } + ); +} + +#[tokio::test] +async fn open_handle_count_is_bounded() { + let manager = FileHandleManager::with_max_handles(1); + let file_system = Arc::new(BlockingFileSystem::default()); + let path = AbsolutePathBuf::from_absolute_path(std::env::temp_dir()).expect("absolute path"); + let open = { + let manager = manager.clone(); + let file_system = Arc::clone(&file_system); + let path = path.clone(); + tokio::spawn(async move { + manager + .open_read(file_system, "read-1".to_string(), &path, None) + .await + }) + }; + + file_system.read_started.notified().await; + assert_eq!( + manager + .open_read(file_system.clone(), "read-2".to_string(), &path, None) + .await + .expect_err("second handle should exceed limit") + .kind(), + io::ErrorKind::InvalidInput + ); + + file_system.read_release.add_permits(1); + open.await + .expect("join read open") + .expect("open read handle"); + manager.close("read-1").await.expect("close read"); +} diff --git a/codex-rs/exec-server/src/lib.rs b/codex-rs/exec-server/src/lib.rs index ce05bbc3a0..f90de277ce 100644 --- a/codex-rs/exec-server/src/lib.rs +++ b/codex-rs/exec-server/src/lib.rs @@ -36,6 +36,7 @@ pub use codex_file_system::CopyOptions; pub use codex_file_system::CreateDirectoryOptions; pub use codex_file_system::ExecutorFileSystem; pub use codex_file_system::FileMetadata; +pub use codex_file_system::FileReadChunk; pub use codex_file_system::FileReadHandle; pub use codex_file_system::FileSystemResult; pub use codex_file_system::FileSystemSandboxContext; @@ -52,7 +53,6 @@ pub use environment_path::EnvironmentPathRef; pub use environment_provider::DefaultEnvironmentProvider; pub use environment_provider::EnvironmentProvider; pub use file_handle_manager::FileHandleManager; -pub use file_handle_manager::FileReadChunk; pub use fs_helper::CODEX_FS_HELPER_ARG1; pub use fs_helper_main::main as run_fs_helper_main; pub use local_file_system::LOCAL_FS; diff --git a/codex-rs/exec-server/src/local_file_system.rs b/codex-rs/exec-server/src/local_file_system.rs index 6105fdc950..b414fe6823 100644 --- a/codex-rs/exec-server/src/local_file_system.rs +++ b/codex-rs/exec-server/src/local_file_system.rs @@ -1,5 +1,6 @@ use async_trait::async_trait; use codex_file_system::DEFAULT_FILE_STREAM_CHUNK_BYTES; +use codex_file_system::FileReadChunk; use codex_file_system::FileReadHandle; use codex_file_system::FileWriteHandle; use codex_file_system::OpenFileMetadata; @@ -377,7 +378,10 @@ impl ExecutorFileSystem for DirectFileSystem { sandbox: Option<&FileSystemSandboxContext>, ) -> FileSystemResult> { reject_sandbox_context(sandbox)?; - let file = std::fs::File::open(path.as_path())?; + let path = path.as_path().to_path_buf(); + let file = tokio::task::spawn_blocking(move || std::fs::File::open(path)) + .await + .map_err(|err| io::Error::other(format!("filesystem task failed: {err}")))??; Ok(Box::new(DirectFileReadHandle { file })) } @@ -387,8 +391,16 @@ impl ExecutorFileSystem for DirectFileSystem { sandbox: Option<&FileSystemSandboxContext>, ) -> FileSystemResult> { reject_sandbox_context(sandbox)?; - let file = std::fs::File::create(path.as_path())?; - Ok(Box::new(DirectFileWriteHandle { file })) + let path = path.as_path().to_path_buf(); + let file = tokio::task::spawn_blocking(move || std::fs::File::create(path)) + .await + .map_err(|err| io::Error::other(format!("filesystem task failed: {err}")))??; + Ok(Box::new(DirectFileWriteHandle { + state: tokio::sync::Mutex::new(DirectFileWriteState { + file: Some(file), + write_task: None, + }), + })) } async fn create_directory( @@ -537,21 +549,26 @@ impl FileReadHandle for DirectFileReadHandle { &self, offset: u64, max_bytes: usize, - ) -> std::pin::Pin>> + Send + '_>> - { + ) -> std::pin::Pin< + Box> + Send + '_>, + > { let file = self.file.try_clone(); Box::pin(async move { let file = file?; let mut bytes = vec![0; max_bytes.min(DEFAULT_FILE_STREAM_CHUNK_BYTES)]; - let (bytes_read, mut bytes) = - tokio::task::spawn_blocking(move || -> io::Result<(usize, Vec)> { - let bytes_read = read_file_at(&file, &mut bytes, offset)?; - Ok((bytes_read, bytes)) - }) - .await - .map_err(|err| io::Error::other(format!("filesystem task failed: {err}")))??; - bytes.truncate(bytes_read); - Ok(bytes) + tokio::task::spawn_blocking(move || -> io::Result { + let requested_bytes = bytes.len(); + let bytes_read = read_file_at(&file, &mut bytes, offset)?; + bytes.truncate(bytes_read); + let eof = if bytes_read < requested_bytes { + true + } else { + offset.saturating_add(bytes_read as u64) >= file.metadata()?.len() + }; + Ok(FileReadChunk { data: bytes, eof }) + }) + .await + .map_err(|err| io::Error::other(format!("filesystem task failed: {err}")))? }) } @@ -573,6 +590,13 @@ impl FileReadHandle for DirectFileReadHandle { }) }) } + + fn close( + &self, + ) -> std::pin::Pin> + Send + '_>> + { + Box::pin(async { Ok(()) }) + } } #[cfg(unix)] @@ -592,8 +616,13 @@ fn read_file_at(file: &std::fs::File, bytes: &mut [u8], offset: u64) -> io::Resu std::io::Read::read(&mut file, bytes) } +struct DirectFileWriteState { + file: Option, + write_task: Option)>>, +} + struct DirectFileWriteHandle { - file: std::fs::File, + state: tokio::sync::Mutex, } impl FileWriteHandle for DirectFileWriteHandle { @@ -601,12 +630,15 @@ impl FileWriteHandle for DirectFileWriteHandle { DEFAULT_FILE_STREAM_CHUNK_BYTES } + #[expect( + clippy::await_holding_invalid_type, + reason = "the state lock keeps the tracked blocking write attached across cancellation" + )] fn write<'a>( &'a self, data: &'a [u8], ) -> std::pin::Pin> + Send + 'a>> { - let file = self.file.try_clone(); Box::pin(async move { if data.len() > DEFAULT_FILE_STREAM_CHUNK_BYTES { return Err(io::Error::new( @@ -616,16 +648,48 @@ impl FileWriteHandle for DirectFileWriteHandle { ), )); } - let file = file?; + let mut state = self.state.lock().await; + finish_direct_write(&mut state).await?; + let file = state.file.take().ok_or_else(|| { + io::Error::new(io::ErrorKind::BrokenPipe, "file write handle is closed") + })?; let data = data.to_vec(); - tokio::task::spawn_blocking(move || { + state.write_task = Some(tokio::task::spawn_blocking(move || { let mut file = file; - std::io::Write::write_all(&mut file, &data) - }) - .await - .map_err(|err| io::Error::other(format!("filesystem task failed: {err}")))? + let result = std::io::Write::write_all(&mut file, &data); + (file, result) + })); + finish_direct_write(&mut state).await }) } + + #[expect( + clippy::await_holding_invalid_type, + reason = "close must join the tracked blocking write before dropping the file" + )] + fn close( + &self, + ) -> std::pin::Pin> + Send + '_>> + { + Box::pin(async move { + let mut state = self.state.lock().await; + let result = finish_direct_write(&mut state).await; + state.file.take(); + result + }) + } +} + +async fn finish_direct_write(state: &mut DirectFileWriteState) -> FileSystemResult<()> { + let Some(write_task) = state.write_task.as_mut() else { + return Ok(()); + }; + let (file, result) = write_task + .await + .map_err(|err| io::Error::other(format!("filesystem task failed: {err}")))?; + state.write_task = None; + state.file = Some(file); + result } fn reject_sandbox_context(sandbox: Option<&FileSystemSandboxContext>) -> io::Result<()> { @@ -799,3 +863,7 @@ mod tests { Ok(()) } } + +#[cfg(test)] +#[path = "local_file_system_streaming_tests.rs"] +mod streaming_tests; diff --git a/codex-rs/exec-server/src/local_file_system_streaming_tests.rs b/codex-rs/exec-server/src/local_file_system_streaming_tests.rs new file mode 100644 index 0000000000..738ce2d266 --- /dev/null +++ b/codex-rs/exec-server/src/local_file_system_streaming_tests.rs @@ -0,0 +1,40 @@ +use super::*; +use pretty_assertions::assert_eq; + +#[tokio::test] +async fn close_waits_for_in_flight_blocking_write() -> io::Result<()> { + let temp_dir = tempfile::TempDir::new()?; + let path = temp_dir.path().join("output"); + let file = std::fs::File::create(&path)?; + let (started_tx, started_rx) = std::sync::mpsc::channel(); + let (release_tx, release_rx) = std::sync::mpsc::channel(); + let write_task = tokio::task::spawn_blocking(move || { + started_tx.send(()).expect("signal write start"); + release_rx.recv().expect("release write"); + let mut file = file; + let result = std::io::Write::write_all(&mut file, b"x"); + (file, result) + }); + let handle = Arc::new(DirectFileWriteHandle { + state: tokio::sync::Mutex::new(DirectFileWriteState { + file: None, + write_task: Some(write_task), + }), + }); + tokio::task::spawn_blocking(move || started_rx.recv()) + .await + .expect("join write start") + .expect("wait for write start"); + + let close = { + let handle = Arc::clone(&handle); + tokio::spawn(async move { handle.close().await }) + }; + tokio::task::yield_now().await; + assert!(!close.is_finished()); + + release_tx.send(()).expect("release write"); + close.await.expect("join close")?; + assert_eq!(std::fs::read(path)?, b"x"); + Ok(()) +} diff --git a/codex-rs/exec-server/src/remote_file_system.rs b/codex-rs/exec-server/src/remote_file_system.rs index 999e06b068..9185f5112e 100644 --- a/codex-rs/exec-server/src/remote_file_system.rs +++ b/codex-rs/exec-server/src/remote_file_system.rs @@ -1,6 +1,7 @@ use async_trait::async_trait; use base64::Engine as _; use base64::engine::general_purpose::STANDARD; +use codex_file_system::FileReadChunk; use codex_file_system::FileReadHandle; use codex_file_system::FileWriteHandle; use codex_file_system::OpenFileMetadata; @@ -306,8 +307,9 @@ impl FileReadHandle for RemoteFileReadHandle { &self, offset: u64, max_bytes: usize, - ) -> std::pin::Pin>> + Send + '_>> - { + ) -> std::pin::Pin< + Box> + Send + '_>, + > { Box::pin(async move { let response = self .client @@ -318,11 +320,15 @@ impl FileReadHandle for RemoteFileReadHandle { }) .await .map_err(map_remote_error)?; - STANDARD.decode(response.data_base64).map_err(|err| { + let data = STANDARD.decode(response.data_base64).map_err(|err| { io::Error::new( io::ErrorKind::InvalidData, format!("remote fs/readFile/read returned invalid base64 dataBase64: {err}"), ) + })?; + Ok(FileReadChunk { + data, + eof: response.eof, }) }) } @@ -347,19 +353,20 @@ impl FileReadHandle for RemoteFileReadHandle { }) }) } -} -impl Drop for RemoteFileReadHandle { - fn drop(&mut self) { - let client = self.client.clone(); - let handle_id = self.handle_id.clone(); - if let Ok(runtime) = tokio::runtime::Handle::try_current() { - runtime.spawn(async move { - let _ = client - .fs_read_file_close(FsReadFileCloseParams { handle_id }) - .await; - }); - } + fn close( + &self, + ) -> std::pin::Pin> + Send + '_>> + { + Box::pin(async move { + self.client + .fs_read_file_close(FsReadFileCloseParams { + handle_id: self.handle_id.clone(), + }) + .await + .map_err(map_remote_error)?; + Ok(()) + }) } } @@ -390,19 +397,20 @@ impl FileWriteHandle for RemoteFileWriteHandle { Ok(()) }) } -} -impl Drop for RemoteFileWriteHandle { - fn drop(&mut self) { - let client = self.client.clone(); - let handle_id = self.handle_id.clone(); - if let Ok(runtime) = tokio::runtime::Handle::try_current() { - runtime.spawn(async move { - let _ = client - .fs_write_file_close(FsWriteFileCloseParams { handle_id }) - .await; - }); - } + fn close( + &self, + ) -> std::pin::Pin> + Send + '_>> + { + Box::pin(async move { + self.client + .fs_write_file_close(FsWriteFileCloseParams { + handle_id: self.handle_id.clone(), + }) + .await + .map_err(map_remote_error)?; + Ok(()) + }) } } diff --git a/codex-rs/exec-server/src/server/file_system_handler.rs b/codex-rs/exec-server/src/server/file_system_handler.rs index f79b0199c7..6653ea5850 100644 --- a/codex-rs/exec-server/src/server/file_system_handler.rs +++ b/codex-rs/exec-server/src/server/file_system_handler.rs @@ -151,7 +151,10 @@ impl FileSystemHandler { &self, params: FsReadFileCloseParams, ) -> Result { - self.handles.close(¶ms.handle_id).await; + self.handles + .close(¶ms.handle_id) + .await + .map_err(map_fs_error)?; Ok(FsReadFileCloseResponse {}) } @@ -192,7 +195,10 @@ impl FileSystemHandler { &self, params: FsWriteFileCloseParams, ) -> Result { - self.handles.close(¶ms.handle_id).await; + self.handles + .close(¶ms.handle_id) + .await + .map_err(map_fs_error)?; Ok(FsWriteFileCloseResponse {}) } diff --git a/codex-rs/file-system/src/lib.rs b/codex-rs/file-system/src/lib.rs index 6b80c4e000..78e7cff3e3 100644 --- a/codex-rs/file-system/src/lib.rs +++ b/codex-rs/file-system/src/lib.rs @@ -48,6 +48,12 @@ pub struct OpenFileMetadata { pub modified_at_ms: i64, } +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct FileReadChunk { + pub data: Vec, + pub eof: bool, +} + #[derive(Clone, Debug, Eq, PartialEq)] pub struct ReadDirectoryEntry { pub file_name: String, @@ -151,11 +157,13 @@ pub trait FileReadHandle: Send + Sync { &self, offset: u64, max_bytes: usize, - ) -> Pin>> + Send + '_>>; + ) -> Pin> + Send + '_>>; fn metadata( &self, ) -> Pin> + Send + '_>>; + + fn close(&self) -> Pin> + Send + '_>>; } /// An open file used for bounded sequential writes. @@ -170,6 +178,8 @@ pub trait FileWriteHandle: Send + Sync { &'a self, data: &'a [u8], ) -> Pin> + Send + 'a>>; + + fn close(&self) -> Pin> + Send + '_>>; } /// Abstract filesystem access used by components that may operate locally or via diff --git a/file-streaming-api.md b/file-streaming-api.md index ef9e13600f..601e7c7794 100644 --- a/file-streaming-api.md +++ b/file-streaming-api.md @@ -163,6 +163,7 @@ Response: - Handle IDs are client-supplied strings scoped to one connection. - Opening a duplicate active handle ID returns `INVALID_REQUEST`. +- Each connection may have at most 64 opening or open file handles. - Operations for one handle are serialized. Different handles may run concurrently. - Reads are positional and do not maintain a server-side cursor. @@ -173,11 +174,9 @@ Response: - Backpressure comes from awaiting bounded read and write responses. Clients should use a bounded pipeline of up to two read requests to hide transport round-trip latency without accumulating unbounded response data. -- Close operations are idempotent. App-server close requests bypass queued - operations and cancel an active open or chunk operation. A close received - while open is pending prevents that handle from becoming live. Exec-server - handles bounded file RPCs in request order, so close takes effect before the - next file operation. +- Close operations are idempotent and serialized with other operations for the + same handle. Close waits for an active operation to finish, rejects queued + operations, and prevents a pending open from becoming live. - Closing a connection closes all of its handles. - Any filesystem or I/O error closes the affected handle. Protocol errors such as an unknown handle do not affect other handles.