elaunira-r2index 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

elaunira/r2index/__init__.py

@@ -1,43 +1,11 @@
-"""
-R2 Index Python Library.
+"""Python library for uploading and downloading files to/from Cloudflare R2 with the r2index API."""
 
-A Python library for uploading files to Cloudflare R2 and registering them
-with the r2index API. Supports both sync and async operations with streaming
-checksums for memory-efficient handling of large files.
+from importlib.metadata import version
 
-Usage:
-    from elaunira.r2index import R2IndexClient, R2Config
-
-    client = R2IndexClient(
-        api_url="https://r2index.example.com",
-        api_token="your-bearer-token",
-        r2_config=R2Config(
-            access_key_id="...",
-            secret_access_key="...",
-            endpoint_url="https://xxx.r2.cloudflarestorage.com",
-            bucket="your-bucket",
-        ),
-    )
-
-    # Upload and register a file
-    record = client.upload_and_register(
-        file_path="./myfile.zip",
-        category="software",
-        entity="myapp",
-        remote_path="/releases",
-        remote_filename="myapp-1.0.0.zip",
-        remote_version="1.0.0",
-    )
-
-Async usage:
-    from elaunira.r2index import AsyncR2IndexClient, R2Config
-
-    async with AsyncR2IndexClient(...) as client:
-        record = await client.upload_and_register(...)
-"""
+__version__ = version("elaunira-r2index")
 
 from .async_client import AsyncR2IndexClient
