Repositório de Listagem de Produtos do Publicador do Marketplace Adoptium®

Visão Geral

O Adoptium promove produtos listados no marketplace. Cada publicador gerencia uma localização contendo informações estruturadas sobre seus produtos. O Adoptium atualiza regularmente o marketplace com as informações do seu repositório de produtos. A localização refere-se a um "repositório" de recursos de dados. Tal repositório pode ser implementado como um sistema de arquivos simples, fluxo de dados criado dinamicamente, armazenamento com controle de versão, banco de dados ou outro recurso que responda a solicitações HTTP para URIs individuais com as informações descritas abaixo.

Na descrição e exemplos abaixo, nos referiremos a "arquivos" e "diretórios" como a implementação do repositório para simplificar.

Nomenclatura

Um repositório consiste em três tipos de arquivos, a saber, arquivos index, arquivos release e arquivos de assinatura.

Arquivos index: descrevem a localização dos arquivos release e arquivos index.
Arquivos release: contêm uma lista de produtos do marketplace.
Arquivos de assinatura: contêm uma assinatura digital associada a um arquivo Index ou Release.

Todos os arquivos são lidos assumindo codificação UTF-8.

Arquivos de Assinatura

Os arquivos de assinatura são usados para garantir que os dados do arquivo index e release foram recebidos corretamente e não foram modificados durante a transmissão. O agente do marketplace Adoptium lerá um arquivo e verificará a assinatura do arquivo associado. A assinatura do arquivo é armazenada em um arquivo com o mesmo nome do arquivo que está sendo assinado, com o sufixo .sha256.sign.

A assinatura deve ser um hash SHA-256 criptografado por RSA e codificado em Base64 de todo o conteúdo do seu arquivo. A assinatura será verificada usando a chave pública fornecida nas suas informações do publicador.

Há vários ferramentas e exemplos de código disponíveis para ajudar a produzir tais assinaturas.

Gerando, verificando e codificando uma assinatura usando OpenSSL

# Generate signature
openssl dgst -sha256 -sign private.pem -out index.json.sig index.json

# Verify
openssl dgst -sha256 -verify public.pem -signature index.json.sig index.json

#Base64 encode for publishing
cat index.json.sig | base64 -w 0 > index.json.sha256.sign

Repositório Simples de Listagem de Produtos

O repositório de listagem de produtos mais simples consiste em um arquivo index e um arquivo release, com assinaturas digitais associadas.

O arquivo index de nível superior deve aparecer na raiz da localização do repositório e deve ser chamado de index.json.

Aqui está um exemplo de repositório de listagem simples.

Example 1. Layout Simples de Repositório

/index.json (1)
/index.json.sha256.sign (2)
/release.json (3)
/release.json.sha256.sign (4)

1	Arquivo index principal do repositório de produtos.
2	Assinatura digital para o arquivo index.
3	Arquivo de listagem de releases do produto.
4	Assinatura digital para o arquivo de listagem de releases.

O arquivo index.json mais simples contém apenas uma referência a um único arquivo releases.json.

{
  "schema_version": "1.0.0",
  "releases": [
    "example.json"
  ]
}

Layout Estruturado do Repositório

O repositório de listagem de produtos pode ser estruturado com múltiplos arquivos index e release para atender às preferências de publicação de cada fornecedor. Por exemplo, um publicador pode optar por gerar um arquivo de releases por versão Java, por plataforma, por lançamento de calendário e assim por diante. O marketplace Adoptium começará no index.json raiz e percorrerá transitivamente cada arquivo index de forma exaustiva para encontrar todos os arquivos release.

Como exemplo mais complexo adicional, o repositório a seguir mostra uma estrutura de arquivo release organizada por versão Java e identificador de release.

Example 2. Layout Estruturado de Repositório

.
├── 17
│   ├── index.json
│   ├── index.json.sha256.sign
│   ├── jdk_17_0_1_12.json
│   ├── jdk_17_0_1_12.json.sha256.sign
│   ├── jdk_17_0_2_8.json
│   └── jdk_17_0_2_8.json.sha256.sign
├── 8
│   ├── index.json
│   ├── index.json.sha256.sign
│   ├── jdk8u312_b07.json
│   └── jdk8u312_b07.json.sha256.sign
├── index.json
└── index.json.sha256.sign

Neste repositório, o /index.json raiz conteria

{
  "schema_version": "1.0.0",
  "indexes": [
    "8/index.json",
    "17/index.json"
  ],
  "releases": [
  ]
}

e o 17/index.json conteria

{
  "schema_version": "1.0.0",
  "indexes": [
  ],
  "releases": [
    "jdk_17_0_1_12.json",
    "jdk_17_0_2_8.json"
  ]
}

Observe que, embora neste exemplo tenhamos criado um arquivo index por versão principal do Java e um arquivo release para cada lançamento Java, isso não é obrigatório. Um index pode conter múltiplos índices e releases, e um arquivo release pode conter múltiplos lançamentos de versão se desejado.

Tip

Cada referência de arquivo index e release é considerada relativa ao caminho do arquivo index, ou seja, se https://release.adoptium.net/repo/17/index.json contiver um release de jdk_17_0_2_8.json, o caminho https://release.adoptium.net/repo/17/jdk_17_0_2_8.json será examinado.

Arquivo Release

O arquivo release contém detalhes sobre seus produtos, incluindo a versão Java, arquitetura da máquina alvo, localização do download, localização dos resultados dos testes e muito mais. O nome do arquivo release não é relevante para o marketplace Adoptium além de ser referenciado a partir de um arquivo index conforme descrito acima.

O arquivo de listagem de releases dos seus produtos deve aderir ao esquema JSON do produto do marketplace, e o Adoptium fornece exemplos e código para ajudar a produzir dados de listagem de produtos no formato correto.

Os arquivos release ao vivo do Temurin estão disponíveis em nosso repositório público de dados do marketplace e servem como exemplo do que é esperado.

Processo de Leitura do Repositório e Atualização do Marketplace

O Adoptium normalmente recupera as informações de listagem de produtos a cada hora, embora esse período não seja garantido e possa variar. O Adoptium pode considerar seus cabeçalhos HTTP de resposta cache-control como max-age para orientar a frequência de busca da listagem de produtos. Por sua vez, a solicitação do Adoptium pode especificar uma solicitação condicional para o seu arquivo de listagem com cabeçalhos como If-Modified-Since para ajudar a reduzir a carga de trabalho.

Um arquivo de listagem de produtos será rejeitado se não aderir ao esquema ou se a assinatura não verificar o conteúdo com sucesso. Entraremos em contato com você se o arquivo de listagem falhar repetidamente nessas verificações de validação.

Quando lido com sucesso, as novas informações do marketplace substituem quaisquer informações anteriores mantidas para este fornecedor.

Em resumo, o processo de atualização prossegue da seguinte forma:

O atualizador obtém o index raiz e o verifica contra a assinatura.
Outros índices, se houver, são extraídos do index recursivamente até que todos os índices tenham sido lidos e verificados.
As localizações de todos os arquivos release são extraídas de todos os índices.
Cada arquivo release é obtido e validado contra a assinatura correspondente.
As informações do arquivo release são analisadas e validadas de acordo com o esquema
Todas as informações do produto são substituídas no marketplace para este fornecedor.