Extensions

pyserve uses a modular extension system for adding functionality. Extensions are loaded in order and can process requests and modify responses.

Built-in Extensions

`process_orchestration`	Run ASGI/WSGI apps in isolated processes with health monitoring
`routing`	nginx-style URL routing with regex patterns
`asgi`	Mount ASGI/WSGI applications in-process
`security`	Security headers and IP filtering
`caching`	Response caching (in development)
`monitoring`	Request metrics and statistics

Extension Configuration

Extensions are configured in the extensions section:

extensions:
  - type: routing
    config:
      # extension-specific configuration
  
  - type: security
    config:
      # ...

Routing Extension

The primary extension for URL routing. See Routing Guide for full documentation.

- type: routing
  config:
    regex_locations:
      "=/health":
        return: "200 OK"
      "~^/api/":
        proxy_pass: "http://backend:9001"
      "__default__":
        root: "./static"

Security Extension

Adds security headers and IP-based access control.

Configuration Options

security_headers: Dictionary of security headers to add to all responses
allowed_ips: List of allowed IP addresses (whitelist mode)
blocked_ips: List of blocked IP addresses (blacklist mode)

- type: security
  config:
    security_headers:
      X-Frame-Options: DENY
      X-Content-Type-Options: nosniff
      X-XSS-Protection: "1; mode=block"
      Strict-Transport-Security: "max-age=31536000"
    blocked_ips:
      - "192.168.1.100"
      - "10.0.0.50"

Default security headers if not specified:

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block

Caching Extension

Response caching for improved performance. (Currently in development)

Configuration Options

cache_patterns: URL patterns to cache
cache_ttl: Default cache TTL in seconds. Default: 3600

- type: caching
  config:
    cache_ttl: 3600
    cache_patterns:
      - "/api/public/*"

Monitoring Extension

Collects request metrics and provides statistics.

Configuration Options

enable_metrics: Enable metrics collection. Default: true

- type: monitoring
  config:
    enable_metrics: true

Collected metrics (available at /metrics):

request_count — Total number of requests
error_count — Number of requests with 4xx/5xx status
error_rate — Error rate (errors / total)
avg_response_time — Average response time in seconds

Built-in Endpoints

pyserve provides built-in endpoints regardless of extensions:

`/health`	Health check endpoint, returns `200 OK`
`/metrics`	JSON metrics from all extensions

Extension Processing Order

Extensions process requests in the order they are defined:

Request comes in
Each extension's process_request is called in order
First extension to return a response wins
Response passes through each extension's process_response
Response is sent to client

Note: Place the routing extension last if you want other extensions (like security) to process requests first.

ASGI Extension

Mount external ASGI/WSGI applications (FastAPI, Flask, Django, etc.) at specified paths.

Configuration Options

mounts: List of mount configurations (see below)

Mount Configuration

path: URL path where the app will be mounted. Example: /api
app_path: Python import path. Format: module:attribute
app_type: Application type: asgi or wsgi. Default: asgi
module_path: Optional path to add to sys.path
factory: If true, call as factory function. Default: false
factory_args: Arguments to pass to factory function
name: Friendly name for logging
strip_path: Remove mount path from request URL. Default: true
django_settings: Django settings module (for Django apps only)

- type: asgi
  config:
    mounts:
      # FastAPI application
      - path: "/api"
        app_path: "myapp.api:app"
        app_type: asgi
        name: "api"
      
      # Flask application (WSGI)
      - path: "/admin"
        app_path: "myapp.admin:app"
        app_type: wsgi
        name: "admin"
      
      # Factory pattern with arguments
      - path: "/api/v2"
        app_path: "myapp.api:create_app"
        factory: true
        factory_args:
          debug: true
          version: "2.0"

Supported frameworks:

FastAPI — Native ASGI (app_type: asgi)
Starlette — Native ASGI (app_type: asgi)
Flask — WSGI, auto-wrapped (app_type: wsgi)
Django — Use django_settings parameter
Custom ASGI — Any ASGI-compatible application

Note: For WSGI applications, install a2wsgi or asgiref: pip install a2wsgi

See ASGI Mounting Guide for detailed documentation.

Process Orchestration Extension

The flagship extension for running apps in isolated subprocesses. Recommended for production.

Key Features

Process isolation — each app runs in its own subprocess
Health monitoring with automatic restart
Multi-worker support per application
Dynamic port allocation (9000-9999)
Request tracing with X-Request-ID

- type: process_orchestration
  config:
    port_range: [9000, 9999]
    health_check_enabled: true
    proxy_timeout: 60.0
    logging:
      httpx_level: warning
      proxy_logs: true
      health_check_logs: false
    apps:
      - name: api
        path: /api
        app_path: myapp.api:app
        workers: 4
        health_check_path: /health
      
      - name: admin
        path: /admin
        app_path: myapp.admin:app
        app_type: wsgi
        workers: 2

App Configuration

name: Unique identifier (required)
path: URL path prefix (required)
app_path: Python import path (required)
app_type: asgi or wsgi. Default: asgi
workers: Number of uvicorn workers. Default: 1
health_check_path: Health endpoint. Default: /health
max_restart_count: Max restart attempts. Default: 5

See Process Orchestration Guide for full documentation.