Допустим, вам захотелось, на всякий случай, сохранить копию всех пакетов nuget.org. Как обнаружить и скачать все пакеты не привлекая внимания админов сервиса?

Протоколы NuGet

Как NuGet-клиент обнаруживает пакеты? У клиента есть список пакетов, которые пользователь хочет скачать, клиент должен выяснить откуда их скачать, рекурсивно разрешить зависимости и собственно произвести загрузку. Для получения всей необходимой информации он обращается к API сервиса.

Особо любознательные знают, что существует две версии протокола NuGet: v2 и v3 с соответствующими "source URLs":

• https://www.nuget.org/api/v2

• https://api.nuget.org/v3/index.json

V2 основан на OData (XML, странный синтаксис запросов - вот это вот все) и фактически является интерфейсом к БД. Официальной документации на него, насколько я понимаю, не существует, но есть неофициальная.

С помощью v2 можно, в принципе, перечислить все пакеты, но администрация сервиса не любит когда по v2 много стучатся и ограничивает частоту запросов v2 и урезает возможности. Не используйте v2.

Протокол v3 был разработан для улучшения масштабируемости. Практически весь v3 работает из статических файлов, которые раздаются через CDN, что масштабировать гораздо проще, чем веб-сервис с БД. Только поиск требует каких-то вычислительных мощностей для работы.

Подробнее про v3

Протокол более-менее адекватно документирован. Запрос к v3 source URL вернет нам JSON со списком "сервисов", предоставляемых реализацией NuGet-сервера.

Из реального ответа nuget.org, нас будут интересовать следующие сервисы:

{
    "@id": "https://api.nuget.org/v3/catalog0/index.json",
    "@type": "Catalog/3.0.0",
    "comment": "Index of the NuGet package catalog."
},

{
    "@id": "https://api.nuget.org/v3-flatcontainer/",
    "@type": "PackageBaseAddress/3.0.0",
    "comment": "Base URL of where NuGet packages are stored, in the format https://api.nuget.org/v3-flatcontainer/{id-lower}/{version-lower}/{id-lower}.{version-lower}.nupkg"
},    

Все (или почти все) JSON объекты, возвращаемые v3, на самом деле являются JSON-LD если вдруг вы знаете что это такое и как этим пользоваться. Из-за этого они содержат занимательные свойства с @ в начале имени, которые можно спокойно игнорировть. Возможно из-за этого же есть... "особенности" парсинга некоторых объектов, об этом ниже.

Catalog

С помощью Catalog/3.0.0 мы будем перечислять все пакеты. Каталог представляет собой журнал всего, что происходило с NuGet-пакетами с "начала времен". Прочитав каталог от начала до конца мы воспроизведем все изменения на nuget.org, что даст нам список всех пакетов. Из каталога ничего не удаляется, только добавляются записи в конец.

Протокол v3 не существовал с самого начала жизни nuget.org, поэтому при его создании был произведен импорт всех пакетов, существовавщих на момент запуска, что привело к созданию большого количества записей в начале каталога с близкими временными метками (1 февраля 2015 года). После этого, все новые пакеты имеют отметку времени близкую ко времени публикации.

https://api.nuget.org/v3/catalog0/index.json возвращает JSON примерно такой структуры:

{
  "@id": "https://api.nuget.org/v3/catalog0/index.json",
  "@type": [
    "CatalogRoot",
    "AppendOnlyCatalog",
    "Permalink"
  ],
  "commitId": "a304b4af-3a2c-4653-8ba8-2cdfd667951d",
  "commitTimeStamp": "2024-10-10T02:42:09.3106213Z",
  "count": 20671,
  "nuget:lastCreated": "2024-10-10T02:41:49.91Z",
  "nuget:lastDeleted": "2024-10-09T16:35:48.4746061Z",
  "nuget:lastEdited": "2024-10-10T02:41:49.91Z",
  "items": [
    {
      "@id": "https://api.nuget.org/v3/catalog0/page7713.json",
      "@type": "CatalogPage",
      "commitId": "9f4532df-09d2-473e-a5b5-acfe3fa3935a",
      "commitTimeStamp": "2018-12-29T16:00:42.7935125Z",
      "count": 533
    }
    ...
  ]
}

Это "оглавление каталога" (catalog index) - информация о всех его страницах. Чтобы не иметь один огромный файл, каталог разбит на страницы.

Свойства, начинающиеся на nuget: в этом ответе - недокументированные служебные поля, имеющие отношение к генерации каталога.

commitId - GUID последней записи (точнее группы записей, подробности ниже). Если он изменился с последнего чтения, значит были добавлены новые записи.

commitTimeStamp - время последней записи. Все временные метки используют UTC.

count - число страниц каталога.

