DEV Community: lukman lukman

Caching: Why Faster Reads Create Consistency Problems

lukman lukman — Tue, 22 Sep 2026 07:48:22 +0000

A dashboard request can look harmless.

The problem appears when hundreds of users ask for the same expensive data at the same time.

In Software Engineering Lab 04, the scenario is a workshop dashboard. Without caching, every request runs six database queries with joins and aggregations.

500 concurrent users
        ↓
Dashboard request
        ↓
6 queries + join/aggregation per request
        ↓
3000 total DB queries

The first instinct is easy:

put Redis in front of the database

That reduces repeated work.

But it also creates a new set of problems.

How stale may the cached value be?
When should it be invalidated?
What happens when the key expires under load?
What happens if Redis is unavailable?
Can the cache return data from the wrong tenant?

That is the part I wanted to explore in Lab 04.

The main mental model is not:

slow query → add cache

It is closer to:

reduce repeated work
        ↓
accept a consistency boundary
        ↓
design expiration, invalidation, failure, and concurrency behavior

PostgreSQL is still the source of truth

The lab uses two storage layers:

Layer	Technology	Role
Primary	PostgreSQL	Durable, persistent, authoritative storage that can rebuild the cache
Cache	Redis	Derived data, TTL-bound, rebuilt on demand

The important decision is ownership of correctness.

In this lab, PostgreSQL remains authoritative for business data. Redis stores derived data that can disappear, expire, or be rebuilt.

That means cache correctness has to work even when the cache is empty.

The cache is an optimization layer, not the only copy of the business state.

The read path: Cache Aside

Lab 04 uses Cache Aside for reads.

GET cache
   ↓
hit? ───── yes ───→ return cached value
   ↓ no
query PostgreSQL
   ↓
populate Redis
   ↓
return value

A cache miss is not an application failure.

It means the application has to rebuild the value from the authoritative source.

The application explicitly knows about both storage layers:

Redis
PostgreSQL

That control is useful when Redis is unavailable because the application can still attempt to read from PostgreSQL, as long as the database and fallback capacity can handle the traffic.

But Cache Aside also means the application now owns cache freshness.

That is where the interesting failures start.

TTL is really a staleness decision

The useful question is not simply:

Does this data change?

The lab asks:

How long can stale data be accepted?

Examples recorded in the lab:

Data	Max staleness	Reasonable?
Dashboard statistics	30s–2min	Yes, operational metrics
Stock display	1–5s	Yes, UI/UX only
Wallet balance	0s	No, audit risk

The difference matters.

A dashboard metric can tolerate a freshness window that would be unacceptable for a transactional balance.

So TTL is not just an expiry configuration. In this implementation, it represents an accepted freshness window and also acts as a recovery path when stale cache survives longer than expected.

Invalidating before commit can reintroduce stale data

Consider this write flow:

DELETE cache
↓
update database
↓
COMMIT

It looks reasonable. Remove the old cache first, then write the new database value.

The race appears when a reader enters between those operations.

Lab 04 describes this timeline:

T1 Writer: DELETE cache
T2 Reader: cache MISS → reads old DB value
T3 Reader: SET old value into cache
T4 Writer: DB COMMIT new value

Final state:

Database = new value
Cache    = old value

This is stale cache, not data loss. The authoritative business data in PostgreSQL is still correct.

A safer order is:

DB COMMIT
↓
DELETE cache

Now a reader that misses after the delete can rebuild from the committed database value.

But even this is not strong consistency.

Another interleaving still exists:

T1 Reader: cache MISS
T2 Reader: reads old DB value
T3 Writer: DB COMMIT new value
T4 Writer: DELETE cache
T5 Reader: SET old DB result into cache

Final state again:

Database = new value
Cache    = old value

So the conclusion is narrower:

COMMIT → DELETE

is safer than:

DELETE → COMMIT

but Cache Aside is still an eventually consistent optimization in this lab.

TTL remains useful as a safety net for the residual stale window.

Updating Redis after a database write is not atomic either

The lab also uses an application-managed update-on-write flow:

DB update
↓
DB COMMIT succeeds
↓
best-effort Redis SET
↓
return success

The database returns the authoritative value, then the application tries to update the cache.

The problem is the boundary between PostgreSQL and Redis.

These are separate systems, so this sequence is not atomic:

DB COMMIT
↓
Redis SET

A process can fail between them:

