django-aiogram 4.0.0.dev0__py3-none-any.whl

django_aiogram/management/commands/tgbot_webhook.py

@@ -0,0 +1,87 @@
+"""Register, inspect or remove the Telegram webhook.
+
+Telegram remembers the URL, not your settings file, so switching between polling
+and webhooks means telling Telegram. `getUpdates` refuses to run while a webhook
+is registered, which is why `delete` exists.
+"""
+
+from argparse import ArgumentParser
+from typing import Any
+
+from django.core.management import BaseCommand, CommandError
+
+from django_aiogram import bot
+from django_aiogram.config.enums import UpdateMode
+from django_aiogram.consumer.webhook import current_mode, webhook_settings
+
+
+class Command(BaseCommand):
+    """Tell Telegram where to post updates, or that it should stop."""
+
+    help = 'Set, delete or show the Telegram webhook'
+
+    def add_arguments(self, parser: ArgumentParser) -> None:
+        """Declare the action and --drop-pending."""
+        parser.add_argument('action', choices=['set', 'delete', 'info'])
+        parser.add_argument(
+            '--drop-pending',
+            action='store_true',
+            help='discard the updates Telegram queued while no webhook was registered',
+        )
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        """Run the chosen action, and close the bot whichever way it ends."""
+        if not bot.enabled:
+            msg = "the bot is disabled here (TELEGRAM_BOT['ENABLED'] or DJANGO_AIOGRAM_ENABLED); nothing was changed"
+            raise CommandError(msg)
+
+        action = options['action']
+        try:
+            getattr(self, f'_{action}')(options)
+        finally:
+            bot.close()
+
+    def _set(self, options: dict[str, Any]) -> None:
+        """Register the webhook Telegram should deliver to, warning if MODE disagrees.
+
+        Setting one is what makes ``getUpdates`` start refusing, so a project still
+        configured for polling is told plainly rather than left to read that from
+        Telegram's error later.
+        """
+        if current_mode() != UpdateMode.WEBHOOK:
+            self.stdout.write(
+                self.style.WARNING(
+                    f"TELEGRAM_BOT['MODE'] is '{current_mode()}': registering this webhook "
+                    'stops getUpdates from working, so polling will fail until it is deleted'
+                )
+            )
+        arguments = webhook_settings()
+        arguments['drop_pending_updates'] = options['drop_pending']
+        bot.loop.run_until_complete(bot.bot.set_webhook(**arguments))
+        self.stdout.write(self.style.SUCCESS(f'webhook set to {arguments["url"]}'))
+        self.stdout.write('polling will refuse to start until this is deleted')
+
+    def _delete(self, options: dict[str, Any]) -> None:
+        """Unregister the webhook, which is what polling needs before it can start.
+
+        ``drop_pending_updates`` decides whether Telegram forgets what it queued while
+        the webhook was down; the caller chooses, because that is a decision about
+        duplicate work rather than about the webhook.
+        """
+        bot.loop.run_until_complete(bot.bot.delete_webhook(drop_pending_updates=options['drop_pending']))
+        self.stdout.write(self.style.SUCCESS('webhook deleted; polling can start again'))
+
+    def _info(self, _options: dict[str, Any]) -> None:
+        """Report what Telegram thinks the webhook is, which is the only authority on it.
+
+        ``last_error_message`` is the field worth the command: a webhook can be
+        registered and rejected on every delivery, and nothing local shows that.
+        """
+        info = bot.loop.run_until_complete(bot.bot.get_webhook_info())
+        if not info.url:
+            self.stdout.write('no webhook registered; this bot is polled')
+            return
+        self.stdout.write(f'url: {info.url}')
+        self.stdout.write(f'pending updates: {info.pending_update_count}')
+        if info.last_error_message:
+            self.stdout.write(self.style.WARNING(f'last error: {info.last_error_message} (at {info.last_error_date})'))

django_aiogram/migrations/0001_initial.py