items - массив объектов с информацией о каждой странице: GUID последней записи, время последней записи, число записей и ссылка на страницу.

Массив записей не отсортирован, если вам нужны страницы в порядке их создания, придется отсортировать его по полю commitTimeStamp.

Страницы каталога

Если послать запрос с адресом страницы, мы получим, например:

{
  "@id": "https://api.nuget.org/v3/catalog0/page0.json",
  "@type": "CatalogPage",
  "commitId": "19a4aedc-5139-4df5-81a3-b40aeabb3f3c",
  "commitTimeStamp": "2015-02-01T06:30:11.7477681Z",
  "count": 540,
  "items": [
    {
      "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.06.22.45/adam.jsgenerator.1.1.0.json",
      "@type": "nuget:PackageDetails",
      "commitTimeStamp": "2015-02-01T06:22:45.8488496Z",
      "nuget:id": "Adam.JSGenerator",
      "nuget:version": "1.1.0",
      "commitId": "b3f4fc8a-7522-42a3-8fee-a91d5488c0b1"
    },
    {
      "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.06.22.45/agatha-rrsl.1.2.0.json",
      "@type": "nuget:PackageDetails",
      "commitTimeStamp": "2015-02-01T06:22:45.8488496Z",
      "nuget:id": "Agatha-rrsl",
      "nuget:version": "1.2.0",
      "commitId": "b3f4fc8a-7522-42a3-8fee-a91d5488c0b1"
    },
    ...,
    {
      "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.06.30.11/superfarter.1.0.0.json",
      "@type": "nuget:PackageDetails",
      "commitTimeStamp": "2015-02-01T06:30:11.7477681Z",
      "nuget:id": "SuperFarter",
      "nuget:version": "1.0.0",
      "commitId": "19a4aedc-5139-4df5-81a3-b40aeabb3f3c"
    }
  ],
  "parent": "https://api.nuget.org/v3/catalog0/index.json",
  "@context": {
    "@vocab": "http://schema.nuget.org/catalog#",
    "nuget": "http://schema.nuget.org/schema#",
    "items": {
      "@id": "item",
      "@container": "@set"
    },
    "parent": {
      "@type": "@id"
    },
    "commitTimeStamp": {
      "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
    },
    "nuget:lastCreated": {
      "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
    },
    "nuget:lastEdited": {
      "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
    }
  }
}

Тут мы видим уже знакомые commitId, commitTimeStamp, count и items в корневом объекте с тем же смыслом, что и в предыдущем запросе, но только в контексте текущей страницы. items, соответственно, содержит данные о записях каталога, вместо страниц.

parent содержит ссылку на оглавление каталога.

@context можно игнорировать.

Элементы массива items содержат ссылку на собственно запись каталога, тип этой записи, время и GUID группы записей, идентификатор и версию пакета. Массив опять не отсортирован.

Группы записей

Как можно заметить в примере выше, первые два элемента items имеют одинаковые значения свойств commitTimeStamp и commitId. Это особенности работы процесса, который формирует каталог.

Процесс-генератор просыпается каждые несколько минут и проверяет свежие изменения в базе данных. Все найденные изменения записываются в одну страницу с одним commitId и commitTimeStamp. Если добавление прочитанных изменений в текущую страницу превысит некий порог, процесс создает новую страницу и помещает записи туда. Из-за этого, также, размер страницы непостоянен.

Вероятно есть ограничения на размер одного коммита, иначе в начале каталога была бы одна (или несколько) огромная страница, но это явно не так.

Еще одно наблюдение: в начале каталога страницы были размером примерно 550 записей, а в конце - больше 2700. Размер был изменен в 2022 году, чтобы замедлить рост количества страниц.

Типы записей

Документация описывает два типа записей каталога:

• nuget:PackageDetails - создается для всех новых пакетов, а также если произошло изменение метаданных пакета.

• nuget:PackageDelete - создается если пакет был удален. Удаление происходит в некоторых исключительных случаях, так что такие записи редки.

Несколько слов об изменениях метаданных пакета. До 2018 года загруженные пакеты можно было редактировать на сайте. Ввиду того, что метаданные находятся в пакете в .nuspec-файле, сайт переупаковывал пакет с новыми метаданными. В 2018 году была добавлена возможность авторам и репозиториям подписывать пакеты (подпись автора и репозитория могут присутствовать одновременно), что поставило крест на возможности редактировать пакеты после публикации и возможность была выпилена.

Соответственно, до 2018 года можно встретить несколько записей каталога для одной пары (идентификатор; версия) с разными метаданными. В таком случае записи, следующие за первой содержат обновленные метаданные пакета и актуальная версия метаданных находится в последней записи.

Документация описывает в каких случаях на сегодняшний день могут быть добавлены новые записи для тех же пакетов.

