Doc system test

Dependency layering

How the file outputs of every template version in one dependency tree are laid on top of each other, and how a file clash is settled.

Meta block front matter of this doc
namespaces
  • durian.cloud/cyanprint/composition
  • durian.cloud/cyanprint/authoring
type
algorithm
code
  • sulfone.iridium/cyancoordinator/src/operations/composition/layerer.rs
  • sulfone.iridium/cyancoordinator/src/conflict_file_resolver/consensus.rs
  • sulfone.iridium/cyancoordinator/src/conflict_file_resolver/registry.rs
  • sulfone.iridium/cyancoordinator/src/operations/composition/operator.rs

Dependency layering turns the outputs of a flattened dependency tree into one file set. A path made by one layer is copied. A path made by two or more layers is a file clash: the layers vote for a conflict resolver, and if they all agree, that resolver merges the file; otherwise the last layer wins.

How it works

Input

  • A list of layer outputs, one per template version that ran, in run order.
  • For each layer, the conflict resolvers its template version declares, each with a config and file globs. Built by build_resolver_registry (operator.rs:121-148) from every template version in the tree.

Per path

ResolverAwareLayerer::layer_merge (layerer.rs:213-372) walks every path that any layer made (collect_all_paths, layerer.rs:101):

  1. Collect the variations: each layer that has this path gives its content and its resolver vote (get_file_variations, layerer.rs:121-150). A layer's vote is the first of its resolvers whose glob matches the path, or no resolver (registry.rs:35-49). A bad glob never matches (registry.rs:69-72).
  2. One variation: copy it. No resolver is called (layerer.rs:234-238).
  3. Two or more: count the votes with determine_consensus (consensus.rs:69-122):
VotesOutcomeRecorded as
all for the same resolver, same image, same configcall that resolverresolver
all for no resolverlast layer winslww_all_no_resolver
some for a resolver, some for nonelast layer winslww_no_consensus
for two different resolvers, or one resolver with two configslast layer winslww_ambiguous_resolver

"Same resolver" means same image reference, same tag, and the same config JSON (consensus.rs:10-33).

  1. Calling the resolver: every variation is sent, in layer order, as text with its origin (template version id and layer) to POST /proxy/resolver/{id}/api/resolve on the coordinator (layerer.rs:153-182). Its content becomes the file.
  2. Every clash is recorded as a file conflict entry (layerer.rs:184-209). The project lifecycle saves these into the state file under file_conflicts (state/models.rs:39).

Where this runs

  • Inside one dependency tree, after all its template versions ran (operator.rs:534-547). Resolvers come from every template version in the tree.
  • The same layerer is reused across stacked templates with a different resolver source. See template stacking.

Worked example

Layers from the flattening example: lint:2 (0), docker:7 (1), node-base:3 (2), web:5 (3). docker:7 and node-base:3 both declare resolver atomi/json-merger:1 with config {} on package.json. web:5 is a template group, so it makes no files.

PathMade byVotesResult
Dockerfiledocker:7none neededcopied
package.jsondocker:7, node-base:3json-merger, json-mergerjson-merger merges both
README.mdlint:2, node-base:3none, nonenode-base:3 wins (last)
.eslintrclint:2, node-base:3none, json-mergernode-base:3 wins; recorded as no consensus

If lint:2 also wanted package.json merged but declared json-merger with config {"arrays":"concat"}, the configs differ: the vote is ambiguous and node-base:3 wins.

Rules worth knowing

  • A resolver never sees a single variation. It is called only on a clash.
  • Content is sent as text. Bytes are turned into UTF-8 with lossy decoding (layerer.rs:116-118). Binary files are not safe to resolve.
  • "No resolver" is a vote. One layer without a resolver for the path blocks the merge for every layer (consensus.rs:3).
  • Layer numbers count every template version in the tree, including template groups that made no files (operator.rs:151-161). The output list holds only the layers that made files (operator.rs:244-257, 372, 494). Found while reading, not run: when a template group sits before a template with files in run order, the resolver votes are read for the wrong template version.

Why this way

  • A vote, not a choice by the last layer. Inferred: a resolver changes content that other templates wrote, so every template that wrote the file must opt in to the same merge. Otherwise the outcome stays the predictable "last layer wins".
  • Last layer wins as the fallback. It is the same rule the run order is built for: the root and the parents come last.