Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

aggrega search

Поиск в локальном индексе настроенных реестров

Синтаксис

aggrega search [query] [flags]

Описание

Search the local index of the configured registries for entities matching a
free-text query and optional facet filters.
The index is the offline snapshot written by 'aggrega registry update'; search
reads it and contacts no network. Run 'aggrega registry update' first, and again
whenever you want to pick up newly published entities. A freshness line naming
each searched registry and when its index was last updated is written to standard
error, so standard output carries only the result data.
The optional positional query is a case-insensitive substring matched against
each entity's name and description. The facet filters narrow the result further,
combining as AND across facets and OR within a repeatable facet:
--kind entity kind (component, feature, recipe, featurerecipe,
workload, plugin); repeatable, case-insensitive
--capability a plugin capability; repeatable
--plugin-type a plugin socket type (for example provider, governance)
-l, --selector a label selector over the entity's catalog labels
Category is matched through the label selector, not a dedicated flag: a catalog
category is the label component.aggrega.ai/category, so
'-l component.aggrega.ai/category=compute' scopes the result to that category.
With no --registry, every configured registry's index is searched and the
results are merged. With --registry (a host or a friendly alias), only that
registry's index is searched.
A search needs at least one configured registry. With none configured there is
nowhere to look, so the command refuses: the reason goes to standard error,
standard output carries nothing, and the exit status is non-zero. That is what
lets a caller tell a search that ran and matched nothing from a search that
could not be performed. Run 'aggrega config init' to register a registry with
its signature trust policy, then 'aggrega registry update' to build the index.
The version reported for an entity is the one a resolution would take: a
version a publisher has retracted, where the retraction carries a signature
this workspace's trust policy verifies, is not reported. Such an entity is
still listed, and the versions left out are named in a NOTES column, so an
entity whose every published version is retracted is reported as existing with
no version to take rather than disappearing from the result. Pass
--include-retracted to report the highest published version whatever its
retraction status; the NOTES column names the retracted versions either way.
The same holds for 'aggrega search -o json', where the 'version' field carries
the version a resolution would take and a 'retracted' array names the versions
left out.

Флаги

ФлагПо умолчаниюОписание
--capability[]Возможность (capability) сущности Plugin для сопоставления. Можно указывать несколько раз; сохраняется запись, объявляющая любую из них.
--include-retractedfalseСообщать наивысшую опубликованную версию, даже если проверенный маркер её отзывает. По умолчанию сообщается версия, которую выбрало бы разрешение зависимостей.
--kind[]Вид сущности для сопоставления (component|feature|recipe|featurerecipe|workload|plugin). Можно указывать несколько раз; сохраняется запись, соответствующая любому из них. Без учёта регистра.
--limit0Ограничить число результатов (0 — без ограничения).
--output, -otableФормат вывода: table|json|names.
--plugin-type—Тип сокета сущности Plugin для сопоставления (например, provider, governance, linter).
--registry—Искать только в этом реестре, указанном по хосту или понятному псевдониму. По умолчанию поиск ведётся во всех настроенных реестрах.
--selector, -l—Селектор меток по меткам каталога сущности, включая её категорию (-l component.aggrega.ai/category=compute).

Если не настроен ни один реестр

Поиск читает локальный индекс реестров, к которым настроен доступ с этой машины, поэтому ему нужен хотя бы один из них. Если не настроен ни один, искать негде, и aggrega search отказывается отвечать: команда пишет причину в стандартный поток ошибок, завершается с ненулевым кодом и оставляет стандартный вывод пустым — в любом формате вывода, включая --output json.

Отказ позволяет различать два разных ответа. Поиск, который выполнился и ничего не нашёл, завершается с нулевым кодом и сообщает (no matches) в стандартный вывод; поиск, который вообще не смог выполниться, завершается с ненулевым кодом и ничего туда не выводит. Поэтому скрипт, ветвящийся по коду возврата, может отличить «эта сущность не опубликована» от «у этой машины нет реестра для запроса», чего уведомление в стандартном выводе с нулевым кодом выразить не может.

Выполните aggrega config init, чтобы зарегистрировать реестр вместе с его политикой доверия к подписям, а затем aggrega registry update, чтобы построить локальный индекс, который читает поиск.

