Merge pull request #15 from Athroniaeth/development

Development

Author: Athroniaeth

CHANGELOG.md

@@ -1,3 +1,22 @@
+## 0.11.0 (2025-12-01)
+
+### BREAKING CHANGE
+
+- key_hash property now raises ValueError when unset
+  instead of returning None. Use try/except or check _key_hash directly.
+- Remove generic type D, entity_factory parameter, and custom entity/model support. Services and repositories now work directly with ApiKey. Remove extensibility patterns. ApiKeyService no longer accepts entity_factory parameter. SqlAlchemyApiKeyRepository no longer accepts model_cls/domain_cls parameters. Custom entities are no longer supported.
+- Please delete all domain_cls parameter use with service
+
+### Refactor
+
+- delete claude code comments and remove str | None who aren't compatible with python 3.9
+- **domain**: add key_hash validation, public init aliases, and secure repr
+- **tests**: mock crypto backends in hasher tests and improve typing in SqlAlchemyApiKeyRepository
+- **tests**: restructure unit tests with 100% coverage on core modules
+- remove extensibility patterns (generics, entity factory, custom mapping)
+- **svc**: remove optional domain cls to service init
+- **cli**: modify bad message for updating .env
+
 ## 0.10.0 (2025-11-26)
 
 ### Feat

CLAUDE.md

@@ -0,0 +1,82 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`fastapi-api-key` is a library for issuing, persisting, and verifying API keys in FastAPI applications. It provides pluggable hashing strategies (Argon2, bcrypt), backend-agnostic persistence (SQLAlchemy, in-memory), optional caching (aiocache), and connectors for FastAPI and Typer CLI.
+
+## Development Commands
+
+```bash
+# Install all dependencies (runtime + dev)
+uv sync --extra all --group dev
+
+# Format and lint (runs ruff format, ruff check, ty, bandit)
+uv run lint
+
+# Run tests with coverage
+uv run pytest
+
+# Run a single test file
+uv run pytest tests/units/test_service.py
+
+# Run a specific test
+uv run pytest tests/units/test_service.py::test_function_name -v
+
+# Preview documentation
+uv run mkdocs serve
+
+# Build documentation
+uv run mkdocs build
+
+# CLI tool (requires cli extra)
+uv run fak --help
+```
+
+## Architecture
+
+### Core Components
+
+- **`ApiKeyService`** (`src/fastapi_api_key/services/base.py`): Main service orchestrating key creation, verification, and lifecycle. Handles timing attack mitigation via random response delays (rrd parameter).
+
+- **`AbstractApiKeyRepository`** (`src/fastapi_api_key/repositories/base.py`): Repository contract. Implementations:
+  - `InMemoryApiKeyRepository` - for testing
+  - `SqlAlchemyApiKeyRepository` - production use with SQLAlchemy
+
+- **`ApiKeyHasher`** (`src/fastapi_api_key/hasher/base.py`): Protocol for hashing. Implementations in `hasher/argon2.py` and `hasher/bcrypt.py`. Uses pepper (secret) + salt pattern.
+
+- **`ApiKey`** (`src/fastapi_api_key/domain/entities.py`): Domain entity representing an API key with fields: id_, key_id, key_hash, name, description, is_active, scopes, expires_at, last_used_at.
+
+### API Key Format
+
+`{global_prefix}-{key_id}-{key_secret}` (e.g., `ak-7a74caa323a5410d-mAfP3l6y...`)
+
+- `key_id`: 16-char UUID fragment (public, stored in DB for lookup)
+- `key_secret`: 48-char base64 string (hashed before storage, never returned after creation)
+
+### Connectors
+
+- **FastAPI Router** (`src/fastapi_api_key/api.py`): `create_api_keys_router()` provides CRUD endpoints. `create_depends_api_key()` creates a FastAPI dependency for protecting routes.
+
+- **Typer CLI** (`src/fastapi_api_key/cli.py`): `create_api_keys_cli()` for command-line key management.
+
+### Caching Layer
+
+`CachedApiKeyService` (`src/fastapi_api_key/services/cached.py`) wraps the base service with aiocache support.
+
+## Key Design Decisions
+
+- Secrets are hashed with salt + pepper; plaintext only returned once at creation
+- Repository pattern enables swapping storage backends
+- Service raises domain errors (`KeyNotFound`, `KeyInactive`, `KeyExpired`, `InvalidKey`, `InvalidScopes`) from `domain/errors.py`
+- RFC 9110/7235 compliance: 401 for missing/invalid keys, 403 for inactive/expired
+- Supports `Authorization: Bearer`, `X-API-Key` header, and `api_key` query param
+
+## Testing
+
+Tests are in `tests/` with coverage configured in `pyproject.toml`. The library emits warnings when using the default pepper - tests rely on this behavior.
+
+## Branching
+
+Feature branches should be created from `development` branch. PRs target `development`.

