Metadata-Version: 2.4
Name: routemq
Version: 0.22.1
Summary: A flexible MQTT routing framework with middleware support
Project-URL: Homepage, https://github.com/ardzz/RouteMQ
Project-URL: Repository, https://github.com/ardzz/RouteMQ
Project-URL: Documentation, https://github.com/ardzz/RouteMQ/tree/master/docs
Project-URL: Changelog, https://github.com/ardzz/RouteMQ/blob/master/CHANGELOG.md
Project-URL: Issues, https://github.com/ardzz/RouteMQ/issues
Project-URL: Security, https://github.com/ardzz/RouteMQ/security/policy
Author-email: Naufal Reky Ardhana <rekyardhana029@gmail.com>
License: MIT
License-File: LICENSE
Keywords: async,framework,middleware,mqtt,queue,redis,routing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.12
Requires-Dist: aiomysql>=0.2.0
Requires-Dist: ipython>=8.20.0
Requires-Dist: nest-asyncio>=1.5.8
Requires-Dist: paho-mqtt>=2.0.0
Requires-Dist: psutil>=5.9.6
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: sqlalchemy>=2.0.23
Provides-Extra: all
Requires-Dist: clickhouse-connect[async]>=1.1.1; extra == 'all'
Requires-Dist: jinja2>=3.1.0; extra == 'all'
Requires-Dist: prometheus-client>=0.22; extra == 'all'
Requires-Dist: questionary>=2.0.0; extra == 'all'
Requires-Dist: redis>=5.0.1; extra == 'all'
Requires-Dist: rich-pyfiglet>=1.0.0; extra == 'all'
Requires-Dist: rich>=14.0.0; extra == 'all'
Provides-Extra: cli
Requires-Dist: jinja2>=3.1.0; extra == 'cli'
Requires-Dist: questionary>=2.0.0; extra == 'cli'
Requires-Dist: rich-pyfiglet>=1.0.0; extra == 'cli'
Requires-Dist: rich>=14.0.0; extra == 'cli'
Provides-Extra: clickhouse
Requires-Dist: clickhouse-connect[async]>=1.1.1; extra == 'clickhouse'
Provides-Extra: dev
Requires-Dist: bandit>=1.8.0; extra == 'dev'
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: commitizen>=3.12.0; extra == 'dev'
Requires-Dist: coverage>=7.6.0; extra == 'dev'
Requires-Dist: cyclonedx-bom>=5.2.0; extra == 'dev'
Requires-Dist: jinja2>=3.1.0; extra == 'dev'
Requires-Dist: mypy>=1.14.0; extra == 'dev'
Requires-Dist: pip-audit>=2.8.0; extra == 'dev'
Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
Requires-Dist: pytest-async-benchmark<1,>=0.2; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.1; extra == 'dev'
Requires-Dist: pytest-benchmark<5,>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.4.3; extra == 'dev'
Requires-Dist: questionary>=2.0.0; extra == 'dev'
Requires-Dist: rich-pyfiglet>=1.0.0; extra == 'dev'
Requires-Dist: rich>=14.0.0; extra == 'dev'
Requires-Dist: ruff>=0.9.0; extra == 'dev'
Requires-Dist: testcontainers[mqtt,mysql,redis]<5,>=4.14.2; extra == 'dev'
Requires-Dist: vulture>=2.13; extra == 'dev'
Provides-Extra: prometheus
Requires-Dist: prometheus-client>=0.22; extra == 'prometheus'
Provides-Extra: redis
Requires-Dist: redis>=5.0.1; extra == 'redis'
Description-Content-Type: text/markdown

<img alt="logo.png" height="200" src="logo.png" width="200"/>

# RouteMQ Framework

