Thunderbird Core File Module

This module provides a simple, consistent API for common file operations across Android and JVM platforms.

Architecture

The file system layer is split into two levels:

• Public low-level I/O: FileSystemManager opens RawSource/RawSink for a given Uri.
  • Android actual: AndroidFileSystemManager
  • JVM actual: JvmFileSystemManager
• Public high-level facade: FileManager for common operations (copy, delete, createDirectories).
  • Default implementation: DefaultFileManager delegating to internal commands
• Internal commands: e.g., CopyCommand(source, dest), DeleteCommand(uri), CreateDirectoriesCommand(dir) implement operations using FileSystemManager.
  • Hidden from public API; return Outcome<Unit, FileOperationError> internally to preserve error context.
• RawSource/RawSink come from kotlinx-io and are referenced in the public API.

Core Components

classDiagram
    class FileManager {
        +copy(source: Uri, dest: Uri): Outcome<Unit, FileOperationError>
    }

    class DefaultFileManager {
        -fs: FileSystemManager
    }

    class FileSystemManager {
        +openSource(uri: Uri): RawSource?
        +openSink(uri: Uri, mode: WriteMode = WriteMode.Truncate): RawSink?
    }

    class CopyCommand {
        -source: Uri
        -destination: Uri
        +invoke(fs: FileSystemManager): Outcome<Unit, FileOperationError>
    }

    class FileOperationError {
    }

    DefaultFileManager ..> FileSystemManager
    CopyCommand --> FileSystemManager
    DefaultFileManager ..> CopyCommand : delegates

Getting Started

Dependency setup

Add the module to your Gradle build. Then, depending on your platform, provide an actual FileSystemManager and wire a FileManager:

// Koin example (Android)
single<FileSystemManager> { AndroidFileSystemManager(androidContext().contentResolver) }
single<FileManager> { DefaultFileManager(get()) }

For JVM-only tools/tests:

val fs: FileSystemManager = JvmFileSystemManager()
val fileManager: FileManager = DefaultFileManager(fs)

Public API

• FileManager
  • suspend fun copy(sourceUri: Uri, destinationUri: Uri): Outcome<Unit, FileOperationError>
  • suspend fun delete(uri: Uri): Outcome<Unit, FileOperationError>
  • suspend fun createDirectories(uri: Uri): Outcome<Unit, FileOperationError>
• FileSystemManager
  • fun openSource(uri: Uri): RawSource?
  • fun openSink(uri: Uri, mode: WriteMode = WriteMode.Truncate): RawSink?
  • fun delete(uri: Uri)
  • fun createDirectories(uri: Uri)
  • Behavior:
    • Sinks default to overwrite/truncate. Pass WriteMode.Append to append where supported.
    • Returns null when the URI cannot be opened (e.g., missing permissions, unsupported scheme).
  • Thread-safety: Implementations are stateless and safe to use from multiple threads, but the returned streams must be used/closed by the caller.
• enum class WriteMode { Truncate, Append }

URI type

The API uses a KMP‑friendly Uri type (com.eygraber.uri.Uri). On Android, convert a platform URI using the provided extension:

val kmpUri = androidUri.toKmpUri()

To build URIs in tests or common code, you can parse a string:

val source = "file:///path/to/file.txt".toKmpUri()

Supported URIs (by platform)

• Android (AndroidFileSystemManager):
  • content:// via ContentResolver
  • file:// via ContentResolver
• JVM (JvmFileSystemManager):
  • file:// URIs only (non-file: schemes are not supported and will return null).
• iOS: No actual yet in this repository, but the API is compatible. An iOS actual can use NSFileManager/NSURL.

Error handling best practices

• openSource(uri)/openSink(uri) return null on failure. Always check for null and handle gracefully (e.g., show a message, request permissions).
• On Android, failures are frequently due to missing URI permissions; prefer SAF pickers and persist permissions when needed.

Performance and buffering

• Internal copy uses a buffered loop (BUFFER_SIZE = 8_192L).
• Streams are flushed and closed to avoid leaks.
• Public openSource/openSink are not suspending; perform I/O on an appropriate dispatcher/thread when needed.

Limitations and notes

• Android: Ensure the app holds read/write permissions for the target URI (e.g., via SAF and optionally takePersistableUriPermission).
• JVM: Only file: URIs are supported by JvmFileSystemManager.
• iOS: No actual yet. The public API is prepared for an iOS actual using NSFileManager/NSURL.