Skip to content
Santekno.com | Level Up Your Engineering Skills
ID
📖 0%
17 Nov 2026 · 24 mnt baca ·Artikel 90 / 208
Go

Golang Notification Service: Kafka Consumer, Email Template, Event-Driven

Implementasi Notification Service Santekno Shop. Kafka consumer untuk order/payment events, email template dengan Go text/template, async processing, dan dead letter queue pattern.

IH
Ihsan Arif
Penulis di Santekno · Backend Engineer

Golang notification service dengan Kafka consumer adalah komponen terakhir yang menutup event lifecycle Santekno Shop. Service ini meng-consume semua event yang di-publish service lain via Kafka — topik santekno.orders.* dan santekno.payments.* — lalu mengirim notifikasi email yang relevan ke customer. Polanya jelas: event-driven, async, dan idempotent supaya duplicate event tidak pernah menghasilkan email ganda.

Di artikel ini kita bangun Notification Service dari nol: domain entity, email template, Kafka consumer group dengan manual commit, sampai dead letter queue untuk failure yang permanen.


10.01 Arsitektur Notification Service

Sebelum menulis kode, penting memahami alur event dari service produsen sampai email terkirim ke customer. Diagram berikut memetakan perjalanan sebuah event dari DB transaction hingga Kafka offset di-commit.

text
 1Event Flow:
 2
 3Order/Payment Service
 4  → DB transaction + outbox_events
 5  → Outbox Worker (Artikel 12)
 6  → Kafka Topics:
 7      santekno.orders.placed
 8      santekno.orders.confirmed
 9      santekno.orders.cancelled
10      santekno.orders.shipped
11      santekno.payments.completed
12      santekno.payments.failed
13
14Notification Service (Kafka Consumer):
15  → Consume event
16  → Lookup user email dari DB
17  → Render email template
18  → Send via SMTP/email provider
19  → Log notification ke DB
20  → Commit Kafka offset (acknowledge)
21
22At-least-once: jika kirim email gagal setelah commit → duplicate possible
23Solution: notification_logs table dengan idempotency key (event_id)

Poin kunci dari diagram ini: karena Kafka memberi jaminan at-least-once, satu-satunya cara mencegah email ganda adalah idempotency key event_id di tabel notifications — itulah pondasi semua handler yang kita tulis berikutnya.


10.02 Domain: Notification Entity

Domain entity mendefinisikan bentuk data notifikasi yang independen dari infrastruktur Kafka maupun SMTP. Struct berikut menyimpan status, channel, dan yang paling penting EventID sebagai idempotency key.

go
 1// internal/domain/notification/entity.go
 2
 3package notification
 4
 5import (
 6    "errors"
 7    "time"
 8    "github.com/google/uuid"
 9)
10
11var (
12    ErrNotificationFailed = errors.New("notification send failed")
13    ErrTemplateNotFound   = errors.New("notification template not found")
14)
15
16type Channel string
17const (
18    ChannelEmail Channel = "EMAIL"
19    ChannelPush  Channel = "PUSH"
20)
21
22type Status string
23const (
24    StatusPending Status = "PENDING"
25    StatusSent    Status = "SENT"
26    StatusFailed  Status = "FAILED"
27)
28
29type Notification struct {
30    ID           uuid.UUID
31    UserID       uuid.UUID
32    Channel      Channel
33    TemplateKey  string
34    Subject      string
35    Body         string
36    RecipientEmail string
37    Status       Status
38    EventID      string  // idempotency key — dari Kafka event ID
39    EventType    string  // "order.confirmed", "payment.completed", dll
40    CreatedAt    time.Time
41    SentAt       *time.Time
42    Error        *string
43}
44
45// NotificationData: data yang di-inject ke template
46type NotificationData struct {
47    CustomerName   string
48    OrderID        string
49    TotalAmountIDR int64
50    PaymentMethod  string
51    Items          []NotificationItem
52    PaymentURL     string
53    CancelDeadline string // formatted time
54}
55
56type NotificationItem struct {
57    ProductName  string
58    Quantity     int
59    SubtotalIDR  int64
60}

Dengan EventID dan Status sebagai bagian dari entity, setiap notifikasi bisa di-trace dari event asalnya sampai statusnya terkirim atau gagal — dasar untuk audit trail dan retry.


10.03 Email Templates

Notifikasi butuh isi email yang dinamis per jenis event. Kode berikut memakai text/template Go untuk mendefinisikan subject dan body per template key, lengkap dengan helper formatIDR untuk memformat rupiah.

