Mirrors/flux2
1
0
Fork 0
mirror of synced 2026-02-07 03:05:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

RFC: add design details artifact revision

Browse Source 
Signed-off-by: Hidde Beydals <hello@hidde.co>
This commit is contained in:
Hidde Beydals
2022-10-21 13:38:28 +00:00
parent 76c31c6303
commit f92d708051
1 changed files with 42 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
rfcs/XXXX-artifact-revision-format/README.md
View File

@@ -66,7 +66,7 @@ with supportive response from Core Maintainers.
- Allow configuration of [BLAKE3][] as an alternative to SHA for calculating
checksums. This has promising performance improvements over SHA-256, which
could allow for performance improvements in large scale environments.
- Allow compatability with SemVer name references which might contain an `@`
- Allow compatibility with SemVer name references which might contain an `@`
symbol already (e.g. `package@v1.0.0@sha256:...`, as opposed to OCI's
`tag:v1.0.0@sha256:...`).
@@ -237,9 +237,49 @@ API. This does not strike as a better alternative.
### Artifact Revision format
For an `Artifact`'s `Revision` which contains a checksum referring to an exact
revision, the checksum within the value MUST be appended with an alias for the
algorithm separated by `:` (e.g. `sha256:...`), further referred to as a
"digest". The algorithm alias and checksum of the digest MUST be lowercase and
alphanumeric.
For an `Artifact`'s `Revision` which contains a digest and a named pointer,
it MUST be prefixed with `@`, and appended at the end of the `Revision` value.
The named pointer MAY contain arbitrary characters, including but not limited
to `/` and `@`.
#### Format
#### Parsing the Revision field
```text
[ <named pointer> ] [ [ "@" ] <algo> ":" <checksum> ]
```
Where `[ ]` indicates an optional element, `" "` a literal string, and `< >`
a variable.
#### Parsing
When parsing the `Revision` field value of an `Artifact` to extract the digest,
the value after the last `@` is considered to be the digest. The remaining
value on the left side is considered to be the named pointer, which MAY contain
an additional `@` delimiter if applicable for the domain of the `Source`
implementation.
#### Truncation
When truncating the `Revision` field value of an `Artifact` to display in a
view with limited space, the `<checksum>` of the digest MAY be truncated to
7 or more characters. The `<algo>` of the digest MUST NOT be truncated.
In addition, a digest MUST always contain the full length checksum for the
algorithm.
#### Backwards compatibility
To allow backwards compatability in the notification-controller, Flux CLI and
other applicable components. The `Revision` new field value format could be
detected by the presence of the `@` or `:` characters. Falling back to their
current behaviour if not present, phasing out the old format in a future
release.
### Artifact Digest