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

tiny_object_storage/core/utils.py

@@ -0,0 +1,209 @@
+import hashlib
+import json
+import re
+from datetime import UTC, datetime
+from email.utils import format_datetime
+from pathlib import Path
+from typing import Any
+from xml.etree.ElementTree import Element, SubElement, tostring
+
+from tiny_object_storage.core.errors import InvalidBucketNameError, InvalidObjectKeyError
+
+_BUCKET_NAME_PATTERN = re.compile(r"^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$")
+
+
+def utc_now() -> datetime:
+    # Return the current UTC datetime.
+    return datetime.now(UTC)
+
+
+def utc_now_iso() -> str:
+    # Return the current UTC time in ISO 8601 format.
+    return utc_now().isoformat()
+
+
+def parse_iso_datetime(value: str | None) -> datetime | None:
+    # Parse an ISO 8601 datetime string.
+    if not value:
+        return None
+
+    normalized = value.replace("Z", "+00:00")
+    parsed = datetime.fromisoformat(normalized)
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=UTC)
+    return parsed.astimezone(UTC)
+
+
+def http_date(value: str | None) -> str | None:
+    # Convert an ISO 8601 timestamp to an RFC 7231 HTTP date string.
+    parsed = parse_iso_datetime(value)
+    if parsed is None:
+        return None
+    return format_datetime(parsed, usegmt=True)
+
+
+def validate_bucket_name(bucket_name: str) -> None:
+    # Validate bucket name using a simplified S3-like rule set.
+    if not bucket_name:
+        raise InvalidBucketNameError("Bucket name cannot be empty.")
+
+    if len(bucket_name) < 3 or len(bucket_name) > 63:
+        raise InvalidBucketNameError("Bucket name length must be between 3 and 63 characters.")
+
+    if not _BUCKET_NAME_PATTERN.fullmatch(bucket_name):
+        raise InvalidBucketNameError(
+            "Bucket name must contain only lowercase letters, numbers, dots, and hyphens."
+        )
+
+    if ".." in bucket_name or ".-" in bucket_name or "-." in bucket_name:
+        raise InvalidBucketNameError("Bucket name contains an invalid sequence.")
+
+    if bucket_name.startswith(".") or bucket_name.endswith("."):
+        raise InvalidBucketNameError("Bucket name cannot start or end with a dot.")
+
+    if bucket_name.startswith("-") or bucket_name.endswith("-"):
+        raise InvalidBucketNameError("Bucket name cannot start or end with a hyphen.")
+
+
+def validate_object_key(object_key: str) -> None:
+    # Validate object key and reject obviously dangerous values.
+    if not object_key:
+        raise InvalidObjectKeyError("Object key cannot be empty.")
+
+    normalized = object_key.strip()
+    if not normalized:
+        raise InvalidObjectKeyError("Object key cannot be blank.")
+
+    if normalized.startswith("/"):
+        raise InvalidObjectKeyError("Object key cannot start with '/'.")
+
+    parts = normalized.split("/")
+    for part in parts:
+        if part in {"", ".", ".."}:
+            raise InvalidObjectKeyError("Object key contains an invalid path segment.")
+
+    if "\x00" in normalized:
+        raise InvalidObjectKeyError("Object key contains a null byte.")
+
+
+def ensure_path_within_base(base_path: Path, target_path: Path) -> None:
+    # Ensure that the target path stays within the configured base directory.
+    base_resolved = base_path.resolve()
+    target_resolved = target_path.resolve()
+
+    if base_resolved not in {target_resolved, *target_resolved.parents}:
+        raise InvalidObjectKeyError("Resolved path escapes the storage base directory.")
+
+
+def bucket_path(base_dir: Path, bucket_name: str) -> Path:
+    # Build a safe bucket path.
+    validate_bucket_name(bucket_name)
+    path = base_dir / bucket_name
+    ensure_path_within_base(base_dir, path)
+    return path
+
+
+def object_path(base_dir: Path, bucket_name: str, object_key: str) -> Path:
+    # Build a safe object path.
+    validate_bucket_name(bucket_name)
+    validate_object_key(object_key)
+
+    path = base_dir / bucket_name / Path(object_key)
+    ensure_path_within_base(base_dir / bucket_name, path)
+    return path
+
+
+def metadata_dir_path(base_dir: Path, bucket_name: str) -> Path:
+    # Build the metadata directory path for a bucket.
+    path = bucket_path(base_dir, bucket_name) / ".meta"
+    ensure_path_within_base(base_dir / bucket_name, path)
+    return path
+
+
+def metadata_file_path(base_dir: Path, bucket_name: str, object_key: str) -> Path:
+    # Build a safe metadata file path for an object.
+    validate_object_key(object_key)
+
+    safe_name = object_key.replace("/", "__")
+    path = metadata_dir_path(base_dir, bucket_name) / f"{safe_name}.json"
+    ensure_path_within_base(base_dir / bucket_name, path)
+    return path
+
+
+def compute_etag(data: bytes) -> str:
+    # Compute a simple ETag using MD5.
+    return hashlib.md5(data).hexdigest()  # noqa: S324
+
+
+def write_json(file_path: Path, payload: dict[str, Any]) -> None:
+    # Write JSON content to disk.
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    with file_path.open("w", encoding="utf-8") as file:
+        json.dump(payload, file, indent=2, ensure_ascii=False)
+
+
+def read_json(file_path: Path) -> dict[str, Any]:
+    # Read JSON content from disk.
+    with file_path.open("r", encoding="utf-8") as file:
+        return json.load(file)  # type: ignore
+
+
+def _xml_bytes(root: Element) -> bytes:
+    # Serialize an XML tree with a standard XML declaration.
+    body = tostring(root, encoding="utf-8", xml_declaration=True)
+    return body  # type: ignore
+
+
+def build_list_buckets_xml(buckets: list[dict[str, Any]]) -> bytes:
+    # Build a minimal S3-style XML response for bucket listing.
+    root = Element("ListAllMyBucketsResult")
+    owner = SubElement(root, "Owner")
+    SubElement(owner, "ID").text = "tiny-object-storage"
+    SubElement(owner, "DisplayName").text = "tiny-object-storage"
+
+    buckets_el = SubElement(root, "Buckets")
+    for bucket in buckets:
+        bucket_el = SubElement(buckets_el, "Bucket")
+        SubElement(bucket_el, "Name").text = bucket["name"]
+        if bucket.get("created_at"):
+            created = parse_iso_datetime(bucket["created_at"])
+            if created is not None:
+                SubElement(bucket_el, "CreationDate").text = created.isoformat().replace(
+                    "+00:00", "Z"
+                )
+
+    return _xml_bytes(root)
+
+
+def build_list_objects_v2_xml(
+    bucket_name: str,
+    objects: list[dict[str, Any]],
+    prefix: str = "",
+    max_keys: int = 1000,
+    is_truncated: bool = False,
+) -> bytes:
+    # Build a minimal S3 ListObjectsV2 XML response.
+    root = Element("ListBucketResult")
+    root.set("xmlns", "http://s3.amazonaws.com/doc/2006-03-01/")
+
+    SubElement(root, "Name").text = bucket_name
+    SubElement(root, "Prefix").text = prefix
+    SubElement(root, "KeyCount").text = str(len(objects))
+    SubElement(root, "MaxKeys").text = str(max_keys)
+    SubElement(root, "IsTruncated").text = "true" if is_truncated else "false"
+
+    for item in objects:
+        contents = SubElement(root, "Contents")
+        SubElement(contents, "Key").text = item["object_key"]
+
+        updated = parse_iso_datetime(item.get("updated_at") or item.get("created_at"))
+        if updated is not None:
+            SubElement(contents, "LastModified").text = updated.isoformat().replace("+00:00", "Z")
+        else:
+            SubElement(contents, "LastModified").text = utc_now_iso().replace("+00:00", "Z")
+
+        SubElement(contents, "ETag").text = f"\"{item['etag']}\""
+        SubElement(contents, "Size").text = str(item["size"])
+        SubElement(contents, "StorageClass").text = "STANDARD"
+
+    return _xml_bytes(root)

tiny_object_storage/logging_config.py

@@ -0,0 +1,73 @@
+import logging
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+LOG_FORMAT = "%(asctime)s | %(levelname)s | %(name)s | %(message)s"
+DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+
+def _build_formatter() -> logging.Formatter:
+    # Create a shared formatter for all handlers.
+    return logging.Formatter(fmt=LOG_FORMAT, datefmt=DATE_FORMAT)
+
+
+def _build_console_handler(log_level: str) -> logging.Handler:
+    # Create console log handler.
+    handler = logging.StreamHandler()
+    handler.setLevel(log_level.upper())
+    handler.setFormatter(_build_formatter())
+    return handler
+
+
+def _build_rotating_file_handler(file_path: Path, log_level: str) -> logging.Handler:
+    # Create a rotating file handler.
+    handler = RotatingFileHandler(
+        filename=file_path,
+        maxBytes=5 * 1024 * 1024,
+        backupCount=5,
+        encoding="utf-8",
+    )
+    handler.setLevel(log_level.upper())
+    handler.setFormatter(_build_formatter())
+    return handler
+
+
+def _build_error_file_handler(file_path: Path) -> logging.Handler:
+    # Create a dedicated error log file handler.
+    handler = RotatingFileHandler(
+        filename=file_path,
+        maxBytes=5 * 1024 * 1024,
+        backupCount=5,
+        encoding="utf-8",
+    )
+    handler.setLevel(logging.ERROR)
+    handler.setFormatter(_build_formatter())
+    return handler
+
+
+def configure_logging(log_dir: Path, log_level: str) -> None:
+    # Configure root logger once for the entire application.
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    root_logger = logging.getLogger()
+    if root_logger.handlers:
+        return
+
+    root_logger.setLevel(logging.DEBUG)
+
+    server_log_path = log_dir / "server.log"
+    error_log_path = log_dir / "error.log"
+
+    handlers = [
+        _build_console_handler(log_level=log_level),
+        _build_rotating_file_handler(file_path=server_log_path, log_level=log_level),
+        _build_error_file_handler(file_path=error_log_path),
+    ]
+
+    for handler in handlers:
+        root_logger.addHandler(handler)
+
+
+def get_logger(name: str) -> logging.Logger:
+    # Return a named logger instance.
+    return logging.getLogger(name)

