auditlog-fastapi 0.2.0__tar.gz

auditlog_fastapi-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Elgamal
+
+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.

auditlog_fastapi-0.2.0/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: auditlog-fastapi
+Version: 0.2.0
+Summary: Production-grade, reusable audit logging for FastAPI applications.
+License-File: LICENSE
+Author: Ahmed Elgamal
+Author-email: ahmed@example.com
+Requires-Python: >=3.11,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: all
+Provides-Extra: asyncpg
+Provides-Extra: mongodb
+Provides-Extra: sqlalchemy
+Provides-Extra: sqlmodel
+Provides-Extra: tortoise
+Requires-Dist: aiomysql ; extra == "sqlalchemy" or extra == "tortoise" or extra == "sqlmodel" or extra == "all"
+Requires-Dist: aiosqlite ; extra == "sqlalchemy" or extra == "tortoise" or extra == "sqlmodel" or extra == "all"
+Requires-Dist: asyncpg (>=0.29) ; extra == "sqlalchemy" or extra == "tortoise" or extra == "sqlmodel" or extra == "asyncpg" or extra == "all"
+Requires-Dist: beanie (>=1.20) ; extra == "mongodb" or extra == "all"
+Requires-Dist: fastapi (>=0.100.0)
+Requires-Dist: motor (>=3.0) ; extra == "mongodb" or extra == "all"
+Requires-Dist: pydantic (>=2.0,<3.0)
+Requires-Dist: pydantic-settings (>=2.0)
+Requires-Dist: sqlalchemy[asyncio] (>=2.0.0) ; extra == "sqlalchemy" or extra == "all"
+Requires-Dist: sqlmodel (>=0.0.14) ; extra == "sqlmodel" or extra == "all"
+Requires-Dist: tortoise-orm (>=0.20) ; extra == "tortoise" or extra == "all"
+Description-Content-Type: text/markdown
+
+# auditlog-fastapi
+
+Production-grade, reusable audit logging for FastAPI applications.
+
+## Features
+
+- **Multi-ORM Support:** SQLAlchemy 2 (async), Tortoise ORM, SQLModel, Beanie (MongoDB), and raw asyncpg.
+- **Flexible Storage:** PostgreSQL, MySQL, MariaDB, SQLite, and MongoDB.
+- **Explicit Configuration:** Clean API with `AuditConfig` and `configure()`.
+- **Middleware Integration:** Capture request/response data automatically.
+- **PII Masking:** Redact sensitive fields from logs.
+- **Context Helpers:** Enrich audit logs from route handlers.
+- **Lifespan Integration:** Automatic startup/shutdown of database connections.
+- **Async & Non-blocking:** Built with performance and safety in mind.
+
+## Installation
+
+```bash
+# Basic install
+pip install auditlog-fastapi
+
+# With SQLAlchemy support (Postgres, MySQL, SQLite)
+pip install auditlog-fastapi[sqlalchemy]
+
+# With Tortoise ORM support
+pip install auditlog-fastapi[tortoise]
+
+# With SQLModel support
+pip install auditlog-fastapi[sqlmodel]
+
+# With MongoDB (Beanie) support
+pip install auditlog-fastapi[mongodb]
+
+# With raw asyncpg (PostgreSQL only) support
+pip install auditlog-fastapi[asyncpg]
+
+# Everything
+pip install auditlog-fastapi[all]
+```
+
+## Quick Start (SQLAlchemy + SQLite)
+
+```python
+from fastapi import FastAPI
+from fastapi_audit_log import AuditMiddleware, AuditConfig, create_audit_lifespan
+
+# 1. Configure the audit log
+config = AuditConfig(
+    orm="sqlalchemy",
+    dsn="sqlite+aiosqlite:///./audit.db",
+    table_name="audit_logs",
+    auto_create_table=True,
+)
+
+# 2. Create lifespan handler
+app = FastAPI(lifespan=create_audit_lifespan(config))
+
+# 3. Add middleware
+app.add_middleware(
+    AuditMiddleware,
+    log_request_body=True
+)
+
+@app.get("/")
+async def root():
+    return {"message": "Hello World"}
+```
+
+## User Configuration Guide
+
+### SQLAlchemy + PostgreSQL
+
+```python
+config = AuditConfig(
+    orm="sqlalchemy",
+    dsn="postgresql+asyncpg://user:pass@localhost:5432/mydb",
+    table_name="audit_logs",
+    auto_create_table=True,
+    sqlalchemy_pool_size=10,
+    mask_fields=["password", "token"],
+)
+```
+
+### SQLAlchemy + MySQL
+
+```python
+config = AuditConfig(
+    orm="sqlalchemy",
+    dsn="mysql+aiomysql://user:pass@localhost:3306/mydb",
+    auto_create_table=True,
+)
+```
+
+### Tortoise ORM + PostgreSQL
+
+```python
+config = AuditConfig(
+    orm="tortoise",
+    dsn="postgres://user:pass@localhost:5432/mydb",
+    auto_create_table=True,
+)
+```
+
+### MongoDB via Beanie
+
+```python
+config = AuditConfig(
+    orm="beanie",
+    dsn="mongodb://localhost:27017",
+    mongodb_database="myapp",
+    table_name="audit_logs",   # becomes collection name
+)
+```
+
+### Raw asyncpg (PostgreSQL, maximum performance)
+
+```python
+config = AuditConfig(
+    orm="asyncpg",
+    dsn="postgresql://user:pass@localhost:5432/mydb",
+    batch_size=200,
+)
+```
+
+### Using with Alembic (SQLAlchemy only)
+
+```python
+# In alembic/env.py — include audit table in your migrations
+from fastapi_audit_log.db.sqlalchemy_table import AuditBase
+target_metadata = [YourBase.metadata, AuditBase.metadata]
+```
+
+## Enriching Logs from Routes
+
+```python
+from fastapi_audit_log import set_audit_action, set_audit_resource, set_audit_extra
+
+@app.post("/items")
+async def create_item(item_id: str):
+    set_audit_action("item.create")
+    set_audit_resource("item", item_id)
+    set_audit_extra("metadata", {"source": "admin_panel"})
+    return {"status": "ok"}
+```
+
+## Retrieving Audit Logs
+
+`fastapi-audit-log` provides a built-in helper to add a route for querying and filtering your audit logs.
+
+```python
+from fastapi import FastAPI
+from fastapi_audit_log import add_audit_log_routes
+
+app = FastAPI(...)
+
+# Register the GET /audit-logs route
+add_audit_log_routes(
+    app,
+    path="/audit-logs",      # default
+    tags=["Audit Logs"]      # optional tags for OpenAPI
+)
+```
+
+### Filtering and Pagination
+
+The added route supports several query parameters:
+
+*   **Pagination:** `limit` (default 100, max 1000) and `offset` (default 0).
+*   **Filters:** `method`, `path`, `status_code`, `user_id`, and `action`.
+
+Example request:
+`GET /audit-logs?method=POST&status_code=201&limit=20`
+
+## Configuration Reference (AuditConfig)
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `orm` | `str` | **Required** | One of: `sqlalchemy`, `tortoise`, `sqlmodel`, `beanie`, `asyncpg`. |
+| `dsn` | `str` | **Required** | Connection string for the database. |
+| `table_name` | `str` | `"audit_logs"` | Name of the table or collection. |
+| `auto_create_table`| `bool` | `True` | Whether to create the table on startup. |
+| `batch_size` | `int` | `1` | Set > 1 to enable batching (not all backends yet). |
+| `mask_fields` | `list[str]` | `[]` | PII fields to mask in request bodies. |
+| `on_storage_error`| `Callable` | `None` | Optional callback for storage errors. |
+
+## Development and Examples
+
+To run the examples that require a real database (PostgreSQL, MongoDB, MySQL), you can use the provided Docker Compose file:
+
+```bash
+docker-compose up -d
+```
+
+This will start:
+
+- **PostgreSQL** at `localhost:5432` (user: `user`, pass: `pass`, db: `audit_db`)
+- **MongoDB** at `localhost:27017`
+- **MySQL** at `localhost:3306` (user: `user`, pass: `pass`, db: `audit_db`)
+
+### Running the MongoDB Example
+
+```bash
+poetry run python examples/beanie_mongodb_usage.py
+```
+
+### Running the Asyncpg Example
+
+```bash
+poetry run python examples/asyncpg_usage.py
+```
+
+## Future Features
+
+- **Admin UI:** Build a simple web UI for viewing/searching audit logs.
+- **Custom Storage Backends:** Allow users to plug in custom storage backends (e.g., S3, Redis, external APIs).
+- **Event Hooks:** Add hooks for pre/post log processing (e.g., for enrichment, notifications).
+- **Log Export:** Support exporting logs to CSV, JSON, or external log management systems.
+- **Retention Policies:** Add configurable log retention and automatic cleanup.
+- **Multi-Tenancy:** Support tenant-aware logging for SaaS apps.
+- **Security:** Encrypt sensitive log fields at rest, and add role-based access for log viewing.
+- **CLI Tooling:** Provide CLI commands for log inspection, export, and management.
+- **OpenTelemetry Integration:** Integrate with OpenTelemetry for distributed tracing and correlation.
+- **Documentation:** Expand usage examples and add troubleshooting guides.
+
+## License
+
+MIT
+

