Saga Pattern di NestJS: Transaksi Terdistribusi Tanpa 2PC

Begitu alur checkout menyentuh tiga layanan, layanan pesanan, layanan pembayaran, dan layanan inventaris, satu transaksi database tunggal berhenti menjadi pilihan. Setiap layanan memiliki database sendiri, sehingga tidak ada koneksi bersama yang bisa dibungkus dalam BEGIN dan COMMIT. Two-phase commit menjanjikan atomisitas lintas node, tetapi caranya adalah menahan lock lintas jaringan sementara setiap peserta menunggu koordinator memberi sinyal lanjut, dan jika koordinator itu tidak tersedia di tengah proses voting, seluruh peserta bisa terblokir tanpa batas waktu.

Saga pattern menyelesaikan masalah yang sama dengan trade-off berbeda. Alih-alih satu transaksi atomik, saga adalah rangkaian transaksi lokal, masing-masing langsung di-commit di layanannya sendiri, dengan aksi kompensasi yang didefinisikan untuk setiap langkah jika langkah berikutnya gagal. Artikel ini membahas implementasi saga di NestJS menggunakan modul CQRS resmi, membandingkan orkestrasi dan koreografi, serta aturan idempotensi yang menjaga kompensasi tetap aman ketika pesan dikirim ulang.

Mengapa two-phase commit tidak cocok untuk microservices

Two-phase commit (2PC) bekerja baik di dalam satu cluster database karena koordinator dan peserta berbagi koneksi cepat dan andal serta domain kegagalan yang sama. Ketika tersebar di layanan yang di-deploy secara independen dengan database masing-masing, tiga masalah muncul dengan cepat.

• Blocking: jika koordinator crash setelah peserta memberi suara setuju tetapi sebelum pesan commit dikirim, setiap peserta menahan lock-nya hingga koordinator pulih, membekukan permintaan lain yang menyentuh baris data yang sama.
• Coupling: setiap layanan dalam transaksi harus mendukung protokol yang sama dan bisa dijangkau secara sinkron pada saat yang bersamaan, yang justru meniadakan tujuan men-deploy layanan secara independen.
• Availability: 2PC menukar ketersediaan demi konsistensi dengan cara yang tidak sesuai dengan bagaimana kebanyakan tim produk ingin alur checkout atau pendaftaran mereka berperilaku saat terjadi gangguan parsial.

Orkestrasi vs koreografi

Ada dua cara menyusun alur kontrol sebuah saga. Pada koreografi, setiap layanan mendengarkan event yang dipublikasikan layanan lain dan memutuskan sendiri langkah berikutnya, tanpa koordinator pusat. Pada orkestrasi, satu komponen orchestrator menyimpan urutan langkah beserta kompensasinya, mengirim perintah ke setiap layanan secara berurutan dan bereaksi terhadap hasilnya. Keduanya valid; pilihan yang tepat bergantung pada berapa banyak layanan yang terlibat dan seberapa besar kebutuhan tim akan visibilitas alur tersebut.

Mengimplementasikan saga terorkestrasi dengan NestJS CQRS

NestJS menyediakan modul CQRS dengan decorator Saga yang dibuat khusus untuk kasus ini. Metode saga menerima stream observable dari setiap event yang dikirim lewat event bus, menyaringnya dengan operator ofType, lalu memetakan event yang cocok menjadi command baru yang otomatis dikirim oleh command bus. Ini menjaga logika orkestrasi tetap deklaratif: bereaksi terhadap sebuah event, memancarkan command berikutnya, atau memancarkan command kompensasi ketika ada langkah sebelumnya yang melaporkan kegagalan.

// order-saga.ts
import { ICommand, ofType, Saga } from '@nestjs/cqrs'
import { Injectable } from '@nestjs/common'
import { Observable } from 'rxjs'
import { map } from 'rxjs/operators'
import { OrderCreatedEvent } from './events/order-created.event'
import { ReserveInventoryCommand } from './commands/reserve-inventory.command'
import { InventoryReservationFailedEvent } from './events/inventory-reservation-failed.event'
import { CancelOrderCommand } from './commands/cancel-order.command'

@Injectable()
export class OrderSaga {
  @Saga()
  orderCreated = (events$: Observable<ICommand>): Observable<ICommand> => {
    return events$.pipe(
      ofType(OrderCreatedEvent),
      map((event) => new ReserveInventoryCommand(event.orderId, event.items)),
    )
  }

  // Compensating step: undo the order if a downstream step fails
  @Saga()
  inventoryReservationFailed = (events$: Observable<ICommand>): Observable<ICommand> => {
    return events$.pipe(
      ofType(InventoryReservationFailedEvent),
      map((event) => new CancelOrderCommand(event.orderId, event.reason)),
    )
  }
}

