react-native-nitro-sse 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IAmTester35
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NitroSse.podspec

@@ -0,0 +1,30 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "NitroSse"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/MaiThanhNam141/react-native-nitro-sse.git", :tag => "#{s.version}" }
+
+  s.source_files = [
+    "ios/**/*.{swift}",
+    "ios/**/*.{m,mm}",
+    "cpp/**/*.{hpp,cpp}",
+  ]
+
+  s.dependency 'React-jsi'
+  s.dependency 'React-callinvoker'
+  s.dependency 'LDSwiftEventSource'
+
+  load 'nitrogen/generated/ios/NitroSse+autolinking.rb'
+  add_nitrogen_files(s)
+
+  install_modules_dependencies(s)
+end

package/README.md

@@ -0,0 +1,121 @@
+# 🚀 react-native-nitro-sse
+
+High-performance Server-Sent Events (SSE) client for React Native, built on top of **Nitro Modules (JSI)**. Designed for mission-critical systems requiring extreme stability, high-throughput data streaming, and absolute battery optimization.
+
+## 🌟 Why NitroSSE?
+
+Unlike traditional EventSource libraries that run on the JS thread or use the legacy Bridge, NitroSSE moves the entire control logic down to the deepest Native layer:
+
+-   **🚀 Zero-Latency JSI**: Communication between JS and Native is instantaneous, bypassing the asynchronous bridge.
+-   **🧠 Smart Reconnect**: Automatic reconnection strategy using **Exponential Backoff** and **Jitter** to prevent thundering herd problems.
+-   **🛡️ DoS Protection**: Respects RFC `Retry-After` headers and enforces strict connection frequency limits.
+-   **🌊 Backpressure Handling**: Advanced **Batching** mechanism aggregates messages and employs **Tail Drop** strategies to protect the UI thread from freezing during data surges.
+-   **🔋 Mobile-First Architecture**: Automatically hibernates when the app enters the background and seamlessly reconnects upon foregrounding to conserve battery.
+-   **💓 Heartbeat Detection**: Native-side detection of keep-alive signals (comments) to maintain a reliable connection watchdog.
+-   **🛠️ Full Protocol Support**: Comprehensive support for GET/POST methods and dynamic header updates.
+
+---
+
+## 📦 Installation
+
+```sh
+yarn add react-native-nitro-sse react-native-nitro-modules
+# or
+npm install react-native-nitro-sse react-native-nitro-modules
+```
+
+> **Note**: `react-native-nitro-modules` is required as the core foundation for JSI performance.
+
+---
+
+## 🚀 Usage
+
+### 1. Basic Initialization
+
+Initialize the module with your endpoint configuration and an event listener.
+
+```tsx
+import { NitroSseModule } from 'react-native-nitro-sse';
+
+NitroSseModule.setup(
+  {
+    url: 'https://api.yourserver.com/stream',
+    method: 'get',
+    headers: {
+      'Authorization': 'Bearer active-token',
+    },
+    // Batch messages every 100ms to optimize UI rendering
+    batchingIntervalMs: 100,
+    // Maximum of 1000 messages in the native queue before tail-drop
+    maxBufferSize: 1000,
+  },
+  (events) => {
+    events.forEach((event) => {
+      if (event.type === 'message') {
+        console.log('Data received:', event.data);
+      } else if (event.type === 'heartbeat') {
+        console.log('Server heartbeat detected...');
+      }
+    });
+  }
+);
+
+// Start the connection
+NitroSseModule.start();
+
+// Stop the connection when unmounting or no longer needed
+// NitroSseModule.stop();
+```
+
+### 2. Check Connection Status
+
+You can synchronously check the connection status at any time:
+
+```tsx
+const connected = NitroSseModule.isConnected();
+console.log('Is Connected:', connected);
+```
+
+### 3. Dynamic Token Updates
+
+When your authentication token expires, update the headers instantly. The native layer will apply these headers to the next automatic reconnection attempt without interrupting the current flow if not necessary.
+
+```tsx
+NitroSseModule.updateHeaders({
+  'Authorization': 'Bearer new-fresh-token',
+});
+```
+
+---
+
+## ⚙️ Configuration (SseConfig)
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `url` | `string` | **Required**. The URL of the SSE endpoint. |
+| `method` | `'get' \| 'post'` | HTTP method (Default: `get`). |
+| `headers` | `Record<string, string>` | Custom headers (e.g., Auth, Content-Type). |
+| `body` | `string` | Request body (payload) for POST requests. |
+| `batchingIntervalMs` | `number` | Time window to buffer events before flushing to JS (Default: 0 - immediate). |
+| `maxBufferSize` | `number` | Native queue limit to prevent memory overflow (Default: 1000). |
+| `backgroundExecution` | `boolean` | (iOS) Attempt to maintain a background task for a short period. |
+
+---
+
+## 🏗️ System Architecture
+
+This project employs a robust **Producer-Consumer** model:
+
+1.  **Native (Producer)**: Collects data from the socket on a dedicated Background Thread, handling all backpressure logic.
+2.  **Nitro (Bridge)**: Snapshots data and securely transports it via the JSI CallInvoker.
+3.  **JavaScript (Consumer)**: Consumes data in batches, ensuring the UI Loop remains buttery smooth even under heavy load.
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)