go
  1// internal/notification/template/templates.go
  2
  3package template
  4
  5import (
  6    "bytes"
  7    "fmt"
  8    "text/template"
  9)
 10
 11type TemplateKey string
 12const (
 13    TmplOrderPlaced    TemplateKey = "order_placed"
 14    TmplOrderConfirmed TemplateKey = "order_confirmed"
 15    TmplOrderCancelled TemplateKey = "order_cancelled"
 16    TmplOrderShipped   TemplateKey = "order_shipped"
 17    TmplPaymentFailed  TemplateKey = "payment_failed"
 18)
 19
 20var templates = map[TemplateKey]emailTemplate{
 21    TmplOrderPlaced: {
 22        Subject: "Pesanan #{{.OrderID}} Berhasil Dibuat — Santekno Shop",
 23        Body: `Halo {{.CustomerName}},
 24
 25Pesanan Anda telah berhasil dibuat!
 26
 27Detail Pesanan:
 28Order ID: {{.OrderID}}
 29{{range .Items}}- {{.ProductName}} x{{.Quantity}}: {{formatIDR .SubtotalIDR}}
 30{{end}}
 31Total: {{formatIDR .TotalAmountIDR}}
 32Metode Pembayaran: {{.PaymentMethod}}
 33
 34Segera selesaikan pembayaran sebelum {{.CancelDeadline}}:
 35{{.PaymentURL}}
 36
 37Terima kasih telah berbelanja di Santekno Shop!
 38`,
 39    },
 40    TmplOrderConfirmed: {
 41        Subject: "Pembayaran Dikonfirmasi — Pesanan #{{.OrderID}} Sedang Diproses",
 42        Body: `Halo {{.CustomerName}},
 43
 44Pembayaran Anda telah dikonfirmasi! Pesanan Anda sedang kami proses.
 45
 46Order ID: {{.OrderID}}
 47Total: {{formatIDR .TotalAmountIDR}}
 48
 49Kami akan mengirimkan notifikasi ketika pesanan Anda dikirim.
 50
 51Terima kasih!
 52— Tim Santekno Shop
 53`,
 54    },
 55    TmplOrderCancelled: {
 56        Subject: "Pesanan #{{.OrderID}} Dibatalkan",
 57        Body: `Halo {{.CustomerName}},
 58
 59Pesanan Anda dengan ID {{.OrderID}} telah dibatalkan.
 60
 61Jika Anda membatalkan sendiri: tidak ada tindakan lebih lanjut.
 62Jika pembayaran gagal: silakan buat pesanan baru.
 63
 64Ada pertanyaan? Hubungi support kami.
 65
 66— Tim Santekno Shop
 67`,
 68    },
 69    TmplPaymentFailed: {
 70        Subject: "Pembayaran Gagal — Pesanan #{{.OrderID}}",
 71        Body: `Halo {{.CustomerName}},
 72
 73Maaf, pembayaran untuk pesanan #{{.OrderID}} gagal diproses.
 74Pesanan Anda telah dibatalkan dan stok telah dikembalikan.
 75
 76Silakan buat pesanan baru untuk melanjutkan pembelian.
 77
 78— Tim Santekno Shop
 79`,
 80    },
 81}
 82
 83type emailTemplate struct {
 84    Subject string
 85    Body    string
 86}
 87
 88type Renderer struct {
 89    funcs template.FuncMap
 90}
 91
 92func NewRenderer() *Renderer {
 93    return &Renderer{
 94        funcs: template.FuncMap{
 95            "formatIDR": func(cents int64) string {
 96                return fmt.Sprintf("Rp %.0f", float64(cents)/100)
 97            },
 98        },
 99    }
100}
101
102type RenderedEmail struct {
103    Subject string
104    Body    string
105}
106
107func (r *Renderer) Render(key TemplateKey, data interface{}) (*RenderedEmail, error) {
108    tmpl, ok := templates[key]
109    if !ok {
110        return nil, fmt.Errorf("template.Render: unknown key %s", key)
111    }
112
113    subjectTmpl, err := template.New("subject").Funcs(r.funcs).Parse(tmpl.Subject)
114    if err != nil {
115        return nil, fmt.Errorf("template.Render: parse subject: %w", err)
116    }
117    bodyTmpl, err := template.New("body").Funcs(r.funcs).Parse(tmpl.Body)
118    if err != nil {
119        return nil, fmt.Errorf("template.Render: parse body: %w", err)
120    }
121
122    var subjectBuf, bodyBuf bytes.Buffer
123    if err := subjectTmpl.Execute(&subjectBuf, data); err != nil {
124        return nil, fmt.Errorf("template.Render: execute subject: %w", err)
125    }
126    if err := bodyTmpl.Execute(&bodyBuf, data); err != nil {
127        return nil, fmt.Errorf("template.Render: execute body: %w", err)
128    }
129
130    return &RenderedEmail{
131        Subject: subjectBuf.String(),
132        Body:    bodyBuf.String(),
133    }, nil
134}

Dengan menyimpan template di satu map dan me-render lewat Renderer, menambah jenis notifikasi baru hanya butuh satu entry — logika pengiriman tidak perlu diubah sama sekali.


10.04 Email Sender Interface

Pengiriman email disembunyikan di balik interface agar handler tidak terikat ke provider tertentu. Kode berikut mendefinisikan Sender dengan dua implementasi: SMTP untuk production dan NoOp untuk development.

go
 1// internal/notification/email/sender.go
 2
 3package email
 4
 5import "context"
 6
 7//go:generate mockgen -destination=../../../testutil/mock/email_sender_mock.go -package=mock -source=sender.go
 8
 9type Sender interface {
10    Send(ctx context.Context, msg Message) error
11}
12
13type Message struct {
14    To      string
15    Subject string
16    Body    string
17    IsHTML  bool
18}
19
20// SMTPSender: implementasi via Go's net/smtp
21type SMTPSender struct {
22    host     string
23    port     int
24    from     string
25    username string
26    password string
27}
28
29func NewSMTPSender(host string, port int, from, username, password string) *SMTPSender {
30    return &SMTPSender{host: host, port: port, from: from, username: username, password: password}
31}
32
33func (s *SMTPSender) Send(ctx context.Context, msg Message) error {
34    // Implementasi SMTP — simplified untuk artikel ini
35    // Production: gunakan library seperti gopkg.in/gomail.v2
36    addr := fmt.Sprintf("%s:%d", s.host, s.port)
37    auth := smtp.PlainAuth("", s.username, s.password, s.host)
38
39    body := fmt.Sprintf("From: %s\r\nTo: %s\r\nSubject: %s\r\n\r\n%s",
40        s.from, msg.To, msg.Subject, msg.Body)
41
42    return smtp.SendMail(addr, auth, s.from, []string{msg.To}, []byte(body))
43}
44
45// NoOpSender: untuk development/testing
46type NoOpSender struct{}
47
48func (s *NoOpSender) Send(ctx context.Context, msg Message) error {
49    fmt.Printf("[NOTIFICATION] To: %s | Subject: %s\n", msg.To, msg.Subject)
50    return nil
51}

Interface Sender membuat handler bisa di-test dengan mock dan dijalankan lokal tanpa SMTP server — cukup ganti implementasi menjadi NoOpSender di environment development.


10.05 Notification Repository

Repository menyimpan setiap notifikasi ke database, termasuk pengecekan idempotency lewat GetByEventID. Interface berikut mendefinisikan kontrak persistensinya.

