PSMinIO/docs/CHANGELOG.md

PSMinIO Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[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

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

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

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.