Help us shape the future of Go! Take the 2026 Go Developer Survey

ids

package
v1.16.0 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: Apache-2.0 Imports: 3 Imported by: 1

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"
	// PrefixAccessKeyHyphen — iam AccessKey (`ak-…`): ключ доступа человека
	// (WebAuthn), ресурс со своей строкой, своими глаголами и своим потолком
	// (iam Ф7, PRO-Robotech/kacho#1273; приёмка `access-keys-are-ours.md`, Р10).
	// NewHyphenID("ak") → "ak-<17-base32>" (20 символов): двухсимвольный prefix,
	// как `ic`.
	//
	// Идентификатор удостоверения WebAuthn адресом НЕ является — это байты
	// нормы, которые выбирает аутентификатор; наружу ключ назван только этим
	// `id`. Запись здесь обязательна по тому же классу, что у `lim` и `mbr`:
	// без неё `validate.ResourceID` отвергал бы корректный `id`, который сама
	// служба и выдала, и снятие ключа отвечало бы `INVALID_ARGUMENT` на всяком
	// входе.
	PrefixAccessKeyHyphen = "ak"
	// PrefixTokenFamilyHyphen — iam семейство токенов (`tfm-…`): грант OAuth 2.0
	// службы доступа, под ключом которого живут код авторизации, токен доступа
	// и токен обновления одной выдачи и по которому семейство отзывается
	// целиком. NewHyphenID("tfm") → "tfm-<17-base32>" (21 символ).
	//
	// Ключ чеканит служба крючком церемонии `oauthceremony.Config.NewGrantID`,
	// и чеканит ИМЕННО NewHyphenID: слитная NewID("tfm") даёт `tfm<17>` без
	// дефиса, и ограничение схемы служебной таблицы семейств (`^tfm-…`)
	// отвергало бы вставку на каждой выдаче кода. Запись в каноне обязательна по
	// тому же классу, что у `lim`, `mbr` и `ak`: без неё `validate.ResourceID`
	// отвергал бы корректный ключ, который служба сама и выдала.
	PrefixTokenFamilyHyphen = "tfm"
	// PrefixHumanSessionHyphen — iam запись сессии человека (`hss-…`): одна
	// сессия входа человека в службе доступа. NewHyphenID("hss") →
	// "hss-<17-base32>" (21 символ).
	//
	// Идентификатор — АДРЕС: перечень своих сессий его называет, выход из
	// выбранной сессии его принимает (PRO-Robotech/kaname#634). Запись в каноне
	// обязательна по тому же классу, что у `lim`, `mbr`, `ak` и `tfm`: без неё
	// `validate.ResourceID` отвергал бы корректный идентификатор, который служба
	// сама и выдала, и выход из выбранной сессии отвечал бы `INVALID_ARGUMENT`
	// на всяком входе.
	PrefixHumanSessionHyphen = "hss"
)

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