ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

Спецификация операций запросов ErisPulse

Tip

Когда нужно читать эту статью: когда вашему адаптеру нужно обрабатывать запросы от друзей/приглашения в группы (преобразование событий запросов, реализация accept/reject, сохранение контекста запросов с гетерогенными эндпоинтами), или когда модули используют event.approve() / event.reject() для одобрения запросов. Если не нужно, то можно пропустить.

В этом документе определены стандартизированные спецификации операций запросов в адаптере ErisPulse, включая требования к полям запроса, использование DSL для запроса и требования к реализации адаптера.

1. Обзор

Событие запроса (type: "request") — это специальный тип события, определенный в OneBot12, представляющий запрос, требующий принятия решения ботом (например, запрос на добавление в друзья, приглашение в группу и т.д.).

В отличие от событий сообщений, запросы требуют двустороннего взаимодействия:

  1. Прием: адаптер преобразует платформенный оригинальный запрос в стандартное событие запроса
  2. Ответ: модуль выполняет операции через DSL для запроса или Event.approve()/Event.reject().
Событие платформенного запроса
    │
    ▼
Converter.convert()        ← Реализация адаптера (прямое преобразование)
    │
    ▼
Стандартное событие запроса (с request_id)
    │
    ├─→ Обработчик модуля @request.on_friend_request()
    │       │
    │       ├─→ event.approve()     ← Согласие с запросом
    │       └─→ event.reject()      ← Отказ в запросе
    │               │
    │               ▼
    │       adapter.Request(request_id).accept()
    │               │
    │               ▼
    │       BaseAdapter.Request.accept()  ← Переопределение адаптером
    │               │
    │               ▼
    │       Вызов API платформы
    │
    └─→ Или напрямую через операции адаптера
            await adapter.Request("req_id").accept()

2. Требования к полям запроса

2.1 Стандартные поля

Событие запроса, помимо обязательных полей OneBot12, должно содержать следующие поля:

Поле Тип Обязательно Описание
request_id string Рекомендуется Идентификатор запроса, используется для согласия/отказа
user_id string Да Идентификатор отправителя запроса
user_nickname string Нет Никнейм отправителя запроса
comment string Нет Комментарий к запросу

2.2 Поле request_id

request_id является ключевым идентификатором для запроса:

  • Назначение: идентификация запроса, используемого для операций через DSL для запроса
  • Правила генерации:
    • В первую очередь использовать оригинальный идентификатор платформы (например, flag из OneBot11, chat_invite_link из Telegram и т.д.)
    • Если платформа не предоставляет оригинальный идентификатор, адаптер должен сгенерировать уникальный идентификатор (рекомендуемый формат: {platform}_{timestamp}_{user_id})
  • Уникальность: в рамках одной платформы должен быть уникален
  • Поведение при отсутствии: если request_id отсутствует, event.approve() / event.reject() выбросят ValueError

2.3 Пример события запроса

{
  "id": "evt_123456",
  "time": 1752241225,
  "type": "request",
  "detail_type": "friend",
  "platform": "onebot11",
  "self": {
    "platform": "onebot11",
    "user_id": "bot_123"
  },
  "user_id": "user_456",
  "user_nickname": "YingXinche",
  "comment": "Пожалуйста, добавьте в друзья",
  "request_id": "flag_abc123",
  "onebot11_raw": {...},
  "onebot11_raw_type": "request"
}

3. DSL для запроса

3.1 Цепочечные вызовы

Request предоставляет интерфейс цепочечных вызовов, аналогичный Send:

# Базовое использование
await adapter.Request("req_id").accept()
await adapter.Request("req_id").reject()

# Указание аккаунта бота
await adapter.Request("req_id").Using("bot1").accept()

# Добавление комментария (через kwargs)
await adapter.Request("req_id").accept(comment="Добро пожаловать")
await adapter.Request("req_id").reject(comment="Временно не добавляю")

# Комбинированные вызовы
await adapter.Request("req_id").Using("bot1").accept(comment="Добро пожаловать")

3.2 Список методов

