SeaweedFS is a distributed storage system for object storage (S3), file systems, Iceberg table buckets, and Lance vector buckets, designed to handle billions of files with O(1) disk access and effortless horizontal scaling.
POSIX Compliance Implementation Roadmap
This document tracks the implementation status of POSIX features in the SeaweedFS FUSE mount compliance test suite and provides a roadmap for completing comprehensive POSIX compliance testing.
Overview
The platform-specific tests listed below are implemented; this document records the implementation plan that produced them, plus the one feature still pending.
Current Status
✅ Implemented Features
- Basic file operations (create, read, write, delete)
- Directory operations (mkdir, rmdir, rename)
- File permissions and ownership
- Symbolic and hard links
- Basic I/O operations (seek, append, positioned I/O)
- File descriptors and atomic operations
- Concurrent access patterns
- Error handling compliance
- Timestamp operations
🚧 Partially Implemented
- Cross-platform compatibility (basic implementation with platform-specific access time handling)
- File sealing (still skipped; Linux-specific, pending)
✅ Implemented Platform-Specific Features
1. Extended Attributes (xattr)
Priority: High Platforms: Linux, macOS, FreeBSD
Status: Implemented
TestExtendedAttributes/SetExtendedAttributeTestExtendedAttributes/ListExtendedAttributesTestExtendedAttributes/RemoveExtendedAttribute
Implementation Plan:
// Linux implementation
//go:build linux
func setXattr(path, name string, value []byte) error {
return syscall.Setxattr(path, name, value, 0)
}
// macOS implementation
//go:build darwin
func setXattr(path, name string, value []byte) error {
return syscall.Setxattr(path, name, value, 0, 0)
}
Required Files:
xattr_linux.go- Linux syscall implementationsxattr_darwin.go- macOS syscall implementationsxattr_freebsd.go- FreeBSD syscall implementationsxattr_unsupported.go- Fallback for unsupported platforms
2. Memory Mapping (mmap)
Priority: High Platforms: All POSIX systems
Status: Implemented
TestMemoryMapping/MemoryMappedReadTestMemoryMapping/MemoryMappedWrite
Implementation Plan:
func testMmap(t *testing.T, filePath string) {
fd, err := syscall.Open(filePath, syscall.O_RDWR, 0)
require.NoError(t, err)
defer syscall.Close(fd)
// Platform-specific mmap implementation
data, err := syscall.Mmap(fd, 0, size, syscall.PROT_READ|syscall.PROT_WRITE, syscall.MAP_SHARED)
require.NoError(t, err)
defer syscall.Munmap(data)
}
Required Files:
mmap_unix.go- Unix-like systems implementationmmap_windows.go- Windows implementation (if needed)
3. Vectored I/O (readv/writev)
Priority: Medium Platforms: All POSIX systems
Status: Implemented
TestAdvancedIO/VectoredIO
Implementation Plan:
func testVectoredIO(t *testing.T, filePath string) {
// Use syscall.Syscall for readv/writev
// Linux: SYS_READV, SYS_WRITEV
// Other platforms: platform-specific syscall numbers
}
4. Direct I/O
Priority: Medium
Platforms: Linux, some Unix variants
Status: Implemented
TestDirectIO/DirectIO
Implementation Plan:
//go:build linux
func testDirectIO(t *testing.T, filePath string) {
fd, err := syscall.Open(filePath, syscall.O_RDWR|syscall.O_DIRECT, 0)
// Test with aligned buffers
}
5. File Preallocation (fallocate)
Priority: Medium Platforms: Linux, some Unix variants
Status: Implemented
TestFilePreallocation/Fallocate
Implementation Plan:
//go:build linux
func testFallocate(t *testing.T, filePath string) {
fd, err := syscall.Open(filePath, syscall.O_RDWR, 0)
err = syscall.Syscall6(syscall.SYS_FALLOCATE, uintptr(fd), 0, 0, uintptr(size), 0, 0)
}
6. Zero-Copy Transfer (sendfile)
Priority: Low Platforms: Linux, FreeBSD, some Unix variants
Status: Implemented
TestZeroCopyTransfer/Sendfile
Implementation Plan:
//go:build linux
func testSendfile(t *testing.T, srcPath, dstPath string) {
// Use syscall.Syscall for sendfile
// Platform-specific implementations
}
7. File Sealing (Linux-specific)
Priority: Low Platforms: Linux only
Current Status: File sealing test is still skipped
TestFileSealing
Implementation Plan:
//go:build linux
func testFileSealing(t *testing.T) {
// Use fcntl with F_ADD_SEALS, F_GET_SEALS
// Test various seal types: F_SEAL_WRITE, F_SEAL_SHRINK, etc.
}
Implementation Strategy
Phase 1: Core Features (High Priority)
- Extended Attributes - Essential for many applications
- Memory Mapping - Critical for performance-sensitive applications
Phase 2: Advanced I/O (Medium Priority)
- Vectored I/O - Important for efficient bulk operations
- Direct I/O - Needed for database and high-performance applications
- File Preallocation - Important for preventing fragmentation
Phase 3: Specialized Features (Low Priority)
- Zero-Copy Transfer - Performance optimization feature
- File Sealing - Security feature, Linux-specific
Platform Support Matrix
| Feature | Linux | macOS | FreeBSD | Windows | Notes |
|---|---|---|---|---|---|
| Extended Attributes | ✅ | ✅ | ✅ | ❌ | Different syscall signatures |
| Memory Mapping | ✅ | ✅ | ✅ | ✅ | Standard POSIX |
| Vectored I/O | ✅ | ✅ | ✅ | ❌ | readv/writev syscalls |
| Direct I/O | ✅ | ❌ | ✅ | ❌ | O_DIRECT flag |
| fallocate | ✅ | ❌ | ❌ | ❌ | Linux-specific |
| sendfile | ✅ | ❌ | ✅ | ❌ | Platform-specific |
| File Sealing | ✅ | ❌ | ❌ | ❌ | Linux-only |
Development Guidelines
1. Platform-Specific Implementation Pattern
// feature_linux.go
//go:build linux
package fuse
func platformSpecificFunction() { /* Linux implementation */ }
// feature_darwin.go
//go:build darwin
package fuse
func platformSpecificFunction() { /* macOS implementation */ }
// feature_unsupported.go
//go:build !linux && !darwin
package fuse
func platformSpecificFunction() { /* Skip or error */ }
2. Test Structure Pattern
func (s *POSIXExtendedTestSuite) TestFeature(t *testing.T) {
if !isFeatureSupported() {
t.Skip("Feature not supported on this platform")
return
}
t.Run("FeatureTest", func(t *testing.T) {
// Actual test implementation
})
}
3. Error Handling
- Use platform-specific error checking
- Provide meaningful error messages
- Gracefully handle unsupported features
Testing Strategy
1. Continuous Integration
- Run tests on multiple platforms (Linux, macOS)
- Use build tags to enable/disable platform-specific tests
- Ensure graceful degradation on unsupported platforms
2. Feature Detection
- Implement runtime feature detection where possible
- Skip tests gracefully when features are unavailable
- Log clear messages about skipped functionality
3. Documentation
- Document platform-specific behavior
- Provide examples for each implemented feature
- Maintain compatibility matrices
Contributing
When implementing these features:
- Start with high-priority items (Extended Attributes, Memory Mapping)
- Follow the platform-specific pattern outlined above
- Add comprehensive tests for each feature
- Update this roadmap as features are implemented
- Document any platform-specific quirks or limitations
Future Enhancements
Beyond the current roadmap, consider:
- File locking (flock, fcntl locks)
- Asynchronous I/O (aio_read, aio_write)
- File change notifications (inotify, kqueue)
- POSIX ACLs (Access Control Lists)
- Sparse file operations
- File hole punching