Skip to content

osbot-fast-api-architecture.md

Latest commit

 

History

History
394 lines (310 loc) · 9.03 KB

osbot-fast-api-architecture.md

File metadata and controls

394 lines (310 loc) · 9.03 KB

OSBot-Fast-API Architecture

📋 Overview

Module: osbot_fast_api
Purpose: Type-Safe FastAPI wrapper with enhanced middleware and monitoring capabilities
Status: Production Ready

🏗️ System Architecture

graph TB
    subgraph "External Layer"
        CLIENT[HTTP Client]
        LAMBDA[AWS Lambda]
        LOCAL[Local Server]
    end
    
    subgraph "OSBot-Fast-API Core"
        FA[Fast_API<br/>Main Controller]
        
        subgraph "Middleware Pipeline"
            MW1[Detect_Disconnect]
            MW2[Http_Request]
            MW3[CORS]
            MW4[API_Key_Check]
            MW1 --> MW2 --> MW3 --> MW4
        end
        
        subgraph "Type System"
            TS[Type_Safe Converters]
            TSB[To_BaseModel]
            BTS[From_BaseModel]
            TSD[To_Dataclass]
            DTS[From_Dataclass]
        end
        
        subgraph "Event System"
            HE[Http_Events Manager]
            HEI[Event Info]
            HEQ[Request Data]
            HER[Response Data]
            HET[Trace Data]
        end
        
        subgraph "Routing"
            FAR[Fast_API__Routes]
            RC[Route Config]
            RM[Route Methods]
        end
    end
    
    subgraph "FastAPI Layer"
        APP[FastAPI App]
        ROUTER[API Router]
        HANDLERS[Route Handlers]
    end
    
    CLIENT --> FA
    LAMBDA --> FA
    LOCAL --> FA
    
    FA --> MW1
    FA --> TS
    FA --> HE
    FA --> FAR
    
    FAR --> APP
    APP --> ROUTER
    ROUTER --> HANDLERS
    
    HE --> HEI
    HE --> HEQ
    HE --> HER
    HE --> HET
    
    TS --> TSB
    TS --> BTS
    TS --> TSD
    TS --> DTS
Loading

🔄 Request Lifecycle

sequenceDiagram
    participant C as Client
    participant MW as Middleware Stack
    participant TS as Type Converter
    participant H as Handler
    participant E as Event System
    
    C->>MW: HTTP Request
    MW->>MW: Detect_Disconnect check
    MW->>E: Create Http_Event
    E->>E: Capture request data
    MW->>MW: API Key validation
    MW->>TS: Convert BaseModel to Type_Safe
    TS->>H: Call handler with Type_Safe
    H->>H: Process request
    H->>TS: Return Type_Safe response
    TS->>MW: Convert to BaseModel
    MW->>E: Capture response data
    E->>E: Store event (max 50)
    MW->>C: HTTP Response
Loading

🧩 Core Components

Fast_API Class

The main controller that orchestrates all components:

classDiagram
    class Fast_API {
        +str base_path
        +bool enable_cors
        +bool enable_api_key
        +bool default_routes
        +Fast_API__Http_Events http_events
        +Random_Guid server_id
        
        +setup()
        +add_route_get(function)
        +add_route_post(function)
        +add_routes(class_routes)
        +setup_middlewares()
        +app()
        +routes()
        +client()
    }
    
    Fast_API --|> Type_Safe
    Fast_API *-- Fast_API__Http_Events
    Fast_API ..> FastAPI : creates
    Fast_API ..> Fast_API__Routes : manages
Loading

Responsibilities:

  • FastAPI application lifecycle
  • Middleware chain configuration
  • Route registration and management
  • HTTP event coordination
  • Global exception handling

Fast_API__Routes Class

Base class for organizing routes with automatic Type-Safe conversion:

classDiagram
    class Fast_API__Routes {
        +APIRouter router
        +FastAPI app
        +str prefix
        +str tag
        
        +add_route(function, methods)
        +add_route_with_body(function, methods)
        +add_route_get(function)
        +add_route_post(function)
        +parse_function_name(function_name)
        +setup_routes()
    }
    
    Fast_API__Routes --|> Type_Safe
    Fast_API__Routes --> APIRouter
    Fast_API__Routes --> FastAPI
Loading

Route Path Generation Algorithm:

# Function name to path conversion
an_post()           → /an-post
get_user()          → /get-user
users__id()         → /users/{id}
users__id_profile() → /users/{id}/profile

HTTP Events System

Comprehensive request/response tracking:

graph LR
    subgraph "Http Event"
        EVENT[Fast_API__Http_Event]
        EVENT --> INFO[Event Info<br/>- timestamp<br/>- client IP<br/>- thread ID]
        EVENT --> REQ[Request<br/>- method<br/>- path<br/>- headers<br/>- duration]
        EVENT --> RESP[Response<br/>- status<br/>- headers<br/>- content type]
        EVENT --> TRACE[Traces<br/>- call stack<br/>- execution path]
    end
