diff --git a/ext/README.md b/ext/README.md deleted file mode 100644 index 27d75d6e..00000000 --- a/ext/README.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -tags: oci,distribution -breaks: false ---- - -# Extensions API for Distribution - -The basis of the Extension API is described in a document which should -be emulated for all extensions. - -## Table - -_notice_: All new `./ext/ext-$ns-$name.md` docs MUST be added to this table. - -| `$ns-$name` | Summary | -|:------------------------:|:----------------------------------------------------:| -| [ext](./ext.md) | Extensions discovering extensions on registry server | - -## Name - -Extension names MUST be unique. Extensions are specified by -`namespace` aligning with the project, followed by the `extension` provided by the project and last by by the `component`. This constitutes the URI segments -of the extension endpoint. Additional options may be passed as parameters to the endpoint. - -```http -_//[?=&...] -``` - -For versioning, extensions SHOULD use versioned `mediaType`. - -### Registry Level Extensions - -Registry level extensions are nested under `/v2`. - -```http -GET /v2/_//[?=&...] -``` - -For example a search extension may be of the form `/v2/_oci/catalog/search?pattern=foo?n=10` - -### Repository Level Extensions - -Repository level extensions follow the same naming rules the endpoints -can be access under a repository. - -```http -GET /v2//_//[?=&...] -``` - -### Reserved Namespaces -As of current, ```_oci``` and ```_ext``` are considered as reserved namespaces and cannot be used by other extensions. - -## Filename - -Extension definitions SHOULD be placed under `./ext/` in the specification repository. Extension files -SHOULD follow the `ext-$ns-$name.md`. Refer [ext.md](./ext.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) diff --git a/ext/ext.md b/ext/ext.md deleted file mode 100644 index a1347de1..00000000 --- a/ext/ext.md +++ /dev/null @@ -1,58 +0,0 @@ -# _ext - Index of Distribution Extensions - -## Summary - -This base extension namespace is used to discover and return an array of extensions. - -## Reference Explanation - -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 -``` - -Repository level extensions may be discovered with a standard GET as follows. - -```HTTP - GET /v2/{name}/_ext/discover -``` - -The base extension returns an array of supported extensions with details of the -endpoints as shown below. - -```HTTP -200 OK -Content-Length: -Content-Type: application/json - -{ - "extensions: [ - { - "name": "_//" - }, - ] -} -``` - -### *Extensions* Property Descriptions - -- **`extensions`** *array of extension objects with properties like `name`* - - This REQUIRED 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,`_ext`. - -## 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. | diff --git a/extensions/README.md b/extensions/README.md new file mode 100644 index 00000000..82e7d466 --- /dev/null +++ b/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/_.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 (``) aligning with the project, followed by the ``, and last by by the ``. +This constitutes the URI segments of the extension endpoint. +Additional options may be passed as parameters to the endpoint. + +```http +_//[?=&...] +``` + +The values of ``, ``, and `` 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/_//[?=&...] +``` + +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//_//[?=&...] +``` + +### 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 `` and/or `/`. +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 `_.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) diff --git a/extensions/_oci.md b/extensions/_oci.md new file mode 100644 index 00000000..1ae44e2b --- /dev/null +++ b/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: +Content-Type: application/json + +{ + "extensions": [ + { + "name": "_", + "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. | diff --git a/specs-go/v1/extensions/ext.go b/specs-go/v1/extensions/ext.go new file mode 100644 index 00000000..5c3d7367 --- /dev/null +++ b/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"` +}