react-native-nitro-logger 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Amir Shayegh
+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/NitroLogger.podspec

@@ -0,0 +1,29 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "NitroLogger"
+  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/AmirShayegh/react-native-nitro-logger.git", :tag => "#{s.version}" }
+
+  s.source_files = [
+    "ios/**/*.{swift}",
+    "ios/**/*.{m,mm}",
+    "cpp/**/*.{hpp,cpp}",
+  ]
+
+  s.dependency 'React-jsi'
+  s.dependency 'React-callinvoker'
+
+  load 'nitrogen/generated/ios/NitroLogger+autolinking.rb'
+  add_nitrogen_files(s)
+
+  install_modules_dependencies(s)
+end

package/README.md

@@ -0,0 +1,214 @@
+# react-native-nitro-logger
+
+Structured, privacy-tiered logging for React Native. A TypeScript core with
+native file and system-console sinks built on [Nitro Modules][nitro].
+
+- **Privacy is a setting, not a habit.** One call at startup decides whether an
+  unwrapped metadata value renders or redacts. In the builds that ship, the
+  strict profile is fail-closed: a forgotten wrapper hides data rather than
+  leaking it.
+- **Designed around the things that actually go wrong.** Rotation, gzip and
+  retention; crash-tail recovery; detection of an externally deleted file, with
+  a reopen into a fresh one; and a compliance purge that reports honestly when
+  it could not finish. Where records cannot be saved they are *accounted for*
+  rather than papered over: a full disk loses records and counts what it lost,
+  and the partial write is rolled back to the last record boundary so the
+  damage does not spread — an attempt, not a guarantee, since the rollback is
+  itself I/O that can fail. An external deletion is detected and recovered
+  from, but the unlinked file and anything written before detection are gone.
+- **New Architecture only**, iOS and Android, no bridge fallback.
+
+```sh
+npm install react-native-nitro-logger react-native-nitro-modules
+```
+
+`react-native-nitro-modules` is a required peer — this library is built on
+[Nitro Modules][nitro].
+
+## Quick start
+
+```ts
+import {
+  Log,
+  ConsoleDestination,
+  FileDestination,
+  createFileSink,
+} from 'react-native-nitro-logger';
+
+Log.addDestination(new ConsoleDestination());
+Log.addDestination(new FileDestination(createFileSink()));
+
+Log.info('app started');
+Log.warning('retrying upload', { attempt: 2, statusCode: 503 });
+```
+
+A scoped logger tags every line with a correlation ID, so one request's lines
+can be picked out of a busy file. Omit the correlation argument and one is
+generated for you — which is also what the lint rules want, since a correlation
+ID must never be derived from an identifier you already have:
+
+```ts
+const scope = Log.scoped(undefined, 'checkout', { orderKind: 'subscription' });
+scope.info('payment authorised');
+scope.error('capture failed', { statusCode: 502 });
+```
+
+## Levels
+
+`verbose` · `debug` · `info` · `warning` · `error` · `todo`
+
+```ts
+Log.minimumLevel('info');             // globally
+Log.subsystem('networking', 'debug'); // and per subsystem
+```
+
+## Privacy
+
+The default profile renders metadata values and is fine for open-source and
+general application use. Apps handling regulated data should switch to the
+strict one in their entry point, before anything logs:
+
+```ts
+import { Log, pub, priv } from 'react-native-nitro-logger';
+
+Log.privacyDefault('private');
+Log.metadataKeyCatalog(['requestId', 'statusCode', 'durationMs']);
+
+Log.info('request finished', {
+  requestId: pub(id),   // rendered
+  statusCode: 200,      // redacted — unwrapped, and the default is private
+});
+```
+
+**In a release build** (`__DEV__` false):
+
+| | `'public'` (default) | `'private'` |
+| --- | --- | --- |
+| bare value | rendered | `<private>` |
+| `pub(v)` | rendered | rendered |
+| `priv(v)` | `<private>` | `<private>` |
+
+**A debug build renders private payloads in the clear**, to every destination
+including the file — so the fail-closed behaviour above is a property of the
+builds that ship, not of every build. A build where reveal is possible is a
+build for synthetic data only.
+
+`privacyDefault` is first-set-wins and tighten-only, so a dependency cannot
+loosen your setting.
+
+Message text, metadata keys, subsystems and correlation IDs are **public by
+contract** — they are never redacted at runtime. The bundled ESLint plugin
+constrains them at build time instead, but only once you enable it: installing
+this package ships the rules, it does not apply them.
+
+```js
+// eslint.config.mjs
+import nitroLogger from 'react-native-nitro-logger/eslint-plugin';
+
+export default [nitroLogger.configs.strict];
+```
+
+**Read [docs/PRIVACY.md](docs/PRIVACY.md) before using this in an app that
+handles regulated data.** It covers what the contract does and does not
+promise, the approved-key catalog, and the compliance boundary — in short, a
+build where reveal is possible is a build for synthetic data only.
+
+## Writing to a file
+
+```ts
+const file = new FileDestination(createFileSink(), {
+  rotation: {
+    maxFileSizeBytes: 10 * 1024 * 1024,
+    maxArchivedFilesCount: 5,
+    compressArchives: true,
+    maxTotalLogBytes: 50 * 1024 * 1024,
+  },
+});
+Log.addDestination(file);
+```
+
+Logs live in app-private storage — `noBackupFilesDir` on Android, `Library/Logs`
+on iOS. Owner-only modes are applied to every artifact; where the platform
+refuses, the sink reports a `protection` degradation and keeps logging rather
+than failing shut.
+
+```ts
+file.getLogFilePaths();     // for a consent-gated support upload
+
+const outcome = file.purge(5000);   // the compliance purge
+if (!outcome.durable) {
+  // Something survived, or the deadline blew. The destination stays fenced
+  // until an explicit retry, so nothing is written into a pending deletion.
+}
+```
+
+`purge` is synchronous and deadline-bounded. It reports `durable` (every
+pre-purge artifact is gone) separately from `rebound` (the destination is
+writable again), because a complete deletion can still be followed by a failed
+reopen, and a caller that resumes on `durable` alone would write into a
+destination with nowhere to put anything. A purge that rebinds opens a fresh,
+empty active file — `durable` is a statement about the data that was there, not
+a promise that the directory is left empty.
+
+It clears the **file sink's** artifacts and nothing else. Anything already
+handed to `os_log` or `logcat` is outside this library's reach.
+
+## Crash handling and backgrounding
+
+```ts
+import { installErrorHandler, flushOnBackground } from 'react-native-nitro-logger';
+
+const uninstallHandler = installErrorHandler();
+const uninstallFlush = flushOnBackground();
+```
+
+The error handler logs uncaught errors with the message dropped outside dev,
+the class name reduced to a built-in or a fixed token, and stack frames reduced
+to a position in a file whose name was already known. It flushes on fatal
+errors, then chains to whatever handler was installed before it. Both functions
+return idempotent uninstall handles.
+
+## Output format
+
+`JsonLinesFormatter` is the default for files — one JSON object per line, with
+a framing guarantee the native crash-tail recovery depends on. It is asserted
+byte-identical to [SwiftLogger][swiftlogger]'s `JSONLogFormatter` over a
+generated corpus.
+
+```json
+{"timestamp":"2026-07-28T10:15:00.123Z","level":"INFO","message":"app started"}
+```
+
+`DefaultFormatter` is the human-readable one used by the console destination.
+Custom formatters implement `LogFormatter`; declare `framing: 'line'` to opt
+into crash-tail trimming.
+
+## Compatibility
+
+| | Supported | Verified |
+| --- | --- | --- |
+| iOS | React Native ≥ 0.78 | CI builds, launches and exercises a pristine 0.78 consumer app |
+| Android | React Native at the example's version; **≥ 0.78 experimental**. minSdk 24 | CI runs the writer's unit suite and builds the example; no minimum-version consumer job exists yet |
+
+New Architecture only. The compatibility claims are split per platform on
+purpose — see [docs/PARITY.md](docs/PARITY.md) for what backs each one, and for
+where the two native writers genuinely differ.
+
+## Documentation
+
+- [docs/PRIVACY.md](docs/PRIVACY.md) — the privacy contract and compliance boundary
+- [docs/PARITY.md](docs/PARITY.md) — parity with SwiftLogger, and between the two native writers
+- [eslint-plugin/README.md](eslint-plugin/README.md) — what the lint rules protect, and what they do not
+
+## Contributing
+
+- [Development workflow](CONTRIBUTING.md#development-workflow)
+- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
+- [Code of conduct](CODE_OF_CONDUCT.md)
+
+## License
+
+MIT
+
+[nitro]: https://nitro.margelo.com/
+[swiftlogger]: https://github.com/amirshayegh/logger

package/android/CMakeLists.txt

@@ -0,0 +1,24 @@
+project(nitrologger)
+cmake_minimum_required(VERSION 3.9.0)
+
+set(PACKAGE_NAME nitrologger)
+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/nitrologger+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.NitroLogger = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return NitroLogger[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/nitrologger+autolinking.gradle'
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.margelo.nitro.nitrologger"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+
+    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"
+    }
+  }
+
+  packaging {
+    resources {
+      excludes += [
+        "META-INF",
+        "META-INF/**"
+      ]
+    }
+
+    jniLibs {
+      excludes += [
+        "**/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 {
+    prefab true
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  testOptions {
+    unitTests {
+      // The writer imports nothing from `android.*` — every syscall it needs
+      // is behind `PlatformIo` — so its suite is plain JUnit on the JVM and
+      // needs neither a device nor Robolectric. This flag only covers the
+      // stray android.* symbol reached through a shared constant.
+      returnDefaultValues = true
+    }
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation project(":react-native-nitro-modules")
+
+  testImplementation "junit:junit:4.13.2"
+}

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,11 @@
+#include <jni.h>
+#include "nitrologgerOnLoad.hpp"
+
+#include <fbjni/fbjni.h>
+
+
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
+  return facebook::jni::initialize(vm, []() {
+    margelo::nitro::nitrologger::registerAllNatives();
+  });
+}

package/android/src/main/java/com/margelo/nitro/nitrologger/AndroidPlatformIo.kt

@@ -0,0 +1,100 @@
+package com.margelo.nitro.nitrologger
+
+import android.system.ErrnoException
+import android.system.Os
+import android.system.OsConstants
+import java.io.File
+import java.io.FileDescriptor
+
+/**
+ * [PlatformIo] against the real syscalls.
+ *
+ * Split out from the interface so that every `android.*` import in the writer's
+ * dependency graph lives in this one file, and the writer itself stays
+ * runnable — and testable — on a plain JVM.
+ *
+ * Every method here is answered with `Os`, which is API 21. Nothing delegates
+ * to [PlatformIo.Jvm] except [restrictToOwner], whose fallback uses only
+ * `java.io`: `java.nio.file` is API 26 and this library supports 24, and a
+ * missing class there would raise `NoClassDefFoundError` rather than something
+ * a `catch (Exception)` would contain.
+ */
+object AndroidPlatformIo : PlatformIo {
+  override fun linkCount(descriptor: FileDescriptor): Int = try {
+    if (!descriptor.valid()) -1 else Os.fstat(descriptor).st_nlink.toInt()
+  } catch (_: Throwable) {
+    // Unknowable, which is not the same as zero. Reporting zero here would
+    // make the writer reopen its file on every health check.
+    -1
+  }
+
+  override fun syncDirectory(directory: File): Boolean {
+    var fd: FileDescriptor? = null
+    return try {
+      fd = Os.open(directory.absolutePath, OsConstants.O_RDONLY, 0)
+      Os.fsync(fd)
+      true
+    } catch (_: Throwable) {
+      false
+    } finally {
+      if (fd != null) {
+        try {
+          Os.close(fd)
+        } catch (_: Throwable) {
+          // Nothing left to do about it, and the sync result already stands.
+        }
+      }
+    }
+  }
+
+  /**
+   * `lstat`, with the errno preserved.
+   *
+   * Only `ENOENT` means the path is gone. Everything else — `EACCES` on a
+   * directory whose mode changed underneath us, `EIO` on failing storage — is
+   * [PlatformIo.Presence.UNKNOWN], and the purge reports it as a failure
+   * instead of counting a file it never saw removed as deleted.
+   */
+  override fun lookup(file: File): PlatformIo.Presence = try {
+    Os.lstat(file.absolutePath)
+    PlatformIo.Presence.PRESENT
+  } catch (e: ErrnoException) {
+    if (e.errno == OsConstants.ENOENT) PlatformIo.Presence.ABSENT
+    else PlatformIo.Presence.UNKNOWN
+  } catch (_: Throwable) {
+    PlatformIo.Presence.UNKNOWN
+  }
+
+  override fun isSymbolicLink(file: File): Boolean = try {
+    OsConstants.S_ISLNK(Os.lstat(file.absolutePath).st_mode)
+  } catch (e: ErrnoException) {
+    // A path that is not there is not a symlink. Anything else is unresolvable,
+    // and unresolvable has to fail closed.
+    e.errno != OsConstants.ENOENT
+  } catch (_: Throwable) {
+    true
+  }
+
+  override fun restrictToOwner(file: File, isDirectory: Boolean): Boolean = try {
+    // chmod through the path rather than the java.io.File permission helpers:
+    // those go through three separate syscalls with observable intermediate
+    // states, and cannot express 0700 in one step.
+    Os.chmod(file.absolutePath, if (isDirectory) 448 /* 0700 */ else 384 /* 0600 */)
+    true
+  } catch (_: Throwable) {
+    PlatformIo.Jvm.restrictToOwner(file, isDirectory)
+  }
+
+  /**
+   * Always null on Android — the age sidecar is the mechanism here.
+   *
+   * `BasicFileAttributes.creationTime()` is API 26, and where it does exist it
+   * is not reliably populated: several Android filesystems have no birth time
+   * and return the mtime instead. An mtime advances on every write, so trusting
+   * it would make the active file look freshly created at every restart and
+   * postpone age-based rotation forever. Reporting nothing is what tells
+   * `LogFileWriter.creationTimeOf` to seed the sidecar from the clock and treat
+   * it as authoritative.
+   */
+  override fun creationTimeMillis(file: File): Long? = null
+}