shared

func DoWithWriteTx ¶

func DoWithWriteTx[T any](
	ctx context.Context,
	repo kanamerepo.Repository,
	action func(ctx context.Context, w kanamerepo.Writer) (T, error),
) (T, error)

DoWithWriteTx оборачивает стандартный writer-tx паттерн вокруг одной мутации: Begin → action → Commit (если action вернул nil) или Rollback (если action вернул err / panic — defer-Rollback срабатывает на любом not-committed возврате).

Использование (account/create.go::doCreate):

created, err := shared.DoWithWriteTx(ctx, u.repo,
    func(ctx context.Context, w kanamerepo.Writer) (domain.Account, error) {
        return w.AccountsW().Insert(ctx, a)
    })
if err != nil { return nil, err }
// post-commit hooks here
return marshalAccount(created)

Generic T — domain-тип, возвращаемый action'ом. Go infer'ит его из closure.

Все ошибки из репо (action error + Writer/Commit) маппятся через MapRepoErr — caller получает уже gRPC-status.

func DoWithWriteTxVoid ¶

func DoWithWriteTxVoid(
	ctx context.Context,
	repo kanamerepo.Repository,
	action func(ctx context.Context, w kanamerepo.Writer) error,
) error

DoWithWriteTxVoid — вариант для action'ов без возвращаемого domain-объекта (например, doDelete). Возвращает только error.

Использование (account/delete.go::doDelete):

if err := shared.DoWithWriteTxVoid(ctx, u.repo,
    func(ctx context.Context, w kanamerepo.Writer) error {
        return w.AccountsW().Delete(ctx, id)
    }); err != nil {
    return nil, err
}
return anypb.New(&emptypb.Empty{})

func EffectiveListPageSize ¶

func EffectiveListPageSize(pageSize int32) int

EffectiveListPageSize resolves a requested page size to the number of visible rows a page holds. It mirrors the repository's own resolution (0 means the default) and is needed in the use-case because THAT is where the page is now filled — the repository no longer knows how large the answer is.

The value is assumed already validated by ValidateVisiblePagination; out of range it clamps to the default rather than inventing a limit, and the guard above is what makes that branch unreachable on the served path.

func EncodeVisiblePageToken ¶

func EncodeVisiblePageToken(c VisibleCursor) string

EncodeVisiblePageToken renders the cursor. Nanosecond precision is kept because the keyset compares the stored timestamp, not the truncated one the resource message carries.

func GoPostCommit ¶

func GoPostCommit(callerCtx context.Context, logger *slog.Logger, what string, fn func(context.Context))

GoPostCommit runs fn asynchronously, detached from callerCtx's cancellation and deadline but carrying its values, under PostCommitTimeout. `what` names the pass in the panic log. A nil fn is a no-op.

The caller MUST NOT rely on fn having completed when GoPostCommit returns — that is the entire point. Use it only for work whose durable record is already committed.

func InvalidArg ¶

func InvalidArg(field, desc string) error

InvalidArg — InvalidArgument-error с одним BadRequest_FieldViolation. Если WithDetails не смог приклеить детали (proto-marshal-fail), возвращает голый status без них (best-effort — клиент получит code+message, отсутствие details не критично).

func IsMembershipCarriesRights ¶

func IsMembershipCarriesRights(err error) bool

IsMembershipCarriesRights — отказ ли это полосы «членство несёт права».

Спрашивается ПОСЛЕ `MapRepoErr`, поэтому смотрит на машинный признак, а не на цепочку sentinel'ов: `MapRepoErr` пересобирает статус и цепочку не сохраняет. Это же делает распознавание НЕЗАВИСИМЫМ ОТ ЯЗЫКА прозы — ровно то свойство, ради которого признак и заводится.

func LabelsEqual ¶

func LabelsEqual(a, b domain.Labels) bool

LabelsEqual reports whether two label maps are equal (same keys + values). Used by Update use-cases to decide whether `labels` is a real change for the audit `changed_fields` set (no-op label re-set must not count as a change).

func LogRepoErr ¶

func LogRepoErr(ctx context.Context, logger *slog.Logger, op string, err error) error

LogRepoErr переводит ошибку хранилища в gRPC-статус и, если перевод СТИРАЕТ причину, называет её журналу сервера.

Какие исходы пишутся и почему не все ¶

