Архитектура SDK

Обзор

EdgeBot — SDK для создания Telegram-ботов на Python, работающих в Cloudflare Workers через Pyodide. Архитектура оптимизирована под stateless-модель Workers: каждый HTTP-запрос обрабатывается независимо, состояние хранится в KV.

Модули

edgebot/
├── bot.py          # Bot — ядро: обработчики, реестры, маршрутизация
├── context.py      # Context — данные апдейта и методы ответа
├── keyboard.py     # InlineKeyboard — билдер клавиатур
├── api.py          # Низкоуровневые вызовы Telegram Bot API
├── ffi.py          # Мост JS ↔ Python (Pyodide)
├── exceptions.py   # Иерархия исключений
├── storage/
│   ├── kv.py       # KVStore — обёртка над KV-биндингом
│   └── users.py    # UserRegistry — реестр пользователей
├── ui/
│   ├── component.py  # UIComponent — базовый экран
│   ├── keyboards.py  # KeyboardRegistry — реестр клавиатур
│   ├── prompts.py    # Prompt + PromptRegistry
│   ├── routing.py    # Компиляция паттернов в regex
│   ├── registry.py   # Внутренний реестр компонентов
│   └── _filtering.py # Автофильтрация kwargs
└── utils/
    ├── http.py     # fetch с ретраями, sleep
    └── log.py      # Структурированное логирование

Поток обработки апдейта

Telegram → Cloudflare Worker → entry.py
                                  │
                          bot.process_update(update)
                                  │
                          Context(bot, update)
                                  │
                    ┌─────────────┴─────────────┐
                    │  callback_query?           │
                    │  ┌───────────────────┐     │
                    │  │ UI-компоненты     │     │  Команда?
                    │  │ (по __prefix__)   │     │  ┌──────────────┐
                    │  │ → handle_callback │     │  │ on_command    │
                    │  └────────┬──────────┘     │  └──────────────┘
                    │           │ не перехвачен  │
                    │  ┌────────┴──────────┐     │  Медиа?
                    │  │ on_callback       │     │  ┌──────────────┐
                    │  └──────────────────┘     │  │ on_photo/... │
                    │                           │  └──────────────┘
                    │                           │
                    │                           │  Текст?
                    │                           │  ┌──────────────┐
                    │                           │  │ on_message   │
                    │                           │  └──────────────┘
                    └───────────────────────────┘

Приоритет: callback → UI → on_callback → command → media → text.

Каждый апдейт обрабатывается ровно одним типом обработчика.

Слои

1. Transport (точка входа)

WorkerEntrypoint принимает HTTP-запрос от Telegram, проверяет secret_token и передаёт апдейт в bot.process_update(). Этот слой не является частью SDK — он пишется разработчиком.

2. Core (Bot + Context)

Bot — маршрутизатор: определяет тип апдейта и вызывает правильный обработчик. Context — фасад для работы с данными апдейта и методами ответа.

3. UI (UIComponent + реестры)

Опциональный слой для сложных ботов. UIComponent — экран с изолированным контроллером. Реестры (KeyboardRegistry, PromptRegistry) отделяют вью от контроллера.

4. Storage (KVStore + UserRegistry)

Обёртки над Cloudflare KV. KVStore — универсальная, UserRegistry — доменная, с автоматическими timestamps.

5. FFI (ffi + utils)

Мост между Python и JavaScript-рантаймом Workers: конвертация типов, fetch, sleep, логирование.

Stateless-модель

Cloudflare Workers не сохраняют состояние между запросами. Каждый вызов process_update начинается с чистого листа:

• Данные пользователей → KV (через UserRegistry)
• Данные экранов → не хранятся (рассчитываются из KV на каждый запрос)
• UI-компоненты — синглтоны без состояния

Это означает, что UIComponent никогда не хранит данные в self.* полях — все данные приходят из Context (KV, реестры, параметры callback_data).