DEV Community: Igor Grieder

Agentic Git Workflow

Igor Grieder — Wed, 04 Feb 2026 17:59:09 +0000

Trunk-Based Development for Fast, Safe AI-Assisted Shipping

If you’re using AI to move faster, trunk-based development (TBD) is the safest way to keep momentum without letting your main branch drift into chaos. The core idea is simple: keep main always releasable by integrating small changes frequently and using feature flags to separate merge from release.

Below is a practical, AI-friendly workflow, with Go examples and a Bash helper for Git worktrees.

What Trunk-Based Development Really Means

TBD is not no branches at all and just commiting to main. It’s short-lived branches (or even small feature branches) and continuous integration:

main (trunk) is always in a releasable state.
Developers (and agents) merge small changes frequently.
Feature flags let you merge unfinished work safely.
CI must be fast and trusted.

This is ideal for AI-assisted development since the agent can generate changes quickly, and you can integrate them safely without long lived branches or merge hell.

A Simple, Repeatable TBD Workflow

Pull trunk before starting.
Create a small branch or worktree for the task.
Make a minimal change (prefer additive changes).
Gate risky behavior with a feature flag.
Run fast checks.
Merge to trunk quickly.
Remove the flag after the feature is stable.

Short feedback loops make errors cheap to have the benefits of shippign code fast.

Go Example: Feature Flag in a Handler

package main

import (
    "net/http"
    "os"
)

// It's better to have a separate service for dealing with feature flags
func enabled(key string) bool {
    return os.Getenv(key) == "true"
}

func profileHandler(w http.ResponseWriter, r *http.Request) {
    if enabled("FF_NEW_PROFILE") {
        w.Write([]byte("new profile experience"))
        return
    }
    w.Write([]byte("old profile experience"))
}

func main() {
    http.HandleFunc("/profile", profileHandler)
    _ = http.ListenAndServe(":8080", nil)
}

Why this works: you can merge the new code, keep it off in production, and enable it later with an environment change. Using this approach new features will just be isolated and controlled in an feature flag service.

Git Worktrees: AI Safe Isolation

Worktrees let you check out multiple branches in parallel without stashing or messing with your main working directory. This is perfect for AI experiments:

One worktree per task.
If the experiment fails, delete it, causing no side effects to trunk.
You can keep one worktree clean for main and another for AI-generated changes.

Bash Helper: Worktree Workflow

Create scripts/worktree.sh and use it to manage fast task worktrees:

#!/usr/bin/env bash
set -euo pipefail

ROOT_DIR=$(git rev-parse --show-toplevel)
BASE_DIR="${ROOT_DIR%/*}"

usage() {
  echo "usage: worktree.sh add <name> <branch> | rm <name> | list | cleanup"
}

case "${1:-}" in
  add)
    name=${2:-}
    branch=${3:-}
    if [[ -z "$name" || -z "$branch" ]]; then
      usage
      exit 1
    fi
    path="${BASE_DIR}/${name}"
    if git show-ref --verify --quiet "refs/heads/${branch}"; then
      git worktree add "$path" "$branch"
    elif git show-ref --verify --quiet "refs/remotes/origin/${branch}"; then
      git worktree add -b "$branch" "$path" "origin/${branch}"
    else
      git worktree add -b "$branch" "$path"
    fi
    echo "created: ${path}"
    ;;
  rm)
    name=${2:-}
    if [[ -z "$name" ]]; then
      usage
      exit 1
    fi
    git worktree remove "${BASE_DIR}/${name}"
    echo "removed: ${BASE_DIR}/${name}"
    ;;
  list)
    git worktree list
    ;;
  cleanup)
    git worktree prune
    git gc --prune=now
    ;;
  *)
    usage
    exit 1
    ;;
esac

Example usage:

# create an experiment worktree
./scripts/worktree.sh add encurtador-exp feat/exp-feature

# list worktrees
./scripts/worktree.sh list

# delete when done
./scripts/worktree.sh rm encurtador-exp

Final Takeaways

Try to apply those tools into your workflow to boost your productivity while using AI! Know the benefits of it:

Trunk-based development keeps you fast and safe.
Feature flags let you merge continuously without shipping unstable code.
Git worktrees make AI experiments low risk.
Smaller changes, faster feedback, fewer surprises.

Idempotency

Igor Grieder — Thu, 18 Dec 2025 19:39:41 +0000

In distributed systems, the assumption that every request reaches its destination and that every response returns to the sender is not true at all times. When a transaction, such as a $500 payment, is executed twice due to a network timeout or an retry policy, it's more than a minor bug, is a failure of system architecture.

Idempotency is not optional. It is a fundamental requirement for maintaining data integrity in any environment where network partitions, client retries, and system failures are inevitable.

In this article I'll show why it matters and how to fix it.

What is Idempotency?

An operation is idempotent if it can be applied multiple times without changing the result beyond the initial application. In the context of an API, this means that making the same call multiple times must not have any side effects on the business layer.

Method	Idempotent	Description
GET	Yes	Should not change state; multiple reads return the same resource.
PUT	Yes	Replaces the resource; repeating the replacement results in the same state.
DELETE	Yes	Deleting a resource twice results in the same outcome (it is gone).
POST	No	Typically creates a new resource. Without intervention, repeated POSTs result in duplicates.

Why Systems Fail Without Idempotency

Idempotency Keys

The standard pattern for enforcing exactly once processing of one transaction is the use of Idempotency Keys.

Implementation Workflow

Key Generation: The client generates a unique identifier (e.g, UUID) for the operation.
Request Header: The key is sent in a custom header (e.g., X-Idempotency-Key).
Server-Side Validation: If the key exists in the "processed" cache, the server returns the cached response immediately.
If the key is new, the server acquires a lock, processes the request, and stores the result before committing.

Client Side

// Generate UUID on first attempt
const idempotencyKey = uuidv4(); // "abc-123-def-456"

// Send request with key in header
fetch('/api/orders', {
  method: 'POST',
  headers: {
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ productId: 42, quantity: 1 })
});

// On retry (timeout/error), use THE SAME key
// The key doesn't change until operation succeeds or max retry is reached

Server Side in Go

func HandleCreateOrder(w http.ResponseWriter, r *http.Request) {
    idempotencyKey := r.Header.Get("Idempotency-Key")

    // Reject requests without key
    if idempotencyKey == "" {
        http.Error(w, "Idempotency-Key required", http.StatusBadRequest)
        return
    }

    // Check if already processed
    cachedResponse, found := checkKeyAlreadyProcessed(idempotencyKey)
    if found {
        // Return cached response
        w.WriteHeader(http.StatusCreated)
        w.Write(cachedResponse)
        return
    }

    // Process the order
    order, err := createOrder(r.Body)
    if err != nil {
        http.Error(w, "Failed to create order", http.StatusInternalServerError)
        return
    }

    // Store key for future retries
    storeProcessedKey(idempotencyKey, order, 24*time.Hour)

    w.WriteHeader(http.StatusCreated)
    json.NewEncoder(w).Encode(order)
}

By implementing idempotency, multiple requests with the same key won't have any side effects.

Strategic Implementation Best Practices

Persistence Layer Choice

Redis: Ideal for performance. Set a Time-to-Live (TTL) of 24–48 hours to prevent memory growth.
Relational DB: Ideal for strict consistency. Store the key within the same transaction as the business logic to ensure atomicity.

Deterministic Responses

An idempotent retry should return the original status code. If the first request returned a 201 Created, the subsequent retry with the same key should also return 201 Created, not a 200 OK or 409 Conflict. This ensures the client-side logic remains simple and consistent.

Scope of the Key

Keys should be scoped to the user or account. This prevents key collisions, where two different users might accidentally generate the same UUID (I know that this is not very likelly but it can happen, separate in tenants).

The Read-Modify-Write problem

A common mistake in implementing idempotency is failing to account for concurrency. In high-traffic systems, two identical requests might reach your API at the exact same millisecond.

// ❌ CRITICAL BUG: Race Condition
const record = await db.idempotency.find(key);
if (!record) {
    // Both Request A and Request B can reach this line simultaneously
    await service.processTransaction(); 
}

This can be fixed with a database Level Atomicity. To solve this, you must rely on database constraints or atomic "Set-if-Not-Exists" operations:

SQL: Use a UNIQUE constraint on the idempotency key column and handle the violation error.
Redis: Use the SET NX command to ensure only one worker can process the key.
NoSQL: Use conditional updates.

Conclusion

Idempotency is the main pillar of building resilient, fault tolerant distributed systems. By moving the responsibility of deduplication from the business logic to a structured architectural pattern, we eliminate entire classes of bugs related to double-spending and data corruption.

Error handling in Go

Igor Grieder — Tue, 25 Nov 2025 19:09:42 +0000

