rustbasic-medialibrary 0.0.2

Highly optimized, extremely secure, and powerful media library management package with Local and Cloud S3 integrations for the RustBasic Framework.
Documentation

๐Ÿ–ผ๏ธ rustbasic-medialibrary

Pustaka manajemen media, unggahan berkas (file upload), kompresi gambar otomatis, dan pembuatan thumbnail berkinerja tinggi untuk RustBasic Framework. Pustaka ini dirancang asinkron, sangat aman, dan kompatibel di seluruh sistem operasi (Windows, macOS, Linux) tanpa membutuhkan dependensi library C eksternal (seperti imagemagick atau libvips), berkat pemanfaatan engine pengolah gambar murni Rust (pure-Rust image crate).


โœจ Fitur Utama

  • Pemasangan Zero-Config (build.rs): Secara otomatis menyuntikkan template pembantu siap pakai ke dalam src/app/helpers/media.rs dan mendaftarkan modul-modul modular di starter kit saat proses kompilasi pertama.
  • Validasi Unggahan Tangguh:
    • Pembatasan ukuran file maksimal secara fleksibel (.max_size(bytes)).
    • Pembatasan format berkas berbasis MIME type yang ketat (.allow_mime(mime)).
  • Penamaan Unik & Anti-Bentrok (SHA-256 Hashing):
    • Setiap file yang diunggah akan dihitung nilai hash SHA-256-nya secara otomatis sebagai nama unik file fisik di disk (deduplikasi data).
    • Menghilangkan risiko bentrok nama file secara mutlak dan mencegah file ganda dengan konten yang sama untuk menghemat penyimpanan disk.
  • Pengolah Gambar Murni Rust (Pure-Rust Image Processor):
    • Pembuat Thumbnail Presisi: Melakukan pemotongan (cropping) dan pengubahan dimensi (resizing) gambar dengan algoritma interpolasi Lanczos3 berkualitas tinggi untuk menghasilkan thumbnail yang tajam.
    • Konversi WebP Modern: Mengonversi berkas JPEG/PNG ke dalam format .webp secara instan untuk memperkecil ukuran file secara drastis hingga 70% lebih ringan tanpa mengurangi kualitas visual secara signifikan.
  • Abstraksi Penyimpanan Modular (StorageBackend Trait):
    • LocalStorageBackend: Menyimpan aset ke folder lokal (cth: public/uploads/).
    • S3StorageBackend: Cloud storage mock layout terstruktur yang siap dihubungkan langsung ke AWS S3, Cloudflare R2, atau Google Cloud Storage.

๐Ÿ“Š Integrasi Database & Kategorisasi Otomatis

Pustaka ini secara cerdas memadukan penyimpanan disk fisik dengan pencatatan metadata di database relasional melalui SQLx atau skema Blueprint bawaan.

1. Struktur Tabel Database (media)

Setiap unggahan berkas generik dicatat di dalam tabel media dengan skema relasional berikut:

Nama Kolom Tipe Data Kunci Deskripsi
id INTEGER PK Primary key unik dengan auto-increment.
filename VARCHAR Unique Nama unik file fisik di disk (SHA-256 hash konten).
original_name VARCHAR - Nama asli berkas saat pertama kali diunggah pengguna.
mime_type VARCHAR - MIME type resmi dari berkas (cth: image/webp, application/pdf).
category VARCHAR Index Kategori berkas hasil deteksi instan oleh pengolah media.
size BIGINT - Ukuran berkas fisik dalam satuan bytes.
url VARCHAR - URL publik relatif untuk merender aset di web browser.
created_at DATETIME - Waktu pembuatan baris berkas.
updated_at DATETIME - Waktu modifikasi baris berkas terakhir.

2. Matriks Kategorisasi Otomatis Berkas (MIME-to-Category)

Saat data masuk, berkas langsung dikategorikan secara instan ke salah satu kategori utama di bawah ini:

