Guia de implementação Java do NuGet Server
Em alguns casos, convém implementar seu próprio feed de pacotes do NuGet. Há muitas implementações existentes que permitem que você hospede seu próprio feed de uma maneira variada, mas o protocolo entre o software cliente do NuGet oficial e um feed de pacote está documentado, permitindo que você crie sua própria implementação de feed do zero.
O protocolo evolui com o tempo e este guia é voltado para aqueles que desejam ou já implementaram um servidor de pacotes do NuGet.
Desde o lançamento inicial do protocolo NuGet V3 em 2015, o NuGet evoluiu para fornecer aos desenvolvedores uma experiência mais rica, e isso requer que os repositórios de pacotes trabalhem mais para fornecer o valor adicional aos consumidores de pacotes, além de simplesmente exigir metadados de pacotes hospedados e retornar os metadados de várias formas. Por exemplo, os pontos de extremidade de metadados de pesquisa e pacote contêm mais do que apenas metadados encontrados no arquivo nuspec do nupkg.
Observe que este guia é focado no protocolo NuGet V3, uma vez que o protocolo V2 é essencialmente não documentado e, desde 2015, o protocolo recomendado para comunicação entre cliente e servidor do NuGet é o protocolo V3. Para obter mais informações, leia sobre o Controle de versão do protocolo.
Cronologia
Para ajudar os autores de repositórios do NuGet existentes a manterem-se atualizados com os recursos mais recentes do NuGet, aqui está a cronologia dos recursos relevantes mencionados no restante do documento.
| Year | Recurso |
|---|---|
| 2013 | Uma postagem no blog explicando como gerenciar proprietários de pacotes em nuget.org esclareceu que os proprietários mostrados no site são as contas que têm permissão para carregar novas versões e, portanto, os metadados owners no pacote são ignorados |
| 2017 | verified adicionado às respostas SearchQueryService. |
| Suporte de controle de versão semântico 2.0.0 | |
| 2018 | Licenças incorporadas |
| 2019 | Ícones incorporados |
Depreciação do pacote em RegistrationBaseUrl (recurso de metadados do pacote) |
|
| 2020 | Informações de vulnerabilidade do pacote em RegistrationsBaseUrl (recurso de metadados do pacote) |
Adicionar parâmetros de consulta packageTypes a uma solicitação SearchQueryService |
|
| 2021 | Leia-me incorporado |
| 2023 | Pré-autenticar solicitações autenticadas Recurso VulnerabilityInfo |
Campo proprietário
Considere dois dos campos do arquivo de manifesto do pacote (.nuspec), <authors> e <owners>.
Os autores de pacotes que estão empacotando conteúdo de terceiros geralmente colocam o nome de terceiros no campo <authors>.
O campo <owners> destinava-se a indicar quem publicou o pacote em um repositório e, portanto, quem deve ser contatado em caso de problemas de empacotamento ou perguntas.
Isso foi explicado em uma postagem no blog de 2013, portanto, o campo <owners> é considerado obsoleto no arquivo .nuspec.
Se o manifesto do pacote contiver esses metadados, ele deverá ser ignorado.
Não retorne o valor do campo <owners> do arquivo .nuspec na propriedade owners no recurso de pesquisa ou na resposta JSON do recurso de metadados do pacote.
Se o repositório tiver permissões por pacote, é recomendável relatar as contas que têm permissões para publicar novas versões nos metadados owner para respostas JSON de recursos de metadados de pesquisa e pacote.
Campo de resposta de pesquisa verified
A interface do usuário do Gerenciador de Pacotes do Visual Studio mostra uma marca de seleção azul ao lado de pacotes nos resultados do serviço de pesquisa, quando um novo campo verified é definido como true.
O NuGet.org usa isso com dados de prefixo de pacote (dados do lado do servidor, não parte da API do NuGet), para que essa marca de seleção só seja mostrada aos clientes quando a conta proprietária do pacote carregar o pacote.
Por exemplo, qualquer pacote com prefixo microsoft.* é verificado somente quando o pacote pertence à conta da Microsoft em nuget.org. Qualquer pessoa que carregou um pacote com ID de pacote começando com microsoft. antes que os prefixos reservados fossem implementados, não terá essa marca de seleção verificada.
O NuGet.org também permite que os prefixos não sejam exclusivos, para que qualquer pessoa possa carregar um pacote em Contoso.ToolWithPlugins.Community.*, mas não obtenha uma marca de seleção verificada.
Suporte de Controle de versão semântico 2.0.0
O NuGet oferece suporte a um híbrido entre System.Version e a Versão semântica, mas o suporte para a Versão semântica 2.0.0 foi adicionado em 2017.
Portanto, os recursos da API do NuGet que retornam versões para versões de cliente inferiores à 3.6.0 não devem retornar pacotes que usam recursos semânticos 2.0.0 que são incompatíveis com o Controle de versão semântico 1.0.0.
As diferenças mais importantes entre as duas versões são os rótulos de pré-lançamento e a cadeia de caracteres de metadados.
A especificação do Controle de versão semântico 1.0.0 fornece [0-9A-Za-z-] como uma cadeia de caracteres de expressão regular de exemplo para os únicos caracteres permitidos como parte do rótulo de pré-lançamento e não oferece suporte a cadeia de caracteres de metadados.
A especificação do Controle de versão semântico 2.0.0 permite que identificadores de pré-lançamento sejam separados por caracteres . (e proíbe que um identificador numérico tenha um zero à esquerda) e, adicionalmente, permite que metadados de compilação sejam adicionados após um +.
No recurso de metadados do pacote (RegistrationsBaseUrl), as versões do recurso abaixo da 3.6.0 só devem retornar pacotes que estejam em conformidade com o System.Version do .NET ou o Controle de versão semântico 1.0.0.
Isso significa que os pacotes cujas versões são compatíveis apenas com o Controle de versão semântico 2.0.0 são invisíveis para essas versões de cliente.
Da mesma forma, o serviço de consulta de pesquisa (SearchQueryService) e o serviço de preenchimento automático (SearchAutocompleteService) adicionaram parâmetros de consulta &semVerLevel={version}.
Quando semVerLevel estiver faltando, assuma o valor 1.0.0.
Como o recurso de metadados do pacote, os pacotes cuja versão é compatível apenas com o Controle de versão semântico 2.0.0 não devem ser retornados quando o valor semVerLevel estiver abaixo de 2.0.0.
Arquivos incorporados
Ícones de pacote, licença e arquivos leia-me podem ser (e é recomendado que sejam) incorporados no pacote.
Esses arquivos precisam de um ponto de extremidade de URL, extraído e colocado em um servidor de arquivos estático, ou uma URL que extraia dinamicamente os arquivos do .nupkg mediante solicitação, para que eles possam ser visualizados sem baixar o nupkg inteiro.
Se o repositório de pacotes fornecer navegação e visualização de detalhes do pacote, você poderá usar as URLs para mostrar aos clientes o conteúdo incorporado em seu site.
Finalmente, o recurso de metadados do pacote e o recurso de pesquisa devem conter a URL hospedada nas propriedades iconUrl, licenseUrl e/ou readmeUrl da resposta JSON.
Os pacotes (arquivos .nupkg) não devem ser modificados, pois os recursos do cliente (arquivos de bloqueio e pacotes assinados) detectarão modificações conforme o pacote tiver sido violado.
Observe que a licença pode ser uma expressão SPDX ou um arquivo incorporado (mas não ambos).
Os pacotes que usam uma expressão de licença, quando representados nos resultados de pesquisa e metadados do pacote, podem ter licenseUrl definido como a expressão de licença, codificada por URL e anexada ao final de https://licenses.nuget.org/.
Por exemplo, https://licenses.nuget.org/Apache-2.0.
A equipe do servidor do NuGet.org tem documentação adicional em licenses.nuget.org.
Dados conhecidos de vulnerabilidade e depreciação
Recurso de metadados do pacote (RegistrationsBaseUrl)
O Recurso de Metadados do Pacote pode conter informações sobre depreciação e vulnerabilidade. Isso permite que os clientes que navegam em pacotes na Interface do Usuário do Gerenciador de Pacotes do Visual Studio, ou equivalente em outros IDEs, sejam notificados sobre problemas importantes de segurança ou manutenção.
Se o repositório de pacotes for “up-sourcing” de outro repositório, para espelhar pacotes em seu próprio feed, recomendamos verificar periodicamente a fonte original para ver se há dados de depreciação ou vulnerabilidade e espelhar esses metadados em seu próprio repositório.
Se o repositório de pacotes estiver fazendo up-sourcing do nuget.org especificamente, mantendo o estado da última vez que você verificou (um “cursor”), você poderá usar o recurso Catalog para verificar com eficiência se há atualizações de pacotes para pacotes que você está espelhando, sem precisar baixar muitos arquivos JSON de metadados de pacote do feed de upstream.
Há um guia sobre como usar o recurso de catálogo com código de exemplo que pode ajudá-lo a começar.
Banco de dados de vulnerabilidades conhecidas (VulnerabilityInfo)
Para fornecer verificação de vulnerabilidade de alto desempenho durante a restauração de pacotes, o NuGet baixa a lista completa de vulnerabilidades conhecidas do recurso VulnerabilityInfo.
O Nuget.org fornece dados de vulnerabilidade para todos os avisos revisados do GitHub do banco de dados de avisos do GitHub, que inclui pacotes que não estão hospedados em nuget.org.
Se o repositório de pacotes estiver hospedando pacotes primários e você quiser fornecer informações sobre vulnerabilidades aos clientes usando seu próprio feed, mas ainda não tiver nenhuma vulnerabilidade de pacote divulgada, forneça um índice de vulnerabilidade com uma ou mais páginas de vulnerabilidade cujo conteúdo seja uma matriz JSON vazia ([]).
Se o repositório de pacotes for destinado a ser usado por aplicativos como repositório padrão (em vez de nuget.org), você poderá usar os dados de vulnerabilidade do nuget.org.
Uma opção é usar a URL do índice de vulnerabilidade do nuget.org em seu índice de serviço.
Outra opção é verificar periodicamente o índice do nuget.org VulnerabilityInfo e baixar todas as páginas alteradas para espelhar localmente.
Consulta de pesquisa packageTypes
A CLI do .NET permite pesquisar pacotes de ferramentas .NET com o comando dotnet tool search.
Isso é implementado adicionando um parâmetro de consulta &packageTypes={value} ao recurso de consulta de pesquisa, que lê valores do campo <packageTypes> de arquivo .nuspec do pacote.
Estrutura de URL para feeds autenticados
Conforme descrito na visão geral da API do NuGet, a URL inicial para toda a comunicação com o servidor do NuGet é o índice de serviço.
Este documento contém as URLs de todos os outros recursos que os clientes do NuGet consultarão.
A partir do NuGet 6.7 (Visual Studio & MSBuild 17.7 e SDK do .NET 7.0.400), o NuGet usa HttpClientHandler.PreAuthenticate do .NET, que só evita solicitações HTTP anônimas quando URLs subsequentes estão no mesmo diretório virtual, ou um subdiretório, de uma URL que foi autenticada anteriormente.
Isso reduzirá drasticamente o número de solicitações HTTP não autenticadas enviadas ao servidor e, portanto, reduzirá a carga de trabalho do servidor.
Estes são alguns exemplos:
| URL | Vai preautenticar? |
|---|---|
| https://pkgs.contoso.com/nuget/v3/feed/index.json | N/A, este é o índice de serviço. |
| https://pkgs.contoso.com/nuget/v3/search | Não, não no mesmo ou no subdiretório do índice de serviço. |
| https://search.pkgs.contoso.com/nuget/v3/feed/ | Não, não no mesmo nome do host que o índice de serviço. |
| https://pkgs.contoso.com/nuget/v3/feed/search | Sim, no mesmo diretório que o índice de serviço. |
| https://pkgs.contoso.com/nuget/v3/registration/ | Não, não em um subdiretório do índice de serviço. |
| https://pkgs.contoso.com/nuget/v3/feed/registration/ | Sim, em um subdiretório do índice de serviço. |
| https://pkgs.contoso.com/nuget/v3/{guid}/registration/ | Consulte abaixo |
No último exemplo, o servidor pode ter um nome canônico (neste exemplo, um guid) e ter um ou mais aliases.
Se a solicitação de índice de serviço foi autenticada em uma URL não canônica (o nome “amigável”, em nosso feed de exemplo), então não, nenhuma solicitação para recursos sob a URL canônica corresponderá às regras do HttpClientHandler para PreAuthenticate.
No entanto, se a URL não canônica for um redirecionamento HTTP para a URL canônica, https://pkgs.contoso.com/nuget/v3/{guid}/index.json, essa URL será usada no cache de credenciais do HttpClientHandler.
Nesse caso, cada solicitação ao índice de serviço terá latência adicional, devido ao redirecionamento.
Embora a API V3 do NuGet tenha sido projetada para funcionar em um servidor de arquivos estático, o recurso de pesquisa é a exceção que sempre requer um serviço Web dinâmico para processar solicitações.
Se você deseja hospedar a pesquisa, ou mesmo qualquer outro recurso da API do NuGet, em servidores diferentes, a fim de se beneficiar da PreAuthenticatedo HttpClientHandler, você precisará usar um proxy reverso para garantir que todas as URLs voltadas para o cliente no índice de serviço atendam à regra “no mesmo ou no subdiretório”.