Each programming language has it's own way of dealing with errors. Popular languages such as JavaScript, Java, C#, and Python choose to use Exceptions to indicate something went wrong at runtime. Other languages, such as Go and Rust, choose to handle errors as values instead, using another paradigm that at first can be odd when you come from the other side of the force.

In this article, I'll cover up the type of errors we have in Go and how to master handling them.

Types

If you are reading this article, probably you've seen the famous err != nil expression that's often seen while coding in Go (in contrast we have try-catches, that can be messy too). I'll try to convince you that treating errors as values is a good choice after all and we can do better than just always returning them.

In Go, we basically have three types of errors: opaque, sentinels and custom errors. Let's cover them up.

Opaque Errors

Opaque errors do not give us much information apart from "an error happened" and the error itself. We often use this kind of error when the caller does not need to know what kind of error happened in the operation, since it won't take any logic operation based on it.

package main

import (
    "errors"
    "fmt"
)

type user struct {
    name    string
    balance int64
}

func main() {
    // Users mocked
    userFrom := &user{
        name:    "Igor",
        balance: 200,
    }

    userTo := &user{
        name:    "Maria",
        balance: 293,
    }

    err := DecrementBalance(userFrom, userTo, 204)
    if err != nil {
        fmt.Printf("Insuficient funds to decrement balance from: %v", err)
    }

  fmt.Println("Transaction finished")
}

func DecrementBalance(userFrom *user, userTo *user, val int64) error {
    if userFrom.balance < val {
        // Creating an opaque error
        return errors.New("user does not have the necessary balance")
    }

    userFrom.balance -= val
    userFrom.balance += val

    return nil
}

Sentinel errors

Let's increment now our example and let's say we need to know what kind of error happened. We can use what we call of sentinel errors to assert that the error emitted is of the kind we are dealing with.

Sentinel errors are often defined as package level variables. They are useful when you want to check for a specific error condition using errors.Is and branch logic based on it.

package main

import (
    "errors"
    "fmt"
)

// Define the sentinel error
var ErrInsufficientFunds = errors.New("user does not have the necessary balance")

type user struct {
    name    string
    balance int64
}

func main() {
    userFrom := &user{name: "Igor", balance: 200}
    userTo := &user{name: "Maria", balance: -23}

    err := DecrementBalance(userFrom, userTo, 204)
    if err != nil {
        // Check if the error is exactly our sentinel
        if errors.Is(err, ErrInsufficientFunds) {
            fmt.Printf("Transaction failed: %v", err)
            return
        }
        fmt.Println("An unexpected error occurred, try again")
    }
}

func DecrementBalance(userFrom *user, userTo *user, val int64) error {
    if userFrom.balance < val {
        // Return the sentinel
        return ErrInsufficientFunds
    }

    if userTo.balance < 0 {
        // Return opaque error
        return errors.New("negative user balance, operation canceled")
    }

    userFrom.balance -= val
    userTo.balance += val

    return nil
}

Custom Errors

Sometimes a simple string isn't enough. You might want to return dynamic data, like how much money was missing, something that would hold information, not just the actual error. For this, we use Custom Errors. These are structs that implement the error interface by defining an Error() string method.

package main

import (
    "errors"
    "fmt"
)

// Define a custom error struct
type InsufficientFundsError struct {
    Current  int64
    Required int64
}

func (e *InsufficientFundsError) Error() string {
    return fmt.Sprintf("insufficient funds: have %d, need %d", e.Current, e.Required)
}

func main() {
    userFrom := &user{name: "Igor", balance: 200}
    userTo := &user{name: "Maria", balance: 293}

    err := DecrementBalance(userFrom, userTo, 204)
    if err != nil {
        // Use errors.As to unwrap the error into our struct
        var fundsErr *InsufficientFundsError
        if errors.As(err, &fundsErr) {
            fmt.Printf("Transaction failed: you are short %d\n", fundsErr.Required - fundsErr.Current)
                return
        }

        fmt.Printf("An unexpected error occurred: %v\n", err)   
    }
}

func DecrementBalance(userFrom *user, userTo *user, val int64) error {
    if userFrom.balance < val {
        // Return the custom error struct
        return &InsufficientFundsError{
            Current:  userFrom.balance,
            Required: val,
        }
    }
    // some code
  return nil
}

Wrapping Errors

In real applications, errors bubble up through many layers (Repository -> Service -> Handler). If every layer just returns the error, you lose context. You know what went wrong, but not where or why.

To have a kind of a call stack behavior we can use error wrapping with %w. This allows to add context at each layer while still keeping the original error available to use errors.Is and errors.As for business logic, e.g. If it's just wanted to have a better vision of the error, using %v is an option, since it appends the error message to the next error. Overall, it's all about context for debuging and to navigate better in the codebase.

Here is how we can build a "perfect stack" of information that really helps when things go wrong. The mock result for the operation would be:

"transaction failed: transfer failed: insufficient funds"

Offcourse we can increment a log on it, but just by looking at the example we can clearly understand what happened!

func main() {
    // something...
    err := MakeTransaction(userFrom, userTo, 204)
    if err != nil {
        // Print the full chain: "transaction failed: transfer failed: insufficient funds"
        fmt.Printf("Error: %v\n", err)

        // We can still check the root cause!
        if errors.Is(err, ErrInsufficientFunds) {
             fmt.Println(">> Root cause was money.")
        }
    }
}

func MakeTransaction(from, to *user, amount int64) error {
    err := DecrementBalance(from, to, amount)
    if err != nil {
        // Wrap the error with more context
        return fmt.Errorf("transaction failed: %w", err)
    }
    return nil
}

Conclusion

If you are new to Go or the general idea of errors as values leave a comment if this article helped you to understand it better! Always remember to handle your errors gracefully.

Locks

Igor Grieder — Wed, 19 Nov 2025 19:31:22 +0000

In a concurrent database context locks are used to prevent race conditions between data accesses. To handle these situations we need to decide how we'll react to a race condition, in an optimistic or an pessimistic way. This article will be a quick summary for when using each of the approaches and how to apply them in PostgreSQL.

Pessimistic Locking

We tend to use pessimistic locks when data is frequently changed and it's known that conflicts are common. The idea of the strategy is to use a lock in a database level that blocks other processes to access the locked rows. This will add more latency because of the blocking behavior, so given that the tradeoff here needs to be considered at scale. Overall, this approach is used when data being updated is critical, we can't take the action atomically in the database layer and blocking is acceptable.

To give a quick example on how to apply this pattern I'll show a quick sample of Go using PostgreSQL.

package main

import (
    "context"
    "database/sql"
    "errors"
    "fmt"
    "log/slog"
    "time"
)

var ErrConflict = errors.New("optimistic lock conflict: data has been modified by another process")
var ErrInsufficientFunds = errors.New("insufficient funds for transfer")

type User struct {
    ID       int64
    PixKey   string
    Bio      string
    IsActive bool
    Version  int
    Credits  float64
}

type UserService struct {
    DB *sql.DB
}

func NewUserService(db *sql.DB) *UserService {
    return &UserService{DB: db}
}

// TransferPixCredits action shows pessimistic locking
// We lock the row, do our work, and then commit the changes
// Concurrent queries on the row will wait the lock to be released
func (s *UserService) TransferPixCredits(ctx context.Context, fromPixKey string, toPixKey string, amount float64) error {
    tx, err := s.DB.BeginTx(ctx, nil)
    if err != nil {
        return fmt.Errorf("failed to begin transaction: %v", err)
    }
    defer tx.Rollback()

    ctxDb, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()

    slog.Info("Acquiring locks for transfer", "from", fromPixKey, "to", toPixKey)

    // Because we used FOR UPDATE in our Select query we'll lock all the rows affected until
    // the transaction is finished
    const getQuery = "SELECT id, pix_key, is_active, version, credits FROM users WHERE pix_key = $1 FOR UPDATE;"

    userFrom := tx.QueryRowContext(ctxDb, getQuery, fromPixKey)
    var sender User
    if err := userFrom.Scan(&sender.ID, &sender.PixKey, &sender.IsActive, &sender.Version, &sender.Credits); err != nil {
        if err == sql.ErrNoRows {
            return fmt.Errorf("sender PIX key not found: %w", err)
        }
        return fmt.Errorf("error scanning sender row: %v", err)
    }

    userTo := tx.QueryRowContext(ctxDb, getQuery, toPixKey)
    var receiver User
    if err := userTo.Scan(&receiver.ID, &receiver.PixKey, &receiver.IsActive, &receiver.Version, &receiver.Credits); err != nil {
        if err == sql.ErrNoRows {
            return fmt.Errorf("receiver PIX key not found: %w", err)
        }
        return fmt.Errorf("error scanning receiver row: %v", err)
    }

    slog.Info("Locks acquired. Performing transfer")

    if !sender.IsActive {
        return fmt.Errorf("sender account is inactive")
    }
    if !receiver.IsActive {
        return fmt.Errorf("receiver account is inactive")
    }
    if sender.Credits < amount {
        return ErrInsufficientFunds
    }

    newSenderCredits := sender.Credits - amount
    newReceiverCredits := receiver.Credits + amount

    const updateQuery = "UPDATE users SET credits = $1 WHERE id = $2;"
    if _, err := tx.ExecContext(ctxDb, updateQuery, newSenderCredits, sender.ID); err != nil {
        return fmt.Errorf("failed to update sender credits: %w", err)
    }

    if _, err := tx.ExecContext(ctxDb, updateQuery, newReceiverCredits, receiver.ID); err != nil {
        return fmt.Errorf("failed to update receiver credits: %w", err)
    }

    const logQuery = "INSERT INTO credit_transfers (from_user_id, to_user_id, amount) VALUES ($1, $2, $3);"
    if _, err := tx.ExecContext(ctxDb, logQuery, sender.ID, receiver.ID, amount); err != nil {
        return fmt.Errorf("failed to log transfer: %w", err)
    }

    slog.Info("Committing transaction and releasing locks")
    return tx.Commit()
}