Метод Описание Возвращаемое значение
Using(account_id) Указывает аккаунт бота для выполнения операции RequestDSL (поддерживает цепочечные вызовы)
accept(**kwargs) Согласие с запросом asyncio.Task (возвращает стандартный ответ после await)
reject(**kwargs) Отказ в запросе asyncio.Task (возвращает стандартный ответ после await)

3.3 Формат возвращаемых значений

Операции возвращают стандартный формат ответа API:

Успех:

{
    "status": "ok",
    "retcode": 0,
    "data": null,
    "message_id": "",
    "message": ""
}

Ошибка:

{
    "status": "failed",
    "retcode": 34001,
    "data": null,
    "message_id": "",
    "message": "Запрос просрочен или не существует"
}

Не реализовано (адаптер не переопределил _do_accept/_do_reject):

{
    "status": "failed",
    "retcode": 10002,
    "data": null,
    "message_id": "",
    "message": "Платформа MyAdapter не реализовала операцию запроса (accept)"
}

4. Удобные методы Event

Класс Event предоставляет удобные методы, подходящие для использования в обработчиках событий запроса:

from ErisPulse.Core.Event import request

@request.on_friend_request()
async def handle_friend_request(event):
    # Проверка идентификатора запроса
    request_id = event.get_request_id()
    if not request_id:
        print("Предупреждение: событие запроса не содержит request_id")
        return
    
    # Согласие с запросом
    result = await event.approve()
    
    # Или отказ в запросе
    # result = await event.reject(comment="Временно не добавляю в друзья")
    
    # Проверка результата
    if result.get("status") == "ok":
        print("Операция выполнена успешно")
    else:
        print(f"Операция не удалась: {result.get('message')}")

4.1 Список методов Event

Метод Описание Возвращаемое значение
get_request_id() Получает идентификатор запроса str
approve(comment=None) Согласие с текущим событием запроса Стандартный формат ответа
reject(comment=None) Отказ в текущем событии запроса Стандартный формат ответа

5. Требования к реализации адаптера

5.1 Требования к конвертеру

Конвертер адаптера при преобразовании событий запроса обязан корректно устанавливать поле request_id:

def convert_request_event(self, raw_event: dict) -> dict:
    """Преобразование нативного события запроса платформы"""
    return {
        "id": self._generate_event_id(raw_event),
        "time": int(time.time()),
        "type": "request",
        "detail_type": self._map_request_type(raw_event),  # "friend" или "group"
        "platform": self._platform_name,
        "self": {
            "platform": self._platform_name,
            "user_id": str(self._bot_id),
        },
        "user_id": str(raw_event.get("user_id", "")),
        "user_nickname": raw_event.get("nickname", ""),
        "comment": raw_event.get("message", ""),
        "request_id": self._extract_request_id(raw_event),  # ← ключевое поле
        f"{self._platform_name}_raw": raw_event,
        f"{self._platform_name}_raw_type": raw_event.get("type", ""),
    }

def _extract_request_id(self, raw_event: dict) -> str:
    """
    Извлечение ID запроса из нативного события платформы
    
    Приоритетно используется нативный идентификатор запроса платформы,
    при его отсутствии генерируется уникальный ID
    """
    # Приоритетно используется нативный ID платформы
    if flag := raw_event.get("flag"):
        return str(flag)
    if request_key := raw_event.get("request_key"):
        return str(request_key)
    
    # Запасной вариант: генерация уникального ID
    import hashlib
    raw = f"{self._platform_name}_{raw_event.get('user_id')}_{raw_event.get('timestamp')}"
    return hashlib.md5(raw.encode()).hexdigest()

5.2 Реализация внутреннего класса Request

accept() / reject() базового класса — это публичные точки входа: встроенный шлюз авторизации scope (scope.actions.<owner>.request, при отключении сразу возвращает ответ с отказом 34601) и обёртка задачи. Адаптер не должен переопределять публичные точки входа — переопределение обойдёт шлюз авторизации. Адаптер переопределяет _do_accept / _do_reject (асинхронные методы, напрямую возвращающие стандартный dict ответа).

