microcorex 0.0.2
Python microservices framework core library providing configuration management, service lifecycle, gRPC support and more
License: MIT
Requires Python: >=3.8
Keywords: microcorex, grpc, fastapi, nacos, configuration

<div align="center">
  <h1>MicroCoreX</h1>
  <p>
    <strong>A powerful Python microservices framework core library with dual protocol support (FastAPI + gRPC)</strong>
  </p>

  <p>
    <a href="https://pypi.org/project/microcorex/"><img src="https://img.shields.io/pypi/v/microcorex.svg" alt="PyPI version"></a>
    <a href="https://pypi.org/project/microcorex/"><img src="https://img.shields.io/pypi/pyversions/microcorex.svg" alt="Python versions"></a>
    <a href="https://github.com/codexiaoke/microcorex/blob/master/LICENSE"><img src="https://img.shields.io/github/license/codexiaoke/microcorex.svg" alt="License"></a>
    <a href="https://github.com/codexiaoke/microcorex/stargazers"><img src="https://img.shields.io/github/stars/codexiaoke/microcorex.svg" alt="GitHub stars"></a>
  </p>

  <p>
    <a href="#key-features">Features</a> •
    <a href="#installation">Installation</a> •
    <a href="#quick-start">Quick Start</a> •
    <a href="#documentation">Documentation</a> •
    <a href="#examples">Examples</a>
  </p>

  <p>
    <strong>
      <a href="README.md">English</a> | 
      <a href="README_zh.md">简体中文</a>
    </strong>
  </p>
</div>

## 📖 About

**MicroCoreX** is a production-ready Python microservices framework that provides comprehensive infrastructure for building scalable, maintainable microservices applications. It seamlessly integrates **FastAPI** and **gRPC** to deliver dual protocol support, enabling both high-performance RPC communication and RESTful API development in a single unified framework.

The framework is built on top of industry-standard technologies and follows best practices for microservices architecture, including service discovery, configuration management, authentication, observability, and resilience patterns.

## ✨ Key Features

### 🚀 Dual Protocol Support
Run **FastAPI** (HTTP/REST) and **gRPC** servers concurrently in the same process, allowing you to serve both web APIs and high-performance RPC calls with minimal overhead.

### ⚙️ Powerful Configuration Management
- **Multi-environment support**: Separate YAML configuration files for dev, test, staging, and production
- **Nacos integration**: Remote configuration center with hot reload capabilities
- **Type-safe configuration**: Pydantic-based configuration models with built-in validation
- **Configuration change listeners**: React to configuration updates in real-time

### 🛰️ Service Discovery & Registration
- **Automatic service registration**: HTTP and gRPC services auto-register with Nacos on startup
- **Health monitoring**: Built-in heartbeat mechanism for ephemeral instances
- **Service metadata**: Rich metadata support for service versioning and environment tagging
- **Graceful deregistration**: Clean service removal on shutdown

### 🔐 Security & Authentication
- **JWT authentication**: Built-in JWT token generation, validation, and refresh token support
- **Security middleware**: Whitelist-based URL filtering and automatic token verification
- **Sensitive data protection**: Automatic masking of passwords, keys, and credentials in logs
- **Production-ready defaults**: Enforced secure configurations for production environments

### 🔭 Observability
- **Structured logging**: Loguru-based logging with automatic rotation and formatting
- **Request tracing**: Comprehensive request/response logging with timing information
- **Sensitive data filtering**: Automatic removal of sensitive information from logs
- **Internationalization (i18n)**: Built-in support for multi-language applications

### 💪 Resilience & Reliability
- **Exponential backoff retry**: Automatic retry with configurable backoff for Nacos operations
- **Graceful shutdown**: Proper cleanup of resources and service deregistration
- **Error handling**: Structured error management with sanitization and categorization
- **Circuit breaker patterns**: Built-in support for gRPC client resilience

### 🧑‍💻 Developer Experience
- **Minimal boilerplate**: Simple, intuitive API that reduces repetitive code
- **Type safety**: Full Pydantic integration for configuration and domain objects
- **Comprehensive examples**: Real-world example services demonstrating best practices
- **Extensible architecture**: Easy to customize and extend with your own components

## 🏗️ Architecture

MicroCoreX follows a modular architecture with clear separation of concerns:

```
┌─────────────────────────────────────────────────────────────┐
│                        AppService                           │
│  (Unified Service Lifecycle Management)                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │   FastAPI    │  │     gRPC     │  │    Nacos     │    │
│  │   Server     │  │    Server    │  │  Registrar   │    │
│  └──────────────┘  └──────────────┘  └──────────────┘    │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│                     Middleware Layer                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │   Security   │  │   Logging    │  │     i18n     │    │
│  │  Middleware  │  │  Middleware  │  │  Middleware  │    │
│  └──────────────┘  └──────────────┘  └──────────────┘    │
├─────────────────────────────────────────────────────────────┤
│                      Core Services                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │    Config    │  │     JWT      │  │   Service    │    │
│  │    Loader    │  │   Manager    │  │   Registry   │    │
│  └──────────────┘  └──────────────┘  └──────────────┘    │
└─────────────────────────────────────────────────────────────┘
```

### Core Components

| Component | Description |
|-----------|-------------|
| **AppService** | Central orchestrator managing the complete service lifecycle, including initialization, startup, and graceful shutdown of both FastAPI and gRPC servers. |
| **ConfigLoader** | Loads configuration from local YAML files and Nacos, with support for hot reload and configuration change notifications. |
| **NacosRegistrar** | Handles service registration and discovery with Nacos, including automatic heartbeat management and retry mechanisms. |
| **GrpcServerBase** | Abstract base class for gRPC servers with QoS configuration (message size limits, keepalive, compression). |
| **GrpcClientBase** | Base class for gRPC clients with connection pooling, service discovery, and resilience patterns. |
| **JwtManager** | Provides JWT token creation, verification, and refresh token management with configurable expiration policies. |
| **Middlewares** | Pluggable middleware stack for logging, security, and internationalization. |
| **Domain Objects** | Standard response wrapper (`R`), pagination models (`PageVo`, `PageQo`), and utility functions. |

## 📦 Installation

### Prerequisites

- Python 3.8 or higher
- Nacos 2.x (optional, for service discovery and configuration management)

### Install from PyPI

```bash
pip install microcorex
```

### Install from source

```bash
git clone https://github.com/codexiaoke/microcorex.git
cd microcorex
pip install -e .
```

## 🚀 Quick Start

### 1. Create a Simple Service

Create a file named `main.py`:

```python
import asyncio
from fastapi import FastAPI
from microcorex import (
    AppService, 
    ConfigLoader,
    load_i18n_middleware,
    load_logging_middleware,
    load_security_middleware
)

# Create FastAPI application with middleware
app = FastAPI(
    title="My Awesome Service",
    description="A microservice built with MicroCoreX",
    version="1.0.0",
    middleware=[
        load_i18n_middleware(),
        load_logging_middleware(),
        load_security_middleware()
    ]
)

@app.get("/")
def read_root():
    return {"message": "Hello, MicroCoreX!"}

@app.get("/health")
def health_check():
    return {"status": "healthy"}

if __name__ == "__main__":
    async def main():
        # Load configuration
        config_loader = ConfigLoader()
        config = await config_loader.load_config()
        
        # Create and start AppService
        app_service = AppService(
            fastapi_app=app,
            config=config,
            config_loader=config_loader
        )
        await app_service.start()
    
    asyncio.run(main())
```

### 2. Create Configuration File

Create `config/config_dev.yaml` in the same directory:

```yaml
app:
  name: my-awesome-service
  env: dev
  logLevel: INFO

server:
  servicePort: 8001
  grpcPort: 8002

nacos:
  host: localhost
  port: 8848
  namespace: public
  groupName: DEFAULT_GROUP

jwt:
  secretKey: your-secret-key-change-in-production
  accessTokenExpireMinutes: 30
  refreshTokenExpireDays: 7

security:
  whiteUrls:
    - /
    - /health
    - /docs
    - /openapi.json
```

### 3. Run the Service

```bash
python main.py
```

Your service is now running at:
- HTTP API: `http://127.0.0.1:8001`
- gRPC: `127.0.0.1:8002`
- API Documentation: `http://127.0.0.1:8001/docs`

## 💡 Usage Examples

### Configuration Management

MicroCoreX uses Pydantic models for type-safe configuration:

```python
from microcorex import MicroCoreConfig, ConfigLoader

# Load configuration with custom config class
class MyConfig(MicroCoreConfig):
    # Add your custom configuration fields
    custom_field: str = "default_value"

config_loader = ConfigLoader(config_class=MyConfig)
config = await config_loader.load_config()

# Access configuration
print(config.app.name)
print(config.server.servicePort)
print(config.custom_field)
```

### Service Discovery

Services automatically register with Nacos on startup:

```python
from microcorex import AppService, NacosRegistrar

# AppService handles registration automatically
app_service = AppService(
    fastapi_app=app,
    config=config
)
await app_service.start()

# Services are registered as:
# - HTTP: {app.name} at {server.ip}:{server.servicePort}
# - gRPC: {app.name}-grpc at {server.ip}:{server.grpcPort}
```

### gRPC Integration

Create a gRPC server by extending `GrpcServerBase`:

```python
from microcorex import GrpcServerBase
import grpc

class MyGrpcService(GrpcServerBase):
    def register_services(self, server: grpc.aio.Server):
        # Register your gRPC services here
        # Example:
        # my_service_pb2_grpc.add_MyServiceServicer_to_server(
        #     MyServiceImplementation(), server
        # )
        pass

# Use with AppService
grpc_service = MyGrpcService(config)
app_service = AppService(
    fastapi_app=app,
    grpc_server=grpc_service,
    config=config
)
```

### JWT Authentication

```python
from microcorex import get_jwt_manager, JWTError

# Create tokens
jwt_manager = get_jwt_manager()
user_data = {"user_id": 123, "username": "john"}

# Create access and refresh tokens
token_pair = jwt_manager.create_token_pair(user_data)
# Returns: {
#   "access_token": "...",
#   "refresh_token": "...",
#   "token_type": "bearer",
#   "expires_in": 1800
# }

# Verify token
try:
    user_data = jwt_manager.verify_token(
        token_pair["access_token"], 
        token_type="access"
    )
    print(f"Authenticated user: {user_data['username']}")
except JWTError as e:
    print(f"Authentication failed: {e.message}")
```

### gRPC Client

```python
from microcorex import GrpcClientBase, ServiceRegistry

# Initialize service registry
ServiceRegistry.init(config)

# Create gRPC client
class UserServiceClient(GrpcClientBase):
    def __init__(self):
        super().__init__(
            service_name="user-service-grpc",
            stub_class=UserServiceStub
        )
    
    def get_user(self, user_id: int):
        return self.call_unary(
            method_name="GetUser",
            request=GetUserRequest(user_id=user_id)
        )

# Use the client
client = UserServiceClient()
user = client.get_user(123)
```

## 📚 Documentation

For detailed documentation, please visit:

- **Configuration Guide**: Learn about configuration management and Nacos integration
- **Service Development**: Best practices for building microservices with MicroCoreX
- **gRPC Guide**: Complete guide to gRPC server and client development
- **Security**: JWT authentication and security middleware configuration
- **API Reference**: Complete API documentation

## 🎯 Examples

Check out the `example/` directory for complete working examples:

- **member_service**: Demonstrates HTTP API with gRPC client calls
- **system_service**: Shows gRPC server implementation and service discovery

Run the examples:

```bash
cd example/services/member_service
python member_service.py
```

## 🗺️ Roadmap

- [ ] Enhanced async database support (SQLAlchemy async)
- [ ] Distributed task queue integration (Celery/RQ)
- [ ] Advanced circuit breaker and rate limiting
- [ ] Metrics and monitoring integration (Prometheus)
- [ ] Service mesh support (Istio)
- [ ] GraphQL support
- [ ] More comprehensive examples and tutorials

See the [open issues](https://github.com/codexiaoke/microcorex/issues) for a full list of proposed features and known issues.

## 🤝 Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

Please make sure to update tests as appropriate and follow the existing code style.

## 📄 License

Distributed under the MIT License. See `LICENSE` for more information.

## 👤 Author

**xiaoke**
- Email: codexiaoke@126.com
- GitHub: [@codexiaoke](https://github.com/codexiaoke)

## 🙏 Acknowledgments

MicroCoreX stands on the shoulders of giants. Special thanks to:

- [FastAPI](https://fastapi.tiangolo.com/) - Modern, fast web framework for building APIs
- [gRPC](https://grpc.io/) - High-performance RPC framework
- [Nacos](https://nacos.io/) - Dynamic service discovery and configuration management
- [Pydantic](https://docs.pydantic.dev/) - Data validation using Python type annotations
- [Loguru](https://loguru.readthedocs.io/) - Python logging made simple
- [PyJWT](https://pyjwt.readthedocs.io/) - JSON Web Token implementation
- [SQLAlchemy](https://www.sqlalchemy.org/) - SQL toolkit and ORM

---

<div align="center">
  <sub>Built with ❤️ by <a href="https://github.com/codexiaoke">xiaoke</a></sub>
</div>