Referencia de entrega

El contrato HTTP para obtener módulos públicos compilados, estilos, source maps, recursos estáticos y documentos de resolución, idéntico en un servidor de desarrollo y en el CDN.

  • Disponibilidad: Experimental
  • Evidencia: Leído del código fuente
  • Referencia

Alcance

La entrega es el lado de lectura del CDN: solicitudes GET que devuelven contenido preparado. Su contrato es @beyond-js/artifact-api, versión 0.3.0, que comparten el Dev Server de Packages, los entornos de Workspace y el CDN. Cada servicio agrega su propio origen, sus reglas de acceso y su política de caché a las mismas identidades, opciones, respuestas y errores.

Un modelo, todos los entornos

Todo origen que implementa el contrato responde dos tipos de solicitud:

Solicitud Respuesta
/m/<identity>/<family>/<subpath>?<options> Una salida de un módulo público: su JavaScript, su hoja de estilos o su source map, o un recurso estático del paquete. Consulta URLs e identidades.
/resolution.json?target=<t>&format=<f> y /importmap.json?target=<t>&format=<f> Qué dirección entrega cada especificador público, como documento beyond-resolution/1 y como import map estándar. Consulta Resolución.

Un origen es un servicio de desarrollo de Packages, un entorno de Workspace o la base de un release del CDN (/_r/<release number> en el host de una aplicación). Un consumidor lee la resolución de su origen y luego solicita los módulos por las direcciones que lista. Lo único que cambia de un entorno a otro es cómo se consume ese documento: un import map en un navegador, SystemJS, BEE Node en Node.js, --import-map en Deno. Consulta Estrategias por entorno.

La versión 0.3.0 amplía la 0.2.0 sin cambiar el significado de ninguna solicitud existente. Agrega las dos rutas de resolución, la lectura desde otros orígenes de toda respuesta y todo error públicos, y las respuestas de nivel de servicio NOT_FOUND, UNAVAILABLE e INTERNAL. La versión 0.2.0 había agregado las familias de estilos, mapas y recursos estáticos, los errores de un servicio que solo entrega y de un servicio privado, el documento beyond-resolution/1 y las dos políticas de caché. El contrato las especifica; por sí solo no demuestra que un servicio determinado las implemente. La tabla siguiente separa ambas cosas.

Qué sirve cada servicio

Capacidad Servidor de desarrollo Entrega publicada
/modules/ format=esm, y format=system convertido desde el módulo ES; env=development&min=false con mapa en línea o ninguno, y env=production&min=true de un módulo que compila un condicional de producción. Cualquier otra cosa es OPTION_UNSUPPORTED. Todos los conjuntos de opciones que se prepararon, esm y system, con mapa externo o ninguno. Un conjunto válido que no se preparó es OUTPUT_NOT_AVAILABLE.
/styles/, /assets/ La hoja de estilos de un módulo, compilada al solicitarla igual que su código, y los archivos que declara un manifiesto de módulo o el paquete. Un módulo sin hoja de estilos y un archivo sin declarar son OUTPUT_NOT_AVAILABLE. Los estilos y los recursos declarados que se prepararon para un release
/maps/ OUTPUT_NOT_AVAILABLE: los mapas de desarrollo van en línea Los mapas externos preparados de un release, según la política de source maps de la aplicación
format=cjs, types=true, css=true OPTION_UNSUPPORTED OPTION_UNSUPPORTED: la generación de Packages nunca produce cjs, y no se producen declaraciones. Tampoco se producen mapas en línea.
Fuentes El workspace y sus paquetes instalados: npm sin prefijo, otro registro por su id, tal como lo registró el lockfile de la instalación. Git, digest y un paquete instalado desde Git o desde un archivo comprimido son SOURCE_UNSUPPORTED. Todas las fuentes: npm, otros registros, repositorios Git en un commit y digests de archivos comprimidos
/resolution.json, /importmap.json Se calculan a partir del workspace en cada solicitud, no-store. Sin consulta, el documento de módulos ES para Node. format=cjs es OPTION_UNSUPPORTED. El documento de Node lista solo los módulos del workspace: un consumidor de Node resuelve los paquetes instalados desde su propia instalación. Los documentos que un release almacenó para sus targets, en la base del release, y en el host de una aplicación como alias del release vinculado. El origen de entrega compartido no tiene ninguno (NOT_FOUND).
Un módulo conocido cuya salida falta Compila desde las fuentes actuales; BUILD_FAILED si no compilan Nunca compila: OUTPUT_NOT_AVAILABLE
Cache-Control de una respuesta correcta no-store public o private con max-age, e immutable mientras los bytes no cambien nunca
Lectura desde otros orígenes Todas las respuestas, errores incluidos Toda respuesta y todo error públicos; las respuestas restringidas y los rechazos no permiten cualquier origen
Códigos de nivel de servicio NOT_FOUND, INTERNAL NOT_FOUND, UNAVAILABLE, INTERNAL

