react-native-buffered-blob 1.0.0

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

@@ -0,0 +1,211 @@
+package com.bufferedblob
+
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import java.io.File
+import java.io.FileOutputStream
+import java.io.IOException
+import java.util.concurrent.TimeUnit
+
+/**
+ * Static bridge methods called from C++ via JNI.
+ * All methods operate on handles from HandleRegistry.
+ */
+object StreamingBridge {
+
+  private val httpClient = OkHttpClient.Builder()
+    .connectTimeout(30, TimeUnit.SECONDS)
+    .readTimeout(60, TimeUnit.SECONDS)
+    .writeTimeout(60, TimeUnit.SECONDS)
+    .build()
+
+  /**
+   * Read the next chunk from a ReaderHandle.
+   * Returns null when EOF is reached.
+   */
+  @JvmStatic
+  fun readNextChunk(handleId: Int): ByteArray? {
+    val reader = HandleRegistry.get<ReaderHandle>(handleId)
+      ?: throw RuntimeException("[READER_CLOSED] Reader handle not found: $handleId")
+
+    synchronized(reader) {
+      if (reader.isClosed) throw RuntimeException("[READER_CLOSED] Reader is closed")
+      if (reader.isEOF) return null
+
+      val buffer = ByteArray(reader.bufferSize)
+      val bytesRead = reader.stream.read(buffer)
+
+      if (bytesRead == -1) {
+        reader.isEOF = true
+        return null
+      }
+
+      reader.bytesRead += bytesRead
+
+      return if (bytesRead == buffer.size) {
+        buffer
+      } else {
+        buffer.copyOf(bytesRead)
+      }
+    }
+  }
+
+  /**
+   * Write data to a WriterHandle.
+   * Returns the number of bytes written.
+   */
+  @JvmStatic
+  fun write(handleId: Int, data: ByteArray): Int {
+    val writer = HandleRegistry.get<WriterHandle>(handleId)
+      ?: throw RuntimeException("[WRITER_CLOSED] Writer handle not found: $handleId")
+
+    synchronized(writer) {
+      if (writer.isClosed) throw RuntimeException("[WRITER_CLOSED] Writer is closed")
+
+      writer.stream.write(data)
+      writer.bytesWritten += data.size
+      return data.size
+    }
+  }
+
+  /**
+   * Flush a WriterHandle.
+   */
+  @JvmStatic
+  fun flush(handleId: Int) {
+    val writer = HandleRegistry.get<WriterHandle>(handleId)
+      ?: throw RuntimeException("[WRITER_CLOSED] Writer handle not found: $handleId")
+
+    synchronized(writer) {
+      if (writer.isClosed) throw RuntimeException("[WRITER_CLOSED] Writer is closed")
+
+      writer.stream.flush()
+    }
+  }
+
+  /**
+   * Close a handle (reader, writer, or downloader).
+   */
+  @JvmStatic
+  fun close(handleId: Int) {
+    HandleRegistry.remove(handleId)
+  }
+
+  /**
+   * Start a download synchronously (blocking the calling thread).
+   * Updates handle.bytesDownloaded and handle.totalBytes during download
+   * for progress polling from the C++ layer.
+   */
+  @JvmStatic
+  fun startDownload(handleId: Int) {
+    val handle = HandleRegistry.get<DownloaderHandle>(handleId)
+      ?: throw RuntimeException("[DOWNLOAD_FAILED] Download handle not found: $handleId")
+
+    if (handle.isCancelled) {
+      throw RuntimeException("[DOWNLOAD_CANCELLED] Download was cancelled")
+    }
+
+    val requestBuilder = Request.Builder().url(handle.url)
+    for ((key, value) in handle.headers) {
+      requestBuilder.addHeader(key, value)
+    }
+    val request = requestBuilder.build()
+
+    val call = httpClient.newCall(request)
+    handle.call = call
+
+    val response = try {
+      call.execute()
+    } catch (e: IOException) {
+      if (handle.isCancelled) {
+        throw RuntimeException("[DOWNLOAD_CANCELLED] Download was cancelled")
+      }
+      throw RuntimeException("[DOWNLOAD_FAILED] ${e.message}")
+    }
+
+    response.use { resp ->
+      if (!resp.isSuccessful) {
+        throw RuntimeException("[DOWNLOAD_FAILED] HTTP ${resp.code}")
+      }
+
+      val body = resp.body
+        ?: throw RuntimeException("[DOWNLOAD_FAILED] Empty response body")
+
+      val contentLength = body.contentLength()
+      handle.totalBytes = contentLength
+
+      val destFile = File(handle.destPath)
+      destFile.parentFile?.mkdirs()
+
+      FileOutputStream(destFile).use { fos ->
+        val buffer = ByteArray(8192)
+        var bytesRead: Int
+
+        body.byteStream().use { inputStream ->
+          while (inputStream.read(buffer).also { bytesRead = it } != -1) {
+            if (handle.isCancelled) {
+              throw RuntimeException("[DOWNLOAD_CANCELLED] Download was cancelled")
+            }
+            fos.write(buffer, 0, bytesRead)
+            handle.bytesDownloaded += bytesRead
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Cancel a download.
+   */
+  @JvmStatic
+  fun cancelDownload(handleId: Int) {
+    val handle = HandleRegistry.get<DownloaderHandle>(handleId) ?: return
+    handle.cancel()
+  }
+
+  // --- Reader info getters ---
+
+  @JvmStatic
+  fun getReaderFileSize(handleId: Int): Long {
+    val reader = HandleRegistry.get<ReaderHandle>(handleId) ?: return 0L
+    return reader.fileSize
+  }
+
+  @JvmStatic
+  fun getReaderBytesRead(handleId: Int): Long {
+    val reader = HandleRegistry.get<ReaderHandle>(handleId) ?: return 0L
+    return reader.bytesRead
+  }
+
+  @JvmStatic
+  fun getReaderIsEOF(handleId: Int): Boolean {
+    val reader = HandleRegistry.get<ReaderHandle>(handleId) ?: return true
+    return reader.isEOF
+  }
+
+  // --- Writer info getters ---
+
+  @JvmStatic
+  fun getWriterBytesWritten(handleId: Int): Long {
+    val writer = HandleRegistry.get<WriterHandle>(handleId) ?: return 0L
+    return writer.bytesWritten
+  }
+
+  // --- Download progress getters (polled from C++ via JNI) ---
+
+  @JvmStatic
+  fun getDownloadBytesDownloaded(handleId: Int): Long {
+    return HandleRegistry.get<DownloaderHandle>(handleId)?.bytesDownloaded ?: 0L
+  }
+
+  @JvmStatic
+  fun getDownloadTotalBytes(handleId: Int): Long {
+    return HandleRegistry.get<DownloaderHandle>(handleId)?.totalBytes ?: -1L
+  }
+
+  interface DownloadCallback {
+    fun onProgress(bytesDownloaded: Long, totalBytes: Long, progress: Double)
+    fun onSuccess()
+    fun onError(message: String)
+  }
+}

package/cpp/AGENTS.md

@@ -0,0 +1,71 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-02-15 -->
+
+# cpp/
+
+JSI HostObject, platform bridge abstraction, and Android JNI loader.
+
+## Purpose
+
+Implements the native streaming layer:
+- **BufferedBlobStreamingHostObject**: JSI HostObject class exposing streaming methods (readNextChunk, write, flush, close, startDownload, etc.)
+- **PlatformBridge**: Abstract interface that iOS and Android implement for actual streaming logic
+- **OwnedMutableBuffer**: Zero-copy ArrayBuffer helper for JSI
+- **jni_onload.cpp**: Android JNI entry point that installs the HostObject
+- **AndroidPlatformBridge**: Android implementation of PlatformBridge using JNI callbacks to Kotlin
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `BufferedBlobStreamingHostObject.h` | PlatformBridge interface (abstract), BufferedBlobStreamingHostObject class, OwnedMutableBuffer |
+| `BufferedBlobStreamingHostObject.cpp` | JSI property handlers, Promise creation via callInvoker->invokeAsync, error handling |
+| `AndroidPlatformBridge.h` | Android implementation header: inherits PlatformBridge, calls JNI static methods |
+| `AndroidPlatformBridge.cpp` | JNI implementation: FindClass, GetStaticMethodID, uses std::thread::detach for async ops |
+| `jni_onload.cpp` | Java_com_bufferedblob_BufferedBlobModule_nativeInstall: extracts JSI runtime, CallInvoker, creates bridge, calls install() |
+| `CMakeLists.txt` | CMake build config: links ReactAndroid::jsi, react_nativemodule_core, turbomodulejsijni, fbjni |
+
+## For AI Agents
+
+### Working In This Directory
+
+1. **Platform abstraction**: PlatformBridge is the abstraction layer. iOS and Android each implement it independently. Changes to PlatformBridge interface require updates to both platforms.
+2. **JSI property handlers**: BufferedBlobStreamingHostObject::get() maps property names to methods. Methods are exposed as Properties or Functions in the HostObject.
+3. **Promise pattern**: Use `react::createPromiseAsJSIValue(rt, asyncFn, callInvoker)` to return Promises to JavaScript. Callbacks invoke `resolve()` or `reject()` with JSI values.
+4. **ArrayBuffer zero-copy**: OwnedMutableBuffer owns the data vector; returned as jsi::MutableBuffer to avoid copying.
+5. **Android JNI**: nativeInstall() is called from Kotlin BufferedBlobModule.install(). Extracts JSI runtime pointer and CallInvoker, creates AndroidPlatformBridge, installs HostObject.
+6. **Error handling**: PlatformBridge callbacks (onSuccess, onError) pass strings to the HostObject, which converts them to JSI errors.
+
+### Testing Requirements
+
+- **Compile without errors**: C++ code compiles with clang, including JSI headers
+- **CMake linking**: Verify CMakeLists.txt links all required libraries (jsi, react_nativemodule_core, fbjni on Android)
+- **Android linking**: Verify nativeInstall() JNI signature matches Kotlin method
+- **Property access**: Verify JSI HostObject properties are accessible from JavaScript
+- **Promise resolution**: Verify async callbacks resolve/reject Promises correctly
+- **Zero-copy**: Verify ArrayBuffer does not copy data (requires profiling)
+
+### Common Patterns
+
+1. **Create Promise**: `react::createPromiseAsJSIValue(rt, [](jsi::Runtime& r, std::function<void(jsi::Value)> resolve, std::function<void(jsi::Runtime&, jsi::Error)> reject) { ... }, callInvoker_)`
+2. **Get string property**: `rt.getPropertyAsFunction(rt, name).call(rt, args...)`
+3. **Call PlatformBridge async**: `bridge_->readNextChunk(handleId, [=](std::vector<uint8_t> data) { ... }, ...)`
+4. **Return Promises**: Store resolve/reject lambdas; call from platform bridge callbacks
+5. **Convert to ArrayBuffer**: `rt.createArrayBuffer(std::make_shared<OwnedMutableBuffer>(data))`
+
+## Dependencies
+
+### Internal
+- `BufferedBlobStreamingHostObject.h` — PlatformBridge interface
+- Android: `AndroidPlatformBridge.h` — JNI to Kotlin static methods
+
+### External
+- **React Native** >= 0.76.0
+  - `<jsi/jsi.h>` — JSI runtime, HostObject, Value, MutableBuffer
+  - `<ReactCommon/CallInvoker.h>` — CallInvoker for Promise creation
+  - `<ReactCommon/TurboModuleManagerDelegate.h>` (Android) — Turbo Module integration
+- **Android**
+  - `<fbjni/fbjni.h>` — Facebook JNI helpers (jni::make_local, etc.)
+  - `<android/log.h>` (optional) — Logging
+
+<!-- MANUAL: Document JSI best practices, Promise handling guidelines, Android/iOS bridge API versioning -->