ScuroNeko/Laniakea

Fork 0

REPOSITORY / ScuroNeko/Laniakea

Wiki

KNOWLEDGE REPOSITORY

Table of Contents

Policies

Что дают политики
Основной API
Регистрация
Встроенные политики
Композиция

AllPolicies
AnyPolicy
NotPolicy

Модель ошибок
Текущие ограничения

Policies

Policies — это полноценная модель правил авторизации в Laniakea. Политика работает поверх нормализованного MessageContext и переданных AppData, возвращает nil, если доступ разрешён, и возвращает ошибку, если действие нужно запретить или сама проверка не смогла корректно выполниться.

Policies не вводят вторую модель выполнения. Они встраиваются в уже существующий middleware pipeline через RequirePolicy(...), поэтому авторизация остаётся на том же пути маршрутизации, что и остальной фреймворк.

Что дают политики

Переиспользуемую абстракцию Policy[T] для проверок доступа.
Интеграцию с middleware через RequirePolicy(...).
Helpers регистрации на Bot и Plugin через UsePolicy(...).
Встроенные Telegram-aware проверки для типичных ограничений по типу чата и правам.
Комбинаторы для all-of, any-of и инверсии правила.

Основной API

type Policy[T laniakea.AppData] func(ctx *laniakea.MessageContext, data T) error

func RequirePolicy[T laniakea.AppData](name string, p Policy[T]) Middleware[T]

func AllPolicies[T laniakea.AppData](policies ...Policy[T]) Policy[T]
func AnyPolicy[T laniakea.AppData](policies ...Policy[T]) Policy[T]
func NotPolicy[T laniakea.AppData](policy Policy[T]) Policy[T]

Контракт политики намеренно остаётся маленьким:

Вернуть nil, чтобы разрешить выполнение.
Вернуть пользовательскую ошибку, чтобы запретить выполнение.
Вернуть внутреннюю ошибку, чтобы остановить выполнение без утечки текста сбоя пользователю.

Поскольку политики используют обычную модель ошибок, они естественно сочетаются с AsUserError(...) и AsInternalError(...).

Регистрация

Политики подключаются через ту же конфигурационную поверхность бота и плагинов, что и middleware.

bot.UsePolicy("human-callbacks", laniakea.RequireCallbackFromUser())

plugin.UsePolicy(
	"admin-only",
	laniakea.AllPolicies(
		laniakea.RequireGroupChat(),
		laniakea.RequireChatAdmin(),
	),
)

RequirePolicy(...) — это нижележащий адаптер, если хочется добавить получившееся middleware вручную.

Встроенные политики

Текущий набор встроенных helpers ориентирован на типичные Telegram-specific проверки доступа:

RequirePrivateChat(...)
RequireGroupChat(...)
RequireSupergroupChat(...)
RequireChatAdmin(...)
RequireChatCreator(...)
RequireBotAdmin(...)
RequireCallbackFromUser(...)

Эти helpers используют нормализованные данные MessageContext. В частности, chat-aware политики опираются на Chat и ChatID, которые теперь заполняются не только для message-backed обновлений.

Композиция

Политики задуманы как маленькие строительные блоки.

AllPolicies

AllPolicies(...) успешен только тогда, когда успешны все вложенные политики.

plugin.UsePolicy(
	"moderation",
	laniakea.AllPolicies(
		laniakea.RequireGroupChat(),
		laniakea.RequireChatAdmin(),
		laniakea.RequireBotAdmin(),
	),
)

Вычисление останавливается на первой возвращённой ошибке.

AnyPolicy

AnyPolicy(...) успешен, когда успешна хотя бы одна вложенная политика.

policy := laniakea.AnyPolicy(
	isGlobalOwner,
	laniakea.RequireChatCreator(),
)

Если ни одна политика не сработала:

внутренняя ошибка имеет приоритет над обычным deny;
иначе возвращается первая ошибка запрета.

Такой подход сохраняет fail-closed поведение и не скрывает сбои, важные для операторов.

NotPolicy

NotPolicy(...) инвертирует deny-результат.

policy := laniakea.NotPolicy(laniakea.RequirePrivateChat())

Если вложенная политика успешна, NotPolicy(...) возвращает deny-ошибку. Если вложенная политика вернула внутреннюю ошибку, она сохраняется как есть и не превращается в success.

Модель ошибок

Ошибки политик идут по тому же централизованному пути, что и ошибки обработчиков:

пользовательские ошибки могут превратиться в обычный ответ пользователю;
внутренние ошибки логируются, но не отправляют свой сырой текст в чат автоматически.

Это позволяет политикам безопасно работать в fail-closed режиме, не заставляя обработчики дублировать авторизационную логику.

Текущие ограничения

Политики выполняются через middleware бота и плагинов; у сцен пока нет собственного middleware layer.
Встроенные helpers — это Telegram-aware проверки авторизации, а не полноценная ролевая или capability system.
Во фреймворке пока нет отдельной principal model, DSL для RBAC или слоя кэширования прав.

Эти вещи можно добавить позже, если текущей модели Policy[T] окажется недостаточно, но текущий дизайн позволяет сделать авторизацию явной, не превращая Laniakea в тяжёлый auth framework.

Wiki

Policies

Что дают политики

Основной API

Регистрация

Встроенные политики

Композиция

AllPolicies

AnyPolicy

NotPolicy

Модель ошибок

Текущие ограничения

Navigation

Start here

Runtime and Architecture

Interaction and Telegram API

Practical Guides

Maintenance