Loading

Event Storage:

  • Circular buffer (deque) with max 50 events
  • FIFO eviction policy
  • Automatic sensitive data cleaning

🔐 Middleware Architecture

Middleware Pipeline

graph TD
    REQ[Incoming Request]
    
    subgraph "Middleware Stack"
        MD[Detect_Disconnect<br/>Monitor client connection]
        MH[Http_Request<br/>Event tracking]
        MC[CORS<br/>Cross-origin headers]
        MA[API_Key_Check<br/>Authentication]
        
        MD --> MH
        MH --> MC
        MC --> MA
    end
    
    HANDLER[Route Handler]
    RESP[Response]
    
    REQ --> MD
    MA --> HANDLER
    HANDLER --> RESP
Loading

Middleware Responsibilities

Middleware Purpose Configuration
Detect_Disconnect Monitor client disconnections Always enabled
Http_Request Track HTTP events Always enabled
CORS Handle cross-origin requests enable_cors=True
API_Key_Check Validate API keys enable_api_key=True

🔄 Type Conversion System

Conversion Matrix

graph TD
    TS[Type_Safe Class]
    BM[BaseModel]
    DC[Dataclass]
    
    TS -->|Type_Safe__To__BaseModel| BM
    BM -->|BaseModel__To__Type_Safe| TS
    TS -->|Type_Safe__To__Dataclass| DC
    DC -->|Dataclass__To__Type_Safe| TS
    BM -->|BaseModel__To__Dataclass| DC
    DC -->|Dataclass__To__BaseModel| BM
Loading

Conversion Process

sequenceDiagram
    participant API as FastAPI
    participant Conv as Converter
    participant Cache as Model Cache
    participant Handler as Route Handler
    
    API->>Conv: Request with JSON
    Conv->>Cache: Check for cached model
    
    alt Model Cached
        Cache-->>Conv: Return cached BaseModel class
    else Model Not Cached
        Conv->>Conv: Generate BaseModel class
        Conv->>Cache: Store in cache
    end
    
    Conv->>Conv: Instantiate with data
    Conv->>Handler: Type_Safe instance
    Handler->>Conv: Type_Safe response
    Conv->>API: BaseModel response
Loading

📊 Performance Characteristics

Operation Complexity

Operation Time Space Notes
Route registration O(1) O(1) Direct dictionary insertion
Type conversion (cached) O(1) O(1) Cache lookup
Type conversion (new) O(n) O(n) n = number of fields
Event tracking O(1) O(1) Deque operations
Middleware chain O(m) O(1) m = number of middleware

Memory Management

  • Model Cache: Singleton pattern, shared across instances
  • Event Buffer: Maximum 50 events, ~10KB per event
  • Route Registry: Lazy loading, minimal overhead

🛡️ Security Architecture

API Key Validation

sequenceDiagram
    participant Client
    participant Middleware
    participant Env
    
    Client->>Middleware: Request with API key
    Middleware->>Env: Get expected key
    
    alt Header contains key
        Middleware->>Middleware: Validate header
    else Cookie contains key
        Middleware->>Middleware: Validate cookie
    else No key found
        Middleware-->>Client: 401 Unauthorized
    end
    
    alt Key valid
        Middleware->>Handler: Continue
    else Key invalid
        Middleware-->>Client: 401 Unauthorized
    end
Loading

Data Sanitization

  • Automatic cookie removal from logged headers
  • Auth header masking in events
  • Stack trace prevention in production

🔧 Extension Points

Custom Middleware

class Custom_Fast_API(Fast_API):
    def setup_middlewares(self):
        super().setup_middlewares()
        # Add custom middleware here
        self.app().add_middleware(CustomMiddleware)

Custom Routes

class Custom_Routes(Fast_API__Routes):
    def setup_routes(self):
        # Add routes with Type-Safe support
        self.add_route_get(self.custom_method)

Event Callbacks

fast_api.http_events.callback_on_request = handle_request
fast_api.http_events.callback_on_response = handle_response

🚀 Deployment Patterns

Local Development

Fast_API → Uvicorn → Local Server

AWS Lambda

Fast_API → Mangum → Lambda Handler → API Gateway

Docker Container

Fast_API → Uvicorn → Docker → Container Service

📈 Scalability Considerations

  • Stateless Design: No shared state between requests
  • Cache Efficiency: Model caching reduces CPU overhead
  • Event Buffer: Fixed memory footprint
  • Middleware Performance: O(1) operations per middleware

🔍 Monitoring & Observability

Built-in monitoring through:

  • Request correlation IDs
  • Execution traces
  • Duration measurements
  • Thread tracking
  • Event history