DB COMMIT succeeds
↓
process crashes
↓
Redis SET never happens
↓
old cache remains

Concurrent writers create another race:

Writer A commits value A
Writer B commits value B
Writer B SET cache = B
Writer A performs a late SET cache = A

Final state:

Database = B
Cache    = A

This was an important distinction for me:

Cache Aside
→ read strategy

Invalidate-on-write / update-on-write
→ write strategy

They solve different parts of the cache lifecycle.

Neither turns PostgreSQL and Redis into one atomic system.

One miss is normal. One thousand simultaneous misses are not

Now consider a popular key reaching expiration.

cache expires
      ↓
1000 concurrent requests arrive
      ↓
1000 cache misses
      ↓
1000 parallel DB queries
      ↓
database overload / crash

This is the cache stampede scenario used in Lab 04.

The cache successfully removes repeated database work while the entry exists, but expiration can suddenly send that work back to the database at the same time.

For duplicate rebuilds inside one process, the lab uses golang.org/x/sync/singleflight.

The flow includes a second cache check:

initial cache GET
      ↓
miss
      ↓
singleflight.Do
      ↓
check cache again
      ↓
query DB
      ↓
populate cache
      ↓
share result

The second check matters because another caller may already have populated the cache between the first miss and the point where this caller becomes the rebuild leader.

Singleflight stops at the process boundary

Singleflight coordinates callers inside one process.

A multi-instance deployment needs a different coordination boundary.

Lab 04 implements a distributed-lock primitive:

WithLock() = try-once lock primitive

The conceptual cache regeneration flow is:

cache GET
   ↓ miss
acquire distributed lock
   ↓
check cache again
   ↓
query DB
   ↓
populate cache
   ↓
safe release

The lock requirements in the lab are explicit:

unique token or owner;
TTL to avoid a permanent deadlock;
atomic compare-and-delete when releasing;
one holder must not remove another holder's lock.

But even this has a boundary.

If regeneration takes longer than the lock TTL:

Instance A acquires lock
↓
lock expires
↓
Instance B acquires a new lock
↓
Instance A is still rebuilding
↓
duplicate rebuild can run

The lock in Lab 04 reduces duplicate cache regeneration. It is not used as a correctness primitive for business transactions.

Expiration can also be spread out

The lab adds TTL jitter so many keys do not expire at nearly the same moment.

Example:

60s + random 0–15s

The implementation produces values in:

[base, base + maxJitter)

The TTL never goes below base, and the upper bound is exclusive.

The lab also discusses background refresh: refresh the cached value before expiry while clients continue receiving the existing cache value.

Both techniques target expiration behavior rather than changing the source of truth.

Cache keys are part of the data boundary

The canonical key format in the lab is:

{app}:{tenant}:{branch}:{resource}:{dimension}

Example:

cmms:tenant:42:branch:7:dashboard:2026-09-01

The rule is simple:

Every input that changes the result belongs in the cache key.

For the dashboard example, that includes tenant, branch, and business date.

This is also a security boundary in a multi-tenant system.

A sensitive cached value must include tenant scope. Missing isolation can expose data under the wrong tenant context.

Key design also affects reuse.

If 10,000 users read the same branch dashboard, this shape:

cache:tenant:42:user:{user_id}:dashboard

creates high-cardinality entries for data that is actually shared.

The lab contrasts it with:

cache:tenant:42:branch:{branch_id}:dashboard

One branch-scoped value can be reused by those readers.

The trade-off is not "specific keys are bad." The point is that key dimensions should match the result boundary.

Redis failure changes where the traffic goes

Cache Aside allows database fallback when Redis fails, but only while the authoritative dependency and fallback capacity remain available.

The traffic pattern becomes:

traffic previously absorbed by Redis
      ↓
directly reaches PostgreSQL
      ↓
load spike / cache-failure amplification

So graceful degradation does not mean the outage has no effect.

It means the main function may continue with degraded performance while PostgreSQL can still handle the fallback traffic.

The lab also separates:

cache_miss

from:

cache_error

because an expected miss and an unavailable cache backend are different operational events.

Hit ratio alone does not tell me whether the cache is worth it

Lab 04 evaluates cache value together with:

avoided query cost
cache latency
memory cost
invalidation complexity
failure amplification

The README gives this comparison:

30% hit ratio for a 100ms operation
may still be valuable

99% hit ratio for a 0.1ms operation
may not justify the complexity

