Initial APIs for FileSystem extensions

Closes: #1466

okio/build.gradle.kts

@@ -66,6 +66,7 @@ kotlin {
       dependencies {
         implementation(libs.kotlin.test)
         implementation(projects.okioTestingSupport)
+        implementation(projects.okioFakefilesystem)
       }
     }
 
@@ -80,7 +81,6 @@ kotlin {
     val nonWasmTest by creating {
       dependencies {
         implementation(libs.kotlin.time)
-        implementation(projects.okioFakefilesystem)
       }
     }
 

okio/src/commonMain/kotlin/okio/FileSystem.kt

@@ -15,6 +15,8 @@
  */
 package okio
 
+import kotlin.reflect.KClass
+
 /**
  * Read and write access to a hierarchical collection of files, addressed by [paths][Path]. This
  * is a natural interface to the current computer's local file system.
@@ -376,6 +378,10 @@ expect abstract class FileSystem() {
   @Throws(IOException::class)
   abstract fun createSymlink(source: Path, target: Path)
 
+  open fun <E : FileSystemExtension> extend(extensionType: KClass<E>, extension: E): FileSystem
+
+  open fun <E : FileSystemExtension> extension(type: KClass<E>): E?
+
   companion object {
     /**
      * Returns a writable temporary directory on [SYSTEM].

okio/src/commonMain/kotlin/okio/FileSystemExtension.kt

@@ -0,0 +1,21 @@
+/*
+ * Copyright (C) 2024 Square, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package okio
+
+/**
+ *
+ */
+interface FileSystemExtension

okio/src/commonMain/kotlin/okio/ForwardingFileSystem.kt

@@ -16,6 +16,8 @@
 package okio
 
 import kotlin.jvm.JvmName
+import kotlin.reflect.KClass
+import kotlin.reflect.cast
 
 /**
  * A [FileSystem] that forwards calls to another, intended for subclassing.
@@ -101,11 +103,15 @@ import kotlin.jvm.JvmName
  * other functions of this class. If desired, subclasses may override non-abstract functions to
  * forward them.
  */
-abstract class ForwardingFileSystem(
+open class ForwardingFileSystem internal constructor(
   /** [FileSystem] to which this instance is delegating. */
   @get:JvmName("delegate")
   val delegate: FileSystem,
+  extensions: Map<KClass<*>, Any>,
 ) : FileSystem() {
+  internal val extensions = extensions.toMap()
+
+  constructor(delegate: FileSystem) : this(delegate, emptyMap())
 
   /**
    * Invoked each time a path is passed as a parameter to this file system. This returns the path to
@@ -142,6 +148,8 @@ abstract class ForwardingFileSystem(
    */
   open fun onPathResult(path: Path, functionName: String): Path = path
 
+  open fun <T : Any> onExtension(type: KClass<T>, extension: T): T = extension
+
   @Throws(IOException::class)
   override fun canonicalize(path: Path): Path {
     val path = onPathParameter(path, "canonicalize", "path")
@@ -238,5 +246,13 @@ abstract class ForwardingFileSystem(
     delegate.createSymlink(source, target)
   }
 
+  override fun <E : FileSystemExtension> extension(type: KClass<E>): E? {
+    val result = extensions[type]?.let { type.cast(it) }
+      ?: delegate.extension(type)
+      ?: return null
+
+    return onExtension(type, result)
+  }
+
   override fun toString() = "${this::class.simpleName}($delegate)"
 }

okio/src/commonMain/kotlin/okio/Okio.kt

@@ -72,3 +72,11 @@ inline fun <T : Closeable?, R> T.use(block: (T) -> R): R {
   @Suppress("UNCHECKED_CAST")
   return result as R
 }
+
+inline fun <reified E : FileSystemExtension> FileSystem.extend(extension: E): FileSystem {
+  return extend(E::class, extension)
+}
+
+inline fun <reified E : FileSystemExtension> FileSystem.extension(): E? {
+  return extension(E::class)
+}

okio/src/commonMain/kotlin/okio/internal/FileSystem.kt

@@ -18,9 +18,11 @@
 package okio.internal
 
 import kotlin.jvm.JvmName
+import kotlin.reflect.KClass
 import okio.FileMetadata
 import okio.FileNotFoundException
 import okio.FileSystem
+import okio.ForwardingFileSystem
 import okio.IOException
 import okio.Path
 import okio.buffer
@@ -69,6 +71,23 @@ internal fun FileSystem.commonCopy(source: Path, target: Path) {
   }
 }
 
+fun <T : Any> FileSystem.commonExtend(extensionType: KClass<T>, extension: T): FileSystem {
+  // If this file system is already an extension wrapper, replace it rather than wrapping again.
+  // Note that this optimization doesn't apply to ForwardingFileSystem subclasses, only to the
+  // ForwardingFileSystem base class.
+  if (this::class === ForwardingFileSystem::class) {
+    this as ForwardingFileSystem
+    val newExtensions = extensions.toMutableMap()
+    newExtensions[extensionType] = extension
+    return ForwardingFileSystem(delegate, newExtensions)
+  }
+
+  return ForwardingFileSystem(
+    delegate = this,
+    extensions = mapOf(extensionType to extension)
+  )
+}
+
 @Throws(IOException::class)
 internal fun FileSystem.commonDeleteRecursively(fileOrDirectory: Path, mustExist: Boolean) {
   val sequence = sequence {

okio/src/commonTest/kotlin/okio/FileSystemExtensionsTest.kt

@@ -0,0 +1,55 @@
+/*
+ * Copyright (C) 2024 Square, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package okio
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import okio.fakefilesystem.FakeFileSystem
+
+class FileSystemExtensionsTest {
+  @Test
+  fun happyPath() {
+    val fakeFileSystem = FakeFileSystem()
+    val extension = FooExtension(fakeFileSystem)
+    val fileSystemWithExtension = fakeFileSystem.extend(extension)
+    assertEquals(fileSystemWithExtension.extension<FooExtension>(), extension)
+  }
+
+  @Test
+  fun absentExtension() {
+  }
+
+  @Test
+  fun overrideExtension() {
+  }
+
+  @Test
+  fun forwardingFileSystemCoalesced() {
+  }
+
+  @Test
+  fun customForwardingFileSystemNotCoalesced() {
+  }
+
+  class FooExtension(
+    val target: FileSystem,
+  ) : FileSystemExtension
+
+  class BarExtension(
+    val target: FileSystem,
+  ) : FileSystemExtension
+}

okio/src/jsMain/kotlin/okio/FileSystem.kt

@@ -15,11 +15,13 @@
  */
 package okio
 
+import kotlin.reflect.KClass
 import okio.Path.Companion.toPath
 import okio.internal.commonCopy
 import okio.internal.commonCreateDirectories
 import okio.internal.commonDeleteRecursively
 import okio.internal.commonExists
+import okio.internal.commonExtend
 import okio.internal.commonListRecursively
 import okio.internal.commonMetadata
 
@@ -84,6 +86,13 @@ actual abstract class FileSystem {
 
   actual abstract fun createSymlink(source: Path, target: Path)
 
+  actual open fun <E : FileSystemExtension> extend(
+    extensionType: KClass<E>,
+    extension: E,
+  ): FileSystem = commonExtend(extensionType, extension)
+
+  actual open fun <E : FileSystemExtension> extension(type: KClass<E>): E? = null
+
   actual companion object {
     actual val SYSTEM_TEMPORARY_DIRECTORY: Path = tmpdir.toPath()
   }

okio/src/jvmMain/kotlin/okio/FileSystem.kt

@@ -16,12 +16,14 @@
 package okio
 
 import java.nio.file.FileSystem as JavaNioFileSystem
+import kotlin.reflect.KClass
 import okio.Path.Companion.toPath
 import okio.internal.ResourceFileSystem
 import okio.internal.commonCopy
 import okio.internal.commonCreateDirectories
 import okio.internal.commonDeleteRecursively
 import okio.internal.commonExists
+import okio.internal.commonExtend
 import okio.internal.commonListRecursively
 import okio.internal.commonMetadata
 
@@ -125,6 +127,13 @@ actual abstract class FileSystem {
   @Throws(IOException::class)
   actual abstract fun createSymlink(source: Path, target: Path)
 
+  actual open fun <E : FileSystemExtension> extend(
+    extensionType: KClass<E>,
+    extension: E,
+  ): FileSystem = commonExtend(extensionType, extension)
+
+  actual open fun <E : FileSystemExtension> extension(type: KClass<E>): E? = null
+
   actual companion object {
     /**
      * The current process's host file system. Use this instance directly, or dependency inject a

okio/src/nativeMain/kotlin/okio/FileSystem.kt

@@ -15,10 +15,12 @@
  */
 package okio
 
+import kotlin.reflect.KClass
 import okio.internal.commonCopy
 import okio.internal.commonCreateDirectories
 import okio.internal.commonDeleteRecursively
 import okio.internal.commonExists
+import okio.internal.commonExtend
 import okio.internal.commonListRecursively
 import okio.internal.commonMetadata
 
@@ -102,6 +104,13 @@ actual abstract class FileSystem {
   @Throws(IOException::class)
   actual abstract fun createSymlink(source: Path, target: Path)
 
+  actual open fun <E : FileSystemExtension> extend(
+    extensionType: KClass<E>,
+    extension: E,
+  ): FileSystem = commonExtend(extensionType, extension)
+
+  actual open fun <E : FileSystemExtension> extension(type: KClass<E>): E? = null
+
   actual companion object {
     /**
      * The current process's host file system. Use this instance directly, or dependency inject a

okio/src/wasmMain/kotlin/okio/FileSystem.kt

@@ -15,11 +15,13 @@
  */
 package okio
 
+import kotlin.reflect.KClass
 import okio.Path.Companion.toPath
 import okio.internal.commonCopy
 import okio.internal.commonCreateDirectories
 import okio.internal.commonDeleteRecursively
 import okio.internal.commonExists
+import okio.internal.commonExtend
 import okio.internal.commonListRecursively
 import okio.internal.commonMetadata
 
@@ -84,6 +86,13 @@ actual abstract class FileSystem {
 
   actual abstract fun createSymlink(source: Path, target: Path)
 
+  actual open fun <E : FileSystemExtension> extend(
+    extensionType: KClass<E>,
+    extension: E,
+  ): FileSystem = commonExtend(extensionType, extension)
+
+  actual open fun <E : FileSystemExtension> extension(type: KClass<E>): E? = null
+
   actual companion object {
     actual val SYSTEM_TEMPORARY_DIRECTORY: Path = "/tmp".toPath()
   }