08 WIKI

REPOSITORY / ScuroNeko/Laniakea

Wiki

猫

KNOWLEDGE REPOSITORY

REPOSITORY ScuroNeko/Laniakea

DEFAULT BRANCH main

SECTION Wiki

4

Update Routing Model RU

ScuroNeko edited this page 2026-05-20 13:28:29 +03:00

Table of Contents

• Update Routing Model RU
• Верхнеуровневая маршрутизация
• Что делает prepareUpdateCtx(...)
• Контракт command flow
• Контракт payload flow
• Callback query, привязанный к обычному сообщению
• Callback query, привязанный к inline message
• Контракт generic update handlers
• Нормализованные поля MessageContext по видам update
• Update types, которые несут message
• Update types с user, но без message
• Callback-specific update type
• Update types без нормализованных гарантий по user/message
• Что уже достаточно стабильно
• Что пока намеренно не закрыто
• Связанные страницы

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Update Routing Model RU

English version: Update-Routing-Model

Эта страница фиксирует текущий контракт маршрутизации обновлений в Laniakea: какие Telegram update types идут через команды, какие через данные callback, какие через generic update handlers, и какие гарантии по MessageContext существуют в каждом потоке.

Это описание текущего поведения фреймворка, а не отдельная новая API-поверхность. Цель страницы — сделать уже существующую маршрутизацию и нормализацию MessageContext явной и тестируемой.

Верхнеуровневая маршрутизация

Сейчас Laniakea маршрутизирует обновления так:

Update type	Routing path
message	command flow
channel_post	command flow
callback_query	payload flow
всё остальное	AddUpdateHandler(...)

Важно:

• message, channel_post и callback_query зарезервированы и не должны регистрироваться через AddUpdateHandler(...).
• сцены проверяются раньше обычной маршрутизации, но текущая модель сцен всё ещё по сути ориентирована на сообщения.

Что делает prepareUpdateCtx(...)

До маршрутизации обработчиков Laniakea нормализует MessageContext из входящего Telegram update.

Эта нормализация намеренно шире, чем command и payload routing:

• некоторые update types заполняют ctx.Msg
• некоторые заполняют ctx.From и ctx.FromID
• callback queries могут заполнять callback target поля
• ctx.Text, ctx.Args и ctx.Prefix на этом этапе не заполняются

Это важное разделение:

• prepareUpdateCtx(...) задаёт сырой нормализованный shape контекста
• routing потом определяет, какой handler path получит этот контекст

Контракт command flow

Command flow применяется только к:

• message
• channel_post

Когда команда совпала, действуют такие гарантии:

• ctx.Update всегда заполнен
• ctx.Msg заполнен
• ctx.Prefix содержит совпавший префикс команды
• ctx.Text содержит хвост после имени команды
• ctx.Args содержит strings.Fields(ctx.Text)
• ctx.Logger переключается на logger совпавшего плагина, если он задан

Не гарантируется:

• ctx.From
• ctx.FromID

Показательный edge case:

• channel_post, пришедший через sender_chat, всё равно даёт ctx.Msg
• но ctx.From может быть nil
• а ctx.FromID может оставаться 0

Контракт payload flow

Payload flow применяется только к:

• callback_query

Базовые гарантии:

• ctx.Update всегда заполнен
• ctx.CallbackQueryID заполнен
• ctx.From и ctx.FromID заполняются, если Telegram прислал user
• ctx.Args заполняется из декодированных данных callback
• ctx.Logger переключается на logger совпавшего плагина, если он задан

Не гарантируется:

• ctx.Text
• ctx.Prefix

У payload flow есть две формы target.

Callback query, привязанный к обычному сообщению

Гарантии:

• ctx.Msg заполнен
• ctx.CallbackMsgID заполнен
• ctx.InlineMsgID == ""

Callback query, привязанный к inline message

Гарантии:

• ctx.Msg == nil
• ctx.CallbackMsgID == 0
• ctx.InlineMsgID заполнен

Контракт generic update handlers

Generic update handlers регистрируются через Plugin.AddUpdateHandler(...).

Они применяются ко всем update types вне зарезервированного command/payload flow.

Общие гарантии:

• ctx.Update всегда заполнен
• ctx.Text не нормализуется
• ctx.Args не нормализуется
• ctx.Prefix не нормализуется
• каждый plugin update handler получает свою копию MessageContext struct

Важное ограничение:

• копируется сам MessageContext, но не обещается глубокая копия всех вложенных Telegram-структур

Нормализованные поля MessageContext по видам update

Update types, которые несут message

Update type	ctx.Msg	ctx.From / ctx.FromID
message	да	да, если есть Msg.From
edited_message	да	да, если есть Msg.From
channel_post	да	только если есть Msg.From
edited_channel_post	да	только если есть Msg.From
business_message	да	да, если есть Msg.From
edited_business_message	да	да, если есть Msg.From

Важно:

• message-backed не означает command-routed
• edited_message, edited_channel_post, business_message и edited_business_message сейчас автоматически не попадают в command flow

Update types с user, но без message

Update type	ctx.Msg	ctx.From / ctx.FromID
inline_query	нет	да
chosen_inline_result	нет	да
shipping_query	нет	да
pre_checkout_query	нет	да
purchased_paid_media	нет	да
my_chat_member	нет	да
chat_member	нет	да
chat_join_request	нет	да
business_connection	нет	да
poll_answer	нет	да
message_reaction	нет	да, если Telegram прислал User
chat_boost	нет	да
removed_chat_boost	нет	да

Callback-specific update type

Update type	ctx.Msg	ctx.From / ctx.FromID	Спецполя
callback_query с Message	да	да	CallbackQueryID, CallbackMsgID
callback_query с InlineMessageID	нет	да	CallbackQueryID, InlineMsgID

Update types без нормализованных гарантий по user/message

Update type	ctx.Msg	ctx.From / ctx.FromID
poll	нет	нет
message_reaction_count	нет	нет
deleted_business_messages	нет	нет
unknown	нет	нет

Что уже достаточно стабильно

• message и channel_post остаются в command flow
• callback_query остаётся в payload flow
• prepareUpdateCtx(...) сам по себе не заполняет Text, Args и Prefix
• command parsing заполняет Text, Args и Prefix
• payload decoding заполняет Args, но не Text
• callback target разделяется на chat-message callbacks и inline-message callbacks
• edited_message и edited_channel_post не входят в command routing

Что пока намеренно не закрыто

• должны ли сцены оставаться только message-driven или получить более широкую update model
• должны ли edited/business message-backed updates когда-нибудь получить command-style routing
• стоит ли оформлять “message-backed update” как отдельную внутреннюю концепцию фреймворка

Связанные страницы

• Commands-and-Plugins-RU
• MessageContext-RU
• Scenes-RU
• Bot-Lifecycle-RU

Navigation

Start here

• Home
• Home-RU
• Getting-Started
• Bot-Options-and-Configuration
• Commands-and-Plugins
• MessageContext

Runtime and Architecture

• Bot-Lifecycle
• Webhook-Runtime
• Middleware
• Runners
• Error-Handling
• Logging
• Update-Routing-Model
• Policies
• Scenes

Interaction and Telegram API

• Inline-Keyboards-and-Payloads
• Auto-Generated-Commands
• Drafts
• Rich-Messages
• Localization
• Rate-Limiting
• tgapi-Overview

Practical Guides

• Recipes
• Sentry-Integration
• Testing-Bots-with-Laniakea

Maintenance

• Migration
• V2-Migration-Plan (DRAFT)
• Semver-and-Releases
• Framework-Backlog