react-native-buffered-blob 1.0.0

package/android/AGENTS.md

@@ -0,0 +1,74 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-02-15 -->
+
+# android/
+
+Android platform bridge: Kotlin Turbo Module, JNI bridge, streaming operations, and handle registry.
+
+## Purpose
+
+Implement BufferedBlob for Android:
+- **BufferedBlobModule.kt**: Turbo Module class extending NativeBufferedBlobSpec; handle factories, FS operations, hashing
+- **BufferedBlobPackage.kt**: TurboReactPackage provider for React Native
+- **HandleRegistry.kt**: Thread-safe handle storage (ConcurrentHashMap), numeric IDs via AtomicInteger
+- **StreamingBridge.kt**: Static JNI-callable methods for read/write/flush/download; OkHttp enqueue() for async downloads
+- **build.gradle**: CMake linking, OkHttp 4.12.0 dependency
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `src/main/java/com/bufferedblob/BufferedBlobModule.kt` | NativeBufferedBlobSpec impl: install(), openRead, openWrite, createDownload, FS ops, hashFile |
+| `src/main/java/com/bufferedblob/BufferedBlobPackage.kt` | TurboReactPackage, ReactModuleInfoProvider; returns BufferedBlobModule |
+| `src/main/java/com/bufferedblob/HandleRegistry.kt` | Singleton: register(handle), remove(id), get(id); AtomicInteger counter, ConcurrentHashMap storage |
+| `src/main/java/com/bufferedblob/StreamingBridge.kt` | Static JNI-callable methods: readNextChunk, write, flush, close, startDownload, cancelDownload, getReaderInfo, getWriterInfo |
+| `build.gradle` | Dependencies: react-android, OkHttp; CMake pointing to cpp/CMakeLists.txt |
+
+## For AI Agents
+
+### Working In This Directory
+
+1. **NativeBufferedBlobSpec**: Generated from Turbo Module spec (NativeBufferedBlob.ts). BufferedBlobModule extends it; implement all abstract methods.
+2. **Coroutine scope**: Module has private CoroutineScope(Dispatchers.IO + SupervisorJob()). All async FS ops launch() on this scope. Module.invalidate() cancels scope.
+3. **Handle lifecycle**: Turbo Module returns numeric handles. JNI and Kotlin static methods access handles via HandleRegistry.get(handleId).
+4. **JNI bridge**: nativeInstall(jsiPtr, callInvokerHolder) is called from install(). Calls C++ install() which creates AndroidPlatformBridge.
+5. **OkHttp downloads**: StreamingBridge.startDownload() uses OkHttp client.newCall(request).enqueue(callback). Calls JNI progress callback and resolve/reject.
+6. **Error codes**: Return -1 for handle errors; throw RuntimeException with "[CODE]" prefix for validation errors.
+
+### Testing Requirements
+
+- **Module loading**: Verify install() returns true; verify system.loadLibrary("bufferedblobstreaming") succeeds
+- **Handle factories**: Test openRead/openWrite/createDownload with valid/invalid paths, buffer sizes
+- **File operations**: Test exists, stat, mkdir, ls, cp, mv, unlink on temp files via scope.launch
+- **Hashing**: Verify SHA256/MD5 via MessageDigest.getInstance()
+- **Streaming**: Test readNextChunk, write, flush, close; verify file IO
+- **Download**: Test with HTTP server, verify OkHttp progress callback, verify file written
+- **Cleanup**: Verify module.invalidate() cancels scope and clears handles
+- **Thread safety**: Test concurrent handle access via ConcurrentHashMap
+
+### Common Patterns
+
+1. **Coroutine file op**: `scope.launch { try { /* do work */ promise.resolve(result) } catch (e: Exception) { promise.reject("ERR_FS", e.message) } }`
+2. **Create reader**: `openRead(path, bufferSize)` → validate buffer size → FileInputStream(file) → ReaderHandle → register → return handleId
+3. **Stream read**: JNI readNextChunk(handleId) → get handle → read chunk → call progress callback → call resolve callback
+4. **Download**: `createDownload(url, destPath)` → DownloaderHandle(url, destPath) → register → StreamingBridge.startDownload() → OkHttp enqueue → callback chain
+5. **Error codes**: Buffer size validation throws with "[INVALID_ARGUMENT]"; file not found with "[FILE_NOT_FOUND]"
+
+## Dependencies
+
+### Internal
+- `HandleRegistry.kt` — Singleton handle storage
+- `StreamingBridge.kt` — JNI static methods (called from C++)
+
+### External
+- **React Native** >= 0.76.0
+  - Codegen: NativeBufferedBlobSpec (generated from src/NativeBufferedBlob.ts)
+  - TurboModuleRegistry, Promise, ReactMethod, ReadableMap
+- **Android SDK**
+  - `java.io.File, FileInputStream, FileOutputStream` — File IO
+  - `java.security.MessageDigest` — SHA256, MD5 hashing
+  - `android.os.Environment` — DIRECTORY_DOWNLOADS
+- **OkHttp** 4.12.0 — HTTP downloads
+- **Kotlin Coroutines** — Dispatchers.IO, CoroutineScope, SupervisorJob
+
+<!-- MANUAL: Document OkHttp configuration (timeouts, certificates), Coroutine scope lifecycle on module invalidate, JNI callback performance -->

