b10-transfer 0.1.4__tar.gz → 0.1.6__tar.gz

{b10_transfer-0.1.4 → b10_transfer-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: b10-transfer
-Version: 0.1.4
+Version: 0.1.6
 Summary: Distributed PyTorch file transfer for Baseten - Environment-aware, lock-free file transfer management
 License: MIT
 Keywords: pytorch,file-transfer,cache,machine-learning,inference

{b10_transfer-0.1.4 → b10_transfer-0.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "b10-transfer"
-version = "0.1.4"
+version = "0.1.6"
 description = "Distributed PyTorch file transfer for Baseten - Environment-aware, lock-free file transfer management"
 authors = ["Shounak Ray <shounak.noreply@baseten.co>", "Fred Liu <fred.liu.noreply@baseten.co>"]
 maintainers = ["Fred Liu <fred.liu.noreply@baseten.co>", "Shounak Ray <shounak.noreply@baseten.co>"]

{b10_transfer-0.1.4 → b10_transfer-0.1.6}/src/b10_transfer/__init__.py

@@ -1,23 +1,24 @@
 """B10 Transfer - Lock-free PyTorch file transfer for Baseten."""
 
-from .core import load_compile_cache, save_compile_cache, clear_local_cache
+from .cache import load_compile_cache, save_compile_cache, clear_local_cache
+from .core import transfer
 from .utils import CacheError, CacheValidationError
 from .space_monitor import CacheOperationInterrupted
 from .info import get_cache_info, list_available_caches
-from .constants import SaveStatus, LoadStatus
+from .constants import OperationStatus
 
 # Version
-__version__ = "0.1.4"
+__version__ = "0.1.6"
 
 __all__ = [
     "CacheError",
     "CacheValidationError",
     "CacheOperationInterrupted",
-    "SaveStatus",
-    "LoadStatus",
+    "OperationStatus",
     "load_compile_cache",
     "save_compile_cache",
     "clear_local_cache",
+    "transfer",
     "get_cache_info",
     "list_available_caches",
 ]

b10_transfer-0.1.4/src/b10_transfer/core.py → b10_transfer-0.1.6/src/b10_transfer/cache.py

@@ -1,11 +1,13 @@
-import os
+"""Cache operations for PyTorch compilation artifacts.
+
+This module provides functions for loading and saving PyTorch compilation cache
+to/from b10fs shared storage using atomic operations and space monitoring.
+"""
+
 import logging
 import tempfile
-import shutil
 from pathlib import Path
 
-import time
-
 from .environment import get_cache_filename
 from .cleanup import cooperative_cleanup_b10fs
 from .utils import (
@@ -17,7 +19,6 @@ from .utils import (
     safe_unlink,
 )
 from .space_monitor import (
-    check_sufficient_disk_space,
     CacheSpaceMonitor,
     CacheOperationInterrupted,
     run_monitored_process,
@@ -33,17 +34,100 @@ from .constants import (
     CACHE_FILE_EXTENSION,
     CACHE_LATEST_SUFFIX,
     CACHE_INCOMPLETE_SUFFIX,
-    LoadStatus,
-    SaveStatus,
-    TransferStatus,
+    OperationStatus,
 )
+from .core import transfer
 
 logger = logging.getLogger(__name__)
 
 
+"""
+FIXME(SRAY):
+What about the case in @b10-transfer/ where a single pod finishes an inference request,
+and then the client calls save_compile_cache. And while we are creating the local archive,
+another inference call on the same pod is kicked off, which then modifies the torch cache.
+How would this be handled? Maybe just accept that the cache will be recompiled/overwritten?
+Otherwise you'd need application level coordination to ensure that the cache is not modified
+while we are creating the archive, but this doesn't really seem like a good idea in terms of adoption.
+
+FIXME(SR):
+More things to consider:
+- [possible] What if b10fs dies *during* an op? right now we check for b10fs availability in the beginning of the op... Add some constants instead of just False for load().
+- [possible, and really bad if it happens] potential memory exhaustion during compression if the cache is super super large. very very edge case. higher compression levels also have high memory usage.
+"""
+
+
+def _setup_cache_paths():
+    """Common setup for cache operations - returns paths and performs cleanup."""
+    # Cooperative cleanup of stale shared resources
+    cooperative_cleanup_b10fs()
+
+    b10fs_dir = Path(B10FS_CACHE_DIR)
+    torch_dir = Path(TORCH_CACHE_DIR)
+    work_dir = Path(LOCAL_WORK_DIR)
+
+    return b10fs_dir, torch_dir, work_dir
+
+
+def _get_cache_file_paths(cache_filename: str, b10fs_dir: Path):
+    """Generate cache file paths for a given cache filename."""
+    final_file = (
+        b10fs_dir / f"{cache_filename}{CACHE_LATEST_SUFFIX}{CACHE_FILE_EXTENSION}"
+    )
+    temp_file = (
+        b10fs_dir / f"{cache_filename}{CACHE_INCOMPLETE_SUFFIX}{CACHE_FILE_EXTENSION}"
+    )
+    return final_file, temp_file
+
+
+def _run_with_space_monitoring(
+    space_threshold_mb: float,
+    monitor_dir: Path,
+    operation_name: str,
+    worker_func,
+    worker_args: tuple,
+    cleanup_func=None,
+):
+    """Helper to run an operation with space monitoring."""
+    space_monitor = CacheSpaceMonitor(space_threshold_mb, monitor_dir)
+    space_monitor.start()
+
+    try:
+        logger.info(
+            f"Starting {operation_name}: {' -> '.join(str(arg) for arg in worker_args[:2])}"
+        )
+        run_monitored_process(
+            worker_func,
+            worker_args,
+            space_monitor,
+            operation_name,
+            cleanup_func=cleanup_func,
+        )
+    finally:
+        space_monitor.stop()
+
+
+def _transfer_with_b10fs_lock(
+    source: str, dest: str, lock_type: str, cleanup_on_failure=True
+):
+    """Transfer a file with b10fs file locking and error handling."""
+
+    @critical_section_b10fs_file_lock(lock_type)
+    def _locked_transfer():
+        result = transfer(source, dest)
+        if result != OperationStatus.SUCCESS:
+            if cleanup_on_failure:
+                safe_unlink(
+                    Path(dest), f"Failed to cleanup after failed transfer {dest}"
+                )
+            raise Exception(f"Failed to transfer {source} -> {dest}")
+
+    _locked_transfer()
+
+
 @timed_fn(logger=logger, name="Loading compile cache")
 @safe_execute("Load failed", False)
-def load_compile_cache() -> LoadStatus:
+def load_compile_cache() -> OperationStatus:
     """Load PyTorch compilation cache from b10fs to local torch cache directory.
 
     This function implements a lock-free pattern to safely load cached PyTorch
@@ -55,40 +139,33 @@ def load_compile_cache() -> LoadStatus:
     extraction phases, interrupting operations if space falls below MIN_LOCAL_SPACE_MB.
 
     Returns:
-        LoadStatus:
-              LoadStatus.SUCCESS if cache was successfully loaded
-              LoadStatus.SKIPPED if already exists
-              LoadStatus.ERROR if b10fs is unavailable, local disk space is insufficient, or loading failed.
-              LoadStatus.DOES_NOT_EXIST if no cache file was found.
+        OperationStatus:
+              OperationStatus.SUCCESS if cache was successfully loaded
+              OperationStatus.SKIPPED if already exists
+              OperationStatus.ERROR if b10fs is unavailable, local disk space is insufficient, or loading failed.
+              OperationStatus.DOES_NOT_EXIST if no cache file was found.
 
     Raises:
-        CacheValidationError: If b10fs is not enabled (caught and returns LoadStatus.ERROR).
+        CacheValidationError: If b10fs is not enabled (caught and returns OperationStatus.ERROR).
         CacheOperationInterrupted: If operations interrupted due to insufficient
-                                  local disk space (caught and returns LoadStatus.ERROR).
-        Exception: Any other errors during loading (caught and returns LoadStatus.ERROR).
+                                  local disk space (caught and returns OperationStatus.ERROR).
+        Exception: Any other errors during loading (caught and returns OperationStatus.ERROR).
     """
     with cache_operation("Load"):
-        # Cooperative cleanup of stale shared resources
-        cooperative_cleanup_b10fs()
-
-        b10fs_dir = Path(B10FS_CACHE_DIR)
-        torch_dir = Path(TORCH_CACHE_DIR)
-        work_dir = Path(LOCAL_WORK_DIR)
+        b10fs_dir, torch_dir, work_dir = _setup_cache_paths()
 
         cache_filename = get_cache_filename()
-        cache_file = (
-            b10fs_dir / f"{cache_filename}{CACHE_LATEST_SUFFIX}{CACHE_FILE_EXTENSION}"
-        )
-        logger.debug(f"Looking for cache file: {cache_file}")
+        final_file, _ = _get_cache_file_paths(cache_filename, b10fs_dir)
+        logger.debug(f"Looking for cache file: {final_file}")
 
-        if not cache_file.exists():
+        if not final_file.exists():
             logger.info("No cache file found in b10fs")
-            return LoadStatus.DOES_NOT_EXIST
+            return OperationStatus.DOES_NOT_EXIST
 
         # Skip if already loaded
         if torch_dir.exists() and any(torch_dir.iterdir()):
             logger.info("Torch cache already loaded, skipping extraction")
-            return LoadStatus.SKIPPED
+            return OperationStatus.SKIPPED
 
         # Create temp local copy
         with tempfile.NamedTemporaryFile(
@@ -99,58 +176,35 @@ def load_compile_cache() -> LoadStatus:
 
         try:
             with temp_file_cleanup(temp_path):
-                # Phase 1: Copy from b10fs to local temp file using transfer()
-                @critical_section_b10fs_file_lock("copy_out")
-                def _monitored_copy_from_b10fs():
-                    result = transfer(str(cache_file), str(temp_path))
-                    if result != TransferStatus.SUCCESS:
-                        raise Exception("Failed to copy cache file from b10fs")
-
-                _monitored_copy_from_b10fs()
-
-                # Phase 2: Extract archive in separate process with space monitoring
-                space_monitor = CacheSpaceMonitor(MIN_LOCAL_SPACE_MB, work_dir)
-                space_monitor.start()
-
-                try:
-                    logger.info(f"Starting extraction: {temp_path} -> {torch_dir}")
-                    run_monitored_process(
-                        _cache_extract_worker,
-                        (str(temp_path), str(torch_dir)),
-                        space_monitor,
-                        "archive extraction",
-                        cleanup_func=lambda: _cleanup_torch_dir(torch_dir),
-                    )
-                finally:
-                    space_monitor.stop()
+                # Phase 1: Copy from b10fs to local temp file
+                _transfer_with_b10fs_lock(
+                    str(final_file),
+                    str(temp_path),
+                    "copy_out",
+                    cleanup_on_failure=False,
+                )
+
+                # Phase 2: Extract archive with space monitoring
+                _run_with_space_monitoring(
+                    MIN_LOCAL_SPACE_MB,
+                    work_dir,
+                    "archive extraction",
+                    _cache_extract_worker,
+                    (str(temp_path), str(torch_dir)),
+                    cleanup_func=lambda: _cleanup_torch_dir(torch_dir),
+                )
 
             logger.info("Cache load complete")
-            return LoadStatus.SUCCESS
+            return OperationStatus.SUCCESS
 
         except CacheOperationInterrupted as e:
             logger.warning(f"Cache load interrupted: {e}")
-            return LoadStatus.ERROR
-
-
-"""
-FIXME(SRAY):
-What about the case in @b10-transfer/ where a single pod finishes an inference request,
-and then the client calls save_compile_cache. And while we are creating the local archive,
-another inference call on the same pod is kicked off, which then modifies the torch cache.
-How would this be handled? Maybe just accept that the cache will be recompiled/overwritten?
-Otherwise you'd need application level coordination to ensure that the cache is not modified
-while we are creating the archive, but this doesn't really seem like a good idea in terms of adoption.
-
-FIXME(SR):
-More things to consider:
-- [possible] What if b10fs dies *during* an op? right now we check for b10fs availability in the beginning of the op... Add some constants instead of just False for load().
-- [possible, and really bad if it happens] potential memory exhaustion during compression if the cache is super super large. very very edge case. higher compression levels also have high memory usage.
-"""
+            return OperationStatus.ERROR
 
 
 @timed_fn(logger=logger, name="Saving compile cache")
 @safe_execute("Save failed", False)
-def save_compile_cache() -> SaveStatus:
+def save_compile_cache() -> OperationStatus:
     """Save local PyTorch compilation cache to b10fs using atomic journal pattern.
 
     This function creates an archive of the local torch cache directory and
@@ -164,46 +218,34 @@ def save_compile_cache() -> SaveStatus:
     space becomes insufficient, finally performing an atomic rename to the final cache file.
 
     Returns:
-        SaveStatus:
-              SaveStatus.SUCCESS if cache was successfully saved or already exists
-              SaveStatus.ERROR if b10fs is unavailable, insufficient disk space caused interruption,
+        OperationStatus:
+              OperationStatus.SUCCESS if cache was successfully saved or already exists
+              OperationStatus.ERROR if b10fs is unavailable, insufficient disk space caused interruption,
                 no cache exists to save, or saving failed.
-              SaveStatus.SKIPPED if no cache exists to save or cache already exists in b10fs
+              OperationStatus.SKIPPED if no cache exists to save or cache already exists in b10fs
 
     Raises:
-        CacheValidationError: If b10fs is not enabled (caught and returns SaveStatus.ERROR).
+        CacheValidationError: If b10fs is not enabled (caught and returns OperationStatus.ERROR).
         CacheOperationInterrupted: If operations interrupted due to insufficient
-                                  disk space (caught and returns SaveStatus.ERROR).
-        ArchiveError: If archive creation fails (caught and returns SaveStatus.ERROR).
-        Exception: Any other errors during saving (caught and returns SaveStatus.ERROR).
+                                  disk space (caught and returns OperationStatus.ERROR).
+        ArchiveError: If archive creation fails (caught and returns OperationStatus.ERROR).
+        Exception: Any other errors during saving (caught and returns OperationStatus.ERROR).
     """
     with cache_operation("Save"):
-        # Cooperative cleanup of stale shared resources
-        cooperative_cleanup_b10fs()
-
-        b10fs_dir = Path(B10FS_CACHE_DIR)
-        torch_dir = Path(TORCH_CACHE_DIR)
-        work_dir = Path(LOCAL_WORK_DIR)
+        b10fs_dir, torch_dir, work_dir = _setup_cache_paths()
 
         # Check if anything to save
         if not torch_dir.exists() or not any(torch_dir.iterdir()):
             logger.info("No torch cache to save")
-            return SaveStatus.SKIPPED
+            return OperationStatus.SKIPPED
 
         cache_filename = get_cache_filename()
-        final_file = (
-            b10fs_dir / f"{cache_filename}{CACHE_LATEST_SUFFIX}{CACHE_FILE_EXTENSION}"
-        )
+        final_file, temp_file = _get_cache_file_paths(cache_filename, b10fs_dir)
 
         # Check for existing cache first (early exit)
         if final_file.exists():
             logger.info("Cache already exists in b10fs, skipping save")
-            return SaveStatus.SKIPPED
-
-        temp_file = (
-            b10fs_dir
-            / f"{cache_filename}{CACHE_INCOMPLETE_SUFFIX}{CACHE_FILE_EXTENSION}"
-        )
+            return OperationStatus.SKIPPED
 
         with tempfile.NamedTemporaryFile(
             suffix=CACHE_FILE_EXTENSION, dir=work_dir, delete=False
@@ -213,34 +255,19 @@ def save_compile_cache() -> SaveStatus:
 
         try:
             with temp_file_cleanup(local_temp):
-                # Phase 1: Compression in separate process with space monitoring
-                space_monitor = CacheSpaceMonitor(REQUIRED_B10FS_SPACE_MB, b10fs_dir)
-                space_monitor.start()
-
-                try:
-                    logger.info(f"Starting compression: {torch_dir} -> {local_temp}")
-                    run_monitored_process(
-                        _cache_compression_worker,
-                        (str(torch_dir), str(local_temp), MAX_CACHE_SIZE_MB),
-                        space_monitor,
-                        "compression",
-                    )
-                finally:
-                    space_monitor.stop()
-
-                # Phase 2: Copy to b10fs using transfer()
-                @critical_section_b10fs_file_lock("copy_in")
-                def _monitored_copy_to_b10fs():
-                    result = transfer(str(local_temp), str(temp_file))
-                    if result != TransferStatus.SUCCESS:
-                        # Clean up the temp file if transfer failed
-                        safe_unlink(
-                            temp_file,
-                            f"Failed to cleanup after failed copy {temp_file}",
-                        )
-                        raise Exception("Failed to copy cache file to b10fs")
-
-                _monitored_copy_to_b10fs()
+                # Phase 1: Compression with space monitoring
+                _run_with_space_monitoring(
+                    REQUIRED_B10FS_SPACE_MB,
+                    b10fs_dir,
+                    "compression",
+                    _cache_compression_worker,
+                    (str(torch_dir), str(local_temp), MAX_CACHE_SIZE_MB),
+                )
+
+                # Phase 2: Copy to b10fs with locking
+                _transfer_with_b10fs_lock(
+                    str(local_temp), str(temp_file), "copy_in", cleanup_on_failure=True
+                )
 
                 # Phase 3: Atomic rename (fast, don't interrupt)
                 logger.info(
@@ -249,95 +276,11 @@ def save_compile_cache() -> SaveStatus:
                 temp_file.rename(final_file)
 
             logger.info("Cache save complete")
-            return SaveStatus.SUCCESS
+            return OperationStatus.SUCCESS
 
         except CacheOperationInterrupted as e:
             logger.warning(f"Cache save interrupted: {e}")
-            return SaveStatus.ERROR
-
-
-@timed_fn(logger=logger, name="Transferring file")
-@safe_execute("Transfer failed", TransferStatus.ERROR)
-def transfer(source: str, dest: str) -> TransferStatus:
-    """Transfer a file from source to destination with space monitoring.
-
-    This function copies a file from source to destination using the same
-    monitored process approach as the cache operations. It monitors disk space
-    at the destination and can interrupt the transfer if space becomes insufficient.
-
-    Args:
-        source: Path to the source file to copy.
-        dest: Path to the destination where the file will be copied.
-
-    Returns:
-        TransferStatus:
-              TransferStatus.SUCCESS if transfer was successful
-              TransferStatus.ERROR if transfer failed due to insufficient disk space,
-                file not found, or other errors.
-
-    Raises:
-        CacheOperationInterrupted: If transfer interrupted due to insufficient
-                                  disk space (caught and returns TransferStatus.ERROR).
-        Exception: Any other errors during transfer (caught and returns TransferStatus.ERROR).
-    """
-    source_path = Path(source)
-    dest_path = Path(dest)
-
-    # Validate source file exists
-    if not source_path.exists():
-        logger.error(f"Source file does not exist: {source}")
-        return TransferStatus.ERROR
-
-    # Create destination directory if it doesn't exist
-    dest_path.parent.mkdir(parents=True, exist_ok=True)
-
-    # Determine appropriate space threshold based on destination directory
-    dest_dir = dest_path.parent
-    if str(dest_dir).startswith(B10FS_CACHE_DIR):
-        # Transferring to b10fs - use b10fs space requirements
-        space_threshold_mb = REQUIRED_B10FS_SPACE_MB
-        logger.debug(
-            f"Transfer to b10fs detected, using {space_threshold_mb:.1f}MB threshold"
-        )
-    else:
-        # Transferring to local directory - use local space requirements
-        space_threshold_mb = MIN_LOCAL_SPACE_MB
-        logger.debug(
-            f"Transfer to local directory detected, using {space_threshold_mb:.1f}MB threshold"
-        )
-
-    # Initial disk space check
-    check_sufficient_disk_space(dest_dir, space_threshold_mb, "file transfer")
-    logger.debug(
-        f"Initial space check passed: {space_threshold_mb:.1f}MB required at destination"
-    )
-
-    # Start background space monitoring for destination directory
-    space_monitor = CacheSpaceMonitor(space_threshold_mb, dest_dir)
-    space_monitor.start()
-
-    try:
-        # Run monitored copy process
-        logger.info(f"Starting transfer: {source} -> {dest}")
-        run_monitored_process(
-            _cache_copy_worker,
-            (str(source_path), str(dest_path)),
-            space_monitor,
-            "file transfer",
-            cleanup_func=lambda: safe_unlink(
-                dest_path, f"Failed to cleanup interrupted transfer {dest_path}"
-            ),
-        )
-
-        logger.info("File transfer complete")
-        return TransferStatus.SUCCESS
-
-    except CacheOperationInterrupted as e:
-        logger.warning(f"File transfer interrupted: {e}")
-        return TransferStatus.ERROR
-
-    finally:
-        space_monitor.stop()
+            return OperationStatus.ERROR
 
 
 @safe_execute("Clear failed", False)
@@ -357,6 +300,8 @@ def clear_local_cache() -> bool:
     torch_dir = Path(TORCH_CACHE_DIR)
     if not torch_dir.exists():
         return True
+    import shutil
+
     shutil.rmtree(torch_dir)
     return True
 
@@ -384,27 +329,12 @@ def _cache_compression_worker(
     create_archive(torch_dir, local_temp, max_size_mb)
 
 
-@worker_process("Copy was cancelled before starting")
-def _cache_copy_worker(source_path_str: str, dest_path_str: str) -> None:
-    """Worker process that handles file copy to b10fs.
-
-    This function runs in a separate process to copy the compressed cache file
-    to the b10fs filesystem. It can be terminated externally if disk space becomes insufficient.
-
-    Args:
-        source_path_str: String path to the source file to copy.
-        dest_path_str: String path where the file will be copied.
-    """
-    source_path = Path(source_path_str)
-    dest_path = Path(dest_path_str)
-
-    shutil.copy2(source_path, dest_path)
-
-
 def _cleanup_torch_dir(torch_dir: Path) -> None:
     """Helper function to safely cleanup torch directory during interrupted extraction."""
     try:
         if torch_dir.exists():
+            import shutil
+
             shutil.rmtree(torch_dir)
             logger.debug(f"Cleaned up torch directory: {torch_dir}")
     except Exception as e:

{b10_transfer-0.1.4 → b10_transfer-0.1.6}/src/b10_transfer/constants.py

@@ -114,25 +114,10 @@ class WorkerStatus(Enum):
     CANCELLED = auto()
 
 
-class LoadStatus(Enum):
-    """Status values for cache loading operations."""
-
-    SUCCESS = auto()
-    ERROR = auto()
-    DOES_NOT_EXIST = auto()
-    SKIPPED = auto()
-
-
-class SaveStatus(Enum):
-    """Status values for cache saving operations."""
-
-    SUCCESS = auto()
-    ERROR = auto()
-    SKIPPED = auto()
-
-
-class TransferStatus(Enum):
-    """Status values for file transfer operations."""
+class OperationStatus(Enum):
+    """Status values for all b10-transfer operations (load, save, transfer)."""
 
     SUCCESS = auto()
     ERROR = auto()
+    DOES_NOT_EXIST = auto()  # Used by load operations when cache file not found
+    SKIPPED = auto()  # Used by load/save operations when operation not needed

b10_transfer-0.1.6/src/b10_transfer/core.py

@@ -0,0 +1,131 @@
+"""Core file transfer operations for b10-transfer.
+
+This module provides generic file transfer functionality with space monitoring
+and error handling for b10fs operations.
+"""
+
+import logging
+import shutil
+from pathlib import Path
+
+from .utils import (
+    timed_fn,
+    safe_execute,
+    safe_unlink,
+)
+from .space_monitor import (
+    check_sufficient_disk_space,
+    CacheSpaceMonitor,
+    CacheOperationInterrupted,
+    run_monitored_process,
+    worker_process,
+)
+from .constants import (
+    B10FS_CACHE_DIR,
+    REQUIRED_B10FS_SPACE_MB,
+    MIN_LOCAL_SPACE_MB,
+    OperationStatus,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@timed_fn(logger=logger, name="Transferring file")
+@safe_execute("Transfer failed", OperationStatus.ERROR)
+def transfer(source: str, dest: str) -> OperationStatus:
+    """Transfer a file from source to destination with space monitoring.
+
+    This function copies a file from source to destination using the same
+    monitored process approach as the cache operations. It monitors disk space
+    at the destination and can interrupt the transfer if space becomes insufficient.
+
+    Args:
+        source: Path to the source file to copy.
+        dest: Path to the destination where the file will be copied.
+
+    Returns:
+        OperationStatus:
+              OperationStatus.SUCCESS if transfer was successful
+              OperationStatus.ERROR if transfer failed due to insufficient disk space,
+                file not found, or other errors.
+
+    Raises:
+        CacheOperationInterrupted: If transfer interrupted due to insufficient
+                                  disk space (caught and returns OperationStatus.ERROR).
+        Exception: Any other errors during transfer (caught and returns OperationStatus.ERROR).
+    """
+    source_path = Path(source)
+    dest_path = Path(dest)
+
+    # Validate source file exists
+    if not source_path.exists():
+        logger.error(f"Source file does not exist: {source}")
+        return OperationStatus.ERROR
+
+    # Create destination directory if it doesn't exist
+    dest_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Determine appropriate space threshold based on destination directory
+    dest_dir = dest_path.parent
+    if str(dest_dir).startswith(B10FS_CACHE_DIR):
+        # Transferring to b10fs - use b10fs space requirements
+        space_threshold_mb = REQUIRED_B10FS_SPACE_MB
+        logger.debug(
+            f"Transfer to b10fs detected, using {space_threshold_mb:.1f}MB threshold"
+        )
+    else:
+        # Transferring to local directory - use local space requirements
+        space_threshold_mb = MIN_LOCAL_SPACE_MB
+        logger.debug(
+            f"Transfer to local directory detected, using {space_threshold_mb:.1f}MB threshold"
+        )
+
+    # Initial disk space check
+    check_sufficient_disk_space(dest_dir, space_threshold_mb, "file transfer")
+    logger.debug(
+        f"Initial space check passed: {space_threshold_mb:.1f}MB required at destination"
+    )
+
+    # Start background space monitoring for destination directory
+    space_monitor = CacheSpaceMonitor(space_threshold_mb, dest_dir)
+    space_monitor.start()
+
+    try:
+        # Run monitored copy process
+        logger.info(f"Starting transfer: {source} -> {dest}")
+        run_monitored_process(
+            _cache_copy_worker,
+            (str(source_path), str(dest_path)),
+            space_monitor,
+            "file transfer",
+            cleanup_func=lambda: safe_unlink(
+                dest_path, f"Failed to cleanup interrupted transfer {dest_path}"
+            ),
+        )
+
+        logger.info("File transfer complete")
+        return OperationStatus.SUCCESS
+
+    except CacheOperationInterrupted as e:
+        logger.warning(f"File transfer interrupted: {e}")
+        return OperationStatus.ERROR
+
+    finally:
+        space_monitor.stop()
+
+
+@worker_process("Copy was cancelled before starting")
+def _cache_copy_worker(source_path_str: str, dest_path_str: str) -> None:
+    """Worker process that handles file copy operations.
+
+    This function runs in a separate process to copy files between locations.
+    It can be terminated externally if disk space becomes insufficient.
+
+    Args:
+        source_path_str: String path to the source file to copy.
+        dest_path_str: String path where the file will be copied.
+    """
+    source_path = Path(source_path_str)
+    dest_path = Path(dest_path_str)
+
+    shutil.copy2(source_path, dest_path)