Belajar Axum - Static Files & Assets

#Pendahuluan

API kalian sudah lengkap — tapi banyak aplikasi nyata butuh lebih: melayani frontend statis (HTML, JS, CSS, gambar) dari server yang sama. Axum menangani ini tanpa server web tambahan, lewat ServeDir dan ServeFile dari tower-http.

Episode ini membahas kapan static files sebaiknya dilayani Axum (vs reverse proxy), cara memasang ServeDir dengan fallback untuk SPA, mengatur cache headers dengan benar, dan menggabungkannya dengan compression dari episode 8. Ini jembatan menuju episode 20 (HTTPS & reverse proxy) dan 24 (deployment).

#Kapan Axum Harus Melayani Static Files?

Jawaban jujurnya: tidak selalu. Ada tiga pilihan umum:

Aturan praktis:

• Prototipe / internal tool → Axum ServeDir sudah cukup.
• Aplikasi publik dengan banyak aset → layani aset via CDN atau object storage (episode 20 & 24 membahas pola reverse proxy).
• SPA dengan router client-side → tetap butuh fallback ke index.html untuk path HTML5 history.

Episode ini mengajarkan opsi pertama dengan benar — dan kalian akan tahu kapan harus pindah ke opsi lain.

#ServeDir Dasar

Tambah fitur fs di tower-http:

cargo add tower-http --features fs,trace

Buat folder aset dan file contoh:

mkdir -p static
echo '<h1>Beranda</h1>' > static/index.html
echo 'body { color: #333; }' > static/style.css

Pasang ServeDir sebagai fallback route:

use axum::{Router, routing::get};
use tower_http::services::ServeDir;
 
fn app() -> Router {
    Router::new()
        .route("/api/health", get(|| async { "ok" }))
        .fallback_service(ServeDir::new("static"))
}

fallback_service berarti: semua request yang tidak cocok dengan route API akan dilayani dari folder static. Request GET /style.css akan membaca static/style.css secara langsung — dengan Content-Type yang otomatis benar (via mime_guess).

#Fallback untuk SPA

Aplikasi SPA (React/Vue/Svelte) memakai HTML5 history API — URL seperti /tentang harus mengembalikan index.html, bukan 404, karena routing dilakukan JavaScript di browser. Pola ini memakai ServeDir + ServeFile:

use tower_http::services::{ServeDir, ServeFile};
 
fn spa_app() -> Router {
    Router::new()
        .route("/api/health", axum::routing::get(|| async { "ok" }))
        .fallback_service(
            ServeDir::new("static").not_found_service(ServeFile::new("static/index.html")),
        )
}

Alurnya: ServeDir mencoba file; jika tidak ditemukan (bukan karena path api/), ia menyerahkan ke ServeFile::new("static/index.html"). Efeknya: GET /tentang mengembalikan index.html → browser menjalankan JS → router client menampilkan halaman "Tentang".

Perlu disadari: pola ini membuat URL yang salah eja juga mengembalikan 200 (index.html). Ini trade-off SPA yang wajar; jika ingin 404 asli untuk aset hilang, pisahkan path aset (/assets/*) dari path halaman.

#Cache Headers yang Benar

Ini bagian yang paling sering salah: cache headers menentukan seberapa cepat (dan hemat bandwidth) situs kalian. Dua kategori aset:

ServeDir mendukung Cache-Control per konfigurasi (via ServeDirLayer atau memakai fallback handler kustom). Pendekatan sederhana: middleware yang menambahkan header cache untuk file di /assets/:

use axum::{extract::Request, middleware::Next, response::Response};
use tower_http::services::ServeDir;
 
async fn set_cache_headers(request: Request, next: Next) -> Response {
    let mut response = next.run(request).await;
    if request.uri().path().starts_with("/assets/") {
        if let Ok(value) =
            axum::http::HeaderValue::from_static("public, max-age=31536000, immutable")
        {
            response.headers_mut().insert("cache-control", value);
        }
    }
    response
}
 
fn app() -> Router {
    Router::new()
        .route("/api/health", axum::routing::get(|| async { "ok" }))
        .fallback_service(ServeDir::new("static"))
        .layer(axum::middleware::from_fn(set_cache_headers))
}

Aturan emasnya: file ber-hash → cache panjang; file tanpa hash → no-cache. Salah menerapkan immutable pada index.html adalah bug yang menyebalkan: pengguna tidak pernah melihat update.

#Menggabungkan dengan Compression

Compression dari episode 8 bekerja otomatis pada response ServeDir — karena kompresi adalah middleware yang membungkus semua service:

use tower_http::{compression::CompressionLayer, services::ServeDir};
 
fn app() -> Router {
    Router::new()
        .fallback_service(ServeDir::new("static"))
        .layer(CompressionLayer::new())
}

Hasilnya: file CSS/JS dikirim terkompresi (gzip/br) jika browser mendukung Accept-Encoding. Periksa dengan curl:

curl -s -o /dev/null -w "%{size_download} bytes\n" \
  -H "Accept-Encoding: gzip" http://localhost:3000/style.css

Angka yang keluar jauh lebih kecil daripada ukuran file asli menandakan kompresi bekerja.

#Alternatif: ServeFile untuk Satu File

Jika hanya perlu melayani satu file statis (misal favicon.ico atau robots.txt) tanpa folder:

use tower_http::services::ServeFile;
 
fn app() -> Router {
    Router::new()
        .route_service("/favicon.ico", ServeFile::new("static/favicon.ico"))
        .route_service("/robots.txt", ServeFile::new("static/robots.txt"))
}

route_service dipakai untuk memasang service (bukan handler) langsung ke route — ServeFile adalah service, jadi ini pasangannya yang tepat.

#Batasan dan Kapan Harus Pindah

ServeDir memuaskan untuk aset kecil, tapi ada batasannya:

• Tidak dirancang untuk load sangat tinggi — membaca file dari disk per request; untuk trafik besar, CDN/reverse proxy lebih baik.
• Tidak ada cache invalidation otomatis — CDN punya purge API, ServeDir tidak.
• Satu instance — jika aplikasi di-scale ke banyak instance di belakang load balancer, aset tetap harus diakses dari storage bersama.

Pola yang umum di produksi: Axum melayani API + index.html saja, sementara aset ber-hash ditaruh di CDN/object storage. Episode 20 dan 24 membahas arsitektur ini.

#Penutup

Pada episode 11 ini kalian telah melayani static files:

• ServeDir via fallback_service untuk melayani seluruh folder.
• not_found_service(ServeFile::new("static/index.html")) untuk fallback SPA.
• Cache headers: file ber-hash immutable, index.html no-cache.
• Kompresi otomatis pada aset statis.
• Kapan harus pindah ke CDN/reverse proxy.

Di episode 12 selanjutnya kita masuk mode real-time: WebSocket (dengan subprotocol) dan Server-Sent Events (SSE) — push data dari server ke klien untuk chat, notifikasi, dan dashboard langsung. Sampai jumpa di episode 12!