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

django_aiogram/consumer/webhook.py

@@ -0,0 +1,154 @@
+"""Receive updates over HTTP instead of polling for them.
+
+Long polling needs a process that runs forever. A webhook does not: Telegram
+posts each update to a URL, so the update arrives in whichever process serves
+that URL — normally the web one.
+
+The view is deliberately synchronous. An async view would run on the server's
+own loop under ASGI but on a throwaway loop per request under WSGI, and the
+bot's HTTP session binds to the first loop that uses it. Driving the bot's own
+loop works the same under both.
+"""
+
+import hmac
+import json
+import logging
+from typing import Any
+
+from aiogram.types import Update
+from django.core.exceptions import ImproperlyConfigured
+from django.http import HttpRequest, HttpResponse, HttpResponseNotAllowed
+from django.views.decorators.csrf import csrf_exempt
+from pydantic import ValidationError
+
+from django_aiogram import bot
+from django_aiogram.config.enums import UpdateMode, choices
+from django_aiogram.config.settings import SETTINGS_NAME, conf
+from django_aiogram.exceptions import LoopUnavailableError
+
+logger = logging.getLogger('django_aiogram')
+
+#: what Telegram sends the configured secret back in
+SECRET_HEADER = 'HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN'  # noqa: S105 - a header name, not the secret it carries
+#: plain strings, so argparse choices and messages read as the settings do
+MODES = choices(UpdateMode)
+
+
+def current_mode() -> str:
+    """Which of the two ways of receiving updates this deployment uses."""
+    mode = str(conf['MODE'] or '').strip().lower()
+    if mode not in MODES:
+        msg = f"{SETTINGS_NAME}['MODE'] must be one of {sorted(MODES)}, got {mode!r}."
+        raise ImproperlyConfigured(msg)
+    return mode
+
+
+def webhook_secret() -> str:
+    """Return the shared secret, which the view refuses to run without."""
+    secret = str(conf['WEBHOOK_SECRET'] or '').strip()
+    if not secret:
+        msg = (
+            f"{SETTINGS_NAME}['WEBHOOK_SECRET'] is required to serve the webhook: without it "
+            'anyone who finds the URL can feed your bot updates.'
+        )
+        raise ImproperlyConfigured(msg)
+    return secret
+
+
+@csrf_exempt
+def telegram_webhook(request: HttpRequest) -> HttpResponse:  # noqa: PLR0911 - a guard-clause chain is the readable shape
+    """Feed one update to the dispatcher.
+
+    Answers 200 for anything Telegram should not retry, including a handler that
+    raised — a non-2xx makes Telegram redeliver the same update, and a handler
+    that fails once will fail again. A *refusal* is the other case: when nothing
+    ran at all, because this process is shutting down, redelivery is exactly
+    what should happen, so that answers 503.
+    """
+    if request.method != 'POST':
+        return HttpResponseNotAllowed(['POST'])
+
+    if not bot.enabled:
+        logger.warning('webhook received an update while the bot is disabled')
+        return HttpResponse(status=503)
+
+    try:
+        # guarded, because an unknown `MODE` and an empty `WEBHOOK_SECRET` each raise
+        # `ImproperlyConfigured` — and unguarded that left an unauthenticated 500 with a
+        # traceback from a view whose every other refusal is a status code. The bot build
+        # below already treats a configuration failure as ours to answer for.
+        #
+        # The secret only when the mode says to serve: a polling deployment has no reason
+        # to set one, and reading it first told every such deployment its configuration was
+        # unreadable instead of that it polls. Each setting is judged where it matters, and
+        # the order the documentation promises is the order here
+        mode = current_mode()
+        polling = mode != UpdateMode.WEBHOOK
+        secret = '' if polling else webhook_secret()
+    except ImproperlyConfigured:
+        logger.exception('webhook is not configured to serve updates')
+        return HttpResponse(status=503)
+
+    if polling:
+        # serving updates here while a worker polls for them would mean two
+        # sources of updates and no way to tell which handled what
+        logger.warning(
+            'webhook received an update while this deployment polls',
+            extra={'tg_mode': mode},
+        )
+        return HttpResponse(status=503)
+
+    given = request.META.get(SECRET_HEADER, '')
+    # bytes, not str: `compare_digest` refuses str arguments outside ASCII, so a header
+    # with one non-ASCII character used to raise TypeError here — an unauthenticated
+    # 500 with a traceback, from the branch whose whole job is to answer 403
+    if not hmac.compare_digest(given.encode(), secret.encode()):
+        logger.warning('webhook rejected an update with a wrong secret')
+        return HttpResponse(status=403)
+
+    try:
+        telegram = bot.bot
+    except ImproperlyConfigured:
+        # a missing token is our problem, not a bad request
+        logger.exception('webhook cannot build the bot')
+        return HttpResponse(status=503)
+
+    try:
+        payload = json.loads(request.body)
+        update = Update.model_validate(payload, context={'bot': telegram})
+    except (json.JSONDecodeError, UnicodeDecodeError, ValidationError, TypeError) as error:
+        # the body is whoever posted it, so the type is all that goes in the log:
+        # a traceback here would spread unvalidated input through the handlers
+        logger.warning(
+            'webhook could not read an update',
+            extra={'tg_error': type(error).__name__},
+        )
+        return HttpResponse(status=400)
+
+    try:
+        bot.feed_update(update)
+    except LoopUnavailableError:
+        # nothing ran, so this update is still Telegram's to redeliver — which a
+        # 2xx would tell it not to. The shutdown window is not a handler that
+        # failed, and the two must not answer the same way
+        logger.warning('webhook refused an update', extra={'tg_update': update.update_id})
+        return HttpResponse(status=503)
+    except Exception:
+        logger.exception('webhook handler failed', extra={'tg_update': update.update_id})
+
+    return HttpResponse(status=200)
+
+
+def webhook_settings() -> dict[str, Any]:
+    """Everything `setWebhook` needs, resolved from settings."""
+    url = str(conf['WEBHOOK_URL'] or '').strip()
+    if not url:
+        msg = f"{SETTINGS_NAME}['WEBHOOK_URL'] is required to register a webhook."
+        raise ImproperlyConfigured(msg)
+    allowed = conf['WEBHOOK_ALLOWED_UPDATES']
+    return {
+        'url': url,
+        'secret_token': webhook_secret(),
+        'allowed_updates': list(allowed) if allowed else None,
+        'drop_pending_updates': False,
+    }

