https://github.com/cmdjulian/kirc
Sync / Coroutines / Reactive Container Registry Client written in Kotlin ready for GraalVM 🐋
https://github.com/cmdjulian/kirc
coroutines docker fuel java jvm kotlin oci projectreactor reactive registry
Last synced: 9 months ago
JSON representation
Sync / Coroutines / Reactive Container Registry Client written in Kotlin ready for GraalVM 🐋
- Host: GitHub
- URL: https://github.com/cmdjulian/kirc
- Owner: cmdjulian
- License: mit
- Created: 2022-08-14T09:38:52.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-23T17:33:39.000Z (about 1 year ago)
- Last Synced: 2024-10-24T01:27:23.553Z (about 1 year ago)
- Topics: coroutines, docker, fuel, java, jvm, kotlin, oci, projectreactor, reactive, registry
- Language: Kotlin
- Homepage: https://github.com/opencontainers/distribution-spec/blob/main/spec.md#pull
- Size: 1.82 MB
- Stars: 10
- Watchers: 0
- Forks: 0
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://jitpack.io/#cmdjulian/kirc)
# kirc - (k)container image registry client
Kotlin client utilizing CoRoutines and Fuel to interact with the Container Registry API V2.
It supports all the read operations from the spec and can not only handle docker format but also oci.
The library is compatible with GraalVM and does already include the required reflection configs.
## Overview
A client can be obtained by the factory pattern from `{MODULE}ContainerImageClientFactory`.
After initializing the client, we can also pin it to a specific container image (repository and reference like Tag or
Digest) and make it an `ContainerImageClient` with the `.toImageClient()` function. This client is then used to interact
with a specific Image and provides some Image specific functions like the compressed size.
The library throws a dedicated error type to report back on exceptions for the different calls. It wraps a specific
instance of `RegistryClientException` for all errors. These errors are than divided into
1. a more general `ClientErrorException` like if a manifest was tried to be retrieved but didn't exist
(`ClientErrorException.NotFoundException`)
2. network related errors (`NetworkError`) like HostNotFound or SSL related errors
3. unexpected errors (`UnknownError`)
As authentication schema JWT auth and BasicAuth are supported. Currently, there are no plans to implement certificate
based authentication.
The Registry communication can be done using either `HTTP` or `HTTPS`. The library is also able to use a proxy for the
communication.
## Functionality
### Implemented
- ping
- list images
- list tags
- retrieve blob
- exists manifest
- retrieve manifest
- delete manifest
- download image
- inspect image
## Modules
The lib is published in three different flavors. All of them are based up on kotlins coroutines. All modules
transitively include the [suspending module](#suspending).
### Blocking
This module provides as the main entry point as `BlockingClientFactory`. All requests are blocking the current Thread.
Gradle
```groovy
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
implementation 'com.github.cmdjulian.kirc:blocking:{VERSION}'
}
```
Gradle Kts
```kotlin
repositories {
maven(url = "https://jitpack.io")
}
dependencies {
implementation("com.github.cmdjulian.kirc:blocking:{VERSION}")
}
```
Maven
```xml
...
jitpack.io
https://jitpack.io
...
com.github.cmdjulian.kirc
blocking
{VERSION}
```
### Reactive
This module provides as the main entry point as `ReactiveClientFactory`. It uses the kotlin extension functions to
return project reactor types.
Gradle
```groovy
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
implementation 'com.github.cmdjulian.kirc:reactive:{VERSION}'
}
```
Gradle Kts
```kotlin
repositories {
maven(url = "https://jitpack.io")
}
dependencies {
implementation("com.github.cmdjulian.kirc:reactive:{VERSION}")
}
```
Maven
```xml
...
jitpack.io
https://jitpack.io
...
com.github.cmdjulian.kirc
reactive
{VERSION}
```
### Suspending
This module provides as the main entry point as `SuspendingClientFactory`. It uses the kotlin coroutines to do the
requests.
Gradle
```groovy
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
implementation 'com.github.cmdjulian.kirc:suspending:{VERSION}'
}
```
Gradle Kts
```kotlin
repositories {
maven(url = "https://jitpack.io")
}
dependencies {
implementation("com.github.cmdjulian.kirc:suspending:{VERSION}")
}
```
Maven
```xml
...
jitpack.io
https://jitpack.io
...
com.github.cmdjulian.kirc
suspending
{VERSION}
```
### Image
This module is transitively included from all the above modules. It's main purpose is to provide the components to parse
container image names. It's mainly packaged in its own module to be included without any of the aforementioned modules.
Gradle
```groovy
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
implementation 'com.github.cmdjulian.kirc:image:{VERSION}'
}
```
Gradle Kts
```kotlin
repositories {
maven(url = "https://jitpack.io")
}
dependencies {
implementation("com.github.cmdjulian.kirc:image:{VERSION}")
}
```
Maven
```xml
...
jitpack.io
https://jitpack.io
...
com.github.cmdjulian.kirc
image
{VERSION}
```