The useful signal is not the percentage alone.

The cost of the work being avoided matters.

Cache comes after understanding the database work

The diagnostic order in the lab is:

measure endpoint
↓
check N+1 queries
↓
inspect execution plan
↓
add / optimize indexes
↓
reduce selected columns
↓
optimize joins / subqueries
↓
evaluate caching if the workload needs it

This prevents cache from becoming a way to hide an unexplained query problem.

For a very cheap query and some workloads, the extra cache hop and operational complexity may not provide meaningful end-to-end benefit.

The mental model I take from this lab

The naive model is:

query is expensive
→ add Redis
→ problem solved

Lab 04 forces a longer chain of questions:

What is the source of truth?
↓
How stale may this value be?
↓
What dimensions belong in the key?
↓
How is the value invalidated after writes?
↓
What happens during concurrent misses?
↓
What happens when Redis fails?
↓
Is the avoided work worth the added complexity?

That is the main lesson from the experiment.

Caching can reduce repeated work in a read-heavy workload.

But the moment a second storage layer is introduced, freshness, invalidation, concurrency, failure behavior, and isolation become part of the design.

Running the lab

From the repository root:

docker compose up -d redis

make lab-04-test
make lab-04-test-race
make lab-04-vet
make lab-04-demo
make lab-04-integration

The demo scenarios can also be run directly:

cd labs/04-caching

go run ./cmd/demo -scenario=without-cache
go run ./cmd/demo -scenario=cache-aside
go run ./cmd/demo -scenario=stampede-unprotected
go run ./cmd/demo -scenario=stampede-protected
go run ./cmd/demo -scenario=write-through

Source Code

Software Engineering Lab 04 — Caching

https://github.com/lukman-ss/software-engineering-lab/tree/main/labs/04-caching

Repository:

https://github.com/lukman-ss/software-engineering-lab

Author: Lukman (lukman-ss)

Database Transactions Are a Boundary, Not a Safety Blanket

lukman lukman — Mon, 21 Sep 2026 02:21:39 +0000

The uncomfortable part of a failed payment flow is not always the error.

Sometimes the function returns an error and the database still keeps half of the work.

That is the failure Lab 03 demonstrates. A payment is inserted. The order is marked as paid. Then the flow fails before the wallet transaction is inserted.

The result is not a clean failure:

payment persisted = 1
order.status = paid
wallet_transactions = 0

That is the useful lesson: database transactions are not just a way to call ROLLBACK. They are a boundary. Anything inside the boundary can commit or roll back together. Anything outside it cannot be magically undone by the database.

The Scenario

The lab starts with a local payment operation.

Initial state:

orders.id = 101
orders.status = pending

invoices.order_id = 101
invoices.status = unpaid

The service needs to do three local writes:

INSERT INTO payments (order_id, amount, status)
VALUES ($1, $2, 'completed')

UPDATE orders
SET status = 'paid'
WHERE id = $1

INSERT INTO wallet_transactions (order_id, amount, type)
VALUES ($1, $2, 'credit')

The injected failure happens after the first two statements, but before the wallet transaction insert.

The Problem

PaymentServiceUnsafe executes statements directly with db.ExecContext.

The flow is:

INSERT payment
  ↓
UPDATE order to paid
  ↓
injected failure
  ↓
wallet transaction is not inserted

There is no shared transaction boundary around the related writes. So when the failure happens, the database does not roll the earlier statements back.

The test result is the whole point:

payment persisted = 1
order.status = paid
wallet_transactions = 0

The application failed. The database did not return to the original state.

What Actually Went Wrong

The bug is not that SQL failed.

The bug is that the service treated a multi-step business operation as separate database statements.

From the business side, the payment row, the paid order status, and the wallet transaction belong to the same local invariant. From the unsafe database flow, they are just separate statements executed in order.

Without a transaction, the database has no reason to undo statement one and statement two just because the application never reaches statement three.

Using a Local Database Transaction

PaymentServiceSafe changes the boundary.

It starts a transaction:

tx, err := s.db.BeginTx(ctx, nil)

It keeps rollback as the default if commit does not happen:

committed := false
defer func() {
    if !committed {
        _ = tx.Rollback()
    }
}()

Then the related writes are executed through tx.ExecContext instead of db.ExecContext.

If all local writes succeed, the transaction commits:

if err := tx.Commit(); err != nil {
    return err
}

