orion/docs/backend/middleware-reference.md

API Reference

Complete technical reference for all middleware components, utilities, and core classes.

Overview

This reference provides detailed API documentation for all internal modules and classes. All documentation is auto-generated from source code docstrings.

---

Authentication & Authorization

AuthManager

The core authentication manager handling JWT tokens, password hashing, and role-based access control.

::: middleware.auth.AuthManager options: show_source: false heading_level: 4 show_root_heading: false show_root_toc_entry: false members: - init - hash_password - verify_password - authenticate_user - create_access_token - verify_token - get_current_user - require_role - require_admin - require_vendor - require_customer - create_default_admin_user

---

Multi-Tenant Context Management

VendorContextManager

Detects and manages vendor context from custom domains, subdomains, or path-based routing. This is the foundation of the multi-tenant system.

Key Features:

• Custom domain routing (customdomain.com → Vendor)
• Subdomain routing (vendor1.platform.com → Vendor)
• Path-based routing (/vendor/vendor1/ → Vendor)
• Clean path extraction for nested routing

::: middleware.vendor_context.VendorContextManager options: show_source: false heading_level: 4 show_root_heading: false

VendorContextMiddleware

ASGI middleware that wraps VendorContextManager for FastAPI integration.

::: middleware.vendor_context.VendorContextMiddleware options: show_source: false heading_level: 4 show_root_heading: false

---

Request Context Detection

RequestContext

Enum defining all possible request context types in the application.

::: middleware.context.RequestContext options: show_source: false heading_level: 4 show_root_heading: false members: - API - ADMIN - VENDOR_DASHBOARD - SHOP - FALLBACK

ContextManager

Detects the type of request (API, Admin, Vendor Dashboard, Shop) based on URL patterns.

Context Detection Rules:

• /api/ → API context
• /admin/ → Admin context
• /vendor/ → Vendor Dashboard context
• /shop/ → Shop context
• Default → Fallback context

::: middleware.context.ContextManager options: show_source: false heading_level: 4 show_root_heading: false

ContextMiddleware

ASGI middleware for context detection. Must run AFTER VendorContextMiddleware.

::: middleware.context.ContextMiddleware options: show_source: false heading_level: 4 show_root_heading: false

---

Theme Management

ThemeContextManager

Manages vendor-specific theme configuration and injection into request context.

::: middleware.theme_context.ThemeContextManager options: show_source: false heading_level: 4 show_root_heading: false

ThemeContextMiddleware

ASGI middleware for theme injection. Must run AFTER ContextDetectionMiddleware.

::: middleware.theme_context.ThemeContextMiddleware options: show_source: false heading_level: 4 show_root_heading: false

---

Rate Limiting

RateLimiter

In-memory rate limiter using a sliding window algorithm for request throttling.

Features:

• Sliding window algorithm for accurate rate limiting
• Per-client tracking
• Automatic cleanup of old entries
• Configurable limits and time windows

::: middleware.rate_limiter.RateLimiter options: show_source: false heading_level: 4 show_root_heading: false

Rate Limiting Decorator

Decorator for applying rate limits to FastAPI endpoints.

::: middleware.decorators.rate_limit options: show_source: true heading_level: 4 show_root_heading: false

Usage Example:

from middleware.decorators import rate_limit

@app.post("/api/v1/resource")
@rate_limit(max_requests=10, window_seconds=60)
async def create_resource():
    return {"status": "created"}

---

Logging & Monitoring

LoggingMiddleware

Middleware for request/response logging and performance monitoring.

Logged Information:

• Request method, path, and client IP
• Response status code
• Request processing time
• Errors and exceptions

Added Headers:

• X-Process-Time: Request processing duration in seconds

::: middleware.logging.LoggingMiddleware options: show_source: false heading_level: 4 show_root_heading: false

---

Path-Based Routing Solution

Modern Approach: Double Router Mounting

Instead of using middleware to rewrite paths, the application registers shop routes twice with different prefixes:

# In main.py
app.include_router(shop_pages.router, prefix="/shop")
app.include_router(shop_pages.router, prefix="/vendors/{vendor_code}/shop")

How It Works:

• Subdomain/Custom Domain Mode: Routes match /shop/* prefix
• Path-Based Development Mode: Routes match /vendors/{vendor_code}/shop/* prefix
• FastAPI handles routing naturally without path manipulation
• Vendor code is available as a path parameter when needed

Benefits:

• ✅ No middleware complexity
• ✅ Explicit route definitions
• ✅ FastAPI native routing
• ✅ Vendor code accessible via path parameter

Note: Previous implementations used path_rewrite_middleware to rewrite paths at runtime. This approach has been deprecated in favor of double mounting, which is simpler and more maintainable.

---

Middleware Execution Order

The middleware stack must be configured in the correct order for proper functionality:

graph TD
    A[Request] --> B[LoggingMiddleware]
    B --> C[VendorContextMiddleware]
    C --> D[ContextMiddleware]
    D --> E[ThemeContextMiddleware]
    E --> F[Application Routes]
    F --> G[Response]

Critical Dependencies:

1. LoggingMiddleware runs first for request timing
2. VendorContextMiddleware detects vendor and sets clean_path
3. ContextMiddleware detects context type (API/Admin/Vendor/Shop)
4. ThemeContextMiddleware loads vendor theme based on context

Note: Path-based routing (e.g., /vendors/{code}/shop/*) is handled by double router mounting in main.py, not by middleware.

---

Request State Variables

Middleware components inject the following variables into request.state:

Variable	Set By	Type	Description
vendor	VendorContextMiddleware	Vendor	Current vendor object
vendor_id	VendorContextMiddleware	int	Current vendor ID
clean_path	VendorContextMiddleware	str	Path without vendor prefix
context_type	ContextMiddleware	RequestContext	Request context (API/Admin/Vendor/Shop)
theme	ThemeContextMiddleware	dict	Vendor theme configuration

Usage in Routes:

from fastapi import Request

@app.get("/shop/products")
async def get_products(request: Request):
    vendor = request.state.vendor
    context = request.state.context_type
    theme = request.state.theme
    return {"vendor": vendor.name, "context": context}

---

Best Practices

Error Handling

All middleware should properly handle exceptions and log errors for debugging:

try:
    # Middleware logic
except Exception as e:
    logger.error(f"Middleware error: {e}")
    raise

Performance

• Keep middleware logic minimal and fast
• Use async/await properly for non-blocking operations
• Log performance metrics for monitoring

Testing

• Test middleware in isolation
• Mock request.state for unit tests
• Test middleware execution order
• Verify error handling paths

For testing examples, see the Testing Guide.

---

Related Documentation

• Authentication Guide - User authentication and JWT tokens
• RBAC Documentation - Role-based access control
• Error Handling - Exception handling patterns
• Rate Limiting - API rate limiting strategies