-from .async_uploader import AsyncR2Uploader
+from .async_storage import AsyncR2Storage
 from .checksums import (
     ChecksumResult,
     compute_checksums,
@@ -48,6 +16,7 @@ from .client import R2IndexClient
 from .exceptions import (
     AuthenticationError,
     ConflictError,
+    DownloadError,
     NotFoundError,
     R2IndexError,
     UploadError,
@@ -72,44 +41,48 @@ from .models import (
     UserAgentEntry,
     UserAgentsResponse,
 )
-from .uploader import R2Config, R2Uploader
+from .storage import R2Config, R2Storage, R2TransferConfig
 
 __all__ = [
+    # Version
+    "__version__",
     # Clients
-    "R2IndexClient",
     "AsyncR2IndexClient",
-    # Uploaders
-    "R2Uploader",
-    "AsyncR2Uploader",
+    "R2IndexClient",
+    # Storage
+    "AsyncR2Storage",
     "R2Config",
+    "R2Storage",
+    "R2TransferConfig",
     # Checksums
     "ChecksumResult",
     "compute_checksums",
     "compute_checksums_async",
     "compute_checksums_from_file_object",
     # Exceptions
-    "R2IndexError",
     "AuthenticationError",
-    "NotFoundError",
-    "ValidationError",
     "ConflictError",
+    "DownloadError",
+    "NotFoundError",
+    "R2IndexError",
     "UploadError",
+    "ValidationError",
     # Models - File operations
-    "FileRecord",
     "FileCreateRequest",
-    "FileUpdateRequest",
     "FileListResponse",
+    "FileRecord",
+    "FileUpdateRequest",
     "IndexEntry",
     "RemoteTuple",
     # Models - Downloads
     "DownloadRecord",
     "DownloadRecordRequest",
     # Models - Analytics
-    "TimeseriesDataPoint",
-    "TimeseriesResponse",
-    "SummaryResponse",
     "DownloadByIpEntry",
     "DownloadsByIpResponse",
+    "SummaryResponse",
+    "TimeseriesDataPoint",
+    "TimeseriesResponse",
     "UserAgentEntry",
     "UserAgentsResponse",
     # Models - Other

elaunira/r2index/async_client.py

@@ -7,7 +7,7 @@ from typing import Any
 
 import httpx
 
-from .async_uploader import AsyncR2Uploader
+from .async_storage import AsyncR2Storage
 from .checksums import compute_checksums_async
 from .exceptions import (
     AuthenticationError,
@@ -32,7 +32,48 @@ from .models import (
     TimeseriesResponse,
     UserAgentsResponse,
 )
-from .uploader import R2Config
+from . import __version__
+from .storage import R2Config, R2TransferConfig
+
+CHECKIP_URL = "https://checkip.amazonaws.com"
+DEFAULT_USER_AGENT = f"elaunira-r2index/{__version__}"
+
+
+def _parse_object_id(object_id: str, bucket: str) -> RemoteTuple:
+    """
+    Parse an object_id into remote_path, remote_version, and remote_filename.
+
+    Format: /path/to/object/version/filename.ext
+    - remote_filename: last component (filename.ext)
+    - remote_version: second-to-last component (version)
+    - remote_path: everything before that (/path/to/object)
+
+    Args:
+        object_id: Full object path like /releases/myapp/v1/myapp.zip
+        bucket: The S3/R2 bucket name.
+
+    Returns:
+        RemoteTuple with parsed components including bucket.
+
+    Raises:
+        ValueError: If object_id doesn't have enough components.
+    """
+    parts = object_id.strip("/").split("/")
+    if len(parts) < 3:
+        raise ValueError(
+            f"object_id must have at least 3 components (path/version/filename), got: {object_id}"
+        )
+
+    remote_filename = parts[-1]
+    remote_version = parts[-2]
+    remote_path = "/" + "/".join(parts[:-2])
+
+    return RemoteTuple(
+        bucket=bucket,
+        remote_path=remote_path,
+        remote_filename=remote_filename,
+        remote_version=remote_version,
+    )
 
 
 class AsyncR2IndexClient:
@@ -58,7 +99,7 @@ class AsyncR2IndexClient:
         self._token = api_token
         self._timeout = timeout
         self._r2_config = r2_config
-        self._uploader: AsyncR2Uploader | None = None
+        self._storage: AsyncR2Storage | None = None
 
         self._client = httpx.AsyncClient(
             base_url=self.api_url,
@@ -76,13 +117,13 @@ class AsyncR2IndexClient:
         """Close the HTTP client."""
         await self._client.aclose()
 
-    def _get_uploader(self) -> AsyncR2Uploader:
+    def _get_storage(self) -> AsyncR2Storage:
         """Get or create the async R2 uploader."""
         if self._r2_config is None:
             raise R2IndexError("R2 configuration required for upload operations")
-        if self._uploader is None:
-            self._uploader = AsyncR2Uploader(self._r2_config)
-        return self._uploader
+        if self._storage is None:
+            self._storage = AsyncR2Storage(self._r2_config)
+        return self._storage
 
     def _handle_response(self, response: httpx.Response) -> Any:
         """Handle API response and raise appropriate exceptions."""
@@ -111,6 +152,7 @@ class AsyncR2IndexClient:
 
     async def list_files(
         self,
+        bucket: str | None = None,
         category: str | None = None,
         entity: str | None = None,
         tags: list[str] | None = None,
@@ -121,6 +163,7 @@ class AsyncR2IndexClient:
         List files with optional filters.
 
         Args:
+            bucket: Filter by bucket.
             category: Filter by category.
             entity: Filter by entity.
             tags: Filter by tags.
@@ -131,6 +174,8 @@ class AsyncR2IndexClient:
             FileListResponse with files and pagination info.
         """
         params: dict[str, Any] = {}
+        if bucket:
+            params["bucket"] = bucket
         if category:
             params["category"] = category
         if entity:
@@ -213,12 +258,13 @@ class AsyncR2IndexClient:
         Delete a file by remote tuple.
 
         Args:
-            remote_tuple: The remote path, filename, and version.
+            remote_tuple: The bucket, remote path, filename, and version.
 
         Raises:
             NotFoundError: If the file is not found.
         """
         params = {
+            "bucket": remote_tuple.bucket,
             "remotePath": remote_tuple.remote_path,
             "remoteFilename": remote_tuple.remote_filename,
             "remoteVersion": remote_tuple.remote_version,
@@ -226,8 +272,32 @@ class AsyncR2IndexClient:
         response = await self._client.delete("/files", params=params)
         self._handle_response(response)
 
+    async def get_file_by_tuple(self, remote_tuple: RemoteTuple) -> FileRecord:
+        """
+        Get a file by remote tuple.
+
+        Args:
+            remote_tuple: The bucket, remote path, filename, and version.
+
+        Returns:
+            The FileRecord.
+
+        Raises:
+            NotFoundError: If the file is not found.
+        """
+        params = {
+            "bucket": remote_tuple.bucket,
+            "remotePath": remote_tuple.remote_path,
+            "remoteFilename": remote_tuple.remote_filename,
+            "remoteVersion": remote_tuple.remote_version,
+        }
+        response = await self._client.get("/files/by-tuple", params=params)
+        data = self._handle_response(response)
+        return FileRecord.model_validate(data)
+
     async def get_index(
         self,
+        bucket: str | None = None,
         category: str | None = None,
         entity: str | None = None,
         tags: list[str] | None = None,
@@ -236,6 +306,7 @@ class AsyncR2IndexClient:
         Get file index (lightweight listing).
 
         Args:
+            bucket: Filter by bucket.
             category: Filter by category.
             entity: Filter by entity.
             tags: Filter by tags.
@@ -244,6 +315,8 @@ class AsyncR2IndexClient:
             List of IndexEntry objects.
         """
         params: dict[str, Any] = {}
+        if bucket:
+            params["bucket"] = bucket
         if category:
             params["category"] = category
         if entity:
@@ -426,7 +499,8 @@ class AsyncR2IndexClient:
 
     async def upload_and_register(
         self,
-        file_path: str | Path,
+        local_path: str | Path,
+        bucket: str,
         category: str,
         entity: str,
         remote_path: str,
@@ -447,7 +521,8 @@ class AsyncR2IndexClient:
         3. Register with r2index API
 
         Args:
-            file_path: Path to the file to upload.
+            local_path: Local path to the file to upload.
+            bucket: The S3/R2 bucket name.
             category: File category.
             entity: File entity.
             remote_path: Remote path in R2 (e.g., "/data/files").
@@ -466,18 +541,18 @@ class AsyncR2IndexClient:
             R2IndexError: If R2 config is not provided.
             UploadError: If upload fails.
         """
-        file_path = Path(file_path)
-        uploader = self._get_uploader()
+        local_path = Path(local_path)
+        uploader = self._get_storage()
 
         # Step 1: Compute checksums
-        checksums = await compute_checksums_async(file_path)
+        checksums = await compute_checksums_async(local_path)
 
         # Step 2: Build R2 object key
         object_key = f"{remote_path.strip('/')}/{remote_filename}"
 
         # Step 3: Upload to R2
         await uploader.upload_file(
-            file_path,
+            local_path,
             object_key,
             content_type=content_type,
             progress_callback=progress_callback,
@@ -485,6 +560,7 @@ class AsyncR2IndexClient:
 
         # Step 4: Register with API
         create_request = FileCreateRequest(
+            bucket=bucket,
             category=category,
             entity=entity,
             remote_path=remote_path,
@@ -501,3 +577,84 @@ class AsyncR2IndexClient:
         )
 
         return await self.create_file(create_request)
+
+    async def _get_public_ip(self) -> str:
+        """Fetch public IP address from checkip.amazonaws.com."""
+        async with httpx.AsyncClient() as client:
+            response = await client.get(CHECKIP_URL, timeout=10.0)
+            return response.text.strip()
+
+    async def download_and_record(
+        self,
+        bucket: str,
+        object_id: str,
+        destination: str | Path,
+        ip_address: str | None = None,
+        user_agent: str | None = None,
+        progress_callback: Callable[[int], None] | None = None,
+        transfer_config: R2TransferConfig | None = None,
+    ) -> tuple[Path, FileRecord]:
+        """
+        Download a file from R2 and record the download in the index asynchronously.
+
+        This is a convenience method that performs:
+        1. Parse object_id into remote_path, remote_version, remote_filename
+        2. Fetch file record from the API using these components
+        3. Download the file from R2
+        4. Record the download in the index for analytics
+
+        Args:
+            bucket: The S3/R2 bucket name.
+            object_id: Full S3 object path in format: /path/to/object/version/filename
+                Example: /releases/myapp/v1/myapp.zip
+                - remote_path: /releases/myapp
+                - remote_version: v1
+                - remote_filename: myapp.zip
+            destination: Local path where the file will be saved.
+            ip_address: IP address of the downloader. If not provided, fetched
+                from checkip.amazonaws.com.
+            user_agent: User agent string. Defaults to "elaunira-r2index/0.1.0".
+            progress_callback: Optional callback for download progress.
+            transfer_config: Optional transfer configuration for multipart/threading.
+
+        Returns:
+            A tuple of (downloaded file path, file record).
+
+        Raises:
+            R2IndexError: If R2 config is not provided.
+            ValueError: If object_id format is invalid.
+            NotFoundError: If the file is not found in the index.
+            DownloadError: If download fails.
+        """
+        storage = self._get_storage()
+
+        # Resolve defaults
+        if ip_address is None:
+            ip_address = await self._get_public_ip()
+        if user_agent is None:
+            user_agent = DEFAULT_USER_AGENT
+
+        # Step 1: Parse object_id into components
+        remote_tuple = _parse_object_id(object_id, bucket)
+
+        # Step 2: Get file record by tuple
+        file_record = await self.get_file_by_tuple(remote_tuple)
+
+        # Step 3: Build R2 object key and download
+        object_key = object_id.strip("/")
+        downloaded_path = await storage.download_file(
+            object_key,
+            destination,
+            progress_callback=progress_callback,
+            transfer_config=transfer_config,
+        )
+
+        # Step 4: Record the download
+        download_request = DownloadRecordRequest(
+            file_id=file_record.id,
+            ip_address=ip_address,
+            user_agent=user_agent,
+        )
+        await self.record_download(download_request)
+
+        return downloaded_path, file_record

elaunira/r2index/{async_uploader.py → async_storage.py}

@@ -1,4 +1,4 @@
-"""Asynchronous R2 uploader using aioboto3."""
+"""Asynchronous R2 storage operations using aioboto3."""
 
 from collections.abc import Callable
 from pathlib import Path
@@ -6,20 +6,16 @@ from pathlib import Path
 import aioboto3
 from aiobotocore.config import AioConfig
 
-from .exceptions import UploadError
-from .uploader import R2Config
+from .exceptions import DownloadError, UploadError
+from .storage import R2Config, R2TransferConfig
 
-# 100MB threshold and part size for multipart uploads
-MULTIPART_THRESHOLD = 100 * 1024 * 1024
-MULTIPART_PART_SIZE = 100 * 1024 * 1024
 
-
-class AsyncR2Uploader:
-    """Asynchronous R2 uploader using aioboto3."""
+class AsyncR2Storage:
+    """Asynchronous R2 storage client using aioboto3."""
 
     def __init__(self, config: R2Config) -> None:
         """
-        Initialize the async R2 uploader.
+        Initialize the async R2 storage client.
 
         Args:
             config: R2 configuration with credentials and endpoint.
@@ -33,17 +29,19 @@ class AsyncR2Uploader:
         object_key: str,
         content_type: str | None = None,
         progress_callback: Callable[[int], None] | None = None,
+        transfer_config: R2TransferConfig | None = None,
     ) -> str:
         """
         Upload a file to R2 asynchronously.
 
-        Uses multipart upload for files larger than 100MB.
+        Uses multipart upload for files larger than the configured threshold.
 
         Args:
             file_path: Path to the file to upload.
             object_key: The key (path) to store the object under in R2.
             content_type: Optional content type for the object.
             progress_callback: Optional callback called with bytes uploaded so far.
+            transfer_config: Optional transfer configuration for multipart/threading.
 
         Returns:
             The object key of the uploaded file.
@@ -56,8 +54,9 @@ class AsyncR2Uploader:
         if not file_path.exists():
             raise UploadError(f"File not found: {file_path}")
 
-        transfer_config = AioConfig(
-            max_pool_connections=10,
+        tc = transfer_config or R2TransferConfig()
+        aio_config = AioConfig(
+            max_pool_connections=tc.max_concurrency,
         )
 
         extra_args = {}
@@ -71,7 +70,7 @@ class AsyncR2Uploader:
                 aws_secret_access_key=self.config.secret_access_key,
                 endpoint_url=self.config.endpoint_url,
                 region_name=self.config.region,
-                config=transfer_config,
+                config=aio_config,
             ) as client:
                 callback = None
                 if progress_callback:
@@ -136,6 +135,62 @@ class AsyncR2Uploader:
                 return False
             raise UploadError(f"Failed to check object existence: {e}") from e
 
+    async def download_file(
+        self,
+        object_key: str,
+        file_path: str | Path,
+        progress_callback: Callable[[int], None] | None = None,
+        transfer_config: R2TransferConfig | None = None,
+    ) -> Path:
+        """
+        Download a file from R2 asynchronously.
+
+        Args:
+            object_key: The key (path) of the object in R2.
+            file_path: Local path where the file will be saved.
+            progress_callback: Optional callback called with bytes downloaded so far.
+            transfer_config: Optional transfer configuration for multipart/threading.
+
+        Returns:
+            The path to the downloaded file.
+
+        Raises:
+            DownloadError: If the download fails.
+        """
+        file_path = Path(file_path)
+
+        # Ensure parent directory exists
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        tc = transfer_config or R2TransferConfig()
+        aio_config = AioConfig(
+            max_pool_connections=tc.max_concurrency,
+        )
+
+        try:
+            async with self._session.client(
+                "s3",
+                aws_access_key_id=self.config.access_key_id,
+                aws_secret_access_key=self.config.secret_access_key,
+                endpoint_url=self.config.endpoint_url,
+                region_name=self.config.region,
+                config=aio_config,
+            ) as client:
+                callback = None
+                if progress_callback:
+                    callback = _AsyncProgressCallback(progress_callback)
+
+                await client.download_file(
+                    self.config.bucket,
+                    object_key,
+                    str(file_path),
+                    Callback=callback,
+                )
+        except Exception as e:
+            raise DownloadError(f"Failed to download file from R2: {e}") from e
+
+        return file_path
+
 
 class _AsyncProgressCallback:
     """Wrapper to track cumulative progress for aioboto3 callback."""

elaunira/r2index/client.py

@@ -31,7 +31,48 @@ from .models import (
     TimeseriesResponse,
     UserAgentsResponse,
 )
-from .uploader import R2Config, R2Uploader
+from . import __version__
+from .storage import R2Config, R2Storage, R2TransferConfig
+
+CHECKIP_URL = "https://checkip.amazonaws.com"
+DEFAULT_USER_AGENT = f"elaunira-r2index/{__version__}"
+
+
+def _parse_object_id(object_id: str, bucket: str) -> RemoteTuple:
+    """
+    Parse an object_id into remote_path, remote_version, and remote_filename.
+
+    Format: /path/to/object/version/filename.ext
+    - remote_filename: last component (filename.ext)
+    - remote_version: second-to-last component (version)
+    - remote_path: everything before that (/path/to/object)
+
+    Args:
+        object_id: Full object path like /releases/myapp/v1/myapp.zip
+        bucket: The S3/R2 bucket name.
+
+    Returns:
+        RemoteTuple with parsed components including bucket.
+
+    Raises:
+        ValueError: If object_id doesn't have enough components.
+    """
+    parts = object_id.strip("/").split("/")
+    if len(parts) < 3:
+        raise ValueError(
+            f"object_id must have at least 3 components (path/version/filename), got: {object_id}"
+        )
+
+    remote_filename = parts[-1]
+    remote_version = parts[-2]
+    remote_path = "/" + "/".join(parts[:-2])
+
+    return RemoteTuple(
+        bucket=bucket,
+        remote_path=remote_path,
+        remote_filename=remote_filename,
+        remote_version=remote_version,
+    )
 
 
 class R2IndexClient:
@@ -57,7 +98,7 @@ class R2IndexClient:
         self._token = api_token
         self._timeout = timeout
         self._r2_config = r2_config
-        self._uploader: R2Uploader | None = None
+        self._storage: R2Storage | None = None
 
         self._client = httpx.Client(
             base_url=self.api_url,
@@ -75,13 +116,13 @@ class R2IndexClient:
         """Close the HTTP client."""
         self._client.close()
 
-    def _get_uploader(self) -> R2Uploader:
+    def _get_storage(self) -> R2Storage:
         """Get or create the R2 uploader."""
         if self._r2_config is None:
             raise R2IndexError("R2 configuration required for upload operations")
-        if self._uploader is None:
-            self._uploader = R2Uploader(self._r2_config)
-        return self._uploader
+        if self._storage is None:
+            self._storage = R2Storage(self._r2_config)
+        return self._storage
 
     def _handle_response(self, response: httpx.Response) -> Any:
         """Handle API response and raise appropriate exceptions."""
@@ -110,6 +151,7 @@ class R2IndexClient:
 
     def list_files(
         self,
+        bucket: str | None = None,
         category: str | None = None,
         entity: str | None = None,
         tags: list[str] | None = None,
@@ -120,6 +162,7 @@ class R2IndexClient:
         List files with optional filters.
 
         Args:
+            bucket: Filter by bucket.
             category: Filter by category.
             entity: Filter by entity.
             tags: Filter by tags.
@@ -130,6 +173,8 @@ class R2IndexClient:
             FileListResponse with files and pagination info.
         """
         params: dict[str, Any] = {}
+        if bucket:
+            params["bucket"] = bucket
         if category:
             params["category"] = category
         if entity:
@@ -212,12 +257,13 @@ class R2IndexClient:
         Delete a file by remote tuple.
 
         Args:
-            remote_tuple: The remote path, filename, and version.
+            remote_tuple: The bucket, remote path, filename, and version.
 
         Raises:
             NotFoundError: If the file is not found.
         """
         params = {
+            "bucket": remote_tuple.bucket,
             "remotePath": remote_tuple.remote_path,
             "remoteFilename": remote_tuple.remote_filename,
             "remoteVersion": remote_tuple.remote_version,
@@ -225,8 +271,32 @@ class R2IndexClient:
         response = self._client.delete("/files", params=params)
         self._handle_response(response)
 
+    def get_file_by_tuple(self, remote_tuple: RemoteTuple) -> FileRecord:
+        """
+        Get a file by remote tuple.
+
+        Args:
+            remote_tuple: The bucket, remote path, filename, and version.
+
+        Returns:
+            The FileRecord.
+
+        Raises:
+            NotFoundError: If the file is not found.
+        """
+        params = {
+            "bucket": remote_tuple.bucket,
+            "remotePath": remote_tuple.remote_path,
+            "remoteFilename": remote_tuple.remote_filename,
+            "remoteVersion": remote_tuple.remote_version,
+        }
+        response = self._client.get("/files/by-tuple", params=params)
+        data = self._handle_response(response)
+        return FileRecord.model_validate(data)
+
     def get_index(
         self,
+        bucket: str | None = None,
         category: str | None = None,
         entity: str | None = None,
         tags: list[str] | None = None,
@@ -235,6 +305,7 @@ class R2IndexClient:
         Get file index (lightweight listing).
 
         Args:
+            bucket: Filter by bucket.
             category: Filter by category.
             entity: Filter by entity.
             tags: Filter by tags.
@@ -243,6 +314,8 @@ class R2IndexClient:
             List of IndexEntry objects.
         """
         params: dict[str, Any] = {}
+        if bucket:
+            params["bucket"] = bucket
         if category:
             params["category"] = category
         if entity:
@@ -425,7 +498,8 @@ class R2IndexClient:
 
     def upload_and_register(
         self,
-        file_path: str | Path,
+        local_path: str | Path,
+        bucket: str,
         category: str,
         entity: str,
         remote_path: str,
@@ -446,7 +520,8 @@ class R2IndexClient:
         3. Register with r2index API
 
         Args:
-            file_path: Path to the file to upload.
+            local_path: Local path to the file to upload.
+            bucket: The S3/R2 bucket name.
             category: File category.
             entity: File entity.
             remote_path: Remote path in R2 (e.g., "/data/files").
@@ -465,18 +540,18 @@ class R2IndexClient:
             R2IndexError: If R2 config is not provided.
             UploadError: If upload fails.
         """
-        file_path = Path(file_path)
-        uploader = self._get_uploader()
+        local_path = Path(local_path)
+        uploader = self._get_storage()
 
         # Step 1: Compute checksums
-        checksums = compute_checksums(file_path)
+        checksums = compute_checksums(local_path)
 
         # Step 2: Build R2 object key
         object_key = f"{remote_path.strip('/')}/{remote_filename}"
 
         # Step 3: Upload to R2
         uploader.upload_file(
-            file_path,
+            local_path,
             object_key,
             content_type=content_type,
             progress_callback=progress_callback,
@@ -484,6 +559,7 @@ class R2IndexClient:
 
         # Step 4: Register with API
         create_request = FileCreateRequest(
+            bucket=bucket,
             category=category,
             entity=entity,
             remote_path=remote_path,
@@ -500,3 +576,83 @@ class R2IndexClient:
         )
 
         return self.create_file(create_request)
+
+    def _get_public_ip(self) -> str:
+        """Fetch public IP address from checkip.amazonaws.com."""
+        response = httpx.get(CHECKIP_URL, timeout=10.0)
+        return response.text.strip()
+
+    def download_and_record(
+        self,
+        bucket: str,
+        object_id: str,
+        destination: str | Path,
+        ip_address: str | None = None,
+        user_agent: str | None = None,
+        progress_callback: Callable[[int], None] | None = None,
+        transfer_config: R2TransferConfig | None = None,
+    ) -> tuple[Path, FileRecord]:
+        """
+        Download a file from R2 and record the download in the index.
+
+        This is a convenience method that performs:
+        1. Parse object_id into remote_path, remote_version, remote_filename
+        2. Fetch file record from the API using these components
+        3. Download the file from R2
+        4. Record the download in the index for analytics
+
+        Args:
+            bucket: The S3/R2 bucket name.
+            object_id: Full S3 object path in format: /path/to/object/version/filename
+                Example: /releases/myapp/v1/myapp.zip
+                - remote_path: /releases/myapp
+                - remote_version: v1
+                - remote_filename: myapp.zip
+            destination: Local path where the file will be saved.
+            ip_address: IP address of the downloader. If not provided, fetched
+                from checkip.amazonaws.com.
+            user_agent: User agent string. Defaults to "elaunira-r2index/0.1.0".
+            progress_callback: Optional callback for download progress.
+            transfer_config: Optional transfer configuration for multipart/threading.
+
+        Returns:
+            A tuple of (downloaded file path, file record).
+
+        Raises:
+            R2IndexError: If R2 config is not provided.
+            ValueError: If object_id format is invalid.
+            NotFoundError: If the file is not found in the index.
+            DownloadError: If download fails.
+        """
+        storage = self._get_storage()
+
+        # Resolve defaults
+        if ip_address is None:
+            ip_address = self._get_public_ip()
+        if user_agent is None:
+            user_agent = DEFAULT_USER_AGENT
+
+        # Step 1: Parse object_id into components
+        remote_tuple = _parse_object_id(object_id, bucket)
+
+        # Step 2: Get file record by tuple
+        file_record = self.get_file_by_tuple(remote_tuple)
+
+        # Step 3: Build R2 object key and download
+        object_key = object_id.strip("/")
+        downloaded_path = storage.download_file(
+            object_key,
+            destination,
+            progress_callback=progress_callback,
+            transfer_config=transfer_config,
+        )
+
+        # Step 4: Record the download
+        download_request = DownloadRecordRequest(
+            file_id=file_record.id,
+            ip_address=ip_address,
+            user_agent=user_agent,
+        )
+        self.record_download(download_request)
+
+        return downloaded_path, file_record

elaunira/r2index/exceptions.py

@@ -38,3 +38,9 @@ class UploadError(R2IndexError):
     """Raised for R2 upload failures."""
 
     pass
+
+
+class DownloadError(R2IndexError):
+    """Raised for R2 download failures."""
+
+    pass

elaunira/r2index/models.py

@@ -9,6 +9,7 @@ from pydantic import BaseModel, Field
 class RemoteTuple(BaseModel):
     """Remote file identifier tuple."""
 
+    bucket: str
     remote_path: str
     remote_filename: str
     remote_version: str
@@ -17,6 +18,7 @@ class RemoteTuple(BaseModel):
 class FileCreateRequest(BaseModel):
     """Request payload for creating/upserting a file record."""
 
+    bucket: str
     category: str
     entity: str
     remote_path: str
@@ -35,6 +37,7 @@ class FileCreateRequest(BaseModel):
 class FileUpdateRequest(BaseModel):
     """Request payload for updating a file record."""
 
+    bucket: str | None = None
     category: str | None = None
     entity: str | None = None
     remote_path: str | None = None
@@ -54,6 +57,7 @@ class FileRecord(BaseModel):
     """File record as returned by the API."""
 
     id: str
+    bucket: str
     category: str
     entity: str
     remote_path: str
@@ -86,6 +90,7 @@ class IndexEntry(BaseModel):
     """Single entry in the index response."""
 
     id: str
+    bucket: str
     category: str
     entity: str
     remote_path: str

elaunira/r2index/{uploader.py → storage.py}

@@ -1,17 +1,41 @@
-"""Synchronous R2 uploader using boto3."""
+"""Synchronous R2 storage operations using boto3."""
 
+import os
 from collections.abc import Callable
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 
 import boto3
 from boto3.s3.transfer import TransferConfig
 
-from .exceptions import UploadError
+from .exceptions import DownloadError, UploadError
 
-# 100MB threshold and part size for multipart uploads
-MULTIPART_THRESHOLD = 100 * 1024 * 1024
-MULTIPART_PART_SIZE = 100 * 1024 * 1024
+# Default thresholds and part sizes for multipart transfers
+DEFAULT_MULTIPART_CHUNKSIZE = 100 * 1024 * 1024  # 100MB
+DEFAULT_MULTIPART_THRESHOLD = 100 * 1024 * 1024  # 100MB
+
+
+def _default_max_concurrency() -> int:
+    """Return default max concurrency: 2x CPU cores, minimum 4."""
+    cpu_count = os.cpu_count() or 2
+    return max(4, cpu_count * 2)
+
+
+@dataclass
+class R2TransferConfig:
+    """Configuration for R2 transfer operations (uploads/downloads)."""
+
+    multipart_threshold: int = DEFAULT_MULTIPART_THRESHOLD
+    """Size threshold (bytes) to trigger multipart transfer. Default 100MB."""
+
+    multipart_chunksize: int = DEFAULT_MULTIPART_CHUNKSIZE
+    """Size of each part (bytes) in multipart transfer. Default 100MB."""
+
+    max_concurrency: int = field(default_factory=_default_max_concurrency)
+    """Number of parallel threads for multipart transfer. Default 2x CPU cores."""
+
+    use_threads: bool = True
+    """Whether to use threads for parallel transfer. Default True."""
 
 
 @dataclass
@@ -25,12 +49,12 @@ class R2Config:
     region: str = "auto"
 
 
-class R2Uploader:
-    """Synchronous R2 uploader using boto3."""
+class R2Storage:
+    """Synchronous R2 storage client using boto3."""
 
     def __init__(self, config: R2Config) -> None:
         """
-        Initialize the R2 uploader.
+        Initialize the R2 storage client.
 
         Args:
             config: R2 configuration with credentials and endpoint.
@@ -50,17 +74,19 @@ class R2Uploader:
         object_key: str,
         content_type: str | None = None,
         progress_callback: Callable[[int], None] | None = None,
+        transfer_config: R2TransferConfig | None = None,
     ) -> str:
         """
         Upload a file to R2.
 
-        Uses multipart upload for files larger than 100MB.
+        Uses multipart upload for files larger than the configured threshold.
 
         Args:
             file_path: Path to the file to upload.
             object_key: The key (path) to store the object under in R2.
             content_type: Optional content type for the object.
             progress_callback: Optional callback called with bytes uploaded so far.
+            transfer_config: Optional transfer configuration for multipart/threading.
 
         Returns:
             The object key of the uploaded file.
@@ -73,10 +99,12 @@ class R2Uploader:
         if not file_path.exists():
             raise UploadError(f"File not found: {file_path}")
 
-        transfer_config = TransferConfig(
-            multipart_threshold=MULTIPART_THRESHOLD,
-            multipart_chunksize=MULTIPART_PART_SIZE,
-            use_threads=True,
+        tc = transfer_config or R2TransferConfig()
+        boto_transfer_config = TransferConfig(
+            multipart_threshold=tc.multipart_threshold,
+            multipart_chunksize=tc.multipart_chunksize,
+            max_concurrency=tc.max_concurrency,
+            use_threads=tc.use_threads,
         )
 
         extra_args = {}
@@ -92,7 +120,7 @@ class R2Uploader:
                 str(file_path),
                 self.config.bucket,
                 object_key,
-                Config=transfer_config,
+                Config=boto_transfer_config,
                 ExtraArgs=extra_args if extra_args else None,
                 Callback=callback,
             )
@@ -134,6 +162,58 @@ class R2Uploader:
                 return False
             raise UploadError(f"Failed to check object existence: {e}") from e
 
+    def download_file(
+        self,
+        object_key: str,
+        file_path: str | Path,
+        progress_callback: Callable[[int], None] | None = None,
+        transfer_config: R2TransferConfig | None = None,
+    ) -> Path:
+        """
+        Download a file from R2.
+
+        Args:
+            object_key: The key (path) of the object in R2.
+            file_path: Local path where the file will be saved.
+            progress_callback: Optional callback called with bytes downloaded so far.
+            transfer_config: Optional transfer configuration for multipart/threading.
+
+        Returns:
+            The path to the downloaded file.
+
+        Raises:
+            DownloadError: If the download fails.
+        """
+        file_path = Path(file_path)
+
+        # Ensure parent directory exists
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        tc = transfer_config or R2TransferConfig()
+        boto_transfer_config = TransferConfig(
+            multipart_threshold=tc.multipart_threshold,
+            multipart_chunksize=tc.multipart_chunksize,
+            max_concurrency=tc.max_concurrency,
+            use_threads=tc.use_threads,
+        )
+
+        callback = None
+        if progress_callback:
+            callback = _ProgressCallback(progress_callback)
+
+        try:
+            self._client.download_file(
+                self.config.bucket,
+                object_key,
+                str(file_path),
+                Config=boto_transfer_config,
+                Callback=callback,
+            )
+        except Exception as e:
+            raise DownloadError(f"Failed to download file from R2: {e}") from e
+
+        return file_path
+
 
 class _ProgressCallback:
     """Wrapper to track cumulative progress for boto3 callback."""

elaunira_r2index-0.2.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: elaunira-r2index
+Version: 0.2.0
+Summary: Python library for uploading files to R2 and registering them with the r2index API
+Project-URL: Homepage, https://github.com/elaunira/elaunira-r2-index
+Project-URL: Repository, https://github.com/elaunira/elaunira-r2-index
+Author: Elaunira
+License-Expression: MIT
+Keywords: cloudflare,index,r2,storage,upload
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aioboto3>=13.0.0
+Requires-Dist: boto3>=1.35.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.10.0
+Provides-Extra: dev
+Requires-Dist: boto3-stubs[s3]>=1.35.0; extra == 'dev'
+Requires-Dist: build>=1.2.0; extra == 'dev'
+Requires-Dist: mypy>=1.15.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.35.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: twine>=6.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# elaunira-r2index
+
+Python library for uploading and downloading files to/from Cloudflare R2 with the r2index API.
+
+## Installation
+
+```bash
+pip install elaunira-r2index
+```
+
+## Usage
+
+### Sync Client
+
+```python
+from elaunira.r2index import R2IndexClient, R2Config
+
+client = R2IndexClient(
+    api_url="https://r2index.example.com",
+    api_token="your-bearer-token",
+    r2_config=R2Config(
+        access_key_id="your-r2-access-key-id",
+        secret_access_key="your-r2-secret-access-key",
+        endpoint_url="https://your-account-id.r2.cloudflarestorage.com",
+        bucket="your-bucket-name",
+    ),
+)
+
+# Upload and register a file
+record = client.upload_and_register(
+    local_path="./myfile.zip",
+    bucket="my-bucket",
+    category="software",
+    entity="myapp",
+    remote_path="/releases/myapp",
+    remote_filename="myapp.zip",
+    remote_version="v1",
+    tags=["release", "stable"],
+)
+
+# Download a file and record the download
+# IP address is auto-detected, user agent defaults to "elaunira-r2index/0.1.0"
+path, record = client.download_and_record(
+    bucket="my-bucket",
+    object_id="/releases/myapp/v1/myapp.zip",
+    destination="./downloads/myfile.zip",
+)
+```
+
+### Async Client
+
+```python
+from elaunira.r2index import AsyncR2IndexClient, R2Config
+
+async with AsyncR2IndexClient(
+    api_url="https://r2index.example.com",
+    api_token="your-bearer-token",
+    r2_config=R2Config(
+        access_key_id="your-r2-access-key-id",
+        secret_access_key="your-r2-secret-access-key",
+        endpoint_url="https://your-account-id.r2.cloudflarestorage.com",
+        bucket="your-bucket-name",
+    ),
+) as client:
+    # Upload
+    record = await client.upload_and_register(
+        local_path="./myfile.zip",
+        bucket="my-bucket",
+        category="software",
+        entity="myapp",
+        remote_path="/releases/myapp",
+        remote_filename="myapp.zip",
+        remote_version="v1",
+        tags=["release", "stable"],
+    )
+
+    # Download
+    path, record = await client.download_and_record(
+        bucket="my-bucket",
+        object_id="/releases/myapp/v1/myapp.zip",
+        destination="./downloads/myfile.zip",
+    )
+```
+
+### Transfer Configuration
+
+Control multipart transfer settings with `R2TransferConfig`:
+
+```python
+from elaunira.r2index import R2IndexClient, R2Config, R2TransferConfig
+
+client = R2IndexClient(
+    api_url="https://r2index.example.com",
+    api_token="your-bearer-token",
+    r2_config=R2Config(...),
+)
+
+# Custom transfer settings
+transfer_config = R2TransferConfig(
+    multipart_threshold=100 * 1024 * 1024,  # 100MB (default)
+    multipart_chunksize=32 * 1024 * 1024,   # 32MB chunks
+    max_concurrency=64,                      # 64 parallel threads
+    use_threads=True,                        # Enable threading (default)
+)
+
+path, record = client.download_and_record(
+    bucket="my-bucket",
+    object_id="/data/files/v2/largefile.zip",
+    destination="./downloads/largefile.zip",
+    transfer_config=transfer_config,
+)
+```
+
+Default `max_concurrency` is 2x the number of CPU cores (minimum 4).
+
+### Progress Tracking
+
+```python
+def on_progress(bytes_transferred: int) -> None:
+    print(f"Downloaded: {bytes_transferred / 1024 / 1024:.1f} MB")
+
+path, record = client.download_and_record(
+    bucket="my-bucket",
+    object_id="/releases/myapp/v1/myapp.zip",
+    destination="./downloads/myfile.zip",
+    progress_callback=on_progress,
+)
+```
+
+## License
+
+MIT

elaunira_r2index-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+elaunira/__init__.py,sha256=qaXVGBU6uIJyveNTEbWux5EcfVSM186PvDwjyxiXLw4,34
+elaunira/r2index/__init__.py,sha256=zbQ929kyFDEoexnvyerpRarQv1VfBKeXyFy3c2U-xAI,2075
+elaunira/r2index/async_client.py,sha256=SfNUPWIcl_hucP0PvzA116uUQUi4sjyF0kEouVVKiLY,20527
+elaunira/r2index/async_storage.py,sha256=wDoxjXbP0SfMxK9DOmcfcfnQIAsfpnOPr0JoN-yo80I,6903
+elaunira/r2index/checksums.py,sha256=tqRTJ7j3pWLJlQ8FQE20JRYk9lXy5YZzymdpYOhsTFo,3281
+elaunira/r2index/client.py,sha256=1bAFXCYP93Zh61PM0gWPzrG6ByCUW01W_MVJCs3FZH0,20072
+elaunira/r2index/exceptions.py,sha256=wgWNUgev9Azbsn4EFTAgVXECjW-TuDR6D1FVo5orTco,885
+elaunira/r2index/models.py,sha256=OfgXYcRFrfYip9GHPAJz9gleWdnpzuanD6adVWAYRGk,4850
+elaunira/r2index/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+elaunira/r2index/storage.py,sha256=3l6w5KS5XeCh8_5rZ7CI2MiPpFi30LOPYUZYi_Rq5Wo,7119
+elaunira_r2index-0.2.0.dist-info/METADATA,sha256=Scdi6AIol__OX4GCEy3P9cQQnBXAKOp9wMhw-9A0zuQ,4716
+elaunira_r2index-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+elaunira_r2index-0.2.0.dist-info/RECORD,,

elaunira_r2index-0.1.0.dist-info/METADATA

@@ -1,101 +0,0 @@
-Metadata-Version: 2.4
-Name: elaunira-r2index
-Version: 0.1.0
-Summary: Python library for uploading files to R2 and registering them with the r2index API
-Project-URL: Homepage, https://github.com/elaunira/elaunira-r2-index
-Project-URL: Repository, https://github.com/elaunira/elaunira-r2-index
-Author: Elaunira
-License-Expression: MIT
-Keywords: cloudflare,index,r2,storage,upload
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Typing :: Typed
-Requires-Python: >=3.12
-Requires-Dist: aioboto3>=12.0.0
-Requires-Dist: boto3>=1.34.0
-Requires-Dist: httpx>=0.25.0
-Requires-Dist: pydantic>=2.0.0
-Provides-Extra: dev
-Requires-Dist: boto3-stubs[s3]>=1.34.0; extra == 'dev'
-Requires-Dist: build>=1.0.0; extra == 'dev'
-Requires-Dist: mypy>=1.8.0; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
-Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
-Requires-Dist: pytest>=8.0.0; extra == 'dev'
-Requires-Dist: ruff>=0.3.0; extra == 'dev'
-Requires-Dist: twine>=5.0.0; extra == 'dev'
-Description-Content-Type: text/markdown
-
-# elaunira-r2index
-
-Python library for uploading files to Cloudflare R2 and registering them with the r2index API.
-
-## Installation
-
-```bash
-pip install elaunira-r2index
-```
-
-## Usage
-
-### Sync Client
-
-```python
-from elaunira.r2index import R2IndexClient, R2Config
-
-client = R2IndexClient(
-    api_url="https://r2index.example.com",
-    api_token="your-bearer-token",
-    r2_config=R2Config(
-        access_key_id="your-r2-access-key-id",
-        secret_access_key="your-r2-secret-access-key",
-        endpoint_url="https://your-account-id.r2.cloudflarestorage.com",
-        bucket="your-bucket-name",
-    ),
-)
-
-# Upload and register a file
-record = client.upload_and_register(
-    file_path="./myfile.zip",
-    category="software",
-    entity="myapp",
-    remote_path="/releases",
-    remote_filename="myapp-1.0.0.zip",
-    remote_version="1.0.0",
-    tags=["release", "stable"],
-)
-```
-
-### Async Client
-
-```python
-from elaunira.r2index import AsyncR2IndexClient, R2Config
-
-async with AsyncR2IndexClient(
-    api_url="https://r2index.example.com",
-    api_token="your-bearer-token",
-    r2_config=R2Config(
-        access_key_id="your-r2-access-key-id",
-        secret_access_key="your-r2-secret-access-key",
-        endpoint_url="https://your-account-id.r2.cloudflarestorage.com",
-        bucket="your-bucket-name",
-    ),
-) as client:
-    record = await client.upload_and_register(
-        file_path="./myfile.zip",
-        category="software",
-        entity="myapp",
-        remote_path="/releases",
-        remote_filename="myapp-1.0.0.zip",
-        remote_version="1.0.0",
-        tags=["release", "stable"],
-    )
-```
-
-## License
-
-MIT

elaunira_r2index-0.1.0.dist-info/RECORD

@@ -1,12 +0,0 @@
-elaunira/__init__.py,sha256=qaXVGBU6uIJyveNTEbWux5EcfVSM186PvDwjyxiXLw4,34
-elaunira/r2index/__init__.py,sha256=dPjPlDfBIUqzS9STNNtyMF1LyPakXeY5I1ypHEM_jTo,2878
-elaunira/r2index/async_client.py,sha256=T8fWZKnJZOTgsDEvdvv67xL-d_QJ5pP1A3LznEZZ6gY,14936
-elaunira/r2index/async_uploader.py,sha256=ctf65f2DjT9gckEh7XXpHRp1Ym14zv6vx1zIgN_SJpg,4868
-elaunira/r2index/checksums.py,sha256=tqRTJ7j3pWLJlQ8FQE20JRYk9lXy5YZzymdpYOhsTFo,3281
-elaunira/r2index/client.py,sha256=LPtE4uq_OKfmyFJKMKM_hdmU8euVAWkCe17T7HAzXL8,14608
-elaunira/r2index/exceptions.py,sha256=JTSztfTH-jar2jSKEUmQO8VKfRNWfHTB0WgvwLJCVU8,795
-elaunira/r2index/models.py,sha256=ie6uOpamrdmOc9bljym61FurRzpcsoQ1qB4rQQGu7_I,4756
-elaunira/r2index/uploader.py,sha256=kKkC6f_YwMIJ-Tict7mn3S0Sdim6pI4rRXF0xvNwjh0,4250
-elaunira_r2index-0.1.0.dist-info/METADATA,sha256=zQ8Up7wJ-7g26hwL-Ay3QXxgtTaIs8ljUGVgloupv3M,2923
-elaunira_r2index-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-elaunira_r2index-0.1.0.dist-info/RECORD,,