tiny-object-storage 0.1.1__py3-none-any.whl

tiny_object_storage/__init__.py

@@ -0,0 +1,8 @@
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("tiny-object-storage")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "unknown"
+
+__all__ = ["__version__"]

tiny_object_storage/api/buckets.py

@@ -0,0 +1,114 @@
+from fastapi import APIRouter, Request, Response, status
+from fastapi.responses import Response as FastAPIResponse
+
+from tiny_object_storage.core.utils import build_list_buckets_xml
+from tiny_object_storage.models.bucket import BucketInfo
+from tiny_object_storage.models.responses import (
+    BucketCreatedResponse,
+    BucketsListResponse,
+    ErrorResponse,
+)
+
+router = APIRouter(tags=["buckets"])
+
+
+@router.get(
+    "/",
+    responses={
+        200: {
+            "description": "Buckets returned in S3-style XML.",
+            "content": {"application/xml": {}},
+        },
+        500: {"model": ErrorResponse, "description": "Internal server error."},
+    },
+    summary="List buckets",
+    description="Return all available buckets as a minimal S3-compatible XML response.",
+)
+def list_buckets(request: Request) -> FastAPIResponse:
+    # Return all buckets from the service layer as XML.
+    bucket_service = request.app.state.bucket_service
+    buckets = bucket_service.list_buckets()
+    xml_payload = build_list_buckets_xml(buckets)
+    return FastAPIResponse(content=xml_payload, media_type="application/xml")
+
+
+@router.get(
+    "/_debug/buckets",
+    response_model=BucketsListResponse,
+    include_in_schema=True,
+    summary="List buckets as JSON",
+    description="Return all available buckets in JSON format for debugging and development.",
+    responses={
+        500: {"model": ErrorResponse, "description": "Internal server error."},
+    },
+)
+def list_buckets_json(request: Request) -> BucketsListResponse:
+    # Return all buckets from the service layer as JSON.
+    bucket_service = request.app.state.bucket_service
+    buckets = bucket_service.list_buckets()
+    return BucketsListResponse(buckets=[BucketInfo(**bucket) for bucket in buckets])
+
+
+@router.put(
+    "/{bucket_name}",
+    response_model=BucketCreatedResponse,
+    status_code=status.HTTP_200_OK,
+    summary="Create bucket",
+    description="Create a new bucket using an S3-style path.",
+    responses={
+        200: {"description": "Bucket created."},
+        400: {"model": ErrorResponse, "description": "Invalid bucket name."},
+        409: {"model": ErrorResponse, "description": "Bucket already exists."},
+        500: {"model": ErrorResponse, "description": "Internal server error."},
+    },
+)
+def create_bucket(bucket_name: str, request: Request) -> BucketCreatedResponse:
+    # Create a new bucket and return its metadata.
+    bucket_service = request.app.state.bucket_service
+    bucket = bucket_service.create_bucket(bucket_name=bucket_name)
+    return BucketCreatedResponse(
+        message="Bucket created successfully.",
+        bucket=BucketInfo(**bucket),
+    )
+
+
+@router.delete(
+    "/{bucket_name}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete bucket",
+    description="Delete an existing bucket. The bucket must be empty.",
+    responses={
+        204: {"description": "Bucket deleted."},
+        400: {"model": ErrorResponse, "description": "Invalid bucket name."},
+        404: {"model": ErrorResponse, "description": "Bucket not found."},
+        409: {"model": ErrorResponse, "description": "Bucket is not empty."},
+        500: {"model": ErrorResponse, "description": "Internal server error."},
+    },
+)
+def delete_bucket(bucket_name: str, request: Request) -> Response:
+    # Delete the requested bucket.
+    bucket_service = request.app.state.bucket_service
+    bucket_service.delete_bucket(bucket_name=bucket_name)
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+@router.head(
+    "/{bucket_name}",
+    status_code=status.HTTP_200_OK,
+    summary="Head bucket",
+    description="Determine if a bucket exists and if you have permission to access it.",
+    responses={
+        200: {"description": "Bucket exists."},
+        400: {"model": ErrorResponse, "description": "Invalid bucket name."},
+        404: {"model": ErrorResponse, "description": "Bucket not found."},
+        500: {"model": ErrorResponse, "description": "Internal server error."},
+    },
+)
+def head_bucket(bucket_name: str, request: Request) -> Response:
+    # Check if a bucket exists. Boto3 relies on this to verify buckets before acting.
+    bucket_service = request.app.state.bucket_service
+    from tiny_object_storage.core.errors import BucketNotFoundError
+
+    if not bucket_service.bucket_exists(bucket_name):
+        raise BucketNotFoundError(f"Bucket '{bucket_name}' does not exist.")
+    return Response(status_code=status.HTTP_200_OK)