Напоминание о мультиаккаунтности: внутри _do_accept / _do_reject адаптер сам вызывает call_api, аккаунт не внедряется автоматически — аккаунт получается через self.request_context.get("account_id") (явное указание Using() > автоматическая привязка по цепочке событий, тот же принцип, что и send_context у Send) и передаётся в call_api как параметр account_id, иначе при мультиаккаунтном развёртывании операция попадёт на аккаунт по умолчанию.

from ErisPulse.Core import BaseAdapter, RequestDSL

class MyAdapter(BaseAdapter):
    
    class Request(RequestDSL):
        """Реализация операций запроса MyPlatform"""
        
        async def _do_accept(self, **kwargs) -> dict:
            """
            Одобрить запрос
            
            :param kwargs: расширенные параметры, например comment="примечание"
            :return: dict стандартного формата ответа
            """
            try:
                result = await self._adapter.call_api(
                    endpoint="/set_request",
                    request_id=self._request_id,
                    account_id=self.request_context.get("account_id"),
                    approve=True,
                    **kwargs,
                )
                return {
                    "status": "ok" if result.get("code") == 0 else "failed",
                    "retcode": result.get("code", 0),
                    "data": None,
                    "message_id": "",
                    "message": result.get("message", ""),
                }
            except Exception as e:
                return {
                    "status": "failed",
                    "retcode": 34001,
                    "data": None,
                    "message_id": "",
                    "message": f"Ошибка операции запроса: {e}",
                }
        
        async def _do_reject(self, **kwargs) -> dict:
            """Отклонить запрос (изоморфно _do_accept: approve=False)"""

5.3 Сохранение контекста типа запроса (обязательно для адаптеров с гетерогенными эндпоинтами)

5.3.1 Пробел в контракте

DSL Request — это дескриптор без состояния: вызывающая сторона владеет только request_id (§3), тип запроса не входит в параметры вызова. При этом у многих платформ эндпоинты одобрения/отклонения гетерогенны — на примере семейства OneBot11:

Тип запроса Эндпоинт
Добавление в друзья set_friend_add_request(flag, approve)
Заявка в группу / Приглашение в группу set_group_add_request(flag, sub_type, approve), sub_type ∈ {"add", "invite"}

Вызывающая сторона знает только request_id, но для выбора эндпоинта нужен тип. Этот контекст может восполнить только адаптер: события запроса и так принимаются и преобразуются адаптером (информация о типе уже есть в руках в момент преобразования), а тип запроса, соответствующий request_id, не меняется. Если адаптер не сохранит его самостоятельно, остаётся только угадывать эндпоинт или полагаться на нестандартные параметры от вызывающей стороны — типичная форма сбоя: приглашение в группу попадает в эндпоинт для друзей, flag разбирается протокольной стороной как user_id, и возникает ошибка.

5.3.2 Требования спецификации