@@ -0,0 +1,50 @@
+"""The first migration this package has ever shipped: the event log table."""
+
+from typing import ClassVar
+
+import django.utils.timezone
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    """Create the append-only event feed and the four indexes it is read by."""
+
+    initial = True
+
+    dependencies: ClassVar[list[tuple[str, str]]] = []
+
+    operations: ClassVar[list[migrations.operations.base.Operation]] = [
+        migrations.CreateModel(
+            name='TelegramEvent',
+            fields=[
+                ('id', models.BigAutoField(primary_key=True, serialize=False)),
+                ('created_at', models.DateTimeField(default=django.utils.timezone.now)),
+                ('correlation_id', models.UUIDField()),
+                ('kind', models.CharField(max_length=48)),
+                ('function', models.CharField(blank=True, max_length=64)),
+                ('chat_id', models.BigIntegerField(blank=True, null=True)),
+                ('user_id', models.BigIntegerField(blank=True, null=True)),
+                ('message_id', models.BigIntegerField(blank=True, null=True)),
+                ('update_id', models.BigIntegerField(blank=True, null=True)),
+                ('worker', models.CharField(blank=True, max_length=128)),
+                ('attempt', models.PositiveSmallIntegerField(default=0)),
+                ('duration_ms', models.PositiveIntegerField(blank=True, null=True)),
+                ('error_code', models.CharField(blank=True, max_length=64)),
+                ('error', models.TextField(blank=True)),
+                ('detail', models.JSONField(blank=True, default=dict)),
+            ],
+            options={
+                'verbose_name': 'telegram event',
+                'verbose_name_plural': 'telegram events',
+                'db_table': 'django_aiogram_event',
+                'ordering': ('-id',),
+                'permissions': (('view_telegramevent_payload', 'Can see event payloads and error text'),),
+                'indexes': [
+                    models.Index(fields=['correlation_id'], name='drai_event_correlation'),
+                    models.Index(fields=['-created_at'], name='drai_event_recent'),
+                    models.Index(fields=['kind', '-created_at'], name='drai_event_kind_recent'),
+                    models.Index(fields=['chat_id', '-id'], name='drai_event_chat'),
+                ],
+            },
+        ),
+    ]

django_aiogram/migrations/0002_kind_id_index.py

@@ -0,0 +1,32 @@
+"""Index the kind filter by the column the changelist actually orders on.
+
+Added before the old one is removed, so the table is never without an index on
+``kind``. A new name rather than a rename, because the columns differ: the old
+one was ``(kind, -created_at)`` while the changelist orders by ``-id``.
+
+``AddIndex`` issues a plain ``CREATE INDEX``, with no ``IF NOT EXISTS`` and no
+adoption of one that is already there — so creating it by hand ahead of this
+migration makes the migration fail rather than saving it work. On a table large
+enough for the lock to matter, run the migration in a window.
+"""
+
+from typing import ClassVar
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    """Swap ``(kind, -created_at)`` for ``(kind, -id)``."""
+
+    dependencies: ClassVar[list[tuple[str, str]]] = [('django_aiogram', '0001_initial')]
+
+    operations: ClassVar[list[migrations.operations.base.Operation]] = [
+        migrations.AddIndex(
+            model_name='telegramevent',
+            index=models.Index(fields=['kind', '-id'], name='drai_event_kind_id'),
+        ),
+        migrations.RemoveIndex(
+            model_name='telegramevent',
+            name='drai_event_kind_recent',
+        ),
+    ]

django_aiogram/migrations/__init__.py

@@ -0,0 +1 @@
+"""Migrations for the event log table."""

django_aiogram/models.py

