Cocoar.FileSystem

Production-ready file system utilities for .NET with automatic error recovery and multi-platform support.

🚀 Features

• 🛡️ Resilient File System Monitoring - Production-ready FileSystemWatcher with automatic fallback
• 🔄 Auto-Recovery - Handles directory disappearing/reappearing, permission errors, watcher crashes
• ⚡ Efficient & Reliable - Automatic switching between FileSystemWatcher (efficient) and polling (resilient)
• 🎯 Debouncing - Built-in debouncing to reduce noise from rapid file changes
• 🚀 High-Performance File Search - Fast directory traversal with lazy evaluation
• 🔐 Secure File Reading - Read files as bytes with shared access support (prevent immutable strings in memory)
• 🌍 Cross-Platform - Tested on Windows, Linux, and macOS
• 📦 Zero Dependencies - Lightweight with no external dependencies

📥 Installation

dotnet add package Cocoar.FileSystem

📖 Quick Start

Resilient File System Monitoring

Monitor directories with automatic error recovery and fallback:

using Cocoar.FileSystem;

var monitor = ResilientFileSystemMonitor
    .Watch(@"C:\configs", "*.json")
    .WithDebounce(500) // Optional: reduce noise from rapid changes
    .OnChanged((sender, e) => Console.WriteLine($"Changed: {e.Name}"))
    .OnCreated((sender, e) => Console.WriteLine($"Created: {e.Name}"))
    .Build();

// Multiple file patterns (certificates example):
var monitor = ResilientFileSystemMonitor
    .Watch(@"C:\certs")
    .WithFilter("*.pfx", "*.p12", "*.cer") // Monitor multiple extensions
    .OnChanged((sender, e) => Console.WriteLine($"Certificate changed: {e.Name}"))
    .Build();

// With subdirectory monitoring (depth control):
var monitor = ResilientFileSystemMonitor
    .Watch(@"C:\configs", "*.json")
    .IncludeSubdirectories(2) // Monitor up to 2 levels deep
    .OnChanged((sender, e) => Console.WriteLine($"Changed: {e.FullPath}"))
    .Build();

// Detect folder renames (certificate rotation scenario):
var monitor = ResilientFileSystemMonitor
    .Watch(@"C:\certs")
    .WithFilter("*.pfx")
    .IncludeSubdirectories()
    .OnRenamed((sender, e) => 
    {
        // Fires when folders containing .pfx files are renamed
        // OR when individual .pfx files are renamed
        Console.WriteLine($"Renamed: {e.OldFullPath} -> {e.FullPath}");
    })
    .Build();

Key Features: Auto-recovery, debouncing, depth control, reactive streams, health checks
📖 Full Guide | Reactive Examples

---

High-Performance File Search

Fast, lazy-evaluated directory traversal with fluent API:

using Cocoar.FileSystem;

// Find all C# files in a project (excluding build folders)
var codeFiles = FileSearcher
    .Search(@"C:\repos\myproject", "*.cs")
    .Excluding("bin", "obj", "node_modules")
    .WithMaxDepth(5)
    .ToList();

// Multiple file patterns (harmonized with ResilientFileSystemMonitor API)
var projectFiles = FileSearcher
    .InDirectory(@"C:\repos\myapp")
    .WithFilter("*.cs", "*.csproj", "*.json")
    .IncludeSubdirectories(2)  // Search 2 levels deep
    .ToList();

// Lazy evaluation with LINQ
var largeFiles = FileSearcher
    .InDirectory(@"C:\data")
    .WithPattern("*.log")
    .Recursively()
    .Where(file => new FileInfo(file).Length > 1_000_000)
    .Take(10);

// Search only current directory (no recursion)
var configs = FileSearcher
    .Search(@"C:\app", "*.json")
    .WithMaxDepth(0)  // Current directory only
    .ToArray();

Key Features: Lazy evaluation, depth limits, exclusion patterns, LINQ support, efficient for large directories
📖 Examples

---

Secure File Reading

Read files with shared access and security features:

using Cocoar.FileSystem;

byte[] content = FileReader.ReadAllBytes(@"C:\config.dat");
try 
{
    ProcessSensitiveData(content);
}
finally
{
    Array.Clear(content, 0, content.Length); // Zero out when done
}

Key Features: Shared read/write access, BOM stripping, try-pattern, byte array zeroing
📖 Full Guide

---

📚 Documentation

• ResilientFileSystemMonitor Guide - Detailed usage guide
• Subdirectory Depth Control - Fine-grained recursive monitoring
• FileReader Guide - Secure file reading with shared access
• Examples - More usage examples
• Reactive Examples - Advanced reactive patterns with Rx.NET
• Event Ordering Guarantees - Thread-safety and event ordering
• Test Coverage - Comprehensive test documentation

🔑 Key Benefits Over Raw FileSystemWatcher

• ✅ No crashes when directory doesn't exist initially
• ✅ No silent failures when watcher encounters errors
• ✅ Handles Docker volume mounts appearing after container start
• ✅ Handles network share availability issues
• ✅ Built-in debouncing (no need for manual throttling)
• ✅ Production-ready error handling
• ✅ Cross-platform compatibility

🛠️ Configuration Options

Option	Type	Default	Description
Path	string	(required)	Directory path to monitor
Filter	string	"*"	File filter pattern (e.g., ".json", ".txt") - supports multiple patterns
IncludeSubdirectories	bool	false	Monitor subdirectories recursively
MaxDepth	int	0	Maximum subdirectory depth (0=root only, -1=unlimited)
NotifyFilter	NotifyFilters	LastWrite | FileName | Size	Types of changes to watch for
EnablePollingFallback	bool	true	Enable automatic polling fallback
PollingInterval	TimeSpan	5 seconds	How often to poll when in fallback mode
AutoRecoverFromErrors	bool	true	Automatically switch to polling on errors
DebounceTime	TimeSpan?	null	Optional debouncing to reduce event noise

Subdirectory Depth Control

Control how deep to monitor subdirectories:

// Don't monitor subdirectories (default)
.Watch(@"C:\certs")  // Only watches C:\certs\*.pfx

// Monitor all subdirectories (unlimited depth)
.Watch(@"C:\certs")
.IncludeSubdirectories()  // or .IncludeSubdirectories(true) or .IncludeSubdirectories(-1)

// Monitor with depth limit
.Watch(@"C:\certs")
.IncludeSubdirectories(1)  // Only direct children: C:\certs\prod\*.pfx
.IncludeSubdirectories(2)  // Two levels: C:\certs\prod\2025\*.pfx

🧵 Thread Safety

All operations are thread-safe. Events are raised sequentially on a background thread, guaranteeing:

• ✅ Events are delivered in the order they occurred
• ✅ No concurrent event handler invocations (unless you subscribe multiple handlers)
• ✅ When using the Events channel, you have full control over concurrency

🗑️ Disposal

Always dispose when done:

using var monitor = ResilientFileSystemMonitor
    .Watch(@"C:\data")
    .Build();
// Use monitor...
// Automatically disposed at end of scope

🤝 Contributing & Versioning

• SemVer (additive MINOR, breaking MAJOR)
• PRs & issues welcome

📄 License & Trademark

This project is licensed under the Apache License, Version 2.0. See NOTICE for attribution.

"Cocoar" and related marks are trademarks of COCOAR e.U. Use of the name in forks or derivatives should preserve attribution and avoid implying official endorsement. See TRADEMARKS for permitted and restricted uses.