Для адаптеров платформ с гетерогенными эндпоинтами (одобрение/отклонение требует маршрутизации по типу запроса) реализация accept / reject должна удовлетворять следующему:

  1. Сохранение на стороне события: в точке входа получения адаптером события запроса записывать request_id → {тип запроса, sub_type, group_id, аккаунт} в кэш экземпляра (единые поля см. §5.3.3) и попутно очищать устаревшие записи
  2. Маршрутизация на стороне операции: порядок выбора эндпоинта внутри _do_accept / _do_reject: явные параметры kwargs > кэш > откат к эндпоинту по умолчанию с записью WARNING — при неизвестном типе обязательно логировать (наблюдаемость), молча выбирать эндпоинт нельзя
  3. Зарезервированные имена kwargs: явно переопределяющие параметры именуются единообразно request_type / sub_type / group_id (без подчёркивания в качестве префикса, одинаковые имена и значения во всех адаптерах); не использовать приватные условные имена вроде _request_type (стандартный вызывающий их не передаёт)
  4. Чтение аккаунта и проверка принадлежности: аккаунт операции получается единообразно через свойство базового класса self.request_context.get("account_id") (явное указание Using() > автоматическая привязка по цепочке событий, тот же принцип, что и send_context у Send); аккаунт прибытия события из сохранённой записи служит запасным вариантом при отсутствии цепочки событий (например, синтезированные события опроса, восстановление после перезапуска). Если аккаунт не удаётся разрешить в конкретный экземпляр аккаунта, обязателен быстрый отказ (возврат 34005), молча откатываться к аккаунту по умолчанию нельзя — откат направит операцию в ошибочное соединение (flag не существует в сессии аккаунта по умолчанию, платформа сообщит invalid, при мультиаккаунтности проявляется как «оперировать может только первый аккаунт»)
  5. Персистентность по умолчанию: носителем сохранения по умолчанию является единое хранилище фреймворка (self.sdk.storage) — полный снимок одним ключом — запросы относятся к низкочастным событиям типа одобрений, write-through выполняется сразу при прибытии события (след в хранилище всегда составляет 1 ключ); при запуске однократная загрузка в память, во время работы путь чтения без накладных расходов; при недоступности хранилища — деградация до режима «только память» (WARNING), поток событий не блокируется
  6. Очистка после обработки: после успешной отправки операции удалить запись request_id и синхронно выполнить write-through снимка

Для платформ с единым эндпоинтом запросов (например, унифицированный /set_request) сохранение не требуется, достаточно прозрачной передачи. Данный раздел задаёт требования к реализации адаптера, контракт DSL Request при этом не затрагивается.

5.3.3 Единые поля записи (независимо от носителя)

Записи контекста сохраняются в следующей единой форме полей. Форма полей — это контракт интероперабельности: dict в памяти, значение KV, строка ORM — все сохраняются в одной и той же форме, при последующей межадаптерной агрегации или миграции форма остаётся согласованной; носитель хранения выбирается свободно, семантика полей не меняется в зависимости от носителя.

Поле Тип Обязательное Семантика и источник
request_type str Да Тип запроса, берётся из detail_type события ("friend" / "group")
sub_type str | None Обязательно для групповых запросов Подтип группового запроса "add" / "invite", берётся из нативного события платформы (sub_type семейства OB11)
group_id str | None Обязательно для групповых запросов ID целевой группы, берётся из нативного события платформы
account str | None Обязательно при мультиаккаунтности Аккаунт прибытия события, берётся из self.user_id события
ts float Да Unix-метка времени прибытия события (в секундах), база для определения TTL

Правила согласованности записей:

  • Взаимно однозначное соответствие: одному request_id соответствует не более одной записи; повторные события с тем же request_id перезаписывают её (идемпотентность)
  • Удаление после обработки: запись удаляется сразу после успешной отправки операции
  • TTL: отсчёт от ts, рекомендуемый порядок — 1 час (покрывает срок действия запроса на стороне платформы); истёкшая запись считается несохранённой, путь — откат к эндпоинту по умолчанию + WARNING
  • Имя ключа (при KV-персистентности): {ключ конфигурации адаптера}:request_ctx:{request_id} — во избежание конфликтов между адаптерами

5.3.4 Референсная реализация (снимок одним ключом в едином хранилище, по умолчанию)

Носителем сохранения по умолчанию является единое хранилище фреймворка (self.sdk.storage): события запросов — низкочастные события типа одобрений (запросы в друзья/группы, не поток сообщений), write-through при прибытии события не создаёт нагрузки на запись. Форма хранения — полный снимок одним ключом: весь словарь контекста записывается одним ключом за один раз (след в хранилище всегда составляет 1 ключ, автоматически сокращается по мере обработки), без разделения на ключи по каждому flag. После перезапуска при старте выполняется однократная загрузка в память, во время работы путь чтения без накладных расходов.

import time

from ErisPulse.Core import BaseAdapter, RequestDSL


