Repositorio de listado de productos para editores del Marketplace de Adoptium®

Descripción general

Adoptium promueve los productos listados en el marketplace. Cada editor gestiona una ubicación que contiene información estructurada sobre sus productos. Adoptium actualiza regularmente el marketplace con la información de su listado de productos. La ubicación hace referencia a un "repositorio" de recursos de datos. Dicho repositorio puede implementarse como un sistema de archivos simple, un flujo de datos generado dinámicamente, un almacén con control de versiones, una base de datos u otra instalación que responda a solicitudes HTTP para URIs individuales con la información descrita a continuación.

En la descripción y los ejemplos que siguen nos referiremos a "archivos" y "directorios" como la implementación del repositorio para simplificar la explicación.

Nomenclatura

Un repositorio consta de tres tipos de archivos: archivos de índice, archivos de versión y archivos de firma.

Archivos de índice: describen la ubicación de los archivos de versión y de otros archivos de índice.
Archivos de versión: contienen una lista de productos del marketplace.
Archivos de firma: contienen una firma digital asociada a un archivo de índice o de versión.

Todos los archivos se leen con codificación UTF-8.

Archivos de firma

Los archivos de firma se utilizan para garantizar que los datos de los archivos de índice y de versión se han recibido correctamente y no han sido modificados en tránsito. El agente del marketplace de Adoptium leerá un archivo y verificará la firma asociada. La firma del archivo se almacena en un archivo con el mismo nombre que el archivo que firma, con el sufijo .sha256.sign.

La firma debe ser un hash SHA-256 cifrado con RSA y codificado en Base64 del contenido completo del archivo. La firma se verificará utilizando la clave pública proporcionada en su información del editor.

Existen varios herramientas y ejemplos de código disponibles para ayudar a generar dichas firmas.

Generación, verificación y codificación de una firma con 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

Repositorio de listado de productos simple

El repositorio de listado de productos más simple comprende un archivo de índice y un archivo de versión, con sus respectivas firmas digitales.

El archivo de índice de nivel superior debe aparecer en la raíz de la ubicación del repositorio y debe llamarse index.json.

A continuación se muestra un ejemplo de repositorio de listado simple.

Example 1. Estructura de repositorio simple

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

1	Archivo de índice principal del repositorio de productos.
2	Firma digital del archivo de índice.
3	Archivo de listado de versiones de productos.
4	Firma digital del archivo de listado de versiones.

El archivo index.json más simple contiene únicamente una referencia a un único archivo releases.json.

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

Estructura de repositorio organizada

El repositorio de listado de productos puede estructurarse con múltiples archivos de índice y de versión según las preferencias de publicación de cada proveedor. Por ejemplo, un editor puede optar por generar un archivo de versiones por versión de Java, por plataforma, por versión de calendario, etc. El marketplace de Adoptium comenzará en el index.json raíz y recorrerá de forma transitiva cada archivo de índice exhaustivamente para encontrar todos los archivos de versión.

Como ejemplo más complejo, el siguiente repositorio muestra una estructura de archivos de versión organizada por versión de Java e identificador de versión.

Example 2. Estructura de repositorio organizada

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

En este repositorio, el /index.json raíz contendría

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

y el 17/index.json contendría

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

Tenga en cuenta que, aunque en este ejemplo hemos creado un archivo de índice por versión principal de Java y un archivo de versión por cada lanzamiento de Java, esto no es un requisito. Un índice puede contener múltiples índices y versiones, y un archivo de versión puede contener múltiples versiones si se desea.

Tip

Cada referencia a un archivo de índice o de versión se considera relativa a la ruta del archivo de índice, es decir, si https://release.adoptium.net/repo/17/index.json contiene una versión jdk_17_0_2_8.json, se examinará la ruta https://release.adoptium.net/repo/17/jdk_17_0_2_8.json.

Archivo de versión

El archivo de versión contiene detalles sobre sus productos, incluyendo la versión de Java, la arquitectura de la máquina de destino, la ubicación de descarga, la ubicación de los resultados de pruebas y más. El nombre del archivo de versión no es relevante para el marketplace de Adoptium más allá de ser referenciado desde un archivo de índice como se describe anteriormente.

El listado del archivo de versión de sus productos debe cumplir con el esquema JSON de productos del marketplace, y Adoptium proporciona ejemplos y código para ayudar a generar los datos del listado de productos en el formato correcto.

Los archivos de versión activos de Temurin están disponibles en nuestro repositorio público marketplace data y sirven como ejemplo de lo que se espera.

Proceso de lectura del repositorio y actualización del marketplace

Adoptium generalmente recupera la información del listado de productos cada hora, aunque este período no está garantizado y puede variar. Adoptium puede tener en cuenta los encabezados HTTP cache-control de su respuesta, como max-age, para orientar la frecuencia de obtención del listado de productos. A su vez, la solicitud de Adoptium puede especificar una solicitud condicional para su archivo de listado con encabezados como If-Modified-Since para ayudar a reducir la carga de trabajo.

Un archivo de listado de productos será rechazado si no cumple con el esquema, o si la firma no verifica el contenido correctamente. Nos pondremos en contacto con usted si el archivo de listado falla repetidamente estas validaciones.

Una vez leído correctamente, la nueva información del marketplace reemplaza cualquier información anterior almacenada para este proveedor.

En resumen, el proceso de actualización es el siguiente:

El actualizador obtiene el índice raíz y lo verifica contra la firma.
Los índices adicionales, si los hay, se extraen del índice de forma recursiva hasta que todos los índices han sido leídos y verificados.
Las ubicaciones de todos los archivos de versión se extraen de todos los índices.
Cada archivo de versión se obtiene y se valida contra la firma correspondiente.
La información del archivo de versión se analiza y valida según el esquema.
Toda la información de productos se reemplaza en el marketplace para este proveedor.