Successful Flow

The successful local flow is:

BEGIN TRANSACTION
  ↓
INSERT payment
  ↓
UPDATE order status
  ↓
INSERT wallet transaction
  ↓
COMMIT

At commit time, the local database state becomes complete together.

The lab uses the same idea again in the outbox example. InvoiceServiceOutbox updates the invoice and inserts an outbox event in one local transaction:

BEGIN
  ↓
UPDATE invoices SET status = 'paid'
  ↓
INSERT INTO outbox_events (... status = 'pending' ...)
  ↓
COMMIT

After commit, both the business state and the event intent exist locally.

Failure Flow

The failure path is where the difference becomes visible:

BEGIN TRANSACTION
  ↓
INSERT payment
  ↓
UPDATE order status
  ↓
injected failure
  ↓
ROLLBACK

The lab verifies the final state:

payments = 0
order.status = pending
wallet_transactions = 0

This is a clean local failure. The service still returns an error, but the database does not keep half of the payment flow.

Before vs After

Unsafe failure:

payments = 1
order.status = paid
wallet_transactions = 0

Safe local transaction failure:

payments = 0
order.status = pending
wallet_transactions = 0

This is what local atomicity buys you.

But the lab does not stop there, because this is only the easy boundary.

Rollback Does Not Undo WhatsApp

The next example uses DistributedOrderService.

The service opens a database transaction, inserts a payment, updates an invoice, sends a WhatsApp notification, then hits a simulated ERP integration error.

BEGIN TRANSACTION
  ↓
INSERT payment
  ↓
UPDATE invoice
  ↓
Send WhatsApp notification
  ↓
simulated ERP integration error
  ↓
ROLLBACK database transaction

The final state:

WhatsApp sent count = 1
payments = 0
paid invoices = 0

The database rollback worked. The WhatsApp message was still sent.

That is not a contradiction. WhatsApp is outside the database transaction boundary. The database can roll back its own rows. It cannot recall a message that has already been sent through another system.

The lab uses the same boundary idea for email, SMS, ERP APIs, payment gateway APIs, and message broker publishes.

HTTP Inside a Transaction

The lab also shows a blocking external call while a database transaction is open:

BEGIN TRANSACTION
  ↓
UPDATE invoice SET status = 'paid'
  ↓
HTTP call blocks
  ↓
transaction stays open

The test verifies that the transaction remains open during the blocking external call, then closes after commit.

The issue here is not only failure. The lifetime of the database transaction is now tied to an external resource.

The Dual-Write Gap

Another failure appears when database commit and event publish are separate operations.

UPDATE invoice
  ↓
COMMIT succeeds
  ↓
process crashes
  ↓
Publish event never happens

The test shows:

invoice.status = paid
published events = 0

The invoice was paid, but no event was published.

Reversing the order does not make the operation atomic. Publishing before commit can produce an event for a database state that never commits.

Transactional Outbox

The lab uses transactional outbox to keep the business state and event intent in one local transaction.

Local transaction
  ↓
Record business state + event intent
  ↓
COMMIT
  ↓
Dispatcher publishes pending events

InvoiceServiceOutbox inserts an outbox_events row with status pending. The dispatcher later reads pending events, publishes them to the broker, and marks them as published.

The important part is the local atomic step: invoice state and event intent are saved together.

Idempotent Consumer

The lab then shows the consumer side.

The commission worker stores a processed-event marker and the business state in the same transaction:

INSERT INTO processed_events (consumer_name, event_id, processed_at)
VALUES ($1, $2, $3)
ON CONFLICT (consumer_name, event_id) DO NOTHING

If the same consumer receives the same event again, the insert affects zero rows and the event is skipped.

The test result:

same consumer: processed once
same consumer duplicate: skipped
same event, different consumer: processed independently

This matters because the outbox side and the consumer side are connected. Recording an event intent is not enough. The receiver also has to handle repeated delivery safely.

What This Lab Demonstrates

A local transaction is the right tool for local state that must commit or roll back together.

It does not roll back external side effects.

It does not make database commit and broker publish atomic when those are executed as separate operations.

Outbox solves the local database/event-intent part by storing both in one transaction.

Idempotent consumer logic handles repeated processing on the consumer side by storing a dedup marker with the business update.

Key Takeaways