aggrega registry list и aggrega registry update реагируют на ту же ситуацию иначе, и это сделано намеренно. Список реестров, когда их нет, — это полный список пустого множества, а построению индекса, которому нечего обходить, больше нечего делать: обе операции завершены, поэтому обе пишут в стандартный вывод и завершаются с нулевым кодом. Только поиск сообщает, что не смог сделать то, о чём его попросили.

Версия, которую сообщает поиск

Столбец VERSION содержит версию, которую выбрало бы разрешение зависимостей. Версия, отозванная её издателем, не сообщается, если отзыв несёт подпись, которую проверяет политика доверия этого рабочего пространства, — это те же два условия, которые решают, влияет ли отзыв на pull, поэтому поиск и pull сходятся в том, какая версия является ответом.

Отзыв, не удовлетворяющий любому из условий, ничего не меняет в сообщаемом. Маркер с рекомендательным уровнем серьёзности оставляет свою версию доступной для выбора, а маркер, подпись которого не проходит проверку, не является утверждением, на основании которого действует это рабочее пространство. В обоих случаях наивысшая опубликованная версия сообщается точно так же, как если бы маркера не было вовсе.

Сущность с отозванной версией всё равно выводится. Столбец NOTES называет исключённые версии и появляется только в результате, где есть что сообщить. Сущность, все опубликованные версии которой отозваны, выводится с (none) в качестве версии и примечанием о том, что версий не осталось, а не удаляется из результата — пропущенную сущность было бы невозможно отличить от несуществующей.

Передайте --include-retracted, чтобы сообщать наивысшую опубликованную версию независимо от статуса её отзыва; это ответ на вопрос «что опубликовано?», а не «что мне использовать?». Флаг меняет только сообщаемую версию; столбец NOTES называет отозванные версии в любом случае.

Поиск читает локальный индекс, который записывает aggrega registry update, поэтому он сообщает то, что каждый реестр заявлял на момент последнего построения индекса. Версия, отозванная после этого, ещё не учтена, а строка актуальности, выводимая в стандартный поток ошибок, называет момент построения каждого индекса.

Машиночитаемый результат

--output json передаёт тот же контракт в двух полях:

  • version — версия, которую выбрало бы разрешение зависимостей. Это пустая строка, когда все опубликованные версии отозваны, и в паре с ней идёт список retracted, называющий их все.
  • retracted перечисляет версии, исключённые из этого выбора, в порядке возрастания версий. Поле отсутствует, если ничего не исключено.

Потребитель, которому нужно знать, какую версию он получит, читает version. Выводить это из массива deprecations означает заново реализовывать условия уровня серьёзности и подписи, а вторая реализация этих условий вполне может расходиться с той, которую применяет компилятор; retracted сообщает результат, уже полученный по этим условиям.

Каждая запись также содержит published: все версии, записанные в индекс, в порядке возрастания версий, каждая с manifestDigest, в который разрешался её тег при построении индекса, и, если политика доверия этого рабочего пространства проверила собственную подпись этой версии, с её signer — из нескольких проходящих проверку тот, который журнал прозрачности записал раньше всех. Версия без signer не несёт подписи, проверенной этой политикой, и больше о ней ничего не сообщается. Потребитель, читающий содержимое одной версии, адресует его по этому дайджесту — например, aggrega inspect oci://<host>/<repository>@<digest>, — поэтому он читает именно те байты, которые записал индекс, что бы ни произошло с тегом впоследствии.

Если что-либо фиксирует время публикации версии, её запись также содержит publishedAt — метку времени RFC 3339 в UTC с точностью до секунды — и publishedAtSource, указывающее её источник. transparency-log — время, когда журнал прозрачности записал бесключевую подпись версии, которую политика доверия этого рабочего пространства проверила вместе с подписанным обещанием журнала об этом времени, — подпись signer, самую раннюю из проходящих проверку, поэтому повторное подписание версии не меняет ни то, ни другое. publisher — время, которое публикация заявила рядом с опубликованным, по собственным часам публикующей машины, которые ничем не заверены. Они хранятся раздельно, чтобы потребитель, сортирующий по дате, мог отличить заверенное время от заявленного. Версия без обоих не несёт даты, и больше о ней ничего не сообщается; о том, когда записывается каждое, см. aggrega registry update.