Belajar Nginx - WebSocket, Server-Sent Events (SSE) & gRPC Proxying

#Pendahuluan

Aplikasi modern tidak hanya meminta dan menerima data. Chat, notifikasi realtime, dan microservices berkomunikasi dengan protokol khusus: WebSocket, Server-Sent Events, dan gRPC. Episode 13 ini membahas cara NGINX mem-proxy ketiganya dengan benar.

Ketiga protokol ini gagal total jika ditangani seperti HTTP biasa. WebSocket butuh upgrade header khusus, SSE terganggu buffering, dan gRPC memerlukan listener khusus. Setelah episode ini, kalian akan memahami perbedaan perlakuan masing-masing.

#WebSocket Proxying

#Kenapa WebSocket Butuh Upgrade Header

WebSocket dimulai sebagai HTTP, lalu koneksi di-upgrade menjadi bidirectional. Proses upgrade terjadi lewat header Upgrade dan Connection. NGINX harus meneruskan kedua header ini agar backend dan klien tahu mereka bicara WebSocket:

location /ws/ {
    proxy_pass http://backend_realtime;
    proxy_http_version 1.1;
 
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
 
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

Tanpa proxy_set_header Upgrade $http_upgrade; dan Connection "upgrade", koneksi tidak akan di-upgrade dan WebSocket gagal. Kunci lainnya: proxy_http_version 1.1; karena HTTP/1.0 tidak mendukung header upgrade, dan timeout diperpanjang karena koneksi WebSocket bisa terbuka lama.

#Server-Sent Events (SSE) Proxying

#Mematikan Buffering agar Stream Lancar

SSE adalah aliran data satu arah dari server ke klien: server mengirim event terus-menerus dalam satu koneksi HTTP. Masalahnya, NGINX secara default menumpuk respons di buffer sebelum mengirim. Untuk SSE, buffering ini menahan event dan menghancurkan sifat realtime-nya:

location /events/ {
    proxy_pass http://backend_realtime;
 
    proxy_buffering off;
    proxy_cache off;
 
    proxy_set_header Connection "";
    proxy_http_version 1.1;
    proxy_read_timeout 3600s;
}

• proxy_buffering off; — respons diteruskan ke klien segera, event tidak tertahan.
• proxy_set_header Connection ""; — menolak header connection, mencegah NGINX menutup koneksi idle.
• proxy_read_timeout 3600s; — koneksi SSE bisa bertahan sangat lama.

Dengan konfigurasi ini, setiap event yang dikirim backend sampai ke browser tanpa penundaan buffering.

#gRPC Services Proxying

#Perbedaan gRPC dari HTTP Biasa

gRPC adalah RPC berperforma tinggi berbasis HTTP/2. Karena berjalan di atas HTTP/2, ia tidak bisa di-proxy lewat listener HTTP/1.1 biasa. NGINX versi modern menyediakan directive khusus:

server {
    listen 50051 http2;
    listen 50051 ssl http2;
 
    grpc_pass grpcs://backend_grpc_service;
}
 
upstream backend_grpc_service {
    server 10.0.2.21:50051;
    server 10.0.2.22:50051;
}

Perhatikan directive listen 50051 http2; dan listen 50051 ssl http2; untuk trafik gRPC terenkripsi, lalu grpc_pass grpcs://backend_grpc_service; sebagai target. grpc_pass mirip proxy_pass, tapi memahami protokol gRPC: streaming, metadata, dan error codes diteruskan secara native.

#Kombinasi gRPC dan REST dalam Satu Domain

Banyak aplikasi memakai gRPC internal dan REST untuk publik. Keduanya bisa hidup berdampingan:

server {
    listen 443 ssl http2;
    server_name api.example.com;
 
    location / {
        grpc_pass grpcs://backend_grpc_service;
    }
 
    location /rest/ {
        proxy_pass http://backend_rest;
    }
}

Satu listener 443 HTTP/2 melayani gRPC dan REST sekaligus; routing ditentukan oleh path.

#Penutup

Episode 13 menuntaskan protokol realtime: kalian bisa mem-proxy WebSocket dengan upgrade header, menyajikan SSE tanpa buffering, dan meneruskan gRPC dengan grpc_pass di atas HTTP/2.

Inti yang harus dibawa pulang:

• WebSocket butuh Upgrade dan Connection "upgrade" plus HTTP/1.1.
• Koneksi WebSocket dan SSE butuh timeout panjang.
• proxy_buffering off membuat SSE realtime tanpa penundaan.
• proxy_set_header Connection "" mencegah koneksi SSE ditutup dini.
• gRPC butuh listener HTTP/2 dan directive grpc_pass.
• REST dan gRPC bisa berbagi satu listener 443 dengan routing per path.

Di episode 14 selanjutnya kita akan membahas reusable, modular, dan maintainable configuration architecture — konvensi sites-available dan sites-enabled, direktori includes untuk snippet reusable, serta injeksi environment variable dengan envsubst di Docker.