tiny_object_storage/main.py

@@ -0,0 +1,199 @@
+import time
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, Request
+from fastapi.responses import Response
+
+from tiny_object_storage.api.buckets import router as buckets_router
+from tiny_object_storage.api.health import router as health_router
+from tiny_object_storage.api.objects import router as objects_router
+from tiny_object_storage.config import get_settings
+from tiny_object_storage.core.errors import (
+    BucketAlreadyExistsError,
+    BucketNotEmptyError,
+    BucketNotFoundError,
+    InvalidBucketNameError,
+    InvalidObjectKeyError,
+    ObjectNotFoundError,
+)
+from tiny_object_storage.logging_config import configure_logging, get_logger
+from tiny_object_storage.services.bucket_service import BucketService
+from tiny_object_storage.services.object_service import ObjectService
+from tiny_object_storage.storage.filesystem import FilesystemStorage
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    # Initialize application resources during startup.
+    settings = get_settings()
+    configure_logging(log_dir=settings.log_dir, log_level=settings.log_level)
+
+    storage = FilesystemStorage(base_dir=settings.data_dir)
+    bucket_service = BucketService(storage=storage)
+    object_service = ObjectService(storage=storage)
+
+    app.state.settings = settings
+    app.state.logger = get_logger("tiny_object_storage.main")
+    app.state.storage = storage
+    app.state.bucket_service = bucket_service
+    app.state.object_service = object_service
+
+    app.state.logger.info("Starting %s", settings.app_name)
+    app.state.logger.info("Host: %s", settings.host)
+    app.state.logger.info("Port: %s", settings.port)
+    app.state.logger.info("Data directory: %s", settings.data_dir)
+    app.state.logger.info("Log directory: %s", settings.log_dir)
+    app.state.logger.info("Log level: %s", settings.log_level)
+    app.state.logger.info("Dev mode: %s", settings.dev_mode)
+
+    yield
+
+    app.state.logger.info("Shutting down %s", settings.app_name)
+
+
+app = FastAPI(
+    title="tiny-object-storage",
+    version="0.1.0",
+    summary="A lightweight S3-style object storage server.",
+    description=(
+        "tiny-object-storage is a lightweight S3-style object storage server for local "
+        "development, testing, and learning. It provides bucket and object operations, "
+        "file-based persistence, structured logging, and OpenAPI documentation."
+    ),
+    lifespan=lifespan,
+)
+
+
+@app.middleware("http")
+async def request_logging_middleware(
+    request: Request, call_next: Callable[[Request], Awaitable[Response]]
+) -> Response:
+    # Log incoming requests and their response status.
+    logger = get_logger("tiny_object_storage.api")
+    started_at = time.perf_counter()
+
+    try:
+        response = await call_next(request)
+    except Exception:
+        duration_ms = (time.perf_counter() - started_at) * 1000
+        logger.exception(
+            "Unhandled request error method=%s path=%s duration_ms=%.2f",
+            request.method,
+            request.url.path,
+            duration_ms,
+        )
+        raise
+
+    duration_ms = (time.perf_counter() - started_at) * 1000
+    logger.info(
+        "Request completed method=%s path=%s status_code=%s duration_ms=%.2f",
+        request.method,
+        request.url.path,
+        response.status_code,
+        duration_ms,
+    )
+    return response
+
+
+def _build_xml_error(code: str, message: str) -> str:
+    return f"""<?xml version="1.0" encoding="UTF-8"?>
+<Error>
+    <Code>{code}</Code>
+    <Message>{message}</Message>
+</Error>"""
+
+
+@app.exception_handler(InvalidBucketNameError)
+async def invalid_bucket_name_handler(request: Request, exc: InvalidBucketNameError) -> Response:
+    logger = get_logger("tiny_object_storage.main")
+    logger.warning("Invalid bucket name path=%s message=%s", request.url.path, str(exc))
+    return Response(
+        status_code=400,
+        content=_build_xml_error("InvalidBucketName", str(exc)),
+        media_type="application/xml",
+    )
+
+
+@app.exception_handler(InvalidObjectKeyError)
+async def invalid_object_key_handler(request: Request, exc: InvalidObjectKeyError) -> Response:
+    logger = get_logger("tiny_object_storage.main")
+    logger.warning("Invalid object key path=%s message=%s", request.url.path, str(exc))
+    return Response(
+        status_code=400,
+        content=_build_xml_error("InvalidObjectKey", str(exc)),
+        media_type="application/xml",
+    )
+
+
+@app.exception_handler(BucketAlreadyExistsError)
+async def bucket_already_exists_handler(
+    request: Request, exc: BucketAlreadyExistsError
+) -> Response:
+    logger = get_logger("tiny_object_storage.main")
+    logger.warning("Bucket already exists path=%s message=%s", request.url.path, str(exc))
+    return Response(
+        status_code=409,
+        content=_build_xml_error("BucketAlreadyExists", str(exc)),
+        media_type="application/xml",
+    )
+
+
+@app.exception_handler(BucketNotFoundError)
+async def bucket_not_found_handler(request: Request, exc: BucketNotFoundError) -> Response:
+    logger = get_logger("tiny_object_storage.main")
+    logger.warning("Bucket not found path=%s message=%s", request.url.path, str(exc))
+    return Response(
+        status_code=404,
+        content=_build_xml_error("NoSuchBucket", str(exc)),
+        media_type="application/xml",
+    )
+
+
+@app.exception_handler(BucketNotEmptyError)
+async def bucket_not_empty_handler(request: Request, exc: BucketNotEmptyError) -> Response:
+    logger = get_logger("tiny_object_storage.main")
+    logger.warning("Bucket not empty path=%s message=%s", request.url.path, str(exc))
+    return Response(
+        status_code=409,
+        content=_build_xml_error("BucketNotEmpty", str(exc)),
+        media_type="application/xml",
+    )
+
+
+@app.exception_handler(ObjectNotFoundError)
+async def object_not_found_handler(request: Request, exc: ObjectNotFoundError) -> Response:
+    logger = get_logger("tiny_object_storage.main")
+    logger.warning("Object not found path=%s message=%s", request.url.path, str(exc))
+    return Response(
+        status_code=404,
+        content=_build_xml_error("NoSuchKey", str(exc)),
+        media_type="application/xml",
+    )
+
+
+@app.exception_handler(ValueError)
+async def value_error_handler(request: Request, exc: ValueError) -> Response:
+    logger = get_logger("tiny_object_storage.main")
+    logger.warning("Invalid request value path=%s message=%s", request.url.path, str(exc))
+    return Response(
+        status_code=400,
+        content=_build_xml_error("InvalidArgument", str(exc)),
+        media_type="application/xml",
+    )
+
+
+@app.exception_handler(Exception)
+async def unhandled_exception_handler(request: Request, exc: Exception) -> Response:
+    logger = get_logger("tiny_object_storage.main")
+    logger.exception("Unhandled application error path=%s", request.url.path)
+    return Response(
+        status_code=500,
+        content=_build_xml_error("InternalError", "An unexpected error occurred."),
+        media_type="application/xml",
+    )
+
+
+app.include_router(health_router)
+app.include_router(buckets_router)
+app.include_router(objects_router)

