subscriptionv1

type InternalSubscriptionServiceClient interface {
	// Subscribe — открыть поток изменений журнала владельца.
	//
	// # Решение о показе принимается НА КАЖДОЙ ОТДАВАЕМОЙ СТРОКЕ
	//
	// Единого объекта, о котором можно было бы задать ОДИН вопрос при открытии, у
	// этого метода не существует: поток несёт события разных предметов разных
	// проектов, и какие именно — заранее не известно. Поэтому метод объявлен
	// `scope_filtered`: край пообъектного вопроса не задаёт, а владелец сужает
	// поток по правам вызывающего на каждой строке, партиями, тем же сужателем,
	// что и списки.
	//
	// Следствие, названное прямо: у метода НЕТ полосы, на которую можно было бы
	// откатиться при неработающем сужателе. Сервер отказывает в открытии потока,
	// если сужатель отсутствует либо не сужает, а боевая стража отказывает в
	// старте процессу, объявившему `scope_filtered` без работающего фильтра.
	//
	// # Что этот метод НЕ делает
	//
	// Он не заменяет полл операции: событие пишется в той же транзакции, что и
	// ресурсная строка, поэтому при отказе операции события нет ВОВСЕ, и
	// наблюдатель ресурсов не отличит «ещё делается» от «упало».
	Subscribe(ctx context.Context, in *SubscriptionRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[SubscriptionMessage], error)
}

type InternalSubscriptionServiceServer interface {
	// Subscribe — открыть поток изменений журнала владельца.
	//
	// # Решение о показе принимается НА КАЖДОЙ ОТДАВАЕМОЙ СТРОКЕ
	//
	// Единого объекта, о котором можно было бы задать ОДИН вопрос при открытии, у
	// этого метода не существует: поток несёт события разных предметов разных
	// проектов, и какие именно — заранее не известно. Поэтому метод объявлен
	// `scope_filtered`: край пообъектного вопроса не задаёт, а владелец сужает
	// поток по правам вызывающего на каждой строке, партиями, тем же сужателем,
	// что и списки.
	//
	// Следствие, названное прямо: у метода НЕТ полосы, на которую можно было бы
	// откатиться при неработающем сужателе. Сервер отказывает в открытии потока,
	// если сужатель отсутствует либо не сужает, а боевая стража отказывает в
	// старте процессу, объявившему `scope_filtered` без работающего фильтра.
	//
	// # Что этот метод НЕ делает
	//
	// Он не заменяет полл операции: событие пишется в той же транзакции, что и
	// ресурсная строка, поэтому при отказе операции события нет ВОВСЕ, и
	// наблюдатель ресурсов не отличит «ещё делается» от «упало».
	Subscribe(*SubscriptionRequest, grpc.ServerStreamingServer[SubscriptionMessage]) error
	// contains filtered or unexported methods
}

type InternalSubscriptionService_SubscribeClient = grpc.ServerStreamingClient[SubscriptionMessage]

type InternalSubscriptionService_SubscribeServer = grpc.ServerStreamingServer[SubscriptionMessage]

type SubscriptionAnchor int32