La columna de desarrollo es la capacidad del adaptador de desarrollo de Packages tal como la documenta su repositorio. La columna de publicación es la entrega del CDN tal como la documenta su repositorio. Ambos implementan la versión 0.3.0 según sus repositorios, y ambos se verifican localmente con la conformidad del contrato; la aceptación del CDN además compara una misma solicitud relativa en los dos orígenes. Son ejecuciones locales, no resultados alojados. No hay nada desplegado, y los ejemplos de esta sección siguen como not executed hasta que se ejecuten contra orígenes reales.

Páginas

  • URL e identidades — La gramática de la ruta de un módulo público compilado, las fuentes que nombra una identidad (registros, repositorios Git y digests de archivos comprimidos) y la regla que permite que una misma URL relativa funcione en cualquier origen.
  • Opciones de la solicitud — Todas las opciones de consulta de una solicitud de módulo, estilo o mapa, con sus valores y valores predeterminados, y qué ocurre cuando un valor no es válido o no se produce.
  • Salidas, estilos y recursos — Las cuatro familias de recursos de una versión de paquete (módulos, estilos, mapas y recursos estáticos), cómo un import selecciona el JavaScript o la hoja de estilos de un módulo público, la hoja de estilos compartida de un paquete y cómo se anuncian los recursos complementarios.
  • Estrategias por entorno — Un modelo de resolución y entrega, consumido de cuatro maneras: navegadores con módulos ES nativos o SystemJS, Node.js mediante BEE Node y Deno mediante su import map, con las actualizaciones de desarrollo que funcionan en todos ellos y las mediciones locales que respaldan los valores predeterminados.
  • ESM nativo e import maps — Carga módulos publicados en un navegador con módulos ES nativos: el shell del release con su import map en línea y los módulos inmediatos precargados, o un import map que construyes a partir de un documento de resolución.
  • SystemJS — El modo de carga system de una aplicación: salidas System.register cargadas por SystemJS 6.15.1, que cada release guarda como su propio loader.js, y cómo cargar las mismas salidas desde una página propia.
  • Resolución — El documento beyond-resolution/1 y el import map que todo origen responde en /resolution.json y /importmap.json, que asignan cada especificador público a una URL relativa al origen, con ámbitos para versiones que conviven.
  • Caché y releases — ETag y solicitudes condicionales, las políticas de caché de desarrollo y de publicación, y por qué una URL con versión exacta se puede almacenar como inmutable.
  • Acceso privado — Cómo abre una aplicación privada un miembro o un invitado: el canje en el host de la aplicación, la cookie de acceso limitada al host, los permisos de recurso de corta duración, los dos errores de acceso y lo que la privacidad no puede ocultar.
  • Errores — Todos los códigos de error del contrato de entrega con su estado, su significado y la reacción correcta, incluida la ausencia de salida que nunca inicia una compilación y las respuestas de nivel de servicio.
  • Recuperar las salidas de una versión publicada — Qué contiene una versión publicada después de la preparación, los tres lugares desde los que se puede recuperar una salida y la ruta autorizada de gestión que responde a un miembro antes de que la aplicación tenga dirección.