Optimistic Locking

On the other hand, optimistic locks are used in environments that data conflicts rarely change. This method does not hold any lock in the selected rows and the control is implemented in the codebase when updating records. We can track if an update happened before we commited our change by looking at a version or an last updated at column, for example. To sum up, this method must only be choosen if conflict rates are low, since we will rollback the entire operation if our read data is stale, adding not desired latency.

package main

import (
    "context"
    "database/sql"
    "errors"
    "fmt"
    "log/slog"
)

var ErrConflict = errors.New("optimistic lock conflict: data has been modified by another process")

type User struct {
    ID         int64
    PixKey     string
    Bio        string
    IsActive   bool
    Version    int
    Credits    float64
    DailyLimit float64
}

type UserService struct {
    DB *sql.DB
}

func NewUserService(db *sql.DB) *UserService {
    return &UserService{DB: db}
}

// UpdateDailyLimit uses optimistic locking to prevent lost updates on critical settings
// If two admins try to change limits simultaneously, the second one will fail safely
// rather than overwriting the first one's changes
func (s *UserService) UpdateDailyLimit(ctx context.Context, pixKey string, newLimit float64) error {
    slog.Info("Reading user limit (no lock).")

    const getQuery = "SELECT id, pix_key, bio, is_active, version, credits, daily_limit FROM users WHERE pix_key = $1;"
    row := s.DB.QueryRowContext(ctx, getQuery, pixKey)

    var user User
    if err := row.Scan(&user.ID, &user.PixKey, &user.Bio, &user.IsActive, &user.Version, &user.Credits, &user.DailyLimit); err != nil {
        if err == sql.ErrNoRows {
            return fmt.Errorf("no PIX key related to the user: %w", err)
        }
        return fmt.Errorf("error while scanning postgres row: %v", err)
    }

    slog.Info("Validating business rules against current state", "current_limit", user.DailyLimit)

    tx, err := s.DB.BeginTx(ctx, nil)
    if err != nil {
        return fmt.Errorf("failed to begin transaction: %w", err)
    }
    defer tx.Rollback()

    slog.Info("Attempting update", "user", user.ID, "version", user.Version)

    const updateQuery = `
        UPDATE users
        SET daily_limit = $1, version = version + 1
        WHERE id = $2 AND version = $3;`

    result, err := tx.ExecContext(ctx, updateQuery, newLimit, user.ID, user.Version)
    if err != nil {
        return fmt.Errorf("failed to attempt update: %w", err)
    }

    rowsAffected, err := result.RowsAffected()
    if err != nil {
        return fmt.Errorf("failed to check rows affected: %w", err)
    }

    if rowsAffected == 0 {
        // This is the critical catch
        // It implies someone else changed the limit
        // after we read it but before we commited our changes
        slog.Warn("CONFLICT -> Data changed by another process before we commited")
        return ErrConflict
    }

    slog.Info("Update successful")
    return tx.Commit()
}

Conclusion

To conclued, dealing with database race conditions goes way beyond the examples discussed in this article, since they were meant to be simple. The tradeoffs between choosing a optimistic or pessimistic lock strategy always need to be considered. If a lock is indeed needed the key to know which one to choose is to identify how often data changes happen in the application. Hope this small article was usefull and leave a comment about locks down below!

Fault Tolerance

Igor Grieder — Tue, 11 Nov 2025 16:42:10 +0000

By definition, fault tolerance is the ability of a system to continue operating despite the failures in one of more components. This is highly applicable in terms of a distributed system application and in order to achieve it we need to take some actions. In this article, I'll cover up some strategies that can be followed, in the application level, to handle failures better overall.

When failures can happen

The main challenge in a distributed system is the communication between nodes, since they're exposed to network, software and hardware failures. Since we cannot handle directly hardware faults, we must ensure our hole system is designed to tolerate software/network failures at edge points. Overall, it's easier to ask when they don't fail actually.

Application-Level Failure Handling

All of our strategies will have the same objective: not overwhelm failing systems and cause node drops in our environment.

Idempotency

Given that we are exposed to network failures, we must ensure our system is idempotent when we can't rely on HTTP verbs. This can be achieved with different approaches, the most common ones being using idempotency keys and unique constraints in databases. In the example below I covered the usage of an idempotency key for processing the POST request in Go. Overall, the idea is to not have side effects if we have already processed the sent key.

// Mimic of the request handler
func HandleRequest(w http.ResponseWriter, r *http.Request) {
    idempotencyKey := r.Header.Get("Idempotency-Key")

    if len(idempotencyKey) == 0 {
        slog.Error("error processing the request",
            slog.String("key", idempotencyKey),
            slog.String("err", "no idempotencyKey provided"),
        )

        w.WriteHeader(http.StatusBadRequest)
        return

    }

    wasProcessed, err := checkKeyAlreadyProcessed(idempotencyKey)
    if err != nil {
        slog.Error("error checking if key was processed", slog.String("err", err.Error()))

        w.WriteHeader(http.StatusInternalServerError)
        return
    }

    if !wasProcessed {
        err = process(idempotencyKey)

        if err != nil {
            slog.Error("error processing the request",
                slog.String("key", idempotencyKey),
                slog.String("err", err.Error()),
            )

            w.WriteHeader(http.StatusInternalServerError)
            return
        }
    }

    // Was already processed
    w.WriteHeader(http.StatusCreated)
}

Timeout

This is the most basic tool we can use to avoid blocking our process and pile up the process queue. ALWAYS define timeout in calls considering the business rules of your domain.

func MakeRequest() error {
    client := &http.Client{Timeout: 1 * time.Minute}
    request, err := http.NewRequest("POST", "http://testing.com", nil)
    if err != nil {
        return fmt.Errorf("error creating the request %v", err)
    }

    // Adding the idempotency key header
    request.Header.Add("Idempotency-Key", uuid.NewString())

    response, err := client.Do(request)
    if err != nil {
        return fmt.Errorf("error procesing the request %v", err)
    }

    // rest of the code...
    slog.String("HTTP code", response.Status)
    return nil
}

Retries (Exponential Backoff + Jitter)

To add on the timeouts and idempotency keys, we can choose to, instead of in the first try returning to the client an error, handle failures in the application level. This approach increases latency overall in failing states but it is often the best choice, since the user will have to interact less with the UI in a failure scenario. Now our MakeRequest function will be enhanced because of:

Exponential Backoff: instead of retrying with the same delay after each failure the interval is increased exponentially. It doesn't make sense to retry in sequence if an error happened without some kind of delay. This choice can be pretty useful to avoid overwhelimg the system in a faulty state.
Jitter: a jitter is added to the delay to add some randomness to avoid sending concurrent retries in the exact same intervals, spreading the calls to the other application overt the time.

