Dépôt de liste de produits pour les éditeurs de la Marketplace Adoptium®

Vue d’ensemble

Adoptium promeut les produits listés sur la marketplace. Chaque éditeur gère un emplacement contenant des informations structurées sur ses produits. Adoptium met régulièrement à jour la marketplace avec les informations provenant de votre liste de produits. L’emplacement fait référence à un « dépôt » de ressources de données. Un tel dépôt peut être implémenté sous forme de système de fichiers simple, de flux de données créé dynamiquement, de magasin sous contrôle de version, de base de données ou d’autre dispositif qui répond aux requêtes HTTP pour des URI individuels avec les informations décrites ci-dessous.

Dans la description et les exemples ci-dessous, nous ferons référence aux « fichiers » et aux « répertoires » comme implémentation du dépôt pour des raisons de simplicité.

Nomenclature

Un dépôt se compose de trois types de fichiers : les fichiers index, les fichiers release et les fichiers signature.

Fichiers index : décrivent l’emplacement des fichiers release et des fichiers index.
Fichiers release : contiennent une liste de produits de la marketplace.
Fichiers signature : contiennent une signature numérique associée à un fichier index ou release.

Tous les fichiers sont lus en supposant un encodage UTF-8.

Fichiers de signature

Les fichiers de signature sont utilisés pour s’assurer que les données des fichiers index et release ont été reçues correctement et n’ont pas été modifiées en transit. L’agent de la marketplace Adoptium lira un fichier et vérifiera la signature associée. La signature du fichier est stockée dans un fichier portant le même nom que le fichier signé, avec le suffixe .sha256.sign.

La signature doit être un hachage SHA-256 chiffré RSA et encodé en Base64 du contenu entier de votre fichier. La signature sera vérifiée à l’aide de la clé publique fournie dans vos informations d’éditeur.

Un certain nombre de outils et d' exemples de code sont disponibles pour aider à produire de telles signatures.

Générer, vérifier et encoder une signature avec 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

Dépôt de liste de produits simple

Le dépôt de liste de produits le plus simple comprend un fichier index et un fichier release, avec leurs signatures numériques associées.

Le fichier index de premier niveau doit apparaître à la racine de l’emplacement du dépôt et doit être nommé index.json.

Voici un exemple simple de dépôt de liste.

Example 1. Disposition simple du dépôt

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

1	Fichier index principal du dépôt de produits.
2	Signature numérique pour le fichier index.
3	Fichier de liste de versions de produits.
4	Signature numérique pour le fichier de liste de versions.

Le fichier index.json le plus simple ne contient qu’une référence à un seul fichier releases.json.

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

Disposition structurée du dépôt

Le dépôt de liste de produits peut être structuré avec plusieurs fichiers index et fichiers release pour s’adapter aux préférences de publication de chaque fournisseur. Par exemple, un éditeur peut choisir de générer un fichier releases par version Java, par plateforme, par version calendaire, etc. La marketplace Adoptium commencera par le index.json racine et parcourra transitivement chaque fichier index de manière exhaustive pour trouver tous les fichiers release.

À titre d’exemple plus complexe, le dépôt suivant montre une structure de fichiers release organisée par version Java et identifiant de version.

Example 2. Disposition structurée du dépôt

.
├── 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

Dans ce dépôt, le /index.json racine contiendrait

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

et le 17/index.json contiendrait

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

Notez que bien que dans cet exemple nous ayons créé un fichier index par version majeure de Java et un fichier release pour chaque version Java, cela n’est pas une exigence. Un index peut contenir plusieurs index et releases, et un fichier release peut contenir plusieurs versions si souhaité.

Tip

Chaque référence à un fichier index ou release est considérée comme relative au chemin du fichier index, c’est-à-dire que si https://release.adoptium.net/repo/17/index.json contenait une release de jdk_17_0_2_8.json, le chemin https://release.adoptium.net/repo/17/jdk_17_0_2_8.json sera examiné.

Fichier release

Le fichier release contient les détails de vos produits, notamment la version Java, l’architecture de la machine cible, l’emplacement de téléchargement, l’emplacement des résultats de tests, et bien plus encore. Le nom du fichier release n’est pas pertinent pour la marketplace Adoptium au-delà du fait d’être référencé depuis un fichier index comme décrit ci-dessus.

La liste de vos produits dans le fichier release doit être conforme au schéma JSON des produits de la marketplace, et Adoptium fournit des exemples et du code pour aider à produire des données de liste de produits dans le format correct.

Les fichiers release Temurin en production sont disponibles dans notre dépôt de données de la marketplace public et constituent un exemple de ce qui est attendu.

Processus de lecture du dépôt et de mise à jour de la marketplace

Adoptium récupère généralement les informations de liste de produits toutes les heures, bien que ce délai ne soit pas garanti et puisse varier. Adoptium peut prendre en compte vos en-têtes HTTP de cache-control tels que max-age pour guider la fréquence de récupération de la liste de produits. En retour, la requête Adoptium peut spécifier une requête conditionnelle pour votre fichier de liste avec des en-têtes tels que If-Modified-Since pour aider à réduire la charge de travail.

Un fichier de liste de produits sera rejeté s’il n’est pas conforme au schéma, ou si la signature ne vérifie pas correctement le contenu. Nous vous contacterons si le fichier de liste échoue à plusieurs reprises à ces vérifications de validation.

Une fois lu avec succès, les nouvelles informations de la marketplace remplacent toute information précédemment détenue pour ce fournisseur.

En résumé, le processus de mise à jour se déroule comme suit :

Le programme de mise à jour récupère l’index racine et le vérifie par rapport à la signature.
Les index supplémentaires, le cas échéant, sont extraits de l’index de manière récursive jusqu’à ce que tous les index aient été lus et vérifiés.
L’emplacement de tous les fichiers release est extrait de tous les index.
Chaque fichier release est récupéré et validé par rapport à la signature correspondante.
Les informations du fichier release sont analysées et validées selon le schéma.
Toutes les informations sur les produits sont remplacées dans la marketplace pour ce fournisseur.