extensions: pulling in latest feedback (WIP)

Co-authored-by: Stephen Day <stephen.day@getcruise.com>
Co-authored-by: Aaron Goulet <gluten@amazon.com>
Co-authored-by: Lachie Evenson <laevenso@microsoft.com
Co-authored-by: Mike Brown <brownwm@us.ibm.com>
Co-authored-by: Samuel Karp <me@samuelkarp.com>
Co-authored-by: Sajay Antony <sajaya@microsoft.com>
Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>

extensions/README.md

@@ -0,0 +1,94 @@
+---
+tags: oci,distribution
+breaks: false
+---
+
+# Extensions API for Distribution
+
+Extensions, in general, to the distribution-spec API are allowed by the distribution-spec, with certain reservations disclosed herein.
+This document outlines a path for registry implementations and clients to iterate on new APIs, establish them, and propose them to OCI for canonical reference.
+
+The basis of the Extension API (`_oci`) should be emulated for all extensions.
+
+## Table
+
+_notice_: All new `/extensions/_$extention.md` docs MUST be added to this table.
+
+| Extension                | Summary                                              |
+|:------------------------:|:----------------------------------------------------:|
+| [`_oci`](./_oci.md)      | Extensions discovering extensions on registry server |
+| `_catalog`               | Reserved prior extension                             |
+
+## Name
+
+Extension names MUST be unique.
+Extensions recorded in this distribution-spec are considered canonical definitions.
+
+Extensions are specified by extension name (`$extension`) aligning with the project, followed by the `component`, and last by by the `module`.
+This constitutes the URI segments of the extension endpoint.
+Additional options may be passed as parameters to the endpoint.
+
+```http
+_<extension>/<component>/<module>[?<key>=<value>&...]
+```
+
+### Registry-Level Extensions
+
+Registry-level extensions are nested under `/v2`.
+
+```http
+GET /v2/_<extension>/<component>/<module>[?<key>=<value>&...]
+```
+
+A contrived example of a search extension may be of the form `/v2/_oci/catalog/search?pattern=foo?n=10`
+
+### Repository-Level Extensions
+
+Repository-level extension endpoints are scoped under a repository name.
+
+Repository-level extensions follow the same naming rules as the [registry-level endpoints](#registry-level-extensions).
+
+```http
+GET /v2/<name>/_<extension>/<component>/<module>[?<key>=<value>&...]
+```
+
+### Reserved Namespaces
+
+As of current, `_oci` and `_catalog` are considered as reserved namespaces and cannot be used by other extensions.
+
+### Versioning
+
+Data payloads being exchanged from extensions SHOULD handle versioned data structures this with `Accepts` and `Content-type` HTTP headers (LINK TO RFC).
+
+If an extension has fundamentally changed enough, then it SHOULD be introduced as a new `<component>` and/or `<component>/<module>`.
+Whether or not there is versioning built into those names is up to the extension maintainer.
+
+## Filename
+
+Extension definitions SHOULD be placed under `./extensions/` in the specification repository.
+Extension files SHOULD follow the `_<extension>.md` pattern.
+Refer [_oci.md](./_oci.md) for more details.
+
+## Detail
+
+Extensions details MAY describe more endpoints and  APIs that it MAY support.
+It is also recommended to call out error codes encountered and enumerated as in the
+in the following table:
+
+| Code                | Message              | Description                                         |
+|---------------------|----------------------|-----------------------------------------------------|
+| `EXTENSION_UNKNOWN` | Extension is unknown | This error MAY be returned when a extension is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. |
+
+## Pagination
+
+Extensions implementing pagination and SHOULD align with the [pagination](./spec.md#pagination) specification.
+
+Extension MAY provide enumeration without lexical ordering and in this case, it is not required to support the `last` parameter.
+Clients are NOT RECOMMENDED to construct the `link` and SHOULD treat the URL as opaque.
+
+## Prior Art
+
+When considering the proposal structure for these extensions, the following processes were considered:
+
+* [Python PEP](https://www.python.org/dev/peps/)
+* [Kubernetes KEP](https://github.com/kubernetes/enhancements/tree/master/keps)

ext/ext.md → extensions/_oci.md

@@ -1,24 +1,26 @@
-# _ext - Index of Distribution Extensions
+# _oci Extension Endpoints
 
 ## Summary
 
-This base extension namespace is used to discover and return an array of extensions.
+This base extension namespace for OCI namespaced extension endpoints.
 
 ## Reference Explanation
 
+### "ext"
+
 The base extension may be queried through a `GET` to discover available
 extensions.
 
 Registry level extensions may be discovered with a standard GET as follows.
 
 ```HTTP
-    GET /v2/_ext/discover
+GET /v2/_oci/ext/discover
 ```
 
 Repository level extensions may be discovered with a standard GET as follows.
 
 ```HTTP
-    GET /v2/{name}/_ext/discover
+    GET /v2/{name}/_oci/ext/discover
 ```
 
 The base extension returns an array of supported extensions with details of the
@@ -30,23 +32,33 @@ Content-Length: <length>
 Content-Type: application/json
 
 {
-    "extensions: [
+    "extensions": [
         {
-            "name": "_<ns>/<ext>/<component>"
-        },
+            "url": "...",
+            "name": "_<extension>",
+            "path": "_<extension>/<component>/<module>"
+        }
     ]    
 }
 ```
 
 ### *Extensions* Property Descriptions
 
-- **`extensions`** *array of extension objects with properties like `name`*
+- **`extensions`** *array of extension objects*, REQUIRED
+
+  This property contains a list of supported extension endpoints.
+
+  The [relative URI]((https://tools.ietf.org/doc/html/rfc1808))
+  which MAY be constructed by replacing
+  the base discovery extension path,`_oci`.
+
+  - **`name`** *string*, REQUIRED
+
+    XXX
 
-    This REQUIRED property contains a list of supported extension endpoints.
+## Code representations
 
-    The [relative URI]((https://tools.ietf.org/doc/html/rfc1808))
-    which MAY be constructed by replacing
-    the base discovery extension path,`_ext`.
+Golang structures for these JSON structures is available at [`github.com/opencontainers/distribution-spec/specs-go/v1/extensions`](XXX)
 
 ## Error Codes
 

specs-go/v1/extensions/ext.go

@@ -0,0 +1,25 @@
+// Copyright 2019 The Linux Foundation
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package extensions
+
+// ExtensionList
+type ExtensionList struct {
+	Extensions []Extension `json:"extensions"`
+}
+
+type Extension struct {
+	Name string
+	Path string
+}