React Native KnotAPI

Please see https://docs.knotapi.com/ for installation instructions.

🚨 Critical Bridge Fixes

This version includes critical fixes to prevent crashes in React Native applications, specifically addressing bridge teardown race conditions and memory management issues.

Quick Fix Summary

• Bridge State Management: Added lifecycle tracking to prevent events being sent to deallocated bridges
• Close Protection: Prevents multiple close calls and double teardown scenarios
• Delegate Safety: All delegate methods now safely ignore events when bridge is inactive
• Exception Handling: Graceful handling of exceptions during close operations
• Memory Management: Proper cleanup and weak reference patterns

Crash Scenarios Fixed

• ✅ Bridge teardown race conditions
• ✅ Events sent to deallocated bridge
• ✅ Multiple close() calls causing double teardown
• ✅ Memory leaks and retain cycles
• ✅ Exception handling during close operations

Required iOS SDK Fix

CRITICAL: The iOS SDK must also be updated to make KnotSession.delegate a weak reference:

// In KnotSession.swift - REQUIRED FIX
public weak var delegate: KnotEventDelegate?

Testing

Comprehensive test suite included to verify all crash scenarios are handled:

cd ios/
./run_tests.sh

Test Options:

• Simple Tests (No Xcode required) - Quick verification of all fixes
• Full XCTest Suite - Comprehensive testing with mocking and edge cases
• Crash Scenario Tests - Specific tests for crash prevention

GitHub Actions Integration

Automated testing with GitHub Actions:

• Bridge Tests - Runs on push/PR/release, comprehensive bridge testing
• Conditional Testing - Additional tests run on releases (iOS compatibility, documentation)

📚 Technical Details

Bridge Fixes Implementation

Files Modified:

• ios/Knotapi.mm - Core bridge implementation with safety checks

Key Changes:

// Added properties
@property (nonatomic, assign) BOOL isBridgeActive;
@property (nonatomic, assign) BOOL isClosing;

// Added safety checks to all delegate methods
- (void)onErrorWithError:(enum KnotError)error {
    if (!self.isBridgeActive) {
        NSLog(@"KnotAPI onError: Bridge inactive, ignoring event");
        return;
    }
    // ... rest of method
}

// Added close protection
- (void)close {
    if (self.isClosing) {
        NSLog(@"KnotAPI close: Already closing, ignoring duplicate call");
        return;
    }
    self.isClosing = YES;
    // ... rest of method
}

Test Suite

Test Files:

• ios/SimpleBridgeTest.m - Quick verification (no Xcode required)
• ios/KnotapiTests.m - Full XCTest suite
• ios/KnotapiCrashScenarioTests.m - Crash scenario tests
• ios/run_tests.sh - Comprehensive test runner (includes verification)

Running Tests:

cd ios/
./run_tests.sh

GitHub Actions

Workflow: .github/workflows/test.yml

• Triggers: Push/PR/release/manual
• Tests: Bridge fixes, compilation, integration
• Conditional: iOS compatibility and docs on releases

Manual Testing:

gh workflow run test.yml

🔧 Troubleshooting

iOS Build Issues

Node.js Path Issues (Homebrew Installation)

If you installed Node.js via Homebrew and encounter build errors like:

/usr/local/bin/node: No such file or directory

Solution: Create a symlink to make Node.js accessible at the expected path:

sudo ln -sf /opt/homebrew/bin/node /usr/local/bin/node

Verify the fix:

which node
# Should show: /opt/homebrew/bin/node

/usr/local/bin/node --version
# Should show your Node.js version

Test Files in Library Build

If you encounter errors like:

'XCTest/XCTest.h' file not found (in target 'react-native-knotapi' from project 'Pods')

Solution: The podspec has been updated to exclude test files from the main library build. If you're still seeing this error:

1. Clean your build:

   cd example/ios
   rm -rf build Pods Podfile.lock

2. Reinstall pods:

   pod install

3. Try building again:

   cd ..
   npm run ios

General iOS Build Issues

If you encounter other iOS build issues:

1. Clean everything:

   cd example/ios
   rm -rf build Pods Podfile.lock
   cd ..
   rm -rf node_modules
   npm install
   cd ios
   pod install

2. Check Xcode version compatibility:

   • Ensure you're using Xcode 16.1 or later
   • Verify iOS deployment target is 15.1+

3. Verify React Native setup:

   npx react-native doctor

Installation & Usage

Please see https://docs.knotapi.com/ for complete installation and usage instructions.