Merge pull request #3 from MehrazRumman/wip

MehrazRumman · web-flow · commit 8b1a62ef61cb · 2026-04-26T02:09:38.000+06:00
ready for publish
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-26
+
+### Added
+- FastAPI middleware for automatic request/response logging
+- Structured `LogEvent` model with request metadata, response status, and latency
+- Configurable event filtering pipeline (`ObserverFilter` protocol)
+- Multiple storage backends: in-memory, JSON file, SQLite
+- Console and file log handlers
+- JSON and plain-text formatters
+- Built-in dashboard for inspecting logged events (mountable as a sub-application)
+- `ObserverConfig` for controlling log level, path filters, and storage
+- Logger factory with structured output support
+- Full test suite (69 tests, 87% coverage)
+- MkDocs documentation site with quickstart, API reference, and best-practices guides
+- CI/CD pipelines for testing (Python 3.10–3.14), coverage badge, and PyPI publishing
+
+[Unreleased]: https://github.com/MehrazRumman/fastapi-observer/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/MehrazRumman/fastapi-observer/releases/tag/v0.1.0
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,81 @@
+# Contributing to fastapi-observer
+
+Thank you for your interest in contributing!
+
+## Getting Started
+
+1. Fork the repository and clone your fork:
+   ```bash
+   git clone https://github.com/<your-username>/fastapi-observer.git
+   cd fastapi-observer
+   ```
+
+2. Install all development dependencies:
+   ```bash
+   pip install -e ".[test,docs,dev]"
+   ```
+
+3. Install pre-commit hooks:
+   ```bash
+   pre-commit install
+   ```
+
+4. Create a feature branch:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+## Running Tests
+
+```bash
+# Run the full test suite
+pytest -q
+
+# Run with coverage report
+pytest --cov=fastapi_observer --cov-report=term-missing
+
+# Run a specific test file
+pytest tests/test_middleware.py -v
+```
+
+Maintain coverage above 85% for any new code you add.
+
+## Code Style
+
+This project uses [Black](https://black.readthedocs.io/) for formatting.
+
+```bash
+# Format all files
+black .
+
+# Check formatting without changing files
+black --check .
+```
+
+Pre-commit hooks run Black automatically on every commit. If a commit is rejected, run `black .` and re-stage the files.
+
+## Building Documentation
+
+```bash
+mkdocs serve        # preview locally at http://127.0.0.1:8000
+mkdocs build        # build static site into /site
+```
+
+## Submitting a Pull Request
+
+1. Make sure all tests pass and coverage has not dropped.
+2. Update documentation if you changed public APIs or added new features.
+3. Add an entry to [CHANGELOG.md](CHANGELOG.md) under the `Unreleased` section.
+4. Open a pull request against the `main` branch with a clear description of the change.
+
+## Reporting Bugs
+
+Open an issue at <https://github.com/MehrazRumman/fastapi-observer/issues> with:
+
+- A minimal reproducible example
+- Expected vs. actual behaviour
+- Python version and fastapi-observer version
+
+## Security Issues
+
+Please do **not** open a public issue for security vulnerabilities. See [SECURITY.md](SECURITY.md) for the responsible disclosure process.
diff --git a/README.md b/README.md
@@ -1,80 +1,129 @@
 # fastapi-observer
 
-FastAPI Observer provides structured logging and observability helpers for FastAPI applications.
+Structured logging and observability middleware for FastAPI applications.
 
 [![Test](https://github.com/MehrazRumman/fastapi-observer/actions/workflows/tests.yml/badge.svg)](https://github.com/MehrazRumman/fastapi-observer/actions/workflows/tests.yml)
 [![coverage](assets/coverage.svg)](https://github.com/MehrazRumman/fastapi-observer/actions/workflows/coverage-badge.yml)
 [![pypi package](https://img.shields.io/pypi/v/fastapi-observer?logo=pypi&label=pypi%20package)](https://pypi.org/project/fastapi-observer/)
 [![python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-brightgreen?logo=python&logoColor=white)](#python-compatibility)
 
-## Python compatibility
+**[Documentation](https://mehrazrumman.github.io/fastapi-observer/)** · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md)
 
-- Supported Python versions: `3.10`, `3.11`, `3.12`, `3.13`, `3.14`
-- Enforced in CI with tox matrix: `py310`, `py311`, `py312`, `py313`, `py314`
+---
 
-## Package versions
+## Features
 
-### Runtime
+- **Zero-boilerplate middleware** — one line to log every request and response
+- **Structured events** — typed `LogEvent` objects with method, path, status code, latency, and more
+- **Pluggable storage** — in-memory, JSON file, JSON Lines, or SQLite backends
+- **Filter pipeline** — drop health-check noise, log only errors, or set a minimum latency threshold
+- **Built-in dashboard** — mount an event-inspector UI at any path in your app
+- **Multiple formatters** — plain-text or JSON output
+- **Python 3.10–3.14** with full CI coverage across all versions
 
-- `pydantic>=2.0,<3.0`
+---
 
-### Testing
+## Install
 
-- `pytest>=8.0`
-- `pytest-cov>=5.0`
+```bash
+pip install fastapi-observer
+```
 
-### Documentation
+---
 
-- `mkdocs>=1.6`
-- `mkdocs-material>=9.5`
+## Quick start
 
-### Development
+### Basic logging
 
-- `pre-commit>=3.7`
-- `black>=24.10`
+```python
+from fastapi import FastAPI
+from fastapi_observer import ObserverConfig, ObserverMiddleware
 
-## Install
+app = FastAPI()
+app.add_middleware(ObserverMiddleware, config=ObserverConfig())
 
-```bash
-pip install fastapi-observer
+@app.get("/items")
+async def list_items():
+    return {"items": ["alpha", "beta", "gamma"]}
 ```
 
-For development:
+Every request is now logged to the console with method, path, status code, and latency.
 
-```bash
-pip install -e ".[test,docs,dev]"
-```
+### Persist events and open the dashboard
 
-## Tests and coverage
+```python
+from fastapi import FastAPI
+from fastapi_observer import ObserverConfig, ObserverMiddleware, build_dashboard_app
+from fastapi_observer.storage import InMemoryEventStore
 
-Run tests:
+app = FastAPI()
+store = InMemoryEventStore()
 
-```bash
-pytest -q
+app.add_middleware(ObserverMiddleware, config=ObserverConfig(), storage=store)
+app.mount("/dashboard", build_dashboard_app(store, title="Observer Dashboard"))
 ```
 
-Run tests with coverage:
+Open `http://localhost:8000/dashboard` to browse and inspect logged events.
 
-```bash
-pytest -q --cov=fastapi_observer --cov-report=term-missing --cov-report=xml
+### Filter out noise
+
+```python
+from fastapi_observer import ObserverConfig, ObserverMiddleware, only_errors, min_duration_ms
+
+app.add_middleware(
+    ObserverMiddleware,
+    config=ObserverConfig(handlers=["console"], log_format="json"),
+    event_filters=[
+        only_errors,           # log 4xx/5xx responses only
+        min_duration_ms(50.0), # ignore fast responses
+    ],
+)
 ```
 
-Run full Python version matrix locally:
+See the [examples/](examples/) directory for more patterns including SQLite storage and custom filters.
+
+---
+
+## Storage backends
+
+| Backend | Class | Use case |
+|---|---|---|
+| In-memory | `InMemoryEventStore` | Development, testing |
+| JSON file | `JsonFileEventStore` | Simple persistence |
+| JSON Lines | `JsonLinesEventStore` | Append-only log files |
+| SQLite | `SQLiteEventStore` | Queryable local storage |
+
+---
+
+## Python compatibility
+
+- Supported versions: `3.10`, `3.11`, `3.12`, `3.13`, `3.14`
+- Enforced in CI with a tox matrix across all versions
+
+---
+
+## Development
+
+Install all dependencies:
 
 ```bash
-tox
+pip install -e ".[test,docs,dev]"
+pre-commit install
 ```
 
-## Docs
-
-Build docs:
+Run tests:
 
 ```bash
-mkdocs build --strict
+pytest -q
+pytest -q --cov=fastapi_observer --cov-report=term-missing   # with coverage
+tox                                                           # full version matrix
 ```
 
-Serve docs locally:
+Build and preview docs:
 
 ```bash
-mkdocs serve
+mkdocs serve        # http://127.0.0.1:8000
+mkdocs build --strict
 ```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution guide.
diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,33 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+| ------- | --------- |
+| 0.1.x   | Yes       |
+
+## Reporting a Vulnerability
+
+Please **do not** open a public GitHub issue for security vulnerabilities.
+
+Instead, report them by emailing **blackndmaroon@gmail.com** with the subject line:
+
+```
+[fastapi-observer] Security vulnerability report
+```
+
+Include as much of the following as you can:
+
+- A description of the vulnerability and its potential impact
+- The file(s) and line number(s) involved
+- A minimal reproducible example or proof-of-concept
+- Any suggested fix (optional but appreciated)
+
+You will receive an acknowledgement within **72 hours** and a resolution timeline once the issue is assessed. We follow responsible disclosure — please allow us reasonable time to address the issue before any public disclosure.
+
+## Security Considerations for Users
+
+- **Do not log sensitive fields** (passwords, tokens, PII). Use path or header filters in `ObserverConfig` to exclude them.
+- **Restrict access to the dashboard** — mount it behind authentication middleware in production.
+- **Secure storage files** — JSON and SQLite storage files contain request data; apply appropriate filesystem permissions.
+- Keep your `fastapi` and `pydantic` dependencies up to date to pick up upstream security fixes.
diff --git a/pyproject.toml b/pyproject.toml
@@ -8,13 +8,35 @@ version = "0.1.0"
 description = "Logging and observability helpers for FastAPI applications."
 readme = "README.md"
 requires-python = ">=3.10,<3.15"
-license = { file = "LICENSE" }
-authors = [{ name = "fastapi-observer maintainers" }]
+license = "MIT"
+authors = [{ name = "Mehraz Hossain Rumman", email = "blackndmaroon@gmail.com" }]
+keywords = ["fastapi", "logging", "observability", "middleware", "monitoring"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: System :: Logging",
+]
+
 dependencies = [
   "fastapi>=0.100,<1.0",
   "pydantic>=2.0,<3.0",
 ]
 
+[project.urls]
+Homepage = "https://github.com/MehrazRumman/fastapi-observer"
+Documentation = "https://mehrazrumman.github.io/fastapi-observer/"
+Repository = "https://github.com/MehrazRumman/fastapi-observer.git"
+Issues = "https://github.com/MehrazRumman/fastapi-observer/issues"
+Changelog = "https://github.com/MehrazRumman/fastapi-observer/blob/main/CHANGELOG.md"
+
 [project.optional-dependencies]
 test = [
   "httpx>=0.24",