auditlog_fastapi-0.2.0/README.md

@@ -0,0 +1,227 @@
+# auditlog-fastapi
+
+Production-grade, reusable audit logging for FastAPI applications.
+
+## Features
+
+- **Multi-ORM Support:** SQLAlchemy 2 (async), Tortoise ORM, SQLModel, Beanie (MongoDB), and raw asyncpg.
+- **Flexible Storage:** PostgreSQL, MySQL, MariaDB, SQLite, and MongoDB.
+- **Explicit Configuration:** Clean API with `AuditConfig` and `configure()`.
+- **Middleware Integration:** Capture request/response data automatically.
+- **PII Masking:** Redact sensitive fields from logs.
+- **Context Helpers:** Enrich audit logs from route handlers.
+- **Lifespan Integration:** Automatic startup/shutdown of database connections.
+- **Async & Non-blocking:** Built with performance and safety in mind.
+
+## Installation
+
+```bash
+# Basic install
+pip install auditlog-fastapi
+
+# With SQLAlchemy support (Postgres, MySQL, SQLite)
+pip install auditlog-fastapi[sqlalchemy]
+
+# With Tortoise ORM support
+pip install auditlog-fastapi[tortoise]
+
+# With SQLModel support
+pip install auditlog-fastapi[sqlmodel]
+
+# With MongoDB (Beanie) support
+pip install auditlog-fastapi[mongodb]
+
+# With raw asyncpg (PostgreSQL only) support
+pip install auditlog-fastapi[asyncpg]
+
+# Everything
+pip install auditlog-fastapi[all]
+```
+
+## Quick Start (SQLAlchemy + SQLite)
+
+```python
+from fastapi import FastAPI
+from fastapi_audit_log import AuditMiddleware, AuditConfig, create_audit_lifespan
+
+# 1. Configure the audit log
+config = AuditConfig(
+    orm="sqlalchemy",
+    dsn="sqlite+aiosqlite:///./audit.db",
+    table_name="audit_logs",
+    auto_create_table=True,
+)
+
+# 2. Create lifespan handler
+app = FastAPI(lifespan=create_audit_lifespan(config))
+
+# 3. Add middleware
+app.add_middleware(
+    AuditMiddleware,
+    log_request_body=True
+)
+
+@app.get("/")
+async def root():
+    return {"message": "Hello World"}
+```
+
+## User Configuration Guide
+
+### SQLAlchemy + PostgreSQL
+
+```python
+config = AuditConfig(
+    orm="sqlalchemy",
+    dsn="postgresql+asyncpg://user:pass@localhost:5432/mydb",
+    table_name="audit_logs",
+    auto_create_table=True,
+    sqlalchemy_pool_size=10,
+    mask_fields=["password", "token"],
+)
+```
+
+### SQLAlchemy + MySQL
+
+```python
+config = AuditConfig(
+    orm="sqlalchemy",
+    dsn="mysql+aiomysql://user:pass@localhost:3306/mydb",
+    auto_create_table=True,
+)
+```
+
+### Tortoise ORM + PostgreSQL
+
+```python
+config = AuditConfig(
+    orm="tortoise",
+    dsn="postgres://user:pass@localhost:5432/mydb",
+    auto_create_table=True,
+)
+```
+
+### MongoDB via Beanie
+
+```python
+config = AuditConfig(
+    orm="beanie",
+    dsn="mongodb://localhost:27017",
+    mongodb_database="myapp",
+    table_name="audit_logs",   # becomes collection name
+)
+```
+
+### Raw asyncpg (PostgreSQL, maximum performance)
+
+```python
+config = AuditConfig(
+    orm="asyncpg",
+    dsn="postgresql://user:pass@localhost:5432/mydb",
+    batch_size=200,
+)
+```
+
+### Using with Alembic (SQLAlchemy only)
+
+```python
+# In alembic/env.py — include audit table in your migrations
+from fastapi_audit_log.db.sqlalchemy_table import AuditBase
+target_metadata = [YourBase.metadata, AuditBase.metadata]
+```
+
+## Enriching Logs from Routes
+
+```python
+from fastapi_audit_log import set_audit_action, set_audit_resource, set_audit_extra
+
+@app.post("/items")
+async def create_item(item_id: str):
+    set_audit_action("item.create")
+    set_audit_resource("item", item_id)
+    set_audit_extra("metadata", {"source": "admin_panel"})
+    return {"status": "ok"}
+```
+
+## Retrieving Audit Logs
+
+`fastapi-audit-log` provides a built-in helper to add a route for querying and filtering your audit logs.
+
+```python
+from fastapi import FastAPI
+from fastapi_audit_log import add_audit_log_routes
+
+app = FastAPI(...)
+
+# Register the GET /audit-logs route
+add_audit_log_routes(
+    app,
+    path="/audit-logs",      # default
+    tags=["Audit Logs"]      # optional tags for OpenAPI
+)
+```
+
+### Filtering and Pagination
+
+The added route supports several query parameters:
+
+*   **Pagination:** `limit` (default 100, max 1000) and `offset` (default 0).
+*   **Filters:** `method`, `path`, `status_code`, `user_id`, and `action`.
+
+Example request:
+`GET /audit-logs?method=POST&status_code=201&limit=20`
+
+## Configuration Reference (AuditConfig)
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `orm` | `str` | **Required** | One of: `sqlalchemy`, `tortoise`, `sqlmodel`, `beanie`, `asyncpg`. |
+| `dsn` | `str` | **Required** | Connection string for the database. |
+| `table_name` | `str` | `"audit_logs"` | Name of the table or collection. |
+| `auto_create_table`| `bool` | `True` | Whether to create the table on startup. |
+| `batch_size` | `int` | `1` | Set > 1 to enable batching (not all backends yet). |
+| `mask_fields` | `list[str]` | `[]` | PII fields to mask in request bodies. |
+| `on_storage_error`| `Callable` | `None` | Optional callback for storage errors. |
+
+## Development and Examples
+
+To run the examples that require a real database (PostgreSQL, MongoDB, MySQL), you can use the provided Docker Compose file:
+
+```bash
+docker-compose up -d
+```
+
+This will start:
+
+- **PostgreSQL** at `localhost:5432` (user: `user`, pass: `pass`, db: `audit_db`)
+- **MongoDB** at `localhost:27017`
+- **MySQL** at `localhost:3306` (user: `user`, pass: `pass`, db: `audit_db`)
+
+### Running the MongoDB Example
+
+```bash
+poetry run python examples/beanie_mongodb_usage.py
+```
+
+### Running the Asyncpg Example
+
+```bash
+poetry run python examples/asyncpg_usage.py
+```
+
+## Future Features
+
+- **Admin UI:** Build a simple web UI for viewing/searching audit logs.
+- **Custom Storage Backends:** Allow users to plug in custom storage backends (e.g., S3, Redis, external APIs).
+- **Event Hooks:** Add hooks for pre/post log processing (e.g., for enrichment, notifications).
+- **Log Export:** Support exporting logs to CSV, JSON, or external log management systems.
+- **Retention Policies:** Add configurable log retention and automatic cleanup.
+- **Multi-Tenancy:** Support tenant-aware logging for SaaS apps.
+- **Security:** Encrypt sensitive log fields at rest, and add role-based access for log viewing.
+- **CLI Tooling:** Provide CLI commands for log inspection, export, and management.
+- **OpenTelemetry Integration:** Integrate with OpenTelemetry for distributed tracing and correlation.
+- **Documentation:** Expand usage examples and add troubleshooting guides.
+
+## License
+
+MIT

