Building a Transport Protocol on Top of UDP

This article explains the core networking concepts that make a reliable transport protocol work, using AeroUDP as a concrete reference implementation. AeroUDP is a reliable, ordered, congestion-controlled transport protocol layered on top of unreliable UDP, essentially a stripped-down hybrid of TCP and QUIC written in idiomatic asynchronous Rust.

> Source code: https://github.com/Mo7ammedd/AeroUDP

---

Why Build a Protocol on Top of UDP?

The Transport Layer

The transport layer sits between the raw network (IP) and your application. It is responsible for turning a best-effort packet delivery service into something programs can actually rely on. The two classic choices are TCP and UDP.

• Reliable, ordered, connection-oriented byte stream
• Built-in congestion and flow control
• Implemented in the kernel, hard to modify or experiment with

• Unreliable, unordered, connectionless datagrams
• No congestion control, no retransmission, no ordering
• A thin wrapper over IP, fast, minimal, and fully programmable in user space

The Middle Ground

Modern protocols like QUIC (which powers HTTP/3) are built on top of UDP in user space, re-implementing reliability and congestion control where they can evolve quickly without kernel changes.

AeroUDP takes the same approach for educational and experimental purposes. It uses UDP as a dumb packet pipe and rebuilds the guarantees people expect from TCP:

• Reliable, in-order, bidirectional delivery
• Detection and recovery from loss, duplication, reordering, and corruption
• Sliding-window flow control
• NewReno-style congestion control
• RTT-driven adaptive timeouts
• A full connection lifecycle (handshake, graceful close, reset, keepalive)

Packets and the Wire Format

What is a Packet Header?

Before any bytes travel across a network, they must be wrapped in a header, a fixed structure of metadata that tells the receiver how to interpret the payload. The header answers questions like: Which connection is this? What sequence number? What is being acknowledged? How much buffer space is available?

AeroUDP Header

Every AeroUDP datagram is exactly one UDP payload carrying one packet with a 28-byte header:

`` +---------------+---------------+---------------+---------------+ | magic=0xAE | version=1 | packet_type | flags | +---------------+---------------+---------------+---------------+ | conn_id (u32) | | seq_num (u32) | | ack_num (u32) | | window (u32) | | payload_len (u16) | reserved (u16) | | checksum (u32, CRC32 over header + payload) | | payload ... | +---------------------------------------------------------------+ `

Later receives: 6, 7 (still missing 5, out of order) ack_num stays: 5 (cannot advance past the gap) `

• Every DATA packet is stored in an in-flight queue, keyed by sequence number.
• A cumulative ACK evicts everything strictly below ack_num, those packets are confirmed delivered.
• If a packet is not acknowledged in time, it is resent (with a RETX flag set for observability).

RTO = clamp(SRTT + 4 * RTTVAR, min_rto, max_rto) `

When an RTO fires (a real timeout), AeroUDP doubles the RTO (RTO *= 2) before retrying. This is exponential backoff, it prevents a sender from hammering an already-congested or broken network. On the next fresh RTT sample, the backoff resets.

As the application reads and drains the buffer, the window grows. As the buffer fills, the window shrinks toward zero. window = 0 → sender pauses entirely until space frees up. `

AeroUDP currently clamps the advertised receive window to at least one packet. An advertised zero therefore still permits a one-packet effective window; complete zero-window backpressure remains a limitation. The peer_window used below is this effective window.

• Start with a small cwnd (default: 10 packets).
• For every ACK that advances the cumulative ACK, grow cwnd by the number of segments acknowledged.
• This doubles cwnd roughly every RTT, exponential growth.
• Exit when cwnd >= ssthresh (the slow-start threshold).

• Once cwnd >= ssthresh, switch to cautious linear growth.
• cwnd grows by roughly 1 packet per RTT (additive increase).