package/android/CMakeLists.txt

@@ -0,0 +1,24 @@
+project(nitrosse)
+cmake_minimum_required(VERSION 3.9.0)
+
+set(PACKAGE_NAME nitrosse)
+set(CMAKE_VERBOSE_MAKEFILE ON)
+set(CMAKE_CXX_STANDARD 20)
+
+# Define C++ library and add all sources
+add_library(${PACKAGE_NAME} SHARED src/main/cpp/cpp-adapter.cpp)
+
+# Add Nitrogen specs :)
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/nitrosse+autolinking.cmake)
+
+# Set up local includes
+include_directories("src/main/cpp" "../cpp")
+
+find_library(LOG_LIB log)
+
+# Link all libraries together
+target_link_libraries(
+        ${PACKAGE_NAME}
+        ${LOG_LIB}
+        android # <-- Android core
+)

package/android/build.gradle

@@ -0,0 +1,120 @@
+buildscript {
+  ext.NitroSse = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36,
+    targetSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return NitroSse[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+apply from: '../nitrogen/generated/android/nitrosse+autolinking.gradle'
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.margelo.nitro.nitrosse"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    targetSdkVersion getExtOrDefault("targetSdkVersion")
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared", "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
+        abiFilters (*reactNativeArchitectures())
+
+        buildTypes {
+          debug {
+            cppFlags "-O1 -g"
+          }
+          release {
+            cppFlags "-O2"
+          }
+        }
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  packagingOptions {
+    excludes = [
+      "META-INF",
+      "META-INF/**",
+      "**/libc++_shared.so",
+      "**/libfbjni.so",
+      "**/libjsi.so",
+      "**/libfolly_json.so",
+      "**/libfolly_runtime.so",
+      "**/libglog.so",
+      "**/libhermes.so",
+      "**/libhermes-executor-debug.so",
+      "**/libhermes_executor.so",
+      "**/libreactnative.so",
+      "**/libreactnativejni.so",
+      "**/libturbomodulejsijni.so",
+      "**/libreact_nativemodule_core.so",
+      "**/libjscexecutor.so"
+    ]
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lint {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation project(":react-native-nitro-modules")
+  implementation "com.squareup.okhttp3:okhttp:4.12.0"
+  implementation "com.squareup.okhttp3:okhttp-sse:4.12.0"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/cpp/cpp-adapter.cpp

@@ -0,0 +1,6 @@
+#include <jni.h>
+#include "nitrosseOnLoad.hpp"
+
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
+  return margelo::nitro::nitrosse::initialize(vm);
+}

package/android/src/main/java/com/margelo/nitro/nitrosse/NitroSse.kt

@@ -0,0 +1,279 @@
+package com.margelo.nitro.nitrosse
+
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import com.facebook.proguard.annotations.DoNotStrip
+import okhttp3.*
+import okhttp3.MediaType.Companion.toMediaType
+import okhttp3.RequestBody.Companion.toRequestBody
+import okhttp3.sse.EventSource
+import okhttp3.sse.EventSources
+import okhttp3.sse.EventSourceListener
+import okio.Buffer
+import okio.ForwardingSource
+import okio.buffer
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicBoolean
+import java.util.concurrent.atomic.AtomicLong
+import kotlin.random.Random
+
+/**
+ * NitroSse implements a high-performance SSE client using OkHttp.
+ * 
+ * ARCHITECTURE DECISIONS:
+ * 1. Threading: Uses a dedicated HandlerThread (sseHandlerThread) to offload all network events 
+ *    and buffer management from the Main/JS threads. This prevents UI freezes during high-frequency bursts.
+ * 2. Backpressure: Implements a producer-consumer pattern with an internal buffer and batching timer.
+ *    This solves the "Bridge Flooding" problem by grouping multiple events into a single JSI call.
+ * 3. Reliability: Uses exponential backoff with jitter and respects 'Retry-After' headers to 
+ *    prevent DoS-ing the server while ensuring resilient reconnections.
+ * 4. Heartbeat: Since OkHttp-SSE obscures comments, we use a Network Interceptor to manually 
+ *    detect ':' bytes, enabling JS-side watchdog timers.
+ */
+@DoNotStrip
+class NitroSse : HybridNitroSseSpec() {
+    private var client: OkHttpClient? = null
+    private var eventSource: EventSource? = null
+    private var config: SseConfig? = null
+    private var onEventsCallback: ((events: Array<SseEvent>) -> Unit)? = null
+    
+    private val isRunning = AtomicBoolean(false)
+    private var wasRunningBeforePaused = false
+    private var sseHandlerThread: android.os.HandlerThread? = null
+    private var sseHandler: Handler? = null
+    
+    private val eventBuffer = mutableListOf<SseEvent>()
+    private var isFlushPending = AtomicBoolean(false)
+    
+    private var backoffCounter = 0
+    @Volatile private var lastProcessedId: String? = null
+    
+    private val totalBytesReceived = AtomicLong(0)
+    private var reconnectCount = 0
+    private var lastErrorTime: Double? = null
+    private var lastErrorCode: String? = null
+
+    private val defaultRetryDelayMs = 3000L
+    private val baseBackoffDelayMs = 2000L
+    private val maxBackoffDelayMs = 30000L
+
+    companion object {
+        private const val TAG = "NitroSse"
+    }
+
+    override fun setup(config: SseConfig, onEvent: (events: Array<SseEvent>) -> Unit) {
+        this.config = config
+        this.onEventsCallback = onEvent
+        
+        this.client = OkHttpClient.Builder()
+            .connectTimeout(15, TimeUnit.SECONDS)
+            .readTimeout(35, TimeUnit.SECONDS)
+            .addNetworkInterceptor { chain ->
+                val response = chain.proceed(chain.request())
+                val responseBody = response.body
+                if (responseBody != null) {
+                    val countingBody = object : ResponseBody() {
+                        override fun contentType() = responseBody.contentType()
+                        override fun contentLength() = responseBody.contentLength()
+                        override fun source() = (object : okio.ForwardingSource(responseBody.source()) {
+                            override fun read(sink: okio.Buffer, byteCount: Long): Long {
+                                val bytesRead = super.read(sink, byteCount)
+                                if (bytesRead != -1L) {
+                                    totalBytesReceived.addAndGet(bytesRead)
+                                    
+                                    try {
+                                        val snapshot = sink.snapshot()
+                                        if (snapshot.size > 0 && snapshot.get(0) == ':'.toByte()) {
+                                            pushEventToBuffer(SseEvent(SseEventType.HEARTBEAT, null, null, null, "keep-alive"))
+                                        }
+                                    } catch (e: Exception) {
+                                        // Silent catch for interceptor parsing
+                                    }
+                                }
+                                return bytesRead
+                            }
+                        }).buffer()
+                    }
+                    response.newBuilder().body(countingBody).build()
+                } else {
+                    response
+                }
+            }
+            .build()
+            
+        if (sseHandlerThread == null) {
+            sseHandlerThread = android.os.HandlerThread("NitroSseThread").apply { start() }
+            sseHandler = Handler(sseHandlerThread!!.looper)
+        }
+    }
+
+    private fun pushEventToBuffer(event: SseEvent) {
+        val batchInterval = config?.batchingIntervalMs ?: 0.0
+        val bufferCapacity = config?.maxBufferSize?.toInt() ?: 1000
+
+        synchronized(eventBuffer) {
+            while (eventBuffer.size >= bufferCapacity) {
+                eventBuffer.removeAt(0)
+            }
+            eventBuffer.add(event)
+        }
+
+        if (batchInterval <= 0) {
+            flushBufferToJs()
+        } else if (!isFlushPending.getAndSet(true)) {
+            sseHandler?.postDelayed({
+                flushBufferToJs()
+            }, batchInterval.toLong())
+        }
+    }
+
+    private fun flushBufferToJs() {
+        val eventsToEmit: Array<SseEvent>
+        synchronized(eventBuffer) {
+            if (eventBuffer.isEmpty()) {
+                isFlushPending.set(false)
+                return
+            }
+            eventsToEmit = eventBuffer.toTypedArray()
+            eventBuffer.clear()
+        }
+        isFlushPending.set(false)
+        onEventsCallback?.invoke(eventsToEmit)
+    }
+
+    override fun setLastProcessedId(id: String) {
+        this.lastProcessedId = id
+    }
+
+    override fun updateHeaders(headers: Map<String, String>) {
+        this.config?.let {
+            this.config = it.copy(headers = headers)
+            Log.d(TAG, "Headers updated for subsequent connections")
+        }
+    }
+
+    override fun getStats(): SseStats {
+        return SseStats(
+            totalBytesReceived.get().toDouble(),
+            reconnectCount.toDouble(),
+            lastErrorTime,
+            lastErrorCode
+        )
+    }
+
+    override fun start() {
+        if (config == null) return
+        isRunning.set(true)
+        backoffCounter = 0
+        sseHandler?.post { performConnection() }
+    }
+
+    private fun performConnection() {
+        if (!isRunning.get()) return
+        
+        val requestBuilder = Request.Builder()
+            .url(config!!.url)
+            .header("Accept", "text/event-stream")
+            .header("Cache-Control", "no-cache")
+        
+        lastProcessedId?.let { 
+            if (it.isNotEmpty()) requestBuilder.header("Last-Event-ID", it) 
+        }
+
+        config!!.headers?.forEach { (k, v) -> requestBuilder.header(k, v) }
+
+        if (config!!.method == HttpMethod.POST) {
+            val body = config!!.body?.toRequestBody("application/json".toMediaType()) ?: "".toRequestBody()
+            requestBuilder.post(body)
+        }
+
+        eventSource = EventSources.createFactory(client!!).newEventSource(requestBuilder.build(), sseListener)
+    }
+
+    private fun extractRetryAfterMillis(response: Response?): Long? {
+        val header = response?.header("Retry-After") ?: return null
+        return try {
+            header.toLong() * 1000L
+        } catch (e: NumberFormatException) {
+            response.headers.getDate("Retry-After")?.let {
+                val diff = it.time - System.currentTimeMillis()
+                if (diff > 0) diff else null
+            }
+        }
+    }
+
+    private val sseListener = object : EventSourceListener() {
+        override fun onOpen(eventSource: EventSource, response: Response) {
+            backoffCounter = 0
+            pushEventToBuffer(SseEvent(SseEventType.OPEN, null, null, null, null))
+        }
+
+        override fun onEvent(eventSource: EventSource, id: String?, type: String?, data: String) {
+            pushEventToBuffer(SseEvent(SseEventType.MESSAGE, data, id, type, null))
+        }
+
+        override fun onFailure(eventSource: EventSource, t: Throwable?, response: Response?) {
+            Log.e(TAG, "SSE Failure: ${t?.message}, Code: ${response?.code}")
+            if (!isRunning.get()) return
+            
+            val statusCode = response?.code ?: -1
+            reconnectCount++
+            lastErrorTime = System.currentTimeMillis().toDouble()
+            lastErrorCode = t?.javaClass?.simpleName ?: statusCode.toString()
+
+            val isFatal = (statusCode == 401 || statusCode == 403 || statusCode == 400)
+            if (isFatal) {
+                pushEventToBuffer(SseEvent(SseEventType.ERROR, null, null, null, "Fatal Error ($statusCode). Stopping."))
+                stop()
+                return
+            }
+
+            val retryAfterMillis = extractRetryAfterMillis(response)
+            if ((statusCode == 429 || statusCode == 503) && retryAfterMillis != null) {
+                val jitter = (500 + Random.nextInt(1500)).toLong()
+                val totalDelay = retryAfterMillis + jitter
+                pushEventToBuffer(SseEvent(SseEventType.ERROR, null, null, null, "Retry-After received: ${totalDelay/1000}s"))
+                sseHandler?.postDelayed({ if (isRunning.get()) performConnection() }, totalDelay)
+                return
+            }
+
+            if (statusCode == 429) {
+                pushEventToBuffer(SseEvent(SseEventType.ERROR, null, null, null, "Rate Limited (429) without Retry-After. Stopping."))
+                stop()
+                return
+            }
+
+            val isHandshakeError = response == null || response.code != 200
+            val reconnectDelay = if (isHandshakeError) {
+                val base = Math.min(baseBackoffDelayMs * (1 shl backoffCounter), maxBackoffDelayMs)
+                backoffCounter++
+                (base * (0.5 + Random.nextDouble())).toLong()
+            } else {
+                (defaultRetryDelayMs * (0.8 + Random.nextDouble() * 0.4)).toLong()
+            }
+
+            val safeReconnectDelay = Math.max(reconnectDelay, 2000L)
+            pushEventToBuffer(SseEvent(SseEventType.ERROR, null, null, null, t?.message ?: "Link lost ($statusCode)"))
+            sseHandler?.postDelayed({ if (isRunning.get()) performConnection() }, safeReconnectDelay)
+        }
+
+        override fun onClosed(eventSource: EventSource) {
+            if (isRunning.get()) {
+                val delay = (defaultRetryDelayMs * (0.8 + Random.nextDouble() * 0.4)).toLong()
+                sseHandler?.postDelayed({ if (isRunning.get()) performConnection() }, delay)
+            }
+        }
+    }
+
+    override fun stop() {
+        isRunning.set(false)
+        backoffCounter = 0 
+        sseHandler?.removeCallbacksAndMessages(null)
+        eventSource?.cancel()
+        eventSource = null
+        synchronized(eventBuffer) {
+            eventBuffer.clear()
+        }
+    }
+}

package/android/src/main/java/com/margelo/nitro/nitrosse/NitroSsePackage.kt

@@ -0,0 +1,22 @@
+package com.margelo.nitro.nitrosse
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfoProvider
+
+class NitroSsePackage : BaseReactPackage() {
+    override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+        return null
+    }
+
+    override fun getReactModuleInfoProvider(): ReactModuleInfoProvider {
+        return ReactModuleInfoProvider { HashMap() }
+    }
+
+    companion object {
+        init {
+            System.loadLibrary("nitrosse")
+        }
+    }
+}