koci

"kay oh see eye"

Kotlin implementation of the OCI Distribution client specification.

Import

com.defenseunicorns.koci

Grab from GitHub packages or Maven Central

Basic Usage

// 0. Create a file store
val store = runBlocking { Layout.create("/tmp/koci-store") }.getOrThrow()

// 1. Connect to a remote repository
val repo = Registry("https://public.ecr.aws").repo("ubuntu/redis")

// 2. Copy from the remote repository to the file store
val tag = "latest"

repo.pull(tag, store).collect{ prog ->
    println("$prog% done")
}

Auth

• Request scopes relevant code
• Basic/Bearer auth w/ Distribution auth flow
• Docker's ~/.docker/config.json support

Pull

Distribution specification

• GET /v2/ Ping registry
• GET /v2/_catalog Catalog
  • Support pagination
• HEAD|GET /v2/<name>/manifests/<reference> Check for existence / fetch manifest by tag/digest
  • Resolve/fetch tag into manifest/index
    • Support custom index -> manifest resolution logic
  • Reference support and validation
• DELETE /v2/<name>/manifests/<digest>
• GET /v2/<name>/tags/list List image tags
  • Support pagination
• Pull image (3 layer concurrency) with %/100 progress
  • By tag
  • By descriptor
  • Into OCI layout
• Fetch blob
  • Accept-Ranges: bytes detection + Range support
  • Resumable downloads
  • Content verification using size + digest
• Referrers API

Push

Distribution specification

• Push blobs
  • Resumable uploads
  • Single PUT request if content < OCI-Chunk-Min-Length or 5MB if unset. Chunked upload otherwise
  • Cross-repository blob mounting
• Push + tag manifests/indexes
• Referrers API

Store

Layout specification

Support for SHA-256 and SHA-512 hashing algorithms.

• index.json
  • Resolve by image reference via org.opencontainers.image.ref.name
  • Resolve by digest
  • Resolve through custom logic
• oci-layout
• blobs directory
  • Remove blob by descriptor
  • Remove image/artifact by digest/reference
  • Garbage collection

Concurrency

Changes to the concurrency API of koci are currently subject to change at any time.

For now, it is best to run operations that could interfere (images sharing layers) sequentially.

Contributing

See CONTRIBUTING.md.

Code of Conduct

See CODE_OF_CONDUCT.md.

Special Thanks

• Distribution Spec authors
• oras-go authors
• ktor authors