go
 1// internal/domain/notification/repository.go
 2
 3package notification
 4
 5import "context"
 6
 7//go:generate mockgen -destination=../../../testutil/mock/notification_repo_mock.go -package=mock -source=repository.go
 8
 9type Repository interface {
10    Create(ctx context.Context, n *Notification) error
11    GetByEventID(ctx context.Context, eventID string) (*Notification, error) // idempotency
12    UpdateStatus(ctx context.Context, id string, status Status, errMsg *string) error
13}

Method GetByEventID inilah gerbang idempotency di level aplikasi; ia dipasangkan dengan constraint UNIQUE di skema tabel berikut sebagai proteksi ganda.

Skema tabel notifications memberi proteksi lapis kedua lewat event_id UNIQUE dan menyiapkan index untuk query retry. Migration berikut mendefinisikan tabel beserta index-nya.

sql
 1-- migrations/20260701000010_create_notifications.up.sql
 2
 3CREATE TYPE notification_channel AS ENUM ('EMAIL', 'PUSH');
 4CREATE TYPE notification_status AS ENUM ('PENDING', 'SENT', 'FAILED');
 5
 6CREATE TABLE notifications (
 7    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
 8    user_id UUID NOT NULL REFERENCES users(id),
 9    channel notification_channel NOT NULL,
10    template_key VARCHAR(50) NOT NULL,
11    subject TEXT,
12    body TEXT,
13    recipient_email VARCHAR(255),
14    status notification_status NOT NULL DEFAULT 'PENDING',
15    event_id VARCHAR(255) UNIQUE,   -- idempotency key
16    event_type VARCHAR(100),
17    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
18    sent_at TIMESTAMPTZ,
19    error_message TEXT
20);
21
22CREATE INDEX idx_notifications_user_id ON notifications(user_id);
23CREATE INDEX idx_notifications_event_id ON notifications(event_id);
24CREATE INDEX idx_notifications_status ON notifications(status)
25    WHERE status = 'PENDING';

Constraint UNIQUE pada event_id memastikan bahwa meskipun ada bug di level aplikasi, database tetap menolak insert duplicate — pertahanan terakhir melawan email ganda.


10.06 Kafka Consumer Setup

Inti service adalah Kafka consumer group yang membaca pesan dan mendelegasikan ke handler per topic. Kode berikut memakai sarama dengan manual commit — offset hanya maju setelah pesan berhasil diproses.

go
 1// internal/notification/consumer/kafka_consumer.go
 2
 3package consumer
 4
 5import (
 6    "context"
 7    "encoding/json"
 8    "fmt"
 9    "log"
10
11    "github.com/IBM/sarama"
12    "github.com/santekno/santekno-shop/internal/notification/handler"
13)
14
15type KafkaConsumer struct {
16    client   sarama.ConsumerGroup
17    topics   []string
18    handlers map[string]handler.EventHandler
19}
20
21func NewKafkaConsumer(brokers []string, groupID string, handlers map[string]handler.EventHandler) (*KafkaConsumer, error) {
22    config := sarama.NewConfig()
23    config.Consumer.Group.Rebalance.GroupStrategies = []sarama.BalanceStrategy{
24        sarama.NewBalanceStrategyRoundRobin(),
25    }
26    config.Consumer.Offsets.Initial = sarama.OffsetNewest
27    config.Consumer.Offsets.AutoCommit.Enable = false // manual commit
28
29    client, err := sarama.NewConsumerGroup(brokers, groupID, config)
30    if err != nil {
31        return nil, fmt.Errorf("kafkaConsumer: create group: %w", err)
32    }
33
34    topics := make([]string, 0, len(handlers))
35    for topic := range handlers { topics = append(topics, topic) }
36
37    return &KafkaConsumer{
38        client:   client,
39        topics:   topics,
40        handlers: handlers,
41    }, nil
42}
43
44func (c *KafkaConsumer) Run(ctx context.Context) error {
45    cgHandler := &consumerGroupHandler{handlers: c.handlers}
46    for {
47        if err := c.client.Consume(ctx, c.topics, cgHandler); err != nil {
48            log.Printf("kafka consumer error: %v", err)
49        }
50        if ctx.Err() != nil {
51            return ctx.Err()
52        }
53    }
54}
55
56func (c *KafkaConsumer) Close() error {
57    return c.client.Close()
58}
59
60// consumerGroupHandler implements sarama.ConsumerGroupHandler
61type consumerGroupHandler struct {
62    handlers map[string]handler.EventHandler
63}
64
65func (h *consumerGroupHandler) Setup(sarama.ConsumerGroupSession) error   { return nil }
66func (h *consumerGroupHandler) Cleanup(sarama.ConsumerGroupSession) error { return nil }
67
68func (h *consumerGroupHandler) ConsumeClaim(
69    session sarama.ConsumerGroupSession,
70    claim sarama.ConsumerGroupClaim,
71) error {
72    for msg := range claim.Messages() {
73        topic := msg.Topic
74        eventHandler, ok := h.handlers[topic]
75        if !ok {
76            session.MarkMessage(msg, "")
77            continue
78        }
79
80        ctx := context.Background()
81        if err := eventHandler.Handle(ctx, msg.Key, msg.Value); err != nil {
82            log.Printf("event handler error [%s]: %v", topic, err)
83            // Tidak commit — retry otomatis oleh Kafka
84            // Untuk permanent failure: kirim ke Dead Letter Queue
85            continue
86        }
87
88        // Manual commit: hanya setelah berhasil diproses
89        session.MarkMessage(msg, "")
90        session.Commit()
91    }
92    return nil
93}

Kunci reliability di sini adalah AutoCommit.Enable = false plus session.Commit() yang hanya dipanggil setelah handler sukses — kalau proses crash sebelum commit, Kafka akan redeliver pesan yang sama.


10.07 Event Handlers per Topic

Setiap topic punya handler sendiri yang mengikuti pola seragam: cek idempotency, ambil user, render template, kirim email, update status. Kode berikut adalah handler untuk event order.confirmed.

