Doc system test

Processor output merge

How the merger container joins the output folders of one template's processors, and settles a path two processors both wrote.

Meta block front matter of this doc
namespaces
  • durian.cloud/cyanprint/coordinator
  • durian.cloud/cyanprint/authoring
type
algorithm
code
  • sulfone.boron/docker_executor/merger.go
  • sulfone.boron/server.go

Each processor of one template version writes into its own folder. The merger container walks those folders in processor order and copies each path to one merged folder. A path written by two or more processors is settled by the template's conflict resolvers: no match means the last processor wins, one match calls that resolver, two or more matches fail the build.

How it works

Merger.MergeFiles (merger.go:362-504), called by POST /merge/{session} in the merger container (server.go:790-816):

  1. Collect every file of every processor folder by relative path. The folder index is the file's layer; the processor version id is its origin.template (merger.go:371-406).
  2. Split paths into single and clashing ones (merger.go:408-417). Equal bytes still count as a clash.
  3. For each clash, match the path against every resolver of the template version with doublestar globs (merger.go:101-117):
    • none: copy the last processor's file (merger.go:428-439);
    • one: send all versions to that resolver; the reply path must equal the clash path; the result gets the last file's mode (merger.go:440-485);
    • more: fail with "Multiple resolvers match conflicting file" (merger.go:486-488).
  4. Copy single paths with their file mode (merger.go:491-502).

Worked example

Template version atomi/web:6 runs processors eta (layer 0) and prettier (layer 1). Both write package.json; only eta writes README.md. web:6 declares one resolver, atomi/json-merger on *.json.

PathWritersMatchesResult
README.mdetanot neededcopied
package.jsoneta, prettierjson-mergerjson-merger merges both

If web:6 also declared atomi/deep-merge on **/*.json, package.json would match two resolvers and the build would fail.

Why this way

  • Inferred: one author owns every processor and resolver of a template version, so two matching resolvers is a mistake in that template, and failing shows it at once. Across templates the CLI uses a vote instead; see conflict resolvers.