From a18ad48721fc9abc806992adbe69e5ad2cda5ed8 Mon Sep 17 00:00:00 2001 From: Samir Boulahtit Date: Wed, 19 Nov 2025 21:55:34 +0100 Subject: [PATCH] updating middleware doc --- docs/architecture/middleware.md | 95 ++++++++++++++++++++++++++ docs/backend/middleware-reference.md | 8 +-- docs/development/naming-conventions.md | 54 ++++++++++++--- 3 files changed, 144 insertions(+), 13 deletions(-) diff --git a/docs/architecture/middleware.md b/docs/architecture/middleware.md index 4882a7f9..fe3fd83e 100644 --- a/docs/architecture/middleware.md +++ b/docs/architecture/middleware.md @@ -119,6 +119,101 @@ else: **Why it's needed**: Each vendor shop can have custom branding +## Naming Conventions + +### Middleware File Organization + +All middleware components follow a consistent naming pattern for maintainability and clarity. + +#### File Naming: Simple Nouns Without Redundant Suffixes + +**Pattern**: `{purpose}.py` (no "_middleware" suffix) + +``` +✅ Good: +middleware/logging.py +middleware/context.py +middleware/auth.py + +❌ Avoid: +middleware/logging_middleware.py +middleware/context_middleware.py +middleware/auth_middleware.py +``` + +**Rationale**: +- Keeps names concise and consistent +- Follows Django, Flask, and FastAPI conventions +- Makes imports cleaner: `from middleware.logging import LoggingMiddleware` +- Reduces redundancy (the `middleware/` directory already indicates the purpose) + +#### Test File Naming: Mirror the Source File + +Test files directly mirror the middleware filename with a `test_` prefix: + +``` +middleware/logging.py → tests/unit/middleware/test_logging.py +middleware/context.py → tests/unit/middleware/test_context.py +middleware/auth.py → tests/unit/middleware/test_auth.py +middleware/vendor_context.py → tests/unit/middleware/test_vendor_context.py +``` + +#### One Component Per File + +Each middleware file contains one primary class or a tightly related set of classes: + +```python +# middleware/logging.py +class LoggingMiddleware(BaseHTTPMiddleware): + """Request/response logging middleware""" + +# middleware/context.py +class ContextManager: # Business logic +class ContextMiddleware: # ASGI wrapper +class RequestContext(Enum): # Related enum + +# middleware/auth.py +class AuthManager: # Authentication logic +``` + +#### One Test File Per Component + +Follow the Single Responsibility Principle - each test file tests exactly one component: + +``` +✅ Good: +tests/unit/middleware/test_logging.py # Tests only LoggingMiddleware +tests/unit/middleware/test_context.py # Tests only ContextManager/Middleware +tests/unit/middleware/test_decorators.py # Tests only rate_limit decorator + +❌ Avoid: +tests/unit/middleware/test_all_middleware.py # Tests multiple components +tests/unit/middleware/test_combined.py # Violates SRP +``` + +**Benefits**: +- Easy to locate tests for specific components +- Clear test organization and maintainability +- Follows unit testing best practices +- Simplifies test debugging and updates + +#### Import Convention + +When importing middleware components, use explicit imports: + +```python +# ✅ Preferred - Explicit and clear +from middleware.logging import LoggingMiddleware +from middleware.context import ContextManager, RequestContext +from middleware.auth import AuthManager + +# ❌ Avoid - Less clear +from middleware import logging_middleware +from middleware import context_middleware +``` + +**See**: [Complete Naming Conventions Guide](../development/naming-conventions.md) for project-wide standards. + ## Middleware Execution Order ### The Stack (First to Last) diff --git a/docs/backend/middleware-reference.md b/docs/backend/middleware-reference.md index 4fcdf502..7e8d8a1f 100644 --- a/docs/backend/middleware-reference.md +++ b/docs/backend/middleware-reference.md @@ -72,7 +72,7 @@ ASGI middleware that wraps VendorContextManager for FastAPI integration. Enum defining all possible request context types in the application. -::: middleware.context_middleware.RequestContext +::: middleware.context.RequestContext options: show_source: false heading_level: 4 @@ -95,7 +95,7 @@ Detects the type of request (API, Admin, Vendor Dashboard, Shop) based on URL pa - `/shop/` → Shop context - Default → Fallback context -::: middleware.context_middleware.ContextManager +::: middleware.context.ContextManager options: show_source: false heading_level: 4 @@ -105,7 +105,7 @@ Detects the type of request (API, Admin, Vendor Dashboard, Shop) based on URL pa ASGI middleware for context detection. Must run AFTER VendorContextMiddleware. -::: middleware.context_middleware.ContextMiddleware +::: middleware.context.ContextMiddleware options: show_source: false heading_level: 4 @@ -192,7 +192,7 @@ Middleware for request/response logging and performance monitoring. **Added Headers:** - `X-Process-Time`: Request processing duration in seconds -::: middleware.logging_middleware.LoggingMiddleware +::: middleware.logging.LoggingMiddleware options: show_source: false heading_level: 4 diff --git a/docs/development/naming-conventions.md b/docs/development/naming-conventions.md index 78f8821e..cbc4948a 100644 --- a/docs/development/naming-conventions.md +++ b/docs/development/naming-conventions.md @@ -184,23 +184,58 @@ class ProductValidationException(ValidationException): **Rationale**: Exception files are domain-focused, not collection-focused. -### Middleware Files (DESCRIPTIVE) +### Middleware Files (SIMPLE NOUNS) -**Rule**: Middleware files use descriptive names based on their function. +**Rule**: Middleware files use simple, descriptive noun names **without redundant suffixes**. **Location**: `middleware/` +**Naming Pattern**: `{purpose}.py` (no "_middleware" suffix) + **Examples**: ``` middleware/ -├── auth.py # Authentication middleware -├── vendor_context.py # Vendor context detection -├── rate_limiter.py # Rate limiting functionality -├── logging_middleware.py # Request logging -└── decorators.py # Cross-cutting decorators +├── auth.py # ✅ AuthManager - Authentication & JWT +├── rate_limiter.py # ✅ RateLimiter - Request throttling +├── vendor_context.py # ✅ VendorContextManager - Multi-tenant detection +├── context.py # ✅ ContextManager - Request context detection +├── theme_context.py # ✅ ThemeContextManager - Theme loading +├── logging.py # ✅ LoggingMiddleware - Request/response logging +└── decorators.py # ✅ rate_limit decorator - Cross-cutting concerns ``` -**Rationale**: Middleware serves specific cross-cutting functions. +**Rationale**: +- Keeps names concise and consistent +- Follows Django, Flask, and FastAPI conventions +- Avoids redundant "_middleware" suffix +- Makes imports cleaner: `from middleware.logging import LoggingMiddleware` + +**Test File Naming**: Test files directly mirror the middleware filename: +``` +tests/unit/middleware/ +├── test_auth.py # Tests auth.py +├── test_rate_limiter.py # Tests rate_limiter.py +├── test_vendor_context.py # Tests vendor_context.py +├── test_context.py # Tests context.py +├── test_theme_context.py # Tests theme_context.py +├── test_logging.py # Tests logging.py +└── test_decorators.py # Tests decorators.py +``` + +**One Test File Per Component**: Each test file should test **exactly one** middleware component, following the Single Responsibility Principle. + +**Class Names Within Files**: +```python +# middleware/logging.py +class LoggingMiddleware(BaseHTTPMiddleware): # Class name can include "Middleware" + pass + +# middleware/context.py +class ContextManager: # Manager for business logic +class ContextMiddleware(BaseHTTPMiddleware): # Middleware wrapper +``` + +**Rationale**: Middleware serves specific cross-cutting functions with clean, predictable naming. ### Frontend Files @@ -397,7 +432,8 @@ Consider implementing linting rules or pre-commit hooks to enforce: | Schema/Pydantic | SINGULAR | `product.py`, `order.py` | | Services | SINGULAR + service | `product_service.py` | | Exceptions | SINGULAR | `product.py`, `order.py` | -| Middleware | DESCRIPTIVE | `auth.py`, `rate_limiter.py` | +| Middleware | SIMPLE NOUN | `auth.py`, `logging.py`, `context.py` | +| Middleware Tests | test_{name}.py | `test_auth.py`, `test_logging.py` | | Database Tables | SINGULAR | `product`, `inventory` | | Database Columns | SINGULAR | `vendor_id`, `created_at` | | API Endpoints | PLURAL | `/products`, `/orders` |