class MyAdapter(BaseAdapter):
    """Платформа с гетерогенными эндпоинтами запросов (раздельные эндпоинты для запросов в друзья и в группы)"""

    _REQ_CTX_TTL = 86400   # Время хранения в секундах (покрывает срок действия flag на стороне платформы, не теряется при перезапуске)
    _REQ_CTX_MAX = 512     # Верхний предел количества записей

    def __init__(self, sdk=None):
        super().__init__(sdk)
        self._request_ctx: dict[str, dict] = {}   # request_id → контекст запроса (состояние в памяти)
        self._ctx_key = f"{self._get_config_key()}:request_ctx"   # полный снимок одним ключом

    async def start(self):
        # Загрузка при старте (одобрение доступно и после перезапуска); при недоступности хранилища трактуется как холодный старт
        try:
            loaded = self.sdk.storage.get(self._ctx_key, {}) or {}
            now = time.time()
            self._request_ctx = {k: v for k, v in loaded.items()
                                 if now - v.get("ts", 0) <= self._REQ_CTX_TTL}
        except Exception as e:
            self.logger.warning(f"Не удалось загрузить контекст запросов (трактуется как холодный старт): {e}")
            self._request_ctx = {}

    def _persist_ctx(self) -> None:
        """Write-through полного снимка одним ключом (при недоступности хранилища — деградация до режима «только память», поток событий не блокируется)"""
        try:
            self.sdk.storage.set(self._ctx_key, self._request_ctx)
        except Exception as e:
            self.logger.warning(f"Не удалось выполнить write-through контекста запросов (деградация до режима «только память»): {e}")

    def remember_request(self, request_id: str, *, request_type: str,
                         sub_type: str | None = None, group_id: str | None = None,
                         account: str | None = None) -> None:
        """Сохранение контекста запроса на стороне события (вызывается в точке входа получения адаптером события запроса)"""
        now = time.time()
        expired = [k for k, c in self._request_ctx.items() if now - c["ts"] > self._REQ_CTX_TTL]
        for k in expired:
            self._request_ctx.pop(k)
        while len(self._request_ctx) >= self._REQ_CTX_MAX:
            self._request_ctx.pop(min(self._request_ctx, key=lambda k: self._request_ctx[k]["ts"]))
        self._request_ctx[request_id] = {
            "request_type": request_type,   # "friend" / "group"
            "sub_type": sub_type,           # подтип группового запроса: "add" / "invite"
            "group_id": group_id,
            "account": account,             # аккаунт прибытия события (self.user_id события / имя аккаунта-заместителя)
            "ts": now,
        }
        self._persist_ctx()

    class Request(RequestDSL):
        """Маршрутизация эндпоинтов: явные параметры kwargs > кэш > откат к эндпоинту по умолчанию + WARNING"""

        def _route(self, **kwargs) -> dict:
            ctx = {k: kwargs[k] for k in ("request_type", "sub_type", "group_id") if kwargs.get(k)}
            cached = self._adapter._request_ctx.get(self._request_id, {})
            if not ctx.get("request_type"):
                ctx.update({k: v for k, v in cached.items()
                            if k in ("request_type", "sub_type", "group_id") and v})
                ctx.setdefault("account", cached.get("account"))
            if not ctx.get("request_type"):
                self._adapter.logger.warning(f"Тип запроса {self._request_id} неизвестен, выполняется откат к эндпоинту для друзей")
                ctx["request_type"] = "friend"
            return ctx

        def _resolve_or_fail(self, account):
            """
            Проверка принадлежности аккаунта при одобрении: при неудаче разрешения — быстрый отказ (34005),
            без отката к аккаунту по умолчанию.

            Откат к аккаунту по умолчанию направит операцию в ошибочное соединение
            (flag не существует в сессии этого аккаунта, платформа сообщит invalid,
            что проявляется как «мистический» сбой «оперировать может только первый аккаунт»).
            """
            if not account:
                return None, None            # при отсутствии какой-либо информации об аккаунте сохраняется семантика аккаунта по умолчанию
            name, inst = self._adapter._resolve_account(account)
            hit = str(account) == str(name) or str(account) == str(getattr(inst, "bot_id", "") or "")
            if not hit:
                self._adapter.logger.warning(
                    f"Аккаунт {account} запроса {self._request_id} не удаётся разрешить, откат к аккаунту по умолчанию отклонён")
                return None, "34005"
            return (name, inst), None

        async def _do_accept(self, **kwargs) -> dict:
            """Одобрить запрос; маршрутизацию типа в kwargs можно явно переопределить через request_type / sub_type / group_id"""
            return await self._do_action(approve=True, **kwargs)

        async def _do_reject(self, **kwargs) -> dict:
            """Отклонить запрос (изоморфно _do_accept: approve=False)"""
            return await self._do_action(approve=False, **kwargs)

        async def _do_action(self, approve: bool, **kwargs) -> dict:
            ctx = self._route(**kwargs)
            account = self.request_context.get("account_id") or ctx.get("account")
            resolved, fail = self._resolve_or_fail(account)
            if fail:
                return {
                    "status": "failed", "retcode": 34005, "data": None,
                    "message_id": "", "message": f"Не удаётся разрешить аккаунт запроса {account} в экземпляр аккаунта",
                }
            try:
                if ctx["request_type"] == "group":
                    result = await self._adapter.call_api(
                        endpoint="/set_group_add_request",
                        flag=self._request_id,
                        sub_type=ctx.get("sub_type") or "add",
                        approve=approve,
                        account_id=account,
                    )
                else:
                    result = await self._adapter.call_api(
                        endpoint="/set_friend_add_request",
                        flag=self._request_id,
                        approve=approve,
                        account_id=account,
                    )
                response = {
                    "status": "ok" if result.get("code") == 0 else "failed",
                    "retcode": result.get("code", 0),
                    "data": None,
                    "message_id": "",
                    "message": result.get("message", ""),
                }
            except Exception as e:
                response = {
                    "status": "failed", "retcode": 34001, "data": None,
                    "message_id": "", "message": f"Ошибка операции запроса: {e}",
                }
            if response["status"] == "ok":
                self._adapter._request_ctx.pop(self._request_id, None)   # очистка после обработки
                self._adapter._persist_ctx()
            return response

