Arsitektur Real-Time GraphQL Subscriptions dengan Redis Pub/Sub

1. Konteks Industri & Analisis Akar Masalah

Dalam lanskap arsitektur web modern, kebutuhan akan pembaruan data secara instan (real-time data streaming) telah bergeser dari sebuah fitur tambahan menjadi standar fundamental ekspektasi pengguna. Aplikasi seperti dashboard finansial, sistem pemantauan infrastruktur IT (observability), platform kolaborasi langsung, hingga sistem perdagangan e-dagang berkinerja tinggi menuntut latensi milidetik antara terjadinya suatu peristiwa (event) di server dan penyampaiannya ke klien peramban (browser).

Secara historis, pengembangan web bergantung pada teknik HTTP Long Polling atau Short Polling yang membebani jaringan dengan lalu lintas permintaan HTTP yang berulang dan redundan. Munculnya protokol WebSocket membawa solusi koneksi persisten dua arah (full-duplex), yang kemudian diintegrasikan secara elegan oleh ekosistem GraphQL melalui fitur GraphQL Subscriptions. Berbeda dengan Query dan Mutation yang beroperasi secara request-response satu arah, Subscriptions mempertahankan koneksi terbuka menggunakan protokol WebSocket untuk mendengarkan perubahan data secara asinkron.

Namun, ketika aplikasi bertumbuh dan menuntut skalabilitas horizontal (horizontal scaling), tantangan infrastruktur yang masif muncul. Pada arsitektur tunggal (monolithic), instance Node.js atau server backend tunggal dapat mengelola peta memori lokal untuk klien yang berlangganan. Ketika traffic melonjak dan infrastruktur diubah menjadi klaster dengan beberapa instance backend di balik load balancer (seperti Nginx atau AWS ALB), terjadilah masalah keterisolasian state (state isolation).

Masalah Utama: Keterisolasian State dalam Klaster

Jika Klien A terhubung ke Instance Backend 1 dan Klien B terhubung ke Instance Backend 2, ketika sebuah Mutation memicu peristiwa di Instance Backend 1, Klien B yang terhubung ke Instance Backend 2 tidak akan menerima pembaruan data tersebut karena memori lokal tidak tersinkronisasi antar-server. Bottleneck ini menyebabkan kegagalan pengiriman data real-time, inkonsistensi antarmuka pengguna, dan pemborosan sumber daya CPU akibat penanganan koneksi WebSocket yang tidak terdistribusi.

[!IMPORTANT] Tanpa mekanisme perutean pesan eksternal yang terdistribusi, arsitektur WebSocket berbasis klaster akan mengalami split-brain state issue di mana klien pada node berbeda terputus dari arus peristiwa global aplikasi.

Kondisi Sebelum vs Sesudah Penerapan

2. Konsep Inti & Deep Dive Arsitektur

Untuk mengatasi masalah fragmentasi state lintas node backend, kita memerlukan perantara pesan (message broker) berkecepatan tinggi yang bertindak sebagai pusat distribusi event global. Di sinilah Redis Pub/Sub berperan sebagai tulang punggung arsitektur.

Alur Kerja di Balik Layar (Under the Hood)

1. Koneksi Klien (Handshake): Klien mengirimkan permintaan upgrade HTTP ke protokol WebSocket melalui endpoint /graphql. Server backend menerima koneksi ini dan mendaftarkannya ke dalam sesi memori lokal.
2. Eksekusi Subscription: Klien mengirimkan dokumen GraphQL Subscription (misalnya: subscription { orderCreated { id total } }). Server mendaftarkan listener lokal untuk topik atau channel tertentu.
3. Mekanisme Pemicu (Mutation Trigger): Klien lain melakukan Mutation (misalnya: createOrder). Server backend yang memproses mutation ini tidak hanya memperbarui basis data (MySQL/PostgreSQL), tetapi juga mempublikasikan payload event ke Redis menggunakan perintah PUBLISH.
4. Distribusi Redis Pub/Sub: Redis menerima pesan tersebut dan secara instan menyiarkannya ke seluruh subscriber yang terhubung ke channel tersebut.
5. Penerimaan Lintas Node: Semua instance backend di dalam klaster yang berlangganan channel Redis tersebut menerima pesan, lalu meneruskannya secara lokal ke klien WebSocket yang relevan.

Diagram Visualisasi Arsitektur

+----------+       WebSocket       +--------------------+       Redis Pub/Sub       +--------------------+
| Client A | <-------------------> | Instance Backend 1 | <-----------------------> |                    |
+----------+                       +--------------------+                           |                    |
                                                                                   |   Redis Cluster    |----
