Documentation
¶
Overview ¶
Package ids — генератор short-form идентификаторов ресурсов в формате "<3-char prefix><17-char crockford-base32>" (всего 20 символов).
Короткие непрозрачные id с per-domain-префиксом: ресурсы и операции идентифицируются короткими строками с префиксом домена, что позволяет gateway-у маршрутизировать запросы к нужному backend по первому сегменту id.
Префиксы определены константами PrefixCloud, PrefixFolder, PrefixNetwork, и т.д. Префикс должен быть ровно 3 символа.
Index ¶
Constants ¶
const ( PrefixCloud = "b1g" PrefixFolder = "b1g" PrefixOrganization = "bpf" PrefixNetwork = "net" PrefixSubnet = "sub" PrefixAddress = "adr" PrefixRouteTable = "rtb" PrefixSecurityGroup = "sgr" PrefixGateway = "gtw" // NetworkInterface и AddressPool — собственные prefix'ы, централизованные здесь. PrefixNetworkInterface = "nic" PrefixAddressPool = "apl" // AnycastAddressPool — tenant-facing пул anycast-VIP, привязываемый к Network // (M:N); собственный resource-prefix, чтобы id-парсеры отличали его от обычного // AddressPool (`apl`). PrefixAnycastPool = "aap" // compute: Instance/Disk делят `epd`, Image/Snapshot делят `fd8` (зеркалит // VPC-группировку); все compute-операции получают `epd` (== PrefixInstance), // чтобы api-gateway opsproxy мог одним правилом маршрутизировать Operation.Get. PrefixInstance = "epd" PrefixDisk = "epd" PrefixImage = "fd8" PrefixSnapshot = "fd8" // storage (kacho-storage): собственный storage-домен, отдельный от compute. // Volume — block-volume нового домена (`vol`); это НЕ epd-Disk, а отдельный // ресурс со своим prefix'ом. StorageSnapshot — snapshot storage-домена // (`snp`), отдельно от compute PrefixSnapshot (`fd8`). DiskType — человеко- // читаемый slug (НЕ NewID-prefix), поэтому своей константы не требует. PrefixVolume = "vol" PrefixStorageSnapshot = "snp" // PrefixStorageImage — storage boot-image (`img`), отдельно от compute // PrefixImage (`fd8`). storage Image.Create эмитит `img<17>` через // NewID(domain.PrefixImage="img"); БЕЗ регистрации здесь well-formed `img`-id // отвергался бы authz-edge api-gateway (corevalidate.ResourceID → 400 "invalid // resource id 'img…'") на КАЖДОМ Get/Update/Delete образа (#59 storage-image). PrefixStorageImage = "img" // nlb: LoadBalancer/Listener/TargetGroup получают каждый свой 3-char // префикс — opsproxy в api-gateway маршрутизирует по PrefixOperationNLB // (== PrefixLoadBalancer), но resource-prefix у Listener/TargetGroup // отдельный, чтобы id-парсеры могли отличать тип ресурса по prefix-у // (в отличие от vpc, где Subnet/Address делят `e9b` — там тип // определяется контекстом URL-path). PrefixLoadBalancer = "nlb" PrefixListener = "lst" PrefixTargetGroup = "tgr" // apps (PaaS): Application получает свой 3-char resource-prefix `app`; // apps-домен Operation получает отдельный стабильный op-prefix `aop` // (декаплен от ресурса, как enp/epd) — api-gateway opsproxy маршрутизирует // Operation.Get по первым 3 символам. PrefixApplication = "app" // registry: Registry (namespace OCI-реестра поверх zot) получает `reg` как // resource-prefix; registry-домен Operation — отдельный стабильный op-prefix // `rop` (декаплен от ресурса), по которому api-gateway opsproxy маршрутизирует // Operation.Get к kacho-registry. Repository/Tag — read-only проекция из zot, // собственного id-prefix не имеют (адресуются именем внутри namespace). PrefixRegistry = "reg" PrefixOperationReg = "rop" // Operation prefix per service-domain — отдельный, стабильный per-домен // prefix, по которому gateway opsproxy маршрутизирует Operation.Get. // // PrefixOperationVPC зафиксирован как `enp` (vpc-op-root), декаплен от // PrefixNetwork — opsproxy.prefixToBackend["enp"]="vpc" остается неизменным, // существующие enp-операции в БД продолжают роутиться. PrefixOperationRM = PrefixCloud // resource-manager (legacy): b1g PrefixOperationVPC = "enp" // vpc op-root (декаплен от PrefixNetwork) PrefixOperationCompute = PrefixInstance // compute: epd PrefixOperationNLB = PrefixLoadBalancer // nlb: nlb PrefixOperationApps = "aop" // apps op-root (декаплен от PrefixApplication) PrefixOperationStorage = "sop" // storage op-root (декаплен от PrefixVolume; opsproxy sop→storage) )
Per-resource префиксы (3 символа, lowercase).
Сгруппированы по домену:
- resource-manager (legacy): cloud, folder, organization
- vpc: network, subnet, address, route_table, security_group, gateway, network_interface, address_pool
Каждый VPC-ресурс получает СВОЙ 3-char prefix. Тип ресурса читается по id (как в NLB-домене). Routing не ломается: resource-RPC маршрутизируются по REST-path, а НЕ по id-prefix.
Operation.id остается с ОТДЕЛЬНЫМ per-domain prefix (PrefixOperationVPC = `enp`, PrefixOperationCompute = `epd`, …) — gateway opsproxy маршрутизирует Operation.Get по первым 3 символам id, поэтому op-prefix должен быть стабильным per-домен (а не per-ресурс).
const ( // PrefixMachineTypeHyphen — compute MachineType (`mt-…`, 2-char prefix; // COMP-1 F7). NewHyphenID("mt") → "mt-<17-base32>". PrefixMachineTypeHyphen = "mt" // PrefixInstanceHyphen — compute Instance редизайна (`ins-…`, COMP-1 F8); // замещает legacy слитный PrefixInstance (`epd`, делит с Disk) для новых // инстансов монорепо project/kacho. NewHyphenID("ins") → "ins-<17-base32>". PrefixInstanceHyphen = "ins" // PrefixInteractiveClientHyphen — iam InteractiveClient (IAM-INT-1): клиент // интерактивного входа человека, admin-only ресурс Internal*-сервиса. // NewHyphenID("ic") → "ic-<17-base32>" (20 символов). Двухсимвольный prefix // — в пределах 2..3 инварианта NewHyphenID (как `mt`). PrefixInteractiveClientHyphen = "ic" // PrefixCidrGroupHyphen — vpc CidrGroup (`cdg-…`): именованный набор // префиксов, на который ссылается правило группы безопасности. // NewHyphenID("cdg") → "cdg-<17-base32>". // // Почему не `grp`/`aps`: `grp` занят группой iam, а имя ресурса выбрано // `CidrGroup` (§9.1.0 плана) — `Cidr` уже слово этого продукта, поэтому и // префикс выведен из него, а не придуман. PrefixCidrGroupHyphen = "cdg" // PrefixLimitHyphen — iam Limit (`lim-…`): величина потолка на число // ресурсов арендатора, назначаемая администратором на одной из трёх областей // видимости (умолчание · аккаунт · проект). NewHyphenID("lim") → // "lim-<17-base32>". // // Почему iam, а не отдельный домен: предел — свойство арендатора, он // заводится вместе с проектом и умирает вместе с ним, а iam уже владеет // Account/Project и уже является leaf'ом для каждого сервиса (приёмка // vpc-quota, Р1). PrefixLimitHyphen = "lim" // PrefixMembershipHyphen — iam Membership (`mbr-…`): принадлежность человека // аккаунту как ОТДЕЛЬНАЯ связь, которых у глобальной личности бывает // несколько (IAM-ID-1/IAM-ID-2). // // Чеканит его НЕ `NewHyphenID`, а неизменяемая SQL-функция // `kaname.membership_mirror_id` — `'mbr-' || substr(md5(…), 1, 17)`: // писателей строки членства больше одного (триггер зеркала и два стейтмента // репозитория), и все они обязаны прийти к ОДНОЙ строке на одну пару // «человек × аккаунт». Шестнадцатеричные цифры md5 — подмножество крокфордова // алфавита этого продукта, поэтому тело остаётся в алфавите канона. // // Запись здесь обязательна и не косметическая: без неё `validate.ResourceID` // отвергал бы корректный идентификатор, который сам же продукт и произвёл, — // то есть одиночное чтение членства отвечало бы `INVALID_ARGUMENT` на всяком // входе (тот же класс, что уже ловили на пределе арендатора выше). PrefixMembershipHyphen = "mbr" )
Going-forward hyphen-form prefix КОНСТАНТЫ (B3-канон, redesign-2026). В отличие от legacy 3-char Prefix* (слитная форма, эмитится NewID) — эти адресуют hyphen-форму "<prefix>-<crockford-base32>", генерируемую NewHyphenID. Часть 2-символьные (`mt`) — вне 3-char NewID-инварианта by construction. Каждая ОБЯЗАНА входить в hyphenFormPrefixes (guard-тест TestHyphenPrefixConstants_InCanon), иначе validate.ResourceID отвергнет well-formed id, который NewHyphenID произвёл.
Variables ¶
This section is empty.
Functions ¶
func HasKnownPrefix ¶
HasKnownPrefix проверяет, что id имеет валидную форму ресурс-id: ровно totalLen символов, 3-символьный префикс входит в множество объявленных префиксов проекта (knownPrefixes), а тело — валидная crockford-base32 строка длиной idBodyLen. Используется для acceptance в gateway/proxy без знания конкретного типа ресурса.
func IsValid ¶
IsValid проверяет, что id соответствует формату "<prefix><17 lowercase crockford-base32-chars>". Не валидирует «правильность» энтропии — только синтаксис. Полезно для сервис-уровневых проверок входов.
func KnownHyphenPrefixes ¶
func KnownHyphenPrefixes() map[string]struct{}
KnownHyphenPrefixes возвращает КОПИЮ множества going-forward hyphen-form prefix'ов (B3). Потребитель (validate.baseHyphenPrefixes) строит свой набор поверх этого + config-extra, не дублируя литералы. Как и KnownPrefixes(), это ЕДИНЫЙ источник истины для hyphen-канона — чтобы router-классификатор и любой будущий consumer не разошлись копиями списка.
func KnownPrefixes ¶
func KnownPrefixes() map[string]struct{}
KnownPrefixes возвращает КОПИЮ множества известных префиксов — потребители (напр. validate.baseResourceIDPrefixes) строят свой набор поверх этого, не дублируя список литералов и не рискуя drift'ом с HasKnownPrefix.
func NewHyphenID ¶
NewHyphenID возвращает going-forward hyphen-form идентификатор "<prefix>-<17-char crockford-base32>" (B3-канон, §2 unified-system-design). В отличие от NewID (слитная 3-char форма) — prefix здесь 2..3 символа (`mt`/`ins`/…), а тело отделено дефисом. Источник энтропии — crypto/rand (то же тело, что у NewID: idBodyLen символов).
Каждый сервис мигрирует свой prefix на hyphen-генерацию в собственном редизайне (router validate.ResourceID уже принимает hyphen-форму с Phase-0 B3); COMP-1 — точка миграции compute для новых/редизайнутых ресурсов (MachineType `mt-`, Instance `ins-`). prefix обязан входить в KnownHyphenPrefixes(), иначе validate.ResourceID отвергнет сгенерированный id.
prefix вне диапазона 2..3 символов → panic (programmer error: prefix приходит из package-level константы).
func NewID ¶
NewID возвращает идентификатор формата "<prefix><17-char crockford-base32>" (всего 20 символов). Источник энтропии — crypto/rand.
prefix должен быть ровно 3 символа; иначе функция panic-ит (programmer error: префикс приходит из package-level константы).
func NewUID ¶
func NewUID() string
NewUID — DEPRECATED: оставлен для backward compatibility с reconciler-ами и legacy-кодом, которому нужен ResourceVersion (UUID-like opaque строка). Для resource id и operation id всегда использовать NewID(<prefix>).
Возвращает строку формата «kachō-style 20-char base32» БЕЗ префикса — для ResourceVersion-полей, где префикс не нужен и не может конфликтовать с прокси-routing-ом.
Types ¶
This section is empty.