Belajar Caddy - URI Manipulation & Rewriting

#Pendahuluan

Tidak semua URL yang masuk sudah sempurna. Pengguna membuka /produk padahal file-nya bernama /produk.html. API lama memakai /v1 sementara yang baru /v2. SPA meminta semua route ke index.html. Semua ini ditangani dengan URI manipulation — dan episode 12 adalah tempatnya belajar.

#Directive rewrite

#Dasar Path Rewriting

rewrite mengubah path yang akan diproses handler, tanpa mengubah URL di browser:

example.com {
    rewrite /produk /produk.html
    root * /var/www
    file_server
}

Request ke /produk diubah menjadi /produk.html secara internal sebelum file_server mencari file. Browser tetap menampilkan /produk di address bar — bersih untuk SEO.

#Strip dan Tambah Prefix

Menghapus prefix adalah pola umum pada reverse proxy:

example.com {
    rewrite /api/* /api{path}
    reverse_proxy localhost:8080
}

Sebenarnya pola yang lebih sering dipakai adalah membuang prefix sebelum ke backend. Contoh memakai regex:

example.com {
    @api path /api/*
    handle @api {
        uri strip_prefix /api
        reverse_proxy localhost:8080
    }
}

uri strip_prefix /api menghapus /api dari path. Jadi /api/users menjadi /users saat diteruskan ke backend — backend tidak perlu tahu tentang prefix.

#Directive uri

#Manipulasi Query String

uri bisa menambah, mengubah, atau menghapus parameter query:

example.com {
    @tracked query campaign=*
    handle @tracked {
        uri query_upd utm_source caddy
        reverse_proxy localhost:8080
    }
}

uri query_upd utm_source caddy menambah atau memperbarui parameter utm_source=caddy. Berguna untuk pelacakan kampanye sebelum request diteruskan.

#Path Normalization

uri juga bisa menormalkan path — misalnya membersihkan titik ganda:

example.com {
    uri path_clean
    root * /var/www
    file_server
}

uri path_clean menormalkan segmen seperti /a/../b menjadi /b. Ini mencegah traversal path.

#Variables dan Placeholder

#Request Variables

Caddy menyediakan placeholder yang bisa dipakai di directive:

*.example.com {
    root * /var/www/sites/{host}
    file_server
}

Placeholder umum yang perlu kalian kenal:

• {host} — host dari request.
• {path} — path tanpa query.
• {query} — query string.
• {method} — metode request.
• {remote_host} — IP klien.

root * /var/www/sites/{host} memakai placeholder {host} untuk memilih direktori per subdomain — pola multi-tenant statis.

#Regex Capture Groups

Matcher path_regexp bisa menangkap bagian path dan memakainya kembali:

example.com {
    @artikel path_regexp ^/blog/([a-z0-9-]+)
    handle @artikel {
        rewrite /blog/{re.1} /posts/{re.1}.html
        root * /var/www
        file_server
    }
}

rewrite /blog/{re.1} /posts/{re.1}.html memakai {re.1}, grup tangkapan pertama dari regex — nama artikel yang ditangkap dari URL. Pola ini membuat URL bersih memetakan ke file fisik yang tersembunyi.

#try_files untuk Routing

#SPA Fallback

Pola paling umum untuk aplikasi React dan Vue:

app.example.com {
    root * /app/dist
    try_files {path} /index.html
    file_server
}

try_files {path} /index.html mencoba file sesuai path; jika tidak ada, jatuh ke index.html agar router SPA bekerja. Kita sudah menyentuh ini di episode 5 — di sini kalian melihat alasannya dari sisi URI.

#Custom 404 dan PHP Routing

Gabungkan fallback dengan halaman khusus:

example.com {
    root * /var/www
    try_files {path} {path}.html /404.html
    file_server
}

Jika file dan versi .html tidak ada, Caddy melayani 404.html dengan status 404. Untuk PHP, polanya menjadi:

example.com {
    root * /var/www
    php_fastcgi unix//run/php/php-fpm.sock
    try_files {path} index.php?{query}
}

try_files {path} index.php?{query} mengarahkan semua request yang tidak cocok dengan file ke index.php — pola front controller Laravel dan Symfony.

#Penutup

Episode 12 melengkapi senjata routing kalian: rewrite untuk perubahan path internal, uri untuk strip prefix dan manipulasi query, variables dan placeholder seperti {host}, {path}, dan {query}, regex capture groups dengan {re.1}, serta pola try_files untuk SPA, halaman 404, dan front controller PHP.

Inti yang harus dibawa pulang:

• rewrite mengubah path internal tanpa mengubah URL di browser.
• uri strip_prefix menghapus prefix sebelum diteruskan ke backend.
• Placeholder {host}, {path}, {query} tersedia di seluruh konfigurasi.
• Regex capture group dipakai lewat {re.1}.
• try_files {path} /index.html adalah pola SPA standar.
• Front controller PHP memakai try_files {path} index.php?{query}.

Di episode 13 selanjutnya kita akan membahas redirects & error handling — directive redir dengan semua status code, pola umum seperti www ke non-www dan redirect URL lama, custom error pages dengan handle_errors, serta directive respond untuk respons statis dan JSON.