django_aiogram/context.py

@@ -0,0 +1,34 @@
+"""The correlation identifier in scope, so a reply inherits the update's id.
+
+A handler that answers an update should produce rows joinable to the update that
+caused it, without every project threading an argument through its own code. A
+context variable does that: aiogram runs each update's chain in its own task,
+and a task copies the context at creation, so one update cannot leak into
+another.
+
+Read it **before** scheduling, never inside the coroutine. ``_hand_off`` creates
+its task from a ``call_soon_threadsafe`` callback whose context belongs to the
+loop rather than to the handler, so a read from in there would come back empty.
+"""
+
+import contextlib
+import uuid
+from collections.abc import Iterator
+from contextvars import ContextVar
+
+_current: ContextVar[uuid.UUID | None] = ContextVar('django_aiogram_correlation_id', default=None)
+
+
+def current_correlation_id() -> uuid.UUID | None:
+    """Return the identifier of whatever is being handled here, if anything is."""
+    return _current.get()
+
+
+@contextlib.contextmanager
+def correlation_scope(correlation_id: uuid.UUID) -> Iterator[None]:
+    """Run a block with this identifier in scope, restoring the previous one."""
+    token = _current.set(correlation_id)
+    try:
+        yield
+    finally:
+        _current.reset(token)

django_aiogram/eventlog/__init__.py