Пишутся ровно те, чьё сообщение на проводе причины НЕ несёт:

• `INTERNAL` — текст фиксирован («internal error») by construction, иначе наружу уехал бы текст драйвера;
• `UNAVAILABLE` — текст тоже фиксирован («service unavailable»), по той же причине: цепочка ведёт к драйверу. До этой правки он собирался из цепочки, и обёртка вызывающего уезжала на провод дословно. Подсистему текст не называет: признак ставит и база, и сосед, и гейт прав.

Остальные отказы называют свою причину САМИ и адресованы вызывающему: «Project %s not found», «Illegal argument …». Дублировать их в журнале значило бы писать строку на каждое обычное обращение арендатора — и та единственная, ради которой журнал и читают, утонула бы среди них. Заметность, введённая таким способом, уничтожается тем же средством, которым вводится.

Что пишется ¶

Полоса (`op`), полная цепочка ошибки (там же код состояния, который мост SQLSTATE оставляет намеренно) и КОНКРЕТНЫЙ ТИП ошибки. Тип назван отдельно, потому что отказ, не несущий строки состояния вовсе (не дозвонились до базы), цепочкой не отличим от прочих, а типом — отличим сразу.

Журнал — серверный, на провод из него не идёт ничего: возвращаемый статус собирает `MapRepoErr`, и он остаётся единственным местом перевода.

func MapOperationsListErr ¶

func MapOperationsListErr(err error) error

MapOperationsListErr classifies a failure of operations.Repo.List by WHAT THE STORE ANSWERED, never by what the caller happened to send.

The operations repo validates the caller's page format itself and reports it as a gRPC InvalidArgument naming the field — a page_token it could not decode, a page_size outside [0..1000] (corevalidate.PageSize). That classification is authoritative and passes through unchanged, field violations included. Everything else the repo returns is a store failure and gets the fixed INTERNAL text (never the pgx/SQL text).

The shape this replaces keyed on "was a page_token supplied", which is not a fact about the failure at all. It mislabelled in both directions: a database that was down was reported as a malformed cursor — sending the operator to fix a client that was fine — and a page_size out of range on the FIRST page (no token yet) was reported as an internal fault, filing a caller's mistake as an outage. Both are now decided by the store's own answer.

func MapRepoErr ¶

func MapRepoErr(err error) error

MapRepoErr — sentinel → gRPC status. Возвращает nil на nil-input.

Полное покрытие 8 sentinel'ов (включая ErrPermissionDenied / ErrUnauthenticated, которых не было в per-resource копиях — leak'ало `codes.Internal` клиенту до этой консолидации).

Fallback'и:

• если err уже несет gRPC status (не codes.Unknown) — пропускаем через;
• если err-текст начинается с "Illegal argument" — YC-style InvalidArgument (parity с verbatim-формой error-сообщений);
• иначе — Internal с переданным err-текстом (StripSentinel снимает sentinel-prefix чтобы клиент не увидел "not found: ...").

Порядок веток — сначала pass-through, потом sentinel-switch (форма kacho-nlb). Он несущий, а не косметический: pkg/validate кладёт имя поля ТОЛЬКО в google.rpc.BadRequest-details, сообщение остаётся общим «invalid argument». Пересборка статуса в sentinel-ветке (`status.Error(code, StripSentinel(err))`) детали теряет, поэтому ошибка, обёрнутая через `%w` на iamerr.Err*, обязана пройти pass-through ПЕРВОЙ. status с codes.Unknown под pass-through НЕ попадает (guard `!= Unknown`) — он падает в sentinel-switch и дальше в фиксированный INTERNAL, без leak'а.

func MapValidationErr ¶

func MapValidationErr(err error) error

MapValidationErr — обертка для результатов `domain.<Type>.Validate()` (cumulative multierr). Все sync-handler'ы вызывают ее на validation-stage перед эмитом Operation, чтобы InvalidArgument имел единую форму.

func MaskAllows ¶

func MaskAllows(mask []string, field string) bool

MaskAllows возвращает true, если поле `field` присутствует в mask, ИЛИ если mask пустой (full-PATCH semantics — все поля применяются).

Заменяет inlined-closure pattern:

apply := func(field string) bool {
    if len(mask) == 0 { return true }
    for _, m := range mask { if m == field { return true } }
    return false
}

func NameBlockingGrants ¶