go
  1// internal/notification/handler/order_confirmed_handler.go
  2
  3package handler
  4
  5import (
  6    "context"
  7    "encoding/json"
  8    "fmt"
  9    "time"
 10
 11    "github.com/google/uuid"
 12    domainNotif  "github.com/santekno/santekno-shop/internal/domain/notification"
 13    "github.com/santekno/santekno-shop/internal/notification/email"
 14    notifTemplate "github.com/santekno/santekno-shop/internal/notification/template"
 15    domainUser    "github.com/santekno/santekno-shop/internal/domain/user"
 16)
 17
 18type EventHandler interface {
 19    Handle(ctx context.Context, key, value []byte) error
 20}
 21
 22// OrderConfirmedPayload: sesuai dengan outbox event dari Artikel 08
 23type OrderConfirmedPayload struct {
 24    OrderID  string `json:"order_id"`
 25    UserID   string `json:"user_id"`
 26    Status   string `json:"status"`
 27}
 28
 29type OrderConfirmedHandler struct {
 30    userRepo     domainUser.Repository
 31    notifRepo    domainNotif.Repository
 32    emailSender  email.Sender
 33    renderer     *notifTemplate.Renderer
 34}
 35
 36func NewOrderConfirmedHandler(
 37    userRepo domainUser.Repository,
 38    notifRepo domainNotif.Repository,
 39    sender email.Sender,
 40    renderer *notifTemplate.Renderer,
 41) *OrderConfirmedHandler {
 42    return &OrderConfirmedHandler{
 43        userRepo: userRepo, notifRepo: notifRepo,
 44        emailSender: sender, renderer: renderer,
 45    }
 46}
 47
 48func (h *OrderConfirmedHandler) Handle(ctx context.Context, key, value []byte) error {
 49    var payload OrderConfirmedPayload
 50    if err := json.Unmarshal(value, &payload); err != nil {
 51        return fmt.Errorf("orderConfirmedHandler: unmarshal: %w", err)
 52    }
 53
 54    // Idempotency: event_id = topic + order_id
 55    eventID := "order.confirmed:" + payload.OrderID
 56    existing, err := h.notifRepo.GetByEventID(ctx, eventID)
 57    if err != nil {
 58        return fmt.Errorf("orderConfirmedHandler: check idempotency: %w", err)
 59    }
 60    if existing != nil {
 61        return nil // already sent
 62    }
 63
 64    // Get user info
 65    userID, _ := uuid.Parse(payload.UserID)
 66    u, err := h.userRepo.GetByID(ctx, userID)
 67    if err != nil || u == nil {
 68        return fmt.Errorf("orderConfirmedHandler: get user: %w", err)
 69    }
 70
 71    // Render email
 72    rendered, err := h.renderer.Render(notifTemplate.TmplOrderConfirmed,
 73        notifTemplate.NotificationData{
 74            CustomerName: u.Name,
 75            OrderID:      payload.OrderID,
 76        })
 77    if err != nil {
 78        return fmt.Errorf("orderConfirmedHandler: render: %w", err)
 79    }
 80
 81    // Create notification record
 82    notif := &domainNotif.Notification{
 83        ID:             uuid.New(),
 84        UserID:         userID,
 85        Channel:        domainNotif.ChannelEmail,
 86        TemplateKey:    string(notifTemplate.TmplOrderConfirmed),
 87        Subject:        rendered.Subject,
 88        Body:           rendered.Body,
 89        RecipientEmail: u.Email,
 90        Status:         domainNotif.StatusPending,
 91        EventID:        eventID,
 92        EventType:      "order.confirmed",
 93        CreatedAt:      time.Now().UTC(),
 94    }
 95
 96    if err := h.notifRepo.Create(ctx, notif); err != nil {
 97        return fmt.Errorf("orderConfirmedHandler: save notification: %w", err)
 98    }
 99
100    // Send email
101    sendErr := h.emailSender.Send(ctx, email.Message{
102        To:      u.Email,
103        Subject: rendered.Subject,
104        Body:    rendered.Body,
105    })
106
107    now := time.Now().UTC()
108    if sendErr != nil {
109        errMsg := sendErr.Error()
110        h.notifRepo.UpdateStatus(ctx, notif.ID.String(), domainNotif.StatusFailed, &errMsg)
111        return fmt.Errorf("orderConfirmedHandler: send email: %w", sendErr)
112    }
113
114    h.notifRepo.UpdateStatus(ctx, notif.ID.String(), domainNotif.StatusSent, nil)
115    return nil
116}

Perhatikan urutannya: notifikasi disimpan sebagai PENDING dulu, baru email dikirim, lalu status di-update — sehingga kalau pengiriman gagal, kita punya record FAILED yang bisa di-retry, bukan event yang hilang tanpa jejak.


10.08 OrderPlaced Handler (Payment URL)

Handler order.placed sedikit lebih kompleks karena butuh detail order dan payment URL. Kode berikut menunjukkan pola yang sama plus helper sendAndLog untuk mengurangi duplikasi.

go
 1// internal/notification/handler/order_placed_handler.go
 2
 3type OrderPlacedPayload struct {
 4    OrderID        string  `json:"order_id"`
 5    UserID         string  `json:"user_id"`
 6    TotalAmountIDR int64   `json:"total_amount_idr"`
 7    ItemCount      int     `json:"item_count"`
 8}
 9
