Delivery reference

The HTTP contract for retrieving compiled public modules, styles, source maps, assets and resolution documents, identical on a development server and on the CDN.

  • Availability: Experimental
  • Evidence: Read from source
  • Reference

Scope

Delivery is the read side of the CDN: GET requests that return prepared content. Its contract is @beyond-js/artifact-api, version 0.3.0, which the Packages Dev Server, Workspace environments and the CDN share. Each service adds its own origin, access rules and cache policy to the same identities, options, responses and errors.

One model, every environment

Every origin that implements the contract answers two kinds of request:

Request Answer
/m/<identity>/<family>/<subpath>?<options> One output of one public module: its JavaScript, its stylesheet or its source map, or one asset of the package. See URLs and identities.
/resolution.json?target=<t>&format=<f> and /importmap.json?target=<t>&format=<f> Which address delivers each public specifier, as a beyond-resolution/1 document and as a standard import map. See Resolution.

An origin is a Packages development service, a Workspace environment, or the base of one CDN release (/_r/<release number> on an application host). A consumer reads the resolution of its origin and then requests modules by the addresses it lists. What changes from one environment to another is only how that document is consumed: an import map in a browser, SystemJS, BEE Node in Node.js, --import-map in Deno. See Strategies per environment.

Version 0.3.0 extends 0.2.0 without changing the meaning of any existing request. It adds the two resolution routes, cross-origin reading of every public answer and error, and the service-level answers NOT_FOUND, UNAVAILABLE and INTERNAL. Version 0.2.0 had added the style, map and asset families, the errors of a retrieval-only and of a private service, the beyond-resolution/1 document and the two cache policies. The contract specifies these; it does not by itself prove that a given service implements them. The table below separates the two.

What each service serves

Capability Development server Published delivery
/modules/ format=esm, and format=system converted from the ES module; env=development&min=false with an inline map or none, and env=production&min=true from a module that builds a production conditional. Anything else is OPTION_UNSUPPORTED. Every option set that was prepared, esm and system, with an external map or none. A valid set that was not prepared is OUTPUT_NOT_AVAILABLE.
/styles/, /assets/ The stylesheet of a module, compiled on request like its code, and the files a module manifest or the package declares. A module without a stylesheet and an undeclared file are OUTPUT_NOT_AVAILABLE. The prepared styles and declared assets of a release
/maps/ OUTPUT_NOT_AVAILABLE: development maps are inline The prepared external maps of a release, subject to the application's source map policy
format=cjs, types=true, css=true OPTION_UNSUPPORTED OPTION_UNSUPPORTED: Packages generation never produces cjs, and declarations are not produced. Inline maps are not produced either.
Sources The workspace and its installed packages: npm unprefixed, another registry by its id, as the lockfile of the installation recorded it. Git, digest and a package installed from Git or from an archive are SOURCE_UNSUPPORTED. Every source: npm, other registries, Git repositories at a commit and archive digests
/resolution.json, /importmap.json Computed from the workspace on every request, no-store. Without a query, the Node ES module document. format=cjs is OPTION_UNSUPPORTED. The Node document lists the modules of the workspace only: a Node consumer resolves installed packages from its own installation. The documents a release stored for its targets, on the release base, and on an application host as the alias of the bound release. The shared delivery origin has none (NOT_FOUND).
A known module whose output is missing Builds from current sources; BUILD_FAILED if they do not compile Never builds: OUTPUT_NOT_AVAILABLE
Cache-Control of a success no-store public or private with max-age, and immutable while the bytes never change
Cross-origin reading Every answer, errors included Every public answer and error; restricted answers and refusals do not allow every origin
Service-level codes NOT_FOUND, INTERNAL NOT_FOUND, UNAVAILABLE, INTERNAL

The development column is the capability of the Packages development adapter as its repository documents it. The published column is CDN delivery as its repository documents it. Both implement version 0.3.0 as their repositories document it, and both are checked locally by the conformance of the contract; the CDN acceptance also compares one relative request on the two origins. Those are local runs, not hosted results. Nothing is deployed, and the examples of this section stay not executed until they are run against real origins.

Pages

  • URLs and identities — The path grammar of a compiled public module, the sources an identity names (registries, Git repositories and archive digests), and the rule that lets one relative URL work on every origin.
  • Request options — Every query option of a module, style or map request, with its values and defaults, and what happens when a value is invalid or not produced.
  • Outputs, styles and assets — The four resource families of a package version (modules, styles, maps and assets), how an import selects the JavaScript or the stylesheet of a public module, the shared stylesheet of a package, and how companions are advertised.
  • Strategies per environment — One resolution and delivery model, consumed four ways: browsers with native ES modules or SystemJS, Node.js through BEE Node and Deno through its import map, with the development updates that work in all of them and the local measurements behind the defaults.
  • Native ESM and import maps — Load published modules in a browser with native ES modules: the release shell with its inline import map and preloaded eager modules, or an import map you build from a resolution document.
  • SystemJS — The system loader mode of an application: System.register outputs loaded by SystemJS 6.15.1, which each release stores as its own loader.js, and how to load the same outputs from a page of your own.
  • Resolution — The beyond-resolution/1 document and the import map every origin answers at /resolution.json and /importmap.json, mapping each public specifier to an origin-relative URL, with scopes for coexisting versions.
  • Caching and releases — ETags and conditional requests, the development and published cache policies, and why an exact version URL can be cached as immutable.
  • Private access — How a member or a guest opens a private application: the exchange on the application's host, the host-only access cookie, short resource grants, the two access errors and what privacy cannot hide.
  • Errors — Every error code of the delivery contract with its status, meaning and the right reaction, including the miss that never starts a build and the service-level answers.
  • Retrieving the outputs of a release — What a release holds after preparation, the three places one output can be retrieved from, and the authorized management path that answers a member before the application has an address.