tiny_object_storage/models/bucket.py

@@ -0,0 +1,10 @@
+from pydantic import BaseModel, Field
+
+
+class BucketInfo(BaseModel):
+    # Represent bucket metadata returned by the API.
+    name: str = Field(..., description="Bucket name.")
+    created_at: str | None = Field(
+        default=None,
+        description="Bucket creation timestamp in ISO 8601 format.",
+    )

tiny_object_storage/models/object_info.py

@@ -0,0 +1,18 @@
+from pydantic import BaseModel, Field
+
+
+class ObjectInfo(BaseModel):
+    # Represent object metadata returned by the API.
+    bucket_name: str = Field(..., description="Bucket name.")
+    object_key: str = Field(..., description="Object key.")
+    size: int = Field(..., description="Object size in bytes.")
+    content_type: str = Field(..., description="Object content type.")
+    etag: str = Field(..., description="Entity tag for the stored object.")
+    created_at: str | None = Field(
+        default=None,
+        description="Object creation timestamp in ISO 8601 format.",
+    )
+    updated_at: str | None = Field(
+        default=None,
+        description="Object update timestamp in ISO 8601 format.",
+    )

tiny_object_storage/models/responses.py

@@ -0,0 +1,48 @@
+from pydantic import BaseModel, Field
+
+from tiny_object_storage.models.bucket import BucketInfo
+from tiny_object_storage.models.object_info import ObjectInfo
+
+
+class HealthResponse(BaseModel):
+    # Represent healthcheck response payload.
+    status: str = Field(..., description="Service status.")
+    app_name: str = Field(..., description="Application name.")
+    data_dir: str = Field(..., description="Configured storage data directory.")
+    log_dir: str = Field(..., description="Configured log directory.")
+    log_level: str = Field(..., description="Configured log level.")
+    dev_mode: bool = Field(..., description="Whether dev mode is enabled.")
+
+
+class MessageResponse(BaseModel):
+    # Represent a generic API message response.
+    message: str = Field(..., description="Human-readable status message.")
+
+
+class ErrorResponse(BaseModel):
+    # Represent a standardized error response.
+    error: str = Field(..., description="Machine-readable error code.")
+    message: str = Field(..., description="Human-readable error message.")
+
+
+class BucketsListResponse(BaseModel):
+    # Represent bucket listing response.
+    buckets: list[BucketInfo] = Field(..., description="List of buckets.")
+
+
+class ObjectsListResponse(BaseModel):
+    # Represent object listing response.
+    bucket_name: str = Field(..., description="Bucket name.")
+    objects: list[ObjectInfo] = Field(..., description="List of objects.")
+
+
+class BucketCreatedResponse(BaseModel):
+    # Represent bucket creation response.
+    message: str = Field(..., description="Human-readable status message.")
+    bucket: BucketInfo = Field(..., description="Created bucket metadata.")
+
+
+class ObjectStoredResponse(BaseModel):
+    # Represent object upload response.
+    message: str = Field(..., description="Human-readable status message.")
+    object: ObjectInfo = Field(..., description="Stored object metadata.")

