ADR 0013: курсорные страницы каталога UPack

Статус: accepted. Дата: 2026-09-23.

Контекст

Нативный список зарегистрированных UPack ограничивался 1000 версиями после фильтрации. Простая нарезка исходного SQL-порядка на страницы нарушила бы выбранную сортировку по SemVer: текстовый порядок 1.10.0 и 1.9.0 отличается от порядка версий.

Решение

• Нативный GET /api/v1/repositories/{repository}/packages возвращает до 50 записей по умолчанию, максимум 100 по limit, и непрозрачный next для параметра after. SDK и консоль используют тот же контракт. Группировка строится только внутри текущей страницы.
• Миграция 7 добавляет неизменяемую SQL-функцию arkvory_semver_key(text). Она строит сравнимый ключ из числовых частей версии и идентификаторов prerelease; build metadata не влияет на приоритет. При равном приоритете исходная строка версии и ID артефакта задают устойчивый порядок. Для имён группы и пакета используется регистронезависимое сравнение с коллацией C.
• Адаптер выполняет keyset-запрос с LIMIT limit+1. Курсор содержит значения последней строки, репозиторий, выбранные фильтры, сортировку и направление. Некорректный курсор или его применение с другим репозиторием, фильтрами или порядком возвращает invalid_input. Права репозитория проверяются до чтения страницы.
• Запрос не удерживает SQL-транзакцию между страницами. Добавленная во время просмотра версия может появиться на следующей странице, если её ключ позже курсора; версия перед курсором в этой последовательности не появится. Для неизменных записей повторов и пропусков нет.

Последствия

Миграция 7 только добавляет функцию и не переписывает существующие таблицы. Замеры и последующие индексы описаны в ADR 0014. На момент решения lookup exact/latest для скачивания сохранял предел 1000 совпадений; последующая точечная выборка exact/latest устранила его без изменения внешнего контракта. Курсор не содержит секретов и не заменяет проверку ACL.