From b251fe1bd020ca034382701e57b933a42c939770 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 6 Sep 2017 16:48:53 -0700 Subject: [PATCH] cas-template: Define and register the oci-cas-template-v1 protocol And allow casEngines in the ref-engine discovery response, supporting folks who want to defer to a ref-engine that is hard/impossible to update (e.g. index JSON on someone else's server for a oci-index-template-v1 ref engine) but who still want to provide their own CAS engine hints. --- cas-engine-protocols.md | 14 ++++++++++++++ cas-template.md | 39 +++++++++++++++++++++++++++++++++++++++ index-template.md | 18 ++++++++++++++++-- ref-engine-discovery.md | 31 ++++++++++++++++++++++++++++++- 4 files changed, 99 insertions(+), 3 deletions(-) create mode 100644 cas-engine-protocols.md create mode 100644 cas-template.md diff --git a/cas-engine-protocols.md b/cas-engine-protocols.md new file mode 100644 index 0000000..91d6b93 --- /dev/null +++ b/cas-engine-protocols.md @@ -0,0 +1,14 @@ +## CAS-engine protocols + +There are many possible [CAS][] engine protocols. +Having identifiers for the protocols provides a standardized way to share structured connection information. +Consumers can then prefer CAS engines which implement their favorite protocol and use the appropriate API to connect to them. + +This section registers known protocol identifiers and maps them to their specification. +Anyone may submit new CAS-engine protocol identifiers for registration. + +| Protocol identifier | Specification | +|-------------------------|---------------------------------------------------------| +| `oci-cas-template-v1` | [OCI CAS template protocol, version 1](cas-template.md) | + +[CAS]: https://en.wikipedia.org/wiki/Content-addressable_storage diff --git a/cas-template.md b/cas-template.md new file mode 100644 index 0000000..ca15775 --- /dev/null +++ b/cas-template.md @@ -0,0 +1,39 @@ +# OCI CAS Template Protocol + +This is version 1 of this specification. + +The CAS-template protocol is configured via a single [URI Template][rfc6570]. +When configured via a [`casEngines` entry](ref-engine-discovery.md#ref-engines-objects), the `uri` property MUST be set, and its value is the URI Template. + +For a given blob digest, consumers MUST provide at least the following variables: + +* `digest`, matching `digest` in the [`digest` rule][digest]. +* `algorithm`, matching `algorithm` in the `digest` rule. +* `encoded`, matching `encoded` in the `digest` rule. + +and expand the URI Template as defined in [RFC 6570 section 3][rfc6570-s3]. + +## Example + +An example [`casEngines` entry](ref-engine-discovery.md#ref-engines-objects) using the [registered `oci-cas-template-v1` protocol identifier](cas-engine-protocols.md) is: + +```json +{ + "protocol": "oci-cas-template-v1", + "uri": "https://a.example.com/cas/{algorithm}/{encoded:2}/{encoded}" +} +``` + +A digest like `sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855` matches [`digest`][digest] with: + +* `sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855` as `digest`, +* `sha256` as `algorithm`, and +* `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855` as `encoded` + +so the expanded URI is: + + https://a.example.com/cas/sha256/e3/e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 + +[digest]: https://github.com/opencontainers/image-spec/blob/v1.0.0/descriptor.md#digests +[rfc6570]: https://tools.ietf.org/html/rfc6570 +[rfc6570-s3]: https://tools.ietf.org/html/rfc6570#section-3 diff --git a/index-template.md b/index-template.md index cd6a223..c91cf0b 100644 --- a/index-template.md +++ b/index-template.md @@ -52,7 +52,13 @@ $ curl -H 'Accept: application/vnd.oci.image.index.v1+json' https://a.b.example. }, "annotations": { "org.opencontainers.image.ref.name": "1.0" - } + }, + "casEngines": [ + { + "protocol": "oci-cas-template-v1", + "uri": "https://a.example.com/cas/{algorithm}/{encoded:2}/{encoded}" + } + ] }, { "mediaType": "application/xml", @@ -61,12 +67,20 @@ $ curl -H 'Accept: application/vnd.oci.image.index.v1+json' https://a.b.example. "annotations": { "org.freedesktop.specifications.metainfo.version": "1.0", "org.freedesktop.specifications.metainfo.type": "AppStream" - } + }, + "casEngines": [ + { + "protocol": "oci-cas-template-v1", + "uri": "https://b.example.com/cas/{algorithm}/{encoded}" + } + ] } ] } ``` +The [`oci-cas-template-v1` protocol](cas-template.md) is [registered](cas-engine-protocols.md). + Deciding whether to look for `1.0` (the `fragment`) or the full `a.b.example.com/c/d#1.0` name is left as an exercise for the reader, as is switching based on `platform` entries or [chosing between multiple entries with the same name][duplicate-name-resolution]. [annotations]: https://github.com/opencontainers/image-spec/blob/v1.0.0/annotations.md#pre-defined-annotation-keys diff --git a/ref-engine-discovery.md b/ref-engine-discovery.md index c460309..9b9e951 100644 --- a/ref-engine-discovery.md +++ b/ref-engine-discovery.md @@ -69,7 +69,13 @@ Each entry in the `refEngines` array MUST be an [objects][rfc7159-s4] with at le Consumers SHOULD ignore entries which declare unsupported `protocol` values. The order of entries in the array is not significant. -### Example +The ref-engine discovery service MAY also include `casEngines` entry if it wants to supplement suggestions made by the ref engines. +If set, the `refEngines` entry MUST be an [array][rfc7159-s5]. +Each entry in the `refEngines` array MUST be an [objects][rfc7159-s4] with at least a `protocol` entry specifying the [cas-engine protocol](cas-engine-protocols.md). +Consumers SHOULD ignore entries which declare unsupported `protocol` values. +The order of entries in the array is not significant. + +### Example 1 ``` $ curl -H 'Accept: application/vnd.oci.ref-engines.v1+json' https://a.b.example.com/.well-known/oci-host-ref-engines @@ -92,6 +98,29 @@ $ curl -H 'Accept: application/vnd.oci.ref-engines.v1+json' https://a.b.example. The [`oci-index-template-v1` protocol](index-template.md) is [registered](ref-engine-protocols.md). The `docker` protocol is currently [unregistered](ref-engine-protocols.md), and is given as sketch of a possible extention protocol. +### Example 2 + +``` +$ curl -H 'Accept: application/vnd.oci.ref-engines.v1+json' https://example.com/.well-known/oci-host-ref-engines +{ + "refEngines": [ + { + "protocol": "oci-index-template-v1", + "uri": "https://{host}/ref/{name}" + } + ], + "casEngines": [ + { + "protocol": "oci-cas-template-v1", + "uri": "https://a.example.com/cas/{algorithm}/{encoded:2}/{encoded}" + } + ], +} +``` + +The [`oci-index-template-v1` protocol](index-template.md) is [registered](ref-engine-protocols.md). +The [`oci-cas-template-v1` protocol](cas-template.md) is [registered](cas-engine-protocols.md). + [CAS]: https://en.wikipedia.org/wiki/Content-addressable_storage [descriptor]: https://github.com/opencontainers/image-spec/blob/v1.0.0/descriptor.md [media-type]: https://tools.ietf.org/html/rfc6838