Initial APIs for FileSystem extensions

okio/api/okio.api

@@ -477,6 +477,8 @@ public abstract class okio/FileSystem {
  public fun deleteRecursively (Lokio/Path;Z)V
  public static synthetic fun deleteRecursively$default (Lokio/FileSystem;Lokio/Path;ZILjava/lang/Object;)V
  public final fun exists (Lokio/Path;)Z
+ public fun extend (Lkotlin/reflect/KClass;Lokio/FileSystemExtension;)Lokio/FileSystem;
+ public fun extension (Lkotlin/reflect/KClass;)Lokio/FileSystemExtension;
  public static final fun get (Ljava/nio/file/FileSystem;)Lokio/FileSystem;
  public abstract fun list (Lokio/Path;)Ljava/util/List;
  public abstract fun listOrNull (Lokio/Path;)Ljava/util/List;
@@ -499,7 +501,23 @@ public final class okio/FileSystem$Companion {
  public final fun get (Ljava/nio/file/FileSystem;)Lokio/FileSystem;
 }
 
-public abstract class okio/ForwardingFileSystem : okio/FileSystem {
+public abstract interface class okio/FileSystemExtension {
+ public abstract fun map (Lokio/FileSystemExtension$Mapping;)Lokio/FileSystemExtension;
+}
+
+public abstract class okio/FileSystemExtension$Mapping {
+ public static final field Companion Lokio/FileSystemExtension$Mapping$Companion;
+ public fun <init> ()V
+ public final fun chain (Lokio/FileSystemExtension$Mapping;)Lokio/FileSystemExtension$Mapping;
+ public abstract fun mapParameter (Lokio/Path;Ljava/lang/String;Ljava/lang/String;)Lokio/Path;
+ public abstract fun mapResult (Lokio/Path;Ljava/lang/String;)Lokio/Path;
+}
+
+public final class okio/FileSystemExtension$Mapping$Companion {
+ public final fun getNONE ()Lokio/FileSystemExtension$Mapping;
+}
+
+public class okio/ForwardingFileSystem : okio/FileSystem {
  public fun <init> (Lokio/FileSystem;)V
  public fun appendingSink (Lokio/Path;Z)Lokio/Sink;
  public fun atomicMove (Lokio/Path;Lokio/Path;)V
@@ -508,10 +526,13 @@ public abstract class okio/ForwardingFileSystem : okio/FileSystem {
  public fun createSymlink (Lokio/Path;Lokio/Path;)V
  public final fun delegate ()Lokio/FileSystem;
  public fun delete (Lokio/Path;Z)V
+ public fun extension (Lkotlin/reflect/KClass;)Lokio/FileSystemExtension;
+ public final fun getExtensionMapping ()Lokio/FileSystemExtension$Mapping;
  public fun list (Lokio/Path;)Ljava/util/List;
  public fun listOrNull (Lokio/Path;)Ljava/util/List;
  public fun listRecursively (Lokio/Path;Z)Lkotlin/sequences/Sequence;
  public fun metadataOrNull (Lokio/Path;)Lokio/FileMetadata;
+ public fun onExtension (Lkotlin/reflect/KClass;Lokio/FileSystemExtension;)Lokio/FileSystemExtension;
  public fun onPathParameter (Lokio/Path;Ljava/lang/String;Ljava/lang/String;)Lokio/Path;
  public fun onPathResult (Lokio/Path;Ljava/lang/String;)Lokio/Path;
  public fun openReadOnly (Lokio/Path;)Lokio/FileHandle;
@@ -819,6 +840,10 @@ public final class okio/_JvmPlatformKt {
  public static final fun withLock (Ljava/util/concurrent/locks/ReentrantLock;Lkotlin/jvm/functions/Function0;)Ljava/lang/Object;
 }
 
+public final class okio/internal/-FileSystem {
+ public static final fun commonExtend (Lokio/FileSystem;Lkotlin/reflect/KClass;Ljava/lang/Object;)Lokio/FileSystem;
+}
+
 public final class okio/internal/_Utf8Kt {
  public static final fun commonAsUtf8ToByteArray (Ljava/lang/String;)[B
  public static final fun commonToUtf8String ([BII)Ljava/lang/String;

okio/build.gradle.kts

@@ -79,6 +79,7 @@ kotlin {
 
  val nonWasmTest by creating {
  dependencies {
+ implementation(libs.kotlin.test)
  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,18 @@ expect abstract class FileSystem() {
  @Throws(IOException::class)
  abstract fun createSymlink(source: Path, target: Path)
 
+ /**
+ * Returns a new file system that forwards all calls to this, and that also returns [extension]
+ * when it is requested.
+ *
+ * When [extensionType] is requested on the returned file system, it will return [extension],
+ * regardless of what is returned by this file system.
+ */
+ open fun <E : FileSystemExtension> extend(extensionType: KClass<E>, extension: E): FileSystem
+
+ /** Returns the extension for [type] if it exists, and null otherwise. */
+ 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,93 @@
+/*
+ * 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:https://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 okio.FileSystemExtension.Mapping
+
+/**
+ * Marks an object that can be attached to a [FileSystem], and that supplements the file system's
+ * capabilities.
+ *
+ * Implementations must support transforms to input and output paths with [Mapping]. To simplify
+ * implementation, use [Mapping.NONE] by default and use [Mapping.chain] to combine mappings.
+ *
+ * ```kotlin
+ * class DiskUsageExtension private constructor(
+ * private val mapping: Mapping,
+ * ) : FileSystemExtension {
+ * constructor() : this(Mapping.NONE)
+ *
+ * override fun map(outer: Mapping): FileSystemExtension {
+ * return DiskUsageExtension(mapping.chain(outer))
+ * }
+ *
+ * fun sizeOnDisk(path: Path): Long {
+ * val mappedPath = mapping.mapParameter(path, "sizeOnDisk", "path")
+ * return lookUpSizeOnDisk(mappedPath)
+ * }
+ *
+ * fun largestFiles(): Sequence<Path> {
+ * val largestFiles: Sequence<Path> = lookUpLargestFiles()
+ * return largestFiles.map {
+ * mapping.mapResult(it, "largestFiles")
+ * }
+ * }
+ * }
+ * ```
+ */
+interface FileSystemExtension {
+ /** Returns a file system of the same type, that applies [outer] to all paths. */
+ fun map(outer: Mapping): FileSystemExtension
+
+ abstract class Mapping {
+ abstract fun mapParameter(path: Path, functionName: String, parameterName: String): Path
+ abstract fun mapResult(path: Path, functionName: String): Path
+
+ fun chain(outer: Mapping): Mapping {
+ val inner = this
+ return object : Mapping() {
+ override fun mapParameter(path: Path, functionName: String, parameterName: String): Path {
+ return inner.mapParameter(
+ outer.mapParameter(
+ path,
+ functionName,
+ parameterName,
+ ),
+ functionName,
+ parameterName,
+ )
+ }
+
+ override fun mapResult(path: Path, functionName: String): Path {
+ return outer.mapResult(
+ inner.mapResult(
+ path,
+ functionName,
+ ),
+ functionName,
+ )
+ }
+ }
+ }
+
+ companion object {
+ val NONE = object : Mapping() {
+ override fun mapParameter(path: Path, functionName: String, parameterName: String) = path
+ override fun mapResult(path: Path, functionName: String) = path
+ }
+ }
+ }
+}

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,25 @@ 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() {
+ /** Extensions added at this layer. Additional extensions may exist in [delegate]. */
+ internal val extensions = extensions.toMap()
+
+ /** Maps paths with [onPathParameter] and [onPathResult]. */
+ val extensionMapping: FileSystemExtension.Mapping = object : FileSystemExtension.Mapping() {
+ override fun mapParameter(path: Path, functionName: String, parameterName: String) =
+ onPathParameter(path, functionName, parameterName)
+
+ override fun mapResult(path: Path, functionName: String) =
+ onPathResult(path, functionName)
+ }
+
+ 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 +158,16 @@ abstract class ForwardingFileSystem(
  */
  open fun onPathResult(path: Path, functionName: String): Path = path
 
+ /**
+ * Invoked each time an extension is returned from [ForwardingFileSystem.extension].
+ *
+ * Overrides of this function must call [FileSystemExtension.map] with [extensionMapping],
+ * otherwise path mapping will not be applied. Or call `super.onExtension()` to do this.
+ */
+ open fun <T : FileSystemExtension> onExtension(type: KClass<T>, extension: T): T {
+ return type.cast(extension.map(extensionMapping))
+ }
+
  @Throws(IOException::class)
  override fun canonicalize(path: Path): Path {
  val path = onPathParameter(path, "canonicalize", "path")
@@ -238,5 +264,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,16 @@ inline fun <T : Closeable?, R> T.use(block: (T) -> R): R {
  @Suppress("UNCHECKED_CAST")
  return result as R
 }
+
+/**
+ * Returns a new file system that forwards all calls to this, and that also returns [extension]
+ * when it is requested.
+ *
+ * When [E] is requested on the returned file system, it will return [extension]. If this file
+ * system already has an extension of this type, [extension] takes precedence.
+ */
+inline fun <reified E : FileSystemExtension> FileSystem.extend(extension: E): FileSystem =
+ extend(E::class, extension)
+
+/** Returns the extension for [E] if it exists, and null otherwise. */
+inline fun <reified E : FileSystemExtension> FileSystem.extension(): E? = 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/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