# macOS NFS Compatibility Issue - Decision Point

**Date:** 2026-05-17 13:51  
**Status:** bold-nfs mount failed (macOS NFS client incompatible)  
**Tests:** 1 mount attempt, 2 connection attempts, both failed

---

## Error Analysis

### Observed Behavior
```bash
$ sudo mount_nfs -o vers=4,port=11112 127.0.0.1:/ /tmp/nfs_demo
mount_nfs: can't mount / from 127.0.0.1 onto /private/tmp/nfs_demo: Connection refused
```

### Server Logs
```
ERROR bold: couldn't get message: InvalidString { cause: FromUtf8Error
bytes: [12, 0, 0, 0, 208, 17, 229, 112, 211, 158, 16, 2, 43, 104, 127, 0, 0, 1, ...]
error: Utf8Error { valid_up_to: 4, error_len: Some(1) }
```

### Root Cause
- **bold-nfs protocol parsing**: Expects UTF-8 strings in NFS RPC fields
- **macOS NFS client**: Sends binary data (memory addresses, path buffers)
- **Compatibility**: bold-nfs designed for Linux NFS client, not macOS

**Bytes breakdown:**
- `[12, 0, 0, 0]` - XDR length prefix
- `[208, 17, 229, 112, ...]` - Binary data (memory address)
- `49, 50, 55, 46, 48, 46, 48, 46, 49, 58, 47` - "127.0.0.1:/" (UTF-8 OK)
- `47, 112, 114, 105, 118, 97, 116, 101, 47, 116, 109, 112, 47, 110, 102, 115, 95, 100, 101, 109, 111` - "/private/tmp/nfs_demo" (UTF-8 OK)

**Problem**: macOS includes binary memory addresses in NFS RPC fields that bold-nfs expects to be UTF-8 strings.

---

## Alternative Approaches

### A. Try NFSv3 or Other Mount Options (5-10 minutes)

**Test commands:**
```bash
# NFSv3 (older protocol, simpler)
sudo mount_nfs -o vers=3,port=11112 127.0.0.1:/ /tmp/nfs_demo

# No authentication
sudo mount_nfs -o vers=4,port=11112,sec=none 127.0.0.1:/ /tmp/nfs_demo

# TCP protocol explicitly
sudo mount_nfs -o vers=4,port=11112,proto=tcp 127.0.0.1:/ /tmp/nfs_demo
```

**Success probability:** 30%  
**Time:** 5-10 minutes  
**Risk:** macOS NFS client may still be incompatible

---

### B. libnfs-go (Go NFS Server) (2-3 days)

**Approach:** Use mature Go NFS library instead of bold-nfs

**Implementation:**
```
MarkBase NFS Server (Go)
├── libnfs-go/server (github.com/smallfz/libnfs-go)
├── MarkBaseBackend (fs.FS interface implementation)
│   ├── SQLite connection (CGO)
│   ├── Go implementation of filesystem operations
└── NFS protocol (NFSv4.0)
```

**Pros:**
- Mature library (v0.0.7, MIT license)
- Production-ready NFS server
- Simple API (fs.FS interface)
- Cross-platform (works on macOS, Linux, Windows)

**Cons:**
- Go binary (not Rust-native)
- CGO for SQLite (complexity)
- Separate Go project management
- Need to build Go binary

**Success probability:** 85%  
**Time:** 2-3 days  
**Effort:** Moderate

**Implementation plan:**
1. Install Go (if not already)
2. Create Go NFS server binary (nfs_backend.go)
3. Implement fs.FS interface (Open, ReadDir, Stat)
4. Connect to SQLite via CGO
5. Test mount_nfs connection
6. AJA System Test validation

---

### C. WebDAV Server (3 days, 95% success)

**Approach:** Switch to HTTP-based WebDAV protocol

**Implementation:**
```
MarkBase WebDAV Server
├── Rust webdav-handler library (if available)
│   Or implement minimal WebDAV protocol
├── SQLite backend (MarkBaseFS already created!)
│   ├── read_dir() → PROPFIND response
│   ├── open_file() → GET response
│   ├── metadata() → PROPFIND metadata
└── HTTP server (Axum, port 8080)
```

**Pros:**
- Simple protocol (HTTP-based)
- macOS native support (Finder WebDAV mount)
- No NFS compatibility issues
- MarkBaseFS backend ready (Day 1 complete!)
- AJA System Test works with mounted volumes

