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

@@ -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

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

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

ref-engine-discovery.md

@@ -48,7 +48,12 @@ 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 [ref-engine protocol](ref-engine-protocols.md).
 Consumers SHOULD ignore entries which declare unsupported `protocol` values.
 
-### 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.
+
+### Example 1
 
 ```
 $ curl -H 'Accept: application/vnd.oci.ref-engines.v1+json' https://a.b.example.com/.well-known/oci-ref-engines
@@ -71,6 +76,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-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