tiny_object_storage/services/bucket_service.py

@@ -0,0 +1,50 @@
+from typing import Any
+
+from tiny_object_storage.logging_config import get_logger
+from tiny_object_storage.storage.base import BaseStorage
+
+
+class BucketService:
+    # Handle bucket-related business logic.
+
+    def __init__(self, storage: BaseStorage):
+        # Store the configured storage backend.
+        self.storage = storage
+        self.logger = get_logger("tiny_object_storage.services.bucket")
+
+    def create_bucket(self, bucket_name: str) -> dict[str, Any]:
+        # Create a bucket and return its metadata.
+        self.logger.info("Creating bucket bucket=%s", bucket_name)
+        self.storage.create_bucket(bucket_name)
+
+        for bucket in self.storage.list_buckets():
+            if bucket["name"] == bucket_name:
+                self.logger.info("Bucket created bucket=%s", bucket_name)
+                return bucket
+
+        result = {
+            "name": bucket_name,
+            "created_at": None,
+        }
+        self.logger.info("Bucket created bucket=%s", bucket_name)
+        return result
+
+    def delete_bucket(self, bucket_name: str) -> None:
+        # Delete an existing bucket.
+        self.logger.info("Deleting bucket bucket=%s", bucket_name)
+        self.storage.delete_bucket(bucket_name)
+        self.logger.info("Bucket deleted bucket=%s", bucket_name)
+
+    def list_buckets(self) -> list[dict[str, Any]]:
+        # Return all buckets from the storage backend.
+        self.logger.info("Listing buckets")
+        buckets = self.storage.list_buckets()
+        self.logger.info("Buckets listed count=%s", len(buckets))
+        return buckets
+
+    def bucket_exists(self, bucket_name: str) -> bool:
+        # Return whether the given bucket exists.
+        self.logger.debug("Checking bucket existence bucket=%s", bucket_name)
+        exists = self.storage.bucket_exists(bucket_name)
+        self.logger.debug("Bucket existence checked bucket=%s exists=%s", bucket_name, exists)
+        return exists