Setiap command handler dalam rangkaian ini menjalankan satu transaksi lokal dan mempublikasikan event sukses yang direspons saga berikutnya, atau event gagal yang memicu kompensasi yang sesuai. Orchestrator itu sendiri, kelas OrderSaga, tidak pernah berbicara langsung ke database layanan lain. Ia hanya mengenal bentuk event yang masuk dan command yang keluar, sehingga tetap mudah diuji tanpa harus menjalankan setiap layanan hilir.

Merancang aksi kompensasi dengan benar

Aksi kompensasi bukan sekadar kebalikan dari aksi maju; ia harus membalikkan efek bisnisnya dengan memperhitungkan apa pun yang terjadi di antaranya. Empat aturan berikut menjaga kompensasi tetap andal dalam praktik.

1. Kompensasi harus berlawanan secara semantik, bukan sekadar berlawanan secara struktural: membatalkan reservasi tidak sama dengan menghapus catatan reservasi jika layanan hilir sudah membaca keberadaannya untuk mengambil keputusan sendiri.
2. Kompensasi harus bisa diulang, karena pesan yang memicu kompensasi bisa dikirim ulang setelah gangguan jaringan, restart consumer, atau jaminan pengiriman at-least-once yang terpicu dua kali.
3. Kompensasi harus tetap toleran meski langkah maju belum pernah terjadi, karena kegagalan yang memicu kompensasi bisa saja tiba sebelum event sukses dari langkah maju itu sendiri, tergantung urutan pesan.
4. Kompensasi harus dicatat, bukan terus dicoba ulang tanpa henti secara diam-diam, sehingga operator bisa melihat saga mana yang macet dalam state kompensasi sebagian dan melakukan intervensi manual jika retry otomatis sudah habis.

// cancel-order.handler.ts
@CommandHandler(CancelOrderCommand)
export class CancelOrderHandler implements ICommandHandler<CancelOrderCommand> {
  constructor(
    private readonly orders: OrderRepository,
    private readonly ledger: ProcessedStepLedger, // dedupe table keyed by (sagaId, step)
  ) {}

  async execute(command: CancelOrderCommand): Promise<void> {
    const { orderId, reason } = command

    // Idempotency check — a redelivered event must not double-compensate
    const alreadyHandled = await this.ledger.wasProcessed(orderId, 'cancel-order')
    if (alreadyHandled) return

    const order = await this.orders.findById(orderId)
    if (order.status === 'cancelled') return // already terminal, safe no-op

    order.cancel(reason)
    await this.orders.save(order)
    await this.ledger.markProcessed(orderId, 'cancel-order')
  }
}

Idempotensi: properti yang membuat retry aman

Message broker mayoritas lebih memilih pengiriman at-least-once dibanding exactly-once, karena pengiriman exactly-once lintas gangguan jaringan sebenarnya tidak bisa dicapai tanpa kerja sama dari penerima. Artinya, setiap command handler dalam saga, baik langkah maju maupun kompensasi, pada akhirnya akan dipanggil dua kali untuk event logis yang sama. Solusinya bukan deduplikasi di sisi broker; melainkan merancang setiap handler agar penerapannya dua kali menghasilkan state akhir yang sama seperti diterapkan satu kali.

• Periksa state entitas saat ini sebelum bertindak: jika sebuah pesanan sudah berstatus dibatalkan, CancelOrderCommand kedua seharusnya menjadi no-op, bukan efek samping pembatalan kedua.
• Lacak identitas langkah yang sudah diproses dalam tabel ledger kecil berkunci id saga dan nama langkah, lalu lewati eksekusi jika baris yang cocok sudah ada.
• Buat efek samping seperti mengirim email konfirmasi bersyarat pada flag pertama-kali dari pemeriksaan ledger, bukan pada kedatangan command itu sendiri, karena kedatangan tidak berarti kebaruan.

Kapan saga benar-benar layak digunakan

Saga menambah biaya operasional yang nyata: lebih banyak tipe event, tabel ledger untuk idempotensi, dan model mental yang mencakup banyak layanan alih-alih hidup dalam satu fungsi. Biaya itu terbayar ketika sebuah proses bisnis memang melintasi batas layanan dan butuh konsistensi eventual dengan jalur pemulihan yang jelas, seperti pemenuhan pesanan yang menyentuh pembayaran, inventaris, dan pengiriman. Saga menjadi alat yang salah ketika data sebenarnya milik satu layanan; perbaikan yang tepat biasanya menyatukan kepemilikan, bukan menambahkan saga di atas batas yang sudah salah.