func MakeRequest() error {
    const MAX_RETRIES = 3
    const BASE_DELAY = 100 * time.Millisecond
    const MAX_JITTER_MS = 100

    // Create a new random source
    r := rand.New(rand.NewSource(time.Now().UnixNano()))

    client := &http.Client{Timeout: 1 * time.Minute}

    // We'll store the last error to return if all retries fail
    var lastErr error
    var response *http.Response

    for i := 0; i <= MAX_RETRIES; i++ {
        request, err := http.NewRequest("POST", "http://testing.com", nil)
        if err != nil {
            // This is a non-retryable error
            return fmt.Errorf("error creating the request %v", err)
        }
        request.Header.Add("Idempotency-Key", uuid.NewString())

        response, err = client.Do(request)
        lastErr = err

        // Success = no network error AND a non-server-error (non-5xx) status.
        // 4xx errors are client errors and typically not retryable.
        if err == nil && response.StatusCode < 500 {
            slog.Info("Request successful", "status", response.Status)
            return nil
        }

        // If we're here, it was either a network error (err != nil)
        // or a server error (response.StatusCode >= 500).
        // Don't sleep if this was the last attempt
        if i == MAX_RETRIES {
            break
        }

        // Exponential backoff, with base 2^n
        backoff := BASE_DELAY * time.Duration(math.Pow(2, float64(i)))

        // Jitter: random duration between 0 and MAX_JITTER_MS
        jitter := time.Duration(r.Intn(MAX_JITTER_MS)) * time.Millisecond

        // Total sleep duration
        sleepDuration := backoff + jitter

        slog.Warn("Request failed, retrying",
            slog.Int("attempt", i+1),
            slog.String("sleep_duration", sleepDuration.String()),
            slog.String("error", err.Error()),
        )

        // Wait before the next attempt
        time.Sleep(sleepDuration)
    }

    // If the loop finishes, all retries have failed
    if lastErr != nil {
        return fmt.Errorf("all retries failed, last network error: %v", lastErr)
    }

    // Handle case where the last attempt was a 5xx error
    return fmt.Errorf("all retries failed, last status: %s", response.Status)
}

Circuit Breaker

The Circuit Breaker is a robust design pattern to handle failing nodes in the
architecture. It introduces three states that describe an application state: circuit open,
circuit closed or circuit half-open.

Closed: calls to the node are sent.
Open: calls to the node won't be sent.
Half-open: after some defined period on open state, the application goes into the half-open state and it tries to make a call. If this action results in a failure, the system goes back into open and, if it succeeds, it goes into closed.

Now our simple HTTP Request will be even more robust following the pattern.
First, let's defined our circuit breaker struct to handle the logic:

package cb

import (
    "errors"
    "fmt"
    "log/slog"
    "math"
    "math/rand"
    "net/http"
    "sync"
    "time"

    "github.com/google/uuid"
)

// Define the states for the circuit breaker
type State int

const (
    StateClosed State = iota
    StateOpen
    StateHalfOpen
)

// Sentinel error
var ErrCircuitOpen = errors.New("circuit breaker is open")

type CircuitBreaker struct {
    mu          sync.Mutex
    state       State
    failures    int
    maxFailures int
    openSince   time.Time
    openTimeout time.Duration
}

// NewCircuitBreaker creates a new circuit breaker with its thresholds
func NewCircuitBreaker(maxFailures int, openTimeout time.Duration) *CircuitBreaker {
    return &CircuitBreaker{
        state:       StateClosed,
        maxFailures: maxFailures,
        openTimeout: openTimeout,
    }
}

Now let's add the logic to handle state changes

// Checks if a request is allowed to proceed
func (cb *CircuitBreaker) CheckBeforeRequest() error {
    cb.mu.Lock()
    defer cb.mu.Unlock()

    switch cb.state {
    case StateClosed:
        // Always allowed in a closed state
        return nil

    case StateOpen:
        // Check if the open timeout has elapsed
        if time.Since(cb.openSince) > cb.openTimeout {
            // Timeout exceeded -> Half-Open
            slog.Warn("Circuit Breaker: Open -> Half-Open")
            cb.state = StateHalfOpen
            return nil // Allow one test request to go through
        }

        // Still open
        return ErrCircuitOpen

    case StateHalfOpen:
        // The circuit is already in a Half-Open state
        // a test request is in flight. Reject all other concurrent requests
        return ErrCircuitOpen
    }
    return nil
}

// OnSuccess notifies the breaker of a successful call
func (cb *CircuitBreaker) OnSuccess() {
    cb.mu.Lock()
    defer cb.mu.Unlock()

    switch cb.state {
    case StateHalfOpen:
        // Test request succeeded -> close circuit
        slog.Info("Circuit Breaker: Half-Open -> Closed")
        cb.state = StateClosed
        cb.failures = 0

    case StateClosed:
        // Reset consecutive failures
        cb.failures = 0
    }
}

// OnFailure notifies the breaker of a failed call
func (cb *CircuitBreaker) OnFailure() {
    cb.mu.Lock()
    defer cb.mu.Unlock()

    switch cb.state {
    case StateHalfOpen:
        // The test request failed -> go into open state again
        slog.Error("Circuit Breaker: Half-Open -> Open (test failed)")
        cb.state = StateOpen
        cb.openSince = time.Now() // Reset the open timer

    case StateClosed:
        cb.failures++
        slog.Warn("Circuit Breaker: Failure recorded", "count", cb.failures)

        // Check if we've reached the threshold
        if cb.failures >= cb.maxFailures {
            slog.Error("Circuit Breaker: Closed -> Open (threshold reached)")
            cb.state = StateOpen
            cb.openSince = time.Now()
        }
    }
}

Now we need to update our request handler to use the circuit breaker

// Handler will hold our client and the circuit breaker for this service
type Handler struct {
    client *http.Client
    cb     *CircuitBreaker
}

// NewHandler creates a new handler
func NewHandler(cb *CircuitBreaker) *Handler {
    return &Handler{
        client: &http.Client{Timeout: 1 * time.Minute},
        cb:     cb,
    }
}

