add sync handlers for internal webhook events (#34)

* add sync handlers for internal webhook events

* allow event method to take sync or async callbacks

* add tests for sync events

* add switch for if async or sync webhook view is used

* remove asyncio mark

* add seq number to full name field

* add tests for ready method

* oops, forgot to remove this

* update changelog and readme

* update readme

Author: joshuadavidthomas

CHANGELOG.md

@@ -22,6 +22,7 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/
 
 - Added `SyncWebhookView`, a synchronous counterpart to `AsyncWebhookView` for Django applications running under WSGI. Works with `SyncGitHubAPI` and synchronous event handlers to provide a fully synchronous workflow for processing GitHub webhooks.
 - Added system check to prevent mixing async and sync webhook views in the same project (`django_github_app.E001`).
+- Added sync versions of internal event handlers for installation and repository webhooks. The library automatically selects async or sync handlers based on the webhook view type configured in your URLs.
 
 ### Changed
 

README.md

@@ -438,6 +438,22 @@ issues = await repo.aget_issues(params={"state": "open"})
 - `owner`: Repository owner from full name
 - `repo`: Repository name from full name
 
+### Built-in Event Handlers
+
+The library includes event handlers for managing GitHub App installations and repositories. These handlers automatically update your `Installation` and `Repository` models in response to GitHub webhooks:
+
+- Installation events:
+  - `installation.created`: Creates new `Installation` record
+  - `installation.deleted`: Removes `Installation` record
+  - `installation.suspend`/`installation.unsuspend`: Updates `Installation` status
+  - `installation.new_permissions_accepted`: Updates `Installation` data
+  - `installation_repositories`: Creates and/or removes the `Repository` models associated with `Installation`
+
+- Repository events:
+  - `repository.renamed`: Updates repository details
+
+The library automatically detects whether you're using `AsyncWebhookView` or `SyncWebhookView` in your URL configuration and loads the corresponding async or sync versions of these handlers.
+
 ### System Checks
 
 The library includes Django system checks to validate your webhook configuration:

src/django_github_app/apps.py

@@ -13,4 +13,22 @@ class GitHubAppConfig(AppConfig):
     @override
     def ready(self):
         from . import checks  # noqa: F401
-        from .events import ahandlers  # noqa: F401
+
+        try:
+            webhook_type = self.detect_webhook_type()
+            if webhook_type == "async":
+                from .events import ahandlers  # noqa: F401
+            elif webhook_type == "sync":
+                from .events import handlers  # noqa: F401
+        except (ImportError, ValueError):
+            pass
+
+    @classmethod
+    def detect_webhook_type(cls):
+        from .views import AsyncWebhookView
+        from .views import get_webhook_views
+
+        views = get_webhook_views()
+        if views:
+            return "async" if issubclass(views[0], AsyncWebhookView) else "sync"
+        return None

src/django_github_app/events/handlers.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from . import installation
+from . import repository
+
+__all__ = [
+    "installation",
+    "repository",
+]

src/django_github_app/events/installation.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from gidgethub import sansio
+from gidgethub.abc import GitHubAPI
+
+from django_github_app.models import Installation
+from django_github_app.models import InstallationStatus
+from django_github_app.models import Repository
+from django_github_app.routing import GitHubRouter
+
+gh = GitHubRouter()
+
+
+@gh.event("installation", action="created")
+def create_installation(event: sansio.Event, gh: GitHubAPI, *args, **kwargs):
+    Installation.objects.create_from_event(event)
+
+
+@gh.event("installation", action="deleted")
+def delete_installation(event: sansio.Event, gh: GitHubAPI, *args, **kwargs):
+    installation = Installation.objects.get_from_event(event)
+    installation.delete()
+
+
+@gh.event("installation", action="suspend")
+@gh.event("installation", action="unsuspend")
+def toggle_installation_status(event: sansio.Event, gh: GitHubAPI, *args, **kwargs):
+    installation = Installation.objects.get_from_event(event)
+    installation.status = InstallationStatus.from_event(event)
+    installation.save()
+
+
+@gh.event("installation", action="new_permissions_accepted")
+def sync_installation_data(event: sansio.Event, gh: GitHubAPI, *args, **kwargs):
+    installation = Installation.objects.get_from_event(event)
+    installation.data = event.data["installation"]
+    installation.save()
+
+
+@gh.event("installation_repositories")
+def sync_installation_repositories(event: sansio.Event, gh: GitHubAPI, *args, **kwargs):
+    removed = [repo["id"] for repo in event.data["repositories_removed"]]
+    added = [
+        Repository(
+            installation=Installation.objects.get_from_event(event),
+            repository_id=repo["id"],
+            repository_node_id=repo["node_id"],
+            full_name=repo["full_name"],
+        )
+        for repo in event.data["repositories_added"]
+        if not Repository.objects.filter(repository_id=repo["id"]).exists()
+    ]
+
+    Repository.objects.filter(repository_id__in=removed).delete()
+    Repository.objects.bulk_create(added)

src/django_github_app/events/repository.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from gidgethub import sansio
+from gidgethub.abc import GitHubAPI
+
+from django_github_app.models import Repository
+from django_github_app.routing import GitHubRouter
+
+gh = GitHubRouter()
+
+
+@gh.event("repository", action="renamed")
+def rename_repository(event: sansio.Event, gh: GitHubAPI, *args, **kwargs):
+    repo = Repository.objects.get_from_event(event)
+    repo.full_name = event.data["repository"]["full_name"]
+    repo.save()

src/django_github_app/routing.py

@@ -1,15 +1,21 @@
 from __future__ import annotations
 
+from collections.abc import Awaitable
 from collections.abc import Callable
 from typing import Any
+from typing import TypeVar
 
 from django.utils.functional import classproperty
 from gidgethub import sansio
-from gidgethub.routing import AsyncCallback
 from gidgethub.routing import Router as GidgetHubRouter
 
 from ._typing import override
 
+AsyncCallback = Callable[..., Awaitable[None]]
+SyncCallback = Callable[..., None]
+
+CB = TypeVar("CB", AsyncCallback, SyncCallback)
+
 
 class GitHubRouter(GidgetHubRouter):
     _routers: list[GidgetHubRouter] = []
@@ -22,11 +28,9 @@ def __init__(self, *args) -> None:
     def routers(cls):
         return list(cls._routers)
 
-    def event(
-        self, event_type: str, **kwargs: Any
-    ) -> Callable[[AsyncCallback], AsyncCallback]:
-        def decorator(func: AsyncCallback) -> AsyncCallback:
-            self.add(func, event_type, **kwargs)
+    def event(self, event_type: str, **kwargs: Any) -> Callable[[CB], CB]:
+        def decorator(func: CB) -> CB:
+            self.add(func, event_type, **kwargs)  # type: ignore[arg-type]
             return func
 
         return decorator

tests/events/test_arepository.py

@@ -7,6 +7,7 @@
 
 from django_github_app.events.arepository import arename_repository
 from django_github_app.models import Repository
+from tests.utils import seq
 
 pytestmark = [pytest.mark.asyncio, pytest.mark.django_db]
 
@@ -17,13 +18,13 @@ async def test_arename_repository(ainstallation, repository_id):
         "django_github_app.Repository",
         installation=installation,
         repository_id=repository_id,
-        full_name="owner/old_name",
+        full_name=f"owner/old_name_{seq.next()}",
     )
 
     data = {
         "repository": {
             "id": repository.repository_id,
-            "full_name": "owner/new_name",
+            "full_name": f"owner/new_name_{seq.next()}",
         },
     }
     event = sansio.Event(data, event="repository", delivery_id="1234")

