subscription

Overview ¶

Package subscription — ОБЩИЙ сервер потока изменений ресурсов. Один на платформу, по экземпляру на владельца журнала.

Зачем пакет существует ¶

Сервер потока был написан ДВАЖДЫ и предметно, в двух разных сервисах: у одного 380 строк с выделенным соединением, курсором и пределом потоков, у другого свой обработчик того же предмета. Потребителя не оказалось ни у одного, а провязать подписку в остальных модулях копированием значило бы завести седьмую копию одного механизма.

Решение владельца: формат подписки один на всех как стандарт, определённый в фундаменте как переиспользуемый механизм; остальное снимается и переводится на него. Этот пакет — тот механизм.

Что приносит владелец, подключаясь ¶

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

КОНТРАКТ МЕХАНИЗМА ¶

Он записан здесь дословно, потому что подписчик ведёт по нему СВОЁ состояние, и каждое из четырёх утверждений ниже — обязательство, а не подробность.

## Доставка: КАЖДОЕ устоявшееся событие ровно один раз на поток

Событие, попавшее в журнал и ставшее устоявшимся, будет отдано подписчику, чьим осям оно отвечает и на чей взгляд у вызывающего есть право. В пределах ОДНОГО потока повтора не бывает: курсор двигается только вперёд.

Между потоками — «хотя бы раз»: клиент, возобновившийся с позиции `P`, получает всё, что после `P`, и не получает того, что `P` покрывает. Если он сохранил позицию, но не успел обработать событие, повтор произойдёт — и это нормальный исход, к которому подписчик обязан быть готов.

**Событие, НЕ попавшее в журнал, не существует для подписки.** Журнальная строка пишется в той же транзакции, что и ресурсная, поэтому при отказе мутации события нет ВОВСЕ: наблюдатель ресурсов не отличит «ещё делается» от «упало». Полл операции подписка не заменяет.

## Порядок: НЕУБЫВАЮЩИЙ по позиции, в пределах одного журнала

События одного журнала приходят в порядке неубывания позиции; событие, пришедшее позже, никогда не относится к состоянию, предшествующему уже полученному. Это верно и для одного предмета, и для журнала целиком.

**Порядок между журналами разных владельцев НЕ определён** и определён быть не может: у них независимые счётчики и независимые транзакции.

Порядок держится не сортировкой, а ГРАНИЦЕЙ УСТОЯВШЕГОСЯ (см. `watermark.go`): номер выдаётся на вставке, а видимость наступает на фиксации, поэтому строка отдаётся только когда все меньшие номера уже определены — видимы либо потеряны откатом. Без этого писатель, закоммитивший позже с меньшим номером, терялся бы навсегда: молча, без отказа и без пропуска в нумерации, видимого клиенту.

## Разрыв: поток обрывается, ПОЗИЦИЯ переживает

Позиция принадлежит КЛИЕНТУ; сервер её не помнит и остаётся stateless. Поэтому возобновление работает и после перезапуска сервера, и к ДРУГОЙ реплике.

Обрыв — штатное событие, а не отказ. Сервер закрывает поток чисто по истечении срока жизни (Config.StreamBudget), и клиент возобновляется со своей позиции. Отдельно и явно назван исход, при котором возобновиться нельзя: владелец, переставший удерживать часть журнала, отвечает `OUT_OF_RANGE` и называет позицию, с которой подписка ещё возможна, — а НЕ начинает молча с ближайшего удержанного места. Молчаливое начало клиент записал бы как «изменений не было».

Недоступность источника — тоже НЕ «событий нет»: она отвечает `UNAVAILABLE`. Пустой поток есть утверждение о мире, и делать его при неотвеченном чтении сервер не вправе.

## Медленный потребитель: держит СВОЙ поток, не чужие

Отправка идёт синхронно в поток вызывающего: не читающий клиент упирается в окно транспорта, и курсор ЕГО потока перестаёт двигаться. Он не задерживает ни других подписчиков (у каждого свой курсор и своё соединение), ни писателей журнала (сервер только читает).

Плата названа: медленный потребитель занимает слот и выделенное соединение всё время своей жизни. Поэтому число одновременных потоков ограничено (Config.MaxStreams), и превышение отвечает `RESOURCE_EXHAUSTED` — ОТКАЗОМ, а не молчаливой очередью: очередь превратила бы исчерпание в неограниченное ожидание, неотличимое для клиента от «событий нет». Сверху стоит срок жизни потока: слот освобождается даже у клиента, который не читает и не уходит.