Запись PackageDetails

{
  "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.08.38.05/bclcontrib-abstract.spring.0.1.6.json",
  "@type": "nuget:PackageDetails",
  "commitId": "0502702c-6a9e-4eb6-93a6-e0798a3a0dc7",
  "commitTimeStamp": "2015-02-01T08:38:05.5456876Z",
  "nuget:id": "BclContrib-Abstract.Spring",
  "nuget:version": "0.1.6"
},

Содержит идентификатор и версию пакета, а так же ссылку на "лист" (catalog leaves, аналогично листовым узлам деревьев), который содержит больше информации: лист типа PackageDetails содержит данные из .nuspec-файла пакета: данные секции metadata из .nuspec-файла, информацию о зависимостях, список файлов, дату и время создания и публикации, размер и хеш пакета, информацию о коммите: GUID и время создания, такие же как на странице каталога и признак видимости пакета.

Запись PackageDelete

Выглядит так:

    {
      "@id": "https://api.nuget.org/v3/catalog0/data/2015.10.28.10.44.16/imagesbuttoncontrol.1.0.0.json",
      "@type": "nuget:PackageDelete",
      "commitId": "15d2ae77-d9e4-413e-a5da-f3ea3d5abeb1",
      "commitTimeStamp": "2015-10-28T10:44:16.9226556Z",
      "nuget:id": "ImagesButtonControl",
      "nuget:version": "1.0.0"
    },

Скачивать лист, на который эта запись ссылается бессмысленно, т.к. там записано то же самое.

"Особенности" парсинга

Уж не знаю, исходит ли это от самого формата JSON-LD, библиотеки, которая была использована для генерации этого JSON-LD или это просто баги, но в JSON-файлах размещенных на api.nuget.org некоторые свойства могут быть представлены либо строковым/числовым литералом, либо массивом.

Например, иногда в секции с зависимостями можно обнаружить такое:

{
  "@id": "https://api.nuget.org/v3/catalog0/data/2016.02.21.11.06.01/dingu.generic.repo.ef7.1.0.0-beta2.json#dependencygroup/.netplatform5.4/nuget.commandline",
  "@type": "PackageDependency",
  "id": "NuGet.CommandLine",
  "range": "[3.3.0, )"
},
{
  "@id": "https://api.nuget.org/v3/catalog0/data/2016.02.21.11.06.01/dingu.generic.repo.ef7.1.0.0-beta2.json#dependencygroup/.netplatform5.4/system.runtime",
  "@type": "PackageDependency",
  "id": "System.Runtime",
  "range": [
    "[4.0.10, )",
    "[4.0.21-beta-23516, )"
  ]
},

Свойство range может быть строкой, а может быть и массивом. Не велика проблема, просто имейте в виду, что такое может встретиться.

Качаем пакеты

Если нас интересуют только сами пакеты, листы каталога можно не качать. Для скачивания пакета нам достаточно знать идентификатор и версию пакета: в комментарии к ресурсу PackageBaseAddress/3.0.0 написано все, что нам надо знать, чтобы сконструировать ссылку для скачивания. Любители документации обнаружат, что там записано то же самое: приводим идентификатор и версию пакета в нижний регистр и добавляем к адресу ресурса согласно схеме:

https://api.nuget.org/v3-flatcontainer/{id-lower}/{version-lower}/{id-lower}.{version-lower}.nupkg

Так что все, что надо сделать: пробежать по записям каталога, сгенерировать ссылки на пакеты и скачать их. Надо иметь в ввиду, что для пакета может быть несколько записей и качать пакет стоит только один раз; пакет может быть удален, так что запрос к сконструированной ссылке вернет 404.

Т.к. записи всегда добавляются только в конец каталога, если надо скачивать пакеты по мере их загрузки, то достаточно запоминать commitId и проверять оглавление каталога раз в несколько минут на предмет изменения идентификатора последнего коммита, и когда он поменялся искать новые записи в последних страницах каталога. Ориентация по временным меткам позволит все быстро найти.

Если же целью стоит склонировать nuget.org с возможностью направить NuGet-клиент на ваш клон и восстанавливать с него пакеты, то нужно будет воссоздать ресурс RegistrationsBaseUrl/3.6.0. Для вычисления полного дерева пакетов клиент пользуется только этим им, так что этого должно быть достаточно. Статья и так уже длинная, так что это я оставлю как упражнение для читателя.

Сколько потребуется места - я не знаю. Последний раз я это пробовал несколько лет назад, и тогда 4-х терабайтного диска мне не хватило. Количество пакетов с тех пор увеличилось в несколько раз. Наверняка, в наши дни общий объем перевалил далеко за 10 ТБ. Дерзайте.