@shamilovtim/react-native-nitro-sse 2.3.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,37 @@
+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, :osx => "10.15" }
+  s.source       = { :git => "https://github.com/shamilovtim/react-native-nitro-sse.git", :tag => "#{s.version}" }
+
+  s.source_files = [
+    "ios/*.{h,m,mm,swift}",
+    "cpp/**/*.{h,hpp,cpp}",
+  ]
+  
+  s.public_header_files = [
+    "ios/NitroSseNetworkInspector.h",
+  ]
+
+  s.test_spec 'Tests' do |test_spec|
+    test_spec.source_files = 'ios/Tests/**/*.{swift}'
+  end
+
+  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,144 @@
+# 🚀 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.
+-   **🔍 DevTools Integration**: Plug-and-play support for **React Native 0.83+ DevTools Network Tab**. Monitor connection status, request/response headers, and timing directly in the official desktop debugger.
+-   **🛠️ Full Protocol Support**: Comprehensive support for GET/POST methods and dynamic header updates.
+
+---
+
+## 📦 Installation
+
+```sh
+yarn add @shamilovtim/react-native-nitro-sse react-native-nitro-modules
+# or
+npm install @shamilovtim/react-native-nitro-sse react-native-nitro-modules
+```
+
+> **Note**: `react-native-nitro-modules` is required as the core foundation for JSI performance.
+
+---
+
+## 📊 Compatibility
+
+| react-native-nitro-sse | react-native-nitro-modules |
+| :--------------------- | :------------------------- |
+| **2.2.0 - latest**     | **0.35.4**                 |
+| **2.0.0 - 2.1.1**      | **0.35.2**                 |
+| **1.6.2**              | **0.35.2**                 |
+| **1.4.0 - 1.6.1**      | **0.35.0**                 |
+| **1.2.2 - 1.3.1**      | **0.34.1**                 |
+| **1.2.0 - 1.2.1**      | **0.34.0**                 |
+| **1.1.0**              | **0.33.9**                 |
+| **1.0.0**              | **0.33.8**                 |
+
+
+---
+
+## 🚀 Usage
+
+### 1. Basic Initialization
+
+Initialize the module with your endpoint configuration and an event listener.
+
+```tsx
+import { createNitroSse } from '@shamilovtim/react-native-nitro-sse';
+
+const nitroSse = createNitroSse();
+
+nitroSse.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 forced flush
+    maxBufferSize: 1000,
+    // Optional: Auto-refresh tokens or dynamic headers
+    onBeforeRequest: async () => {
+      const token = await fetchNewToken();
+      return { 'Authorization': `Bearer ${token}` };
+    }
+  },
+  (events) => {
+    // events is an array of SseEvent objects
+    events.forEach((event) => {
+      console.log('Received:', event);
+    });
+  }
+);
+
+// Start the connection
+nitroSse.start();
+```
+
+### 2. Monitoring & Statistics
+
+NitroSSE provides synchronous access to connection health and throughput data.
+
+```tsx
+const stats = nitroSse.getStats();
+console.log(`Downloaded: ${stats.totalBytesReceived / 1024} KB`);
+console.log(`Reconnections: ${stats.reconnectCount}`);
+```
+
+---
+
+## ⚙️ Configuration (SseConfig)
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `url` | `string` | - | **Required**. The URL of the SSE endpoint. |
+| `method` | `'get' \| 'post'` | `get` | HTTP method. |
+| `headers` | `Record<string, string>` | `{}` | Custom HTTP headers. |
+| `body` | `string` | - | Request body (payload) for POST requests. |
+| `batchingIntervalMs` | `number` | `0` | Time window (ms) to group events. `0` = real-time. |
+| `maxBufferSize` | `number` | `1000` | Native queue limit to prevent memory overflow. |
+| `connectionTimeoutMs`| `number` | `15000` | Max time for initial handshake / connect. |
+| `readTimeoutMs`      | `number` | `300000`| Max idle time between data packets before reconnecting. |
+| `backgroundExecution` | `boolean` | `false` | (iOS) Attempt to maintain connection via background tasks. |
+| `autoParseJSON` | `boolean` | `false` | Automatically parse message data as JSON in a background native thread. Result is in `parsedData`. |
+| `monitorNetwork` | `boolean` | `true` | Automatically hibernate connection on system network loss to save battery. |
+| `onBeforeRequest`    | `function`| - | Async hook to refresh headers/tokens before every attempt. |
+
+---
+
+## 🛡️ Reliability Features (v1.5.1+)
+
+-   **Atomic State Management**: Calling `.start()` or `.stop()` updates the instance status immediately on the JSI thread, ensuring the UI (e.g., `isConnected()`) never feels laggy or stuck.
+-   **Promise Safety**: The `onBeforeRequest` interceptor is wrapped in a native fallback timeout. Even if your JS token refresh hangs indefinitely, the native state machine will recover and retry safely.
+-   **Zero-Ghost Reloads**: Seamlessly handles React Native Hot Reloads. The native layer detects when the JS environment is being destroyed and synchronously kills active sockets to prevent duplicate connections.
+-   **Cumulative Logic**: Statistics (`totalBytesReceived`) are preserved across reconnections, giving you a true 360-degree view of the session's data usage.
+
+---
+
+## 🏗️ 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,124 @@
+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"
+  implementation "androidx.lifecycle:lifecycle-process:2.8.7"
+
+  testImplementation "junit:junit:4.13.2"
+  testImplementation "org.json:json:20240303"
+}