5.3.5 Границы и деградация

Семантика деградации: при недоступности единого хранилища (fast-fail в период охлаждения после ошибки соединения) write-through деградирует до режима «только память» (WARNING для наблюдаемости), события распределяются как обычно; после перезапуска потерянные записи идут по пути «откат при неизвестном типе + WARNING».

Эквивалентный носитель: встроенная ORM (таблица с первичным ключом request_id, см. Слой моделей данных) семантически эквивалентна, адаптер может выбрать её по необходимости; без дополнительных файлов или новых зависимостей.

Границы мультиэкземплярности: данная спецификация не охватывает координацию мультипроцессных экземпляров — ErisPulse использует модель «один процесс, много ботов» (мультиаккаунтность в одном процессе, запросы и их принадлежащий аккаунт естественно находятся на одной стороне), единое хранилище удовлетворяет семантике перезапуска; совместное использование между экземплярами (распределение аккаунтов по процессам) — при необходимости отдельный проект.

5.4 Платформа не поддерживает операции запросов

Если платформа сама не поддерживает операции запросов в друзья/приглашений в группы (например, некоторые платформы автоматически обрабатывают запросы), адаптер может:

  1. Не переопределять внутренний класс Request: использовать реализацию базового класса по умолчанию, при вызове accept()/reject() возвращается retcode=10002
  2. Пропускать request_id при преобразовании: не генерировать request_id, чтобы event.approve() выбрасывал ValueError
  3. Записывать в лог: в _do_accept / _do_reject записывать предупреждение и возвращать соответствующий код ошибки

5.5 Итог: Send и Request работают параллельно

У адаптера есть два параллельных внутренних класса DSL, каждый выполняет свою роль:

BaseAdapter
├── Send(SendDSL)     ← отправка сообщений
│   ├── Raw_ob12()    ← обязательна к реализации
│   ├── Text()        ← рекомендуется к реализации
│   └── Image()       ← реализуется по необходимости
│
└── Request(RequestDSL) ← операции запросов
    ├── accept()        ← публичная точка входа (шлюз scope + обёртка задачи, не переопределять)
    ├── reject()        ← публичная точка входа (аналогично)
    ├── _do_accept()    ← переопределяется по необходимости
    └── _do_reject()    ← переопределяется по необходимости

