From 15662f643d9b0349cb02e20c9481af1e36081c7f Mon Sep 17 00:00:00 2001 From: Uwe Krueger Date: Thu, 26 Dec 2024 17:33:29 +0100 Subject: [PATCH] adapt ADR --- .../commands/ocmcmds/sources/add/cmd_test.go | 2 +- ...erene-hints.md => 0003-reference-hints.md} | 67 ++++++++++++------- 2 files changed, 45 insertions(+), 24 deletions(-) rename docs/adrs/{0003-referene-hints.md => 0003-reference-hints.md} (66%) diff --git a/cmds/ocm/commands/ocmcmds/sources/add/cmd_test.go b/cmds/ocm/commands/ocmcmds/sources/add/cmd_test.go index aa540557c..2a5d86377 100644 --- a/cmds/ocm/commands/ocmcmds/sources/add/cmd_test.go +++ b/cmds/ocm/commands/ocmcmds/sources/add/cmd_test.go @@ -8,7 +8,6 @@ import ( . "github.com/onsi/ginkgo/v2" . "github.com/onsi/gomega" - "ocm.software/ocm/api/utils/runtime" . "ocm.software/ocm/cmds/ocm/testhelper" "ocm.software/ocm/api/ocm/compdesc" @@ -18,6 +17,7 @@ import ( "ocm.software/ocm/api/utils/blobaccess" "ocm.software/ocm/api/utils/mime" common "ocm.software/ocm/api/utils/misc" + "ocm.software/ocm/api/utils/runtime" ) const ( diff --git a/docs/adrs/0003-referene-hints.md b/docs/adrs/0003-reference-hints.md similarity index 66% rename from docs/adrs/0003-referene-hints.md rename to docs/adrs/0003-reference-hints.md index b69f4e9b8..3c091778f 100644 --- a/docs/adrs/0003-referene-hints.md +++ b/docs/adrs/0003-reference-hints.md @@ -1,10 +1,15 @@ -# Architectural Decision Record: Rework of Referebce Hints +# ADR-0003 - Rework of Reference Hints +* Status: proposed +* Date: 2014-12-27 +* Authors: @mandelsoft +* Deciders: @fabianburth @jakobmoellerdev +* Reference Implementation: ### Meaning of Reference Hints During the transport of software artifacts referenced from external artifact repositories like OCI registries, they might be stored as blobs along with the component version (access method -`localBlob`. If those component versions are transported again into a repository landscape they +`localBlob`). If those component versions are transported again into a repository landscape they might be uploaded again to external repositories. To provide useful identities for storing those artifacts hints in external repositories, again, @@ -12,20 +17,20 @@ the original identity of the external artifact must be stored along with the loc ### Current Solution -The access method origibally used to refernce the exterbal artfact provides a reference hint, +The access method originally used to reference the external artifact provides a reference hint, which can later be used by the blob uploaders to reconstruct a useful identity. Therefore, the `localBlob` access method is able to keep track of this hint value. -The hint is just a string, which needs to be intepreted by the uploader. +The hint is just a string, which needs to be interpreted by the uploader. ### Problems with Current Solution -The assumprion behind the current solution is that the uploader will always upload the -artifactinto a similar repository, again. Therefore, there would be a one-to-one relation +The assumption behind the current solution is that the uploader will always upload the +artifact into a similar repository, again. Therefore, there would be a one-to-one relation between access method and uploader. Unfortunately this is not true in all cases: - There are access methods now (like`wget`), which are able to handle any kind of artifact blob - with different natural repositoty types and identity schemes. + with different natural repository types and identity schemes. - Therefore, - it can neither provide an implicit reference hint anymore - nor there is a one-to-one relation to a typed uploader anymore. @@ -33,15 +38,15 @@ Unfortunately this is not true in all cases: identity schemes. This problem is partly covered by allowing to specify a hint along with those access methods -similar to the `localBlob` access method. But this can only be a workarround, because -- the hint is not typed and potential target repositories might use diufferent identity schemes +similar to the `localBlob` access method. But this can only be a workaround, because +- the hint is not typed and potential target repositories might use different identity schemes - it is possible to store a single hint, only. ### Proposed Solution -Hints have to be typed, to allow uploaders to know what identites are provided and how the +Hints have to be typed, to allow uploaders to know what identities are provided and how the hint string has to be interpreted. Additionally, it must be possible to store -mulltiple hints for an artifact. +multiple hints for an artifact. To be compatible a serialization format is defined for a list of type hints, which maps such a list to a single string. @@ -51,33 +56,49 @@ a formal hint, by providing access to a set of string attributes. There are thre attributes: - `type` the formal type of the hint (may be empty to cover old component versions) The types are defined like the resource types. The following types are defined for now: - - `oci`: OCI identity given by the attribute `reference` with the cirrently used format + - `oci`: OCI identity given by the attribute `reference` with the currently used format - `maven`: Maven identity (GAV) given by the attribute `reference` with the currently used format - `npm`: Node package identity given by the attribute `reference` with the currently used format - `reference`: the standard attribute to hold a string representation for the identity. - `implicit`: Value `true` indicated an implicit hint (as used today) provided by an accessmethods. -New Hint types my use other attributes. +Typeless former hints are represented by the sole attribute `reference`. +New Hint types may use other attributes. -An access method can provide (and store) implicit hints as before. THose hints are indicated +#### Access Methods + +An access method can provide (and store) implicit hints as before. Those hints are indicated to be implicit. When composing an access method it is only allowed to store implicit hints. This is completely compatible to the current solution. -Additionally, multiplehints can be stored abd delivered. +Additionally, multiple hints can be stored abd delivered. To support any kind of hint for any scenario, the artifact metadata (resources and sources) is extended to store explicit hints, which will be part of the normalized form. This is done by an additional attribute `referenceHints`. It is a list of string maps holding the hint attributes (including the hint type). -Uploaders are called with the aggrgation of explicit (from metadata) and implicit (from +#### Uploaders + +Uploaders are called with the aggregation of explicit (from metadata) and implicit (from access methods) hints. Hereby, the explicit hints have precedence. If an uploader creates a local access specification, only implicit hints may be stored, here. There is a new composition option (`--refhint`) now for composing resources -and sources for the CLI. It accepts an attribute setting. Multiple such options starting with the `type`attribute are used to compose a single hint. +and sources for the CLI. It accepts an attribute setting. Multiple such options starting with the `type` attribute are used to compose a single hint. + +#### Inputs + +Inputs may provide explicit or implicit hints, now. All file based inputs now allow to specify implicit hints as used before. +The implicit hints (if not conflicting with explicit hints) are used to be stored in `localBlob` +access methods. The explicit hints are used to default the explicit artifact hints. + +Hints used in a component version must be unique. This check is extended to consider implicit +and explicit hints provided by inputs, access methods and artifact hints. + +Hints may either be specified as a list of string maps (canonical form) or as string using the serialized from. ### Hint Serialization Format @@ -86,8 +107,8 @@ In general a hint is serialized to the following string [<*type*>`::]`<*attribute*>`=`<*value*>{`,`<*attribute*>`=`<*value*>} -The type is not serilaized as attribute. The `implicit` attribute is never serialized is the string is stored in an access specification. -If no type is known the type part is omiited. +The type is not serialized as attribute, but as prefix separated by a `::`. The `implicit` attribute is never serialized if the string is stored in an access specification. +If no type is known the type part is omitted. A list of hints is serialized to @@ -95,10 +116,10 @@ A list of hints is serialized to <*hint*>{`;`<*hint*>} -*Attributes* names consist of alpha numeric chaŕacters, only. -If a *value*may not cotain a `::`. If it contains a `;`, `,` or `"` +*Attributes* names consist of alphanumeric characters, only. +A *value* may not contain a `::`. If it contains a `;`, `,` or `"` character it must be given in double quotes. -In the double quote form any `"` or `\` character has to be escaped by +In the double-quoted form any `"` or `\` character has to be escaped by a preceding `\` character. To be as compatible as possible, a single attribute hint with the attribute @@ -107,7 +128,7 @@ characters enforcing a quoted form. ### Incompatible Changes: -#### Componwnt Version Representation +#### Component Version Representation - The new library creates always typed hints for new elements. Old hints are left as they are. This means, that old versions of the OCM tooling