diff --git a/wit/client.wit b/wit/client.wit index 7134f00..5ecd069 100644 --- a/wit/client.wit +++ b/wit/client.wit @@ -3,270 +3,298 @@ interface client { use wasi:clocks/system-clock@0.3.0.{ instant }; + /// Error codes defined by the OCI distribution spec, or other @since(version = 0.1.0-dev) variant error-code { - // blob unknown to registry (code-1 `BLOB_UNKNOWN`) + /// blob unknown to registry (code-1 `BLOB_UNKNOWN`) blob-unknown(string), - // blob upload invalid (code-2 `BLOB_UPLOAD_INVALID`) + /// blob upload invalid (code-2 `BLOB_UPLOAD_INVALID`) blob-upload-invalid(string), - // blob upload unknown to registry (code-3`BLOB_UPLOAD_UNKNOWN`) + /// blob upload unknown to registry (code-3`BLOB_UPLOAD_UNKNOWN`) blob-upload-unknown(string), - // provided digest did not match uploaded content (code-4 `DIGEST_INVALID`) + /// provided digest did not match uploaded content (code-4 `DIGEST_INVALID`) digest-invalid(string), - // manifest references a manifest or blob unknown to registry (code-5 `MANIFEST_BLOB_UNKNOWN`) + /// manifest references a manifest or blob unknown to registry (code-5 `MANIFEST_BLOB_UNKNOWN`) manifest-blob-unknown(string), - // manifest invalid (code-6 `MANIFEST_INVALID`) + /// manifest invalid (code-6 `MANIFEST_INVALID`) manifest-invalid(string), - // manifest unknown to registry (code-7 `MANIFEST_UNKNOWN`) + /// manifest unknown to registry (code-7 `MANIFEST_UNKNOWN`) manifest-unknown(string), - // invalid repository name (code-8 `NAME_INVALID`) + /// invalid repository name (code-8 `NAME_INVALID`) name-invalid(string), - // repository name not known to registry (code-9 `NAME_UNKNOWN`) + /// repository name not known to registry (code-9 `NAME_UNKNOWN`) name-unknown(string), - // provided length did not match content length (code-10 `SIZE_INVALID`) + /// provided length did not match content length (code-10 `SIZE_INVALID`) size-invalid(string), - // authentication required (code-11 `UNAUTHORIZED`) + /// authentication required (code-11 `UNAUTHORIZED`) unauthorized(string), - // requested access to the resource is denied (code-12 `DENIED`) + /// requested access to the resource is denied (code-12 `DENIED`) denied(string), - // the operation is unsupported (code-13 `UNSUPPORTED`) + /// the operation is unsupported (code-13 `UNSUPPORTED`) unsupported(string), - // too many requests (code-14 `TOOMANYREQUESTS`) + /// too many requests (code-14 `TOOMANYREQUESTS`) toomanyrequests(option), - // other + /// other other(option), } + /// time when a failed request should not be retried until. Part of code-14 `TOOMANYREQUESTS` error response @since(version = 0.1.0-dev) variant retry-after { date(instant), delay-seconds(u32), } + /// schmea version for OCI manifests, should always be 2 @since(version = 0.1.0-dev) variant schema-version { + /// literal 2. Prefixed with a 'v' to bypass wit naming constrains v2, + /// a non-2 value, the parsed manifest may be incomplete or otherwise inaccurate. other(option), } - // common media types for oci artifacts + /// common media types for oci artifacts @since(version = 0.1.0-dev) variant media-type { - // content descriptor + /// content descriptor application-vnd-oci-descriptor-v1(media-type-suffix), - // oci layout + /// oci layout application-vnd-oci-layout-header-v1(media-type-suffix), - // image index + /// image index application-vnd-oci-image-index-v1(media-type-suffix), - // image manifest + /// image manifest application-vnd-oci-image-manifest-v1(media-type-suffix), - // image config + /// image config application-vnd-oci-image-config-v1(media-type-suffix), - // layer, as a tar archive + /// layer, as a tar archive application-vnd-oci-image-layer-v1-tar(media-type-suffix), - // empty for unused descriptors + /// empty for unused descriptors application-vnd-oci-empty-v1(media-type-suffix), - // layer, as a tar archive + /// layer, as a tar archive application-vnd-oci-image-layer-nondistributable-v1-tar(media-type-suffix), - // wasm config + /// wasm config application-vnd-wasm-config-v0(media-type-suffix), - // wasm + /// wasm application-wasm, - // other + /// all other values other(string), } + /// encoding for a resource representation @since(version = 0.1.0-dev) variant media-type-suffix { - // json encoded + /// json encoded json, - // compressed with gzip + /// compressed with gzip gzip, - // compressed with zstd + /// compressed with zstd zstd, - // other encoding + /// other encoding other(option), } + /// OCI Descriptor v1 + /// https://github.com/opencontainers/image-spec/blob/main/descriptor.md @since(version = 0.1.0-dev) record oci-descriptor-v1 { - // media type of the referenced content + /// media type of the referenced content media-type: media-type, - // digest of the targeted content + /// digest of the targeted content digest: digest, - // size, in bytes, of the raw content + /// size, in bytes, of the raw content size: u64, - // list of URIs from which this object MAY be downloaded + /// list of URIs from which this object MAY be downloaded urls: option>, - // arbitrary metadata for this descriptor + /// arbitrary metadata for this descriptor annotations: option>, - // embedded representation of the referenced content + /// embedded representation of the referenced content data: option, - // type of an artifact when the descriptor points to an artifact + /// type of an artifact when the descriptor points to an artifact artifact-type: option, } + /// OCI Manifests @since(version = 0.1.0-dev) variant manifest { - // oci image + /// oci image oci-image-v1(oci-image-manifest-v1), - // oci image index + /// oci image index oci-image-index-v1(oci-image-index-manifest-v1), - // other + /// other, raw bytes of the manifest blob other(list), } + /// OCI Image Manifest v1 + /// https://github.com/opencontainers/image-spec/blob/main/manifest.md @since(version = 0.1.0-dev) record oci-image-manifest-v1 { - // manifest schema version + /// manifest schema version schema-version: schema-version, - // must contain the media type 'application/vnd.oci.image.manifest.v1+json'. + /// must contain the media type 'application/vnd.oci.image.manifest.v1+json'. media-type: media-type, - // type of an artifact when the manifest is used for an artifact + /// type of an artifact when the manifest is used for an artifact artifact-type: option, - // configuration object for a container + /// configuration object for a container config: oci-descriptor-v1, - // list of layer descriptors + /// list of layer descriptors layers: list, - // weak association to another manifest + /// weak association to another manifest subject: option, - // arbitrary metadata for the image manifest + /// arbitrary metadata for the image manifest annotations: option>, } + /// OCI Image Index v1 + /// https://github.com/opencontainers/image-spec/blob/main/image-index.md @since(version = 0.1.0-dev) record oci-image-index-manifest-v1 { - // manifest schema version + /// manifest schema version schema-version: schema-version, - // must contain the media type 'application/vnd.oci.image.index.v1+json'. + /// must contain the media type 'application/vnd.oci.image.index.v1+json'. media-type: media-type, - // type of an artifact when the manifest is used for an artifact + /// type of an artifact when the manifest is used for an artifact artifact-type: option, - // manifests for specific platforms + /// manifests for specific platforms manifests: list, - // weak association to another manifest + /// weak association to another manifest subject: option, - // arbitrary metadata for the image manifest + /// arbitrary metadata for the image manifest annotations: option>, } + /// OCI Image Index v1 - manifest entry + /// https://github.com/opencontainers/image-spec/blob/main/image-index.md @since(version = 0.1.0-dev) record oci-image-index-manifest-v1-manifest { - // media type of the referenced content + /// media type of the referenced content media-type: media-type, - // digest of the targeted content + /// digest of the targeted content digest: digest, - // size, in bytes, of the raw content + /// size, in bytes, of the raw content size: u64, - // list of URIs from which this object MAY be downloaded + /// list of URIs from which this object MAY be downloaded urls: option>, - // arbitrary metadata for this descriptor + /// arbitrary metadata for this descriptor annotations: option>, - // embedded representation of the referenced content + /// embedded representation of the referenced content data: option, - // type of an artifact when the descriptor points to an artifact + /// type of an artifact when the descriptor points to an artifact artifact-type: option, - // minimum runtime requirements of the image + /// minimum runtime requirements of the image platform: option, - // descriptor of another manifest + /// descriptor of another manifest subject: option, } + /// OCI Image Index v1 - manifest entry platform + /// https://github.com/opencontainers/image-spec/blob/main/image-index.md @since(version = 0.1.0-dev) record oci-image-index-manifest-v1-manifest-platform { - // CPU architecture which the binaries in this image are built to run on + /// CPU architecture which the binaries in this image are built to run on architecture: string, - // name of the operating system which the image is built to run on + /// name of the operating system which the image is built to run on os: string, - // version of the operating system + /// version of the operating system os-version: option, - // mandatory OS features + /// mandatory OS features os-features: option>, - // variant of the CPU + /// variant of the CPU %variant: option, } + /// OCI Configs @since(version = 0.1.0-dev) variant config { - // oci iamge + /// oci iamge oci-image-v1(oci-image-config-v1), - // wasm module + /// wasm module wasm-v0(wasm-config-v0), - // other + // other, raw bytes of the config blob other(list), } + /// OCI Image Config v1 + /// https://github.com/opencontainers/image-spec/blob/main/config.md @since(version = 0.1.0-dev) record oci-image-config-v1 { - // combined date and time at which the image was created + /// combined date and time at which the image was created created: option, - // name and/or email address of the person or entity which created and is responsible for maintaining the image + /// name and/or email address of the person or entity which created and is responsible for maintaining the image author: option, - // CPU architecture which the binaries in this image are built to run on + /// CPU architecture which the binaries in this image are built to run on architecture: string, - // name of the operating system which the image is built to run on + /// name of the operating system which the image is built to run on os: string, - // version of the operating system + /// version of the operating system os-version: option, - // mandatory OS features + /// mandatory OS features os-features: option>, - // variant of the specified CPU architecture + /// variant of the specified CPU architecture %variant: option, - // execution parameters which should be used as a base when running a container using the image + /// execution parameters which should be used as a base when running a container using the image config: option, - // layer content addresses used by the image + /// layer content addresses used by the image rootfs: oci-image-config-v1-content-addresses, - // history of each layer. The array is ordered from first to last + /// history of each layer. The array is ordered from first to last history: option>, } + /// OCI Image Config v1 - config + /// https://github.com/opencontainers/image-spec/blob/main/config.md @since(version = 0.1.0-dev) record oci-image-config-v1-config { - // username or UID which is a platform-specific structure that allows specific control over which user the process run as + /// username or UID which is a platform-specific structure that allows specific control over which user the process run as user: option, - // set of ports to expose from a container running this image + /// set of ports to expose from a container running this image exposed-ports: option>, - // values act as defaults and are merged with any specified when creating a container + /// values act as defaults and are merged with any specified when creating a container env: option>, - // arguments to use as the command to execute when the container starts + /// arguments to use as the command to execute when the container starts entrypoint: option>, - // arguments to the entrypoint of the container + /// arguments to the entrypoint of the container cmd: option>, - // directories describing where the process is likely to write data specific to a container instance + /// directories describing where the process is likely to write data specific to a container instance volumes: option>, - // current working directory of the entrypoint process in the container + /// current working directory of the entrypoint process in the container working-dir: option, - // arbitrary metadata for the container + /// arbitrary metadata for the container labels: option>, - // system call signal that will be sent to the container to exit + /// system call signal that will be sent to the container to exit stop-signal: option, - // deprecated: present only for legacy compatibility + /// deprecated: present only for legacy compatibility args-escaped: option, } + /// OCI Image Config v1 - content address + /// https://github.com/opencontainers/image-spec/blob/main/config.md @since(version = 0.1.0-dev) record oci-image-config-v1-content-addresses { - // must be 'layers' + /// must be 'layers' %type: string, - // layer content hashes, in order from first to last + /// layer content hashes, in order from first to last diff-ids: list, } + /// OCI Image Config v1 - history entry + /// https://github.com/opencontainers/image-spec/blob/main/config.md @since(version = 0.1.0-dev) record oci-image-config-v1-history-entry { - // combined date and time at which the layer was created + /// combined date and time at which the layer was created created: option, - // author of the build point + /// author of the build point author: option, - // command which created the layer + /// command which created the layer created-by: option, - // custom message set when creating the layer + /// custom message set when creating the layer comment: option, - // mark if the history item created a filesystem diff + /// mark if the history item created a filesystem diff empty-layer: option, } + /// WASM Config v0 + /// https://tag-runtime.cncf.io/wgs/wasm/deliverables/wasm-oci-artifact/ @since(version = 0.1.0-dev) record wasm-config-v0 { // combined date and time at which the image was created @@ -283,39 +311,57 @@ interface client { component: option, } + /// WASM Config v0 - component + /// https://tag-runtime.cncf.io/wgs/wasm/deliverables/wasm-oci-artifact/ @since(version = 0.1.0-dev) record wasm-config-v0-component { + /// items (interfaces, functions, types) exported by the component exports: list, + /// items (interfaces, functions, types) imported by the component imports: list, + /// target world the component implements target: option, } + /// Image reference, typically created by `parse-reference(string)` @since(version = 0.1.0-dev) record reference { + /// host and port of the registry, defaults to `index.docker.io` registry: string, + /// repository path within the registry repository: string, + /// tag of the content, defaults to `latest` tag: option, + /// digest of the referenced content, supersedes any tag digest: option, } + /// Content digest @since(version = 0.1.0-dev) record digest { + /// hashing algorithm. `sha256` is strongly recommended algorithm: string, + /// digest value. Format is defined by the algorithm. encoded: string, } + /// Parse a string image reference like `ubuntu` or `ghcr.io/componentized/oci:1.0.0` for use by the other methods. @since(version = 0.1.0-dev) parse-reference: func(reference: string) -> result; + /// Resolves a tagged reference to a digest with the registry. Digested references are returned immediately. @since(version = 0.1.0-dev) resolve-digest: async func(reference: reference) -> result; + /// Gets a blob from the registry. The reference must be digested. Manifests must be fetched with `get-manifest()` @since(version = 0.1.0-dev) get-blob: async func(reference: reference) -> result, error-code>; + /// Gets a config from the registry decoding by media type. In many cases, the media type cannot be inferred and must be passed explicitly. The reference must be digested. @since(version = 0.1.0-dev) get-config: async func(reference: reference, default-media-type: option) -> result; + /// Gets a manifest from the registry decoding by media type. The reference may be tagged or digested. @since(version = 0.1.0-dev) get-manifest: async func(reference: reference) -> result;