tiny-object-storage 0.1.1__tar.gz

tiny_object_storage-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ehsan Bitaraf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tiny_object_storage-0.1.1/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: tiny-object-storage
+Version: 0.1.1
+Summary: A lightweight S3-compatible object storage server for local development and learning.
+Author: Ehsan Bitaraf
+License: MIT
+Project-URL: Homepage, https://github.com/EhsanBitaraf/tiny-object-storage
+Project-URL: Repository, https://github.com/EhsanBitaraf/tiny-object-storage
+Project-URL: Bug Tracker, https://github.com/EhsanBitaraf/tiny-object-storage/issues
+Keywords: s3,object-storage,minio,aws-s3,emulator,s3-compatible,mock,testing,fastapi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi<1.0.0,>=0.115.0
+Requires-Dist: uvicorn[standard]<1.0.0,>=0.30.0
+Requires-Dist: pydantic<3.0.0,>=2.8.0
+Requires-Dist: pydantic-settings<3.0.0,>=2.4.0
+Requires-Dist: python-dotenv<2.0.0,>=1.0.1
+Requires-Dist: python-multipart<1.0.0,>=0.0.9
+Provides-Extra: dev
+Requires-Dist: pytest<9.0.0,>=8.3.0; extra == "dev"
+Requires-Dist: pytest-cov<6.0.0,>=5.0.0; extra == "dev"
+Requires-Dist: httpx<1.0.0,>=0.27.0; extra == "dev"
+Requires-Dist: ruff<1.0.0,>=0.6.0; extra == "dev"
+Requires-Dist: mypy<2.0.0,>=1.11.0; extra == "dev"
+Requires-Dist: bandit<2.0.0,>=1.7.9; extra == "dev"
+Requires-Dist: safety<4.0.0,>=3.2.0; extra == "dev"
+Requires-Dist: pre-commit<4.0.0,>=3.8.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+  <img src="assets/logo.png" alt="tiny-object-storage logo" width="180" height="auto" />
+  <h1>🪣 tiny-object-storage</h1>
+  <p><i>A lightweight, S3-compatible object storage server for local development, testing, and learning.</i></p>
+
+[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg?logo=python&logoColor=white)](https://www.python.org)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-009688.svg?logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Mypy Strict](https://img.shields.io/badge/mypy-strict-success.svg)](https://mypy.readthedocs.io/en/stable/)
+[![Security: Bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
+[![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+[![Coverage: 91%](https://img.shields.io/badge/Coverage-91%25-brightgreen.svg)](https://pytest-cov.readthedocs.io/en/latest/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+</div>
+
+---
+
+## 📖 Overview
+
+`tiny-object-storage` is a fast, minimalistic object storage server written in Python using FastAPI. It acts as a local emulator that mimics the core functionality of Amazon S3, allowing developers to test S3-integrated applications locally without relying on external cloud services or heavy containers like MinIO.
+
+## ✨ Features
+
+- **S3 Compatibility**: Supports core S3 XML responses and basic HTTP methods (`GET`, `PUT`, `HEAD`, `DELETE`).
+- **Bucket Management**: Create, list, and delete buckets.
+- **Object Operations**: Upload, download, metadata lookup, listing (`list-type=2`), and deletion.
+- **Persistent Storage**: Filesystem-based persistence with dedicated metadata and data separation.
+- **Developer Experience**: Interactive Swagger UI and OpenAPI schema built-in.
+- **Enterprise Code Quality**: Enforced static typing (Mypy strict), linting (Ruff), and security analysis (Bandit).
+- **Flexible Configuration**: Configurable via CLI arguments, environment variables, or `.env` files.
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+**From PyPI (Recommended)**
+Install the package globally or in a virtual environment using `pip`:
+
+```bash
+pip install tiny-object-storage
+```
+
+**From Source (Development)**
+Clone the repository and install it in a virtual environment:
+
+```bash
+git clone https://github.com/EhsanBitaraf/tiny-object-storage.git
+cd tiny-object-storage
+python -m venv .venv
+
+# On Linux/macOS:
+source .venv/bin/activate
+# On Windows:
+.venv\Scripts\activate
+
+# Install the application and development dependencies
+pip install -e ".[dev]"
+```
+
+### Running the Server
+
+Start the server using the built-in CLI:
+
+```bash
+tos-server
+```
+
+Or run it directly with `uvicorn`:
+```bash
+uvicorn tiny_object_storage.main:app --reload --host 0.0.0.0 --port 9000
+```
+
+---
+
+## ⚙️ Configuration
+
+The server reads configuration in the following priority (highest to lowest):
+1. **Command-line arguments**
+2. **Environment variables**
+3. **`.env` file**
+
+### CLI Usage Examples
+
+```bash
+# View all available options
+tos-server --help
+
+# Load from a specific .env file
+tos-server --env-file .env.custom
+
+# Override host and port
+tos-server --host 127.0.0.1 --port 9001 --reload
+
+# Customize storage directories and log level
+tos-server --data-dir ./storage_data --log-dir ./logs --log-level debug
+```
+
+---
+
+## 🔌 S3 Client Compatibility
+
+`tiny-object-storage` acts as a local emulator and has been successfully verified against the following official SDKs and tools:
+
+- **MinIO Python SDK**
+- **Boto3 (AWS SDK for Python)**
+- **AWS CLI**
+
+> **Note:** For official SDKs to interact locally, configure them with `secure=False` (or `--no-verify-ssl`) and point the `endpoint_url` to `http://127.0.0.1:9000` with any dummy credentials.
+
+Sample scripts for verifying SDK interactions are included in the repository root (e.g., `test_boto3_sdk.py`, `test_minio_sdk.py`).
+
+---
+
+## 🛠 Testing & Code Quality
+
+The project includes an extensive test suite built with `pytest` achieving **100% test pass rate** over 63 edge-case scenarios.
+
+### Running Tests
+
+```bash
+pytest
+```
+*(Optionally, use `pytest --cov=src` to generate a coverage report).*
+
+### Code Quality Tools
+
+We use `pre-commit` to maintain our code quality. The suite includes:
+- **Ruff**: For ultra-fast linting and code formatting.
+- **Mypy**: For strict static type checking.
+- **Bandit**: For security vulnerability scanning.
+
+To run checks manually on all files:
+```bash
+pre-commit run --all-files
+```
+
+---
+
+## 🌐 API Endpoints (Examples)
+
+After starting the server, visit `/docs` for the interactive Swagger UI. Below are standard `curl` examples targeting common S3 actions:
+
+**Health check**
+```bash
+curl http://127.0.0.1:9000/health
+```
+
+**Create a bucket**
+```bash
+curl -X PUT http://127.0.0.1:9000/photos
+```
+
+**Upload an object**
+```bash
+curl -X PUT --data-binary @"cat.jpg" http://127.0.0.1:9000/photos/cat.jpg
+```
+
+**Download an object**
+```bash
+curl http://127.0.0.1:9000/photos/cat.jpg --output cat.jpg
+```
+
+**List objects (S3 Format)**
+```bash
+curl "http://127.0.0.1:9000/photos?list-type=2"
+```
+
+**Debug endpoints (JSON format)**
+```bash
+curl http://127.0.0.1:9000/_debug/buckets
+curl http://127.0.0.1:9000/_debug/photos
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome and highly appreciated! Please review our [Contributing Guidelines](CONTRIBUTING.md) to get started. By participating in this project, you agree to abide by the [Code of Conduct](.github/CODE_OF_CONDUCT.md).
+
+## 🔒 Security
+
+For instructions on reporting security vulnerabilities, please refer to our [Security Policy](SECURITY.md).
+
+## 📜 License
+
+This project is licensed under the MIT License - see the `LICENSE` file for details.

tiny_object_storage-0.1.1/README.md

@@ -0,0 +1,189 @@
+<div align="center">
+  <img src="assets/logo.png" alt="tiny-object-storage logo" width="180" height="auto" />
+  <h1>🪣 tiny-object-storage</h1>
+  <p><i>A lightweight, S3-compatible object storage server for local development, testing, and learning.</i></p>
+
+[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg?logo=python&logoColor=white)](https://www.python.org)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-009688.svg?logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Mypy Strict](https://img.shields.io/badge/mypy-strict-success.svg)](https://mypy.readthedocs.io/en/stable/)
+[![Security: Bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
+[![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+[![Coverage: 91%](https://img.shields.io/badge/Coverage-91%25-brightgreen.svg)](https://pytest-cov.readthedocs.io/en/latest/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+</div>
+
+---
+
+## 📖 Overview
+
+`tiny-object-storage` is a fast, minimalistic object storage server written in Python using FastAPI. It acts as a local emulator that mimics the core functionality of Amazon S3, allowing developers to test S3-integrated applications locally without relying on external cloud services or heavy containers like MinIO.
+
+## ✨ Features
+
+- **S3 Compatibility**: Supports core S3 XML responses and basic HTTP methods (`GET`, `PUT`, `HEAD`, `DELETE`).
+- **Bucket Management**: Create, list, and delete buckets.
+- **Object Operations**: Upload, download, metadata lookup, listing (`list-type=2`), and deletion.
+- **Persistent Storage**: Filesystem-based persistence with dedicated metadata and data separation.
+- **Developer Experience**: Interactive Swagger UI and OpenAPI schema built-in.
+- **Enterprise Code Quality**: Enforced static typing (Mypy strict), linting (Ruff), and security analysis (Bandit).
+- **Flexible Configuration**: Configurable via CLI arguments, environment variables, or `.env` files.
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+**From PyPI (Recommended)**
+Install the package globally or in a virtual environment using `pip`:
+
+```bash
+pip install tiny-object-storage
+```
+
+**From Source (Development)**
+Clone the repository and install it in a virtual environment:
+
+```bash
+git clone https://github.com/EhsanBitaraf/tiny-object-storage.git
+cd tiny-object-storage
+python -m venv .venv
+
+# On Linux/macOS:
+source .venv/bin/activate
+# On Windows:
+.venv\Scripts\activate
+
+# Install the application and development dependencies
+pip install -e ".[dev]"
+```
+
+### Running the Server
+
+Start the server using the built-in CLI:
+
+```bash
+tos-server
+```
+
+Or run it directly with `uvicorn`:
+```bash
+uvicorn tiny_object_storage.main:app --reload --host 0.0.0.0 --port 9000
+```
+
+---
+
+## ⚙️ Configuration
+
+The server reads configuration in the following priority (highest to lowest):
+1. **Command-line arguments**
+2. **Environment variables**
+3. **`.env` file**
+
+### CLI Usage Examples
+
+```bash
+# View all available options
+tos-server --help
+
+# Load from a specific .env file
+tos-server --env-file .env.custom
+
+# Override host and port
+tos-server --host 127.0.0.1 --port 9001 --reload
+
+# Customize storage directories and log level
+tos-server --data-dir ./storage_data --log-dir ./logs --log-level debug
+```
+
+---
+
+## 🔌 S3 Client Compatibility
+
+`tiny-object-storage` acts as a local emulator and has been successfully verified against the following official SDKs and tools:
+
+- **MinIO Python SDK**
+- **Boto3 (AWS SDK for Python)**
+- **AWS CLI**
+
+> **Note:** For official SDKs to interact locally, configure them with `secure=False` (or `--no-verify-ssl`) and point the `endpoint_url` to `http://127.0.0.1:9000` with any dummy credentials.
+
+Sample scripts for verifying SDK interactions are included in the repository root (e.g., `test_boto3_sdk.py`, `test_minio_sdk.py`).
+
+---
+
+## 🛠 Testing & Code Quality
+
+The project includes an extensive test suite built with `pytest` achieving **100% test pass rate** over 63 edge-case scenarios.
+
+### Running Tests
+
+```bash
+pytest
+```
+*(Optionally, use `pytest --cov=src` to generate a coverage report).*
+
+### Code Quality Tools
+
+We use `pre-commit` to maintain our code quality. The suite includes:
+- **Ruff**: For ultra-fast linting and code formatting.
+- **Mypy**: For strict static type checking.
+- **Bandit**: For security vulnerability scanning.
+
+To run checks manually on all files:
+```bash
+pre-commit run --all-files
+```
+
+---
+
+## 🌐 API Endpoints (Examples)
+
+After starting the server, visit `/docs` for the interactive Swagger UI. Below are standard `curl` examples targeting common S3 actions:
+
+**Health check**
+```bash
+curl http://127.0.0.1:9000/health
+```
+
+**Create a bucket**
+```bash
+curl -X PUT http://127.0.0.1:9000/photos
+```
+
+**Upload an object**
+```bash
+curl -X PUT --data-binary @"cat.jpg" http://127.0.0.1:9000/photos/cat.jpg
+```
+
+**Download an object**
+```bash
+curl http://127.0.0.1:9000/photos/cat.jpg --output cat.jpg
+```
+
+**List objects (S3 Format)**
+```bash
+curl "http://127.0.0.1:9000/photos?list-type=2"
+```
+
+**Debug endpoints (JSON format)**
+```bash
+curl http://127.0.0.1:9000/_debug/buckets
+curl http://127.0.0.1:9000/_debug/photos
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome and highly appreciated! Please review our [Contributing Guidelines](CONTRIBUTING.md) to get started. By participating in this project, you agree to abide by the [Code of Conduct](.github/CODE_OF_CONDUCT.md).
+
+## 🔒 Security
+
+For instructions on reporting security vulnerabilities, please refer to our [Security Policy](SECURITY.md).
+
+## 📜 License
+
+This project is licensed under the MIT License - see the `LICENSE` file for details.

tiny_object_storage-0.1.1/pyproject.toml

@@ -0,0 +1,110 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tiny-object-storage"
+version = "0.1.1"
+description = "A lightweight S3-compatible object storage server for local development and learning."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+  { name = "Ehsan Bitaraf" }
+]
+keywords = [
+    "s3",
+    "object-storage",
+    "minio",
+    "aws-s3",
+    "emulator",
+    "s3-compatible",
+    "mock",
+    "testing",
+    "fastapi"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Internet :: WWW/HTTP",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+  "fastapi>=0.115.0,<1.0.0",
+  "uvicorn[standard]>=0.30.0,<1.0.0",
+  "pydantic>=2.8.0,<3.0.0",
+  "pydantic-settings>=2.4.0,<3.0.0",
+  "python-dotenv>=1.0.1,<2.0.0",
+  "python-multipart>=0.0.9,<1.0.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/EhsanBitaraf/tiny-object-storage"
+Repository = "https://github.com/EhsanBitaraf/tiny-object-storage"
+"Bug Tracker" = "https://github.com/EhsanBitaraf/tiny-object-storage/issues"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.3.0,<9.0.0",
+  "pytest-cov>=5.0.0,<6.0.0",
+  "httpx>=0.27.0,<1.0.0",
+  "ruff>=0.6.0,<1.0.0",
+  "mypy>=1.11.0,<2.0.0",
+  "bandit>=1.7.9,<2.0.0",
+  "safety>=3.2.0,<4.0.0",
+  "pre-commit>=3.8.0,<4.0.0"
+]
+
+[project.scripts]
+tos-server = "tiny_object_storage.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "UP", # pyupgrade
+    "B",  # flake8-bugbear
+    "C4", # flake8-comprehensions
+    "SIM",# flake8-simplify
+]
+ignore = []
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true
+disallow_untyped_decorators = false
+exclude = ["venv", ".venv"]
+
+[tool.bandit]
+exclude_dirs = ["tests", "venv", ".venv"]
+skips = ["B104", "B405", "B324", "B404", "B603", "B105", "B106"]

tiny_object_storage-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tiny_object_storage-0.1.1/src/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-0.1.1/src/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)