tiny_object_storage/api/health.py

@@ -0,0 +1,25 @@
+from fastapi import APIRouter, Request
+
+from tiny_object_storage.models.responses import HealthResponse
+
+router = APIRouter(tags=["health"])
+
+
+@router.get(
+    "/health",
+    response_model=HealthResponse,
+    summary="Health check",
+    description="Return the current service health status and active runtime configuration.",
+)
+def healthcheck(request: Request) -> HealthResponse:
+    # Return a simple health status payload.
+    settings = request.app.state.settings
+
+    return HealthResponse(
+        status="ok",
+        app_name=settings.app_name,
+        data_dir=str(settings.data_dir),
+        log_dir=str(settings.log_dir),
+        log_level=settings.log_level,
+        dev_mode=settings.dev_mode,
+    )

tiny_object_storage/api/objects.py

@@ -0,0 +1,196 @@
+from datetime import UTC, datetime
+from io import BytesIO
+
+from fastapi import APIRouter, Header, Query, Request, Response, status
+from fastapi.responses import StreamingResponse
+
+from tiny_object_storage.core.utils import build_list_objects_v2_xml, http_date
+from tiny_object_storage.models.object_info import ObjectInfo
+from tiny_object_storage.models.responses import (
+    ErrorResponse,
+    ObjectsListResponse,
+)
+
+router = APIRouter(tags=["objects"])
+
+
+@router.get(
+    "/{bucket_name}",
+    responses={
+        200: {
+            "description": "Objects returned in minimal S3 ListObjectsV2 XML format.",
+            "content": {"application/xml": {}},
+        },
+        400: {"model": ErrorResponse, "description": "Invalid bucket name or query parameter."},
+        404: {"model": ErrorResponse, "description": "Bucket not found."},
+        500: {"model": ErrorResponse, "description": "Internal server error."},
+    },
+    summary="List objects",
+    description="Return objects in a bucket using a minimal S3 ListObjectsV2 XML response.",
+)
+def list_objects(
+    bucket_name: str,
+    request: Request,
+    list_type: int = Query(
+        default=2,
+        alias="list-type",
+        description="S3-style listing mode. Only value 2 is currently supported.",
+    ),
+    prefix: str = Query(default="", description="Optional key prefix filter."),
+    max_keys: int = Query(default=1000, alias="max-keys", description="Maximum number of keys."),
+) -> Response:
+    # Return bucket contents in minimal S3-compatible XML.
+    if list_type != 2:
+        raise ValueError("Only list-type=2 is supported.")
+
+    object_service = request.app.state.object_service
+    objects = object_service.list_objects(bucket_name=bucket_name)
+
+    if prefix:
+        objects = [item for item in objects if item["object_key"].startswith(prefix)]
+
+    limited = objects[:max_keys]
+    truncated = len(objects) > max_keys
+
+    xml_payload = build_list_objects_v2_xml(
+        bucket_name=bucket_name,
+        objects=limited,
+        prefix=prefix,
+        max_keys=max_keys,
+        is_truncated=truncated,
+    )
+    return Response(content=xml_payload, media_type="application/xml")
+
+
+@router.get(
+    "/_debug/{bucket_name}",
+    response_model=ObjectsListResponse,
+    include_in_schema=True,
+    summary="List objects as JSON",
+    description="Return objects in a bucket as JSON for debugging and development.",
+    responses={
+        400: {"model": ErrorResponse, "description": "Invalid bucket name or query parameter."},
+        404: {"model": ErrorResponse, "description": "Bucket not found."},
+        500: {"model": ErrorResponse, "description": "Internal server error."},
+    },
+)
+def list_objects_json(bucket_name: str, request: Request) -> ObjectsListResponse:
+    # Return all objects in the requested bucket as JSON.
+    object_service = request.app.state.object_service
+    objects = object_service.list_objects(bucket_name=bucket_name)
+    return ObjectsListResponse(
+        bucket_name=bucket_name,
+        objects=[ObjectInfo(**item) for item in objects],
+    )
+
+
+@router.put(
+    "/{bucket_name}/{object_key:path}",
+    status_code=status.HTTP_200_OK,
+    summary="Upload object",
+    description="Store an object in a bucket using an S3-style path and a raw request body.",
+    responses={
+        200: {"description": "Object stored."},
+        400: {"model": ErrorResponse, "description": "Invalid input."},
+        404: {"model": ErrorResponse, "description": "Bucket not found."},
+        500: {"model": ErrorResponse, "description": "Internal server error."},
+    },
+)
+async def put_object(
+    bucket_name: str,
+    object_key: str,
+    request: Request,
+    content_type: str | None = Header(default=None, alias="Content-Type"),
+) -> Response:
+    # Upload an object using a raw request body.
+    body = await request.body()
+    object_service = request.app.state.object_service
+    metadata = object_service.put_object(
+        bucket_name=bucket_name,
+        object_key=object_key,
+        data=body,
+        content_type=content_type,
+    )
+    headers = {"ETag": f"\"{metadata['etag']}\""}
+    return Response(status_code=status.HTTP_200_OK, headers=headers)
+
+
+@router.head(
+    "/{bucket_name}/{object_key:path}",
+    status_code=status.HTTP_200_OK,
+    summary="Head object",
+    description="Return object metadata headers without returning the object body.",
+    responses={
+        200: {"description": "Object metadata returned in headers."},
+        400: {"model": ErrorResponse, "description": "Invalid input."},
+        404: {"model": ErrorResponse, "description": "Bucket or object not found."},
+        500: {"model": ErrorResponse, "description": "Internal server error."},
+    },
+)
+def head_object(bucket_name: str, object_key: str, request: Request) -> Response:
+    # Return object metadata using standard S3-style headers.
+    object_service = request.app.state.object_service
+    stored_object = object_service.get_object(bucket_name=bucket_name, object_key=object_key)
+
+    headers = {
+        "ETag": f"\"{stored_object.metadata['etag']}\"",
+        "Content-Length": str(stored_object.metadata["size"]),
+        "Content-Type": stored_object.metadata["content_type"],
+        "Last-Modified": http_date(stored_object.metadata.get("updated_at"))
+        or format_fallback_http_date(),
+    }
+    return Response(status_code=status.HTTP_200_OK, headers=headers)
+
+
+@router.get(
+    "/{bucket_name}/{object_key:path}",
+    summary="Download object",
+    description="Download a stored object using an S3-style path.",
+    responses={
+        200: {"description": "Object returned."},
+        400: {"model": ErrorResponse, "description": "Invalid input."},
+        404: {"model": ErrorResponse, "description": "Bucket or object not found."},
+        500: {"model": ErrorResponse, "description": "Internal server error."},
+    },
+)
+def get_object(bucket_name: str, object_key: str, request: Request) -> StreamingResponse:
+    # Stream the stored object back to the client.
+    object_service = request.app.state.object_service
+    stored_object = object_service.get_object(bucket_name=bucket_name, object_key=object_key)
+
+    headers = {
+        "ETag": f"\"{stored_object.metadata['etag']}\"",
+        "Content-Length": str(stored_object.metadata["size"]),
+        "Last-Modified": http_date(stored_object.metadata.get("updated_at"))
+        or format_fallback_http_date(),
+    }
+
+    return StreamingResponse(
+        content=BytesIO(stored_object.data),
+        media_type=stored_object.metadata["content_type"],
+        headers=headers,
+    )
+
+
+@router.delete(
+    "/{bucket_name}/{object_key:path}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete object",
+    description="Delete an object from a bucket using an S3-style path.",
+    responses={
+        204: {"description": "Object deleted."},
+        400: {"model": ErrorResponse, "description": "Invalid input."},
+        404: {"model": ErrorResponse, "description": "Bucket or object not found."},
+        500: {"model": ErrorResponse, "description": "Internal server error."},
+    },
+)
+def delete_object(bucket_name: str, object_key: str, request: Request) -> Response:
+    # Delete the requested object.
+    object_service = request.app.state.object_service
+    object_service.delete_object(bucket_name=bucket_name, object_key=object_key)
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+def format_fallback_http_date() -> str:
+    # Return the current UTC time formatted for HTTP headers.
+    return datetime.now(UTC).strftime("%a, %d %b %Y %H:%M:%S GMT")

