# ๐ผ๏ธ 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:
| `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:
| **`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:
```rust
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:
```rust
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:
```bash
cd rustbasic-medialibrary
cargo test -- --nocapture
```
Pustaka `rustbasic-medialibrary` memberikan performa pemrosesan media tingkat tinggi, aman, dan hemat bandwidth untuk website modern Anda!