10type OrderPlacedHandler struct {
11    userRepo    domainUser.Repository
12    orderRepo   domainOrder.Repository
13    notifRepo   domainNotif.Repository
14    emailSender email.Sender
15    renderer    *notifTemplate.Renderer
16}
17
18func (h *OrderPlacedHandler) Handle(ctx context.Context, key, value []byte) error {
19    var payload OrderPlacedPayload
20    if err := json.Unmarshal(value, &payload); err != nil {
21        return fmt.Errorf("orderPlacedHandler: %w", err)
22    }
23
24    eventID := "order.placed:" + payload.OrderID
25    if existing, _ := h.notifRepo.GetByEventID(ctx, eventID); existing != nil {
26        return nil
27    }
28
29    userID, _ := uuid.Parse(payload.UserID)
30    u, err := h.userRepo.GetByID(ctx, userID)
31    if err != nil || u == nil {
32        return fmt.Errorf("orderPlacedHandler: get user: %w", err)
33    }
34
35    // Bisa fetch order detail untuk items jika perlu
36    orderID, _ := uuid.Parse(payload.OrderID)
37    o, err := h.orderRepo.GetByID(ctx, orderID)
38    if err != nil || o == nil {
39        return fmt.Errorf("orderPlacedHandler: get order: %w", err)
40    }
41
42    items := make([]notifTemplate.NotificationItem, len(o.Items))
43    for i, item := range o.Items {
44        items[i] = notifTemplate.NotificationItem{
45            ProductName: item.ProductName,
46            Quantity:    item.Quantity,
47            SubtotalIDR: item.SubtotalIDR,
48        }
49    }
50
51    deadline := o.CreatedAt.Add(24 * time.Hour).Format("02 Jan 2006 15:04 WIB")
52    paymentURL := ""
53    if o.PaymentURL != nil { paymentURL = *o.PaymentURL }
54
55    rendered, _ := h.renderer.Render(notifTemplate.TmplOrderPlaced,
56        notifTemplate.NotificationData{
57            CustomerName:   u.Name,
58            OrderID:        payload.OrderID,
59            TotalAmountIDR: payload.TotalAmountIDR,
60            Items:          items,
61            CancelDeadline: deadline,
62            PaymentURL:     paymentURL,
63        })
64
65    return h.sendAndLog(ctx, u, eventID, "order.placed", rendered, notifTemplate.TmplOrderPlaced)
66}
67
68// sendAndLog: helper untuk create notif record + send + update status
69func (h *OrderPlacedHandler) sendAndLog(
70    ctx context.Context, u *domainUser.User,
71    eventID, eventType string,
72    rendered *notifTemplate.RenderedEmail,
73    tmplKey notifTemplate.TemplateKey,
74) error {
75    notif := &domainNotif.Notification{
76        ID:             uuid.New(),
77        UserID:         u.ID,
78        Channel:        domainNotif.ChannelEmail,
79        TemplateKey:    string(tmplKey),
80        Subject:        rendered.Subject,
81        Body:           rendered.Body,
82        RecipientEmail: u.Email,
83        Status:         domainNotif.StatusPending,
84        EventID:        eventID,
85        EventType:      eventType,
86        CreatedAt:      time.Now().UTC(),
87    }
88    h.notifRepo.Create(ctx, notif)
89
90    if err := h.emailSender.Send(ctx, email.Message{To: u.Email, Subject: rendered.Subject, Body: rendered.Body}); err != nil {
91        errMsg := err.Error()
92        h.notifRepo.UpdateStatus(ctx, notif.ID.String(), domainNotif.StatusFailed, &errMsg)
93        return err
94    }
95
96    h.notifRepo.UpdateStatus(ctx, notif.ID.String(), domainNotif.StatusSent, nil)
97    return nil
98}

Helper sendAndLog mengangkat pola “create record → send → update status” ke satu tempat, sehingga handler-handler lain cukup memanggilnya dan tidak mengulang boilerplate yang sama.


10.09 Dead Letter Queue Pattern

Pesan yang gagal terus-menerus tidak boleh memblokir consumer selamanya. Pola Dead Letter Queue berikut memindahkan pesan yang melewati batas retry ke topic khusus agar bisa diinspeksi tim ops.

go
 1// Untuk messages yang gagal setelah max retry
 2
 3const maxRetries = 3
 4
 5type RetryableHandler struct {
 6    inner      EventHandler
 7    dlqTopic   string
 8    maxRetries int
 9    producer   sarama.SyncProducer
10}
11
12func (h *RetryableHandler) Handle(ctx context.Context, key, value []byte) error {
13    retries := extractRetryCount(key) // embedded in message key
14
15    if err := h.inner.Handle(ctx, key, value); err != nil {
16        if retries >= h.maxRetries {
17            // Send to Dead Letter Queue
18            h.producer.SendMessage(&sarama.ProducerMessage{
19                Topic: h.dlqTopic, // e.g., "santekno.notifications.dlq"
20                Key:   sarama.StringEncoder(string(key)),
21                Value: sarama.ByteEncoder(value),
22                Headers: []sarama.RecordHeader{
23                    {Key: []byte("original-topic"), Value: key},
24                    {Key: []byte("error"), Value: []byte(err.Error())},
25                    {Key: []byte("retries"), Value: []byte(fmt.Sprintf("%d", retries))},
26                },
27            })
28            return nil // acknowledge: DLQ diterima
29        }
30        return err // tidak acknowledge: Kafka akan retry
31    }
32    return nil
33}
34
35// DLQ monitoring: alert jika ada pesan di DLQ
36// Bisa di-replay manual oleh ops team setelah fix issue

Dengan DLQ, satu pesan beracun tidak akan menghentikan seluruh pipeline; pesan itu “diparkir” dengan metadata error di header, sementara consumer terus memproses pesan berikutnya.


10.10 Notification Service Entry Point

Semua komponen dirakit di entry point yang bisa berjalan sebagai binary terpisah atau goroutine dalam server utama. Kode berikut menyusun infrastruktur, repository, handler, dan consumer sekaligus menangani graceful shutdown.