type SubscriptionEvent struct {

	// position — позиция ЭТОГО события. Непрозрачна; клиент запоминает её и
	// возвращает дословно, чтобы возобновиться отсюда.
	Position string `protobuf:"bytes,1,opt,name=position,proto3" json:"position,omitempty"`
	// kind — вид предмета из закрытого словаря ВЛАДЕЛЬЦА, в том же написании, в
	// каком его принимает ось `SubscriptionRequest.kinds` и в каком его
	// перечисляет `SubscriptionOpened.known_kinds`.
	//
	// Написание одно на всё дерево — тип объекта модели прав; чем оно держится и
	// почему выбрано именно оно, сказано у поля `kinds`. Слово, которым владелец
	// записал строку в своём журнале, сюда не попадает: оно частное.
	Kind string `protobuf:"bytes,2,opt,name=kind,proto3" json:"kind,omitempty"`
	// resource_id — неизменяемый идентификатор предмета. По нему сужает ось
	// `SubscriptionRequest.ids`.
	//
	// Может быть пуст: не всякое событие относится к ресурсу (предметом бывает
	// субъект прав), и непустой идентификатор ресурса не является условием ни
	// открытия подписки, ни доставки события.
	ResourceId string `protobuf:"bytes,3,opt,name=resource_id,json=resourceId,proto3" json:"resource_id,omitempty"`
	// project_id — АВТОРИЗУЕМЫЙ ЯКОРЬ, и он стоит полем ОБОЛОЧКИ, а не внутри
	// нагрузки.
	//
	// Решение «кому это показать» принимается по нему БЕЗ обращения к предмету.
	// Для события удаления это несущее: обратиться не к чему — предмета больше
	// нет, а нагрузка у удаления беднее всего. Якорь внутри нагрузки означал бы
	// выбор из двух негодных: спрашивать модель прав про несуществующий объект
	// либо не показывать удаления вовсе. Второе наступает ТИХО, и цена его — та
	// самая, ради которой заводится подписка: потребитель, снявший поллинг,
	// никогда не узнает об удалении и будет держать удалённые строки вечно.
	//
	// Пусто означает «событие не принадлежит проекту» — предмет уровня аккаунта
	// или кластера. Это законное состояние, а не пропуск.
	ProjectId string `protobuf:"bytes,4,opt,name=project_id,json=projectId,proto3" json:"project_id,omitempty"`
	// change — род изменения. Словарь платформенный, в отличие от `kind`: действие
	// потребителя зависит именно от него, и различать снос от правки обязан уметь
	// всякий подписчик, не зная домена.
	Change SubscriptionEvent_Change `protobuf:"varint,5,opt,name=change,proto3,enum=kacho.cloud.subscription.SubscriptionEvent_Change" json:"change,omitempty"`
	// Носитель нагрузки — ВЫБОР ИЗ ДВУХ ВЕТВЕЙ: состояние ЛИБО признак, что
	// состояния нет.
	//
	// Ветвление здесь потому, что запретить прозой значение, которое допускает
	// собственный тип, невозможно. Пустая нагрузка НИКОГДА не означает «у предмета
	// не осталось полей»: подставить пустой объект вместо признака недоступности
	// в этой форме просто негде.
	//
	// Подписчик, получивший непустую нагрузку, вправе читать её как ПОЛНОЕ
	// состояние предмета — и это единственный случай, когда он вправе так делать.
	//
	// Types that are valid to be assigned to Carrier:
	//
	//	*SubscriptionEvent_State
	//	*SubscriptionEvent_StateUnavailable_
	Carrier isSubscriptionEvent_Carrier `protobuf_oneof:"carrier"`
	// contains filtered or unexported fields
}

type SubscriptionEvent_Change int32

type SubscriptionEvent_State struct {
	// state — состояние предмета. Тип НАЗВАН: `Any` несёт имя типа на проводе,
	// и ключи нагрузки суть поля этого типа, объявленные контрактом владельца.
	//
	// Свободной структуры здесь нет намеренно. У неё ключи на проводе
	// производятся от имён идентификаторов Go, `buf breaking` этого не видит
	// by construction (в контракте написано «объект»), и обычный внутренний
	// рефактор молча ломает публичную нагрузку.
	State *anypb.Any `protobuf:"bytes,10,opt,name=state,proto3,oneof"`
}

type SubscriptionEvent_StateUnavailable struct {
	Reason SubscriptionEvent_StateUnavailable_Reason `` /* 138-byte string literal not displayed */
	// contains filtered or unexported fields
}

type SubscriptionEvent_StateUnavailable_ struct {
	// state_unavailable — состояния по этому событию не будет, и сказано почему.
	StateUnavailable *SubscriptionEvent_StateUnavailable `protobuf:"bytes,11,opt,name=state_unavailable,json=stateUnavailable,proto3,oneof"`
}

