gRPC Integration

Production-Ready gRPC Server Build high-performance gRPC APIs with full Django integration - ORM, authentication, admin interface, and automatic service discovery.

🎯 What is This?

Django-CFG provides a complete gRPC server that integrates seamlessly with Django:

✅ Async Support - High-concurrency async server with streaming (1000+ concurrent requests)
✅ Auto-Discovery - Services automatically registered from Django apps
✅ Django Integration - Full ORM, auth, admin, signals access
✅ API Key Authentication - Simple, secure API key management with admin interface
✅ Request Logging - All requests logged to database with API key tracking
✅ Server Monitoring - Real-time server status and uptime tracking
✅ REST API - Monitor services and manage API keys via REST endpoints
✅ Production-Ready - Interceptors, error handling, monitoring
✅ Developer-Friendly - Base classes, helpers, zero configuration

🚀 Quick Start

1. Install


pip install django-cfg[grpc]

2. Enable in Config


# api/config.py
from django_cfg import DjangoConfig, GRPCConfig, GRPCServerConfig
 
class MyConfig(DjangoConfig):
    grpc = GRPCConfig(
        enabled=True,
        server=GRPCServerConfig(
            host="[::]",
            port=50051,
        ),
        enabled_apps=["apps.users", "apps.products"],
    )

3. Create Service


# apps/users/grpc_services.py
from django_cfg.apps.integrations.grpc.services import BaseService
from django.contrib.auth import get_user_model
 
User = get_user_model()
 
class UserService(BaseService):
    def GetUser(self, request, context):
        user = User.objects.get(id=request.user_id)
        return UserResponse(
            id=user.id,
            username=user.username,
            email=user.email,
        )

4. Start Server


python manage.py rungrpc

Output:


🚀 Starting gRPC server...
📡 Server running at [::]:50051
✅ Registered 1 service: api.users.UserService

5. Test


grpcurl -plaintext -d '{"user_id": 1}' \
  localhost:50051 api.users.UserService/GetUser

That’s it! Your gRPC service is running. 🎉

🏗️ Architecture

🎯 Key Features

Auto-Discovery

Services are automatically discovered from your Django apps:


# No registration needed! Just create the file:
# apps/users/grpc_services.py
 
class UserService(BaseService):
    def GetUser(self, request, context):
        # Automatically discovered and registered
        pass

Discovery locations:

app/grpc_services.py ✅
app/grpc_handlers.py ✅
app/services/grpc.py ✅

Django Integration

Full access to Django features:


class OrderService(BaseService):
    def CreateOrder(self, request, context):
        # Django ORM
        user = self.require_user(context)  # From API key
        order = Order.objects.create(user=user)
 
        # Django signals
        order_created.send(sender=Order, instance=order)
 
        # Django cache
        cache.set(f'order:{order.id}', order, 300)
 
        return OrderResponse(...)

API Key Authentication

Manage API keys through Django Admin for secure service authentication:

Create key:

Go to Django Admin → gRPC API Keys
Click “Add gRPC API Key”
Fill in name, user, type, expiration
Save and copy the generated key

Use key:


grpcurl -H "x-api-key: <your-key>" \
  localhost:50051 api.users.UserService/GetUser

Features:

Auto-generated secure keys (64-character hex)
Managed through Django Admin
Optional expiration dates
Usage tracked automatically (request count, last used)
Easy revocation
Django SECRET_KEY support for dev/internal use

Example service with auth:


class UserService(BaseService):
    def UpdateProfile(self, request, context):
        # Require authentication
        user = self.require_user(context)
 
        # Check permissions
        if not user.has_perm('users.change_profile'):
            self.abort_permission_denied(context, "No access")
 
        # Access API key info
        api_key = getattr(context, 'api_key', None)
        if api_key:
            print(f"Request from: {api_key.name}")
 
        # Update profile
        user.bio = request.bio
        user.save()
        return UserResponse(...)

Request Logging

All requests automatically logged to database with API key tracking:


# View in Django Admin
/admin/integrations/grpc/grpcrequestlog/
 
# Query programmatically
from django_cfg.apps.integrations.grpc.models import GRPCRequestLog
 
stats = GRPCRequestLog.objects.get_statistics(hours=24)
# {
#     "total": 1543,
#     "successful": 1489,
#     "success_rate": 96.5,
#     "avg_duration_ms": 125.3
# }
 