func (h *Handler) MakeRequest() error {
    if err := h.cb.CheckBeforeRequest(); err != nil {
        // Circuit is Open or Half-Open -> fail fast
        slog.Error("Request blocked by circuit breaker",
      slog.String("error", err.Error(),
    )
        return err
    }

    err := h.attemptRequestWithRetry()

    if err != nil {
        // The operation failed after all retries
        h.cb.OnFailure()
    return err
    }

  // The operation succeeded
  h.cb.OnSuccess()

    return nil
}

// Function with retry encapsulated
func (h *Handler) attemptRequestWithRetry() error {
    const MAX_RETRIES = 3
    const BASE_DELAY = 100 * time.Millisecond
    const MAX_JITTER_MS = 100
        idempotencyKey = uuid.NewString()

    r := rand.New(rand.NewSource(time.Now().UnixNano()))

    var lastErr error
    var response *http.Response

    for i := 0; i <= MAX_RETRIES; i++ {
        request, err := http.NewRequest("POST", "http://testing.com", nil)
        if err != nil {
            return fmt.Errorf("error creating the request %v", err)
        }
        request.Header.Add("Idempotency-Key", idempotencyKey)

        // Use the handler's client
        response, err = h.client.Do(request)
        lastErr = err

        if err == nil && response.StatusCode < 500 {
            slog.Info("Request successful", "status", response.Status)
            if response.Body != nil {
                response.Body.Close()
            }
            return nil
        }

        if i == MAX_RETRIES {
            break
        }

        // Calculate backoff and jitter
        backoff := BASE_DELAY * time.Duration(math.Pow(2, float64(i)))
        jitter := time.Duration(r.Intn(MAX_JITTER_MS)) * time.Millisecond
        sleepDuration := backoff + jitter

        // Safely create error message
        errMsg := "server error"
        if err != nil {
            errMsg = err.Error()
        }

        slog.Warn("Request failed, retrying",
            slog.Int("attempt", i+1),
            slog.String("sleep_duration", sleepDuration.String()),
            slog.String("error", err.Error()),
        )

        time.Sleep(sleepDuration)
    }

    // All retries failed
    if lastErr != nil {
        return fmt.Errorf("all retries failed, last network error: %v", lastErr)
    }

    return fmt.Errorf("all retries failed, last status: %s", response.Status)
}

Conclusion

You need to always consider how your system will handle failures when interacting with external services. Remember to consider the tradeoffs, even though it's more likely to have a fault-tolerant application, given its benefits. Please leave a like and a comment about this topic.

Cache

Igor Grieder — Mon, 20 Oct 2025 20:40:03 +0000

Caching is a well know abstraction in programming, we see it every where, from our CPU, to keep data in a memory storage faster than the RAM, to CDNs, for delivering content faster to the user. It's usually used as an optimization factor in systems that need a slower latency in read operations. Thus, understading what it is and how to implement it in applications is a good knowledge to have overall.

Caching in Web Development

In Web Development, the Cache is a layer that usually sits between our persistent data storage and the application. Its purpose is to make access to frequently used data cheaper/quicker by having these information in the cache available for read operations. In this article we'll cover read and write implementations for caching in our backend, but first I'll explain some important topics.

Consistency

Consistency between the cache and the database layers is something we need to always be aware of. We can try to achieve it relying on a short TTL (Time-to-Live) or strategies to invalidate the cache on database updates, to avoid manipulating stale data. Overall, it's important to decide how consistency is going to be reached between these components of the system and we'll cover some strategies on that.

Invalidation

To ensure consistency we need to always once our database layer is updated to invalidate our cache keys that are affected by the operation. We can either choose to delete or to update in the cache layer to avoid having stale data. This decision can depend on which approach of caching it's being used.

Cache hit and Cache miss

Those are two terms I'll be using quite a lot in this article, cache miss and cache hit and what they're is pretty self-explanatory I would say:

Cache hit: we say he have a cache hit if when we look into our cache and we can find the data we would like to access, so we call it a hit!
Cache miss: in the other hand if we cannot find the data in the cache we have a miss.

Cache-Aside pattern

The Cache-Aside pattern, known as the lazy loading as well, is a simple implementation and usually is the most common approach for caching and reading. The idea of this method is to always have in cache the last written data in our database and repopulate the cache on every first cache miss.

Overall, this pattern will provides slower first reads, since it will need to fetch in the database and than populate the cache, but subsequent reads will be way faster. Given that, when we change something in our database, we need to invalidate cache keys that possibly use our data.

package handlers

import (
    "context"
    "database/sql"
    "encoding/json"
    "log"
    "net/http"
    "time"

    "github.com/redis/go-redis/v9"
)

type Product struct {
    ID    string  `json:"id"`
    Name  string  `json:"name"`
    Price float64 `json:"price"`
}

type handler struct {
    redis *redis.Client
    pg    *sql.DB
}

func NewHandler(redis *redis.Client, pg *sql.DB) *handler {
    return &handler{redis: redis, pg: pg}
}

func (h *handler) GetProductCacheAside(w http.ResponseWriter, r *http.Request) {
    // Assume we get the product ID from the query params
    id := r.URL.Query().Get("id")
    if id == "" {
        http.Error(w, "Product ID is required", http.StatusBadRequest)
        return
    }

    // Look for data in the cache
    cacheKey := "product:" + id
    cachedProduct, err := h.redis.Get(context.Background(), cacheKey).Bytes()

    // Cache hit
    if err == nil {
        log.Println("Cache HIT")
        w.Header().Set("Content-Type", "application/json")
        w.Write(cachedProduct)
        return
    }

    // Cache Miss
    log.Println("Cache MISS")
    var product Product

    // Query the database
    err = h.pg.QueryRow("SELECT id, name, price FROM products WHERE id = $1", id).Scan(&product.ID, &product.Name, &product.Price)
    if err != nil {
        http.Error(w, "Product not found", http.StatusNotFound)
        return
    }

    // Populate the cache for next time
  productJSON, err := json.Marshal(product)
    if err != nil {
        // In a real prod environment a more persistent way of this double write should be enforced
        // if the cache write fails after the DB write succeeds.

        http.Error(w, "Could not process product data", http.StatusInternalServerError)
        return
    }

    err = h.redis.Set(context.Background(), cacheKey, productJSON, 5*time.Minute).Err()
    if err != nil {
        // In a real prod environment a more robust way is the right choice
        // if the cache write fails after the DB write succeeds.

        log.Printf("CRITICAL: DB updated but cache failed: %v", err)
        http.Error(w, "Failed to update cache", http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(product)
}

Write-Through pattern

The Write-Through pattern, is a way for dealing with cache writes and the idea is to maintain a strong consistency between the data storages, improving the number of cache hits. This option is usually chosen when we have an environment that needs consistent low latency reads.

However, the Write-Through expects a more robust system to implement those dual write situations. Given that, it is recommended to have a strong fault tolerance approach during the dual inserts, since we need to guarantee that one write will just be successful if it's done correctly in both storages.

Both write strategies I'll discuss can be used alongside the Cache-Aside pattern and usually they are.

package handlers

import (
    "context"
    "database/sql"
    "encoding/json"
    "log"
    "net/http"
    "time"

    "github.com/redis/go-redis/v9"
)

type Product struct {
    ID    string  `json:"id"`
    Name  string  `json:"name"`
    Price float64 `json:"price"`
}

type handler struct {
    redis *redis.Client
    pg    *sql.DB
}

func NewHandler(redis *redis.Client, pg *sql.DB) *handler {
    return &handler{redis: redis, pg: pg}
}

func (h *handler) UpdateProductWriteThrough(w http.ResponseWriter, r *http.Request) {
    var product Product
    if err := json.NewDecoder(r.Body).Decode(&product); err != nil {
        http.Error(w, "Invalid request body", http.StatusBadRequest)
        return
    }
    cacheKey := "product:" + product.ID

    // Write to the database first
    _, err := h.pg.Exec("UPDATE products SET name = $1, price = $2 WHERE id = $3", product.Name, product.Price, product.ID)
    if err != nil {
        http.Error(w, "Failed to update database", http.StatusInternalServerError)
        return
    }

    // Write the same data to the cache
    productJSON, err := json.Marshal(product)
    if err != nil {
        // In a real prod environment a more persistent way of this double write should be enforced
        // if the cache write fails after the DB write succeeds.

        http.Error(w, "Could not process product data", http.StatusInternalServerError)
        return
    }

    err = h.redis.Set(context.Background(), cacheKey, productJSON, 5*time.Minute).Err()
    if err != nil {
        // In a real prod environment a more persistent way of this double write should be enforced
        // if the cache write fails after the DB write succeeds.

        log.Printf("CRITICAL: DB updated but cache failed: %v", err)
        http.Error(w, "Failed to update cache", http.StatusInternalServerError)
        return
    }

    log.Println("Write-Through successful")
    w.WriteHeader(http.StatusOK)
}

Write-Behind pattern

The Write-Behind or Lazy Write pattern goal is to reduce the latency increased in write operations when we need to update state in two different storages. The strategy is simple and consists of writing only to the cache and confirming the operation immediately. The database is then updated asynchronously in the background.

This makes write operations feel instantaneous to the user. However, this speed comes with a trade-off between immediate consistency for performance, resulting in eventual consistency.

package handlers

import (
    "context"
    "database/sql"
    "encoding/json"
    "log"
    "net/http"
    "time"

    "github.com/redis/go-redis/v9"
)

type Product struct {
    ID    string  `json:"id"`
    Name  string  `json:"name"`
    Price float64 `json:"price"`
}

type handler struct {
    redis *redis.Client
    pg    *sql.DB
}

func NewHandler(redis *redis.Client, pg *sql.DB) *handler {
    return &handler{redis: redis, pg: pg}
}

func (h *handler) UpdateProductWriteBehind(w http.ResponseWriter, r *http.Request) {
    var product Product
    if err := json.NewDecoder(r.Body).Decode(&product); err != nil {
        http.Error(w, "Invalid request body", http.StatusBadRequest)
        return
    }
    cacheKey := "product:" + product.ID

    // Write data to the cache immediately
    productJSON, _ := json.Marshal(product)
    err := h.redis.Set(context.Background(), cacheKey, productJSON, 5*time.Minute).Err()
    if err != nil {
        http.Error(w, "Failed to write to cache", http.StatusInternalServerError)
        return
    }

  err := h.redis.Set(context.Background(), cacheKey, productJSON, 5*time.Minute).Err()
    if err != nil {
        http.Error(w, "Failed to write to cache", http.StatusInternalServerError)
        return
    }

    // Return success to the user immediately
    log.Println("Write-Behind: Cache updated. Acknowledged to client.")
    w.WriteHeader(http.StatusAccepted) // 202 Accepted is a good status code here

    // Asynchronously write to the database after a delay
    go func() {
        // In a real prod application this need to be a more robust queueing system
        // instead of just a simple timed goroutine.
        time.Sleep(10 * time.Second)

        _, err := h.pg.Exec("UPDATE products SET name = $1, price = $2 WHERE id = $3", product.Name, product.Price, product.ID)
        if err != nil {
            log.Printf("ERROR: Failed write-behind to database: %v", err)
            // Need an error handling/retry mechanism here to ensure consistency
        } else {
            log.Println("Write-Behind: Database updated successfully.")
        }
    }()
}

Conclusion

To sum up, it's a good practice to use the Cache-Aside pattern to reduce latency overall in reads. You then choose a write strategy to proactively keep the cache data fresh when your database changes. A fresher, more consistent cache naturally leads to more occurrences of cache hits for your Cache-Aside pattern.

Always remember that the database is your system's true source of truth. While the cache is fast, it's also volatile since it's an in-memory storage and data can be lost. The database provides durability, ensuring your data is safely written to disk.

If you liked this article please leave a like and a comment!

Dual Write and the Transactional Outbox Pattern

Igor Grieder — Wed, 15 Oct 2025 00:50:10 +0000

Introduction to the Dual Write problem

When dealing with an application that uses the Event Driven Architecture (EDA), for asynchronous communication between components, we often come against a situation that we must update state in the database and after publish a messsage into a broker, or make an HTTP call. This scenario is typically called the Dual Write Problem, when we need to make an operation in two different systems at the same time and it must be atomic.

As we know, those operations aren't atomic, so if we write/update a record in the database and then we have an error publishing to the broker, we need to undo our command.

Transactional Outbox Pattern

The Transactional Outbox Pattern comes to solve this problem in a simple, consistent, resilient and elegant way. It transforms two writes, in different systems, into just one transaction in the database. Following this approach, we ensure strong consistency between the application state, since SQL or even NoSQL databases ensure atomicity in a transaction.

This pattern is implemented using an outbox table, which serves as a durable queue for events. An asynchronous worker, often called a Relay, continually polls this table and publishes the saved events to the message broker. This design ensures both consistency and resilience because the Relay can implement a robust retry strategy to handle issues like a failing broker or a network partition.

Code example

I'll give a small example with a Go code to illustrate and show how to use it properly.

package order

import (
    "context"
    "database/sql"
    "encoding/json"
    "log"

    _ "github.com/lib/pq" // PG driver
)

func CreateOrder(db *sql.DB, customerID int, product string) error {
    tx, err := db.BeginTx(context.Background(), nil)
    if err != nil {
        return err
    }
    defer tx.Rollback()

    // Inserting the business data into its table for auditing
    var orderID int
    err = tx.QueryRow(
        `INSERT INTO orders (customer_id, product) VALUES ($1, $2) RETURNING id`,
        customerID, product,
    ).Scan(&orderID)
    if err != nil {
        return err
    }

    // Creating the event payload and inserting it into the outbox table
    eventPayload, err := json.Marshal(map[string]interface{}{
        "order_id":    orderID,
        "customer_id": customerID,
        "product":     product,
    })
    if err != nil {
        return err
    }

    _, err = tx.Exec(
        `INSERT INTO outbox (topic, payload) VALUES ($1, $2)`,
        "order.created", eventPayload,
    )
    if err != nil {
        return err
    }

    log.Printf("Successfully created order %d and outbox event in one transaction.", orderID)

    // If we made both inserts we can commit our operation
    return tx.Commit()
}

Now we need to create a Relay Worker that will be pooling events from the outbox table.

package worker

import (
    "context"
    "database/sql"
    "log"

    "github.com/streadway/amqp"
)

const MAX_RETRIES = 3 // Maximum retry value when trying to publish an event from the outbox table

func processOutboxEvents(db *sql.DB, ch *amqp.Channel) error {
    // The transaction locks the selected rows and ensures the status updates are atomic
    tx, err := db.BeginTx(context.Background(), nil)
    if err != nil {
        return err
    }
    defer tx.Rollback()

    // Select pending events, locking them to prevent other workers from processing them
    // In this way we can have multiple relay workers processing the same table
    rows, err := tx.Query(`
        SELECT id, topic, payload, retry_count FROM outbox
        WHERE status = 'PENDING' AND processed_at IS NULL
        ORDER BY created_at ASC
        LIMIT 10
        FOR UPDATE SKIP LOCKED
    `)
    if err != nil {
        return err
    }
    defer rows.Close()

    for rows.Next() {
        var id, topic string
        var payload []byte
        var retryCount int
        if err := rows.Scan(&id, &topic, &payload, &retryCount); err != nil {
            return err // We should rollback the transaction
        }

        // Publishing the event into RabbitMQ
        err = ch.Publish(
            "events.exchange",
            topic,
            false,
            false,
            amqp.Publishing{
                ContentType: "application/json",
                Body:        payload,
            })

        if err != nil {
            log.Printf("Failed to publish event %s (attempt %d): %v", id, retryCount+1, err)

            // Since we had an error we must see if we reached the retry limit for this event
            if retryCount+1 >= MAX_RETRIES {
                // We've reached the max retries, so mark as FAILED (dead-letter it).
                log.Printf("Event %s reached max retries. Moving to FAILED state.", id)

                _, updateErr := tx.Exec(`
                    UPDATE outbox SET status = 'FAILED', retry_count = $1, last_error = $2
                    WHERE id = $3
                `, retryCount+1, err.Error(), id)
                if updateErr != nil {
                    return updateErr // We should rollback the transaction since it's an database error
                }
            } else {
                // Since we didn't reach the limit we will just increment it
                _, updateErr := tx.Exec(`
                    UPDATE outbox SET retry_count = $1, last_error = $2 WHERE id = $3`, retryCount+1, err.Error(), id)
                if updateErr != nil {
                    return updateErr // We should rollback the transaction since it's an database error
                }
            }
        } else {
            // If we don't have an error we can update in the database the status to success
            _, updateErr := tx.Exec(`
                UPDATE outbox SET processed_at = NOW(), status = 'PROCESSED', last_error = NULL
                WHERE id = $1
            `, id)
            if updateErr != nil {
                return updateErr // We should rollback the transaction since it's an database error
            }

            log.Printf("Successfully published event %s", id)
        }
    }

    // Commit our transaction
    return tx.Commit()
}

Conclusion

Overall, we could've solved this problem by by simply handling potential errors in our application when writing to the database and then publishing the event. However, using the Outbox Pattern, a concise and elegant way of solving the dual write problem, enforces separation of concerns in the application and can be very handy. The next time you come across this scenario give it a try and feel free to leave some comments!

CAP Theorem

Igor Grieder — Fri, 03 Oct 2025 12:39:42 +0000

In this short article I will talk about an important topic in computer science, the CAP theorem. It is also known as Brewer's theorem and it's a fundamental principle in distributed data store systems, but first, what's a distributive system?

Distributive System

In a few words, a system is considered to be a distributive system when it has multiple computers operating over a network, called nodes, and for the end-user it appears to be just one after all.

What's CAP Theorem?

The theorem states that it's impossible for a distributed data store to simultaneously provide more than two of the following three pillars: Consistency, Availability, and Partition Tolerance (CAP).

Importance

This is indeed important because modern applications rely on distributed systems to be scalable and resilient, with tolerance to faults. Given that these nodes communicate over a network, failures are inevitable, and the CAP theorem provides trade-offs that we can make when a failure happens.

The Three Pillars Explained

C - Consistency: Guarantees that every read operation receives the most recent write or an error. When data is written to one node it will be replicated to the others, ensuring that whenever a read operation is done in any node it will be consistent.

A - Availability: This means that every request receives a response, even if one or more nodes are failing, but it doens't guarantee that the last write will be returned.

P - Partition Tolerance: This is the ability of the system to continue operating, even when there is a network partition. This pillar is a must have since node communications due to newtork failures can happen at any time, so we need to decide in which way we will bend to when having a partition.

How to act in a network partition

Since network partitions are inevitable in a distributed system, the theorem forces a crucial choice: when a partition happens, do you sacrifice Consistency or Availability? This leads to two main system design patterns.

CP - Consistency & Partition Tolerance

A CP system chooses to prioritize consistency over availability when a partition happens.

If a partition happens, a request to a partitioned node will be blocked or return an error until the network communication is restored and the data can be fully synchronized between the nodes. This ensures that no client ever sees an outdated data and this behavior is chosen in banking systems, financial ledgers, e-commerce inventory management.

AP - Availability & Partition Tolerance

An AP system chooses to prioritize availability over consistency when a partition happens.

Even if nodes can't communicate with each other, every client request will still get a response. This response, however, might contain outdated data since the node handling the request may not have received the latest write from another part of the system. These systems often aim for eventual consistency, where the data across all nodes will be synchronized once the partition is resolved.

This is ideal for systems where uptime and responsiveness are more important than having perfectly up-to-date data at all times, for example social media feeds, content delivery networks (CDNs), and databases like Amazon's DynamoDB or Cassandra, which are designed for high availability. MongoDB can also be configured for AP by allowing reads from secondary nodes when the primary is unavailable.

Conclusion

I hope you enjoyed the quick read and if you have something to add to this topic please leave a comment!

Streams and memory usage

Igor Grieder — Thu, 04 Sep 2025 00:57:15 +0000

I'm writing this short article because recently I came across a big problem that we sometimes make: using a lot of memory.

To give more context, I was investigating why an Azure Function was constantly restarting the k8s pod in production, causing a massive delay in the processing of some key financial data for the application users. After seeing the logs I saw that the process was being killed because of memory usage, exiting with code 137 Out Of Memory (OOM), with a lot of memory spikes before exiting.

There was a significant inefficiency in the file-producing function. It created an Excel sheet, wrote it's content to a MemoryStream, and then, instead of using the stream directly to upload the content, it was converted to a byte array. This entire byte array was then passed to some functions and then in the upstream layer, to load into the blob, it created another memoryStream based on the data and just after that the file was uploaded. This is a major flaw that unnecessarily consumes memory and processing power.

Now imagine, if just an small amount of files, let's say 10 files of 10mb were being processed in parallel, this implementation would cause an overhead of 200mb of program memory usage and would stress the GC.

Bad code choice

var someMemoryStream = new MemoryStream();
var worbook = new XSSFWorkbook();

// After fiiling the workbook

workbook.Write(someMemoryStream);
byte[] data = someMemoryStream.ToArray()

///... after some lines of code in other layers

// A MemoryStream is created from the original data
await using (var otherMemoryStream = new MemoryStream(data))
{           
    await blobClient.UploadAsync(otherMemoryStream);
}

To fix this not optimal implementation my solution was simple, I was going to handle the data transfer using a blob storage Stream directly!

var worbook = new XSSFWorkbook();

// After filling the workbook just write it to the opened stream
await using (var blobStream = await blobClient.OpenWriteAsync(true))
{
    workbook.Write(blobStream);
}

What's a Stream

A Stream is an abstraction for processing loads of data in batches, instead of loading all the bytes into memory at once.

To understand how it actually works we can think about the following situation. Imagine we are in a restaurant sitting in a table with 20 people and we all asked to drink coke cola. The waiter or waitress can deliver all of those cans at once but it would be very hard, since it's tray fits only 5 cans at a time (this would be our memory limitations in the environment). So the waitress decides to serve the table 4 times, given it would be better in this situation, even thought he or she would have more effort going back and forth (this would represent our flushing process in each stream read batch).

Streams in programming are widelly used an we can see how efficient they are in a simple example, such as the one I gave in this article or even in the foundations of the Event Driven Paradigm, being present in the heart of Kafka for example.

Linkup to the problem

This metaphor actually explains in a simple way what my implementation was doing. I had a big excel file produced and instead of using an MemoryStream and then transforming it into an array of bytes I just created a write blob stream and wrote my data directly into it. This simple change eliminated my memory problem and my Azure Function was operating fine after it.

Conclusion

Sometimes we tend not to think about memory when working in languages with a higher level of abstraction, but in controlled environments it is always crucial to understand what would happen when scale hits. If you have anything to comment or you would like to share ideas about the topic leave a comment below!

Adapters in Go

Igor Grieder — Sat, 03 May 2025 17:53:29 +0000

While studying the standard http module I came across a new concept of adapters that I had never encountered in another language until now. In this small article I will talk about this pattern and show a use case example of a rate limit.

Adapters

In Go we can use adapters in a clever way that lets us implement interfaces in functions. This allows functions to be treated as objects. We can see this being done for example by the HandleFunc of the http module that adapts any given function handler to act as an implementation of the Handler interface, needed by a server multiplexer e.g.

To satisfy an interface implementation a struct is not needed. In this situation, we can think of functions as objects to avoid declaring a complex or an empty struct to implement just one method.
This can be done because Go doesn't have a strict OOP structure, we can bind methods to types by just informing the receiver of a function (it has to be a local type, we can't define a method for a int32 type e.g).

func (receiver MyReceiverType) myFunction(){
  // ... something
}

In this case we bound myFunction declaration to the MyReceiverType. In this case we are passing the receiver as a copy, if we would like to change it we would need to pass a pointer to be de referenced.

HTTP Handler interface

// The handler interface
type Handler interface {
  ServeHTTP (ResponseWriter, *Request)
}

// HandlerFunc implementation
type HandlerFunc func (ResponseWriter, *Request)

func (f HandlerFunc) ServeHTTP (w ResponseWriter, r *Request) {
  f(w,r)
}

In this code we can see that the HandlerFunc type satisfies the Handler interface implementation and we can use this to use functions as HTTP handlers.

The hole ideia is that we are casting an anonymous function to a HandlerFunc type that has implemented the ServeHTTP method in it, meaning that the function will implement the Handler interface.

Rate Limit example

In this example we will have an struct API to track HTTP calls in a map (just an example). To safely write and read from the map I will be using a RWMutex, since each new http request is handled in a go routine we need this safety of shared state between them.

Struct and methods declaration

type apiConfig struct {
 rateLimit map[string]int
 mux       *sync.RWMutex
}

// Method to wrap an example response
func (api apiConfig) SendResponse(w http.ResponseWriter, req *http.Request) {
 message := "API Call"
 w.Write([]byte(message))
}

// Rate limit middleware
func (api *apiConfig) middlewareHandlerFunc() http.Handler {
 return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
  ip, _, err := net.SplitHostPort(req.RemoteAddr)

  if err != nil {
   // error handling
  }

  api.mux.RLock()
  n := api.rateLimit[ip]
  fmt.Printf("IP %s has reached to the API %d times\n", ip, n)
  api.mux.RUnlock()

  switch {
  case n == 0:
   api.mux.Lock()
   api.rateLimit[ip] = 1
   api.mux.Unlock()
   api.SendResponse(w, req)
   return // We don't actually need an return because of the way the http module handles responses but I consider it a good practice

  case n > 10:
   http.Error(w, "Rate limit reached", http.StatusTooManyRequests)
   return

  default: // 1 ≤ count ≤ 10
   api.mux.Lock()
   api.rateLimit[ip] = n + 1
   api.mux.Unlock()
   api.SendResponse(w, req)
   return
  }
 })
}