type SubscriptionEvent_StateUnavailable_Reason int32

type SubscriptionMessage struct {

	// Types that are valid to be assigned to Message:
	//
	//	*SubscriptionMessage_Opened
	//	*SubscriptionMessage_Event
	Message isSubscriptionMessage_Message `protobuf_oneof:"message"`
	// contains filtered or unexported fields
}

type SubscriptionMessage_Event struct {
	// event — событие. Приходит только после `opened`.
	Event *SubscriptionEvent `protobuf:"bytes,2,opt,name=event,proto3,oneof"`
}

type SubscriptionMessage_Opened struct {
	// opened — служебное сообщение открытия. Приходит первым и ровно один раз за
	// поток.
	Opened *SubscriptionOpened `protobuf:"bytes,1,opt,name=opened,proto3,oneof"`
}

type SubscriptionOpened struct {

	// position — позиция, с которой сервер начал отдавать. Непрозрачна ровно так
	// же, как `SubscriptionRequest.position`, и возвращается в неё дословно.
	Position string `protobuf:"bytes,1,opt,name=position,proto3" json:"position,omitempty"`
	// caught_up — исчерпан ли журнал на момент открытия.
	//
	// Этим «событий не было» отличается от «я подключился позже», и отличается ПО
	// СЛОВУ СЕРВЕРА, а не арифметикой клиента: над непрозрачным токеном сравнение
	// двух позиций невыразимо by construction, и непрозрачность именно этот ход и
	// запрещает.
	//
	// `true` + молчание = изменений не было. `false` + молчание = я ещё догоняю.
	CaughtUp bool `protobuf:"varint,2,opt,name=caught_up,json=caughtUp,proto3" json:"caught_up,omitempty"`
	// honored_filters — оси, которые этот владелец отобрал ЧЕСТНО.
	//
	// Значения — ИМЕНА ПОЛЕЙ `SubscriptionRequest`, как они объявлены в этом
	// контракте: `kinds`, `project_id`, `ids`. Имя поля контракта и есть провод,
	// поэтому свой второй словарь осей здесь не заводится — он разошёлся бы с
	// полями молча.
	//
	// Зачем перечень. Журналы владельцев устроены по-разному, и ось, выразимая
	// контрактом, не у каждого отбираема. Исходов у такой оси три: молча
	// проигнорировать — ЗАПРЕЩЕНО (вызывающий получит успех и решит, что его
	// параметр применён); отвергнуть — лишает подписки половину владельцев;
	// НАЗВАТЬ — то, что выбрано здесь. Цена названа: по неотобранной оси клиент
	// доотбирает сам.
	//
	// Исключение — ЯКОРНАЯ ось: её в этом перечне не бывает отсутствующей при
	// заданном значении, потому что владелец, не умеющий по ней отобрать,
	// подписку отвергает. Решение о показе не перекладывается на клиента.
	//
	// Владелец, отобравший все заданные оси, перечисляет их все, и перечень
	// совпадает с заданными вызывающим.
	HonoredFilters []string `protobuf:"bytes,3,rep,name=honored_filters,json=honoredFilters,proto3" json:"honored_filters,omitempty"`
	// earliest_resumable_position — самая ранняя позиция, с которой возобновление
	// ещё возможно.
	//
	// Владелец, переставший удерживать часть журнала, обязан уметь сказать
	// «твоя позиция больше не возобновима» ЯВНО и назвать место, с которого
	// подписка возможна, — а не начать молча с ближайшего удержанного. Молчаливое
	// начало клиент запишет как «изменений не было», и дописать этот исход потом
	// будет ломающим изменением.
	//
	// Отказ на невозобновимой позиции называет ЭТУ ЖЕ величину, поэтому она
	// объявлена одним полем, а не двумя похожими в двух местах.
	EarliestResumablePosition string `` /* 138-byte string literal not displayed */
	// retains_everything — владелец удерживает журнал целиком.
	//
	// Тогда отказ «позиция утрачена» не наступает никогда, и это СВОЙСТВО
	// ВЛАДЕЛЬЦА, объявленное им, а не умолчание формы: при `true` поле
	// `earliest_resumable_position` не несёт горизонта, потому что горизонта нет.
	RetainsEverything bool `protobuf:"varint,5,opt,name=retains_everything,json=retainsEverything,proto3" json:"retains_everything,omitempty"`
	// known_kinds — ЗАКРЫТЫЙ СЛОВАРЬ ВИДОВ этого владельца, целиком.
	//
	// Это ответ на вопрос «что вообще можно назвать в `SubscriptionRequest.kinds`».
	// До него ответа не было НИ ОДНОГО: словарь принадлежит владельцу, объявлен
	// закрытым, а прочесть его было неоткуда — оставался перебор против отказа на
	// живой ручке. Перебор не воспроизводится при добавлении домена: новый
	// владелец заводит свои виды, и узнать о них снова стало бы неоткуда.
	//
	// # ПОЧЕМУ ЗДЕСЬ, А НЕ ПЕРЕЧИСЛЕНИЕМ В КОНТРАКТЕ И НЕ ОТДЕЛЬНЫМ ГЛАГОЛОМ
	//
	// Перечислением НЕЛЬЗЯ: словарь принадлежит владельцу, а эта форма — общая.
	// Перечисление в ней означало бы, что виды всех владельцев объявлены здесь, и
	// тогда владелец, чьи события не про ресурс, а про субъект прав, в форму не
	// поместился бы вовсе — ровно то, что оговорено у поля `kinds`. Плюс каждый
	// новый вид становился бы правкой ОБЩЕГО контракта, то есть словарь пополнялся
	// бы правкой документа, а не по построению.
	//
	// Отдельным глаголом МОЖНО, и цена измерена, а не предположена: глагол — это
	// вторая запись каталога прав (обе встроенные копии обязаны остаться
	// байт-идентичными), регистрация у КАЖДОГО владельца, второй путь на крае и
	// второе место, где словарь может разойтись с тем, чем сервер на самом деле
	// судит. Здесь же он не может разойтись by construction: сервер отдаёт ровно
	// тот перечень, которым отвергает неизвестный вид.
	//
	// Служебное сообщение приходит ПЕРВЫМ и ВСЕГДА и уже везётся по проводу — то
	// есть поверхность не расширяется вовсе, а до браузера словарь доезжает через
	// существующую проекцию края без единой её правки.
	//
	// # КАК ЕГО ПРОЧИТАТЬ, НЕ ЗНАЯ НИ ОДНОГО ВИДА
	//
	// Открыть подписку, НЕ называя `kinds`: незаданная ось не сужает, отказа не
	// будет, а первое же сообщение принесёт словарь целиком. Названный неизвестный
	// вид отвергается ДО открытия — поэтому узнать словарь отказом нельзя, и
	// отказ по этой причине называет его сам.
	//
	// # ПОРЯДОК ЗНАЧИМ: перечень отсортирован
	//
	// Он приходит в возрастающем лексикографическом порядке, и это ЧАСТЬ
	// КОНТРАКТА, а не «как получилось»: словарь живёт отображением, обход
	// отображения в Go случаен by construction, и клиент, ведущий своё состояние
	// по индексу, читал бы каждое открытие как смену словаря.
	//
	// # ЧТО ЭТО НЕ ЗНАЧИТ
	//
	// Не значит «по каждому из них тебе придут события»: словарь есть объявление
	// ВЛАДЕЛЬЦА, а не выборка по правам вызывающего. Показ решается построчно, и
	// вид, на который у вызывающего нет прав, остаётся в словаре — иначе перечень
	// стал бы способом узнать, что кому доступно.
	//
	// Пустым не бывает: владелец с пустым словарём не поднимается вовсе — поток,
	// из которого не доставляется ничего, объявлением подписки не является.
	KnownKinds []string `protobuf:"bytes,6,rep,name=known_kinds,json=knownKinds,proto3" json:"known_kinds,omitempty"`
	// contains filtered or unexported fields
}