tiny_object_storage/cli.py

@@ -0,0 +1,128 @@
+import argparse
+import os
+from pathlib import Path
+
+import uvicorn
+from dotenv import load_dotenv
+
+from tiny_object_storage.config import get_settings
+
+
+def str_to_bool(value: str) -> bool:
+    # Convert common string values to boolean.
+    normalized = value.strip().lower()
+    if normalized in {"1", "true", "yes", "y", "on"}:
+        return True
+    if normalized in {"0", "false", "no", "n", "off"}:
+        return False
+    raise argparse.ArgumentTypeError(f"Invalid boolean value: {value}")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    # Build the CLI argument parser.
+    parser = argparse.ArgumentParser(
+        prog="tos-server",
+        description="Run the tiny-object-storage server.",
+    )
+
+    parser.add_argument(
+        "--env-file",
+        default=".env",
+        help="Path to the .env file to load before starting the server.",
+    )
+    parser.add_argument(
+        "--host",
+        help="Override server host.",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        help="Override server port.",
+    )
+    parser.add_argument(
+        "--log-level",
+        choices=["critical", "error", "warning", "info", "debug", "trace"],
+        help="Override uvicorn log level.",
+    )
+    parser.add_argument(
+        "--reload",
+        action="store_true",
+        help="Enable auto-reload.",
+    )
+    parser.add_argument(
+        "--no-reload",
+        action="store_true",
+        help="Disable auto-reload even if dev mode is enabled.",
+    )
+    parser.add_argument(
+        "--data-dir",
+        help="Override storage data directory.",
+    )
+    parser.add_argument(
+        "--log-dir",
+        help="Override application log directory.",
+    )
+    parser.add_argument(
+        "--dev-mode",
+        type=str_to_bool,
+        help="Override development mode.",
+    )
+    parser.add_argument(
+        "--max-object-size",
+        type=int,
+        help="Override maximum object size in bytes.",
+    )
+
+    return parser
+
+
+def main() -> None:
+    # Load configuration sources, apply CLI overrides, and start the server.
+    parser = build_parser()
+    args = parser.parse_args()
+
+    env_file = Path(args.env_file)
+    if env_file.exists():
+        load_dotenv(dotenv_path=env_file, override=False)
+
+    if args.host is not None:
+        os.environ["TOS_HOST"] = args.host
+
+    if args.port is not None:
+        os.environ["TOS_PORT"] = str(args.port)
+
+    if args.data_dir is not None:
+        os.environ["TOS_DATA_DIR"] = args.data_dir
+
+    if args.log_dir is not None:
+        os.environ["TOS_LOG_DIR"] = args.log_dir
+
+    if args.dev_mode is not None:
+        os.environ["TOS_DEV_MODE"] = "true" if args.dev_mode else "false"
+
+    if args.max_object_size is not None:
+        os.environ["TOS_MAX_OBJECT_SIZE"] = str(args.max_object_size)
+
+    if args.log_level is not None:
+        os.environ["TOS_LOG_LEVEL"] = args.log_level.upper()
+
+    get_settings.cache_clear()
+    settings = get_settings()
+
+    reload_enabled = settings.dev_mode
+    if args.reload:
+        reload_enabled = True
+    if args.no_reload:
+        reload_enabled = False
+
+    uvicorn.run(
+        "tiny_object_storage.main:app",
+        host=settings.host,
+        port=settings.port,
+        reload=reload_enabled,
+        log_level=settings.log_level.lower(),
+    )
+
+
+if __name__ == "__main__":
+    main()