docs/usage/database.md

@@ -0,0 +1,209 @@
+# Database Configuration
+
+This guide covers SQLAlchemy setup and connection pooling best practices for production use.
+
+## Installation
+
+Install the SQLAlchemy extra:
+
+```bash
+pip install fastapi-api-key[sqlalchemy]
+```
+
+## Basic Setup
+
+The `SqlAlchemyApiKeyRepository` requires an `AsyncSession`:
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
+from fastapi_api_key.repositories.sql import SqlAlchemyApiKeyRepository
+
+# Create async engine
+engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db")
+
+# Create session factory
+async_session = async_sessionmaker(engine, expire_on_commit=False)
+
+# Use in your application
+async with async_session() as session:
+    repo = SqlAlchemyApiKeyRepository(session)
+    # ... use repository
+    await session.commit()
+```
+
+## Connection Pooling
+
+SQLAlchemy uses connection pooling by default. For production, configure the pool explicitly.
+
+### PostgreSQL (asyncpg)
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine
+
+engine = create_async_engine(
+    "postgresql+asyncpg://user:pass@localhost/db",
+    pool_size=5,           # Number of persistent connections
+    max_overflow=10,       # Additional connections when pool is exhausted
+    pool_timeout=30,       # Seconds to wait for a connection
+    pool_recycle=1800,     # Recycle connections after 30 minutes
+    pool_pre_ping=True,    # Verify connections before use
+)
+```
+
+### SQLite (aiosqlite)
+
+SQLite doesn't benefit from connection pooling. Use `NullPool` for async SQLite:
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlalchemy.pool import NullPool
+
+engine = create_async_engine(
+    "sqlite+aiosqlite:///./api_keys.db",
+    poolclass=NullPool,
+)
+```
+
+### MySQL (aiomysql)
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine
+
+engine = create_async_engine(
+    "mysql+aiomysql://user:pass@localhost/db",
+    pool_size=5,
+    max_overflow=10,
+    pool_timeout=30,
+    pool_recycle=3600,     # MySQL default wait_timeout is 8 hours
+    pool_pre_ping=True,
+)
+```
+
+## Pool Size Guidelines
+
+| Scenario | pool_size | max_overflow |
+|----------|-----------|--------------|
+| Development | 2 | 5 |
+| Small app (<100 req/s) | 5 | 10 |
+| Medium app (100-1000 req/s) | 10 | 20 |
+| Large app (>1000 req/s) | 20+ | 40+ |
+
+!!! tip "Rule of Thumb"
+    A good starting point is `pool_size = (2 * CPU cores) + effective_spindle_count`.
+    For cloud databases, start with 5-10 and monitor.
+
+## FastAPI Integration
+
+Use a dependency to manage sessions per request:
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, Depends
+from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession
+
+from fastapi_api_key import ApiKeyService
+from fastapi_api_key.repositories.sql import SqlAlchemyApiKeyRepository
+
+# Engine with connection pooling
+engine = create_async_engine(
+    "postgresql+asyncpg://user:pass@localhost/db",
+    pool_size=5,
+    max_overflow=10,
+    pool_pre_ping=True,
+)
+
+async_session = async_sessionmaker(engine, expire_on_commit=False)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup: optionally create tables
+    async with engine.begin() as conn:
+        # await conn.run_sync(Base.metadata.create_all)
+        pass
+    yield
+    # Shutdown: dispose of the connection pool
+    await engine.dispose()
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+async def get_session():
+    async with async_session() as session:
+        yield session
+
+
+async def get_api_key_service(session: AsyncSession = Depends(get_session)):
+    repo = SqlAlchemyApiKeyRepository(session)
+    return ApiKeyService(repo=repo)
+```
+
+## Connection Health
+
+### Pre-ping
+
+Enable `pool_pre_ping=True` to test connections before use. This handles:
+
+- Database restarts
+- Network interruptions
+- Idle connection timeouts
+
+### Pool Recycling
+
+Set `pool_recycle` to a value less than your database's connection timeout:
+
+| Database | Default Timeout | Recommended `pool_recycle` |
+|----------|-----------------|---------------------------|
+| PostgreSQL | No limit | 1800 (30 min) |
+| MySQL | 8 hours | 3600 (1 hour) |
+| MariaDB | 8 hours | 3600 (1 hour) |
+
+## Monitoring
+
+Log pool statistics for debugging:
+
+```python
+import logging
+
+logging.getLogger("sqlalchemy.pool").setLevel(logging.DEBUG)
+```
+
+Check pool status programmatically:
+
+```python
+pool = engine.pool
+print(f"Pool size: {pool.size()}")
+print(f"Checked out: {pool.checkedout()}")
+print(f"Overflow: {pool.overflow()}")
+print(f"Checked in: {pool.checkedin()}")
+```
+
+## Common Issues
+
+### "QueuePool limit reached"
+
+The pool is exhausted. Solutions:
+
+1. Increase `pool_size` and `max_overflow`
+2. Ensure sessions are properly closed (use context managers)
+3. Reduce query execution time
+
+### "Connection reset by peer"
+
+The database closed an idle connection. Solutions:
+
+1. Enable `pool_pre_ping=True`
+2. Set `pool_recycle` to a lower value
+3. Check database idle timeout settings
+
+### High latency on first request
+
+The pool creates connections lazily. Pre-warm the pool:
+
+```python
+async def warm_pool():
+    """Pre-create connections to avoid cold start latency."""
+    async with engine.connect() as conn:
+        await conn.execute(text("SELECT 1"))
+```

mkdocs.yml

@@ -63,6 +63,7 @@ nav:
   - Quickstart: quickstart.md
   - Usage:
       - Dotenv: usage/dotenv.md
+      - Database: usage/database.md
       - Cache: usage/cache.md
       - FastAPI: usage/fastapi.md
       - Scopes: usage/scopes.md

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-api-key"
-version = "0.10.0"
+version = "0.11.0"
 description = "fastapi-api-key provides secure, production-ready API key management for FastAPI. It offers pluggable hashing strategies (Argon2 or bcrypt), backend-agnostic persistence (currently SQLAlchemy), and an optional cache layer (aiocache). Includes a Typer CLI and a FastAPI router for CRUD management of keys."
 readme = "README.md"
 authors = [
@@ -100,6 +100,7 @@ dev = [
     "typer>=0.12.5",
     "mkdocs>=1.6.1",
     "mkdocs-material>=9.6.23",
+    "httpx>=0.28.1",
 ]
 
 [tool.commitizen]
@@ -141,4 +142,4 @@ omit = [
     "src/fastapi_api_key/__init__.py",
     "src/fastapi_api_key/__main__.py",
 ]
-branch = true
+branch = true