func NameBlockingGrants(err error, named []string, total int) error

NameBlockingGrants дополняет отказ полосы перечнем выдач, которые ДЕРЖАТ членство: тем же перечнем прозой и машинно.

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

func OperationToProto ¶

func OperationToProto(op *operations.Operation) *operationpb.Operation

OperationToProto — прослойка к общему слою: перевод строки операции в контракт объявлен в дереве ОДИН раз (`pkg/operations/operationspb`, задача #1369).

До сведения объявлений было двенадцать, а смысловых версий — пять; расходились они именем помощника усечения времени и охраной пустого значения, то есть там, где расхождение не ломает сборку и видно только тому, кто сравнит копии.

func ResolveLabelsUpdate ¶

func ResolveLabelsUpdate(mask []string, body domain.Labels) (newLabels domain.Labels, apply bool)

ResolveLabelsUpdate решает, нужно ли применить labels в Update, и возвращает целевое значение метки.

proto3-map не несет presence: пустой `labels:{}` и отсутствующий labels в теле приходят в use-case как nil domain.Labels — неотличимо. Поэтому единственный надежный сигнал «очистить labels» — присутствие "labels" в update_mask:

• mask содержит "labels" → apply, значение = тело (nil/пусто → очистка);
• mask пустой (full-PATCH) и labels переданы в теле → apply, значение = тело;
• иначе → labels не трогаем.

При apply=true newLabels всегда non-nil (пустой набор = очистка), чтобы writer записал labels='{}' и LabelsEqual корректно сравнил с текущим значением.

func RevokeBindingsInScope ¶

func RevokeBindingsInScope(
	ctx context.Context,
	w kanamerepo.Writer,
	resourceType domain.ResourceType,
	resourceID string,
	displayNoun string,
) ([]outboxtypes.RelationTuple, int, error)

RevokeBindingsInScope сносит КАЖДУЮ выдачу, сделанную на область (resourceType, resourceID), внутри транзакции вызывающего: читает её персистентную ведомость выпущенных кортежей, удаляет строку выдачи (её ведомость уходит каскадом) и ВОЗВРАЩАЕТ собранный набор кортежей на снятие.

Эмитит собранное САМ ВЫЗЫВАЮЩИЙ — вместе со своими собственными кортежами жизненного цикла (указатель аккаунта на кластер, структурные указатели проекта), которые в ведомости выдач по построению не значатся.

displayNoun — существительное ресурса в тоне контракта («Account», «Project»); попадает в текст отказа, который читает оператор.

func TimestampProto ¶

func TimestampProto(t time.Time) *timestamppb.Timestamp

TimestampProto конвертирует time.Time в *timestamppb.Timestamp с truncate'ом до секунд (конвенция Kachō: timestamp precision = seconds, не nanoseconds). Zero-time → nil (parity с handler-стиль омитом null timestamp полей).

func ValidatePageToken ¶

func ValidatePageToken(field, token string) error

ValidatePageToken returns InvalidArgument when a non-empty token is not a well-formed keyset cursor (base64 of `<RFC3339Nano>|<id>`). Empty → OK (first page). The message is the stable contract form "Illegal argument <field>".

func ValidatePagination ¶

func ValidatePagination(pageToken string, pageSize int32) error

ValidatePagination — sync-проверка формата пагинации целиком (page_size + page_token) для списочного use-case'а.

Зачем в use-case'е, а не только в хендлере. Списочный use-case решает, кто спрашивает, раньше, чем читает страницу: анонимный или неуправомоченный вызывающий получает пустую страницу и до репозитория не доходит. Пока формат проверял только репозиторий, один и тот же мусорный курсор получал разный ответ в зависимости от того, что вызывающему выдано, — то есть проверка ввода зависела от прав. Здесь она от них не зависит.

Репозиторий остаётся авторитетным: он повторяет обе проверки на служимом пути.

ВАЖНО про место вызова: сюда приходит уже суженное до int32 значение. Если вызывающий сузил его насыщающим преобразованием, отрицательный ввод превратился в 0 ещё ДО этой строки, а 0 в контракте значит «применить умолчание» — проверка стоит, верна и не может сработать. Формат СЫРОГО запроса судит ValidateRawPagination; эта функция остаётся проверкой уже разобранного фильтра.

func ValidateRawPagination ¶

func ValidateRawPagination(pageToken string, pageSize int64) error

ValidateRawPagination — формат пагинации по СЫРЫМ значениям запроса, до любого преобразования типа и до любого решения о доступе.

Зачем отдельная функция и почему она принимает int64. `page_size` приезжает по проводу как int64, а внутренние фильтры iam — int32, поэтому транспорт сужал значение насыщающим преобразованием (safeconv.ClampNonNegInt32). Насыщение — не проверка: −1 становится нулём, ноль означает «умолчание», и вызывающий получает страницу, о которой не просил, ничего об этом не узнав. Судить надо то, что прислали, а сужать — уже проверенное (после этой строки значение лежит в [0..1000] и в int32 помещается by construction).

Порядок тоже её предмет. Вопрос «правильно ли составлен запрос» имеет ОДИН ответ для всех вызывающих, поэтому отвечать на него надо раньше, чем на вопрос «что этому вызывающему видно» (api-conventions.md: формат → authz → repo). Иначе один и тот же мусорный курсор даёт InvalidArgument тому, у кого грант есть, и отказ либо пустую страницу тому, у кого его нет.

Текст отказа — платформенный (`validate.PageSize`), тот же, что у vpc/geo/storage и что записан в требованиях к продукту: "page_size must be in [0..1000]".

func ValidateRawVisiblePagination ¶

func ValidateRawVisiblePagination(pageToken string, pageSize int64) error

ValidateRawVisiblePagination is ValidateVisiblePagination over the RAW request values — the transport's int64 page_size before it is narrowed to int32. Narrowing saturates, and saturation is not validation: −1 becomes 0, and 0 means "apply the default", so a caller would receive a page it did not ask for and never learn of it.

func ValidateResourceID ¶

func ValidateResourceID(id, prefix, resourceName string) error

ValidateResourceID проверяет соответствие id формату `<prefix><17-char-tail>` (общая для всех IAM-ресурсов длина — `domain.ShortIDLen`).

СТРОГОСТЬ ЗДЕСЬ — РЕШЕНИЕ, А НЕ УПУЩЕНИЕ, и она отличает эту проверку от платформенного маршрутизатора `corevalidate.ResourceID` по ТРЁМ осям, а не по одной: пустая строка (здесь отвергается, там проходит), чужой тип с известным префиксом (здесь отвергается, там проходит в полосу отсутствия) и длина тела (здесь фиксирована, там не проверяется).

Поэтому «привести к конвенции» заменой вызова — ослабление по трём осям сразу; ось пустой строки при этом завела бы отказ с вырезанным id (`"Account not found"`) во все места разом. Расхождение с `api-conventions.md` §«By-lane code-split», довод, три границы и ВНЕШНИЙ предикат пересмотра записаны решением: `docs/engineering/architecture/known-divergences.md`, §19.

ЗВАТЬ ТОЛЬКО ДЛЯ СВОЕГО ИДЕНТИФИКАТОРА. Тип чужого решает его владелец; строгая сверка префикса на чужой ссылке — нарушение конвенции, и она стережётся гейтом `TestStrictIDFormatCheckStaysOwnerScoped` (ids_owner_scope_test.go): префикс обязан быть константой собственного пакета `domain`.

На несоответствии возвращает InvalidArgument с сообщением в каноническом Kachō-формате: `"invalid <resource-name> id '<id>'"`. resourceName — для error-сообщения (например "account", "service account", "access binding"; **именно** в той форме, в какой Kachō показывает ошибку — с пробелами, не camelCase).

func ValidateUpdateMask ¶

func ValidateUpdateMask(mask []string, mutable map[string]struct{}, immutable map[string]string) error

ValidateUpdateMask проверяет, что каждое поле в mask:

• НЕ присутствует в `immutable` map (если присутствует → InvalidArg с per-field error message — по контракту error-format Kachō), И
• присутствует в `mutable` set (если нет — Illegal-argument update_mask field — по контракту error-format Kachō).

Пустая mask проходит без ошибок (full-PATCH semantics).

`immutable` value-string — сообщение для конкретного field (`"<field> is immutable after <Resource>.Create"` — см. per-resource maps).

func ValidateVisiblePagination ¶

func ValidateVisiblePagination(pageToken string, pageSize int32) error

ValidateVisiblePagination — the whole page-format question for a visible-page list, answered before anything about the caller is decided.