go
 1// cmd/notification/main.go
 2// Binary terpisah dari HTTP server (optional — bisa juga goroutine dalam server)
 3
 4package main
 5
 6import (
 7    "context"
 8    "fmt"
 9    "os"
10    "os/signal"
11    "syscall"
12
13    "github.com/santekno/santekno-shop/config"
14    "github.com/santekno/santekno-shop/internal/notification/consumer"
15    "github.com/santekno/santekno-shop/internal/notification/email"
16    notifTemplate "github.com/santekno/santekno-shop/internal/notification/template"
17    "github.com/santekno/santekno-shop/internal/notification/handler"
18    postgresRepo "github.com/santekno/santekno-shop/internal/repository/postgres"
19    // ...
20)
21
22func main() {
23    cfg, _ := config.Load()
24
25    // Infrastructure
26    db, _    := pgxpool.New(context.Background(), cfg.Database.URL)
27    sender   := email.NewSMTPSender(cfg.SMTP.Host, cfg.SMTP.Port, cfg.SMTP.From, cfg.SMTP.Username, cfg.SMTP.Password)
28    renderer := notifTemplate.NewRenderer()
29
30    // Repositories
31    userRepo  := postgresRepo.NewUserRepository(db)
32    orderRepo := postgresRepo.NewOrderRepository(db)
33    notifRepo := postgresRepo.NewNotificationRepository(db)
34
35    // Handlers per topic
36    handlers := map[string]handler.EventHandler{
37        "santekno.orders.placed":    handler.NewOrderPlacedHandler(userRepo, orderRepo, notifRepo, sender, renderer),
38        "santekno.orders.confirmed": handler.NewOrderConfirmedHandler(userRepo, notifRepo, sender, renderer),
39        "santekno.orders.cancelled": handler.NewOrderCancelledHandler(userRepo, notifRepo, sender, renderer),
40        "santekno.payments.failed":  handler.NewPaymentFailedHandler(userRepo, notifRepo, sender, renderer),
41    }
42
43    // Kafka consumer
44    kafkaConsumer, _ := consumer.NewKafkaConsumer(
45        cfg.Kafka.Brokers,
46        "santekno-notification-service",
47        handlers,
48    )
49    defer kafkaConsumer.Close()
50
51    ctx, cancel := context.WithCancel(context.Background())
52    defer cancel()
53
54    go func() {
55        fmt.Println("Notification Service started")
56        kafkaConsumer.Run(ctx)
57    }()
58
59    // Graceful shutdown
60    quit := make(chan os.Signal, 1)
61    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
62    <-quit
63    fmt.Println("Notification Service stopping...")
64    cancel()
65}

Struktur map topic → handler membuat penambahan consumer baru cukup dengan satu baris registrasi — arsitektur yang mudah discale saat jumlah jenis notifikasi bertambah.


10.11 Notification Tests

Handler harus diuji untuk happy path, idempotency, dan kegagalan email. Test suite berikut memakai gomock untuk mengisolasi handler dari database dan SMTP.

go
 1// internal/notification/handler/order_confirmed_handler_test.go
 2
 3type OrderConfirmedHandlerSuite struct {
 4    suite.Suite
 5    ctrl        *gomock.Controller
 6    userRepo    *mock.MockUserRepository
 7    notifRepo   *mock.MockNotificationRepository
 8    emailSender *mock.MockEmailSender
 9    handler     *handler.OrderConfirmedHandler
10}
11
12func (s *OrderConfirmedHandlerSuite) SetupTest() {
13    s.ctrl       = gomock.NewController(s.T())
14    s.userRepo   = mock.NewMockUserRepository(s.ctrl)
15    s.notifRepo  = mock.NewMockNotificationRepository(s.ctrl)
16    s.emailSender = mock.NewMockEmailSender(s.ctrl)
17    renderer    := notifTemplate.NewRenderer()
18
19    s.handler = handler.NewOrderConfirmedHandler(
20        s.userRepo, s.notifRepo, s.emailSender, renderer)
21}
22
23// Happy path: event valid → email terkirim
24func (s *OrderConfirmedHandlerSuite) TestHandle_ValidEvent_SendsEmail() {
25    userID  := uuid.New()
26    orderID := uuid.New()
27    payload := handler.OrderConfirmedPayload{
28        OrderID: orderID.String(), UserID: userID.String(), Status: "CONFIRMED",
29    }
30    value, _ := json.Marshal(payload)
31
32    u := &domainUser.User{ID: userID, Email: "user@example.com", Name: "John"}
33
34    s.notifRepo.EXPECT().GetByEventID(gomock.Any(), "order.confirmed:"+orderID.String()).Return(nil, nil)
35    s.userRepo.EXPECT().GetByID(gomock.Any(), userID).Return(u, nil)
36    s.notifRepo.EXPECT().Create(gomock.Any(), gomock.Any()).Return(nil)
37    s.emailSender.EXPECT().Send(gomock.Any(), gomock.Any()).Return(nil)
38    s.notifRepo.EXPECT().UpdateStatus(gomock.Any(), gomock.Any(), domainNotif.StatusSent, nil).Return(nil)
39
40    err := s.handler.Handle(context.Background(), []byte(orderID.String()), value)
41    s.NoError(err)
42}
43
44// Idempotent: event yang sama tidak kirim ulang
45func (s *OrderConfirmedHandlerSuite) TestHandle_DuplicateEvent_Idempotent() {
46    orderID := uuid.New()
47    payload := handler.OrderConfirmedPayload{OrderID: orderID.String(), UserID: uuid.New().String()}
48    value, _ := json.Marshal(payload)
49
50    existing := &domainNotif.Notification{Status: domainNotif.StatusSent}
51    s.notifRepo.EXPECT().GetByEventID(gomock.Any(), "order.confirmed:"+orderID.String()).Return(existing, nil)
52    // emailSender.Send TIDAK boleh dipanggil
53
54    err := s.handler.Handle(context.Background(), []byte(orderID.String()), value)
55    s.NoError(err)
56}
57
58// Email gagal: status FAILED, error di-return (Kafka tidak commit)
59func (s *OrderConfirmedHandlerSuite) TestHandle_EmailFails_UpdatesStatusFailed() {
60    userID  := uuid.New()
61    orderID := uuid.New()
62    payload := handler.OrderConfirmedPayload{OrderID: orderID.String(), UserID: userID.String()}
63    value, _ := json.Marshal(payload)
64    u := &domainUser.User{ID: userID, Email: "user@example.com", Name: "Test"}
65
66    s.notifRepo.EXPECT().GetByEventID(gomock.Any(), gomock.Any()).Return(nil, nil)
67    s.userRepo.EXPECT().GetByID(gomock.Any(), userID).Return(u, nil)
68    s.notifRepo.EXPECT().Create(gomock.Any(), gomock.Any()).Return(nil)
69    s.emailSender.EXPECT().Send(gomock.Any(), gomock.Any()).Return(fmt.Errorf("SMTP connection refused"))
70    s.notifRepo.EXPECT().UpdateStatus(gomock.Any(), gomock.Any(), domainNotif.StatusFailed, gomock.Any()).Return(nil)
71
72    err := s.handler.Handle(context.Background(), []byte(orderID.String()), value)
73    s.Error(err) // error → Kafka tidak commit → retry
74}
75
76func TestOrderConfirmedHandlerSuite(t *testing.T) {
77    suite.Run(t, new(OrderConfirmedHandlerSuite))
78}