type SubscriptionRequest struct {

	// kinds — виды предметов, о которых слать события. Категория: УДОБСТВА.
	//
	// Словарь видов принадлежит ВЛАДЕЛЬЦУ и им закрыт; фиксированного перечня
	// «ресурсы такого-то домена» здесь нет — иначе владелец, чьи события не про
	// ресурс, а про субъект прав, в эту форму не поместился бы вовсе.
	//
	// ГДЕ ЕГО ПРОЧИТАТЬ: `SubscriptionOpened.known_kinds` — служебное сообщение
	// открытия несёт словарь целиком и приходит первым. Подписка, не назвавшая ни
	// одного вида, законна и отказа не даёт, поэтому словарь читается ОДНИМ
	// открытием, а не перебором против отказа.
	//
	// # НАПИСАНИЕ ВИДА ОДНО НА ВСЁ ДЕРЕВО: это ТИП ОБЪЕКТА МОДЕЛИ ПРАВ
	//
	// Вид называется тем же словом, каким этот предмет зовёт модель прав
	// (`compute_instance`, `nlb_network_load_balancer`) — тем самым, что стоит в
	// `scope_extractor.object_type` контрактов домена. Слово НЕ придумывается
	// подпиской и не берётся из хранилища владельца: как строка журнала записана,
	// есть частное дело владельца, и наружу это не выходит.
	//
	// Причина ровно одна и она про клиента: словарь, у которого нет единственного
	// производителя, пишется столькими способами, сколько у него авторов, и
	// клиент, взявший написание у одного, не может знать, то ли оно. Здесь
	// производитель один — тот же, которым сервер решает вопрос о видимости
	// строки, — поэтому второго написания не существует by construction, а не по
	// договорённости.
	//
	// Форма слова: строчные латинские буквы, цифры и подчёркивание, первый знак —
	// буква. Владелец, объявивший вид иначе, НЕ ПОДНИМАЕТСЯ.
	//
	// Вид вне словаря владельца — `INVALID_ARGUMENT` с именем поля, названным
	// значением И перечнем известных видов, а НЕ открытый поток, в который никогда
	// ничего не придёт. Пустой поток есть утверждение «событий нет», которого
	// сервер не вправе делать про вход, которого он не понял; отказ, не называющий
	// годных значений, оставляет вызывающего ровно там, откуда он пришёл.
	Kinds []string `protobuf:"bytes,1,rep,name=kinds,proto3" json:"kinds,omitempty"`
	// project_id — проект, к которому относятся события. Категория: ЯКОРНАЯ.
	//
	// По ней принимается решение о показе, поэтому владелец, не умеющий отобрать
	// по ней, ОТВЕРГАЕТ подписку, а не открывает её с оговоркой: «доотбор на
	// клиенте» означало бы, что границу доступа держит клиент.
	//
	// Незаданная ось проектом не сужает. Событие, не принадлежащее проекту вовсе
	// (предмет уровня аккаунта или кластера), выразимо — см.
	// `SubscriptionEvent.project_id`.
	ProjectId string `protobuf:"bytes,2,opt,name=project_id,json=projectId,proto3" json:"project_id,omitempty"`
	// ids — неизменяемые идентификаторы предметов. Категория: УДОБСТВА.
	//
	// Это единственная ось, принимающая произвольную строку, и потому единственный
	// путь протащить мутабельную адресацию через иммутабельную. Имя ресурса,
	// поданное сюда, обязано быть отвергнуто `INVALID_ARGUMENT` — иначе подписка
	// откроется и замолчит навсегда, потому что имени не отвечает ни один
	// идентификатор.
	//
	// Идентификатор правильной формы, которому не отвечает ни один предмет, —
	// НЕ отказ: подписка открывается и просто не приносит по нему событий.
	// «Негодная форма» и «такого нет» — разные полосы, и подписка их не смешивает.
	Ids []string `protobuf:"bytes,3,rep,name=ids,proto3" json:"ids,omitempty"`
	// start — с какого места отдавать. Состояний ТРИ, и они различимы:
	// «с начала журнала», «с этой позиции», «с текущего конца».
	//
	// ИСХОД НЕЗАДАННОГО НАЗВАН, а не подразумевается: `start` не задан означает
	// ровно `CURRENT_END` — подписка на то, что произойдёт дальше. Выбор
	// осознанный: молчаливая полная выдача журнала («с начала») превращает
	// подписку в выгрузку и тем дороже, чем дольше журнал не чистили, а узнать об
	// этом вызывающий может только по счёту за неё.
	//
	// Types that are valid to be assigned to Start:
	//
	//	*SubscriptionRequest_Anchor
	//	*SubscriptionRequest_Position
	Start isSubscriptionRequest_Start `protobuf_oneof:"start"`
	// contains filtered or unexported fields
}

