containerd/vendor/github.com/Microsoft/hcsshim/pkg/cimfs/doc.go

/*
This package provides simple go wrappers on top of the win32 CIMFS APIs.

Details about CimFS & related win32 APIs can be found here:
https://learn.microsoft.com/en-us/windows/win32/api/_cimfs/

Details about how CimFS is being used in containerd can be found here:
https://github.com/containerd/containerd/issues/8346

CIM types:
Currently we support 2 types of CIMs:
  - Standard/classic (for the lack of a better term) CIMs.
  - Block CIMs.

Standard CIMs store all the contents of a CIM in one or more region & objectID files. This
means a single CIM is made up of a `.cim` file, one or more region files and one or more
objectID files. All of these files MUST be present in the same directory in order for that
CIM to work. Block CIMs store all the data of a CIM in a single block device. A VHD can be
such a block device. For convenience CimFS also allows using a block formatted file as a
block device.

Standard CIMs can be created with the `func Create(imagePath string, oldFSName string,
newFSName string) (_ *CimFsWriter, err error)` function defined in this package, whereas
block CIMs can be created with the `func CreateBlockCIM(blockPath, oldName, newName
string, blockType BlockCIMType) (_ *CimFsWriter, err error)` function.

Verified CIMs:
A block CIM can also provide integrity checking (via a hash/Merkel tree,
similar to dm-verity on Linux). If a CIM is written and sealed, it generates a
root hash of all of its contents and shares it back with the client. Any
verified CIM can be mounted by passing a hash that we expect to be its root
hash. All read operations on such a mounted CIM will then validate that the
generated root hash matches with the one that was provided at mount time. If it
doesn't match the read fails. This allows us to guarantee that the CIM based
layered aren't being modified underneath us.

Forking & Merging CIMs:
In container world, CIMs are used for storing container image layers. Usually, one layer
is stored in one CIM. This means we need a way to combine multiple CIMs to create the
rootfs of a container. This can be achieved either by forking the CIMs or merging the
CIMs.

Forking CIMs:
Forking means every time a CIM is created for a non-base layer, we fork it off of a parent
layer CIM. This ensures that contents that are written to this CIM are merged with that of
parent layer CIMs at the time of CIM creation itself. When such a CIM is mounted we get a
combined view of the contents of this CIM as well as the parent CIM from which this CIM
was forked. However, this means that all the CIMs MUST be stored in the same directory in
order for forked CIMs to work. And every non-base layer CIM is dependent on all of its
parent layer CIMs.

Merging CIMs:
If we create one or more CIMs without forking them at the time of creation, we can still
merge those CIMs later to create a new special type of CIM called merged CIM. When
mounted, this merged CIM provides a view of the combined contents of all the layers that
were merged. The advantage of this approach is that each layer CIM (also referred to as
source CIMs in the context of merging CIMs) can be created & stored independent of its
parent CIMs. (Currently we only support merging block CIMs).

In order to create a merged CIM we need at least 2 non-forked block CIMs (we can not merge
forked & non-forked CIMs), these CIMs are also referred to as source CIMs. We first create
a new CIM (for storing the merge) via the `CreateBlockCIM` API, then call
`CimAddFsToMergedImage2` repeatedly to add the source CIMs one by one to the merged
CIM. Closing the handle on this new CIM commits it automatically. The order in which
source CIMs are added matters. A source CIM that was added before another source CIM takes
precedence when merging the CIM contents. Crating this merged CIM only combines the
metadata of all the source CIMs, however the actual data isn't copied to the merged
CIM. This is why when mounting the merged CIM, we still need to provide paths to the
source CIMs.

`CimMergeMountImage` is used to mount a merged CIM. This API expects an array of paths of
the merged CIM and all the source CIMs. Note that the array MUST include the merged CIM
path at the 0th index and all the source CIMs in the same order in which they were added
at the time of creation of the merged CIM. For example, if we merged CIMs 1.cim & 2.cim by
first adding 1.cim (via CimAddFsToMergedImage) and then adding 2.cim, then the array
should be [merged.cim, 1.cim, 2.cim]

Merged CIM specific APIs.

`CimTombstoneFile`: is used for creating a tombstone file in a CIM. Tombstone file is
similar to a whiteout file used in case of overlayFS. A tombstone's primary use case is
for merged CIMs. When multiple source CIMs are merged, a tombstone file/directory ensures
that any files with the same path in the lower layers (i.e source CIMs that are added
after the CIM that has a tombstone) do not show up in the mounted filesystem view.  For
example, imagine 1.cim has a file at path `foo/bar.txt` and 2.cim has a tombstone at path
`foo/bar.txt`. If a merged CIM is created by first adding 2.cim (via
CimAddFsToMergedImage) and then adding 1.cim and then when that merged CIM is mounted,
`foo/bar.txt` will not show up in the mounted filesystem.  A tombstone isn't required when
using forked CIMs, because we can just call `CimDeletePath` to remove a file from the
lower layers in that case. However, that doesn't work for merged CIMs since at the time of
writing one of the source CIMs, we can't delete files from other source CIMs.

`CimCreateMergeLink`: is used to create a file link that is resolved at the time of
merging CIMs. This is required if we want to create a hardlink in one source CIM that
points to a file in another source CIM. Such a hardlink can not be resolved at the time of
writing the source CIM. It can only be resolved at the time of merge. This API allows us
to create such cross layer hard links.
*/
package cimfs