Test TestHandle_DuplicateEvent_Idempotent adalah yang paling penting: ia membuktikan bahwa emailSender.Send tidak pernah dipanggil untuk event duplikat — jaminan bahwa customer tidak akan menerima email ganda.


10.12 Specify Audit Final: Semua 29 ACs

Setelah semua handler jadi, kita jalankan specify audit untuk mengukur coverage AC secara otomatis. Perintah berikut mem-parsing output JSON menjadi ringkasan skor.

bash
 1specify audit --output json | jq '{
 2  score: .score,
 3  total_covered: .covered,
 4  total_acs: .total
 5}'
 6
 7# Expected setelah Artikel 10:
 8# {
 9#   "score": 95,
10#   "total_covered": 25,
11#   "total_acs": 29
12# }
13#
14# Note: 29 ACs dari spec → 25 yang di-track oleh specify audit
15# (4 ACs tidak ter-auto-detect karena patternya di event consumer, bukan HTTP)
16# Manual verification untuk notification ACs

Skor 95 menunjukkan sebagian besar AC ter-cover otomatis; 4 AC notification yang berbasis event consumer perlu verifikasi manual karena pattern-nya bukan HTTP endpoint yang bisa dideteksi audit tool.


10.13 Notification Status Dashboard

Untuk observability, kita expose endpoint statistik notifikasi. Handler berikut mengagregasi jumlah notifikasi SENT, FAILED, dan PENDING dalam 24 jam terakhir.

go
 1// delivery/http/handler/admin_handler.go (preview — Artikel 14)
 2
 3// GET /admin/notifications/stats
 4func (h *AdminHandler) NotificationStats(c echo.Context) error {
 5    ctx := c.Request().Context()
 6
 7    var stats struct {
 8        Sent   int `json:"sent"`
 9        Failed int `json:"failed"`
10        Pending int `json:"pending"`
11    }
12
13    h.db.QueryRow(ctx,
14        `SELECT
15            COUNT(*) FILTER (WHERE status = 'SENT') as sent,
16            COUNT(*) FILTER (WHERE status = 'FAILED') as failed,
17            COUNT(*) FILTER (WHERE status = 'PENDING') as pending
18         FROM notifications
19         WHERE created_at > NOW() - INTERVAL '24 hours'`,
20    ).Scan(&stats.Sent, &stats.Failed, &stats.Pending)
21
22    return c.JSON(http.StatusOK, stats)
23}

Endpoint sederhana ini memberi tim ops visibilitas cepat: lonjakan jumlah FAILED adalah sinyal awal masalah SMTP atau provider email sebelum customer mengeluh.


10.14 Consumer Group Strategy

Kafka consumer group memungkinkan horizontal scaling dengan membagi partisi ke beberapa instance. Diagram berikut menunjukkan bagaimana 3 partisi dibagi ke 3 consumer instance.

text
 1Consumer Group: santekno-notification-service
 2
 3Kafka Partition Assignment:
 4  santekno.orders.placed     [p0, p1, p2]
 5  santekno.orders.confirmed  [p0, p1, p2]
 6  ...
 7
 8Dengan 3 partisi dan 3 consumer instance:
 9  Instance A: partition 0 dari semua topics
10  Instance B: partition 1 dari semua topics
11  Instance C: partition 2 dari semua topics
12
13Benefits:
14  - Horizontal scaling: tambah instance tanpa ubah code
15  - Ordering per partition: event per order_id di-route ke satu partition via key
16  - Fault tolerance: jika instance A down, B/C mengambil alih
17
18Key design: gunakan order_id sebagai Kafka message key
19  → Semua event untuk order yang sama masuk ke partisi yang sama
20  → Ordering guarantee per order

Kunci desain ini adalah pemilihan order_id sebagai message key: semua event untuk satu order selalu jatuh ke partisi yang sama, sehingga urutan placed → confirmed → shipped dijamin konsisten.


10.15 Graceful Shutdown Consumer

Saat menerima SIGTERM, consumer harus berhenti dengan rapi tanpa kehilangan pesan yang sedang diproses. Kode berikut merangkum langkah-langkah shutdown yang aman.

go
 1// Ketika SIGTERM diterima:
 2
 3func (c *KafkaConsumer) GracefulShutdown(ctx context.Context) {
 4    // 1. Stop menerima message baru
 5    c.cancel()
 6
 7    // 2. Tunggu in-flight messages selesai
 8    // sarama consumer group handle ini secara otomatis via context
 9    // dengan timeout 30 detik
10
11    // 3. Commit offset terakhir
12    // done via session.Commit() yang sudah dipanggil di setiap message
13
14    // 4. Close consumer group
15    c.client.Close()
16    fmt.Println("Notification consumer stopped gracefully")
17}

Karena offset di-commit setelah tiap pesan sukses, shutdown yang rapi menjamin tidak ada pesan yang hilang maupun diproses dua kali di luar jaminan idempotency yang sudah ada.


10.16 Retry Logic dengan Backoff

Kegagalan SMTP sering bersifat sementara, jadi retry dengan exponential backoff bisa menyelamatkan banyak notifikasi. Kode berikut membungkus Sender dengan logika retry berjenjang.

