Middleware & Decorators

De volgorde van middleware in app.py is belangrijk, omdat elke middleware de request en response kan beïnvloeden voordat deze naar de volgende laag gaat. Hieronder vind je de actuele chain:

Volgorde	Middleware	Doel & Beschrijving
1	error_middleware	Vangt alle exceptions af en zorgt voor consistente foutafhandeling en logging.
2	auth_middleware	Handelt API key authenticatie en origin validatie af voor beveiligde routes.

Decorator chain in app.py:

@app.middleware('http')
def error_handling_middleware(event, get_response):
    return error_middleware(event, get_response)

@app.middleware('http')
def auth_middleware(event, get_response):
    return validate_requestor(event, get_response)

Let op: De volgorde waarin deze decorators in de code staan, bepaalt de volgorde van uitvoering. De eerste decorator wordt als eerste aangeroepen bij een request.

Error Handling Middleware

Functionaliteit

De error handling middleware vangt alle onverwachte fouten op en zorgt voor consistente foutresponses door de hele applicatie. Het onderschept exceptions en converteert ze naar gestandaardiseerde HTTP responses.

Succes requirements

Geen specifieke vereisten - de middleware handelt automatisch alle exceptions af

Foutafhandeling

De error handling middleware zorgt voor consistente foutresponses. Hieronder een voorbeeld van het gestandaardiseerde error response formaat:

400 Bad Request - Validation failed

{
  "error": "Business logic error",
  "message": "Request validation failed",
  "request_id": "abc123def456"
}

Exception Types

ValidationError (422)

Trigger: Pydantic model validatie fouten

Response:

{
  "error": "Validation failed",
  "message": "Request validation failed",
  "details": [
    {
      "type": "missing",
      "loc": ["recipients"],
      "msg": "Field required",
      "input": null
    }
  ],
  "request_id": "abc123def456"
}

ValueError (400)

Trigger: Business logic fouten

Response:

{
  "error": "Business logic error",
  "message": "Request validation failed: recipients field is required",
  "request_id": "abc123def456"
}

Exception (500)

Trigger: Onverwachte fouten

Response:

{
  "error": "Internal server error",
  "request_id": "abc123def456"
}

Implementatievoordelen

Separation of Concerns: Centrale foutafhandeling gescheiden van business logic
Consistency: Uniforme foutresponses door de hele applicatie
Scalability: Eenvoudig nieuwe error types toevoegen via ErrorHandler
Maintainability: Centrale plek voor alle foutafhandeling logica
Transferability: Herbruikbare error handling patterns
Monitoring: Gestructureerde logging voor operationele inzichten

Authenticatie Middleware

Functionaliteit

De authenticatie middleware handelt API key authenticatie en origin validatie af voor alle API endpoints. Het verwerkt API key validatie en controleert toegestane origins.

Publieke Paden

De volgende paden worden als publiek beschouwd en omzeilen authenticatie validatie:

/v1/health
/v1/api-key (POST)
/v1/api-key/{api_key} (DELETE)
/v1/api-key/{api_key}/origins (POST)

Beveiligde Routes Authenticatie

Succes requirements:

Voor alle niet-publieke routes (exclusief API key management endpoints):

x-api-key - API key uit request headers
origin - Origin domain uit request headers

Foutafhandeling:

401 Unauthorized - Missing API key or origin

{
  "status": 401,
  "message": "Unauthorized - Missing API key or origin"
}

401 Unauthorized - Invalid API key or origin

{
  "status": 401,
  "message": "Unauthorized - Invalid API key or origin"
}

API Key Validatie Flow

Validatie Process

Header Extraction: API key en origin worden geëxtraheerd uit request headers
Database Lookup: API key wordt gevalideerd tegen database
Origin Check: Origin wordt gecontroleerd tegen toegestane origins
Cache Check: Validatie resultaat wordt gecached voor 5 minuten
Context Update: Validatie info wordt toegevoegd aan request context

Cache Strategy

TTL: 5 minuten (300 seconden)
Key Format: validate_api_key:{api_key}:{origin}
Invalidation: Automatisch na TTL expiry