**Буфера на подписчика здесь нет намеренно.** Он превратил бы отставание в потерю (переполнился — что-то выбросили) либо в неограниченную память. Вместо этого отставание становится задержкой, и она видна: курсор не двигается, позиция в служебном сообщении при следующем открытии это покажет.

Чего этот пакет НЕ делает ¶

• НЕ фильтрует по меткам: они мутабельны, ресурс входит в выборку и выходит из неё, и без предыдущего состояния выход неотличим от удаления. Метки отбирает КЛИЕНТ — и ровно там, где владелец состояние ПРОИЗВОДИТ (kacho#1025 заводит серверный отбор, когда объём событий будет измерен).

  **Оговорка несущая, и без неё эта строка лгала.** Прежняя редакция обосновывала клиентский отбор тем, что «событие несёт полное состояние», — утверждением обо ВСЕЙ форме, тогда как состояние производит владелец, а не она. Контракт (`SubscriptionRequest`) оговорку нёс, эта строка — нет: два места об одном предмете, из которых верно одно, и неверным было то, которое читает владелец, подключая новый журнал.

  Кто из владельцев состояние производит — НЕ выписывается ни здесь, ни в клиентской странице по памяти: число владельцев растёт, а выписанное устаревает молча. Согласие двух мест держит гейт `internal/repohygiene` `TestSubscriptionOwnerPageSaysWhatItsJournalDoes`: он обходит объявления журналов, судит УЗЕЛ (доходит ли функция состояния до `anypb.New`) и требует, чтобы таблица владельцев обещала то же. Судить подстрокой он не вправе: имя упаковщика стоит и в объяснениях тех, кто состояния не производит. Перепись он печатает по обеим сторонам.

  Спрашивать об этом документ вообще не нужно: событие без состояния несёт причину `NOT_PRODUCED`, машинно отличимую от сбоя сборки, и она верна на день запроса, а не на день правки страницы. Клиент, которому метки нужны у такого владельца, читает предмет по `resource_id`;

• НЕ фильтрует по имени: имя мутабельно, и подписка по нему МОЛЧА перестаёт совпадать после переименования. Адресный отбор делает ось `ids`;

• НЕ подписывает на операции: полл операции дёшев, а поток операций тиражировал бы подписчикам идентификатор, присвоенный до выполнения;

• НЕ чистит журнал: удержание — свойство владельца, и он его объявляет;

• НЕ принимает ЖУРНАЛ СМЕНЫ СУБЪЕКТА (`kaname.subject_change_outbox`), и это решение, а не объём работы. Он читается унарным глаголом (`InternalIAMService.PollSubjectChanges`, потребитель — `pkg/subjectchange` на крае), и попытка подключить его сюда была бы не обобщением, а подменой предмета.

  Предметы РАЗНЫЕ, и различие видно по вопросу, на который отвечает событие: этот поток отвечает арендатору «что стало с твоими ресурсами», тот — слою авторизации «твои решения устарели». Отсюда противоположная модель доступа: здесь построчное сужение по правам есть ЗАЩИТА (глагол объявлен `scope_filtered`), там оно fail-open — пропущенная строка означает, что кэш вердиктов не погас, то есть край продолжает отвечать по отозванному праву. Сужение сняло бы ровно тот эффект, ради которого журнал заведён.

  И оно замкнуло бы круг: чтобы отдать строку, владелец спросил бы модель прав, а предмет строки — обесценить кэшированные ответы на такие вопросы. Под fail-closed это даёт «модель недоступна ⇒ край не узнаёт об отзывах», то есть хуже прямого чтения, а не лучше.

  Два расхождения помельче названы здесь же, чтобы их не приняли за единственные: сужатель этой формы типизирован конкретным `*listnarrow.Narrower`, а у владельца прав своя реализация по решению (видимость строки определяется НАБОРОМ отношений, а не одним действием); и у того журнала нет колонки вида предмета, которой Storage требует, — тип субъекта лежит в нагрузке, а `resource_type` там необязательная подсказка, которую читатель не берёт.

  Разбор целиком, включая два отвергнутых исхода и их цену, — `docs/architecture/subject-change-journal-is-not-a-resource-stream.md`; здесь он не пересказывается, чтобы два места об одном предмете снова не разошлись (kacho#1397).

КТО ВЛАДЕЛЕЦ, А КТО НЕТ — и почему двух доменов здесь не будет ¶

Глагол служат пять доменов из семи, и разница — РЕШЕНИЕ, а не остаток работы. Записано здесь, потому что снаружи «решено не заводить» и «ещё не сделано» неразличимы by construction: и то и другое выглядит как отсутствие провязки.

Считать домены по имени таблицы нельзя, и это измерено, а не предположено. Предикат «сервис, у которого есть таблица с именем на `_outbox`» неверен В ОБЕ СТОРОНЫ: он засчитывает очереди прав, аудита, реконсиляции и компенсации (у iam таких четыре, ни одна лентой изменений не является) и НЕ засчитывает настоящий журнал registry — `registry_resource_journal`, названный не так. Единица счёта здесь одна и принадлежит самому механизму: журнал служится тогда, когда его виды суть ТИПЫ МОДЕЛИ ПРАВ, — этого требует [Mapping.validate], и требует ровно потому, что иначе вопрос о видимости строки задать нечем.

По этой единице дерево считается так: лент изменений ресурсов ШЕСТЬ (compute, geo, nlb, registry, storage, vpc), доменов с собственными типами модели прав тоже шесть (те же минус geo, плюс iam), а пересечение — ПЯТЬ, и все пять глагол служат. Пять из пяти, а не пять из семи.

## geo — сужать нечем

`geo_outbox` по форме лента изменений и есть: номер, вид, идентификатор, род, состояние. Но виды у неё `Region` и `Zone`, а типов `geo_*` в модели прав НОЛЬ — каталог размещения намеренно вынесен из пообъектной авторизации: его обязан читать всякий аутентифицированный арендатор, и вопрос «вправе ли этот вызывающий видеть эту зону» имеет один ответ для всех.

Отсюда следует не «трудно», а «невозможно назвать законный словарь»: [Mapping.validate] отвергает пустой словарь видов и вид без типа объекта, то есть владелец geo не поднялся бы. Провязать его можно было бы, лишь заведя `geo_region`/`geo_zone` ради того, чтобы сужатель отвечал «да» всем, — проверка, форма которой есть, а содержания нет.

## iam — предмета нет

У iam ленты изменений ресурсов НЕТ ни одной. Четыре его очереди — кортежей прав, реконсиляции зеркала, смены субъекта и аудита — суть внутренняя механика: они отвечают не арендатору «что стало с твоими ресурсами», а слою авторизации «твои решения устарели».

Предметы разные, и разница не в объёме работы: у ресурсного потока построчное сужение — ЗАЩИТА, а для потребителя журнала субъектов оно fail-open (строка, не отданная из-за прав, означает непогашенный кэш вердикта, то есть край продолжает отвечать по отозванному). Разобрано в kacho#1397, и развилка «чем читать журнал субъектов» РЕШЕНА 2026-08-29 в пользу чтения курсором через унарный `InternalIAMService.PollSubjectChanges`. Здесь решение не принимается и не пересказывается: оно объявлено единственным местом — `docs/architecture/subject-change-journal-is-not-a-resource-stream.md`.

## Как эти два решения истекают

Не памятью. Гейт дерева (`internal/repohygiene`, `TestEveryDomainEitherServesSubscriptionOrRecordsWhyNot`) требует от каждого домена одного из двух — служить глагол либо нести запись решения, — и роняет прогон, когда запись пережила предмет: домен стал владельцем, домен исчез, либо у geo появился свой тип в модели прав.

grant.go — ОКНО МАТЕРИАЛИЗАЦИИ ГРАНТА: почему «нет» от модели прав не всегда окончательно, и чем ограничено ожидание.

ПРЕДМЕТ ¶

Строка журнала и строка ресурса коммитятся ОДНОЙ транзакцией — это несущее свойство формы подписки. Кортеж владения кладётся ПОСЛЕ фиксации: сначала синхронным докладом владельцу прав, а если тот не дошёл — дренажем намерения из той же writer-транзакции. Пробуждение потока приходит НА ФИКСАЦИИ, то есть в самый ранний возможный миг: строка уже видна, гранта ещё нет.

Пообъектный вопрос в этот миг получает «нет» ЗАКОННО. До задачи #2264 такой ответ был ОКОНЧАТЕЛЬНЫМ: курсор идёт по ПРОЧИТАННОЙ строке (см. [Server.drain], и это верно — иначе невидимая партия перечитывалась бы вечно), поэтому строка уезжала под курсор, и открытый поток не отдавал её больше НИКОГДА.

Наблюдаемое следствие — то, ради чего подписка заведена, и оно ТИХОЕ: у клиента нет ни пропуска в нумерации, ни отказа, поэтому «изменений не было» и «изменение было и не доехало» для него неразличимы. Возобновление с той же позиции предмет ПРИНОСИЛО (грант к тому времени уже лежал) — то есть строка была и в журнале, и видна вызывающему, а открытый поток её пропустил.

РЕШЕНИЕ: ОТСРОЧИТЬ СУЖДЕНИЕ, А НЕ РАСШИРИТЬ ЕГО ¶

Рассмотрен и отвергнут симметричный ход: судить создание ПО ЯКОРЮ, как уже судится снятие (см. `removalsAllowedByAnchor`). Довод там — «предмета уже нет в модели прав»; здесь он звучал бы «предмета ещё нет», и симметрия соблазнительна. Отвергнут по цене: у снятия расширение касается ОДНОГО рода изменения и предмета, которого больше нет, а у создания оно означало бы, что всякий, кому разрешён проект, видит КАЖДОЕ создание в нём — постоянно, а не в окне. Это расширение поверхности доступа, и принимать его молча нельзя.

Отсрочка расширением не является BY CONSTRUCTION: наружу не уходит ни одна строка, которой модель не сказала «да». Платится ЛАТЕНТНОСТЬЮ, и она названа ниже числом.

ЧЕГО ОТСРОЧКА НЕ ОБЕЩАЕТ ¶

Она покрывает ДВУХ производителей гранта, разбуженных той же фиксацией: синхронный доклад и дренаж намерения. Реконсайлер — третий производитель, и его шаг измеряется десятками секунд; держать поток столько значило бы платить этой задержкой за КАЖДУЮ строку, которую вызывающему не разрешат никогда. Поэтому окно его не покрывает, а остаток называется ПЕРЕПИСЬЮ (см. [delivery.census]): строка, снятая по истечении окна, попадает в счётчик, и расхождение «прочитано против отдано» перестаёт быть немым.

retention.go — УБОРКА ЖУРНАЛА ПОДПИСКИ: предикат и его пороги.

Предмет — задача продукта #1666. Журнал подписки заведён у пяти владельцев (`polyrepo.md` §runtime-edges), строка в него пишется НА КАЖДОЙ мутации ресурса, а снятия строк не было ни на одном пути ни у одного из них: рост монотонный и вечный, темп задаёт арендатор.

Петля, партии, потолок проходов и наблюдаемость живут в `pkg/retention` и здесь не повторяются. Здесь — только ПРЕДИКАТ и его пороги, потому что предикат есть свойство ЭТОЙ семьи таблиц: у журнала подписки нет признака доставки, его читают КУРСОРОМ ПО ПОЗИЦИИ, и порог выводится из того, что обещано подписчику, а не из того, что кем-то применено.

ПОЧЕМУ ПРЕДИКАТ ЗДЕСЬ, А НЕ У КАЖДОГО ВЛАДЕЛЬЦА ¶

`pkg/retention` разводит петлю и предикат ровно потому, что предикат — свойство СХЕМЫ: у операций признак `done`, у очереди дренажа `sent_at`. У пяти журналов подписки схема одна и та же по существу — возрастающая позиция плюс отметка времени, — и объявлена она уже: `Storage.PositionColumn` и `Storage.AgeColumn`. Пять копий одного оператора разошлись бы молча и дали бы РАЗНЫЙ срок жизни события у разных доменов при ОДНОМ контракте подписки.

ЦЕНА РЕШЕНИЯ, НАЗВАННАЯ ВСЛУХ ¶

Имя таблицы приезжает сюда значением (`Storage.Table`), поэтому текста имени в исходнике НЕТ, и гейт роста (`internal/repohygiene` TestLiveTablesNameTheirGrowthLimit) этот оператор снятия у себя не резолвит — он уходит в НАЗВАННУЮ САМИМ ГЕЙТОМ слепую зону `RemovalsUnresolved`. Следствие обязано быть записано, а не умолчано: у журнала подписки остаётся запись реестра роста, и её вердикт — «предел» с причиной, называющей этот уборщик.

Обратный размен рассматривался и отвергнут: чтобы гейт видел имя, оператор пришлось бы написать ПЯТЬ раз, по разу у каждого владельца, различая их одним токеном — именем таблицы. Это тот самый разъезд, ради устранения которого заведён `pkg/retention`. Взамен машинную сторону закрывает ДРУГОЙ гейт — `TestSubscriptionJournalLanesAgreeOnRetention`: он сверяет полосы попарно и требует, чтобы объявленное удержание и провязанный уборщик были ОДНИМ решением.