ids

package
v1.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 13, 2026 License: Apache-2.0 Imports: 3 Imported by: 0

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

View Source
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-ресурс).

View Source
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

func HasKnownPrefix(id string) bool

HasKnownPrefix проверяет, что id имеет валидную форму ресурс-id: ровно totalLen символов, 3-символьный префикс входит в множество объявленных префиксов проекта (knownPrefixes), а тело — валидная crockford-base32 строка длиной idBodyLen. Используется для acceptance в gateway/proxy без знания конкретного типа ресурса.

func IsValid

func IsValid(id, prefix string) bool

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

func NewHyphenID(prefix string) string

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

func NewID(prefix string) string

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL