Migrate AWS S3 Storage from s3lite to MinIO Client and Enhance Error Handling

[Gk0Wk]

Overview

This pull request modernizes Dynmap's AWS S3 storage implementation by migrating from the unsupported s3lite library to the robust MinIO Java client. The changes include comprehensive error handling, support for path-style S3 access, and significant improvements in reliability and maintainability.

🚀 Major Improvements

1. Library Migration

• Replaced: s3lite library (unsupported, JAXB dependency issues)
• Using: MinIO Java client v8.5.7 (actively maintained, stable)
• Advantages: Better stability, active maintenance, no JAXB conflicts

2. Enhanced S3 Compatibility

• New Feature: Support for path-style S3 access via path_style_access configuration
• Compatibility: Supports AWS S3, MinIO, and other S3-compatible services
• Backward Compatibility: All existing configurations remain valid

3. Robust Error Handling

• Exponential Backoff: Intelligent retry mechanism to prevent infinite loops
• Error Classification: Distinguish between authentication errors and other issues
• Rate-Limiting Logs: Prevent log flooding during S3 failures
• Graceful Degradation: Skip operations during prolonged failures

📋 Change Summary

Key Modified Files

DynmapCore/src/main/java/org/dynmap/storage/aws_s3/AWSS3MapStorage.java

• Completely rewritten using MinIO client API
• Added comprehensive error handling with exponential backoff
• Implemented support for path-style access
• Improved rate-limiting logs
• Enhanced connection pool and resource management

DynmapCore/build.gradle

• Removed s3lite dependencies and JAXB libraries
• Added MinIO client dependency (v8.5.7)
• Updated shadowJar configuration to include MinIO dependencies
• Optimized dependency relocation

Configuration Files (All Platforms)

• Added path_style_access: false option
• Maintained backward compatibility

Supported Platforms

• ✅ Spigot
• ✅ Fabric (1.14.4 to 1.21.3)
• ✅ Forge (1.12.2 to 1.21.3)

🔧 Configuration Changes

New S3 Configuration Options

storage:
  type: aws_s3
  bucketname: "your-bucket-name"
  aws_access_key_id: "your-access-key"
  aws_secret_access_key: "your-secret-key"
  region: "us-east-1"
  # New: Enable path-style access (supports S3-compatible services)
  path_style_access: false  # Optional, default is false

When to Use Path-Style Access

• MinIO server: Usually requires path-style
• Custom S3 endpoints: Some implementations only support path-style
• Legacy systems: Old S3-compatible services
• AWS S3: Both styles supported (default virtual-hosted)

🛡️ Enhanced Error Handling

Previous (s3lite)

// Simple try-catch with basic logging
try {
    s3.putObject(request);
} catch (S3Exception e) {
    Log.severe("AWS Exception", e);
}

After (MinIO, with enhanced handling)

// Intelligent error handling with exponential backoff
if (shouldSkipOperation()) {
    return false; // Skip during backoff
}

try {
    minioClient.putObject(args);
    recordSuccess(); // Reset error count
} catch (ErrorResponseException e) {
    if ("AccessDenied".equals(e.errorResponse().code())) {
        recordError(e, "Authentication error");
    } else {
        recordError(e, "Operation error");
    }
}

Error Handling Features

• Exponential Backoff: 1s → 2s → 4s → ... up to 5 minutes
• Error Classification: Authentication vs. operational errors
• Rate-Limited Logs: Max one log per minute to prevent spam
• Automatic Recovery: Reset counters upon success

📊 Performance Impact

JAR File Size

Due to the inclusion of MinIO and its dependencies, the JAR size has increased to approximately 30MB, with no easy way around this currently.

Memory Usage

• Reduced: Fewer dependency conflicts
• Stable: Better connection pool management
• Efficient: Optimized resource management

🧪 Testing Recommendations

Test Scenarios

1. Normal Operations

   • Upload/download tiles
   • Marking operations
   • Static file operations

2. Error Scenarios

   • Invalid credentials
   • Network timeouts
   • Bucket access issues

3. Configuration Variations

   • AWS S3 (virtual host)
   • AWS S3 (path style)
   • MinIO server
   • Custom S3 endpoint

Validation Steps

# 1. Build and test
./gradlew shadowJar

# 2. Check JAR size
ls -lh target/Dynmap-*.jar

# 3. Test S3 connection
# Enable debug logs and observe error handling

🔄 Migration Guide

Existing Users

No action needed — all current configurations remain compatible.

For New S3-Compatible Services

Add path style configuration if needed:

storage:
  type: aws_s3
  # ... other configs ...
  path_style_access: true  # For MinIO / custom endpoints

🐛 Bug Fixes

Issues Resolved

• JAXB Conflicts: Eliminated NoClassDefFoundError at runtime
• Infinite Retries: Prevented endless retries on auth failures
• Log Flooding: Controlled error log frequency
• Memory Leaks: Improved connection pool management

Error Scenarios Addressed

• Invalid AWS credentials
• Network connectivity issues
• Bucket permission problems
• S3 service outages
• Malformed S3 responses

📚 Dependencies

Removed

// Old s3lite dependencies (unsupported)
implementation 'io.github.linktosriram.s3lite:core:0.0.2-SNAPSHOT'
implementation 'io.github.linktosriram.s3lite:api:0.0.2-SNAPSHOT'
implementation 'jakarta.xml.bind:jakarta.xml.bind-api:3.0.1'
implementation 'com.sun.xml.bind:jaxb-impl:3.0.0'

Added

// Modern MinIO client (actively maintained)
implementation 'io.minio:minio:8.5.7'

📑 Code Quality

Improvements

• Type Safety: More granular exception handling
• Resource Management: Proper use of try-with-resources
• Logging Structure: Better contextual information
• Documentation: Optimized JavaDoc comments
• Maintainability: Cleaner, more readable code

Coding Style

• Consistent formatting and indentation
• Unified exception handling patterns
• Clear variable naming
• Comprehensive error messages

🚦 Compatibility

Backward Compatibility

• ✅ All existing S3 configurations unchanged
• ✅ Other Dynmap component APIs unaffected
• ✅ User configurations remain valid

Forward Compatibility

• ✅ Support for future MinIO client updates
• ✅ Extensible error handling framework
• ✅ Configurable retry mechanisms

Testing

Conducted on PaperMC 1.20.1.

Ready for review and testing! 🚀

---

Reviewers

Please focus on:

• Error handling logic in AWSS3MapStorage.java
• Dependency changes in build.gradle
• Compatibility across supported platforms

[XLordalX]

This seems to fix #4161.