extensions: pulling in latest feedback

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,100 @@
+---
+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>&...]
+```
+
+The values of `<extension>`, `<component>`, and `<module>` MUST conform to the following regular expression:
+
+`[a-z0-9]+([._-][a-z0-9]+)`
+
+Note: the leading `_` on the extension is a prefix before this regular expression.
+
+### 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)

extensions/_oci.md

@@ -0,0 +1,79 @@
+# _oci Extension Endpoints
+
+## Summary
+
+This base extension namespace for OCI namespaced extension endpoints.
+
+## Reference Explanation
+
+### Component: `ext`
+
+This component is for endpoints relating to extensions on the registry API being queried.
+
+#### Module: `discover`
+
+This endpoint may be queried to discover extensions available on this registry API.
+
+Registry-level extensions may be discovered with a standard `GET` as follows.
+
+```HTTP
+GET /v2/_oci/ext/discover
+```
+
+Repository-level extensions may be discovered with a standard GET as follows.
+
+```HTTP
+    GET /v2/{name}/_oci/ext/discover
+```
+
+The base extension returns an array of supported extensions with details of the endpoints as shown below.
+
+```HTTP
+200 OK
+Content-Length: <length>
+Content-Type: application/json
+
+{
+    "extensions": [
+        {
+            "name": "_<extension>",
+            "description": "",
+            "url": "..."
+        }
+    ]    
+}
+```
+
+### *Extensions* Property Descriptions
+
+- **`extensions`** *array of extension objects*, REQUIRED
+
+  This property contains a list of supported extension endpoints.
+
+  - **`name`** *string*, REQUIRED
+
+    The name of the extension (i.e. '`_oci`') as it will appear in the URL path.
+
+  - **`url`** *string*, REQUIRED
+
+    URL link to the documentation defining this extension and its endpoints.
+
+  - **`description`** *string*, OPTIONAL
+
+    Human readable description of this endpoint.
+
+  - **`endpoints`** *array of strings*, REQUIRED
+
+    Enumeration of the endpoints provided on this registry (as not all "OPTIONAL" endpoints may be present in all registries)
+
+## Code representations
+
+Golang structures for these JSON structures is available at [`github.com/opencontainers/distribution-spec/specs-go/v1/extensions`](https://github.com/opencontainers/distribution-spec/tree/main/specs-go/v1/extensions/)
+
+## Error Codes
+
+Registry implementations MAY chose to not support any extension and the base extension MAY return the following error message.
+
+| Code          | Message                       | Description                                                                                 |
+|---------------|-------------------------------|---------------------------------------------------------------------------------------------|
+| `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. |

specs-go/v1/extensions/ext.go

@@ -0,0 +1,29 @@
+// Copyright 2022 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 is the structure returned from discover endpoint defined in /extensions/_oci.md
+type ExtensionList struct {
+	Extensions []Extension `json:"extensions"`
+}
+
+// Extension provides information on extensions provided on a Registry.
+// defined further in /extensions/_oci.md
+type Extension struct {
+	Name        string   `json:"name"`
+	URL         string   `json:"url"`
+	Description string   `json:"description,omitempty"`
+	Endpoints   []string `json:"endpoints"`
+}