auditlog_fastapi-0.2.0/fastapi_audit_log/__init__.py

@@ -0,0 +1,36 @@
+from contextlib import asynccontextmanager
+
+from .config import AuditConfig, configure, get_storage
+from .context import set_audit_action, set_audit_extra, set_audit_resource
+from .middleware import AuditMiddleware
+from .routes import add_audit_log_routes
+
+
+def create_audit_lifespan(config: AuditConfig):
+    storage = configure(config)
+
+    @asynccontextmanager
+    async def lifespan(app):
+        # Store config in app for testing/access if needed
+        if not hasattr(app, "extra"):
+            app.extra = {}
+        app.extra["audit_config"] = config
+
+        await storage.startup()
+        yield
+        await storage.shutdown()
+
+    return lifespan
+
+
+__all__ = [
+    "AuditConfig",
+    "configure",
+    "get_storage",
+    "AuditMiddleware",
+    "create_audit_lifespan",
+    "set_audit_action",
+    "set_audit_resource",
+    "set_audit_extra",
+    "add_audit_log_routes",
+]

auditlog_fastapi-0.2.0/fastapi_audit_log/config.py

@@ -0,0 +1,86 @@
+import typing
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .exceptions import AuditAlreadyConfiguredError, AuditNotConfiguredError
+
+if TYPE_CHECKING:
+    from .storage.base import AuditStorage
+
+ORMBackend = Literal["sqlalchemy", "tortoise", "sqlmodel", "beanie", "asyncpg"]
+
+
+class AuditConfig(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    # Required
+    orm: ORMBackend
+    dsn: str  # full connection string e.g. "postgresql+asyncpg://user:pass@host/db"
+
+    # Table / collection config
+    table_name: str = "audit_logs"
+    auto_create_table: bool = True  # CREATE TABLE IF NOT EXISTS on startup
+
+    # SQLAlchemy-specific
+    sqlalchemy_pool_size: int = 10
+    sqlalchemy_max_overflow: int = 20
+    sqlalchemy_pool_timeout: int = 30
+    sqlalchemy_echo: bool = False
+    expose_metadata: bool = False  # if True, exposes Base.metadata for Alembic
+
+    # Tortoise-specific
+    tortoise_modules: dict[str, list[str]] | None = None
+
+    # MongoDB / Beanie-specific
+    mongodb_database: str = "audit"
+
+    # Batching (for all backends)
+    batch_size: int = 1  # set > 1 to enable batch inserts
+    batch_flush_interval: float = 5.0  # seconds, used if batch_size > 1
+
+    # PII masking
+    mask_fields: list[str] = Field(default_factory=list)
+
+    # Error handling
+    on_storage_error: Any = None  # callable(exc: Exception, entry: AuditEntry) -> None
+
+
+# Global registry holding the configured storage instance
+_registry: dict[str, Any] = {}
+
+
+def configure(config: AuditConfig) -> "AuditStorage":
+    """
+    Initialize and register the audit storage backend.
+    Must be called once at app startup before serving requests.
+    Returns the configured storage instance.
+    Raises AuditConfigurationError if config is invalid or backend cannot connect.
+    """
+    from .registry import resolve_storage
+
+    if "storage" in _registry:
+        existing_config = _registry["config"]
+        if existing_config == config:
+            return typing.cast("AuditStorage", _registry["storage"])
+        raise AuditAlreadyConfiguredError(
+            "Audit storage is already configured with a different configuration."
+        )
+
+    storage = resolve_storage(config)
+    _registry["storage"] = storage
+    _registry["config"] = config
+    return typing.cast("AuditStorage", storage)
+
+
+def get_storage() -> "AuditStorage":
+    """
+    Retrieve the globally registered storage instance.
+    Raises AuditNotConfiguredError if configure() has not been called.
+    """
+    if "storage" not in _registry:
+        raise AuditNotConfiguredError(
+            "Audit storage has not been configured. Call configure() first."
+        )
+    return typing.cast("AuditStorage", _registry["storage"])
+

auditlog_fastapi-0.2.0/fastapi_audit_log/context.py

@@ -0,0 +1,33 @@
+from contextvars import ContextVar
+from typing import Any
+
+from .models import AuditEntry
+
+_current_entry: ContextVar[AuditEntry | None] = ContextVar("audit_entry", default=None)
+
+
+def get_current_audit_entry() -> AuditEntry | None:
+    """Returns the current audit entry from the context."""
+    return _current_entry.get()
+
+
+def set_audit_action(action: str) -> None:
+    """Sets the action field on the current audit entry."""
+    entry = get_current_audit_entry()
+    if entry:
+        entry.action = action
+
+
+def set_audit_resource(resource_type: str, resource_id: str) -> None:
+    """Sets resource_type and resource_id fields on the current audit entry."""
+    entry = get_current_audit_entry()
+    if entry:
+        entry.resource_type = resource_type
+        entry.resource_id = resource_id
+
+
+def set_audit_extra(key: str, value: Any) -> None:
+    """Adds a key-value pair to the extra field of the current audit entry."""
+    entry = get_current_audit_entry()
+    if entry:
+        entry.extra[key] = value

auditlog_fastapi-0.2.0/fastapi_audit_log/db/beanie_document.py

@@ -0,0 +1,42 @@
+import uuid
+from datetime import datetime
+
+from beanie import Document
+from pydantic import Field
+
+
+class AuditLogDocument(Document):
+    """Beanie Document model for audit logs, with dynamic collection name set at runtime."""  # noqa: E501
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4)
+    timestamp: datetime
+    user_id: str | None = None
+    username: str | None = None
+    ip_address: str | None = None
+    user_agent: str | None = None
+    method: str
+    path: str
+    query_params: dict | None = None
+    status_code: int | None = None
+    request_body: dict | None = None
+    response_body: dict | None = None
+    duration_ms: float | None = None
+    action: str | None = None
+    resource_type: str | None = None
+    resource_id: str | None = None
+    extra: dict | None = None
+    error: str | None = None
+
+    class Settings:
+        """Settings for Beanie Document, with collection name set dynamically at runtime."""  # noqa: E501
+
+        name = "audit_logs"  # overridden by config at runtime
+        indexes = [
+            "timestamp",
+            "user_id",
+            "path",
+            "status_code",
+            "action",
+            "resource_type",
+            "resource_id",
+        ]