package/android/build.gradle

@@ -0,0 +1,34 @@
+buildscript {
+  ext.safeExtGet = { prop, fallback ->
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+  }
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.bufferedblob"
+  compileSdk safeExtGet("compileSdkVersion", 35)
+
+  defaultConfig {
+    minSdk safeExtGet("minSdkVersion", 24)
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  sourceSets {
+    main {
+      java.srcDirs += ['src/main/java']
+    }
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "com.squareup.okhttp3:okhttp:4.12.0"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,4 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+  package="com.bufferedblob">
+  <uses-permission android:name="android.permission.INTERNET" />
+</manifest>

package/android/src/main/java/com/bufferedblob/BufferedBlobModule.kt

@@ -0,0 +1,274 @@
+package com.bufferedblob
+
+import android.os.Environment
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.WritableNativeArray
+import com.facebook.react.bridge.WritableNativeMap
+import java.io.File
+import java.io.FileInputStream
+import java.io.FileOutputStream
+import java.security.MessageDigest
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.launch
+
+class BufferedBlobModule(reactContext: ReactApplicationContext)
+  : NativeBufferedBlobSpec(reactContext) {
+
+  companion object {
+    const val NAME = "BufferedBlob"
+    private const val MIN_BUFFER_SIZE = 4096
+    private const val MAX_BUFFER_SIZE = 4194304 // 4MB
+    private const val HASH_CHUNK_SIZE = 8192
+  }
+
+  private val scope = CoroutineScope(Dispatchers.IO + SupervisorJob())
+
+  override fun getName(): String = NAME
+
+  override fun install(): Boolean {
+    return try {
+      val jsContext = reactApplicationContext.javaScriptContextHolder?.get() ?: return false
+      if (jsContext == 0L) return false
+      val callInvokerHolder = reactApplicationContext.jsCallInvokerHolder ?: return false
+      nativeInstall(jsContext, callInvokerHolder)
+      true
+    } catch (e: Exception) {
+      false
+    }
+  }
+
+  private external fun nativeInstall(jsiPtr: Long, callInvokerHolder: Any)
+
+  init {
+    System.loadLibrary("bufferedblobstreaming")
+  }
+
+  @ReactMethod(isBlockingSynchronousMethod = true)
+  override fun openRead(path: String, bufferSize: Double): Double {
+    val size = bufferSize.toInt()
+    if (size < MIN_BUFFER_SIZE || size > MAX_BUFFER_SIZE) {
+      throw RuntimeException("[INVALID_ARGUMENT] Buffer size must be $MIN_BUFFER_SIZE-$MAX_BUFFER_SIZE: $size")
+    }
+    val file = File(path)
+    if (!file.exists()) throw RuntimeException("[FILE_NOT_FOUND] File does not exist: $path")
+    if (!file.isFile) throw RuntimeException("[INVALID_ARGUMENT] Path is not a file: $path")
+    val stream = try {
+      FileInputStream(file)
+    } catch (e: java.io.FileNotFoundException) {
+      throw RuntimeException("[FILE_NOT_FOUND] File was removed during open: $path")
+    }
+    val reader = ReaderHandle(stream, size, file.length())
+    return HandleRegistry.register(reader).toDouble()
+  }
+
+  @ReactMethod(isBlockingSynchronousMethod = true)
+  override fun openWrite(path: String, append: Boolean): Double {
+    val file = File(path)
+    file.parentFile?.mkdirs()
+    val stream = FileOutputStream(file, append)
+    val writer = WriterHandle(stream)
+    return HandleRegistry.register(writer).toDouble()
+  }
+
+  @ReactMethod(isBlockingSynchronousMethod = true)
+  override fun createDownload(url: String, destPath: String, headers: ReadableMap): Double {
+    val headerMap = mutableMapOf<String, String>()
+    val iter = headers.keySetIterator()
+    while (iter.hasNextKey()) {
+      val key = iter.nextKey()
+      headerMap[key] = headers.getString(key) ?: ""
+    }
+    val handle = DownloaderHandle(url, destPath, headerMap)
+    return HandleRegistry.register(handle).toDouble()
+  }
+
+  @ReactMethod(isBlockingSynchronousMethod = true)
+  override fun closeHandle(handleId: Double) {
+    HandleRegistry.remove(handleId.toInt())
+  }
+
+  override fun getTypedExportedConstants(): Map<String, Any> {
+    return mapOf(
+      "documentDir" to reactApplicationContext.filesDir.absolutePath,
+      "cacheDir" to reactApplicationContext.cacheDir.absolutePath,
+      "tempDir" to (System.getProperty("java.io.tmpdir") ?: reactApplicationContext.cacheDir.absolutePath),
+      "downloadDir" to Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_DOWNLOADS).absolutePath
+    )
+  }
+
+  override fun exists(path: String, promise: Promise) {
+    scope.launch {
+      try {
+        promise.resolve(File(path).exists())
+      } catch (e: Exception) {
+        promise.reject("ERR_FS", e.message, e)
+      }
+    }
+  }
+
+  override fun stat(path: String, promise: Promise) {
+    scope.launch {
+      try {
+        val file = File(path)
+        if (!file.exists()) throw RuntimeException("[FILE_NOT_FOUND] File does not exist: $path")
+        val type = when {
+          file.isFile -> "file"
+          file.isDirectory -> "directory"
+          else -> "unknown"
+        }
+        val map = WritableNativeMap().apply {
+          putString("path", file.absolutePath)
+          putString("name", file.name)
+          putDouble("size", (if (file.isFile) file.length() else 0L).toDouble())
+          putString("type", type)
+          putDouble("lastModified", file.lastModified().toDouble())
+        }
+        promise.resolve(map)
+      } catch (e: Exception) {
+        promise.reject("ERR_FS", e.message, e)
+      }
+    }
+  }
+
+  override fun unlink(path: String, promise: Promise) {
+    scope.launch {
+      try {
+        val file = File(path)
+        if (!file.exists()) throw RuntimeException("[FILE_NOT_FOUND] File does not exist: $path")
+        if (file.isDirectory) {
+          if (!file.deleteRecursively()) throw RuntimeException("[IO_ERROR] Failed to delete directory: $path")
+        } else {
+          if (!file.delete()) throw RuntimeException("[IO_ERROR] Failed to delete: $path")
+        }
+        promise.resolve(null)
+      } catch (e: Exception) {
+        promise.reject("ERR_FS", e.message, e)
+      }
+    }
+  }
+
+  override fun mkdir(path: String, promise: Promise) {
+    scope.launch {
+      try {
+        val file = File(path)
+        if (file.exists()) {
+          if (!file.isDirectory) {
+            throw RuntimeException("[INVALID_ARGUMENT] Path exists and is not a directory: $path")
+          }
+          promise.resolve(null)
+          return@launch
+        }
+        if (!file.mkdirs()) throw RuntimeException("[IO_ERROR] Failed to create directory: $path")
+        promise.resolve(null)
+      } catch (e: Exception) {
+        promise.reject("ERR_FS", e.message, e)
+      }
+    }
+  }
+
+  override fun ls(path: String, promise: Promise) {
+    scope.launch {
+      try {
+        val dir = File(path)
+        if (!dir.exists()) throw RuntimeException("[FILE_NOT_FOUND] Directory does not exist: $path")
+        if (!dir.isDirectory) throw RuntimeException("[NOT_A_DIRECTORY] Path is not a directory: $path")
+        val arr = WritableNativeArray()
+        (dir.listFiles() ?: emptyArray()).forEach { file ->
+          val type = when {
+            file.isFile -> "file"
+            file.isDirectory -> "directory"
+            else -> "unknown"
+          }
+          arr.pushMap(WritableNativeMap().apply {
+            putString("path", file.absolutePath)
+            putString("name", file.name)
+            putDouble("size", (if (file.isFile) file.length() else 0L).toDouble())
+            putString("type", type)
+            putDouble("lastModified", file.lastModified().toDouble())
+          })
+        }
+        promise.resolve(arr)
+      } catch (e: Exception) {
+        promise.reject("ERR_FS", e.message, e)
+      }
+    }
+  }
+
+  override fun cp(srcPath: String, destPath: String, promise: Promise) {
+    scope.launch {
+      try {
+        val src = File(srcPath)
+        if (!src.exists()) throw RuntimeException("[FILE_NOT_FOUND] Source does not exist: $srcPath")
+        if (!src.isFile) throw RuntimeException("[INVALID_ARGUMENT] Source is not a file: $srcPath")
+        val dest = File(destPath)
+        dest.parentFile?.mkdirs()
+        src.copyTo(dest, overwrite = true)
+        promise.resolve(null)
+      } catch (e: Exception) {
+        promise.reject("ERR_FS", e.message, e)
+      }
+    }
+  }
+
+  override fun mv(srcPath: String, destPath: String, promise: Promise) {
+    scope.launch {
+      try {
+        val src = File(srcPath)
+        if (!src.exists()) throw RuntimeException("[FILE_NOT_FOUND] Source does not exist: $srcPath")
+        val dest = File(destPath)
+        dest.parentFile?.mkdirs()
+        if (!src.renameTo(dest)) {
+          if (src.isFile) {
+            src.copyTo(dest, overwrite = true)
+            if (!src.delete()) {
+              throw RuntimeException("[IO_ERROR] Move partially failed: copied but could not delete source: $srcPath")
+            }
+          } else {
+            throw RuntimeException("[IO_ERROR] Failed to move: $srcPath")
+          }
+        }
+        promise.resolve(null)
+      } catch (e: Exception) {
+        promise.reject("ERR_FS", e.message, e)
+      }
+    }
+  }
+
+  override fun hashFile(path: String, algorithm: String, promise: Promise) {
+    scope.launch {
+      try {
+        val file = File(path)
+        if (!file.exists()) throw RuntimeException("[FILE_NOT_FOUND] File does not exist: $path")
+        if (!file.isFile) throw RuntimeException("[INVALID_ARGUMENT] Path is not a file: $path")
+        val algoName = when (algorithm) {
+          "sha256" -> "SHA-256"
+          "md5" -> "MD5"
+          else -> throw RuntimeException("[INVALID_ARGUMENT] Unknown algorithm: $algorithm")
+        }
+        val digest = MessageDigest.getInstance(algoName)
+        FileInputStream(file).use { stream ->
+          val buffer = ByteArray(HASH_CHUNK_SIZE)
+          var bytesRead: Int
+          while (stream.read(buffer).also { bytesRead = it } != -1) {
+            digest.update(buffer, 0, bytesRead)
+          }
+        }
+        promise.resolve(digest.digest().joinToString("") { "%02x".format(it) })
+      } catch (e: Exception) {
+        promise.reject("ERR_FS", e.message, e)
+      }
+    }
+  }
+
+  override fun invalidate() {
+    scope.cancel()
+    HandleRegistry.clear()
+    super.invalidate()
+  }
+}

package/android/src/main/java/com/bufferedblob/BufferedBlobPackage.kt

@@ -0,0 +1,32 @@
+package com.bufferedblob
+
+import com.facebook.react.TurboReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+
+class BufferedBlobPackage : TurboReactPackage() {
+  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+    return if (name == BufferedBlobModule.NAME) {
+      BufferedBlobModule(reactContext)
+    } else {
+      null
+    }
+  }
+
+  override fun getReactModuleInfoProvider(): ReactModuleInfoProvider {
+    return ReactModuleInfoProvider {
+      mapOf(
+        BufferedBlobModule.NAME to ReactModuleInfo(
+          BufferedBlobModule.NAME,
+          BufferedBlobModule::class.java.name,
+          false,
+          false,
+          false,
+          true
+        )
+      )
+    }
+  }
+}

package/android/src/main/java/com/bufferedblob/HandleRegistry.kt

@@ -0,0 +1,84 @@
+package com.bufferedblob
+
+import java.io.Closeable
+import java.io.FileInputStream
+import java.io.FileOutputStream
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.atomic.AtomicBoolean
+import java.util.concurrent.atomic.AtomicInteger
+
+object HandleRegistry {
+  private val nextId = AtomicInteger(1)
+  private val handles = ConcurrentHashMap<Int, Any>()
+
+  fun register(obj: Any): Int {
+    while (true) {
+      val id = nextId.getAndUpdate { current ->
+        if (current >= Int.MAX_VALUE) 1 else current + 1
+      }
+      if (handles.putIfAbsent(id, obj) == null) return id
+    }
+  }
+
+  @Suppress("UNCHECKED_CAST")
+  fun <T> get(id: Int): T? = handles[id] as? T
+
+  fun remove(id: Int): Any? {
+    val obj = handles.remove(id)
+    if (obj is Closeable) {
+      try { obj.close() } catch (_: Exception) {}
+    }
+    return obj
+  }
+
+  fun clear() {
+    handles.keys.toList().forEach { remove(it) }
+  }
+}
+
+data class ReaderHandle(
+  val stream: FileInputStream,
+  val bufferSize: Int,
+  val fileSize: Long,
+  @Volatile var bytesRead: Long = 0L,
+  @Volatile var isEOF: Boolean = false
+) : Closeable {
+  private val closed = AtomicBoolean(false)
+  val isClosed: Boolean get() = closed.get()
+  override fun close() {
+    if (closed.compareAndSet(false, true)) {
+      try { stream.close() } catch (_: Exception) {}
+    }
+  }
+}
+
+data class WriterHandle(
+  val stream: FileOutputStream,
+  @Volatile var bytesWritten: Long = 0L
+) : Closeable {
+  private val closed = AtomicBoolean(false)
+  val isClosed: Boolean get() = closed.get()
+  override fun close() {
+    if (closed.compareAndSet(false, true)) {
+      try { stream.flush(); stream.close() } catch (_: Exception) {}
+    }
+  }
+}
+
+data class DownloaderHandle(
+  val url: String,
+  val destPath: String,
+  val headers: Map<String, String>,
+  @Volatile var isCancelled: Boolean = false,
+  @Volatile var call: okhttp3.Call? = null,
+  @Volatile var bytesDownloaded: Long = 0L,
+  @Volatile var totalBytes: Long = -1L
+) : Closeable {
+  fun cancel() {
+    isCancelled = true
+    call?.cancel()
+  }
+  override fun close() {
+    cancel()
+  }
+}