In the middlewareHandlerFunc we just check if the request sender IP has reached our defined limit and if it has, we return an error message. RWMutex allows concurrent read access (RLock()) while ensuring exclusive write access (Lock()), improving performance under high read loads. In this example I could've used sync.map but I choose not to for learning reasons.

HTTP Server

In our http server we are using a Serve Multiplexer to address our routes and start a server. We can see that our adapter worked because we are using our middlewareHandlerFunc and attaching it's return to a mux.Handle, that expects a string and a http.Handler.

func main() {
 fmt.Println("Starting the server multiplexer")

 api := &apiConfig{
  rateLimit: make(map[string]int),
  mux:       &sync.RWMutex{},
 }

 mux := http.NewServeMux()

 mux.Handle("/", api.middlewareHandlerFunc())

 svr := &http.Server{Addr: ":8080", Handler: mux}
 err := svr.ListenAndServe()

 if err != nil {
  fmt.Println(err)
  os.Exit(1)
 }
}

Complete code

package main

import (
 "fmt"
 "net"
 "net/http"
 "os"
 "sync"
)

type apiConfig struct {
 rateLimit map[string]int
 mux       *sync.RWMutex
}

func (api apiConfig) SendResponse(w http.ResponseWriter, req *http.Request) {
 message := "API Call"
 w.Write([]byte(message))
}