@@ -0,0 +1,16 @@
+"""The optional table, and the metrics seam that is not the table.
+
+`recorder` is the writer thread and its accounting; `writer` puts a batch into the
+database; `events` names an event and the worker that produced it; `instrumentation`
+describes an update without keeping its contents; `signals` is the seam a project connects
+a metrics exporter to; `dbrouter` sends this app's tables to their own alias.
+
+The model itself is `django_aiogram.models`, at the app root, because Django looks for it
+there and moving it would cost an `app_label` on the model and a `MIGRATION_MODULES` in
+every project.
+"""
+
+#: 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, ...] = ()

django_aiogram/eventlog/dbrouter.py

@@ -0,0 +1,55 @@
+"""Send the event log to its own database, when one is configured.
+
+Optional. The writer and the admin always name the alias explicitly, so the log
+lands in the right database with no router installed at all. What the router
+adds is ``migrate`` creating the table there, and third-party code reaching the
+right alias through the plain manager.
+
+Not ``routers.py``: that name already means aiogram router autodiscovery.
+"""
+
+from typing import Any
+
+from django.db.models import Model
+
+from django_aiogram.config.settings import conf
+
+APP_LABEL = 'django_aiogram'
+
+
+def event_log_database() -> str | None:
+    """Return the configured alias for the log, or None when it lives in the default one."""
+    return str(conf['EVENT_LOG_DATABASE'] or '').strip() or None
+
+
+class TelegramEventLogRouter:
+    """Routes this app's models to ``EVENT_LOG_DATABASE`` and nothing else anywhere."""
+
+    def _alias_for(self, model: type[Model]) -> str | None:
+        """Return the alias this app's models belong to, or None to express no opinion."""
+        alias = event_log_database()
+        # _meta is how Django itself asks a model which app it belongs to
+        return alias if alias and model._meta.app_label == APP_LABEL else None  # noqa: SLF001
+
+    def db_for_read(self, model: type[Model], **hints: Any) -> str | None:
+        """Read this app's models from the log database."""
+        return self._alias_for(model)
+
+    def db_for_write(self, model: type[Model], **hints: Any) -> str | None:
+        """Write this app's models to the log database."""
+        return self._alias_for(model)
+
+    def allow_relation(self, *objects: Model, **hints: Any) -> bool | None:
+        """Express no opinion: this app owns no relations in either direction."""
+        return None
+
+    def allow_migrate(self, db: str, app_label: str, **hints: Any) -> bool | None:
+        """Create the table on the log database only, and only when one is set.
+
+        None rather than False for other apps: where somebody else's table
+        belongs is not this router's decision to make.
+        """
+        alias = event_log_database()
+        if alias is None or app_label != APP_LABEL:
+            return None
+        return db == alias

django_aiogram/eventlog/events.py