go
 1// Retry dengan exponential backoff untuk email send
 2
 3type RetryEmailSender struct {
 4    inner      email.Sender
 5    maxRetries int
 6}
 7
 8func (r *RetryEmailSender) Send(ctx context.Context, msg email.Message) error {
 9    var lastErr error
10    for attempt := 0; attempt <= r.maxRetries; attempt++ {
11        if err := r.inner.Send(ctx, msg); err != nil {
12            lastErr = err
13            if attempt < r.maxRetries {
14                // Exponential backoff: 1s, 2s, 4s
15                backoff := time.Duration(1<<attempt) * time.Second
16                select {
17                case <-time.After(backoff):
18                case <-ctx.Done():
19                    return ctx.Err()
20                }
21                continue
22            }
23        } else {
24            return nil // sukses
25        }
26    }
27    return fmt.Errorf("send failed after %d retries: %w", r.maxRetries, lastErr)
28}

Karena RetryEmailSender juga mengimplementasi interface Sender, ia bisa dipasang transparan di depan SMTPSender tanpa mengubah satu baris pun di handler — kekuatan komposisi lewat interface.


10.17 Monitoring: Failed Notifications

Notifikasi yang gagal setelah semua retry perlu dijalankan ulang secara terjadwal. Job berikut memindai notifikasi berstatus FAILED dan mencoba mengirim ulang setiap 15 menit.

go
 1// Scheduled job untuk retry failed notifications (Artikel 18)
 2// Berjalan setiap 15 menit
 3
 4func (s *RetryJob) Run(ctx context.Context) {
 5    failedNotifs, _ := s.notifRepo.ListFailed(ctx, 100)
 6
 7    for _, notif := range failedNotifs {
 8        // Re-send
 9        if err := s.sender.Send(ctx, email.Message{
10            To:      notif.RecipientEmail,
11            Subject: notif.Subject,
12            Body:    notif.Body,
13        }); err != nil {
14            // Still failing — leave for ops team
15            continue
16        }
17
18        now := time.Now().UTC()
19        s.notifRepo.UpdateStatus(ctx, notif.ID.String(), domainNotif.StatusSent, nil)
20    }
21}
22
23// Alert: jika failed count > threshold dalam 1 jam
24// → PagerDuty / Slack alert

Job ini melengkapi safety net: notifikasi yang lolos dari retry inline tetap punya kesempatan kedua secara terjadwal, dan yang tetap gagal ditandai untuk investigasi manual.


10.18 Event Consumer Summary

Sebagai rangkuman, berikut peta lengkap topic ke handler dan langkah standar yang dijalankan setiap handler. Daftar ini menjadi referensi cepat saat menambah jenis event baru.

text
 1Topics dan handler yang di-register:
 2
 3santekno.orders.placed     → OrderPlacedHandler
 4  → Send "Pesanan dibuat, segera bayar" email
 5
 6santekno.orders.confirmed  → OrderConfirmedHandler
 7  → Send "Pembayaran dikonfirmasi, pesanan diproses" email
 8
 9santekno.orders.cancelled  → OrderCancelledHandler
10  → Send "Pesanan dibatalkan" email
11
12santekno.orders.shipped    → OrderShippedHandler (Topik 5 Part 3)
13  → Send "Pesanan dikirim, no resi: xxx" email
14
15santekno.payments.failed   → PaymentFailedHandler
16  → Send "Pembayaran gagal, pesanan dibatalkan" email
17
18Semua handler:
19  1. Idempotency check (event_id unique)
20  2. Get user info dari DB
21  3. Render template
22  4. Create notification record (PENDING)
23  5. Send email
24  6. Update status (SENT / FAILED)
25  7. Return nil (commit) atau error (no commit = retry)

Tujuh langkah seragam inilah yang membuat service mudah dirawat: setiap handler baru cukup mengikuti pola yang sama, dan reviewer bisa langsung memverifikasi kelengkapannya.


10.19 Part 2 Completion: Score Summary

Notification Service menandai selesainya Part 2 dari seri e-commerce. Ringkasan berikut menunjukkan progres skor specify dari skeleton sampai notification.

text
 1TOPIK 5 PART 2 — SELESAI
 2
 3Artikel 05 (Skeleton):     go build PASS, specify 5/100
 4Artikel 06 (User Service): bcrypt + JWT + Redis, specify 35/100
 5Artikel 07 (Product):      full-text search, optimistic lock, specify 50/100
 6Artikel 08 (Order):        atomic PlaceOrder + CancelOrder, specify 80/100 ✅
 7Artikel 09 (Payment):      HMAC webhook + idempotency, specify 90/100
 8Artikel 10 (Notification): Kafka consumer + email + DLQ, specify 95/100
 9
10Total ACs covered: 25/29 (4 notification ACs = event-driven, tidak di-spec awal)
11Pipeline status: FULLY GREEN ✅
12
13Selanjutnya:
14Part 3 (Artikel 11-15): Infrastructure — Database indexing, Kafka integration,
15                        Redis caching, API Gateway, Docker + Kubernetes
16Part 4 (Artikel 16-20): Production Baseline — Testing, CI/CD, Observability,
17                        Performance, Bridge to Topic 6

Progres skor yang naik konsisten di tiap artikel membuktikan nilai SDD: setiap fitur baru menambah coverage yang terukur, bukan sekadar “rasanya sudah jalan”.


10.20 Ringkasan

Notification Service melengkapi core services Santekno Shop dengan pipeline notifikasi yang andal:

Kafka Consumer Group dengan manual commit — hanya commit setelah berhasil diproses, retry otomatis jika gagal.

Idempotency via event_id di tabel notifications — duplicate event tidak kirim email ulang.

Email Template dengan text/template — subject dan body di-render dari data dinamis.

Dead Letter Queue untuk permanent failures — tidak block main consumer, ops bisa replay.

Notification Log untuk semua notifikasi — audit trail, monitoring, dan retry support.

Santekno Shop sekarang punya full event-driven notification pipeline — dari order dibuat sampai customer menerima email konfirmasi, semua berjalan async dan reliable. Di artikel berikutnya kita rapikan fondasi database: migration workflow yang solid, index strategy yang tepat untuk query e-commerce, dan pgvector yang siap untuk fitur AI.

Artikel Terkait

💬 Komentar