5.6 Замечания по __init__ адаптера

При переопределении __init__ внутреннего класса Request необходимо пробрасывать параметры и вызывать super().__init__(), подробнее см. Введение в разработку адаптеров — замечания по __init__ (для Request аналогично, параметры: adapter, request_id, account_id).

6. Чек-лист реализации адаптера

Базовые требования

  • Если переопределён __init__, вызван super().__init__() (гарантирует инициализацию фабрик Send / Request)

Преобразование событий запросов

  • Событие запроса содержит поле request_id (настоятельно рекомендуется)
  • detail_type корректно отображается в "friend" или "group"
  • Исходные данные платформы сохраняются в поле {platform}_raw
  • Правила генерации request_id задокументированы

Операции с запросами

  • Внутренний класс Request реализован (если платформа поддерживает операции с запросами)
  • _do_accept() / _do_reject() переопределены (не переопределяйте публичные методы accept() / reject() — это обходит шлюз авторизации scope)
  • Операции возвращают стандартный формат ответа API
  • Неподдерживаемые операции возвращают retcode=10002
  • Сетевые ошибки возвращают retcode=33xxx (в соответствии со стандартом ответов API)

Сохранение контекста типа запроса (платформы с гетерогенными эндпоинтами, см. §5.3)

  • На входе событий запросов сохранён контекст request_id → {тип запроса, sub_type, group_id, аккаунт}
  • Поля записей соответствуют единой таблице полей §5.3.3 (включая метку времени ts; request_id строго соответствует один к одному, запись удаляется после обработки)
  • Порядок маршрутизации эндпоинтов accept / reject: явные kwargs > кэш > запасной эндпоинт по умолчанию + WARNING
  • Параметры переопределения типа используют зарезервированные имена request_type / sub_type / group_id (без приватных имён вроде _request_type)
  • Кэш имеет TTL и ограничение по ёмкости; после успешной отправки операции соответствующая запись удаляется
  • Мультиаккаунт: аккаунт операции считывается через self.request_context.get("account_id") (Using() > резервный вариант на основе цепочки событий); сохранённый аккаунт используется как запасной при отсутствии цепочки событий
  • При ошибке разрешения аккаунта одобрения — быстрый отказ (34005), без отката к аккаунту по умолчанию
  • По умолчанию — единое хранилище одноключевых снимков: загрузка при запуске, сквозная запись при поступлении/обработке событий, при недоступности хранилища — деградация до работы только в памяти

7. Расширение кодов ошибок

Рекомендуемые коды ошибок для уровня реализации адаптера, относящиеся к операциям с запросами (в соответствии со стандартом ответов API §3.2, настраиваемые младшие три цифры в сегменте ошибок платформы 34xxx):

Код ошибки Название ошибки Описание
34001 Request Not Found Запрос не существует или срок его действия истёк
34002 Request Already Handled Запрос уже был обработан
34003 Request Not Supported Платформа не поддерживает операции с запросами данного типа
34004 Permission Denied У бота нет прав на обработку данного запроса (возвращается платформой)
34005 Request Account Unresolved Не удаётся сопоставить аккаунт, к которому относится запрос, с экземпляром аккаунта (fail-fast, без отката к аккаунту по умолчанию)

Граница с кодами фреймворка: указанные выше 340xx — это сбои обработки запросов, возвращаемые платформой/адаптером; когда фреймворк ErisPulse отключает request-действие (action) некоторого модуля через scope.actions, он до вызова адаптера сразу возвращает 34601 (Action Denied, см. стандарт ответов API §5.3); они не заменяют друг друга: сначала запрос проходит через шлюз фреймворка 34601, а уже затем попадает на уровень ошибок платформы 340xx.

8. Связанные документы

Документы для сопоставления при реализации операций запроса:

Другие DSL в одном адаптере: