Allow referring images in oci: (and oci-archive: ?) by manifest digest

[mtrmac]

See containers/podman#17308 for the previous discussion.

[mwopfner]

Currently the oci (and oci-archive) does not allow to refer an image by the manifest digest like docker transport does with the @digest syntax.

oci transport currently supports

• :tag references
• :@index references (implemented by Add reader/writer for oci-archive multi image support #1381, OCI-archive multi-manifest support POC #1677)

Proposal
Add support for digest by using one of (or another)

• @digest Same as used in docker transport. This would add another constrain on path names and may brake currently used image names. Depends on how widely @ is used in path names currently.
• :@digest Does not brake current behavior, because the name is currently already split by :
  Must be coordinated with :@index which should be possible, because index is a number >= 0 and a digest is of format algorithm:encoded (see: https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests)

[mwopfner]

Is there a currently a plan to include this in a further version? If nobody has time currently may I can implement the feature and open a pull request. Only thing that should be defined is the syntax for the digest.

[mtrmac]

It’s tracked here as a reasonable RFE; I’m not aware of anyone actively working on it, and a PR would definitely be welcome.

---

Yes, the syntax is the first thing which needs to be decided. Note that in the algorithm:encoded syntax linked, it is allowed for algorithm to be composed of digits only… So would the presence of the second : be the differentiator? Or possibly we could use some other prefix, not @ — that might be less ambiguous but probably much less intuitive.

[mwopfner]

My idea was to use a regex to separate between the tag, index and digest form. Something like:

tag: ^:([a-zA-Z0-9_][a-zA-Z0-9-_.]{0,127})$ (based on https://docs.docker.com/engine/reference/commandline/tag/)
index: ^:@([0-9]+)$
digest: ^:@([a-z0-9]+([+._-][a-z0-9]+)*:[a-zA-Z0-9=_-]+)$

The above regex also consider the specific constrains for tag and digest. I'm not sure if the restrictions should be enforced here or if another processing step does this and we only have to distinguish between the different cases.

[mwopfner]

@mtrmac what are your thoughts about using regex to separate between these cases? Is this the right way to go or do you have another suggestion?

[mtrmac]

Using a regex matcher, or not, is an implementation choice, secondary to choosing the syntax. *shrug*

The above proposes that foo:@0 is an index reference, but foo:@0:0 is a digest reference, differentiated by the presence of the second :, doesn’t it? Purely in abstract that looks a bit confusing, but in practice the algorithm part is going to be sha256 or something very similar, so this might well be the most practical design.

[mwopfner]

Yes, that is correct foo:@0 would be an index and foo:@0:0 is a digest reference. So the second : (plus some trailing characters) is the main divider.

What is the process to decide which syntax to use or should I just implement it and open a PR?

@mtrmac If I implement this function would a regex solution be accepted or are there other ways to do it which are preferred/used in the library.

[mtrmac]

Just open a PR, I think. No committee regularly meeting to present a proposal in triplicate to :)

Intuitively I’m a bit skeptical that using a regex is ideal — regexes are fairly costly, and it seems harder to me to be certain that the decision is unambiguous and has been comprehensively tested (we require *_transport.go to have detailed unit tests).