type SubscriptionRequest_Anchor struct {
	// anchor — назвать место словом.
	Anchor SubscriptionAnchor `protobuf:"varint,10,opt,name=anchor,proto3,enum=kacho.cloud.subscription.SubscriptionAnchor,oneof"`
}

type SubscriptionRequest_Position struct {
	// position — НЕПРОЗРАЧНЫЙ ТОКЕН, выданный сервером, и ничего больше.
	//
	// Клиент хранит его и возвращает ДОСЛОВНО: не разбирает, не сравнивает два
	// токена между собой и не конструирует свой. Позиция, сконструированная или
	// изменённая клиентом, отвергается `INVALID_ARGUMENT` — а не принимается
	// «как похожая».
	//
	// ОБЯЗАТЕЛЬСТВО, РАДИ КОТОРОГО ПОЗИЦИЯ НЕПРОЗРАЧНА:
	//
	//	позиция, выданная сервером, обязана быть такой, что возобновление с неё
	//	не пропускает ни одной строки, закоммиченной ПОСЛЕ её выдачи.
	//
	// Оно записано здесь дословно, потому что непрозрачность его НЕ ОБЕСПЕЧИВАЕТ.
	// Непрозрачность покупает право починить внутреннюю форму позже, не ломая
	// контракт; она не чинит. Токен, кодирующий границу по МАКСИМУМУ ВИДИМОГО
	// номера, непрозрачен и всё равно теряет строку: номер присваивается на
	// вставке, видимость наступает на фиксации, поэтому писатель, закоммитивший
	// позже с меньшим номером, оказывается за границей — навсегда, молча и без
	// пропуска в нумерации, видимого клиенту. Скалярная граница законна;
	// граница по максимуму видимого — нет.
	//
	// Кодек позиции живёт там же, где объявлены прочие формы курсора этого
	// дерева, — в пакете `corelib/pagetoken`, и объявляется СВОИМ типом. Уже
	// объявленный там `Cursor` для неё НЕ ГОДИТСЯ: его семантика — «последняя
	// ОТДАННАЯ строка», а это дословно та граница, которую обязательство выше и
	// запрещает.
	//
	// Позиция принадлежит КЛИЕНТУ, а не подписке: сервер её не помнит и остаётся
	// stateless. Иначе возобновление привязывается к реплике, на которой
	// подписка была открыта, и переподключение к другой перестаёт работать.
	Position string `protobuf:"bytes,11,opt,name=position,proto3,oneof"`
}

type UnimplementedInternalSubscriptionServiceServer struct{}

type UnsafeInternalSubscriptionServiceServer interface {
	// contains filtered or unexported methods
}