tiny_object_storage/config.py

@@ -0,0 +1,37 @@
+from functools import lru_cache
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    # Runtime settings for the application.
+    app_name: str = Field(default="tiny-object-storage", alias="TOS_APP_NAME")
+    host: str = Field(default="0.0.0.0", alias="TOS_HOST")
+    port: int = Field(default=9000, alias="TOS_PORT")
+    data_dir: Path = Field(default=Path("./storage_data"), alias="TOS_DATA_DIR")
+    log_dir: Path = Field(default=Path("./logs"), alias="TOS_LOG_DIR")
+    log_level: str = Field(default="INFO", alias="TOS_LOG_LEVEL")
+    dev_mode: bool = Field(default=True, alias="TOS_DEV_MODE")
+    max_object_size: int = Field(default=104857600, alias="TOS_MAX_OBJECT_SIZE")
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+        populate_by_name=True,
+    )
+
+    def ensure_directories(self) -> None:
+        # Create required directories if they do not exist.
+        self.data_dir.mkdir(parents=True, exist_ok=True)
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+
+
+@lru_cache
+def get_settings() -> Settings:
+    # Return cached application settings.
+    settings = Settings()
+    settings.ensure_directories()
+    return settings

tiny_object_storage/core/errors.py

@@ -0,0 +1,33 @@
+class TinyObjectStorageError(Exception):
+    # Base exception for all domain-specific errors.
+    pass
+
+
+class BucketAlreadyExistsError(TinyObjectStorageError):
+    # Raised when trying to create a bucket that already exists.
+    pass
+
+
+class BucketNotFoundError(TinyObjectStorageError):
+    # Raised when the target bucket does not exist.
+    pass
+
+
+class BucketNotEmptyError(TinyObjectStorageError):
+    # Raised when trying to delete a non-empty bucket.
+    pass
+
+
+class ObjectNotFoundError(TinyObjectStorageError):
+    # Raised when the target object does not exist.
+    pass
+
+
+class InvalidBucketNameError(TinyObjectStorageError):
+    # Raised when a bucket name does not meet validation rules.
+    pass
+
+
+class InvalidObjectKeyError(TinyObjectStorageError):
+    # Raised when an object key does not meet validation rules.
+    pass