First define the transaction boundary.
Put related local writes inside the same transaction.
Do not treat external calls as rollbackable database work.
Do not keep a transaction open longer than necessary while waiting on external systems.
Use outbox when database state and event publishing must be coordinated.
Make consumers idempotent when the same event can be processed more than once.

Source Code

Repository:

https://github.com/lukman-ss/software-engineering-lab

Lab:

https://github.com/lukman-ss/software-engineering-lab/tree/main/labs/03-database-transaction

Author:

Lukman (lukman-ss)

Database Index: Why Queries Become Slow as Data Grows

lukman lukman — Thu, 17 Sep 2026 07:36:43 +0000

This query looks ordinary:

SELECT *
FROM service
WHERE branch_id = 2
  AND status = 'FINISHED'
  AND service_date BETWEEN '2026-01-01' AND '2026-01-31'
ORDER BY service_date DESC;

With a small dataset, a query like this may appear completely fine.

Lab 02 does not rely on assumptions. The query is tested using EXPLAIN (ANALYZE, BUFFERS) against the same dataset.

Dataset

Table: service

Total rows:

500,000

Status distribution:

Status	Fraction	Rows
FINISHED	70.00%	350,000
CANCELLED	20.00%	100,000
IN_PROGRESS	5.00%	25,000
WAITING	4.90%	24,500
PENDING_REFUND	0.10%	500

Branch 2 is the busiest branch, containing 25.00% of the data.

Baseline

The baseline only has constraint-backed indexes:

service_pkey
service_invoice_no_key

There is no secondary index on:

branch_id
status
service_date

Baseline query:

EXPLAIN (ANALYZE, BUFFERS)
SELECT *
FROM service
WHERE branch_id = 2
  AND status = 'FINISHED'
  AND service_date BETWEEN '2026-01-01' AND '2026-01-31'
ORDER BY service_date DESC;

What should be inspected:

plan node;
actual rows;
rows removed by filter;
explicit Sort;
shared read / shared hit;
planning time;
execution time.

Add the Candidate Index

CREATE INDEX idx_service_branch_status_date
ON service(branch_id, status, service_date DESC);

This index follows the query shape:

branch_id equality
→ status equality
→ service_date range/order

It is a candidate for this specific query, not a universal index.

Run the Same Query Again

EXPLAIN (ANALYZE, BUFFERS)
SELECT *
FROM service
WHERE branch_id = 2
  AND status = 'FINISHED'
  AND service_date BETWEEN '2026-01-01' AND '2026-01-31'
ORDER BY service_date DESC;

Compare:

Condition	What to inspect
Before index	Seq Scan, Sort, buffers, rows, time
After index	Index usage, Index Cond, Sort presence, buffers, rows, time

The lab does not store fixed execution-time numbers. Those values should come from the local run.

Cardinality Is Not Match Fraction

status has 5 distinct values. That is its cardinality.

Match fraction is the proportion of rows that match a predicate.

Predicate	Match fraction	Expected / likely plan
`status = 'FINISHED'`	70.0%	Seq Scan likely cheaper
`status = 'PENDING_REFUND'`	0.1%	index-based plan likely cheaper

The lesson is that low cardinality does not automatically make an index useless.

Column Order Matters

The lab compares:

CREATE INDEX idx_service_a_branch_status_date
    ON service(branch_id, status, service_date);

CREATE INDEX idx_service_b_date_branch_status
    ON service(service_date, branch_id, status);

CREATE INDEX idx_service_c_status_date_branch
    ON service(status, service_date, branch_id);

For the main query, the first index becomes a strong candidate because the leading equality predicates can narrow the scan range more effectively.

ORDER BY + LIMIT

Dashboard query:

SELECT *
FROM service
WHERE branch_id = 2
  AND status = 'FINISHED'
ORDER BY service_date DESC
LIMIT 20;

Index:

CREATE INDEX idx_service_branch_status_date_desc
    ON service(branch_id, status, service_date DESC);

What to inspect:

whether Sort is absent;
whether the plan uses Index Scan or Index Only Scan;
how many rows are examined before LIMIT is satisfied.

Index Is Not Free

The lab also tests:

inserting 1,000 rows without secondary indexes;
inserting 1,000 rows with 1 composite index;
inserting 1,000 rows with 4 secondary indexes;
updating indexed vs non-indexed columns;
storage cost using pg_relation_size, pg_indexes_size, and pg_total_relation_size.

An index can improve specific reads, but it also adds write and storage cost.