+----------+       WebSocket       +--------------------+                           | (Message Broker)   |    |
| Client B | <-------------------> | Instance Backend 2 | <-----------------------> |                    |    |
+----------+                       +--------------------+                           +--------------------+    |
                                                                                                              |
                                             +----------------------------------------------------------------+
                                             |
                                             v
                                   +-------------------+
                                   | Database (MySQL)  |
                                   +-------------------+

3. Perbandingan Komparatif / Analisis Pendekatan

Memilih teknologi perantara untuk GraphQL Subscriptions menuntut analisis mendalam terhadap konsumsi sumber daya dan karakteristik beban kerja.

[!TIP] Untuk 95% kasus penggunaan aplikasi web modern yang membutuhkan real-time notifications dan live data sync, Redis Pub/Sub adalah pilihan optimal karena keseimbangan antara kecepatan milidetik dan kemudahan pengelolaan operasional.

4. Prasyarat Sistem & Persiapan Lingkungan

Sebelum menyelami implementasi kode, pastikan infrastruktur lokal atau server produksi Anda memenuhi spesifikasi teknis berikut:

• Node.js: Versi 18.x LTS atau 20.x LTS
• Redis Server: Versi 7.0+ (berjalan di port standar 6379 atau menggunakan Unix Domain Socket untuk performa maksimal)
• Web Server / Reverse Proxy: Nginx (sebagai SSL terminator dan WebSocket reverse proxy)
• Manajer Proses: PM2 atau Systemd untuk memastikan layanan Node.js berjalan secara daemon.

Verifikasi Instalasi Redis

Jalankan perintah berikut di terminal untuk memastikan Redis aktif dan merespons:

redis-cli ping
# Output yang diharapkan: PONG

5. Panduan Implementasi Langkah demi Langkah

Kita akan membangun sebuah aplikasi server Node.js menggunakan GraphQL-Yoga (atau Apollo Server dengan graphql-ws), Redis (ioredis), dan graphql-redis-subscriptions sebagai adaptor penghubung.

Langkah 1: Inisialisasi Proyek dan Instalasi Dependensi

Buat direktori baru dan instal paket yang diperlukan:

mkdir graphql-redis-subscriptions-demo
cd graphql-redis-subscriptions-demo
npm init -y
npm install graphql @graphql-yoga/node graphql-ws ioredis graphql-redis-subscriptions
npm install --save-dev typescript @types/node ts-node

Buat file konfigurasi TypeScript tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "rootDir": "./src",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"]
}

Langkah 2: Membuat Struktur Kode Sumber

Buat direktori src dan file src/index.ts:

mkdir src
touch src/index.ts

Isi file src/index.ts dengan kode lengkap implementasi server GraphQL, Redis Pub/Sub, dan WebSocket:

import { createServer } from 'http';
import { createPubSub } from '@graphql-yoga/node';
import { createYoga } from 'graphql-yoga';
import { useServer } from 'graphql-ws/lib/use-ws';
import { WebSocketServer } from 'ws';
import { RedisPubSub } from 'graphql-redis-subscriptions';
import Redis from 'ioredis';

// Konfigurasi koneksi Redis untuk Publisher dan Subscriber
const options = {
  host: process.env.REDIS_HOST || '127.0.0.1',
  port: parseInt(process.env.REDIS_PORT || '6379'),
  retryStrategy: (times: number) => Math.min(times * 50, 2000),
};

const publisher = new Redis(options);
const subscriber = new Redis(options);

// Inisialisasi RedisPubSub dengan instance terpisah
const pubSub = new RedisPubSub({
  publisher,
  subscriber,
});

const NOTIFICATION_CHANNEL = 'NOTIFICATION_CHANNEL';

// Skema Definisi GraphQL (SDL)
const typeDefs = `
  type Notification {
    id: ID!
    message: String!
    createdAt: String!
  }

  type Query {
    ping: String!
  }

  type Mutation {
    sendNotification(message: String!): Notification!
  }

  type Subscription {
    notificationAdded: Notification!
  }
`;

// Resolver GraphQL
const resolvers = {
  Query: {
    ping: () => 'pong',
  },
  Mutation: {
    sendNotification: async (_: any, { message }: { message: string }) => {
      const notification = {
        id: Math.random().toString(36.substring(2, 9)),
        message,
        createdAt: new Date().toISOString(),
      };

      // Publikasikan event ke Redis Pub/Sub
      await pubSub.publish(NOTIFICATION_CHANNEL, { notificationAdded: notification });

      return notification;
    },
  },
  Subscription: {
    notificationAdded: {
      // Berlangganan ke channel Redis melalui asyncIterator
      subscribe: () => pubSub.asyncIterator([NOTIFICATION_CHANNEL]),
    },
  },
};

// Inisialisasi Yoga Server
const yoga = createYoga({
  typeDefs,
  resolvers,
  graphqlEndpoint: '/graphql',
  landingPage: false,
});

// Membuat HTTP Server native Node.js
const server = createServer(yoga);

// Membuat WebSocket Server untuk menangani Subscriptions
const wsServer = new WebSocketServer({
  server,
  path: yoga.graphqlEndpoint,
});

// Mengintegrasikan graphql-ws dengan WebSocket Server
useServer(
  {
    execute: yoga.execute,
    subscribe: yoga.subscribe,
    onSubscribe: async (ctx, msg) => {
      console.log(`[WebSocket] Klien baru berlangganan:`, msg.id);
      return ctx;
    },
    onConnect: async (ctx) => {
      console.log(`[WebSocket] Klien terhubung dari IP:`, ctx.extra.request.socket.remoteAddress);
    },
    onDisconnect: () => {
      console.log(`[WebSocket] Klien terputus`);
    },
  },
  wsServer
);

const PORT = process.env.PORT || 4000;

server.listen(PORT, () => {
  console.log(`🚀 Server berjalan di http://localhost:${PORT}/graphql`);
  console.log(`🔌 WebSocket Subscription aktif di ws://localhost:${PORT}/graphql`);
});

Langkah 3: Konfigurasi Reverse Proxy Nginx untuk WebSocket

Agar aplikasi dapat diakses dengan aman di lingkungan produksi, konfigurasikan Nginx sebagai reverse proxy yang mendukung WebSocket upgrade headers.

Buat file konfigurasi /etc/nginx/sites-available/graphql-app:

upstream graphql_cluster {
    server 127.0.0.1:4000;
    # Tambahkan instance backend lain untuk klaster
    # server 127.0.0.1:4001;
}

server {
    listen 80;
    server_name api.example.com;

    # Redirect HTTP ke HTTPS (Let's Encrypt SSL)
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name api.example.com;

    ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    location /graphql {
        proxy_pass http://graphql_cluster;
        proxy_http_version 1.1;
        
        # Header penting untuk mendukung WebSocket Upgrade
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Timeout untuk koneksi WebSocket jangka panjang
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }
}

Aktifkan konfigurasi Nginx dan uji sintaksnya:

sudo ln -s /etc/nginx/sites-available/graphql-app /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

6. Bedah Kode & Penjelasan Detail Baris Kunci

Mari kita bedah beberapa komponen paling krusial dalam implementasi di atas:

1. Instance Redis Terpisah (publisher & subscriber):

   const publisher = new Redis(options);
   const subscriber = new Redis(options);
   

   [!WARNING] Berdasarkan spesifikasi protokol Redis, koneksi klien yang berada dalam mode Subscriber dilarang menjalankan perintah lain selain perintah manajemen channel (seperti SUBSCRIBE, UNSUBSCRIBE, PSUBSCRIBE). Oleh karena itu, kita wajib membuat dua instance koneksi Redis yang terpisah: satu untuk mempublikasikan pesan (publisher) dan satu untuk mendengarkan pesan (subscriber). Menggunakan satu instance untuk keduanya akan mengakibatkan Redis Protocol Error.

2. graphql-redis-subscriptions Adapter: Adaptor ini menerjemahkan fungsi pubSub.asyncIterator() GraphQL menjadi mekanisme berlangganan channel Redis di balik layar. Setiap kali mutation memanggil pubSub.publish(), adaptor mengirimkan string JSON terserialisasi ke Redis, yang kemudian didistribusikan ke seluruh node klaster.

3. graphql-ws vs subscriptions-transport-ws: Perhatikan bahwa kita menggunakan pustaka graphql-ws dan bukan subscriptions-transport-ws (yang saat ini telah dinyatakan deprecated oleh komunitas). graphql-ws sepenuhnya mematuhi standar protokol WebSocket GraphQL modern, mendukung penanganan ping/pong heartbeat bawaan, serta manajemen siklus hidup koneksi yang jauh lebih aman.

7. Skenario Produksi & Studi Kasus Dunia Nyata

Dalam studi kasus implementasi platform perdagangan saham (High-Frequency Trading Dashboard), klaster Node.js beroperasi dengan 8 instance di belakang AWS Application Load Balancer (ALB).

• Tantangan: 50.000 klien aktif bersamaan (concurrent connections) menerima pembaruan harga instan per detik.
• Solusi Infrastruktur:
  • Menggunakan Redis Cluster dengan arsitektur Master-Replica untuk mencegah bottleneck pada broker pesan.
  • Mengonfigurasi parameter sistem kernel Linux (sysctl.conf) untuk meningkatkan batas maksimum deskriptor file (file descriptors) agar server mampu menampung puluhan ribu koneksi TCP terbuka secara bersamaan.

Optimasi parameter kernel /etc/sysctl.conf untuk menangani high concurrency:

# Meningkatkan batas maksimal file descriptors
fs.file-max = 2097152