Implementatievoordelen

Separation of Concerns: Authenticatie logica gescheiden van business logic
Consistency: Uniforme authenticatie handling voor alle endpoints
Scalability: Eenvoudig nieuwe authenticatie flows toevoegen
Maintainability: Centrale authenticatie configuratie
Transferability: Herbruikbare authenticatie patterns
Security: Gedetailleerde logging voor beveiligingsmonitoring en request tracing via request IDs

Decorators

Functionaliteit

Decorators bieden een declaratieve manier om cross-cutting concerns toe te voegen aan functies en routes. Ze worden gebruikt voor performance monitoring, caching en andere functionaliteiten die op meerdere plekken nodig zijn.

Performance Monitoring Decorator

`@timer(label=None)`

Succes requirements:

Geen specifieke vereisten - de decorator meet automatisch alle functie uitvoeringen

Foutafhandeling:

Geen foutresponses - de decorator faalt nooit
Alle functie uitvoeringen worden gelogd met uitvoeringstijd in milliseconden

Gebruik:

@timer("send_email_service")
def send_email(self, request_dict: dict, publish_status: bool = True):
    # Functie logica hier
    pass

# Of zonder label (gebruikt functienaam)
@timer()
def process_email_from_queue(self, sqs_message: SQSEmailMessageModel):
    # Functie logica hier
    pass

Log Output:

[TIMER] send_email_service took 125.45 ms
[TIMER] process_email_from_queue took 89.23 ms

Caching Decorator

`@cache(ttl=300)`

Succes requirements:

Functie moet deterministisch zijn (zelfde input =zelfde output)
Functie parameters moeten hashable zijn
Cache key wordt gegenereerd op basis van functienaam en parameters

Foutafhandeling:

Geen foutresponses - cache miss leidt tot normale functie uitvoering
Cache errors worden genegeerd en functie wordt normaal uitgevoerd

Gebruik:

@cache(ttl=300)  # 5 minuten cache
def validate_api_key(self, api_key: str, origin: str) -> dict:
    # Functie logica hier
    pass

@cache(ttl=600)  # 10 minuten cache
def get_active_api_keys(self) -> list:
    # Functie logica hier
    pass

Cache Key Format:

validate_api_key:1234567890:example.com
get_active_api_keys:1234567890

Cache Management

`clear_cache()`

Functionaliteit:

Wist alle gecachte items
Handig voor testing of cache invalidation
Thread-safe implementatie

Gebruik:

from chalicelib.utils.decorators import clear_cache

# Clear all cached items
clear_cache()

Implementatievoordelen

Separation of Concerns: Cross-cutting concerns gescheiden van business logic
Consistency: Uniforme performance monitoring en caching
Scalability: Eenvoudig nieuwe decorators toevoegen voor andere concerns
Maintainability: Centrale plek voor alle decorator logica
Transferability: Herbruikbare decorator patterns
Monitoring: Gestructureerde logging voor performance tracking
Performance: Caching vermindert database calls en verbetert response times

Middleware Best Practices

Error Handling

No Try-Catch in Controllers: Laat errors bubblen naar error middleware
Service Layer Error Handling: Services mogen wel try-catch gebruiken voor business logic
Consistent Error Format: Alle errors volgen hetzelfde response formaat
Request ID Tracking: Alle errors bevatten request ID voor tracing

Authentication

Cache API Key Validation: Vermindert database calls
Origin Validation: Controleert toegestane domains
Structured Logging: Logt alle authenticatie events
Context Propagation: Voegt validatie info toe aan request context

Performance

Timer Decorators: Meet kritieke functie uitvoeringen
Cache Decorators: Cache expensive operations
Minimal Middleware: Houd middleware chain kort en efficiënt
Async Considerations: Middleware is synchroon, services kunnen async zijn

Testing

Mock Middleware: Test controllers zonder middleware
Integration Tests: Test volledige middleware chain
Error Scenarios: Test alle error paths
Performance Tests: Meet middleware overhead