Provide Okio adapters (#420)

Created a new `kotlinx-io-okio` module that adapts:
- `kotlinx.io.RawSource` to `okio.Source` and vice versa;
- `kotlinx.io.RawSink` to `okio.Sink` and vice versa;
- `kotlinx.io.bytestring.ByteString` to `okio.ByteString` and vice versa.

The module will be published only for targets supported by Okio.

Closes #178

Author: fzhinkin

README.md

@@ -28,9 +28,10 @@ which includes the `FileSystem` interface and its default implementation - `Syst
 
 `FileSystem` provides basic operations for working with files and directories, which are represented by yet another class under the same package - `Path`.
 
-There are two `kotlinx-io` modules:
+There are several `kotlinx-io` modules:
 - [kotlinx-io-bytestring](./bytestring) - provides `ByteString`.
 - [kotlinx-io-core](./core) - provides IO primitives (`Buffer`, `Source`, `Sink`), filesystems support, depends on `kotlinx-io-bytestring`.
+- [kotlinx-io-okio](./integration/okio) - bridges `kotlinx-io` and `Okio` `ByteString`, `kotlinx.io.RawSource` and `okio.Source`, `kotlinx.io.RawSink` and `okio.Sink`. 
 
 ## Using in your projects
 
@@ -81,6 +82,7 @@ Add the library to dependencies:
 On JVM, `kotlinx-io` supports Java Modules:
 - `kotlinx-io-bytestring` library provides `kotlinx.io.bytestring` module; 
 - `kotlinx-io-core` library provides `kotlinx.io.core` module.
+- `kotlinx-io-okio` library provides `kotlinx.io.okio` module.
 
 Read [this](https://kotlinlang.org/docs/gradle-configure-project.html#configure-with-java-modules-jpms-enabled) article 
 for details on how to configure a Gradle project to utilize JPMS.

build-logic/src/main/kotlin/kotlinx/io/conventions/kotlinx-io-multiplatform.gradle.kts

@@ -145,6 +145,8 @@ fun KotlinSourceSet.configureSourceSet() {
 }
 
 private fun KotlinMultiplatformExtension.nativeTargets() {
+    val configureAllTargets = project.findProperty("kotlinx.io.okio.compat.targets")?.toString()?.toBoolean() != true
+
     iosX64()
     iosArm64()
     iosSimulatorArm64()
@@ -159,15 +161,19 @@ private fun KotlinMultiplatformExtension.nativeTargets() {
     watchosSimulatorArm64()
     watchosDeviceArm64()
 
-    androidNativeArm32()
-    androidNativeArm64()
-    androidNativeX64()
-    androidNativeX86()
+    if (configureAllTargets) {
+        androidNativeArm32()
+        androidNativeArm64()
+        androidNativeX64()
+        androidNativeX86()
+    }
 
     linuxX64()
     linuxArm64()
-    @Suppress("DEPRECATION") // https://github.com/Kotlin/kotlinx-io/issues/303
-    linuxArm32Hfp()
+    if (configureAllTargets) {
+        @Suppress("DEPRECATION") // https://github.com/Kotlin/kotlinx-io/issues/303
+        linuxArm32Hfp()
+    }
 
     macosX64()
     macosArm64()

build.gradle.kts

@@ -33,6 +33,7 @@ apiValidation {
 dependencies {
     kover(project(":kotlinx-io-core"))
     kover(project(":kotlinx-io-bytestring"))
+    kover(project(":kotlinx-io-okio"))
 }
 
 kover {

core/api/kotlinx-io-core.klib.api

@@ -197,6 +197,7 @@ open class kotlinx.io.files/FileNotFoundException : kotlinx.io/IOException { //
 open class kotlinx.io/EOFException : kotlinx.io/IOException { // kotlinx.io/EOFException|null[0]
     constructor <init>() // kotlinx.io/EOFException.<init>|<init>(){}[0]
     constructor <init>(kotlin/String?) // kotlinx.io/EOFException.<init>|<init>(kotlin.String?){}[0]
+    constructor <init>(kotlin/String?, kotlin/Throwable?) // kotlinx.io/EOFException.<init>|<init>(kotlin.String?;kotlin.Throwable?){}[0]
 }
 
 open class kotlinx.io/IOException : kotlin/Exception { // kotlinx.io/IOException|null[0]

core/js/src/-PlatformJs.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2010-2023 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Copyright 2010-2024 JetBrains s.r.o. and Kotlin Programming Language contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE.txt file.
  */
 
@@ -19,6 +19,8 @@ public actual open class EOFException : IOException {
     public actual constructor() : super()
 
     public actual constructor(message: String?) : super(message)
+
+    public constructor(message: String?, cause: Throwable?) : super(message, cause)
 }
 
 internal actual fun withCaughtException(block: () -> Unit): Throwable? {

core/native/src/-NonJvmPlatform.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2023 JetBrains s.r.o. and respective authors and developers.
+ * Copyright 2017-2024 JetBrains s.r.o. and respective authors and developers.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the LICENCE file.
  */
 
@@ -34,4 +34,6 @@ public actual open class EOFException : IOException {
     public actual constructor() : super()
 
     public actual constructor(message: String?) : super(message)
+
+    public constructor(message: String?, cause: Throwable?) : super(message, cause)
 }

core/wasm/src/-PlatformWasm.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2010-2023 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Copyright 2010-2024 JetBrains s.r.o. and Kotlin Programming Language contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE.txt file.
  */
 
@@ -19,4 +19,6 @@ public actual open class EOFException : IOException {
     public actual constructor() : super()
 
     public actual constructor(message: String?) : super(message)
+
+    public constructor(message: String?, cause: Throwable?) : super(message, cause)
 }

gradle/libs.versions.toml

@@ -9,6 +9,7 @@ benchmark = "0.4.11"
 jmh = "1.37"
 coroutines = "1.7.3"
 animalsniffer = "1.7.1"
+okio = "3.9.1"
 
 [libraries]
 
@@ -17,6 +18,7 @@ kotlin-gradle-plugin = { group = "org.jetbrains.kotlin", name = "kotlin-gradle-p
 dokka-gradle-plugin = { group = "org.jetbrains.dokka", name = "dokka-gradle-plugin", version.ref = "dokka" }
 kotlinx-coroutines-core = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-core", version.ref = "coroutines" }
 animalsniffer-gradle-plugin = { group = "ru.vyarus", name = "gradle-animalsniffer-plugin", version.ref = "animalsniffer" }
+okio = { group = "com.squareup.okio", name = "okio", version.ref = "okio" }
 
 [plugins]
 

integration/kotlinx-io-okio/Module.md

@@ -0,0 +1,27 @@
+# Module kotlinx-io-okio
+
+The module bridges `Okio` `3.x` interfaces with `kotlinx-io` and vice versa.
+
+[okio.Source] could be wrapped into [kotlinx.io.RawSource]
+using [kotlinx.io.okio.asKotlinxIoRawSource], and [kotlinx.io.RawSource]
+could be wrapped into [okio.Source] using [kotlinx.io.okio.asOkioSource].
+
+Similar pair of functions is also defined for [okio.Sink]
+and [kotlinx.io.RawSink]: [kotlinx.io.okio.asKotlinxIoRawSink], [kotlinx.io.okio.asOkioSink].
+
+Wrappers translate IO-exceptions thrown from an underlying library into exceptions provided by a wrapping library.
+I.e, if an [okio.Source] wrapped into [kotlinx.io.RawSource]
+throws [okio.IOException]
+during [kotlinx.io.RawSource.readAtMostTo] (or any other) call, that exception will be caught and a [kotlinx.io.IOException] will be thrown.
+The same translation is performed in the opposite direction as well.
+
+`ByteString` classes provided by both libraries could also be converted one into another: [kotlinx.io.okio.toKotlinxIoByteString],
+[kotlinx.io.okio.toOkioByteString].
+
+# Package kotlinx.io.okio
+
+`kotlinx-io` <-> `Okio` adapters.
+
+#### Thread-safety guarantees
+
+Until stated otherwise, types and functions provided by the library are not thread safe.

integration/kotlinx-io-okio/api/kotlinx-io-okio.api

@@ -0,0 +1,9 @@
+public final class kotlinx/io/okio/OkioAdaptersKt {
+	public static final fun asKotlinxIoRawSink (Lokio/Sink;)Lkotlinx/io/RawSink;
+	public static final fun asKotlinxIoRawSource (Lokio/Source;)Lkotlinx/io/RawSource;
+	public static final fun asOkioSink (Lkotlinx/io/RawSink;)Lokio/Sink;
+	public static final fun asOkioSource (Lkotlinx/io/RawSource;)Lokio/Source;
+	public static final fun toKotlinxIoByteString (Lokio/ByteString;)Lkotlinx/io/bytestring/ByteString;
+	public static final fun toOkioByteString (Lkotlinx/io/bytestring/ByteString;)Lokio/ByteString;
+}
+