package/android/src/main/AndroidManifest.xml

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

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

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

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

@@ -0,0 +1,94 @@
+package com.margelo.nitro.nitrosse
+
+import android.util.Log
+import okhttp3.Request
+import okhttp3.Response
+import java.util.UUID
+
+/**
+ * A utility to report network events to the React Native DevTools Network Tab.
+ * It uses reflection to access the internal InspectorNetworkReporter class in RN.
+ */
+object NetworkInspector {
+    private const val TAG = "NitroSseNetworkInspector"
+    private var reporterClass: Class<*>? = null
+    private var isEnabledCached: Boolean = false
+
+    init {
+        try {
+            reporterClass = Class.forName("com.facebook.react.modules.network.InspectorNetworkReporter")
+            Log.d(TAG, "InspectorNetworkReporter found. Network tracing is available.")
+        } catch (e: Exception) {
+            Log.d(TAG, "InspectorNetworkReporter not found. Network tracing is disabled.")
+        }
+    }
+
+    private fun isEnabled(): Boolean {
+        if (reporterClass == null) return false
+        return try {
+            val method = reporterClass?.getDeclaredMethod("isDebuggingEnabled")
+            method?.invoke(null) as? Boolean ?: false
+        } catch (e: Exception) {
+            false
+        }
+    }
+
+    fun reportRequestStart(requestId: String, request: Request) {
+        if (reporterClass == null || !isEnabled()) return
+        try {
+            val method = reporterClass?.getDeclaredMethod(
+                "reportRequestStart",
+                String::class.java,
+                String::class.java,
+                String::class.java,
+                Map::class.java,
+                String::class.java,
+                Long::class.javaPrimitiveType
+            )
+            val headers = request.headers.toMap()
+            // We send an empty body string as SSE setup usually doesn't have a large body
+            val body = "" 
+            method?.invoke(null, requestId, request.url.toString(), request.method, headers, body, 0L)
+        } catch (e: Exception) {
+            Log.e(TAG, "Error reporting request start", e)
+        }
+    }
+
+    fun reportResponseStart(requestId: String, request: Request, response: Response) {
+        if (reporterClass == null || !isEnabled()) return
+        try {
+            val method = reporterClass?.getDeclaredMethod(
+                "reportResponseStart",
+                String::class.java,
+                String::class.java,
+                Int::class.javaPrimitiveType,
+                Map::class.java,
+                Long::class.javaPrimitiveType
+            )
+            val headers = response.headers.toMap()
+            method?.invoke(null, requestId, request.url.toString(), response.code, headers, -1L)
+        } catch (e: Exception) {
+            Log.e(TAG, "Error reporting response start", e)
+        }
+    }
+
+    fun reportResponseEnd(requestId: String, totalBytes: Long) {
+        if (reporterClass == null || !isEnabled()) return
+        try {
+            val method = reporterClass?.getDeclaredMethod("reportResponseEnd", String::class.java, Long::class.javaPrimitiveType)
+            method?.invoke(null, requestId, totalBytes)
+        } catch (e: Exception) {
+            Log.e(TAG, "Error reporting response end", e)
+        }
+    }
+
+    fun reportRequestFailed(requestId: String, cancelled: Boolean) {
+        if (reporterClass == null || !isEnabled()) return
+        try {
+            val method = reporterClass?.getDeclaredMethod("reportRequestFailed", String::class.java, Boolean::class.javaPrimitiveType)
+            method?.invoke(null, requestId, cancelled)
+        } catch (e: Exception) {
+            Log.e(TAG, "Error reporting request failure", e)
+        }
+    }
+}