OCI.Storage.Adapter behaviour (oci v0.0.2)
View SourceBehaviour for OCI registry storage backends.
This module defines the interface that storage adapters must implement to work with OCI (Open Container Initiative) registries. A storage adapter is responsible for storing and retrieving container images and their components.
Key Concepts
- Repository: A collection of related container images (e.g., "myapp/backend")
- Blob: Binary data that represents layers of a container image or configuration
- Manifest: A JSON document that describes a container image, including its layers and configuration
- Digest: A unique identifier for a blob, typically a SHA-256 hash
- Reference: A human-readable identifier for a manifest (e.g., "latest", "v1.0.0")
Implementation Guide
When implementing this behaviour, you'll need to handle:
- Repository initialization and management
- Blob storage and retrieval
- Manifest storage and retrieval
- Tag management
- Upload handling for large blobs
Example Usage
defmodule MyStorageAdapter do
@behaviour OCI.Storage.Adapter
defstruct [:path] # Define your struct fields here
# Implement all callbacks here
end
Summary
Callbacks
Checks if a blob exists in the repository and returns its size if found.
Cancels an ongoing blob upload session.
Finalizes a blob upload and verifies the digest.
Deletes a blob from the repository.
Deletes a manifest from the repository.
Retrieves a blob's content from the repository.
Gets the total size of an ongoing blob upload.
Gets the status of an ongoing blob upload.
Retrieves a manifest from the repository.
Gets metadata about a manifest without retrieving its content.
Initializes a new storage adapter instance with the given configuration.
Initiates a blob upload session.
Lists tags in a repository with pagination support.
Mounts a blob from one repository to another.
Checks if a repository exists.
Stores a manifest in the repository.
Uploads a chunk of data to an ongoing blob upload.
Types
Callbacks
@callback blob_exists?(storage :: t(), repo :: String.t(), digest :: String.t()) :: {:ok, size :: non_neg_integer()} | {:error, :BLOB_UNKNOWN}
Checks if a blob exists in the repository and returns its size if found.
@callback cancel_blob_upload(storage :: t(), repo :: String.t(), uuid :: String.t()) :: :ok | {:error, :BLOB_UPLOAD_UNKNOWN}
Cancels an ongoing blob upload session.
@callback complete_blob_upload( storage :: t(), repo :: String.t(), upload_id :: String.t(), digest :: String.t() ) :: :ok | {:error, :digest_mismatch | term()}
Finalizes a blob upload and verifies the digest.
@callback delete_blob(storage :: t(), repo :: String.t(), digest :: String.t()) :: :ok | {:error, :BLOB_UNKNOWN}
Deletes a blob from the repository.
@callback delete_manifest(storage :: t(), repo :: String.t(), reference :: String.t()) :: :ok | {:error, atom()}
Deletes a manifest from the repository.
@callback get_blob(storage :: t(), repo :: String.t(), digest :: String.t()) :: {:ok, content :: binary()} | {:error, :BLOB_UNKNOWN}
Retrieves a blob's content from the repository.
@callback get_blob_upload_offset(storage :: t(), repo :: String.t(), uuid :: String.t()) :: {:ok, size :: non_neg_integer()} | {:error, term()}
Gets the total size of an ongoing blob upload.
@callback get_blob_upload_status( storage :: t(), repo :: String.t(), uuid :: String.t() ) :: {:ok, range :: String.t()} | {:error, term()}
Gets the status of an ongoing blob upload.
@callback get_manifest(storage :: t(), repo :: String.t(), reference :: String.t()) :: {:ok, manifest :: binary(), content_type :: String.t()} | {:error, atom(), error_details_t()}
Retrieves a manifest from the repository.
@callback get_manifest_metadata( storage :: t(), repo :: String.t(), reference :: String.t() ) :: {:ok, content_type :: String.t(), byte_size :: non_neg_integer()} | {:error, atom(), error_details_t()}
Gets metadata about a manifest without retrieving its content.
Initializes a new storage adapter instance with the given configuration.
@callback initiate_blob_upload(storage :: t(), repo :: String.t()) :: {:ok, upload_id :: String.t()} | {:error, term()}
Initiates a blob upload session.
@callback list_tags( storage :: t(), repo :: String.t(), pagination :: OCI.Registry.Pagination.t() ) :: {:ok, tags :: [String.t()]} | {:error, :NAME_UNKNOWN}
Lists tags in a repository with pagination support.
@callback mount_blob( storage :: t(), repo :: String.t(), digest :: String.t(), from_repo :: String.t() ) :: :ok | {:error, :BLOB_UNKNOWN}
Mounts a blob from one repository to another.
Checks if a repository exists.
@callback store_manifest( storage :: t(), repo :: String.t(), reference :: String.t(), manifest :: map(), manifest_digest :: String.t() ) :: :ok | {:error, :MANIFEST_BLOB_UNKNOWN | :MANIFEST_INVALID | :NAME_UNKNOWN, error_details_t()}
Stores a manifest in the repository.
@callback upload_blob_chunk( storage :: t(), repo :: String.t(), uuid :: String.t(), chunk :: binary(), content_range :: String.t() ) :: {:ok, range :: String.t()} | {:error, term()}
Uploads a chunk of data to an ongoing blob upload.