Chd.Library.Min.IO 8.5.9

MinIO Helper Library for .NET Core

Chd (Cleverly Handle Difficulty) library helps you cleverly handle difficulty, write code quickly, and keep your application stable.

📝 Table of Contents

• About
• Features
• Installation & Setup
• Configuration
• Usage Overview
  • Uploading Files
  • Downloading, Deleting, and Public Links
  • Bucket Management
  • Error Handling & Robustness
• Deep Dive: Advanced Image Processing, Storage, and Optimization
• Testing & Sample Code
• Best Practices & Production Benefits
• FAQ
• Authors
• Acknowledgements

About

Chd.Library.MinIO is a modern, robust .NET Core integration for MinIO (or any S3-compatible) storage.
It offers developer-friendly, highly efficient, and production-tested tools for secure file, document, and image storage.
Thanks to advanced optimization features, it’s perfect for user-generated content, SaaS, and media-rich web/mobile/cloud apps.

Features

• 🔌 Plug-and-play .NET 9.0+ support with DI and builder extension
• ⚡ Asynchronous upload/download for single files or batches
• 🖼️ Auto format detection & conversion (JPEG/PNG/WebP) for images
• 📉 Automatic resize, crop, compress, and strict memory/size limiting
• 🧠 Preserves transparency, disallows "fake" image uploads, rejects corrupt files
• 🚦 Generates secure, time-limited public URLs
• 🗂️ Automatic bucket management, multi-tenant/resource support
• 🏆 Production-tested for large enterprises and high-scale web/SaaS products

Installation & Setup

1. Add NuGet package

dotnet add package Chd.Library.MinIO

2. Register on Startup

Add to your Program.cs or startup routine:

app.UseMinIO();
// or, for manual DI
MinIODependenyInjectionExtensions.UseMinIO(app.Services);

Configuration

Add the following to your appsettings.json:

"Minio": {
  "Host": "localhost:9000",
  "AccessKey": "admin",
  "SecretKey": "secret_key_for_min.io",
  "BucketName": "software"
}

• Host: MinIO or S3 endpoint
• AccessKey/SecretKey: Authentication info
• BucketName: Default storage bucket (auto-created as needed)

Usage Overview

All primary APIs are accessible via FileUtils class.
Both async and batch workflows are supported.
(Examples use await, so place inside async methods.)

Uploading Files

Basic single file upload:

var result = await FileUtils.Upload(formFile); // Upload from an IFormFile

• Works with Streams and byte[] too.
• Returns key, full path, and metadata.

Multi-file upload:

var uploadTasks = files.Select(f => FileUtils.Upload(f));
var results = await Task.WhenAll(uploadTasks);

Downloading, Deleting, and Public Links

Download as byte array or stream:

byte[] data = await FileUtils.Download("object_key");
Stream s = await FileUtils.DownloadAsStream("object_key");

Delete file:

await FileUtils.Delete("object_key");

Generate time-limited public URL:

string url = FileUtils.GetPublicUrl("object_key", TimeSpan.FromMinutes(30));

Bucket Management

• Buckets are auto-created on first use (lazy-initialization).
• You can change buckets per environment or logical tenant (adjust config at runtime).
• Compatible with all MinIO and S3-compatible providers.

Error Handling & Robustness

• All API calls raise clear exceptions (with error codes, messages).
• Corrupt, over-large, or unsupported files are blocked with meaningful error text.
• Designed for zero data loss and operational resilience in high-load environments.

📷 Deep Dive: Advanced Image Processing, Storage, and Optimization

This library is not just a bridge to S3 or MinIO — it provides a full, robust, and production-tested media optimization pipeline
tailored for real-world .NET applications. Here’s how it outclasses basic “file save” logic and why it makes operational, UX, and cost sense.

🚀 What Makes Image Handling in This Library Special?

• Bandwidth and Storage Efficiency:
  Large camera/photo uploads are automatically resized, compressed, and—where possible—reformatted to cut storage costs and page loads by 60–80%+.
• Product-Grade Quality:
  Transparency (alpha channel) is never lost by accidental format downscaling: Avatars, logos, overlays always look crisp, no “white box” bugs!
