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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 issueDengan 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.
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.
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.
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 ACsSkor 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.
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.
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 orderKunci 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.
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.
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.
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 alertJob 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.
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.
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 6Progres 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.