func (api *apiConfig) middlewareHandlerFunc() http.Handler {
 return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
  ip, _, err := net.SplitHostPort(req.RemoteAddr)

  if err != nil {
   // error handling
  }

  api.mux.RLock()
  n := api.rateLimit[ip]
  fmt.Printf("IP %s has reached to the API %d times\n", ip, n)
  api.mux.RUnlock()

  switch {
  case n == 0:
   api.mux.Lock()
   api.rateLimit[ip] = 1
   api.mux.Unlock()
   api.SendResponse(w, req)
   return

  case n >= 10:
   http.Error(w, "Rate limit reached", http.StatusTooManyRequests)
   return

  default: // 1 ≤ count ≤ 10
   api.mux.Lock()
   api.rateLimit[ip] = n + 1
   api.mux.Unlock()
   api.SendResponse(w, req)
   return
  }
 })
}

func main() {
 fmt.Println("Starting the server multiplexer")

 api := &apiConfig{
  rateLimit: make(map[string]int),
  mux:       &sync.RWMutex{},
 }

 mux := http.NewServeMux()

 mux.Handle("/", api.middlewareHandlerFunc())

 svr := &http.Server{Addr: ":8080", Handler: mux}
 err := svr.ListenAndServe()

 if err != nil {
  fmt.Println(err)
  os.Exit(1)
 }
}

Conclusion

I hope you've found the article useful for you and have learned something from it! Let me know your thoughts!

Module imports in node.js

Igor Grieder — Sun, 30 Mar 2025 20:12:50 +0000