@@ -0,0 +1,120 @@
+"""The registry of event kinds, and the identifier that ties a message together.
+
+``kind`` is an unconstrained ``CharField``: the set of legal values lives here,
+in Python, so registering one is not a schema change. The cost is that nothing
+at the database level rejects a typo, which is why the recorder validates
+against this registry before a row is built.
+
+Imported by :mod:`django_aiogram.models`, so it must stay free of aiogram
+and of anything that reads Django settings at import time.
+"""
+
+import os
+import socket
+import time
+import uuid
+from dataclasses import dataclass
+
+from django_aiogram.config.enums import EventKind
+from django_aiogram.config.settings import conf
+
+#: the width of the model's ``kind`` column; a longer code would be truncated by
+#: MySQL in non-strict mode and rejected in strict mode, so it is refused here
+MAX_KIND_LENGTH = 48
+
+
+@dataclass(frozen=True)
+class EventKindSpec:
+    """One registered kind: the stored code, its label, and whether it is bad news."""
+
+    code: str
+    label: str
+    failure: bool = False
+
+
+_KINDS: dict[str, EventKindSpec] = {}
+
+
+def register_kind(code: str, label: str, *, failure: bool = False) -> str:
+    """Register an event kind, and return its code.
+
+    Adding a kind is not a schema change. Namespace your own as
+    ``<app>.<noun>.<verb>`` and keep the total in the tens: ``kind`` is the
+    leading column of an index, and it stays worth having only while its
+    cardinality is low.
+    """
+    if len(code) > MAX_KIND_LENGTH:
+        msg = f'Event kind {code!r} is longer than {MAX_KIND_LENGTH} characters.'
+        raise ValueError(msg)
+    spec = EventKindSpec(code, label, failure=failure)
+    existing = _KINDS.get(code)
+    if existing is not None and existing != spec:
+        msg = f'Event kind {code!r} is already registered as {existing.label!r}.'
+        raise ValueError(msg)
+    _KINDS[code] = spec
+    return code
+
+
+def known_kinds() -> frozenset[str]:
+    """Every registered code, for membership checks."""
+    return frozenset(_KINDS)
+
+
+def kind_choices() -> list[tuple[str, str]]:
+    """Every registered kind as Django choices, for the admin filter.
+
+    Deliberately not passed to the model field: a callable there would have to
+    survive ``deconstruct()`` unexpanded, and if it ever did not, registering a
+    kind would become a migration every consumer has to run.
+    """
+    return [(spec.code, spec.label) for spec in _KINDS.values()]
+
+
+def failure_kinds() -> tuple[str, ...]:
+    """Return the kinds that mean something went wrong."""
+    return tuple(spec.code for spec in _KINDS.values() if spec.failure)
+
+
+def new_correlation_id() -> uuid.UUID:
+    """Build a time-ordered identifier, so its index appends instead of scattering.
+
+    uuid4 is uniformly random, and inserting random keys into a large B-tree
+    touches a different leaf page every time. RFC 9562's version 7 puts a 48-bit
+    millisecond prefix first, which sorts the same way on every backend —
+    PostgreSQL compares the raw bytes, and the others store lowercase hex.
+    """
+    generate = getattr(uuid, 'uuid7', None)
+    if generate is not None:  # pragma: no cover - 3.14 and newer
+        return generate()  # type: ignore[no-any-return]
+    raw = bytearray(int(time.time() * 1000).to_bytes(6, 'big') + os.urandom(10))
+    raw[6] = (raw[6] & 0x0F) | 0x70
+    raw[8] = (raw[8] & 0x3F) | 0x80
+    return uuid.UUID(bytes=bytes(raw))
+
+
+def worker_identity() -> str:
+    """Name this process, for the in-flight list and for the rows it records.
+
+    Defaults to the hostname, which a container keeps across restarts — that is
+    what lets a restarted worker find its own interrupted messages. Set
+    WORKER_NAME when several workers share a host.
+    """
+    configured = conf.get('WORKER_NAME')
+    if configured:
+        return str(configured)
+    return os.environ.get('HOSTNAME') or socket.gethostname()
+
+
+register_kind(EventKind.OUTBOUND_QUEUED.value, 'Queued')
+register_kind(EventKind.OUTBOUND_CONSUMED.value, 'Taken off the queue')
+register_kind(EventKind.OUTBOUND_SENT.value, 'Sent')
+register_kind(EventKind.OUTBOUND_RETRIED.value, 'Rate limited, retrying', failure=True)
+register_kind(EventKind.OUTBOUND_FAILED.value, 'Send failed', failure=True)
+register_kind(EventKind.OUTBOUND_DROPPED.value, 'Dropped', failure=True)
+register_kind(EventKind.INBOUND_RECEIVED.value, 'Update received')
+register_kind(EventKind.INBOUND_HANDLED.value, 'Update handled')
+register_kind(EventKind.INBOUND_FAILED.value, 'Handler raised', failure=True)
+register_kind(EventKind.FSM_TRANSITION.value, 'FSM transition')
+register_kind(EventKind.QUEUE_UNDECODABLE.value, 'Undecodable payload', failure=True)
+register_kind(EventKind.QUEUE_REJECTED.value, 'Rejected payload', failure=True)
+register_kind(EventKind.LOG_DROPPED.value, 'Events dropped', failure=True)

django_aiogram/eventlog/instrumentation.py

