- Shutdown signals

- Reflection API
- github actions

Author: Stan Misiurev

.github/workflows/python-publish.yml

@@ -50,12 +50,7 @@ jobs:
     # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
     environment:
       name: pypi
-      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
-      # url: https://pypi.org/p/YOURPROJECT
-      #
-      # ALTERNATIVE: if your GitHub Release name is the PyPI project version string
-      # ALTERNATIVE: exactly, uncomment the following line instead:
-      # url: https://pypi.org/project/YOURPROJECT/${{ github.event.release.name }}
+      url: https://pypi.org/project/YOURPROJECT/${{ github.event.release.name }}
 
     steps:
       - name: Retrieve release distributions

.github/workflows/test.yml

@@ -0,0 +1,23 @@
+name: Test with tox
+
+on: [push]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.9", "3.11", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install tox and any other packages
+        run: pip install tox
+      - name: Run tox
+        # Run tox using the version of Python in `PATH`
+        run: tox -e py

README.md

@@ -1,8 +1,5 @@
 # django-grpc
 
-[![CircleCI](https://circleci.com/gh/gluk-w/django-grpc.svg?style=svg)](https://circleci.com/gh/gluk-w/django-grpc)
-
-
 Easy way to launch gRPC server with access to Django ORM and other handy stuff.
 gRPC calls are much faster that traditional HTTP requests because communicate over
 persistent connection and are compressed. Underlying gRPC library is written in C which
@@ -37,6 +34,7 @@ GRPCSERVER = {
         'certificate_chain': 'certificate_chain.pem'
     }],    # required only if SSL/TLS support is required to be enabled
     'async': False  # Default: False, if True then gRPC server will start in ASYNC mode
+    'reflection': False, # Default: False, enables reflection on a gRPC Server (https://grpc.io/docs/guides/reflection/)
 }
 ```
 

django_grpc/management/commands/grpcserver.py

@@ -1,9 +1,12 @@
 import datetime
 import asyncio
 
+from django.core.exceptions import ImproperlyConfigured
 from django.core.management.base import BaseCommand
 from django.utils import autoreload
 from django.conf import settings
+
+from django_grpc.signals import grpc_shutdown
 from django_grpc.utils import create_server, extract_handlers
 
 
@@ -39,10 +42,14 @@ def handle(self, *args, **options):
                 self._serve(**options)
 
     def _serve(self, max_workers, port, *args, **kwargs):
+        """
+        Run gRPC server
+        """
         autoreload.raise_last_exception()
         self.stdout.write("gRPC server starting at %s" % datetime.datetime.now())
 
         server = create_server(max_workers, port)
+
         server.start()
 
         self.stdout.write("gRPC server is listening port %s" % port)
@@ -53,10 +60,18 @@ def _serve(self, max_workers, port, *args, **kwargs):
                 self.stdout.write("* %s" % handler)
 
         server.wait_for_termination()
+        # Send shutdown signal to all connected receivers
+        grpc_shutdown.send(None)
 
     def _serve_async(self, max_workers, port, *args, **kwargs):
+        """
+        Run gRPC server in async mode
+        """
         self.stdout.write("gRPC async server starting  at %s" % datetime.datetime.now())
 
+        # Coroutines to be invoked when the event loop is shutting down.
+        _cleanup_coroutines = []
+
         server = create_server(max_workers, port)
 
         async def _main_routine():
@@ -70,4 +85,14 @@ async def _main_routine():
 
             await server.wait_for_termination()
 
-        asyncio.get_event_loop().run_until_complete(_main_routine())
+        async def _graceful_shutdown():
+            # Send the signal to all connected receivers on server shutdown.
+            # https://github.com/gluk-w/django-grpc/issues/31
+            grpc_shutdown.send(None)
+
+        loop = asyncio.get_event_loop()
+        try:
+            loop.run_until_complete(_main_routine())
+        finally:
+            loop.run_until_complete(*_cleanup_coroutines)
+            loop.close()

django_grpc/signals/__init__.py

@@ -18,3 +18,6 @@
 grpc_request_started.connect(reset_queries)
 grpc_request_started.connect(close_old_connections)
 grpc_request_finished.connect(close_old_connections)
+
+# Triggered when the server receives graceful shut down signal
+grpc_shutdown = Signal()

django_grpc/utils.py

@@ -3,6 +3,7 @@
 from concurrent import futures
 
 import grpc
+from django.core.exceptions import ImproperlyConfigured
 
 from django.utils.module_loading import import_string
 from django_grpc.signals.wrapper import SignalWrapper
@@ -20,6 +21,7 @@ def create_server(max_workers, port, interceptors=None):
     options = config.get('options', [])
     credentials = config.get('credentials', None)
     is_async = config.get('async', False)
+    need_reflection = config.get('reflection', False)
 
     # create a gRPC server
     if is_async is True:
@@ -38,6 +40,9 @@ def create_server(max_workers, port, interceptors=None):
 
     add_servicers(server, servicers_list)
 
+    if need_reflection:
+        enable_reflection(server)
+
     if credentials is None:
         server.add_insecure_port('[::]:%s' % port)
     else:
@@ -61,7 +66,7 @@ def create_server(max_workers, port, interceptors=None):
     return server
 
 
-def add_servicers(server, servicers_list):
+def add_servicers(server, servicers_list: list[str]):
     """
     Add servicers to the server
     """
@@ -107,3 +112,24 @@ def extract_handlers(server):
                 params=params,
                 abstract=abstract
             )
+
+def enable_reflection(server):
+    """
+    Enables gRPC reflection for the server so consumers can discover available services and methods.
+    https://grpc.io/docs/guides/reflection/
+    """
+    try:
+        from grpc_reflection.v1alpha import reflection
+    except ImportError:
+        raise ImproperlyConfigured(
+            "Failed to enable gRPC reflection. " +
+            "Install `grpcio-reflection` package or disable \"reflection\" in settings."
+        )
+
+    service_names = [
+        handler.service_name()
+        for handler in server._state.generic_handlers
+    ]
+
+    service_names.append(reflection.SERVICE_NAME)
+    reflection.enable_server_reflection(service_names, server)

poetry.lock

@@ -12,11 +12,13 @@ protobuf = "^5.29.3"
 grpcio = "^1.70.0"
 grpcio-tools = "^1.70.0"
 django = ">=4.2,<5.2"
+grpcio-reflection = "^1.70.0"
 
 
 [tool.poetry.group.dev.dependencies]
 bumpversion = "^0.6.0"
 wheel = "^0.45.1"
+pytest-django = "^4.10.0"
 
 [tool.poetry.group.qa.dependencies]
 mirakuru = "^2.5.3"

pyproject.toml

@@ -40,4 +40,5 @@
 
 GRPCSERVER = {
     'servicers': ('tests.sampleapp.utils.register_servicer',),
+    'reflection': False,
 }

tests/settings.py

@@ -0,0 +1,14 @@
+import pytest
+
+from django_grpc.utils import create_server
+
+
+def test_reflection(settings):
+    settings.GRPCSERVER['reflection'] = True
+    server = create_server(1, 50080)
+    server.start()
+
+    assert len(server._state.generic_handlers) == 2, "Reflection handler must be appended"
+    assert '/grpc.reflection.v1alpha.ServerReflection/ServerReflectionInfo' in server._state.generic_handlers[1]._method_handlers
+
+    server.stop(True)

tests/test_reflection.py

@@ -1,6 +1,7 @@
 import pytest
 from grpc import RpcError
 
+from django_grpc.utils import create_server
 from tests.helpers import call_hello_method
 
 

tests/test_signals.py

@@ -3,8 +3,7 @@
 
 def test_extract_handlers():
     server = create_server(1, 50080)
-    assert list(extract_handlers(server)) == [
-        '/helloworld.Greeter/SayHello: inner(args, kwargs, response, exc) NOT IMPLEMENTED',
-        '/helloworld.Greeter/SayHelloStreamReply: ???(???) DOES NOT EXIST',
-        '/helloworld.Greeter/SayHelloBidiStream: ???(???) DOES NOT EXIST',
-    ]
+    handers =  set(extract_handlers(server))
+    assert '/helloworld.Greeter/SayHello: inner(args, kwargs, response, exc) NOT IMPLEMENTED' in handers
+    assert '/helloworld.Greeter/SayHelloStreamReply: ???(???) DOES NOT EXIST' in handers
+    assert '/helloworld.Greeter/SayHelloBidiStream: ???(???) DOES NOT EXIST' in handers