Registration and the pinned graph

What stage 1 does#

A registration resolves the complete package and version graph of the application and pins it. It reads provider metadata with the credentials configured service-side. It analyzes no code and downloads no archive. A provider that offers no metadata is recorded as an exception that required fetching a manifest.

Resolution handles peers with explicit contexts, optional and build-time policy, overrides and optional reuse of an earlier graph. Inputs it cannot satisfy produce a failed job with an actionable reason, never a partially pinned graph.

Operations#

Create a registration#

Targets are read from the application as they are when the request is accepted. The body adds what else to resolve; every member is optional:

Credentials of private providers never travel in this document. An owner or an administrator sets them once for the organization; see Registry providers.

The answer is 202 with the registration and its job:

{
  "registration": { "id": "reg_a1B2c3D4", "state": "resolving", "job": "job_Reg00001x" },
  "job": { "id": "job_Reg00001x", "kind": "registration", "state": "queued" }
}

A retry with the same Idempotency-Key answers the same pair. Admission can refuse with QUOTA_EXCEEDED or BUDGET_EXHAUSTED.

A registration is resolving, then pinned, failed or cancelled. Once pinned it carries graph, the id of its graph, and a snapshot of the targets that were resolved. A failed registration carries failure, typically RESOLUTION_FAILED: a missing version, conflicting constraints or an unsatisfied peer. Follow the job as described in Jobs.

Declaring dynamic imports#

Static tracing cannot follow an import() or a require() whose argument is not a literal. declared tells the analysis what such an import may load: by the specifier of the importing public module, the specifiers of the public modules it may reach.

{ "declared": { "@acme/shop/main": ["@acme/ui/chart", "@acme/ui/table"] } }

Analysis follows the declared modules as lazy references and reports the import as DYNAMIC_IMPORT_DECLARED. An import that stays undeclared fails the preparation with DYNAMIC_IMPORT_UNKNOWN. A declaration adds items to the inventory and never changes the inputs of the importer, so it does not invalidate outputs that already exist. Each list holds 1 to 200 distinct specifiers.

A module manifest may carry the same declaration. This member is for packages that do not, such as an ordinary npm package you cannot change.

The graph#

graphs.read answers a summary and the beyond-graph/1 document:

In the document, nodes are keyed by their source and carry the integrity, tarball, origin and visibility of the package: npm:<name>@<version> or <registry id>:<name>@<version> for a registry release, git:<host>/<owner>/<repo>@<commit> for a Git source and digest:<algorithm>-<hex> for an archive URL. A node read with a credential also records access, the evidence of its visibility. Edges record the kind of dependency, the requested range and the peer context.

Resolution pins every mutable reference. A Git branch or tag becomes the full commit it points to; an archive URL without an integrity fragment is downloaded once and pinned by its digest, recorded as an exception of the graph. Git sources are read over https from github.com, gitlab.com, bitbucket.org and the hosts of those kinds the operator declares; any other host is UNSUPPORTED_INPUT. Within one application, one name@version from two sources, such as a registry release and a Git fork that declares the same name and version, fails with UNSUPPORTED_INPUT. A graph that holds a node read with a credential has another digest than the same inputs gave before visibility was recorded per package.

Review a change before preparing it#

graphs.diff compares a graph with a base graph of the same application:

outputs is a prediction from compatibility keys, reported apart from measured build results. Use it to judge the size of a change, not to bill or to promise build time.

Update notices#

With notices enabled on the application, notices.list reports dependency updates that are available: the package, its current and available versions, and checked, the time of the last successful registry check.

A notice informs. It never changes a selection, prepares a release or activates anything. To adopt an update, create a new registration, review the diff, prepare a candidate and test it.

source: "unavailable" means the registry could not be asked. It is never evidence that everything is current.