Imports in general are one of the most basic programming language features. Most of the languages support it for us to follow the DRY (don't repeat yourself) principle.

Particularly in developing web applications in node.js, we can sometimes make mistakes about simple imports, and that's going to be covered in this short article.

Understanding how imports work

First, node will hoist all imports on a file, regardless of they're position in the codebase, for all files, following the import flow. It's called the parsing phase.
After that it will have built a dependency graph and will execute the code in the order it was defined. The graph is not necessarily the order of the imports of the files.

Circular dependency

Because of import hoisting we can come across the circular dependencies
problem. This often happens when we try to access a exported module declared in a module that depends on the main module. I know that sounded a little bit hard to
understand, but I will clear this out.

In this example index.js exports a database connection URL to be used in the
db.js file and the main module itself utilizes the database connection
established in the db.js file. This clearly creates a circular dependency flow between
them and this causes an error of use before initialization of DBURL variable.

Solution

In this case the solution is very clear, we could just initialize the DBURL
variable inside of our centralized database module, and that's the reason we
often centralize some specific cores of our applications in dedicated
configuration files. This example was just purely designed for a simple explanation.

Config files

Configuration files are the main solution for this module importing confusion.
A most appropriate example of a config file usage would be the following one.

In this example, an AWS S3 connection is being established and it will be used by
our main module index.js and inside a get request route.js. In this setup we'll have the same problem from the previous example.

Main module

// index.js
import someRoute from "./route.js"

export const s3client = new S3Client({
  region: "s3 region",
  credentials: {
    accessKeyId: process.env.ACCESS_KEY,
    secretAccessKey: process.env.SECRET_ACCESS_KEY
  }
});

// express http server setup...

Route module

// route.js
import s3client from "./index.js"
import { Router } from "express";

const router = new Router();
router.get("get-URL", async (req, res) => {
  const foo = await s3client.bar;
  return res.status(code)
});

export default router;

Quick fix

We could just have started the S3 connection in a configuration file and import it
when the module is required for some operation, solving our problem.

// s3.js
export const s3client = new S3Client({
  region: "s3 region",
  credentials: {
    accessKeyId: process.env.ACCESS_KEY,
    secretAccessKey: process.env.SECRET_ACCESS_KEY
  }
});

Conclusion

This was a quick article about imports and the circular dependency loop that we can
come across while working with modules in node.js. Hope you find it use full!

node.js core concepts

Igor Grieder — Wed, 05 Mar 2025 15:58:59 +0000

In this article, I will discuss some Node.js fundamentals that every
beginner needs to know to improve the code quality of a Node-based web
application.

node.js main components

Core JavaScript API: Responsible for the high-level implementation.
V8 Engine: Responsible for interpreting JavaScript code and executing the program. It's written in C/C++ and implements the core functionality of JavaScript.
libuv: A library written in C/C++ responsible for event manipulation, asynchronous processing with functions and timers, implementing the Event Loop, and managing thread pools. It also handles high-demand CPU code execution. It's a crucial module in Node.js as it provides access to the operating system.

Threads and processes

A fundamental concept to properly understand how Node.js works is the distinction between a thread and a process, as they are used by computers to execute instructions.

Process/Task

In simple terms, a process is a set of program instructions to be executed. A computer executes many processes simultaneously, which can be considered tasks that the operating system runs periodically, such as antivirus programs. Each process has its
own memory space and does not share memory with other processes.

Thread

A thread is the smallest processing unit of a program and represents how the instruction set is divided and scheduled for execution. A process is composed of threads that share memory for efficient execution of different instructions.

Is Node single threaded?

Node.js is considered single-threaded because its main component for execution, the Event Loop, relies on only one thread for execution, called the main thread.
However, it's important to note that libuv has, by default, 4 threads that can be used for high-demand CPU processing, allowing Node.js to act as a multi-threaded runtime in certain scenarios.

Event Loop

Before introducing about the event loop we need to gather some extra concepts, Call Stack and the Callback/Task Queue.

Call Stack

This is a component present in many programming languages for keeping track of the program execution and it's function calls in a Stack data structure. It's functioning can be explained as LIFO (Last in first out).
It's important to know that callbacks in Node are just executed if the Call Stack is empty, without executing a particular function at the time.

Callback/Task Queue

Its job is to storage, in a queue, all the callbacks to be executed by the program. The execution of the queue's tasks will only start when the Call Stack is free.
Since a queue is a FIFO (First in first out) data structure the callbacks will be executed in insertion order.

Understanding the Event Loop

The Event Loop is fundamental for the node.js runtime since it makes possible
for the non-blocking I/0 structure of the language to work. It's responsible for
making node application really good with reading files, processing http requests
and querying databases.

Event Loop Phases

We can devide the Event Loop in some phases of execution:

Timers Phase: Executes callbacks scheduled by setTimeout() and setInterval().
Pending Callbacks Phase: Processes I/O callbacks that were deferred to the next loop iteration.
Poll Phase: Retrieves new I/O events and executes their callbacks. If no callbacks are scheduled, it waits for new events.
Check Phase: Executes callbacks scheduled by setImmediate().
Close Callbacks Phase: Handles close events, like when a socket or handle is closed.

The loop repeats these phases as long as there are tasks in the Call Stack
to be executed.

Non-blocking I/0

I/O represents any system interaction with the disk (file manipulation, database
querying) or with the network (HTTP requests). When writing JavaScript code, we
can have blocking and non-blocking calls. By understanding how the
Event Loop works, we can write code that won't block it.

Blocking calls

We say we have a blocking call when a non JavaScript node.js code is being
executed and it will not allow any other process to be executed until it finishes.
This behavior pauses the execution of the Event Loop since it can't continue
to execute any process.

Note: High intense CPU performance process aren't considered blocking calls

Example from the node.js Documentation

const fs = require('node:fs');

const data = fs.readFileSync('/file.md'); // blocks here until file is read
console.log(data);
moreWork(); // will run after console.log

In this example we have a blocking operation that will prevent the Event Loop
from executing callbacks.

const fs = require('node:fs');

fs.readFile('/file.md', (err, data) => {
  if (err) throw err;
  console.log(data);
});
moreWork(); // will run before console.log

In this example the Event Loop will not be blocked and we will depend on the
resolution of the async operation to have the data displayed.

Async/await is a blocking operation?

Async/await is a sintax sugar built on top of promisses and those operations do
not block the Event Loop. While waiting for the promise to be resolved the
Event Loop continues it's execution to execute callbacks and receive another
I/O operations.

Example of async/await

async function fetchData() {
  console.log("Fetching data...");
  const response = await fetch("https://api.example.com/data"); // Pauses here
  const data = await response.json();
  console.log("Data received:", data);
}

console.log("Start");
fetchData(); // This runs asynchronously
console.log("End");

The execution of this program would return

Start
Fetching data...
End
Data received: { ... }

This happens because when a Promise is returned by the fetch method it will stop
the execution of the function until it resolves the promise, but because the
Event Loop isn't blocked, it will continue to executed the code normally. When the promise is resolved it will schedule to continue the function
execution as a second priority before changing an Event Loop Phase.
Every cycle, before starting a new step of the Event Loop, it will be checked if any promisses got resolved, successfully or not.

Really understanding this behavior is key for developing JavaScript node.js code
without any unexpected behavior.

Conclusion

In this article, we covered many core concepts of Node.js that
beginners often overlook at the start of their journey. However, understanding
these concepts is crucial for writing efficient and scalable applications.
Feel free to leave any observations or questions in the comments section below!

DEV Community: Igor Grieder

Agentic Git Workflow

Trunk-Based Development for Fast, Safe AI-Assisted Shipping

What Trunk-Based Development Really Means

A Simple, Repeatable TBD Workflow

Go Example: Feature Flag in a Handler

Git Worktrees: AI Safe Isolation

Bash Helper: Worktree Workflow

Final Takeaways

Idempotency

What is Idempotency?

Why Systems Fail Without Idempotency

Idempotency Keys

Implementation Workflow

Client Side

Server Side in Go

Strategic Implementation Best Practices

Persistence Layer Choice

Deterministic Responses

Scope of the Key

The Read-Modify-Write problem

Conclusion

Error handling in Go

Types

Opaque Errors

Sentinel errors

Custom Errors

Wrapping Errors

Conclusion

Locks

Pessimistic Locking

Optimistic Locking

Conclusion

Fault Tolerance

When failures can happen

Application-Level Failure Handling

Idempotency

Timeout

Retries (Exponential Backoff + Jitter)

Circuit Breaker

Conclusion

Links

Cache

Caching in Web Development

Consistency

Invalidation

Cache hit and Cache miss

Cache-Aside pattern

Write-Through pattern

Write-Behind pattern

Conclusion

Dual Write and the Transactional Outbox Pattern

Introduction to the Dual Write problem

Transactional Outbox Pattern

Code example

Conclusion

CAP Theorem

Distributive System

What's CAP Theorem?

Importance

The Three Pillars Explained

How to act in a network partition

CP - Consistency & Partition Tolerance

AP - Availability & Partition Tolerance

Conclusion

Streams and memory usage

Bad code choice

What's a Stream

Linkup to the problem

Conclusion

Adapters in Go

Adapters

HTTP Handler interface

Rate Limit example

Struct and methods declaration

HTTP Server

Complete code

Conclusion

Module imports in node.js

Understanding how imports work