**Cons:**
- Not NFS (different protocol)
- HTTP overhead (slightly slower)
- Finder mount required (not mount_nfs)

**Success probability:** 95%  
**Time:** 3 days  
**Effort:** Low-Medium

**Mount command:**
```bash
# Finder mount
Finder → Connect to Server → http://localhost:8080/webdav

# Or command line
mount_webdav http://localhost:8080/webdav /Volumes/MarkBase_warren
```

---

### D. Report to bold-nfs Project (1-2 days wait)

**Approach:** File bug report with bold-nfs developers

**GitHub issue content:**
```
Title: macOS mount_nfs client incompatible - deserialization error

Description:
bold-mem NFS server fails to handle macOS NFS client requests.
Error: InvalidString when parsing binary data in NFS RPC fields.

Environment:
- macOS 26.4.1
- bold-nfs compiled from source (main branch)
- mount_nfs command: sudo mount_nfs -o vers=4,port=11112 127.0.0.1:/ /tmp/nfs_demo

Server logs:
[ERROR bold: couldn't get message: InvalidString { cause: FromUtf8Error bytes: [...] }]

Expected:
NFS mount succeeds, files visible in /tmp/nfs_demo

Actual:
mount_nfs: can't mount / from 127.0.0.1 onto /private/tmp/nfs_demo: Connection refused

Question:
Is bold-nfs compatible with macOS NFS client? If not, is there a workaround?
```

**Success probability:** 50% (depends on developer response)  
**Time:** 1-2 days wait  
**Risk:** Developers may not respond, or may not have macOS expertise

---

## Recommendation

**Primary recommendation: WebDAV Server**

**Reasons:**
1. **Highest success rate** (95% vs 30%/85%/50%)
2. **Fastest path** (3 days vs 2-3 days + debugging)
3. **Minimal complexity** (HTTP-based, no NFS protocol issues)
4. **MarkBaseFS ready** (Day 1 backend complete, just needs HTTP wrapper)
5. **Native macOS support** (Finder WebDAV mount)
6. **AJA compatible** (works with any mounted volume)

**Secondary recommendation: libnfs-go fallback**

If WebDAV has issues, use Go NFS server as fallback.

**Not recommended:**
- Bold-nfs (macOS incompatible, needs debugging)
- Waiting for bug report (uncertain response time)

---

## Decision Matrix

| Approach | Success % | Time | Effort | macOS Native | AJA Support |
|----------|-----------|------|--------|--------------|-------------|
| NFSv3 options | 30% | 10 min | Low | ✅ mount_nfs | ✅ |
| libnfs-go | 85% | 2-3 days | Medium | ✅ mount_nfs | ✅ |
| WebDAV | 95% | 3 days | Low-Med | ✅ Finder mount | ✅ |
| Report bug | 50% | 1-2 days | Low | ❓ | ❓ |
| bold-nfs (fix) | 20% | 7+ days | High | ❓ | ❓ |

---

## Next Actions

### Immediate Test (Optional)
Try NFSv3 mount options (5-10 minutes):
```bash
sudo mount_nfs -o vers=3,port=11112 127.0.0.1:/ /tmp/nfs_demo
sudo mount_nfs -o vers=4,port=11112,sec=none 127.0.0.1:/ /tmp/nfs_demo
```

### Decision Point
**Choose approach:**
1. **WebDAV** (recommended) → Start implementation immediately
2. **libnfs-go** (fallback) → Install Go, create Go NFS server
3. **Try NFSv3** (quick test) → If fails, proceed to WebDAV
4. **Report bug** (wait) → File GitHub issue, wait 1-2 days

---

## What We Have (Reusable)

**From Day 1 (bold-nfs attempt):**
- ✅ MarkBaseFS backend (236 lines, vfs::FileSystem trait)
- ✅ SQLite integration (read_dir, open_file, metadata)
- ✅ Tests passing (2 tests)
- ✅ Compilation success (zero errors)

**All backend code is reusable for:**
- WebDAV server (HTTP wrapper)
- libnfs-go backend (fs.FS interface)
- Any future virtual filesystem implementation

**No wasted effort** - backend is ready for any protocol wrapper!

---

**Your decision:** Which approach should we take next?

**Recommendation:** WebDAV (95% success, 3 days, reuse MarkBaseFS backend)