• Immediately retransmit the missing segment, do not wait for the RTO.
• ssthresh = max(cwnd / 2, 2)
• cwnd = ssthresh (halve, don't reset)
• Enter fast recovery; exit when a new cumulative ACK passes the recovery point.

• ssthresh = max(cwnd / 2, 2)
• cwnd = 1, collapse the window
• Return to slow start

The handshake itself uses the same retransmission-with-backoff machinery, capped by handshake_timeout (5 s) and max_retries.

If something goes catastrophically wrong, either side sends a RST (reset). The receiver immediately transitions to CLOSED and surfaces a PeerReset event, no graceful exchange, just an abrupt teardown.

• If nothing is received for keepalive_interval (15 s), send a PING.
• The peer replies with PONG.
• After keepalive_probes (3) unanswered probes, declare the peer dead and close.

A protocol you cannot measure is a protocol you cannot debug or tune. AeroUDP exposes a ConnectionMetrics snapshot backed by atomic counters:

A single send() call in AeroUDP quietly exercises every concept in this article:

• The payload is wrapped in a 28-byte header with a sequence number and CRC32 checksum.
• The sender checks flow control (peer window) and congestion control (cwnd), it only transmits if in_flight < min(cwnd, peer_window)`.
• The packet is stored in the retransmission queue and sent over UDP.
• If it arrives cleanly, the receiver buffers or delivers in order and returns a cumulative ACK, advancing its window.
• The ACK confirms the packet, updates the RTT/RTO estimate, and grows cwnd (slow start or congestion avoidance).
• If it is lost, either three duplicate ACKs (fast retransmit) or an RTO timeout triggers retransmission and shrinks cwnd.

---

Further Reading

• Standards:

• Books:

• Source Code:

Author: Mohammed Mostafa
Published: July 1, 2026
Reading Time: 14 min read
Tags: networking, transport-protocols, congestion-control, udp, tcp, rust
Read on modev.me →

Pagination Strategies: OFFSET vs Cursor Pagination

Pagination is one of the most deceptively simple problems in backend engineering. Every application that lists data needs it. Yet the choice between offset-based and cursor-based pagination carries enormous implications for query performance, data consistency, scalability, and API design: implications that only become visible under production load.

This post tears into both strategies at the database internals level. We'll look at how each approach interacts with B-tree indexes, what query plans they produce, where their O-complexity comes from, and how to implement each one correctly.

What Is Pagination, Really?

Before diving into strategies, let's be precise. Pagination is the technique of breaking a large result set into smaller, sequential chunks called pages. The database still holds the full dataset; the client receives one slice at a time.

The core challenge: how do you tell the database where to start returning rows for any given page?

That single question leads to two fundamentally different answers.

Strategy 1: OFFSET Pagination

The Mechanics

OFFSET pagination works by telling the database: "skip the first N rows and give me the next M."

``sql title="offset-pagination.sql" {5,11,17} showLineNumbers -- Page 1: skip 0, take 10 SELECT id, title, created_at FROM posts ORDER BY created_at DESC LIMIT 10 OFFSET 0;

-- Page 51: skip 500, take 10 SELECT id, title, created_at FROM posts ORDER BY created_at DESC LIMIT 10 OFFSET 500; `

Page number translates directly to OFFSET = (page - 1) * pageSize. Clean. Predictable.

When PostgreSQL processes LIMIT 10 OFFSET 500, it:

• Evaluates the full WHERE clause to find candidate rows
• Sorts those rows by ORDER BY created_at DESC
• Reads rows 1 through 510 in order
• Discards rows 1 through 500
• Returns rows 501 through 510

EXPLAIN (ANALYZE, BUFFERS)
SELECT id, title, created_at
FROM posts
ORDER BY created_at DESC
LIMIT 10 OFFSET 500000;

-- Subsequent pages (cursor = last row from previous page) SELECT id, title, created_at FROM posts WHERE (created_at, id) < ('2026-03-10 14:23:00', 5892) ORDER BY created_at DESC, id DESC LIMIT 10; `

The WHERE clause anchors the query to a specific position in the index. The database doesn't skip anything: it seeks directly to the cursor position and reads forward.

Read the next LIMIT rows from that position: O(limit).

For a table with 10M rows, log₂(10,000,000) ≈ 23. Regardless of which "page" you're on: page 1 or page 1,000,000: cursor pagination only traverses ~23 tree levels to find the starting position. The complexity is O(log n + limit), effectively constant relative to dataset size.

Simple cursors based on a single monotonically increasing integer ID work perfectly. Real world queries are messier. What if you're ordering by created_at, which is not unique?

-- WRONG: created_at is not unique: ties cause missed rows
WHERE created_at < '2026-03-10 14:23:00'
ORDER BY created_at DESC
LIMIT 10;

If multiple rows share the same created_at timestamp (common with bulk inserts), rows at the boundary can be skipped. Use a composite cursor that includes a unique tiebreaker, typically the primary key, in both the filter and the sort order.

-- CORRECT: composite cursor with tiebreaker
WHERE (created_at, id) < ('2026-03-10 14:23:00', 5892)
ORDER BY created_at DESC, id DESC
LIMIT 10;

This requires a composite index on (created_at DESC, id DESC):

CREATE INDEX idx_posts_cursor ON posts (created_at DESC, id DESC);

Always create a composite index that exactly matches your cursor columns and sort direction. PostgreSQL can use an index scan backward if the index is in ascending order and your query is DESC, but an explicit DESC index avoids ambiguity and is often faster in practice.

// Encoding a cursor
interface CursorPayload {
  created_at: string
  id: number
}
function encodeCursor(payload: CursorPayload): string {
  return Buffer.from(JSON.stringify(payload)).toString('base64url')
}
// Decoding a cursor
function decodeCursor(token: string): CursorPayload {
  try {
    return JSON.parse(Buffer.from(token, 'base64url').toString('utf-8'))
  } catch {
    throw new Error('Invalid pagination cursor')
  }
}

Using base64url (URL-safe base64) avoids the need to URL-encode the token when passing it as a query parameter.

interface Post {
  id: number
  title: string
  created_at: Date
}
interface PaginatedResult {
  data: T[]
  next_cursor: string | null
  has_more: boolean
}
interface CursorPayload {
  created_at: string
  id: number
}
function encodeCursor(payload: CursorPayload): string {
  return Buffer.from(JSON.stringify(payload)).toString('base64url')
}
function decodeCursor(token: string): CursorPayload {
  try {
    const decoded = JSON.parse(Buffer.from(token, 'base64url').toString('utf-8'))
    if (!decoded.created_at || typeof decoded.id !== 'number') {
      throw new Error('Invalid cursor shape')
    }
    return decoded
  } catch {
    throw new Error('Malformed pagination cursor')
  }
}
async function getPosts(
  pool: Pool,
  limit: number = 10,
  cursor?: string
): Promise> {
  // Request one extra row to determine if there is a next page
  const pageSize = limit + 1
let rows: Post[]
if (!cursor) {
    // First page: no cursor condition
    const result = await pool.query(
      SELECT id, title, created_at
       FROM posts
       ORDER BY created_at DESC, id DESC
       LIMIT $1,
      [pageSize]
    )
    rows = result.rows
  } else {
    const { created_at, id } = decodeCursor(cursor)

// Subsequent pages: use composite cursor
    const result = await pool.query(
      SELECT id, title, created_at
       FROM posts
       WHERE (created_at, id) < ($1::timestamptz, $2)
       ORDER BY created_at DESC, id DESC
       LIMIT $3,
      [created_at, id, pageSize]
    )
    rows = result.rows
  }

const has_more = rows.length > limit
  const data = has_more ? rows.slice(0, limit) : rows
const last = data[data.length - 1]
  const next_cursor =
    has_more && last
      ? encodeCursor({
          created_at: last.created_at.toISOString(),
          id: last.id,
        })
      : null
return { data, next_cursor, has_more }
}

The "fetch limit + 1" trick is the standard way to determine has_more without running a separate COUNT(*) query.

interface BidirectionalResult {
  data: T[]
  page_info: {
    start_cursor: string | null
    end_cursor: string | null
    has_next_page: boolean
    has_previous_page: boolean
  }
}

To paginate backward (before cursor):

-- Get the previous page: rows just before the start cursor
-- Wrap in a subquery to re-sort after reversing
SELECT * FROM (
  SELECT id, title, created_at
  FROM posts
  WHERE (created_at, id) > ($1::timestamptz, $2)   -- reversed comparison
  ORDER BY created_at ASC, id ASC                   -- reversed sort
  LIMIT $3
) sub
ORDER BY created_at DESC, id DESC;                  -- re-sort for display

PostgreSQL's planner is excellent at recognising cursor patterns. A composite WHERE (a, b) < ($1, $2) is properly decomposed into range conditions the planner can use with a composite index:

-- PostgreSQL rewrites this:
WHERE (created_at, id) < ('2026-03-10', 5892)
-- Into the equivalent:
WHERE created_at < '2026-03-10'
   OR (created_at = '2026-03-10' AND id < 5892)

This rewrite uses the index correctly. Verify with EXPLAIN:

EXPLAIN (ANALYZE, BUFFERS)
SELECT id, title, created_at
FROM posts
WHERE (created_at, id) < ('2026-03-10 14:23:00'::timestamptz, 5892)
ORDER BY created_at DESC, id DESC
LIMIT 10;

MySQL handles row value expressions less elegantly. The (a, b) < ($1, $2) syntax is supported but the optimizer does not always use it efficiently. The explicit expansion is safer:

-- Explicit expansion: more reliable in MySQL
SELECT id, title, created_at
FROM posts
WHERE created_at < '2026-03-10 14:23:00'
   OR (created_at = '2026-03-10 14:23:00' AND id < 5892)
ORDER BY created_at DESC, id DESC
LIMIT 10;

Ensure the composite index exists: CREATE INDEX idx_posts_cursor ON posts (created_at DESC, id DESC);

SQL Server supports row value expressions with (a, b) < ($1, $2) syntax and uses it correctly with covering indexes. Additionally, SQL Server's FETCH NEXT ... ROWS ONLY syntax (standard OFFSET-FETCH) has the same performance characteristics as LIMIT ... OFFSET.

When a cursor-paginated query runs, the WHERE condition (created_at, id) < (cursor_value) is deterministic and set-based. Rows that have been inserted or deleted since the first page was fetched affect only the pages where they would logically appear. Rows the user has already seen remain unchanged. Rows ahead of the cursor are fetched as they exist at query time.

type SortField = 'created_at' | 'likes' | 'comments'
type SortDirection = 'asc' | 'desc'
interface CursorPayload {
  sort_field: SortField
  sort_direction: SortDirection
  sort_value: string | number
  id: number             // tiebreaker always included
}

Validate that the cursor's sort_field and sort_direction match the current request. Reject stale cursors with a 400 Bad Request.

If your cursor column can contain NULLs, comparison semantics break down. SQL's three-valued logic means NULL < 5 is NULL (neither true nor false), not true. You have two options:

• Exclude NULLs from the result set if possible (WHERE sort_column IS NOT NULL)
• Use COALESCE to give NULLs a sentinel value that sorts consistently

-- Option 2: treat NULL as the minimum value (sorts last in DESC)
WHERE (COALESCE(score, -1), id) < ($1, $2)
ORDER BY COALESCE(score, -1) DESC, id DESC

When pagination is combined with filtering (e.g., WHERE status = 'published'), the cursor must respect the filter:

SELECT id, title, created_at
FROM posts
WHERE status = 'published'
  AND (created_at, id) < ($1::timestamptz, $2)
ORDER BY created_at DESC, id DESC
LIMIT 10;

-- Partial index for published posts only
CREATE INDEX idx_posts_published_cursor
ON posts (created_at DESC, id DESC)
WHERE status = 'published';

query GetPosts($first: Int, $after: String) {
  posts(first: $first, after: $after) {
    edges {
      cursor
      node {
        id
        title
        createdAt
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
  }
}

• first / after for forward pagination (equivalent to our limit / cursor)
• last / before for backward pagination
• Each edge contains the item (node) and its cursor
• pageInfo exposes cursors for the current page boundary

// Relay-compatible resolver (simplified)
async function postsConnection(
  args: { first?: number; after?: string; last?: number; before?: string }
) {
  if (args.first !== undefined) {
    return forwardPaginate(args.first, args.after)
  }
  if (args.last !== undefined) {
    return backwardPaginate(args.last, args.before)
  }
  throw new Error('Must provide first or last')
}

GET /api/posts?limit=10

{
  "data": [
    { "id": 2051, "title": "Latest post", "created_at": "2026-03-13T09:00:00Z" },
    ...
  ],
  "pagination": {
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMy0xMFQxNDoyMzowMFoiLCJpZCI6NTg5Mn0",
    "has_more": true,
    "limit": 10
  }
}

GET /api/posts?limit=10&cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wMy0xMFQxNDoyMzowMFoiLCJpZCI6NTg5Mn0

• cursor is always optional on the first request
• next_cursor is null when there are no more pages
• Never expose raw database values in the cursor (always encode)
• Validate cursor structure on decode; return 400 for invalid cursors
• Consider cursor expiry for very large datasets (cursors pointing to deleted rows)

WHERE sort_key > :last_seen_value
ORDER BY sort_key ASC
LIMIT :n

is keyset pagination. The "cursor" is just the encoded last_seen_value. This works for any sortable, indexed column: integer IDs, timestamps, UUIDs (with ordered UUID strategies like UUIDv7), composite keys, and more.

-- UUIDv7 cursor: no tiebreaker needed because UUIDs are globally unique
SELECT id, title, created_at
FROM posts
WHERE id > $1::uuid
ORDER BY id ASC
LIMIT 10;

The reproducible check is scripts/verify-blog/pagination.sql` in the portfolio repository. It verifies query results and page boundaries; the interactive model above illustrates index entry counts under its stated assumptions.

Author: Mohammed Mostafa
Published: March 13, 2026
Reading Time: 19 min read
Tags: database, pagination, performance, sql, backend, postgresql
Read on modev.me →

Nginx: From Request Flow to Production Deployment

Introduction

Nginx is one of the most widely used web servers and reverse proxies in production systems. It powers high-traffic websites, APIs, microservices platforms, and edge gateways worldwide. Companies like Netflix, Dropbox, and WordPress.com rely on Nginx to handle millions of concurrent connections.

Unlike traditional process-based servers (Apache with prefork MPM), Nginx is built around an event-driven, non-blocking architecture. This fundamental design difference allows it to handle tens of thousands of concurrent connections with predictable resource usage and minimal memory footprint.

Nginx is commonly deployed for:

• Serving static content - HTML, CSS, JavaScript, images with sendfile() optimization
• Reverse proxy - Abstracting backend services behind a unified interface
• Load balancing - Distributing traffic across multiple backend servers
• TLS termination - Offloading SSL/TLS encryption from application servers
• API gateways - Request routing, authentication, rate limiting
• Zero-downtime deployments - Graceful configuration reloads without dropping connections
• Security filtering - DDoS protection, request validation, WAF integration

---

Nginx Architecture: The Master-Worker Model

!Nginx Architecture Overview

Nginx uses a master-worker process model that differs fundamentally from traditional web servers like Apache's prefork MPM.

Master Process Responsibilities

The master process runs as root (or with CAP_NET_BIND_SERVICE on Linux) and performs privileged operations:

• Configuration management - Reads, parses, and validates nginx.conf
• Port binding - Binds to privileged ports (80, 443) before dropping privileges
• Worker lifecycle - Spawns, monitors, and restarts worker processes
• Signal handling - Processes SIGHUP (reload), SIGTERM (shutdown), SIGUSR1 (log rotation)
• Graceful operations - Coordinates zero-downtime configuration reloads
• Binary upgrades - Enables hot-swapping Nginx binary without downtime

Worker Process Design

Worker processes run as unprivileged users (typically nginx or www-data) and handle all client traffic:

worker_processes auto;  # One per CPU core
worker_cpu_affinity auto;  # Pin workers to specific CPUs

Each worker operates independently with:

• Event loop - Uses epoll (Linux), kqueue (FreeBSD), or event ports (Solaris)
• Non-blocking I/O - All socket operations are async
• Connection pooling - Reuses connections to upstream servers
• Memory management - Per-worker memory pools for efficient allocation

Why This Architecture Matters

Traditional process-per-connection models (Apache prefork) consume resources linearly:

• 10,000 connections = 10,000 processes = GBs of memory
• Context switching overhead increases with connection count
• Resource limits become bottlenecks (file descriptors, memory)

• 10,000 connections = 4-8 worker processes = hundreds of MBs
• No context switching between connections
• Predictable memory usage regardless of connection count

---

Event-Driven Architecture Deep Dive

Nginx workers use an event loop similar to Node.js, but implemented in C for maximum performance.

The Event Loop

Each worker runs a continuous loop:

while (true) {
    // Wait for events (readable sockets, timers, signals)
    events = epoll_wait(epfd, max_events, timeout);
    
    // Process each event without blocking
    for (event in events) {
        if (event.type == READ) {
            read_request_nonblocking(event.socket);
        } else if (event.type == WRITE) {
            write_response_nonblocking(event.socket);
        } else if (event.type == TIMER) {
            handle_timeout(event.connection);
        }
    }
    
    // Process deferred handlers
    process_posted_events();
}

Non-Blocking I/O Implementation

All socket operations use O_NONBLOCK flag:

• accept() returns immediately with EAGAIN if no connections pending
• read() returns partial data or EAGAIN without blocking
• write() returns bytes written or EAGAIN if socket buffer full

• Register interest with epoll/kqueue
• Return to event loop
• Resume when socket becomes ready

---

Request Processing Pipeline

!Nginx Request Lifecycle

Understanding Nginx's request processing phases is crucial for correct configuration.

Processing Phases (in order)

• POST_READ - Request headers just read
• SERVER_REWRITE - Server-level rewrites (before location matching)
• FIND_CONFIG - Location block selection
• REWRITE - Location-level rewrites
• POST_REWRITE - Check if URI changed (may restart from FIND_CONFIG)
• PREACCESS - Modules that run before access check (limit_req, limit_conn)
• ACCESS - Access control (allow, deny, auth_basic)
• POST_ACCESS - Check access results
• PRECONTENT - try_files directive runs here
• CONTENT - Generate response (proxy_pass, fastcgi_pass, return, etc.)
• LOG - Write access logs

Phase Execution Rules

• Phases run sequentially, but some can be skipped
• Multiple handlers can register for a phase
• A handler can short-circuit the pipeline (e.g., return 403)
• Location rewrites can restart the pipeline from FIND_CONFIG

Example Request Flow

server {
    listen 80;
    server_name api.example.com;
    
    # SERVER_REWRITE phase
    rewrite ^/v1/(.*)$ /api/v1/$1 last;
    
    location /api/ {
        # REWRITE phase
        rewrite ^/api/v1/users$ /api/v1/users/ permanent;
        
        # PREACCESS phase
        limit_req zone=api burst=20;
        
        # ACCESS phase
        allow 10.0.0.0/8;
        deny all;
        
        # CONTENT phase
        proxy_pass http://backend;
    }
}

• SERVER_REWRITE: URI becomes /api/v1/users
• FIND_CONFIG: Matches /api/ location
• REWRITE: URI becomes /api/v1/users/ (301 redirect sent)
• Pipeline stops, response returned

Configuration File Structure and Inheritance

Nginx configuration uses a hierarchical, context-based structure with specific inheritance rules.

Context Hierarchy

main          # Global directives
├── events    # Connection processing settings
└── http      # HTTP server settings
    ├── upstream    # Backend server groups
    ├── server      # Virtual host
    │   └── location    # URI-specific rules
    │       └── if      # Conditional logic (use sparingly)
    └── map     # Variable mappings

Directive Context Rules

Each directive is only valid in specific contexts:

• worker_processes - main only
• listen - server only
• proxy_pass - location, if in location
• root - http, server, location, if in location

Inheritance Behavior

Child contexts inherit from parents but can override:

http {
    client_max_body_size 10m;  # Default for all servers
    
    server {
        # Inherits 10m
        
        location /upload {
            client_max_body_size 100m;  # Override for this location
        }
    }
}

---

Location Matching: The Most Critical Concept

Location matching determines which block handles a request. Getting this wrong causes 90% of Nginx misconfigurations.

Match Types (in priority order)

• Exact match = /path
• Preferential prefix ^~ /path
• Regex (case-sensitive) ~ pattern
• Regex (case-insensitive) ~* pattern
• Longest prefix /path

Matching Algorithm

``

• Check for exact match (=)

location /api/ { proxy_pass http://api; }      # Prefix
location ~ \.php$ { fastcgi_pass php; }        # Regex

Request /api/test.php hits the PHP location, not /api/!

location ^~ /api/ { proxy_pass http://api; }   # Stops before regex
location ~ \.php$ { fastcgi_pass php; }

location /api { proxy_pass http://backend; }

Matches /api, /api123, /apitest - probably not what you want.

location = /api { }          # Exact /api only
location /api/ { }           # /api/anything
location ~ ^/api(/|$) { }    # /api or /api/anything

server {
    # Health check - fastest possible response
    location = /health {
        access_log off;
        return 200 "OK\n";
    }
    
    # API routes - must not hit static file handlers
    location ^~ /api/ {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }
    
    # Static assets with caching
    location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
    
    # PHP files
    location ~ \.php$ {
        fastcgi_pass unix:/run/php-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
    
    # Default fallback
    location / {
        try_files $uri $uri/ =404;
    }
}

• /health → Exact match, returns 200 immediately
• /api/users → Preferential prefix, proxies to backend
• /logo.png → Regex match, serves with cache headers
• /index.php → Regex match, passes to PHP-FPM
• /about → Prefix match, tries file then 404

location / {
    proxy_pass http://backend;
}

location / {
    # Backend address
    proxy_pass http://backend;
    
    # HTTP version (1.1 required for keepalive)
    proxy_http_version 1.1;
    
    # Essential headers
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    
    # WebSocket support
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    
    # Timeouts
    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;
    
    # Buffering
    proxy_buffering on;
    proxy_buffer_size 4k;
    proxy_buffers 8 4k;
    
    # Connection reuse
    proxy_http_version 1.1;
    proxy_set_header Connection "";
}

proxy_set_header Host $host;  # Preserve original Host header

proxy_set_header X-Real-IP $remote_addr;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_set_header X-Forwarded-Proto $scheme;

upstream backend {
    # Load balancing method (see below)
    least_conn;
    
    # Backend servers
    server app1:8080 weight=3 max_fails=3 fail_timeout=30s;
    server app2:8080 weight=2 max_fails=3 fail_timeout=30s;
    server app3:8080 weight=1 max_fails=3 fail_timeout=30s;
    server app4:8080 backup;  # Only used if all others down
    
    # Connection pooling
    keepalive 32;
    keepalive_requests 100;
    keepalive_timeout 60s;
}
location / {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
}

upstream backend {
    server app1:8080;
    server app2:8080;
    server app3:8080;
}

upstream backend {
    least_conn;
    server app1:8080;
    server app2:8080;
    server app3:8080;
}

upstream backend {
    ip_hash;
    server app1:8080;
    server app2:8080;
    server app3:8080;
}

upstream backend {
    hash $request_uri consistent;  # Or $cookie_sessionid, etc.
    server app1:8080;
    server app2:8080;
    server app3:8080;
}

• Hash any variable for custom affinity
• consistent parameter uses consistent hashing (minimizes redistribution when servers change)
• Use when: You need affinity based on specific request attributes

upstream backend {
    least_time header;  # Or 'last_byte'
    server app1:8080;
    server app2:8080;
    server app3:8080;
}

upstream backend {
    server app1:8080 max_fails=3 fail_timeout=30s;
    server app2:8080 max_fails=3 fail_timeout=30s;
}

• After max_fails consecutive failures, mark server as down
• Retry after fail_timeout seconds
• Failure criteria: Connection refused, timeout, or 502/503/504 response

upstream backend {
    zone backend 64k;
    server app1:8080;
    server app2:8080;
}
location / {
    proxy_pass http://backend;
    health_check interval=5s fails=3 passes=2 uri=/health;
}

upstream backend {
    server app1:8080;
    server app2:8080;
    
    keepalive 32;  # Pool size
    keepalive_requests 100;  # Requests per connection
    keepalive_timeout 60s;  # Idle timeout
}
location / {
    proxy_pass http://backend;
    proxy_http_version 1.1;  # Required
    proxy_set_header Connection "";  # Clear Connection header
}

proxy_buffering on;  # Default
proxy_buffer_size 4k;  # Buffer for response headers
proxy_buffers 8 4k;  # Buffers for response body
proxy_busy_buffers_size 8k;  # Can send to client while receiving

location /stream {
    proxy_buffering off;  # Disable for streaming
    proxy_pass http://backend;
}

Use proxy_buffering off for:

• Server-Sent Events (SSE)
• WebSockets (after upgrade)
• Streaming APIs
• Large file downloads where you want backpressure

client_body_buffer_size 128k;  # Buffer requests in memory
client_max_body_size 100m;  # Max request body size
client_body_temp_path /tmp/nginx/client_body;  # Disk spill location

server {
    listen 443 ssl http2;
    server_name example.com;
    
    # Certificate and key
    ssl_certificate /etc/ssl/certs/fullchain.pem;
    ssl_certificate_key /etc/ssl/private/privkey.pem;
    
    # Protocols
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    
    # Ciphers
    ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384';
    
    # Session cache
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    ssl_session_tickets off;
    
    # OCSP stapling
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_trusted_certificate /etc/ssl/certs/chain.pem;
    
    # Security headers
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
}

ssl_session_cache shared:SSL:10m;

ssl_stapling on;
ssl_stapling_verify on;

listen 443 ssl http2;

Define cache zone
proxy_cache_path /var/cache/nginx/proxy
                 levels=1:2
                 keys_zone=my_cache:10m
                 max_size=1g
                 inactive=60m
                 use_temp_path=off;
server {
    location / {
        proxy_cache my_cache;
        proxy_cache_valid 200 10m;
        proxy_cache_valid 404 1m;
        proxy_cache_use_stale error timeout updating;
        proxy_cache_background_update on;
        proxy_cache_lock on;
        
        # Cache key
        proxy_cache_key "$scheme$request_method$host$request_uri";
        
        # Add cache status header
        add_header X-Cache-Status $upstream_cache_status;
        
        proxy_pass http://backend;
    }
}

proxy_cache_use_stale error timeout updating http_500 http_502 http_503;

proxy_cache_bypass $http_pragma $http_authorization;
proxy_no_cache $http_pragma $http_authorization;

add_header X-Cache-Status $upstream_cache_status;

Define rate limit zone
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
location /api/ {
    limit_req zone=api burst=20 nodelay;
    proxy_pass http://backend;
}

• $binary_remote_addr: Key for limiting (client IP)
• zone=api:10m: 10MB shared memory zone (stores ~160k IP addresses)
• rate=10r/s: Allow 10 requests per second
• burst=20: Allow bursts up to 20 requests above rate
• nodelay: Process burst immediately (don't delay to smooth rate)

Without burst:

• Request 1-10 in first second: OK
• Request 11: 503 (rate exceeded)

limit_req_zone $binary_remote_addr zone=global:10m rate=100r/s;
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
limit_req_zone $server_name zone=per_vhost:10m rate=1000r/s;
location /api/ {
    limit_req zone=global burst=50;
    limit_req zone=api burst=20;
    proxy_pass http://backend;
}

limit_conn_zone $binary_remote_addr zone=addr:10m;
location /download/ {
    limit_conn addr 2;  # Max 2 concurrent connections per IP
    proxy_pass http://storage;
}

server_tokens off;  # Don't expose Nginx version
more_clear_headers Server;  # Remove Server header entirely (requires headers-more module)

location ~ /\. {
    deny all;
    access_log off;
    log_not_found off;
}

Blocks .git, .env, .htaccess, etc.

location ~* (wp-admin|wp-login|xmlrpc\.php|phpmyadmin) {
    return 444;  # Close connection without response
}

client_max_body_size 10m;  # Max request body
client_body_timeout 12s;
client_header_timeout 12s;

add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Referrer-Policy "no-referrer-when-downgrade" always;
add_header Content-Security-Policy "default-src 'self' https:" always;

nginx -t  # Test configuration
nginx -s reload  # Graceful reload

kill -USR2 cat /var/run/nginx.pid  # Start new master with new binary
kill -WINCH cat /var/run/nginx.pid.oldbin  # Old workers stop accepting connections
kill -QUIT cat /var/run/nginx.pid.oldbin  # Gracefully shutdown old master

log_format detailed '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent" '
                    'rt=$request_time uct="$upstream_connect_time" '
                    'uht="$upstream_header_time" urt="$upstream_response_time"';
access_log /var/log/nginx/access.log detailed buffer=32k flush=5s;
error_log /var/log/nginx/error.log warn;

• $request_time: Total request time (client → Nginx → backend → client)
• $upstream_connect_time: Time to connect to backend
• $upstream_header_time: Time to receive first byte from backend
• $upstream_response_time: Time to receive full response from backend

error_log /var/log/nginx/error.log debug;

location /nginx_status {
    stub_status;
    allow 127.0.0.1;
    deny all;
}

curl http://localhost/nginx_status

Output: ` Active connections: 291 server accepts handled requests 16630 16630 31070 Reading: 6 Writing: 179 Waiting: 106 ``

---

Common Production Mistakes

proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;

events {
    worker_connections 4096;  # Adjust based on load
}

Bad
location / {
    if ($request_method = POST) {
        proxy_pass http://backend;
    }
}
Good
location = /api {
    limit_except GET HEAD {
        proxy_pass http://backend;
    }
}

---

Performance Tuning

Worker Configuration

worker_processes auto;  # One per CPU core
worker_rlimit_nofile 65535;  # File descriptor limit
worker_cpu_affinity auto;  # Pin workers to CPUs
events {
    worker_connections 4096;  # Max concurrent connections per worker
    use epoll;  # Linux kernel 2.6+
    multi_accept on;  # Accept multiple connections per event loop iteration
}

TCP Optimization

http {
    sendfile on;  # Use sendfile() for zero-copy
    tcp_nopush on;  # Optimize packet sizes
    tcp_nodelay on;  # Disable Nagle's algorithm for low latency
    
    keepalive_timeout 65;  # Client connection reuse
    keepalive_requests 100;
    
    reset_timedout_connection on;  # Reset timed out connections
}

File Caching

open_file_cache max=10000 inactive=30s;
open_file_cache_valid 60s;
open_file_cache_min_uses 2;
open_file_cache_errors on;

Caches open file descriptors for static files.

---

Nginx in Microservices Architecture

Nginx often serves as:

• API Gateway - Single entry point, routing, authentication
• Service Mesh Sidecar - Per-service proxy (though Envoy more common now)
• Ingress Controller (Kubernetes) - External traffic routing
• Load Balancer - Distributing traffic across service instances

Kubernetes Ingress Example

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
    nginx.ingress.kubernetes.io/rate-limit: "100"
spec:
  rules:
  - host: api.example.com
    http:
      paths:
      - path: /v1/users
        pathType: Prefix
        backend:
          service:
            name: user-service
            port:
              number: 8080

Nginx Ingress Controller converts this to Nginx config.

---

When NOT to Use Nginx

Nginx is infrastructure, not application logic. Don't use Nginx for:

• Complex business logic - Use application code
• Dynamic routing decisions - Use API gateway or service mesh
• Stateful request handling - Nginx is stateless
• Heavy data transformation - Use application tier
• Database queries - Obviously belongs in application

---

Conclusion

Nginx is a high-performance traffic control layer that, when properly configured, becomes one of the most reliable components in your infrastructure.

• Architecture matters - Event-driven design enables massive concurrency
• Request flow understanding - Know the 11 processing phases
• Location matching - Most misunderstood feature, most important to get right
• Headers in proxy - Always set Host, X-Real-IP, X-Forwarded-*
• Load balancing - Choose algorithm based on your workload
• Caching - Dramatic performance gains for read-heavy workloads
• Security - Rate limiting, request size limits, security headers
• Zero-downtime - Graceful reloads and binary upgrades
• Observability - Log timing breakdowns, monitor cache hit rates
• Know your limits - Nginx is infrastructure, not application logic

Author: Mohammed Mostafa
Published: January 15, 2026
Reading Time: 20 min read
Tags: nginx, web-server, reverse-proxy, load-balancing, devops, performance, configuration
Read on modev.me →

OS Concepts Explained

This article provides detailed explanations of the operating system concepts implemented in SimuKernel.

> Source code: https://github.com/Mo7ammedd/SimuKernel

CPU Scheduling

What is CPU Scheduling?

CPU scheduling is the process of determining which process in the ready queue will be allocated the CPU for execution. The goal is to maximize CPU utilization, throughput, and minimize waiting time and response time.

Process States

A process transitions through several states:

• New: Process is being created
• Ready: Process is waiting to be assigned to CPU
• Running: Instructions are being executed
• Waiting: Process is waiting for I/O or event
• Terminated: Process has finished execution

Scheduling Algorithms

1. Round Robin (RR)

• Each process gets a fixed time slice (quantum)
• After quantum expires, process moves to end of ready queue
• Next process in queue gets CPU
• Preemptive algorithm

• Fair allocation of CPU time
• No starvation
• Good for time-sharing systems
• Predictable response time

• Context switching overhead
• Average waiting time can be high
• Performance depends on time quantum selection

• Too small: High context switching overhead
• Too large: Becomes FCFS, poor response time
• Typical: 10-100 milliseconds

Execution Order: P1[0-4] → P2[4-8] → P3[8-12] → P1[12-16] → P2[16-17] → P3[17-21] → P1[21-22] `

Non-Preemptive Order: P2 → P4 → P1 → P3 (Execution order by priority) `

Example: Virtual: Page 2, Offset 100 Physical: Frame 1, Offset 100 `

3 Frames: 9 page faults 4 Frames: 10 page faults (worse!) `

Access times when referencing page 5: P1: 3, P2: 5, P3: 2, P4: 4 Replace P3 (oldest access) `

Replace P4 (optimal choice) `

where p = page fault rate `

---

Real-World Applications

Linux Process Scheduler

• Red-black tree of runnable processes
• Each process has virtual runtime (vruntime)
• Runs process with smallest vruntime
• Time slice based on nice value and number of processes

Windows Memory Manager

• Each process has working set (pages in physical memory)
• Minimum and maximum working set sizes
• Page frame database tracks all physical memory
• Modified page writer writes dirty pages to disk

Android Process Management

• Processes assigned priority levels
• When memory low, kills lowest priority processes
• Background apps killed before foreground
• System services protected

Further Reading

• Books:

• Online Resources:

Author: Mohammed Mostafa
Published: October 29, 2025
Reading Time: 9 min read
Tags: operating-systems, cpu-scheduling, memory-management, process-management
Read on modev.me →

Building Custom Middleware in ASP.NET Core

Introduction

In ASP.NET Core, middleware is the fundamental mechanism that processes every HTTP request and response. Every request that enters the application and every response that leaves it flows through the middleware pipeline.

A middleware component can:

• Inspect the incoming request
• Modify request headers or body
• Decide whether to short-circuit the pipeline
• Invoke the next middleware
• Modify the outgoing response

• Logging and tracing
• Authentication and authorization
• Rate limiting
• Request validation
• Performance monitoring
• Response transformation

---

Understanding Middleware Basics

!ASP.NET Core Middleware Pipeline Sequence

ASP.NET Core uses a chain of responsibility model. Each middleware receives a HttpContext and a delegate pointing to the next component in the pipeline.

Each middleware can execute logic in two phases:

• Before calling next
• After the next middleware completes

Conceptual Pipeline Flow

async Task ProcessRequest(HttpContext context)
{
    // Middleware A (before)
    await MiddlewareA(context, async () =>
    {
        // Middleware B (before)
        await MiddlewareB(context, async () =>
        {
            // Endpoint execution
            await Controller(context);
        });
        // Middleware B (after)
    });
    // Middleware A (after)
}

Key observations:

• Middleware order matters
• Short-circuiting stops downstream execution
• Exceptions bubble upward unless handled

How Middleware Is Registered

Middleware is registered during application startup using Use, Map, or Run.

• Use allows calling the next middleware
• Run terminates the pipeline
• Map branches the pipeline based on path

---

Implementation Methods

ASP.NET Core provides three main ways to build custom middleware. Each serves a different purpose and has different trade-offs.

---

1. Request Delegates (Inline Middleware)

This is the simplest way to write middleware. Logic is defined inline using a lambda.

app.Use(async (context, next) =>
{
    var timer = Stopwatch.StartNew();
    var logger = context.RequestServices.GetService>();
logger?.LogInformation(
        "Processing {Method} {Path}",
        context.Request.Method,
        context.Request.Path
    );
context.Response.OnStarting(() =>
    {
        context.Response.Headers["X-Response-Time"] =
            timer.ElapsedMilliseconds.ToString();
        return Task.CompletedTask;
    });
await next(context);
timer.Stop();
logger?.LogInformation(
        "Completed {Method} {Path} in {ElapsedMs}ms",
        context.Request.Method,
        context.Request.Path,
        timer.ElapsedMilliseconds
    );
});

This approach is useful for:

• Simple logging
• Header manipulation
• Debugging
• Rapid prototyping

Limitations

• Hard to test
• No clear separation of concerns
• Grows messy as logic increases
• Limited reuse

---

2. Convention-Based Middleware (Class + Extension Method)

This is the most commonly recommended approach for production code.

It consists of:

• A middleware class
• A constructor receiving RequestDelegate and dependencies
• An InvokeAsync method
• An extension method for registration

public class RequestLoggingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger _logger;
    private readonly RequestLoggingOptions _options;
public RequestLoggingMiddleware(
        RequestDelegate next,
        ILogger logger,
        IOptions options)
    {
        _next = next;
        _logger = logger;
        _options = options.Value;
    }
public async Task InvokeAsync(HttpContext context)
    {
        var request = await FormatRequest(context.Request);
        _logger.LogInformation("Incoming Request: {Request}", request);
await _next(context);
var response = await FormatResponse(context.Response);
        _logger.LogInformation("Outgoing Response: {Response}", response);
    }
}

Extension Method

public static class RequestLoggingMiddlewareExtensions
{
    public static IApplicationBuilder UseRequestLogging(
        this IApplicationBuilder builder)
    {
        return builder.UseMiddleware();
    }
}

Usage

app.UseRequestLogging();

Why This Works Well

• Clear responsibility boundaries
• Full dependency injection support
• Configurable via options
• Easy to unit test
• Reusable across applications

---

3. Factory-Based Middleware (IMiddleware)

This approach uses the IMiddleware interface. Each request receives a fresh instance.

public class PerformanceMiddleware : IMiddleware
{
    private readonly ILogger _logger;
    private readonly IMetricsService _metrics;
public PerformanceMiddleware(
        ILogger logger,
        IMetricsService metrics)
    {
        _logger = logger;
        _metrics = metrics;
    }
public async Task InvokeAsync(HttpContext context, RequestDelegate next)
    {
        var timer = Stopwatch.StartNew();
        var path = context.Request.Path;
try
        {
            await next(context);
        }
        finally
        {
            timer.Stop();
await _metrics.RecordMetricAsync(new RequestMetric
            {
                Path = path,
                Method = context.Request.Method,
                Duration = timer.ElapsedMilliseconds,
                StatusCode = context.Response.StatusCode
            });
        }
    }
}

Registration

services.AddTransient();
app.UseMiddleware();

Characteristics

• Full constructor injection
• New instance per request
• Easier unit testing
• Slightly higher allocation cost

---

Middleware Lifetime and DI Behavior

• Convention-based middleware is created once
• Dependencies follow their registered lifetimes
• IMiddleware instances are created per request

---

Best Practices

Error Handling

Centralized exception handling middleware is common.

public async Task InvokeAsync(HttpContext context, RequestDelegate next)
{
    try
    {
        await next(context);
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Unhandled exception");
        context.Response.StatusCode = 500;
        await context.Response.WriteAsync("Internal Server Error");
    }
}

This should be placed early in the pipeline.

---

Performance Considerations

• Avoid buffering request bodies unless necessary
• Use async APIs exclusively
• Minimize allocations
• Avoid synchronous I/O
• Be careful with large response interception

---

Configuration Support

Middleware should be configurable via options.

public class MiddlewareOptions
{
    public bool EnableLogging { get; set; }
    public string[] ExcludedPaths { get; set; }
    public int TimeoutSeconds { get; set; }
}

services.Configure(
    configuration.GetSection("Middleware"));

Avoid hardcoded behavior.

---

Advanced Scenarios

Conditional Execution

public async Task InvokeAsync(HttpContext context, RequestDelegate next)
{
    if (!_options.ExcludedPaths.Contains(context.Request.Path))
    {
        await ProcessRequest(context);
    }
await next(context);
}

This is useful for excluding health checks or static files.

---

Branching Pipelines

app.Map("/api", apiApp =>
{
    apiApp.UseMiddleware();
    apiApp.UseMiddleware();
});

Branching avoids unnecessary middleware execution for unrelated routes.

---

Ordering Pitfalls

Incorrect ordering can break applications.

Examples:

• Authentication must run before authorization
• Exception handling must wrap downstream components
• Response compression must run before response writing

---

Middleware Approach Comparison

---

Summary

Middleware is the backbone of ASP.NET Core request processing.

Key takeaways:

• Middleware order defines behavior
• Keep middleware focused and small
• Prefer convention-based middleware by default
• Use IMiddleware for complex, test-heavy scenarios
• Treat middleware as infrastructure, not business logic

Verified Examples

Checked on September 16, 2026 with ASP.NET Core 10.0.12 and .NET 10.0.12, using SDK 10.0.112. A local Kestrel server handled two real HTTP requests to verify delegate ordering, one-time construction of conventional middleware, per-request resolution of transient IMiddleware, and a response timing header registered through OnStarting.

The verification harness is scripts/verify-blog/dotnet/Program.cs in the portfolio repository. The logging and metrics helpers in the article remain application-specific examples.

Author: Mohammed Mostafa
Published: March 15, 2024
Reading Time: 7 min read
Tags: aspnet-core, middleware, dotnet, web-development, request-pipeline, csharp
Read on modev.me →

Clustered and Non-Clustered Implementations

Introduction to Database Indexing

Database indexes help the database locate data faster by reducing the amount of data that must be read from disk.

Without an index, the database engine performs a table scan, which means reading every data page and evaluating each row until the query condition is satisfied. This approach is acceptable for very small tables but quickly becomes a bottleneck as data volume grows.

Indexes exist to avoid this cost by allowing the engine to jump directly to relevant pages.

Indexes improve:

• Query performance by reducing I/O
• Sorting efficiency by maintaining ordered structures
• Join performance by enabling fast lookups
• CPU usage by minimizing row evaluations
• Overall system throughput under concurrent load

Creating the right index is not about indexing everything. It is about indexing access patterns.

---

How Tables Are Organized

!Clustered vs Non-Clustered Index Overview

A table can be organized in two fundamental ways:

• Physically ordered by a clustered index
• Unordered as a heap with optional non-clustered indexes

---

B-Tree Architecture: How Indexes Work

Most relational databases use B-Tree structures for indexes. This includes SQL Server, PostgreSQL, MySQL (InnoDB), and Oracle.

A B-Tree keeps data balanced and shallow, which guarantees predictable performance even as tables grow to millions or billions of rows.

Key properties:

• All leaf nodes are at the same depth
• The tree remains balanced automatically
• Lookups require a small number of page reads

How a B-Tree Works

• The root node contains key ranges
• Intermediate nodes narrow the search range
• Leaf nodes contain either data rows or row locators
• Each page stores multiple keys to reduce tree height

Operation Complexity

In practice, most index seeks require only 2 to 4 page reads, even for very large tables.

---

Clustered Indexes

A clustered index defines the physical order of rows on disk.

When a table has a clustered index, the leaf level of the B-Tree is the table itself. There is no separate data structure for the table rows.

Because data can only be physically ordered one way, a table can have only one clustered index.

!Clustered Index Structure

Key Characteristics

• Data pages are sorted by the clustered key
• Non-unique keys are made unique using an internal uniquifier
• Range queries are extremely efficient
• Large inserts benefit from sequential keys
• Page splits occur when inserting into the middle of the key range

Example

CREATE CLUSTERED INDEX IX_Orders_Date 
ON Orders (OrderDate);

This layout is ideal for queries such as:

SELECT *
FROM Orders
WHERE OrderDate BETWEEN '2024-01-01' AND '2024-01-31';

What Happens on Disk

`` Page 1023 -> rows for 2024-01-01 Page 1024 -> rows for 2024-01-02 Page 1025 -> rows for 2024-01-03 `

CREATE CLUSTERED INDEX IX_Customers_Cluster 
ON Customers (LastName)
WITH (FILLFACTOR = 90);

CREATE CLUSTERED INDEX IX_Orders_Composite
ON Orders (OrderDate DESC, OrderID ASC);

CREATE NONCLUSTERED INDEX IX_Orders_Customer
ON Orders (CustomerID)
INCLUDE (OrderDate, TotalAmount);

This index supports queries that filter by CustomerID and select included columns without touching the base table.

Key Lookups

If a query selects columns not present in the index, the engine performs a key lookup to fetch the remaining columns from the clustered index.

Covering indexes eliminate this cost.

---

Specialized Index Types

Filtered Index

Filtered indexes store only a subset of rows.

CREATE NONCLUSTERED INDEX IX_Users_Active
ON Users (LastLoginDate)
WHERE IsActive = 1;

Benefits:

• Smaller size
• Faster seeks
• Lower maintenance cost

Columnstore Index

Columnstore indexes store data by column instead of by row.

CREATE COLUMNSTORE INDEX IX_Sales_Columnstore
ON Sales (ProductID, SaleDate, Quantity, Amount);

They are optimized for:

• Aggregations
• Scans over large datasets
• Analytics and reporting workloads

---

Index Selection Guide

---

Index Maintenance

Over time, inserts and deletes cause fragmentation.

Fragmentation increases:

• Page reads
• Memory usage
• CPU overhead

Maintenance Strategy

• Reorganize when fragmentation is between 5 and 30 percent
• Rebuild when fragmentation exceeds 30 percent

Smart Maintenance Script

DECLARE @IndexName NVARCHAR(255), @Fragmentation FLOAT
DECLARE IndexCursor CURSOR FOR
SELECT name, avg_fragmentation_in_percent
FROM sys.dm_db_index_physical_stats(DB_ID(), NULL, NULL, NULL, NULL) ps
JOIN sys.indexes i 
  ON ps.object_id = i.object_id AND ps.index_id = i.index_id
WHERE ps.avg_fragmentation_in_percent > 5
OPEN IndexCursor
FETCH NEXT FROM IndexCursor INTO @IndexName, @Fragmentation
WHILE @@FETCH_STATUS = 0
BEGIN
    IF @Fragmentation > 30
        EXEC('ALTER INDEX ' + @IndexName + ' ON Orders REBUILD')
    ELSE
        EXEC('ALTER INDEX ' + @IndexName + ' ON Orders REORGANIZE')
FETCH NEXT FROM IndexCursor INTO @IndexName, @Fragmentation
END
CLOSE IndexCursor
DEALLOCATE IndexCursor

---

Performance Comparison (10M Rows)

---

Advanced Index Patterns

Indexed View

Indexed views materialize aggregations.

CREATE VIEW dbo.OrderSummary WITH SCHEMABINDING AS
SELECT CustomerID, COUNT_BIG(*) AS OrderCount, SUM(TotalAmount) AS Total
FROM dbo.Orders
GROUP BY CustomerID;
CREATE UNIQUE CLUSTERED INDEX IX_OrderSummary
ON dbo.OrderSummary (CustomerID);

They are useful for expensive aggregations with stable data.

Partitioned Index

Partitioning improves manageability and query pruning.

CREATE PARTITION FUNCTION OrderDateRangePF (DATE)
AS RANGE RIGHT FOR VALUES 
('2024-01-01', '2024-02-01', '2024-03-01');

Often combined with sliding window strategies.

---

Troubleshooting Index Problems

Useful diagnostics:

SET STATISTICS XML ON;
SELECT * FROM sys.dm_db_missing_index_details;
SELECT * FROM sys.dm_db_index_usage_stats;

Never create indexes blindly based only on missing index suggestions.

---

Conclusion

A strong indexing strategy balances:

• Read performance
• Write cost
• Storage usage
• Maintenance overhead

• Choose clustered keys deliberately
• Use non-clustered indexes to support query patterns
• Cover critical queries with INCLUDE
• Remove unused indexes regularly
• Maintain indexes based on fragmentation metrics

Author: Mohammed Mostafa
Published: November 10, 2023
Reading Time: 8 min read
Tags: database, sql-server, indexing, performance, b-tree, database-optimization
Read on modev.me →

Deep Dive into C# Boxing and Unboxing

Understanding the Fundamentals

Boxing and unboxing describe how the .NET runtime moves data between value types and reference types.

This behavior is rooted in how the CLR represents data in memory and how the JIT compiler generates machine code.

!C# Boxing and Unboxing Overview

Value Types vs Reference Types

• int, double, bool
• struct, enum
• Stored inline
• Copied by value
• Designed for small, immutable data

• class, string, object
• Stored on the managed heap
• Passed by reference
• Require garbage collection

What Is Boxing

int number = 42;
object boxed = number;

At runtime, this causes the CLR to allocate a new object on the managed heap and copy the value into it.

What Is Unboxing

object boxed = 42;
int unboxed = (int)boxed;

Unboxing is not just a cast. It includes a runtime type check and a memory copy.

---

What Actually Happens During Boxing

int number = 42;
object boxed = number;

Internally, the CLR performs the following steps:

• Allocates memory on the managed heap
• Writes an object header (method table pointer, sync block)
• Copies the value into the object payload
• Returns a reference to the object

Why Size Increases

A boxed value includes:

• Object header
• Type metadata pointer
• Padding for alignment
• The actual value

---

What Actually Happens During Unboxing

object boxed = 42;
int value = (int)boxed;

The CLR performs:

• A runtime type check to ensure the object contains the expected value type
• Copies the value from the heap back to the stack or register
• Leaves the boxed object on the heap for later garbage collection

If the runtime type does not match, an InvalidCastException is thrown.

---

Memory Management

!Stack vs Heap in .NET

Stack vs Heap in Practice

• Extremely fast allocation
• Automatic cleanup
• Limited size
• Used for local value types and method frames

• Slower allocation
• Managed by garbage collector
• Larger and flexible
• Used for reference types and boxed values

Example Memory Layout

int x = 10;
object boxed = x;

• x lives inline in the stack frame
• boxed is a reference pointing to heap memory
• The value 10 is duplicated, not shared

---

Why Boxing Hurts Performance

Boxing introduces multiple hidden costs:

• Heap allocation
• Additional memory usage
• CPU cycles for copying
• Garbage collection pressure
• Cache inefficiency

• Runtime type checking
• Additional memory copy

• Hot loops
• High-throughput services
• Real-time systems
• Large collections

Performance Analysis

!Boxing Performance and Memory Allocation

Boxing in Collections

Compare the same loop with an object-based collection and a generic collection:

object o = 10;

Console.WriteLine(10);

The WriteLine(object) overload causes boxing.

IComparable c = 10;

Enum e = DayOfWeek.Monday;

Enums are value types and get boxed when treated as Enum or object.

int value = 42;
string s = $"Value is {value}";

string s = $"Value is {value:D}";

string s = string.Create(
    CultureInfo.InvariantCulture,
    $"Value is {value}"
);

const int count = 1_000_000;
// No boxing
int sum1 = 0;
for (int i = 0; i < count; i++)
{
    sum1 += i;
}
// Boxing
object sum2 = 0;
for (int i = 0; i < count; i++)
{
    sum2 = (int)sum2 + i;
}

• Prefer generics everywhere
• Use List, Dictionary
• Implement IEquatable on structs
• Keep structs small and immutable
• Use profilers to detect boxing

• ArrayList, Hashtable
• APIs that accept object unnecessarily
• Structs implementing non-generic interfaces
• Passing value types through object pipelines

public readonly struct Money : IEquatable
{
    private readonly decimal amount;
public Money(decimal amount)
    {
        this.amount = amount;
    }
public bool Equals(Money other) => amount == other.amount;
public override bool Equals(object obj)
    {
        return obj is Money other && Equals(other);
    }
public override int GetHashCode() => amount.GetHashCode();
}

Implementing IEquatable avoids boxing during equality checks in generic collections.

public class Processor where T : struct
{
    public T Process(T value)
    {
        return value;
    }
}

The struct constraint allows the JIT to generate boxing-free code paths.

• Generics
• Span and ReadOnlySpan
• Nullable value types (int?)
• ValueTask
• Pattern matching with generics

Checked on September 16, 2026 with .NET 10.0.12 using SDK 10.0.112. The functional checks cover copying a value into a box, unboxing it to the exact stored type, rejecting an invalid cast, and preserving the same values in ArrayList and List.

The verification harness is scripts/verify-blog/dotnet/Program.cs` in the portfolio repository. These checks exercise behavior; allocation sizes and performance measurements require their own workload and runtime configuration.

Author: Mohammed Mostafa
Published: August 22, 2023
Reading Time: 7 min read
Tags: csharp, dotnet, performance, memory-management, programming-fundamentals
Read on modev.me →