MGit iOS Bridge

A Go framework adapter that wraps MGit functionality for iOS applications using gomobile bind. This bridge provides iOS-compatible APIs for MGit operations without duplicating code from the main MGit project.

Overview

The MGit iOS Bridge serves as a thin wrapper layer that:

• Imports MGit as a Go module dependency
• Provides simple, iOS-friendly function signatures
• Converts complex MGit operations into gomobile-compatible APIs
• Handles iOS-specific constraints (sandboxing, file paths, etc.)

Architecture

iOS App
    ↓
MGitBridge.xcframework (generated by gomobile)
    ↓  
mgit-ios-bridge (this project - simple wrapper functions)
    ↓
MGit project (imported as Go module dependency)
    ↓
Core MGit functionality (clone, commit, auth, etc.)

Why This Approach?

Constraints of gomobile bind

• Package limitations: Only works with library packages, not package main
• Type restrictions: Limited to basic types (string, int, []byte, simple structs)
• No complex dependencies: Many CLI-oriented packages are incompatible
• No interfaces/channels: Advanced Go features don't translate to iOS
• No variadic functions: Functions like func(args ...string) won't work

Our Solution

Instead of copying/porting MGit code, we:

1. Import MGit as dependency in go.mod
2. Create simple wrapper functions that gomobile can export
3. Call actual MGit implementations internally
4. Convert results to iOS-compatible formats

Project Structure

mgit-ios-bridge/
├── README.md                 # This file
├── go.mod                    # Imports ../mgit as dependency
├── go.sum                    # Go module checksums  
├── bridge.go                 # Main wrapper functions
├── types.go                  # iOS-compatible data structures
├── auth.go                   # Authentication helpers
└── MGitBridge.xcframework    # Generated iOS framework

Development Workflow

1. Building the Framework

# Ensure MGit dependency is available
go mod tidy

# Generate iOS framework
gomobile bind -target ios -o MGitBridge.xcframework .

# Copy to React Native module
cp -r MGitBridge.xcframework ../react-native-mgit/ios/frameworks/

2. Adding New Functionality

To add a new MGit operation (e.g., push):

1. Add wrapper function in bridge.go:

func Push(repoPath string, token string) *PushResult {
    // Call actual MGit push logic
    result := mgit.DoPush(repoPath, token)
    
    // Convert to iOS-compatible result
    return &PushResult{
        Success: result.Success,
        Message: result.Message,
        // ... other fields
    }
}

2. Define result struct in types.go:

type PushResult struct {
    Success bool
    Message string
    CommitHash string
    // Fields must be exportable and simple types
}

3. Rebuild framework and copy to React Native module

3. iOS Integration

The generated framework exposes simple Objective-C/Swift APIs:

// Objective-C usage
MGitbridgeCloneResult *result = MGitbridgeClone(@"repo-url", @"/path", @"jwt-token");
NSLog(@"Clone success: %@", result.success ? @"YES" : @"NO");

Current Functionality

Implemented

• Help() - Get MGit usage information
• TestLogging() - Comprehensive logging test for debugging
• SimpleAdd(a, b) - Basic arithmetic test (proof of concept)

Planned

• Clone(url, localPath, token) - Clone repositories with MGit metadata
• Commit(repoPath, message, options) - Create commits with Nostr signatures
• Pull(repoPath, options) - Pull changes from remote repositories
• Push(repoPath, options) - Push changes to remote repositories

Design Principles

1. Simplicity First

• Functions take basic parameters (strings, ints, bools)
• Results are simple structs with basic fields
• No complex Go types exposed to iOS

2. Error Handling

• Never use os.Exit() or panic in wrapper functions
• Return error information in result structs
• Provide detailed error messages for debugging

3. iOS Compatibility

• Use iOS-appropriate file paths (Documents directory)
• Handle iOS sandbox restrictions
• Support background execution limitations

4. No Code Duplication

• All actual logic stays in main MGit project
• Bridge only contains translation/conversion code
• Changes to MGit core automatically available after rebuild

Dependencies

• MGit project: The main MGit implementation (imported as Go module)
• gomobile: For generating iOS framework (go install golang.org/x/mobile/cmd/gomobile@latest)
• iOS development tools: Xcode for framework integration

Testing

Framework Testing

# Test the Go code before building framework
go test ./...

# Test specific functionality
go run main.go  # If you create a test main.go

iOS Integration Testing

Use the React Native test app to verify:

1. Framework loads correctly
2. Function calls return expected results
3. Error handling works properly
4. Logging is visible in Xcode console

Troubleshooting

Build Issues

• "package main not allowed": Ensure this is a library package, not main
• "unsupported type": Check that all exported types are gomobile-compatible
• "dependency not found": Run go mod tidy to resolve MGit imports

Runtime Issues

• Framework not found: Ensure MGitBridge.xcframework is in iOS project
• Function not available: Check that function is exported (starts with capital letter)
• Crashes on call: Verify parameter types match exactly

Future Enhancements

• Streaming progress: For long operations like clone
• Background operations: Support for iOS background tasks
• Caching layer: Local storage of authentication tokens
• Offline mode: Enhanced support for disconnected operations

Contributing

When adding new functionality:

1. Keep wrapper functions simple and gomobile-compatible
2. Let MGit project handle complex logic
3. Add comprehensive error handling
4. Test thoroughly on actual iOS devices
5. Update this README with new functionality