# Optimasi network socket buffer
net.core.somaxconn = 65535
net.ipv4.tcp_max_syn_backlog = 65535
net.ipv4.ip_local_port_range = 1024 65535

Terapkan perubahan dengan perintah:

sudo sysctl -p

8. Common Pitfalls, Anti-Patterns & Solusi

1. Anti-Pattern: Menyimpan State Autentikasi di Memori Lokal WebSocket

   • Masalah: Menyimpan token sesi atau status pengguna hanya pada saat handshake awal tanpa mekanisme validasi ulang berkala.
   • Solusi: Manfaatkan fungsi onConnect pada graphql-ws untuk memverifikasi token JWT secara kriptografis sebelum koneksi WebSocket diterima.

2. Pitfalls: Kebocoran Memori (Memory Leak) pada AsyncIterator

   • Masalah: Klien terputus secara tidak normal (abrupt disconnect) tanpa membersihkan listener di memori Redis.
   • Solusi: Pastikan pustaka adaptor menangani pembersihan subscription secara otomatis saat koneksi WebSocket tertutup (cleanup on close).

3. Kesalahan Konfigurasi Timeout Nginx

   • Masalah: Koneksi WebSocket terputus secara otomatis setiap 60 detik oleh Nginx.
   • Solusi: Selalu tambahkan proxy_read_timeout 86400s; dan proxy_send_timeout 86400s; pada blok konfigurasi Nginx reverse proxy.

9. Benchmark, Metrik Kinerja & Tuning Performa

Pengujian beban (load testing) untuk layanan berbasis WebSocket dan GraphQL Subscriptions tidak dapat dilakukan dengan alat pengujian HTTP konvensional seperti ApacheBench (ab) karena sifat koneksinya yang persisten.

Pengujian Menggunakan Artillery.io atau k6

Berikut adalah skrip pengujian k6 (load-test.js) untuk mensimulasikan klien yang terhubung via WebSocket dan berlangganan topik GraphQL:

import ws from 'k6/ws';
import { check, sleep } from 'k6';

export const options = {
  stages: [
    { duration: '30s', target: 1000 }, // Ramp up ke 1000 pengguna
    { duration: '1m', target: 1000 },  // Pertahankan beban
    { duration: '30s', target: 0 },    // Ramp down
  ],
};

export default function () {
  const url = 'ws://localhost:4000/graphql';
  const params = { headers: { 'sec-websocket-protocol': 'graphql-transport-ws' } };

  const res = ws.connect(url, params, function (socket) {
    socket.on('open', function () {
      // Kirim pesan inisialisasi koneksi graphql-ws
      socket.send(JSON.stringify({ type: 'connection_init' }));
    });

    socket.on('message', function (message) {
      const data = JSON.parse(message);
      if (data.type === 'connection_ack') {
        // Kirim permintaan subscription
        socket.send(JSON.stringify({
          id: '1',
          type: 'subscribe',
          payload: {
            query: 'subscription { notificationAdded { id message } }',
          },
        }));
      }
    });

    socket.setTimeout(function () {
      socket.close();
    }, 20000);
  });

  check(res, { 'koneksi WebSocket sukses': (r) => r && r.status === 101 });
  sleep(1);
}

Jalankan pengujian menggunakan k6:

k6 run load-test.js

10. Checklist Penerapan Produksi & Kesimpulan

Sebelum meluncurkan arsitektur GraphQL Subscriptions berbasis Redis Pub/Sub ke lingkungan produksi (production deployment), pastikan Anda telah memverifikasi seluruh daftar periksa berikut:

• Keamanan Transportasi: Seluruh lalu lintas WebSocket wajib menggunakan enkripsi TLS (wss://) melalui sertifikat SSL/TLS valid (Let's Encrypt).
• Autentikasi & Otorisasi: Token JWT divalidasi pada tahap onConnect WebSocket sebelum sesi berlangganan diizinkan.
• Koneksi Redis: Menggunakan dua instance terpisah untuk publisher dan subscriber, serta mengaktifkan proteksi password Redis (requirepass).
• Optimasi Reverse Proxy: Nginx dikonfigurasi dengan header Upgrade dan perpanjangan proxy_read_timeout.
• Manajemen Proses & Pemantauan: Aplikasi Node.js dikelola menggunakan PM2 atau Systemd dengan konfigurasi auto-restart, serta integrasi pemantauan metrik CPU/RAM melalui Prometheus dan Grafana.

Dengan menerapkan arsitektur ini secara disiplin, sistem Anda tidak hanya mampu memberikan pengalaman pengguna yang sangat responsif secara real-time, tetapi juga memiliki tingkat ketahanan, skalabilitas, dan keamanan kelas enterprise yang siap menghadapi lonjakan traffic masif.