• Failsafe Security:
  Extension spoofing (e.g. JPG that's really a .doc) and broken/corrupt files are detected—your system is never DOS-ed by file upload attacks.
• Image Trustworthiness:
  What the user sees is always what is delivered—pixel shape, background, sharpness preserved based on business rules.
• Automation Simplicity:
  Devs don’t have to handwrite format conversion, downsize, or edge-case filters; all this logic is handled automatically, tested in prod at scale!

🧪 Supported Pipeline Features

1. Auto Format Selection & Conversion

   • Detects if uploaded image has an alpha channel (transparency).
   • Preserves PNG for transparent images (e.g. logos, overlays).
   • Converts PNG→JPEG for non-transparent images (big space savings).
   • Supports WebP for next-gen web clients (where enabled).
   • SVGs are never rasterized: stored as-is, with downstream thumbnailing as a separate concern.

2. Gradual Memory & Dimension Downscaling

   • Params (maxWidth, maxHeight) restrict user uploads to maintain UX/pixel/design bounds.
   • After resizing, applies compression/quality so final file fits maxMemorySizeMB (defensive against mobile camera abuse).
   • If the final image can’t be shrunk below limit, fails gracefully.

3. Content-based File Validation

   • Validates magic bytes and decodes within bounds.
   • Fakes (e.g. .jpg with PDF contents) are blocked, with a detailed error thrown.
   • Rejects zero-length or broken/corrupted images.

4. Edge Format Handling

   • GIFs (animated/static) preserved as GIF unless explicit conversion requested.
   • WebP supported for modern clients and with fallback if needed.
   • SVG uploads passed through untouched, never rasterized.
   • Animated images aren’t downgraded to static.

5. Bulk, Batch & Parallel Image Workflow

   • Async, parallel-safe; entire catalogs can be processed with high throughput easily.

🔄 Algorithm: "What Format Will My Image Be Saved As?"

• Always checks actual binary, not just extension.
• You can override format (format: "png"/"jpeg"/"webp") or allow auto selection by best practice.

💡 Real-World Scenario Table

⚠️ Complex Edge Cases & Warnings

• Uploading “maxed-out” PNGs: If a user attempts to upload a 13MB lossless PNG, with a hard limit of 2MB, system downscales (pixels + quality) until: the threshold is met or it returns a “file too large” exception.
• Animated images: Supported, but no “frame loss” happens unless you forcibly request a format change.
• SVGs: Are never shown as raster previews by the lib. You must generate thumbnails elsewhere if you want them.
• Batch uploads: All pipeline logic applies per-image, never “short-circuits” the workflow.

🏆 Engineering and Business Value

• Reduce bill shock: Prevents runaway AWS/S3/MinIO/ISP costs via auto-compression and dimension limits.
• Improve time-to-first-paint: End users see media faster and production CDNs can cache efficiently.
• Bulletproof broken/corrupt upload defense: No more noisy bug tickets of blank/FUBAR images.
• Explicitly control user content: Out-of-range/abusive uploads rejected before save.
• Great for both web, mobile, API and desktop clients.

⚙️ Example: Putting It All Together

// Full config for optimal UX:
var result = await FileUtils.Upload(
    formFile, 
    autoFormat: true,         // Smart PNG/JPEG/WebP switching
    maxWidth: 1200,           // Crop to 1200px if needed
    maxHeight: 800,
    maxMemorySizeMB: 1.0      // Hard 1MB limit post-optimization
);

// Later: Get pre-signed public link for a 2hr preview
string url = FileUtils.GetPublicUrl(result.Key, TimeSpan.FromHours(2));

📚 Further Reading & References

• Image Optimization: Patterns & Principles (Google)
• Smashing Magazine: PNG vs. JPEG vs. WebP/SVG
• MinIO Docs

Testing & Sample Code

[TestClass]
public class MinIOTests
{
    static MinIOTests() => MinIODependenyInjectionExtensions.UseMinIO(null);

    [TestMethod]
    public async Task TestImageUpload()
    {
        using var fs = File.Open("assets/sample.png", FileMode.Open);
        var formFile = new FormFile(fs, 0, fs.Length, "sample", "sample.png");
        var result = await FileUtils.Upload(formFile, autoFormat: true, maxMemorySizeMB: 1.0);
        Assert.IsNotNull(result);
        string url = FileUtils.GetPublicUrl(result.Key, TimeSpan.FromMinutes(60));
        Assert.IsTrue(url.StartsWith("http"));
    }
}

Run this as part of your CI/CD pipeline or integration tests!

Best Practices & Production Benefits

• Always combine autoFormat: true with reasonable maxWidth/maxMemorySizeMB for user uploads.
• Handle all exceptions and provide friendly user feedback on upload/download errors.
• Regularly clean orphaned or outdated images—integrate with scheduled deletes.
• Use GetPublicUrl for all static sharing; never expose private buckets directly!
• Restrict public uploading to authenticated users for security.
• Automatic image optimization can reduce storage and hosting costs by up to 80%.

FAQ

Q: Can I use with Amazon S3, Wasabi, or other S3-compatible providers?
A: Yes! Just update Host, AccessKey, and SecretKey. Works with any S3 API.

Q: Is SVG resizing supported?
A: SVGs are stored as-is. If you need rasterized thumbnails, generate them in your app before upload.

Q: How does it handle animated GIFs and WebP?
A: Animation is preserved; format conversion only when explicitly requested.

Q: What happens if a user uploads a 12MB photo with “maxMemorySizeMB: 2”?
A: The image is scaled down (and/or quality reduced) until under 2MB; if impossible, the upload fails with a clear exception.

Q: Can I upload files in parallel?
A: Yes! All methods are async/await-friendly and built for scale.

Authors

• Mehmet Yoldaş (LinkedIn)

See also contributors on NuGet

Acknowledgements

• Inspired by MinIO, AWS S3, and the .NET open-source community.
• Kudos to real-world users for testing and feedback.

For issues, feature requests, or contributions, please visit mehmet-yoldas/library-core

📋 Changelog

Version 8.5.9 (2025-01-XX)

🔐 Security Update - Critical

🛡️ Security Fixes

• CRITICAL: Updated Magick.NET-Q8-AnyCPU from 14.2.0 to 14.10.3
  • Fixed 8+ HIGH severity vulnerabilities
  • Fixed 20+ MODERATE severity vulnerabilities
  • Fixed 12+ LOW severity vulnerabilities
  • Affected advisories: GHSA-6hjr-v6g4-3fm8, GHSA-72hf-fj62-w6j4, GHSA-543g-8grm-9cw6, and 40+ more
• Updated Magick.NET.Core from 14.2.0 to 14.10.3

📝 Documentation

• Enhanced README with detailed security notes
• Added comprehensive image processing pipeline documentation

⚠️ Breaking Changes

None - Safe to upgrade!

🔄 Migration Guide

Simply update your package reference:

dotnet add package Chd.Library.MinIO --version 8.5.9

Recommendation: This is a security-critical update. Please upgrade immediately.

Version 8.5.8 (Previous)

• Standard image processing features
• MinIO integration improvements