Kategori (category) Indikator MIME Type Ekstensi Contoh
image image/* .png, .jpg, .jpeg, .webp, .gif, .svg
video video/* .mp4, .mkv, .avi, .mov, .webm
audio audio/* .mp3, .wav, .ogg, .aac, .flac
document application/pdf, text/*, MIME mengandung document/sheet/presentation/msword .pdf, .txt, .docx, .xlsx, .pptx, .csv
archive MIME mengandung zip/tar/rar/compressed/archive .zip, .tar.gz, .rar, .7z
other Format lain yang tidak memenuhi kriteria di atas .bin, .dat, .exe

๐Ÿš€ Template Pembantu Siap Pakai (Scaffold Presets)

Setelah paket diaktifkan, helper siap pakai otomatis terpasang di src/app/helpers/media.rs proyek Anda:

  1. initialize_media_library(upload_dir: &str) -> MediaLibrary: Inisialisasi media khusus gambar & PDF dengan batas ukuran 10MB.
  2. initialize_generic_media_library(upload_dir: &str) -> MediaLibrary: Inisialisasi media generik tanpa batasan format (mengizinkan ZIP, MP4, Excel, PDF, dll) dengan batas maksimal 100MB.
  3. handle_user_avatar_upload(bytes, original_name, mime): Alur avatar lengkap (simpan -> WebP transcoder -> crop 150x150 -> pembersihan cache file mentah).
  4. handle_generic_file_upload(bytes, original_name, mime, target_subfolder): Alur upload generik instan yang dapat menyimpan file jenis apa saja (MIME-free) ke dalam subfolder pilihan Anda di bawah direktori public/uploads/ dengan penamaan SHA-256 hash unik secara otomatis.

๐Ÿ“‚ Contoh Penggunaan Praktis

1. Inisialisasi Media Library (RustBasic Handler)

Anda dapat mengambil data berkas berformat Base64 langsung dari JSON request input, lalu memprosesnya melalui helper asinkron:

use rustbasic_core::{Request, Response, ResponseHelper};
use crate::app::helpers::media::handle_user_avatar_upload;

pub async fn upload_avatar_handler(req: Request) -> Response {
    // 1. Ambil data Base64 berkas avatar dari request input JSON
    let base64_image = match req.input_as_str("avatar") {
        Some(img) => img,
        None => return ResponseHelper::error("Berkas avatar (base64) tidak ditemukan."),
    };

    // 2. Bersihkan metadata data URL jika ada (misal: "data:image/png;base64,...")
    let clean_base64 = if let Some(index) = base64_image.find("base64,") {
        &base64_image[index + 7..]
    } else {
        base64_image
    };

    // Decode base64 menjadi raw bytes
    let file_bytes = match rustbasic_core::base64::decode(clean_base64) {
        Ok(bytes) => bytes,
        Err(_) => return ResponseHelper::error("Format base64 tidak valid."),
    };

    let file_name = req.input_as_str("filename").unwrap_or("avatar.png");
    let mime_type = req.input_as_str("mime_type").unwrap_or("image/png");

    // 3. Gunakan helper media untuk validasi, konversi WebP, dan crop 150x150
    match handle_user_avatar_upload(&file_bytes, file_name, mime_type) {
        Ok(media_file) => {
            ResponseHelper::json(serde_json::json!({
                "status": "success",
                "message": "Avatar berhasil diunggah dan dioptimalkan!",
                "data": {
                    "filename": media_file.filename,
                    "original_name": media_file.original_name,
                    "size": media_file.size,
                    "url": media_file.url // URL relatif siap pakai (cth: /uploads/avatars/abc_thumb_150x150.png)
                }
            }))
        }
        Err(err) => {
            ResponseHelper::error(&format!("Gagal memproses avatar: {}", err))
        }
    }
}

2. Membuat Instansi Media Library Kustom Sendiri

Jika Anda ingin menyimpan berkas non-gambar (misal file laporan PDF atau CSV) dengan folder kustom, Anda dapat membangunnya secara manual:

use std::sync::Arc;
use rustbasic_medialibrary::{MediaLibrary, LocalStorageBackend};

fn process_invoice_upload(pdf_bytes: &[u8], filename: &str) -> Result<(), String> {
    // 1. Arahkan direktori penyimpanan ke public/uploads/invoices
    let backend = Arc::new(LocalStorageBackend::new("public/uploads/invoices"));

    // 2. Batasi hanya menerima format PDF dengan ukuran maksimal 5MB
    let library = MediaLibrary::new(backend)
        .max_size(5 * 1024 * 1024)
        .allow_mime("application/pdf");

    // 3. Lakukan upload (berkas akan otomatis diberi nama SHA-256 unik agar aman)
    let media = library.upload(filename, "application/pdf", pdf_bytes)?;

    println!("๐Ÿ“„ Invoice PDF berhasil diunggah ke: {}", media.url);
    Ok(())
}

๐Ÿงช Uji Coba Cepat (Unit Tests)

Jalankan perintah pengujian unit murni di bawah ini untuk memverifikasi fungsionalitas validasi, hashing SHA-256 unik, pengubahan ukuran Lanczos3, konversi WebP, serta pembersihan file:

cd rustbasic-medialibrary
cargo test -- --nocapture

Pustaka rustbasic-medialibrary memberikan performa pemrosesan media tingkat tinggi, aman, dan hemat bandwidth untuk website modern Anda!