@@ -0,0 +1,79 @@
+"""The append-only feed of what the bot did.
+
+Django imports this on every ``django.setup()`` — before ``AppConfig.ready()``
+and regardless of ``ENABLED`` — so it may not reach aiogram, directly or
+otherwise, and may not read settings at import time.
+
+Rows are inserted and never updated. The stages of one outbound message are
+three rows sharing a ``correlation_id``: the web process writes the queued row
+and the bot container writes the delivered one, with no coordination between
+them and no foreign key either way. That only works because the feed is
+insert-only, which is also what keeps pruning cheap and the table shardable.
+"""
+
+from django.db import models
+from django.utils import timezone
+
+from django_aiogram.eventlog.events import MAX_KIND_LENGTH
+
+
+class TelegramEvent(models.Model):
+    """One thing that happened to one message, update or handler."""
+
+    id = models.BigAutoField(primary_key=True)
+    # stamped by whoever recorded it: the writer batches, so auto_now_add would
+    # record when the batch was flushed rather than when the thing happened
+    created_at = models.DateTimeField(default=timezone.now)
+    # time-ordered (UUIDv7), so this index appends rather than scattering
+    correlation_id = models.UUIDField()
+    # no choices: see events.kind_choices for why the registry stays in Python
+    kind = models.CharField(max_length=MAX_KIND_LENGTH)
+
+    function = models.CharField(max_length=64, blank=True)
+    chat_id = models.BigIntegerField(null=True, blank=True)
+    user_id = models.BigIntegerField(null=True, blank=True)
+    message_id = models.BigIntegerField(null=True, blank=True)
+    update_id = models.BigIntegerField(null=True, blank=True)
+    # the same name the in-flight list uses, so a row points at a container
+    worker = models.CharField(max_length=128, blank=True)
+
+    attempt = models.PositiveSmallIntegerField(default=0)
+    duration_ms = models.PositiveIntegerField(null=True, blank=True)
+    error_code = models.CharField(max_length=64, blank=True)
+    error = models.TextField(blank=True)
+    detail = models.JSONField(default=dict, blank=True)
+
+    class Meta:
+        """Portable everywhere: no constraints, no relations, four indexes."""
+
+        db_table = 'django_aiogram_event'
+        # by id, not created_at: id is the insert order and unique, so the admin
+        # paginator gets a total order without a tie-breaker column
+        ordering = ('-id',)
+        verbose_name = 'telegram event'
+        verbose_name_plural = 'telegram events'
+        # Django's four stock permissions, plus the one it has no equivalent for:
+        # there are no field-level permissions, and seeing that a message went
+        # out is a different question from reading what it said
+        permissions = (('view_telegramevent_payload', 'Can see event payloads and error text'),)
+        # named explicitly and kept short: Oracle rejects an identifier over 30
+        indexes = (
+            models.Index(fields=('correlation_id',), name='drai_event_correlation'),
+            # two consumers: the changelist's created_at sort header and the
+            # prune watermark. Django appends -pk to make the sort deterministic,
+            # which this cannot serve on its own — measured, the descending header
+            # sorts only the last term, within rows sharing one created_at, and
+            # the ascending one needs no sort at all. A pair of (created_at, -id)
+            # indexes would remove even that, at the price of two more writes per
+            # row on a table whose whole design is cheap inserts
+            models.Index(fields=('-created_at',), name='drai_event_recent'),
+            # by -id, matching `ordering`: on (kind, -created_at) every filtered
+            # changelist sorted in a temp b-tree, page query and bounded count
+            # alike, which is what made the count's documented bound untrue
+            models.Index(fields=('kind', '-id'), name='drai_event_kind_id'),
+            models.Index(fields=('chat_id', '-id'), name='drai_event_chat'),
+        )
+
+    def __str__(self) -> str:
+        """Name the event the way an admin row reads."""
+        return f'{self.kind} {self.function}'.strip()

django_aiogram/producer/__init__.py

@@ -0,0 +1,13 @@
+"""The send side: what a project calls to make a message happen.
+
+`client` is the bot and the producer — routing a send to Telegram or to the queue, and
+owning the loop a webhook process turns. `throttling` paces what reaches Telegram.
+
+A caller outside this package names `client` and nothing else. `throttling` is reached
+through the bot, and its rate is a setting rather than an argument.
+"""
+
+#: deliberately empty: callers import from the modules in this package, not from the
+#: package itself. A re-export here would make a second path to every name, and the one
+#: nobody chose is the one that cannot be moved later
+__all__: tuple[str, ...] = ()