Key Takeaways

Do not optimize based on guesses.
Use EXPLAIN (ANALYZE, BUFFERS).
A composite index should follow the query shape.
Column order matters.
Cardinality is different from match fraction.
A Seq Scan can be the correct plan.
Indexes have write and storage costs.

Hands-on Lab

Software Engineering Lab #02 — Database Index

Author: Lukman

GitHub: lukman-ss

Repository:
https://github.com/lukman-ss/software-engineering-lab/tree/main/labs/02-database-index

Making POST Requests Safe to Retry with Idempotency Keys

lukman lukman — Tue, 15 Sep 2026 08:05:50 +0000

A practical guide to duplicate execution, request fingerprints, concurrency, and safe retries.

A request timeout does not mean the operation failed.

Sometimes the server has already completed the operation, but the response never reaches the client.

Consider:

POST /orders/order-123/pay

with:

{
  "amount": 500000
}

The timeline may look like this:

Client -> POST /pay
Server -> payment succeeds
Server -> response lost
Client -> timeout
Client -> retry
Server -> payment succeeds again

The problem is not the duplicate HTTP request itself. The problem is duplicate execution.

The target invariant

For a mutation API, the goal should be:

1 logical operation
=
1 effective side effect

even if the request is delivered multiple times.

Introduce an Idempotency Key

The client generates an identifier for one logical operation:

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

The key must remain the same across retries.

same logical operation -> same key
new logical operation  -> new key

The basic flow becomes:

Request
  ↓
Check Idempotency-Key
  ↓
New key?
  ↓
Process operation
  ↓
Store result
  ↓
Return response

On retry:

Same key
  ↓
Existing completed result
  ↓
Replay response
  ↓
Do not execute side effect again

Why check-then-act fails

This is not enough:

if key does not exist:
    process payment

Two concurrent requests may both observe the key as missing:

A -> key not found
B -> key not found

A -> process
B -> process

This is a race condition. The uniqueness decision needs to be atomic.

For a relational database, that normally means enforcing the invariant in storage:

CREATE UNIQUE INDEX idx_idempotency_key
ON payments(idempotency_key);

Application checks are useful. The unique constraint is the final guard.

Same key, different payload

An idempotency key must represent exactly one logical operation.

This should be accepted:

key: abc
amount: 500000

retry

key: abc
amount: 500000

This should not:

key: abc
amount: 500000

retry

key: abc
amount: 800000

The lab uses a request fingerprint based on SHA-256:

func hashRequest(data []byte) string {
    sum := sha256.Sum256(data)
    return hex.EncodeToString(sum[:])
}

Then:

same key + same fingerprint
-> replay safely

same key + different fingerprint
-> 409 Conflict

PROCESSING vs COMPLETED

The safe flow uses two important states:

PROCESSING
COMPLETED

When a second request arrives:

PROCESSING
-> return 409
-> do not execute payment again

When the operation is already finished:

COMPLETED
-> load stored response
-> replay it

Idempotency is not a transaction

A database transaction provides atomicity inside one execution.

Idempotency protects a logical operation across multiple execution attempts.

These can both succeed:

Request A
BEGIN
create payment
COMMIT

Request B
BEGIN
create payment
COMMIT

The database is consistent. The business result is not. The customer was charged twice.

External side effects have a different boundary

Consider:

Call payment provider
↓
Provider SUCCESS
↓
Local commit fails
↓
ROLLBACK

The local rollback does not undo the external charge.

local rollback
!=
external rollback

If the provider supports provider-side idempotency, the backend should reuse a stable key for that external request too.

Lab implementation

The lab intentionally keeps the infrastructure small.

Unsafe:

func ProcessPayment(req PaymentRequest) (PaymentResult, error) {
    return gateway.Charge(req)
}

Safe:

validate key
↓
calculate fingerprint
↓
reserve operation
↓
PROCESSING
↓
execute payment
↓
store result
↓
COMPLETED

The storage implementation uses:

map + sync.RWMutex

This simulates atomic uniqueness without introducing a real database into the lab.

Run both versions:

go test ./labs/01-idempotency/unsafe/... -v -count=1

go test ./labs/01-idempotency/safe/... -v -count=1

Final mental model

Retry is normal.
Duplicate execution is the problem.
Idempotency makes retry safe.

Source code:

https://github.com/lukman-ss/software-engineering-lab/tree/main/labs/01-idempotency