flatten

Overview ¶

Package flatten squashes an OCI image's layer stack into one plain tar stream. It is ossein's fork of go-containerregistry's mutate.Extract (adapted from pkg/v1/mutate, Copyright 2018 Google LLC, Apache License 2.0), kept in-tree because upstream's streaming flatten mishandles three things ossein depends on:

• opaque whiteouts (.wh..wh..opq) were ignored entirely, so files an image deleted by replacing a directory reappeared in the output;
• a hardlink whose target a higher layer deleted was emitted dangling (go-containerregistry#977) — the inode survives under the link's name on a real layered filesystem, so it is materialized as a regular file here, while the guest would have failed the boot on the dangling link;
• a hardlink was emitted wherever its layer put it, so a link could precede its target in the stream, and a link to a file a higher layer overwrote silently acquired the new content instead of the inode it actually shares.

Layers are walked TOP FIRST. That is not an optimization: the stream cannot retract an entry once written, and only in top-first order is the first occurrence of a name its winning version, making every decision final at the moment an entry is scanned. The price is that entries arrive in no parent-first order and a link's target may flow later — the pending and spool machinery below exists to pay exactly that price.

The output holds invariants the guest extractor relies on: entry names are normalized (no leading "/", "./" or ".." segments); every name appears at most once; a TypeLink entry always appears after the entry it links to; no whiteout markers of any kind survive.