# Filter by API key
api_key_logs = GRPCRequestLog.objects.filter(
    api_key__name="Analytics Service"
)
 
# Filter by user
user_logs = GRPCRequestLog.objects.filter(
    user__username="service_user",
    is_authenticated=True
)
 
# Get recent requests with API key info (via REST API)
# GET /api/grpc/monitor/requests/
# Returns: user_id, username, api_key_id, api_key_name for each request

Server Monitoring

Real-time server status tracking:

View in Django Admin: /admin/ → gRPC Server Status

See server monitoring:

Server address and port
Status (running/stopped)
Uptime
Registered services

Integration Testing

Test your complete gRPC setup with a single command:


python manage.py test_grpc_integration [--app APP_NAME] [--quiet]

What it tests:

✅ Proto file generation
✅ Server startup
✅ API key authentication
✅ Request logging with API key tracking
✅ Service discovery
✅ Automatic cleanup

Example output:


🧪 gRPC Integration Test
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Step 1/6: Generated proto files
✅ Step 2/6: Started gRPC server (PID: 12345)
✅ Step 3/6: Created test API key
✅ Step 4/6: Client tests passed (3/3)
   ✓ With API key
   ✓ With SECRET_KEY
   ✗ Invalid key (expected failure)
✅ Step 5/6: Request logs verified
   • Total logs: 95
   • With API key: 33
   • With SECRET_KEY: 62
✅ Step 6/6: Cleanup completed

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎉 All tests passed! (6/6)

Production Testing

Use this command in CI/CD pipelines to verify your gRPC setup before deployment.

📊 Process Flows

Simple Request Flow

API Key Authentication Flow

Interceptor Chain

Base Service Classes

Three base classes for common patterns:


# Flexible authentication
from django_cfg.apps.integrations.grpc.services import BaseService
 
class MyService(BaseService):
    pass
 
# Read-only operations
from django_cfg.apps.integrations.grpc.services import ReadOnlyService
 
class CatalogService(ReadOnlyService):
    pass
 
# All methods require auth
from django_cfg.apps.integrations.grpc.services import AuthRequiredService
 
class AccountService(AuthRequiredService):
    pass

Dynamic Invocation (Phase 4)

Test services without proto files using reflection:


from django_cfg.apps.integrations.grpc.services.grpc_client import DynamicGRPCClient
 
client = DynamicGRPCClient("localhost", 50051)
 
# Discover services
services = client.list_services()
 
# Invoke method
response = client.invoke_method(
    "api.users.UserService",
    "GetUser",
    {"user_id": 1}
)

🔄 Request Flow

🔄 Server Lifecycle

Server States

Development Workflow

📚 Documentation

Core Guides

Getting Started - Build your first service (10 min)
Concepts - Architecture and design patterns
Configuration - Complete configuration reference
Authentication - API key authentication

Advanced Topics

Async Support - High-concurrency async server and streaming
REST API - REST endpoints for monitoring and management
Dynamic Invocation - Test without proto files
FAQ - Common questions and troubleshooting

💡 Why Django-CFG gRPC?

vs. Plain gRPC

Feature	Plain gRPC	Django-CFG gRPC
Service Registration	Manual	✅ Automatic
Django ORM	Manual setup	✅ Built-in
API Key Auth	DIY	✅ Built-in with admin
Request Logging	DIY	✅ Automatic with API key tracking
Server Monitoring	DIY	✅ Real-time status tracking
REST API	None	✅ Full monitoring and management API
Admin Interface	None	✅ Django Admin integration
Error Handling	Manual	✅ Automatic

vs. REST

Aspect	REST	gRPC
Performance	Good	✅ Excellent
Binary Protocol	No	✅ Yes (smaller, faster)
Streaming	Limited	✅ Bidirectional
Type Safety	Optional	✅ Built-in (protobuf)
Browser Support	✅ Native	Limited (grpc-web)
Public APIs	✅ Better	Good

Use gRPC for:

Microservices communication
Mobile app backends
Real-time systems
High-performance APIs

Use REST for:

Public APIs
Browser-based apps
Simple CRUD

Ready to start? Check out the Getting Started Guide and build your first gRPC service in 10 minutes! 🚀