genro-asgi 0.2.0

A minimal, stable ASGI foundation - framework-agnostic toolkit for building high-performance web services

Genro ASGI

A minimal, stable ASGI foundation - framework-agnostic toolkit for building high-performance web services.

Overview

Genro ASGI provides a minimal, production-ready ASGI server and application toolkit built on top of genro-routes for routing. It offers essential components for building web services with full type safety.

Key Features

• Minimal Core: Essential components only, no bloat
• Router Integration: Uses genro-routes for flexible, decorator-based routing
• MCP Support: Built-in MCP Streamable HTTP transport via McpApplication
• Production-Ready: Tested, typed, and stable
• Type-Safe: Full type hints throughout
• Essential Components:
  • ASGI server with config-driven application mounting
  • HTTP request/response utilities
  • Lifespan management
  • Middleware (authentication, CORS, errors, compression, cache, logging)
  • Static file serving via StaticRouter
  • WebSocket support with WSX extension protocol
  • Filesystem storage with mount system

Installation

# Basic installation
pip install genro-asgi

# With fast JSON support
pip install genro-asgi[json]

# Development installation
pip install genro-asgi[dev]

# Documentation build
pip install genro-asgi[docs]

Quick Start

CLI - Serve static files

# Create config.yaml
cat > config.yaml << EOF
server:
  host: "127.0.0.1"
  port: 8000

apps:
  static:
    module: "genro_asgi:StaticRouter"
    directory: "./public"
    index: "index.html"
EOF

# Run server
python -m genro_asgi serve .

Python - Custom server

from genro_asgi import AsgiServer

server = AsgiServer(server_dir=".")
server.run()  # Starts uvicorn

Architecture

Genro ASGI is designed around these principles:

1. Instance Isolation: Server and apps are isolated instances, not global functions
2. Composability: Mix and match components as needed
3. Type Safety: Full type hints throughout
4. Dual Parent-Child: Child objects hold a semantic reference to their parent

Core Components

• AsgiServer: ASGI entry point, loads config, mounts apps
• AsgiApplication: Base class for mountable applications
• McpApplication: MCP Streamable HTTP transport
• HttpRequest: HTTP request wrapper with headers, query, body
• Response: HTTP response with auto content-type detection
• Lifespan / ServerLifespan: Startup/shutdown event management
• Dispatcher: Request routing and dispatch
• StaticRouter: Filesystem-backed static file serving
• LocalStorage: Filesystem storage with mount system

Middleware

• AuthMiddleware: O(1) authentication (bearer, basic, JWT)
• CORSMiddleware: Cross-Origin Resource Sharing headers
• ErrorMiddleware: Exception handling and error responses
• CompressionMiddleware: Gzip response compression
• CacheMiddleware: HTTP response caching
• LoggingMiddleware: Request/response logging

Documentation

Full documentation available at: https://genro-asgi.readthedocs.io

Development

Setup

# Clone repository
git clone https://github.com/genropy/genro-asgi.git
cd genro-asgi

# Install in development mode
pip install -e .[dev]

Testing

# Run tests
pytest

# With coverage
pytest --cov=genro_asgi --cov-report=html

Code Quality

# Lint code
ruff check .

# Type check
mypy src

License

This project is licensed under the Apache License 2.0.

Copyright © 2025-2026 Softwell S.r.l.

You may obtain a copy of the license at:

https://www.apache.org/licenses/LICENSE-2.0

This project may include third-party components distributed under separate open-source licenses. See the NOTICE file for additional attribution.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Links

• GitHub: https://github.com/genropy/genro-asgi
• PyPI: https://pypi.org/project/genro-asgi/
• Documentation: https://genro-asgi.readthedocs.io
• Issue Tracker: https://github.com/genropy/genro-asgi/issues

Credits

Developed by Softwell S.r.l.