The following languages are currently supported:
The objective of ORAS is simple as transferring artifacts from one place to another.
In the conventional client-server model, the operation of downloading artifacts from the remote registries is referred to as pull, and the operation of uploading artifacts to the remote registry is referred to as push.
This model can be generalized by abstracting the client and the server as targets so that pull and push can be viewed as copying from one target to another (see Copy API oras-project/oras-go#8). For instances,
- Copy from memory to a remote registry.
- Copy from a remote registry to a local file folder.
- Copy from a remote registry to another remote registry.
- Copy from memory to a local file folder.
To retrieve a blob,
- Get a descriptor. Optionally, it can be resolved by a tag.
- Query the blob with a descriptor.
To store a blob,
- Store the blob directly in the CAS. A descriptor will be returned.
- Optionally, associate the returned descriptor with a tag.
It is worth noting that a target is not equal to a registry.
- Blobs can be tagged in a target but not in a registry.
- Tag list is available in a registry but not always available in a target.
Besides plain blobs, it is natural to store directed acyclic graphs (DAGs) in a CAS. Precisely, all blobs are leaf nodes and most manifests are non-leaf nodes.
Given a node of a DAG in a CAS, it is efficient to find out all its children. Since CASs are usually not enumerable or indexed, it is not possible to find the parent nodes of an arbitrary node. Nevertheless, some CASs choose to implement or partially implement the functionality of parent node finding. For instances, registries with Manifest Referrers API support are CASs with partially implementation where parent node finding is only available for manifest nodes.
With the concepts above, we can formally define that
- Copy is a function to replicate a rooted DAG from one CAS to another.
- Extended Copy is a function to replicate a DAG from one CAS to another.
It is worth noting that extended copy is possible only if the source CAS supports parent node finding. Based on the scenarios, extended copy can have many options such as opting to copy a sub-DAG rooted by a certain node and all its parent nodes of a certain depth with / without their children.
Optionally, node filters or even node modifiers can be attached to a copy process for advanced scenarios.
- Support copy of images and associated references oras-project/oras-go#29
- Copy Artifact Reference Graph oras-project/oras#307
Hint: A polytree is a DAG.
🚧 Note: this section is contingent on oras-project/oras-go#8 and does not reprersent the current state of the ORAS Go client library.
At a high-level, each client library provides the concept of a
Copy transfers content from one
Target to another.
Target represents a place to which one can send/push or retrieve/pull artifacts.
Anything that implements this interface can be used as a place to send
or retrieve artifacts.
Some examples of a
Target may include the following:
- An OCI Registry
- An OCI Image Layout
- A local collection of files
Copy copies a ref from one
Target to a ref in another
The following is a rough method signature based on the Go version:
func Copy(from Target, fromRef string, to Target, toRef string) Descriptor