# Genro ASGI

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

[![PyPI version](https://img.shields.io/pypi/v/genro-asgi.svg)](https://pypi.org/project/genro-asgi/)
[![Python Support](https://img.shields.io/pypi/pyversions/genro-asgi.svg)](https://pypi.org/project/genro-asgi/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Documentation](https://readthedocs.org/projects/genro-asgi/badge/?version=latest)](https://genro-asgi.readthedocs.io)

## 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

```bash
# 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

```bash
# 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

```python
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

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

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

### Testing

```bash
# Run tests
pytest

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

### Code Quality

```bash
# 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](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.](https://www.softwell.it/)