tests/events/test_installation.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import pytest
+from gidgethub.abc import sansio
+from model_bakery import baker
+
+from django_github_app.events.installation import create_installation
+from django_github_app.events.installation import delete_installation
+from django_github_app.events.installation import sync_installation_data
+from django_github_app.events.installation import sync_installation_repositories
+from django_github_app.events.installation import toggle_installation_status
+from django_github_app.models import Installation
+from django_github_app.models import InstallationStatus
+from django_github_app.models import Repository
+from tests.utils import seq
+
+pytestmark = [pytest.mark.django_db]
+
+
+def test_create_installation(installation_id, repository_id, override_app_settings):
+    data = {
+        "installation": {
+            "id": installation_id,
+            "app_id": seq.next(),
+        },
+        "repositories": [
+            {"id": repository_id, "node_id": "node1234", "full_name": "owner/repo"}
+        ],
+    }
+    event = sansio.Event(data, event="installation", delivery_id="1234")
+
+    with override_app_settings(APP_ID=str(data["installation"]["app_id"])):
+        create_installation(event, None)
+
+    installation = Installation.objects.get(installation_id=data["installation"]["id"])
+
+    assert installation.data == data["installation"]
+
+
+def test_delete_installation(installation):
+    data = {
+        "installation": {
+            "id": installation.installation_id,
+        }
+    }
+    event = sansio.Event(data, event="installation", delivery_id="1234")
+
+    delete_installation(event, None)
+
+    assert not Installation.objects.filter(
+        installation_id=data["installation"]["id"]
+    ).exists()
+
+
+@pytest.mark.parametrize(
+    "status,action,expected",
+    [
+        (InstallationStatus.ACTIVE, "suspend", InstallationStatus.INACTIVE),
+        (InstallationStatus.INACTIVE, "unsuspend", InstallationStatus.ACTIVE),
+    ],
+)
+def test_toggle_installation_status_suspend(status, action, expected, installation):
+    installation.status = status
+    installation.save()
+
+    data = {
+        "action": action,
+        "installation": {
+            "id": installation.installation_id,
+        },
+    }
+    event = sansio.Event(data, event="installation", delivery_id="1234")
+
+    assert installation.status != expected
+
+    toggle_installation_status(event, None)
+
+    installation.refresh_from_db()
+    assert installation.status == expected
+
+
+def test_sync_installation_data(installation):
+    data = {
+        "installation": {
+            "id": installation.installation_id,
+        },
+    }
+    event = sansio.Event(data, event="installation", delivery_id="1234")
+
+    assert installation.data != data
+
+    sync_installation_data(event, None)
+
+    installation.refresh_from_db()
+    assert installation.data == data["installation"]
+
+
+def test_sync_installation_repositories(installation):
+    existing_repo = baker.make(
+        "django_github_app.Repository",
+        installation=installation,
+        repository_id=seq.next(),
+    )
+
+    data = {
+        "installation": {
+            "id": installation.installation_id,
+        },
+        "repositories_removed": [
+            {
+                "id": existing_repo.repository_id,
+            },
+        ],
+        "repositories_added": [
+            {
+                "id": seq.next(),
+                "node_id": "repo1234",
+                "full_name": "owner/repo",
+            }
+        ],
+    }
+    event = sansio.Event(data, event="installation", delivery_id="1234")
+
+    assert Repository.objects.filter(
+        repository_id=data["repositories_removed"][0]["id"]
+    ).exists()
+    assert not Repository.objects.filter(
+        repository_id=data["repositories_added"][0]["id"]
+    ).exists()
+
+    sync_installation_repositories(event, None)
+
+    assert not Repository.objects.filter(
+        repository_id=data["repositories_removed"][0]["id"]
+    ).exists()
+    assert Repository.objects.filter(
+        repository_id=data["repositories_added"][0]["id"]
+    ).exists()

tests/events/test_repository.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import pytest
+from gidgethub import sansio
+from model_bakery import baker
+
+from django_github_app.events.repository import rename_repository
+from django_github_app.models import Repository
+from tests.utils import seq
+
+pytestmark = [pytest.mark.django_db]
+
+
+def test_rename_repository(installation, repository_id):
+    repository = baker.make(
+        "django_github_app.Repository",
+        installation=installation,
+        repository_id=repository_id,
+        full_name=f"owner/old_name_{seq.next()}",
+    )
+
+    data = {
+        "repository": {
+            "id": repository.repository_id,
+            "full_name": f"owner/new_name_{seq.next()}",
+        },
+    }
+    event = sansio.Event(data, event="repository", delivery_id="1234")
+
+    assert not Repository.objects.filter(
+        full_name=data["repository"]["full_name"]
+    ).exists()
+
+    rename_repository(event, None)
+
+    assert Repository.objects.filter(full_name=data["repository"]["full_name"]).exists()