Initial commit: PSMinIO module with chunked transfer support

2026-08-10 12:56:58 +00:00 · 2025-07-10 12:58:44 -04:00
parent a306ade1f3
commit 5fdcd31d5e
40 changed files with 9899 additions and 1 deletions
@@ -0,0 +1,166 @@
+# PSMinIO Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2025.07.10.1200] - 2025-07-10
+
+### Added
+
+#### Core Infrastructure
+- **MinIOConfiguration**: Singleton configuration management with JSON persistence
+- **MinIOLogger**: Centralized logging utility with timestamp formatting (yyyy/MM/dd HH:mm:ss.fff)
+- **MinIOClientWrapper**: Synchronous wrapper for async MinIO operations using `.GetAwaiter().GetResult()`
+- **MinIOBaseCmdlet**: Base class for all cmdlets with common functionality
+- **ProgressReporter**: Upload/download progress tracking with percentages and time estimates
+
+#### Bucket Operations
+- **Get-MinIOBucket**: List buckets with optional statistics gathering
+- **New-MinIOBucket**: Create buckets with region support and validation
+- **Remove-MinIOBucket**: Delete buckets with optional object removal
+- **Test-MinIOBucketExists**: Check bucket existence with detailed information
+
+#### Object Operations
+- **Get-MinIOObject**: List objects with filtering, sorting, and pagination
+- **New-MinIOObject**: Upload files with progress reporting and content type detection
+- **Get-MinIOObjectContent**: Download objects with progress reporting
+- **Remove-MinIOObject**: Delete objects with prefix support for batch operations
+
+#### Security & Policy Management
+- **Get-MinIOBucketPolicy**: Retrieve bucket policies as JSON or structured objects
+- **Set-MinIOBucketPolicy**: Set policies from JSON, files, or predefined canned policies
+
+#### Configuration & Utilities
+- **Set-MinIOConfig**: Configure MinIO connection with validation and testing
+- **Get-MinIOConfig**: View configuration with optional sensitive data masking
+- **Get-MinIOStats**: Comprehensive statistics with per-bucket details
+
+#### PowerShell Integration
+- **Type Definitions**: Custom .ps1xml files for formatted output
+- **Format Definitions**: Table views for all major object types
+- **Parameter Validation**: Comprehensive input validation and error handling
+- **ShouldProcess Support**: All destructive operations support -WhatIf and -Confirm
+
+### Design Decisions
+
+#### .NET Standard 2.0 Compatibility
+- **Target Framework**: .NET Standard 2.0 for maximum compatibility
+- **PowerShell Support**: Compatible with PowerShell 5.1 (.NET Framework 4.7.2) and PowerShell 7+
+- **Dependency Management**: Uses PowerShellStandard.Library 5.1.1 for cmdlet base classes
+
+#### Synchronous Operations Only
+- **No Async/Await**: All operations are synchronous for PowerShell compatibility
+- **Wrapper Strategy**: Uses `Task.Run().GetAwaiter().GetResult()` pattern
+- **Cancellation Support**: Implements CancellationToken for operation cancellation
+
+#### Logging Strategy
+- **Conditional Logging**: Only logs when `-Verbose` is specified
+- **Timestamp Format**: Consistent yyyy/MM/dd HH:mm:ss.fff format
+- **Centralized Utility**: Single MinIOLogger class for all logging operations
+- **Error Categorization**: Proper PowerShell ErrorCategory assignment
+
+#### Progress Reporting
+- **Upload/Download Progress**: Real-time progress with bytes transferred
+- **Time Estimates**: Calculates remaining time based on current speed
+- **Throttled Updates**: Updates every 100ms to avoid console flooding
+- **Formatted Display**: Human-readable size formatting (B, KB, MB, GB, etc.)
+
+#### Configuration Management
+- **Singleton Pattern**: Single configuration instance across the module
+- **Persistent Storage**: JSON configuration file in user's AppData
+- **Validation**: Comprehensive validation before client creation
+- **Security**: Sensitive data masking in display output
+
+#### Error Handling
+- **Comprehensive Validation**: Input validation at multiple levels
+- **Proper Error Categories**: Uses appropriate PowerShell ErrorCategory values
+- **Graceful Degradation**: Operations continue when possible, warn on failures
+- **Detailed Error Messages**: Includes context and suggestions for resolution
+
+#### Performance Considerations
+- **Lazy Client Creation**: MinIO client created only when needed
+- **Resource Disposal**: Proper disposal of clients and resources
+- **Batch Operations**: Support for bulk operations with progress reporting
+- **Configurable Limits**: MaxObjects parameters to prevent performance issues
+
+#### PowerShell Best Practices
+- **Parameter Sets**: Logical grouping of related parameters
+- **Pipeline Support**: ValueFromPipeline and ValueFromPipelineByPropertyName
+- **Aliases**: Common aliases for frequently used parameters
+- **Help Integration**: Comprehensive parameter documentation
+- **Output Types**: Strongly typed output objects
+
+### Technical Implementation
+
+#### Synchronous Wrapper Pattern
+```csharp
+public bool BucketExists(string bucketName)
+{
+    var args = new BucketExistsArgs().WithBucket(bucketName);
+    return Task.Run(async () => 
+        await _client.BucketExistsAsync(args, CancellationToken))
+        .GetAwaiter().GetResult();
+}
+```
+
+#### Progress Reporting Implementation
+```csharp
+var progressReporter = new ProgressReporter(
+    this, "Uploading Object", $"Uploading {fileInfo.Name}", fileSize, 1);
+
+var etag = Client.UploadFile(BucketName, ObjectName, FilePath, ContentType,
+    bytesTransferred => progressReporter.UpdateProgress(bytesTransferred));
+```
+
+#### Logging Pattern
+```csharp
+MinIOLogger.WriteVerbose(this, "Operation started: {0}", operationName);
+// ... operation code ...
+MinIOLogger.WriteVerbose(this, "Operation completed: {0}", operationName);
+```
+
+### Dependencies
+
+- **Minio**: 5.0.0 - Core MinIO .NET SDK
+- **PowerShellStandard.Library**: 5.1.1 - PowerShell cmdlet base classes
+- **System.Text.Json**: 6.0.0 - JSON serialization for configuration and policies
+
+### Breaking Changes
+
+None - Initial release.
+
+### Security Considerations
+
+- **Credential Storage**: Configuration file stored in user's AppData directory
+- **Sensitive Data Masking**: Access keys and secret keys masked in output by default
+- **SSL by Default**: UseSSL defaults to true for secure connections
+- **Input Validation**: Comprehensive validation to prevent injection attacks
+
+### Known Limitations
+
+- **Large Bucket Performance**: Object counting can be slow for buckets with many objects
+- **Synchronous Only**: No async operations available (by design)
+- **Windows Paths**: File path handling optimized for Windows (cross-platform compatible)
+
+### Future Enhancements
+
+- **Multipart Upload Support**: For large files
+- **Presigned URL Generation**: For temporary access
+- **Server-Side Encryption**: Configuration and management
+- **Lifecycle Policies**: Bucket lifecycle management
+- **Notification Configuration**: Event notification setup
+
+---
+
+## Version Numbering
+
+This project uses a date-based versioning scheme: `YYYY.MM.DD.HHMM`
+
+- **YYYY**: Year (2025)
+- **MM**: Month (07)
+- **DD**: Day (10)
+- **HHMM**: Hour and minute (1200 = 12:00 PM)
+
+This ensures chronological ordering and makes it easy to identify when a version was released.