Skip to content

Multiplatform docker cp implementation #212

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
devnatan merged 19 commits into from
Dec 30, 2025
Merged

Multiplatform docker cp implementation #212

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
8d776ab
Create tar entry manipulation utils
devnatan Dec 30, 2025
7946526
Write TarUtils tests
devnatan Dec 30, 2025
d06e788
Add `ContainerCopyOptions` model for container file copy operations
devnatan Dec 30, 2025
d54319f
Add `ContainerCopyResult` model for container file copy operations
devnatan Dec 30, 2025
f3beb5c
Update `ContainerArchiveInfo` model to include serial names and use c…
devnatan Dec 30, 2025
a148b12
Add `FileSystemUtils` for multiplatform file operations
devnatan Dec 30, 2025
dc3a544
Add `TarOperations` for creating and extracting tar archives
devnatan Dec 30, 2025
44a52c0
Refactor container file operations to add `copyTo`, `copyFrom`, and r…
devnatan Dec 30, 2025
7cb086b
Add `ArchiveNotFoundException` for handling missing container archive…
devnatan Dec 30, 2025
a2ff710
Rename `archive` to `copyFrom`
devnatan Dec 30, 2025
541af74
Implement `copyTo` consistently and helper functions
devnatan Dec 30, 2025
bcbc123
Remove old readTarFile and writeTarFile
devnatan Dec 30, 2025
d7b68f8
Create tests for copy methods
devnatan Dec 30, 2025
afd773c
Create extensions
devnatan Dec 30, 2025
a142c18
Update README.md examples
devnatan Dec 30, 2025
b868cd6
Add missing methods to ContainerResource.native.kt
devnatan Dec 30, 2025
e81bfac
Update .api
devnatan Dec 30, 2025
7837d50
Update README.md
devnatan Dec 30, 2025
10eab0f
Update README.md
devnatan Dec 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
175 changes: 161 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ dependencies {

## Basic Usage

Use `DockerKotlin.create()` to create a new Docker client instance with the default settings, default settings are based on the
Use `DockerKotlin.create()` to create a new Docker client instance with the default settings, default settings are based on the
current platform or environment variables, e.g.: socket path will be set to [`DOCKER_HOST`](https://docs.docker.com/compose/environment-variables/envvars/#docker_host)
if present otherwise `unix://var/run/docker.sock` if the current platform is Unix-like.

Expand All @@ -28,13 +28,25 @@ val client = DockerClient {
}
```

##### Get System Information

## Resources

* [System](#system)
* [Containers](#containers)
* [Networks](#networks)
* [Exec](#exec)

### System

#### Get Docker Version

```kotlin
val version: SystemVersion = client.system.version()
```

##### Create and start a Container with explicit port bindings
### Containers

#### Create and start a Container with explicit port bindings

```kotlin
val containerId = client.containers.create("busybox:latest") {
Expand All @@ -51,7 +63,7 @@ val containerId = client.containers.create("busybox:latest") {
client.containers.start(containerId)
```

##### Create and start a Container with auto-assigned port bindings
#### Create and start a Container with auto-assigned port bindings

```kotlin
val containerId = client.containers.create("busybox:latest") {
Expand All @@ -70,13 +82,29 @@ val container = testClient.containers.inspect(id)
val ports = container.networkSettings.ports
```

##### List All Containers
#### List All Containers

```kotlin
val containers: List<Container> = client.containers.list()
```

##### Create a new Network
#### Stream Container Logs

```kotlin
val logs: Flow<Frame> = client.containers.logs("floral-fury") {
stderr = true
stdout = true
}

logs.onStart { /* streaming started */ }
.onCompletion { /* streaming finished */ }
.catch { /* something went wrong */ }
.collect { log -> /* do something with each log */ }
```

### Networks

#### Create a new Network

```kotlin
val networkId: String = client.networks.create {
Expand All @@ -85,18 +113,137 @@ val networkId: String = client.networks.create {
}
```

##### Stream Container Logs
#### List all Networks
```kotlin
val networks = client.networks.list()
```

#### Connect a container to a network
```kotlin
val logs: Flow<Frame> = client.containers.logs("floral-fury") {
stderr = true
stdout = true
client.networks.connect(networkId, containerId)
```

### Exec

#### Execute a command in a running container
```kotlin
val execId = client.exec.create(containerId) {
command = listOf("echo", "Hello, Docker!")
attachStdout = true
}

logs.onStart { /* streaming started */ }
.onCompletion { /* streaming finished */ }
.catch { /* something went wrong */ }
.collect { log -> /* do something with each log */ }
val result = client.exec.start(execId, ExecStartOptions())
when (result) {
is ExecStartResult.Complete -> println(result.output)
else -> error("Unexpected result")
}
```

#### Execute a command with streaming output
```kotlin
val execId = client.exec.create(containerId) {
command = listOf("sh", "-c", "for i in 1 2 3; do echo line \$i; sleep 1; done")
attachStdout = true
}

val result = client.exec.start(execId) { stream = true }
when (result) {
is ExecStartResult.Stream -> {
result.output.collect { chunk ->
print(chunk)
}
}
else -> error("Unexpected result")
}
```

#### Execute a command with separated stdout/stderr
```kotlin
val execId = client.exec.create(containerId) {
command = listOf("sh", "-c", "echo stdout; echo stderr >&2")
attachStdout = true
attachStderr = true
}

val result = client.exec.start(execId) { demux = true }
when (result) {
is ExecStartResult.CompleteDemuxed -> {
println("STDOUT: ${result.output.stdout}")
println("STDERR: ${result.output.stderr}")
}
else -> error("Unexpected result")
}
```

#### Check exec exit code
```kotlin
val execId = client.exec.create(containerId) {
command = listOf("false")
}

client.exec.start(execId) { detach = true }

val execInfo = client.exec.inspect(execId)
println("Exit code: ${execInfo.exitCode}") // Exit code: 1
```

### File Operations

#### Copy a file from container to host
```kotlin
client.containers.copyFileFrom(
containerId,
sourcePath = "/var/log/app.log",
destinationPath = "/tmp/app.log"
)
```

##### Copy a file from host to container
```kotlin
client.containers.copyFileTo(
containerId,
sourcePath = "/home/user/config.json",
destinationPath = "/app/config/"
)
```

#### Copy a directory from container to host
```kotlin
client.containers.copyDirectoryFrom(
containerId,
sourcePath = "/app/logs",
destinationPath = "/tmp/container-logs"
)
```

#### Copy a directory from host to container
```kotlin
client.containers.copyDirectoryTo(
containerId,
sourcePath = "/home/user/configs",
destinationPath = "/app/"
)
```

#### Advanced copy with custom options
```kotlin
// Copy with custom options
client.containers.copy.copyTo(
container = containerId,
destinationPath = "/app/data",
tarArchive = myTarArchive
) {
path = "/app/data"
noOverwriteDirNonDir = true // Don't overwrite if types mismatch
copyUIDGID = true // Preserve UID/GID
}

// Get raw tar archive from container
val result = client.containers.copyFrom(containerId, "/app/config")
val tarData = result.archiveData

// Archive info including file metadata
val stats = result.stat
```

## License
Expand Down
117 changes: 106 additions & 11 deletions api/docker-kotlin.api
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,37 @@ public final class me/devnatan/dockerkt/io/SocketUtils {
public static final field DefaultDockerUnixSocket Ljava/lang/String;
}

public final class me/devnatan/dockerkt/io/TarEntry {
public fun <init> (Ljava/lang/String;JJJZ[B)V
public synthetic fun <init> (Ljava/lang/String;JJJZ[BILkotlin/jvm/internal/DefaultConstructorMarker;)V
public final fun component1 ()Ljava/lang/String;
public final fun component2 ()J
public final fun component3 ()J
public final fun component4 ()J
public final fun component5 ()Z
public final fun component6 ()[B
public final fun copy (Ljava/lang/String;JJJZ[B)Lme/devnatan/dockerkt/io/TarEntry;
public static synthetic fun copy$default (Lme/devnatan/dockerkt/io/TarEntry;Ljava/lang/String;JJJZ[BILjava/lang/Object;)Lme/devnatan/dockerkt/io/TarEntry;
public fun equals (Ljava/lang/Object;)Z
public final fun getData ()[B
public final fun getMode ()J
public final fun getMtime ()J
public final fun getName ()Ljava/lang/String;
public final fun getSize ()J
public fun hashCode ()I
public final fun isDirectory ()Z
public fun toString ()Ljava/lang/String;
}

public final class me/devnatan/dockerkt/io/TarOperations {
public static final field INSTANCE Lme/devnatan/dockerkt/io/TarOperations;
public final fun collectDirectoryContents (Lkotlinx/io/files/Path;Ljava/lang/String;Ljava/util/List;)V
public final fun createTarFromDirectory (Lkotlinx/io/files/Path;Ljava/lang/String;)[B
public static synthetic fun createTarFromDirectory$default (Lme/devnatan/dockerkt/io/TarOperations;Lkotlinx/io/files/Path;Ljava/lang/String;ILjava/lang/Object;)[B
public final fun createTarFromFile (Lkotlinx/io/files/Path;)[B
public final fun extractTar ([BLkotlinx/io/files/Path;)V
}

public final class me/devnatan/dockerkt/models/BlkioWeightDevice {
public static final field Companion Lme/devnatan/dockerkt/models/BlkioWeightDevice$Companion;
public fun <init> (Ljava/lang/String;I)V
Expand Down Expand Up @@ -1290,19 +1321,19 @@ public final class me/devnatan/dockerkt/models/container/Container$Companion {

public final class me/devnatan/dockerkt/models/container/ContainerArchiveInfo {
public static final field Companion Lme/devnatan/dockerkt/models/container/ContainerArchiveInfo$Companion;
public fun <init> (Ljava/lang/String;JILjava/lang/String;Ljava/lang/String;)V
public synthetic fun <init> (Ljava/lang/String;JILjava/lang/String;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
public fun <init> (Ljava/lang/String;JJLjava/lang/String;Ljava/lang/String;)V
public synthetic fun <init> (Ljava/lang/String;JJLjava/lang/String;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
public final fun component1 ()Ljava/lang/String;
public final fun component2 ()J
public final fun component3 ()I
public final fun component3 ()J
public final fun component4 ()Ljava/lang/String;
public final fun component5 ()Ljava/lang/String;
public final fun copy (Ljava/lang/String;JILjava/lang/String;Ljava/lang/String;)Lme/devnatan/dockerkt/models/container/ContainerArchiveInfo;
public static synthetic fun copy$default (Lme/devnatan/dockerkt/models/container/ContainerArchiveInfo;Ljava/lang/String;JILjava/lang/String;Ljava/lang/String;ILjava/lang/Object;)Lme/devnatan/dockerkt/models/container/ContainerArchiveInfo;
public final fun copy (Ljava/lang/String;JJLjava/lang/String;Ljava/lang/String;)Lme/devnatan/dockerkt/models/container/ContainerArchiveInfo;
public static synthetic fun copy$default (Lme/devnatan/dockerkt/models/container/ContainerArchiveInfo;Ljava/lang/String;JJLjava/lang/String;Ljava/lang/String;ILjava/lang/Object;)Lme/devnatan/dockerkt/models/container/ContainerArchiveInfo;
public fun equals (Ljava/lang/Object;)Z
public final fun getLinkTarget ()Ljava/lang/String;
public final fun getMode ()I
public final fun getModifiedAtRaw ()Ljava/lang/String;
public final fun getMode ()J
public final fun getModifiedAtMillis ()Ljava/lang/String;
public final fun getName ()Ljava/lang/String;
public final fun getSize ()J
public fun hashCode ()I
Expand Down Expand Up @@ -1405,6 +1436,57 @@ public final class me/devnatan/dockerkt/models/container/ContainerConfig$Compani
public final fun serializer ()Lkotlinx/serialization/KSerializer;
}

public final class me/devnatan/dockerkt/models/container/ContainerCopyOptions {
public static final field Companion Lme/devnatan/dockerkt/models/container/ContainerCopyOptions$Companion;
public fun <init> (Ljava/lang/String;ZZZ)V
public synthetic fun <init> (Ljava/lang/String;ZZZILkotlin/jvm/internal/DefaultConstructorMarker;)V
public final fun component1 ()Ljava/lang/String;
public final fun component2 ()Z
public final fun component3 ()Z
public final fun component4 ()Z
public final fun copy (Ljava/lang/String;ZZZ)Lme/devnatan/dockerkt/models/container/ContainerCopyOptions;
public static synthetic fun copy$default (Lme/devnatan/dockerkt/models/container/ContainerCopyOptions;Ljava/lang/String;ZZZILjava/lang/Object;)Lme/devnatan/dockerkt/models/container/ContainerCopyOptions;
public fun equals (Ljava/lang/Object;)Z
public final fun getCopyUIDGID ()Z
public final fun getExtractArchive ()Z
public final fun getNoOverwriteDirNonDir ()Z
public final fun getPath ()Ljava/lang/String;
public fun hashCode ()I
public final fun setCopyUIDGID (Z)V
public final fun setExtractArchive (Z)V
public final fun setNoOverwriteDirNonDir (Z)V
public final fun setPath (Ljava/lang/String;)V
public fun toString ()Ljava/lang/String;
}

public final synthetic class me/devnatan/dockerkt/models/container/ContainerCopyOptions$$serializer : kotlinx/serialization/internal/GeneratedSerializer {
public static final field INSTANCE Lme/devnatan/dockerkt/models/container/ContainerCopyOptions$$serializer;
public final fun childSerializers ()[Lkotlinx/serialization/KSerializer;
public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
public final fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lme/devnatan/dockerkt/models/container/ContainerCopyOptions;
public final fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
public final fun serialize (Lkotlinx/serialization/encoding/Encoder;Lme/devnatan/dockerkt/models/container/ContainerCopyOptions;)V
public fun typeParametersSerializers ()[Lkotlinx/serialization/KSerializer;
}

public final class me/devnatan/dockerkt/models/container/ContainerCopyOptions$Companion {
public final fun serializer ()Lkotlinx/serialization/KSerializer;
}

public final class me/devnatan/dockerkt/models/container/ContainerCopyResult {
public fun <init> ([BLme/devnatan/dockerkt/models/container/ContainerArchiveInfo;)V
public final fun component1 ()[B
public final fun component2 ()Lme/devnatan/dockerkt/models/container/ContainerArchiveInfo;
public final fun copy ([BLme/devnatan/dockerkt/models/container/ContainerArchiveInfo;)Lme/devnatan/dockerkt/models/container/ContainerCopyResult;
public static synthetic fun copy$default (Lme/devnatan/dockerkt/models/container/ContainerCopyResult;[BLme/devnatan/dockerkt/models/container/ContainerArchiveInfo;ILjava/lang/Object;)Lme/devnatan/dockerkt/models/container/ContainerCopyResult;
public fun equals (Ljava/lang/Object;)Z
public final fun getArchiveData ()[B
public final fun getStat ()Lme/devnatan/dockerkt/models/container/ContainerArchiveInfo;
public fun hashCode ()I
public fun toString ()Ljava/lang/String;
}

public final class me/devnatan/dockerkt/models/container/ContainerCreateOptions {
public static final field Companion Lme/devnatan/dockerkt/models/container/ContainerCreateOptions$Companion;
public fun <init> ()V
Expand Down Expand Up @@ -3858,6 +3940,11 @@ public final class me/devnatan/dockerkt/resource/ResourcePaths {
public static final field INSTANCE Lme/devnatan/dockerkt/resource/ResourcePaths;
}

public final class me/devnatan/dockerkt/resource/container/ArchiveNotFoundException : me/devnatan/dockerkt/resource/container/ContainerException {
public final fun getContainerId ()Ljava/lang/String;
public final fun getSourcePath ()Ljava/lang/String;
}

public final class me/devnatan/dockerkt/resource/container/ContainerAlreadyExistsException : me/devnatan/dockerkt/resource/container/ContainerException {
public final fun getName ()Ljava/lang/String;
}
Expand Down Expand Up @@ -3892,12 +3979,18 @@ public final class me/devnatan/dockerkt/resource/container/ContainerRenameConfli

public final class me/devnatan/dockerkt/resource/container/ContainerResource {
public fun <init> (Lkotlinx/coroutines/CoroutineScope;Lkotlinx/serialization/json/Json;Lio/ktor/client/HttpClient;)V
public final fun archive (Ljava/lang/String;Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static synthetic fun archive$default (Lme/devnatan/dockerkt/resource/container/ContainerResource;Ljava/lang/String;Ljava/lang/String;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
public final synthetic fun attach (Ljava/lang/String;)Lkotlinx/coroutines/flow/Flow;
public final fun copyDirectoryFrom (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public final fun copyDirectoryTo (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lme/devnatan/dockerkt/models/container/ContainerCopyOptions;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static synthetic fun copyDirectoryTo$default (Lme/devnatan/dockerkt/resource/container/ContainerResource;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lme/devnatan/dockerkt/models/container/ContainerCopyOptions;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
public final fun copyFileFrom (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public final fun copyFileTo (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lme/devnatan/dockerkt/models/container/ContainerCopyOptions;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static synthetic fun copyFileTo$default (Lme/devnatan/dockerkt/resource/container/ContainerResource;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lme/devnatan/dockerkt/models/container/ContainerCopyOptions;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
public final fun copyFrom (Ljava/lang/String;Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public final fun copyTo (Ljava/lang/String;Ljava/lang/String;[BLme/devnatan/dockerkt/models/container/ContainerCopyOptions;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static synthetic fun copyTo$default (Lme/devnatan/dockerkt/resource/container/ContainerResource;Ljava/lang/String;Ljava/lang/String;[BLme/devnatan/dockerkt/models/container/ContainerCopyOptions;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
public final synthetic fun create (Lme/devnatan/dockerkt/models/container/ContainerCreateOptions;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public final fun createAsync (Lme/devnatan/dockerkt/models/container/ContainerCreateOptions;)Ljava/util/concurrent/CompletableFuture;
public final fun downloadArchive (Ljava/lang/String;Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public final synthetic fun inspect (Ljava/lang/String;ZLkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static synthetic fun inspect$default (Lme/devnatan/dockerkt/resource/container/ContainerResource;Ljava/lang/String;ZLkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
public final fun inspectAsync (Ljava/lang/String;)Ljava/util/concurrent/CompletableFuture;
Expand Down Expand Up @@ -3948,7 +4041,6 @@ public final class me/devnatan/dockerkt/resource/container/ContainerResource {
public final fun stopAsync (Ljava/lang/String;I)Ljava/util/concurrent/CompletableFuture;
public final synthetic fun unpause (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public final fun unpauseAsync (Ljava/lang/String;)Ljava/util/concurrent/CompletableFuture;
public final fun uploadArchive (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public final synthetic fun wait (Ljava/lang/String;Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static synthetic fun wait$default (Lme/devnatan/dockerkt/resource/container/ContainerResource;Ljava/lang/String;Ljava/lang/String;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
public final fun waitAsync (Ljava/lang/String;)Ljava/util/concurrent/CompletableFuture;
Expand All @@ -3957,6 +4049,9 @@ public final class me/devnatan/dockerkt/resource/container/ContainerResource {
}

public final class me/devnatan/dockerkt/resource/container/ContainerResourceExtKt {
public static final fun copyDirectoryTo (Lme/devnatan/dockerkt/resource/container/ContainerResource;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lkotlin/jvm/functions/Function1;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static final fun copyFileTo (Lme/devnatan/dockerkt/resource/container/ContainerResource;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lkotlin/jvm/functions/Function1;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static final fun copyTo (Lme/devnatan/dockerkt/resource/container/ContainerResource;Ljava/lang/String;Ljava/lang/String;[BLkotlin/jvm/functions/Function1;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static final fun create (Lme/devnatan/dockerkt/resource/container/ContainerResource;Lkotlin/jvm/functions/Function1;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static final fun list (Lme/devnatan/dockerkt/resource/container/ContainerResource;Lkotlin/jvm/functions/Function1;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static final fun logs (Lme/devnatan/dockerkt/resource/container/ContainerResource;Ljava/lang/String;)Lkotlinx/coroutines/flow/Flow;
Expand Down
Loading
Loading