@@ -0,0 +1,231 @@
+"""Watching what comes in, through the one hook both update sources pass.
+
+Polling and webhook both feed the same ``Dispatcher``, so a single update
+middleware sees every update exactly once. When the log is off nothing is
+registered at all — the cost per update is zero rather than one branch.
+
+FSM transitions come from wrapping the configured storage rather than diffing
+state around the handler: ``set_state`` *is* the transition, so it costs no
+extra round trip and misses none of the ones that happen inside a nested call,
+a filter or a scene. Append-only makes the previous state unnecessary — the
+previous row for the same key is it.
+"""
+
+import logging
+import time
+import uuid
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from aiogram import BaseMiddleware, Dispatcher
+from aiogram.dispatcher.event.bases import CancelHandler
+from aiogram.fsm.state import State
+from aiogram.fsm.storage.base import BaseStorage, StateType, StorageKey
+from aiogram.types import TelegramObject, Update
+from aiogram.types.update import UpdateTypeLookupError
+
+from django_aiogram.config.enums import EventKind
+from django_aiogram.context import correlation_scope, current_correlation_id
+from django_aiogram.eventlog.events import new_correlation_id
+from django_aiogram.eventlog.recorder import Event, recorder
+from django_aiogram.wire.payloads import describe
+
+logger = logging.getLogger('django_aiogram')
+
+
+def state_name(state: StateType) -> str | None:
+    """Name a state the way a reader recognizes it, whatever shape it arrives in."""
+    if state is None:
+        return None
+    if isinstance(state, State):
+        return state.state
+    return str(state)
+
+
+def event_type(update: Update) -> str:
+    """Name the update's type, or nothing when this aiogram does not know it.
+
+    `Update.event_type` raises rather than returning None, and a Bot API newer
+    than the installed aiogram is exactly when it does. aiogram itself treats
+    that as an update to skip, so the log must not be what turns it into an
+    error.
+    """
+    try:
+        return update.event_type
+    except UpdateTypeLookupError:
+        return ''
+
+
+def describe_update(update: Update) -> dict[str, Any]:
+    """Summarize an update, under the same payload policy a send obeys."""
+    message = update.message or update.edited_message
+    query = update.callback_query
+    return describe(
+        {
+            'type': event_type(update) or None,
+            'text': getattr(message, 'text', None),
+            'data': getattr(query, 'data', None),
+        }
+    )
+
+
+@dataclass(frozen=True)
+class Inbound:
+    """What every row about one update needs to name itself."""
+
+    correlation_id: uuid.UUID
+    update_id: int | None
+    chat_id: int | None
+    user_id: int | None
+    started: float
+
+
+class RecordingMiddleware(BaseMiddleware):
+    """One row per update, and the correlation scope its replies inherit."""
+
+    async def __call__(
+        self,
+        handler: Any,  # noqa: ANN401 - aiogram types this as a bare callable
+        event: TelegramObject,
+        data: dict[str, Any],
+    ) -> Any:  # noqa: ANN401 - whatever the handler chain returns
+        """Record the update, then run the handlers inside its correlation scope."""
+        if not isinstance(event, Update):
+            return await handler(event, data)
+
+        inbound = Inbound(
+            correlation_id=new_correlation_id(),
+            update_id=event.update_id,
+            chat_id=getattr(data.get('event_chat'), 'id', None),
+            user_id=getattr(data.get('event_from_user'), 'id', None),
+            started=time.monotonic(),
+        )
+        identifier = inbound.correlation_id
+        data['correlation_id'] = identifier
+
+        recorder.record(
+            Event(
+                kind=EventKind.INBOUND_RECEIVED.value,
+                correlation_id=identifier,
+                update_id=inbound.update_id,
+                function=event_type(event),
+                chat_id=inbound.chat_id,
+                user_id=inbound.user_id,
+                # summarized only for the table: a receiver counting updates has no
+                # use for the text, and this is the costly part of recording one
+                detail=describe_update(event) if recorder.wants_payload else None,
+            )
+        )
+
+        # everything a handler sends inherits this id, so a reply is joined to
+        # the update that caused it without any project code passing it along
+        with correlation_scope(identifier):
+            try:
+                result = await handler(event, data)
+            except CancelHandler:
+                raise
+            except Exception as error:
+                self._record(
+                    EventKind.INBOUND_FAILED,
+                    inbound,
+                    error=error,
+                    raw_state=data.get('raw_state'),
+                )
+                raise
+            self._record(EventKind.INBOUND_HANDLED, inbound, raw_state=data.get('raw_state'))
+            return result
+
+    @staticmethod
+    def _record(
+        kind: EventKind,
+        inbound: 'Inbound',
+        *,
+        error: BaseException | None = None,
+        raw_state: object = None,
+    ) -> None:
+        """Record the outcome of one update, with how long the handlers took."""
+        recorder.record(
+            Event(
+                kind=kind.value,
+                correlation_id=inbound.correlation_id,
+                update_id=inbound.update_id,
+                chat_id=inbound.chat_id,
+                user_id=inbound.user_id,
+                duration_ms=int((time.monotonic() - inbound.started) * 1000),
+                error_code=type(error).__name__ if error is not None else '',
+                error=str(error) if error is not None else '',
+                detail={'state_before': raw_state} if raw_state else {},
+            )
+        )
+
+
+class RecordingStorage(BaseStorage):
+    """Forwards to the configured storage, recording every state change.
+
+    ``set_state`` is the transition, so this needs no extra read and misses
+    none — including the ones a filter or a scene makes.
+    """
+
+    def __init__(self, inner: BaseStorage) -> None:
+        """Hold the storage everything is forwarded to."""
+        self.inner = inner
+
+    async def set_state(self, key: StorageKey, state: StateType = None) -> None:
+        """Set the state, then record the transition it just made."""
+        await self.inner.set_state(key, state)
+        recorder.record(
+            Event(
+                kind=EventKind.FSM_TRANSITION.value,
+                correlation_id=current_correlation_id() or new_correlation_id(),
+                chat_id=key.chat_id,
+                user_id=key.user_id,
+                detail={'to': state_name(state), 'destiny': key.destiny, 'thread_id': key.thread_id},
+            )
+        )
+
+    async def get_state(self, key: StorageKey) -> str | None:
+        """Forward unchanged: reading a state is not a transition."""
+        return await self.inner.get_state(key)
+
+    async def set_data(self, key: StorageKey, data: Mapping[str, Any]) -> None:
+        """Forward unchanged."""
+        await self.inner.set_data(key, data)
+
+    async def get_data(self, key: StorageKey) -> dict[str, Any]:
+        """Forward unchanged."""
+        return await self.inner.get_data(key)
+
+    async def update_data(self, key: StorageKey, data: Mapping[str, Any]) -> dict[str, Any]:
+        """Forward rather than inherit: a storage may make this one round trip."""
+        return await self.inner.update_data(key, data)
+
+    async def close(self) -> None:
+        """Forward: TelegramBot.close releases the storage through this."""
+        await self.inner.close()
+
+
+def install_instrumentation(dispatcher: Dispatcher) -> None:
+    """Register the update middleware, unless nothing is reading events.
+
+    Returning before anything is built is what makes the inactive cost zero:
+    there is no middleware in the chain at all, not one that checks a flag.
+
+    Read once, when the dispatcher is built — so a receiver connected after the
+    first update arrives will not see updates in this process. Connect them while
+    the apps load, which is where Django says signal receivers belong anyway.
+    """
+    if not recorder.active:
+        return
+    dispatcher.update.outer_middleware.register(RecordingMiddleware())
+
+
+def instrumented(storage: BaseStorage) -> BaseStorage:
+    """Wrap the storage when something reads events, and hand it back untouched when not.
+
+    Same one-shot reading as :func:`install_instrumentation`, and for the same
+    reason: the storage is built once.
+    """
+    if not recorder.active:
+        return storage
+    return RecordingStorage(storage)