[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ardzz/RouteMQ/badge)](https://scorecard.dev/viewer/?uri=github.com/ardzz/RouteMQ)

<!-- TODO(sprint-15-followup): replace <PROJECT_ID> after submitting at https://www.bestpractices.dev/en/projects/new
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/<PROJECT_ID>/badge)](https://www.bestpractices.dev/projects/<PROJECT_ID>)
-->

A flexible MQTT routing framework with middleware, dynamic routes, queue workers, Redis integration, and horizontal scaling — inspired by Laravel/Django web frameworks.

## Quick Start

### 1. Install

```bash
pip install routemq[cli]
```

### 2. Scaffold a new project

```bash
routemq new my-app
cd my-app
```

The scaffolder asks about optional features (MySQL, Redis, background queue, Docker). Use `--yes` to accept defaults non-interactively.

### 3. Run

```bash
# Edit .env with your MQTT broker details
routemq run
```

## Features

- **Dynamic Router Loading** - Automatically discover and load routes from multiple files
- **Route-based MQTT topic handling** - Define routes for MQTT topics
- **Middleware support** - Process messages through middleware chains
- **Parameter extraction** - Extract variables from MQTT topics using Laravel-style syntax
- **Background Task Queue** - Laravel-style queue system for async job processing
- **Shared Subscriptions** - Horizontal scaling with worker processes
- **Redis Integration** - Optional Redis support for distributed caching and rate limiting
- **Advanced Rate Limiting** - Multiple rate limiting strategies with Redis backend
- **Optional MySQL integration** - Use with or without a database
- **Docker Support** - Production-ready Docker Compose setup with queue workers
- **Environment-based configuration** - Configuration through .env files

## Documentation

**Documentation is available in the [docs](./docs) folder, optimized for GitBook integration.**

See the [Installation Guide](./INSTALL.md) for detailed setup instructions.

### Quick Links

- **[Getting Started](./docs/getting-started/README.md)** - Installation, quick start, and basic setup
- **[Architecture Overview](./docs/architecture.md)** - High-level runtime components and data flow
- **[Configuration](./docs/configuration/README.md)** - Environment variables and setup options
- **[Routing](./docs/routing/README.md)** - Route definition, parameters, and organization
- **[Controllers](./docs/controllers/README.md)** - Creating and organizing business logic
- **[Middleware](./docs/middleware/README.md)** - Request processing and middleware chains
- **[Queue System](./docs/queue/README.md)** - Background task processing and job queues
- **[Testing](./docs/testing/README.md)** - Unit and Docker-backed integration testing
- **[Docker Deployment](./docs/docker-deployment.md)** - Production deployment with Docker
- **[Redis Integration](./docs/redis/README.md)** - Caching, sessions, and distributed features
- **[Rate Limiting](./docs/rate-limiting/README.md)** - Advanced rate limiting strategies
- **[Examples](./docs/examples/README.md)** - Practical examples and use cases
- **[API Reference](./docs/api-reference/README.md)** - Complete API documentation
- **[Monitoring](./docs/monitoring/README.md)** - Health, readiness, and observability hooks
- **[Release Conformance](./docs/release-conformance.md)** - SLSA, Scorecard, SBOM, and SemVer evidence
- **[FAQ](./docs/faq.md)** - Frequently asked questions

### Project Health

- **[Security Policy](./SECURITY.md)** - Private vulnerability reporting and supported versions
- **[Contributing Guide](./CONTRIBUTING.md)** - Issue reports, pull requests, tests, and coding standards
- **[Code of Conduct](./CODE_OF_CONDUCT.md)** - Community expectations and enforcement
- **[Changelog](./CHANGELOG.md)** - Release history
- **[Issue Tracker](https://github.com/ardzz/RouteMQ/issues)** - Bug reports and feature requests

## Project Structure

Scaffolded projects follow this layout:

```
my-app/
├── app/                    # Your application code
│   ├── controllers/        # Route handlers
│   ├── middleware/         # Custom middleware
│   ├── models/             # Database models
│   ├── jobs/               # Background jobs
│   └── routers/            # Route definitions
├── bootstrap/              # Application bootstrap
├── docker-compose.yml      # Optional Docker setup
├── pyproject.toml          # Project metadata and dependencies
└── .env                    # Environment configuration
```

## Docker Deployment

RouteMQ can scaffold Docker support for Redis, MySQL, app runtime, and queue workers:

```bash
routemq new my-app --with-docker --with-redis --with-mysql --with-queue
cd my-app

# Start services from the scaffolded project
docker compose up -d

# View logs
docker compose logs -f

# Scale workers
docker compose up -d --scale queue-worker-default=5
```

See [Docker Deployment Guide](./docs/docker-deployment.md) for detailed instructions.

## Background Task Queue

Process time-consuming tasks asynchronously with the built-in queue system:

```python
# Create a job
from routemq.job import Job

class SendEmailJob(Job):
    max_tries = 3
    queue = "emails"

    async def handle(self):
        # Send email logic
        pass

# Dispatch the job
from routemq.queue.queue_manager import dispatch

job = SendEmailJob()
job.to = "user@example.com"
await dispatch(job)
```

Run a worker from your scaffolded app:

```bash
routemq queue-work --queue emails
```

See [Queue System Documentation](./docs/queue/README.md) for the complete guide.

## Advanced: Fork the framework

If you want to modify the framework internals directly (rather than depend on the published wheel), see [TEMPLATE.md](./TEMPLATE.md). This path is deprecated as the primary workflow; `pip install routemq[cli]` is recommended for application development.

For direct framework development:

```bash
git clone https://github.com/ardzz/RouteMQ.git
cd RouteMQ
uv sync --all-extras --dev
uv run python run_tests.py
```

## Contributing

We welcome contributions! Please see our documentation for development setup and contribution guidelines.

## License

MIT License - see [LICENSE](LICENSE) file for details.
