Mobile Networking: Handling Slow, Unreliable Connections

Building mobile applications on local development workstations often creates a dangerous illusion of network reliability. In an office or home environment, developer devices connect over gigabit fiber or low-latency Wi-Fi where round-trip times (RTT) remain stable below 20 milliseconds, packet loss rarely exceeds 0.1%, and wall power provides virtually unlimited energy.

In the hands of real users, mobile computing operates in a physically hostile communication environment. Devices travel through subway tunnels, step into shielded elevators, switch between fading Wi-Fi hotspots, and traverse cellular base station boundaries at highway speeds. A smartphone is not a miniature server on a reliable wire; it is a battery-constrained radio transmitter communicating over dynamically modulated radio frequency (RF) channels subject to atmospheric fading, physical obstructions, and severe contention.

Treating mobile networking as an ordinary HTTP fetch with a standard try/catch block and an immediate retry loop leads directly to broken user experiences: frozen interfaces, corrupted database states, double-charged credit cards, and drained batteries. This guide examines the physics of cellular radios, the mechanics of mobile network degradation, and the architectural patterns required to deliver resilient, production-grade mobile applications.

---

1. The Physics of Cellular Computing: RRC States and the Tail Energy Trap

To design resilient networking code, mobile engineers must understand how cellular modems consume electrical power. Unlike Wi-Fi chips, which can cycle into micro-sleep states between packet receptions, cellular modems (LTE, 5G NR, and legacy UMTS) are governed by the telecommunications network via the Radio Resource Control (RRC) protocol.

The Cellular RRC State Machine

A cellular base station (an eNodeB in 4G LTE or a gNodeB in 5G NR) directly manages the radio state of every connected user equipment (UE). The modem cannot arbitrarily transmit data whenever an application executes an HTTP request. It must negotiate dedicated radio resource channels with the tower before transmitting a single byte.

In 4G LTE and 5G NR networks, the RRC state machine primarily operates across distinct states:

1. RRC_IDLE: The radio transmitter is powered down. The device consumes minimal energy (often under 10–15 mW for paging reception), periodically listening to broadcast channels for incoming calls or notifications. No radio bearers exist for user data transfer.
2. RRC_CONNECTED (Active): Dedicated radio bearers are established. The device allocates physical resource blocks (PRBs), synchronizes transmit timing, and runs power amplifiers at high output (drawing anywhere from 800 mW to over 2,000 mW depending on transmission power and RF band).
3. Tail State (Connected with Discontinuous Reception - C-DRX): After transmitting data, the modem does not immediately drop to RRC_IDLE. Transitioning from RRC_IDLE to RRC_CONNECTED introduces noticeable signaling latency (typically 50 to 150 milliseconds of radio round trips). To prevent repeated reconnection overhead for bursty traffic, the carrier base station keeps the radio in a high-power tail state governed by an inactivity timer.

               Application Transmits Data
      ┌──────────────────────────────────────────┐
      │                                          │
      ▼                                          │
┌──────────────┐   Data Transmitted    ┌──────────────────┐
│              │ ────────────────────> │  RRC_CONNECTED   │
│   RRC_IDLE   │                       │ (Peak Power Draw)│
│  (Low Power) │ <──────────────────── │                  │
└──────────────┘    Inactivity Timer   └──────────────────┘
                      Expires (5-15s)            │
                     "The Tail Trap"             │ Inactivity Timer
                                                 ▼
                                       ┌──────────────────┐
                                       │   C-DRX Tail     │
                                       │  (Intermittent   │
                                       │   High Power)    │
                                       └──────────────────┘

The Tail Energy Trap

The critical vulnerability in mobile network efficiency is the tail timer (e.g., the 3GPP t-InactivityTimer). Configured by cellular network operators, this timer typically runs for 5 to 15 seconds after the last packet has been exchanged. During this entire interval, the cellular radio remains energized in a high-power state, waiting for subsequent data packets.

This physical reality makes chatty polling catastrophic for device battery life:

• Scenario A (Batched Flush): An application collects analytics, sync checks, and metric logs in memory. Every 15 minutes, it awakens the radio once, flushes 20 requests in parallel over 800 milliseconds, and finishes. The radio remains in the tail state for 10 seconds before transitioning back to RRC_IDLE. The total active radio uptime across 15 minutes is roughly 11 seconds.
• Scenario B (Chatty Heartbeats): An application transmits a small, 60-byte telemetry ping or heartbeat every 20 seconds. Each individual transmission takes only 40 milliseconds over the air. However, each transmission resets the 10-second tail timer. The radio spends 10 seconds out of every 20 seconds energized in a high-power state. The modem is effectively held at peak or elevated power draw for 50% of the entire device runtime, consuming hundreds of milliwatt-hours of battery capacity for a negligible volume of actual data.

Cellular Radio State Comparison

| RRC State | Relative Power Draw | Data Transfer Latency | State Description and Transition Trigger | | :--- | :--- | :--- | :--- | | RRC_IDLE | Base baseline (~10–20 mW) | High (50–150 ms) | Radio powered off for data; listening only to carrier paging cycles. Woken by new outbound packet. | | RRC_CONNECTED (Active) | Maximum (800–2,200 mW) | Zero (Immediate) | Dedicated radio channels active; power amplifiers transmitting at full target RF wattage. | | C-DRX / Tail State | Elevated (200–600 mW) | Low (10–30 ms) | Carrier inactivity timer running after data burst; awaiting further packets before releasing radio bearers. | | RRC_INACTIVE (5G NR) | Low-Medium (~30–50 mW) | Medium (15–40 ms) | 5G NR fast-resume state; stores UE context in radio access network (RAN) to avoid full signaling handshakes. |

---

2. Anatomy of Mobile Network Hostility

Mobile applications fail in production because engineers design for binary connectivity: the device is either online or offline. Real mobile networks are almost never cleanly offline; they exist in prolonged degraded states characterized by packet loss, jitter, bufferbloat, and half-open connections.

Variable Latency, Jitter, and Base Station Bufferbloat

In wired connections, latency is largely bounded by physical distance and router hops. In cellular networks, latency fluctuates erratically due to RF modulation adjustments, physical multipath fading, and carrier scheduling.

A major contributor to severe mobile latency spikes is bufferbloat. Cellular base stations maintain large packet buffers in their Packet Data Convergence Protocol (PDCP) and Radio Link Control (RLC) layers. When a mobile client transfers a burst of data, base station queues can absorb hundreds of packets to avoid dropping them during transient radio fades. However, if the radio channel degrades, these deep buffers fill up.

Instead of dropping packets and signaling TCP to throttle its congestion window, the base station holds packets in transit. This creates queuing delays that inflate typical 40 ms round trips into 2,000 to 5,000 ms delays. For interactive mobile applications, a 4-second delay is practically indistinguishable from a hard network failure, yet traditional network client libraries will hang indefinitely waiting for an OS socket response.

Handover Interruptions and Half-Open TCP Sockets

As users move through space, their mobile device continuously evaluates signal strength across surrounding cell towers. When transitioning between cells (or dropping from 5G to 4G LTE), the carrier initiates a handover:

1. Hard Handovers & Micro-Drops: The radio breaks connection with the current tower before completing association with the target tower. This process creates temporary dropouts lasting from 100 milliseconds to several seconds where packets are silently discarded at the physical layer.
2. Half-Open Sockets (The "Black Hole" Failure): When a phone enters an elevator, goes underground, or loses coverage, the operating system does not receive a TCP FIN or RST packet. To the application's networking stack, the socket descriptor remains open and valid. If the application writes to this socket without aggressive application-layer timeouts, the OS will attempt exponential TCP packet retransmissions for minutes before finally returning ETIMEDOUT.

[Mobile App]                         [Cell Tower / Gateway]             [Backend API]
     │                                         │                              │
     │── GET /v1/feed (Socket Open) ──────────>│                              │
     │                                         │── Forward Request ──────────>│
     │      *User Enters Subway Tunnel*        │                              │
     │      *Cell Signal Completely Lost*      │                              │
     │                                         │<── Processed & Returns 200 ──│
     │                                         │   (Cannot reach Mobile UE)   │
     │   [Socket waits on OS default timeout]  │   (Packets dropped silently) │
     │   (App hangs for 60-120 seconds)        │                              │
     ▼                                         ▼                              ▼

The Captive Portal and Flapping Connectivity Hazard

A ubiquitous flaw in mobile applications is relying blindly on passive operating system network callbacks. Both Android (ConnectivityManager.NetworkCallback) and iOS (NWPathMonitor) provide events when network interfaces change. Cross-platform libraries (such as connectivity_plus) surface these events to application code.

However, an OS callback stating that the Wi-Fi interface is active only indicates a physical layer link to a local router or access point. It provides zero guarantee of upstream Internet egress.

This creates two critical production hazards:

1. The Captive Portal Interception: When a device connects to public Wi-Fi in an airport, hotel, or train station, all outbound HTTP/HTTPS requests are intercepted by a captive portal gateway. Requests to your backend API (https://api.example.com/v1/sync) will either fail TLS handshakes (generating confusing SSL certification errors) or, if plaintext HTTP fallback is permitted, receive an HTTP 200 or 302 redirect containing an HTML login page. If your JSON deserializer attempts to parse an HTML <doctype html> string into an API model, the application crashes.
2. Flapping Interfaces: When walking along the perimeter of known Wi-Fi coverage, the device rapidly associates and disassociates with the access point every few seconds. Naively initiating full state synchronization on every "Network Connected" event creates an endless storm of half-started, aborted requests that choke the app and throttle device performance.

---

3. Resilience Architecture: Outboxes, Idempotency, and Jittered Retries

Resilient mobile architectures accept that any network request can fail, be delayed, or be duplicated. To preserve data consistency across erratic networks, systems must decouple user intent from immediate transport execution.

The Idempotent Mutation Outbox Pattern

The most dangerous failure in distributed mobile computing is the Two Generals Problem:

When a mobile client sends a mutating request (POST /v1/orders or POST /v1/payments) and encounters a socket timeout, the client has no way of knowing whether the request reached the server. The network failure could have occurred on the uplink before the server saw it, or on the downlink after the server successfully processed the mutation and debited the user's account.

Retrying a naive POST request upon reconnection can result in duplicate payments, duplicated bookings, or corrupted state.

┌─────────────────┐      1. User Action       ┌────────────────────────┐
│  Mobile UI /    │ ────────────────────────> │ Durable Local Database │
│ Feature Module  │                           │   (SQLite Outbox)      │
└─────────────────┘                           └────────────────────────┘
                                                           │
                                                           │ 2. Read Pending Mutations
                                                           ▼
┌─────────────────┐   3. Dispatch Mutation    ┌────────────────────────┐
│   Backend API   │ <──────────────────────── │ Outbox Sync Dispatcher │
│   & Database    │ ── Idempotency-Key: UUID ─│  (Background Worker)   │
└─────────────────┘                           └────────────────────────┘
         │                                                 │
         │ 4. HTTP 200 (Success) or 409 (Replay)           │
         └─────────────────────────────────────────────────┘
                   5. Mark Outbox Item COMMITTED

To solve this deterministically, production mobile applications implement an Idempotent Outbox Pattern:

1. Local Transactional Enqueue: When the user performs an action (e.g., submitting a comment or placing an order), the app generates a cryptographically random UUID v4 representing the unique Idempotency Key. The mutation payload and its key are stored directly in a durable local SQLite table marked with status PENDING.
2. Immediate UI Optimism: The local UI reflects the change immediately using the local database as the single source of truth, without blocking on a network spinner.
3. Outbox Synchronization Worker: A background worker reads pending records sequentially or by entity group. When transmitting over the network, it attaches the header:

   Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
   

4. Backend Transactional Deduplication: The backend database enforces a unique constraint on the idempotency_key column within its mutations table. If the backend receives an identical key that was already executed, it skips execution and safely replays the previously cached response payload.
5. Durable Completion: Only after receiving a successful response from the server does the mobile outbox mark the record as COMMITTED or remove it from disk. If the app process is terminated or the phone reboots mid-flight, pending mutations remain safely stored on disk to be synced upon restart.

Exponential Backoff with Full Jitter

When a backend service experiences degradation or when a mobile network disconnects, retrying immediately is counterproductive. Immediate retries saturate the fading radio channel and waste battery power.

However, naive exponential backoff ($t = t_{\text{base}} \times 2^{\text{attempt}}$) introduces a severe vulnerability known as the Thundering Herd or Retry Storm:

Imagine a crowded commuter train traveling through a tunnel. Hundreds of passengers on the train have your application open. While inside the tunnel, all network requests fail. When the train emerges into cell tower coverage, if every client uses deterministic exponential backoff, their retry intervals synchronize. Every client will retry simultaneously at 1s, 2s, 4s, 8s, and 16s, producing massive periodic spikes of traffic that hammer backend load balancers and trigger cascading outages.

To break client synchronization, mobile clients must implement Full Jitter:

$t_{\text{sleep}} = \text{random}(0, \min(t_{\max}, t_{\text{base}} \times 2^{\text{attempt}}))$

Where:

• $t_{\text{base}}$ is the initial retry delay (e.g., 500 ms).
• $t_{\max}$ is the maximum backoff ceiling (e.g., 30,000 ms).
• $\text{attempt}$ is the consecutive failure count (0-indexed).
• $\text{random}(0, x)$ yields a uniform pseudorandom value between 0 and $x$.

Retry Strategy Comparison

| Retry Strategy | Mathematical Delay Formulation | Client Synchronization Behavior | Peak Load on Backend | Mobile Battery Impact | | :--- | :--- | :--- | :--- | :--- | | Immediate Retry | $t = 0$ | Constant / Immediate | Extreme packet bursts; triggers rate limiters | Severe; locks radio in continuous peak transmission | | Fixed Interval | $t = C$ | Synchronized periodicity | High periodic spikes across reconnecting devices | High; keeps modem from sleeping between retries | | Exponential (No Jitter) | $t = \min(t_{\max}, t_{\text{base}} \times 2^{a})$ | Strongly synchronized step curves | Severe periodic spikes (Thundering Herd waves) | Moderate; backoff intervals increase but remain aligned | | Full Jitter | $t = \text{random}(0, \min(t_{\max}, t_{\text{base}} \times 2^{a}))$ | Completely desynchronized | Flat, uniform load distribution across time | Optimal; minimizes modem wake collisions |

Adhering to RFC 9110 and Client-Side Circuit Breakers

A resilient client must also adhere to standard HTTP protocol semantics:

• Respecting Retry-After (RFC 9110 Section 10.2.3): When a server responds with HTTP 429 (Too Many Requests) or HTTP 503 (Service Unavailable), it often includes a Retry-After header specifying delay in seconds or an HTTP-date. The mobile client must override its internal backoff algorithm and sleep for the server-specified duration.
• Client-Side Circuit Breaker: If an application receives repeated consecutive 5xx errors or network timeouts (e.g., 5 failures in a row), continuing to ping the server depletes the device battery and wastes mobile data. The client should transition to an OPEN circuit state for a defined cooldown window (e.g., 30 seconds), instantly failing fast locally and displaying a graceful "Offline Mode" UI without dispatching hardware radio calls.

---

4. Caching Semantics and Over-The-Air Payload Optimization

Every byte not transmitted over a cellular connection is a byte that cannot be delayed, corrupted, or retransmitted. Caching is not merely a performance optimization; it is a primary reliability mechanism.

Stale-While-Revalidate (SWR)

Mobile users should never be confronted with blank loading screens or full-page skeleton loaders when navigating previously visited screens. The Stale-While-Revalidate pattern (formalized in RFC 5861) reconciles instant perceived responsiveness with background data freshness:

1. Instant Render: When the UI requests an entity (e.g., a user profile or product list), the client immediately queries the local persistent disk cache (SQLite or key-value storage) and renders the cached data in 0 ms.
2. Background Revalidation: Concurrently, the networking client dispatches an asynchronous background fetch to the remote API.
3. Reactive UI State Propagation: When the remote server responds with updated data, the client updates the local disk cache and notifies UI subscribers via reactive streams (e.g., StateNotifier or Observables). The UI updates seamlessly in place without layout flickers.

UI Component                     Networking Layer                   Local Storage             Remote Server
     │                                  │                                 │                         │
     │── Request Data ─────────────────>│                                 │                         │
     │                                  │── Read Stale Cache ────────────>│                         │
     │                                  │<── Return Cached Record ────────│                         │
     │<── Emit Stale Data (Render 0ms) ─│                                 │                         │
     │                                  │── Background Fetch ──────────────────────────────────────>│
     │                                  │   (With If-None-Match ETag)     │                         │
     │                                  │                                 │                         │
     │                                  │<── 200 OK (Fresh Payload) ────────────────────────────────│
     │                                  │── Write Fresh Data ────────────>│                         │
     │<── Emit Fresh Data (Update UI) ──│                                                           │
     ▼                                  ▼                                                           ▼

Conditional Validation via ETags and HTTP 304

Mobile applications frequently re-fetch data that has not changed on the server. Without conditional caching, the server serializes and retransmits the full JSON body over the cellular link, consuming bandwidth, CPU cycles, and battery power.

By implementing HTTP conditional caching (RFC 9111):

1. The server returns an ETag (entity tag) header with every read response:

   HTTP/1.1 200 OK
   ETag: "686897696a7c876b7e"
   Cache-Control: public, max-age=300, must-revalidate
   

2. The mobile client persists the ETag alongside the response payload in its local cache store.
3. Upon revalidation, the mobile client attaches the cached tag in the If-None-Match header:

   GET /v1/feed HTTP/1.1
   If-None-Match: "686897696a7c876b7e"
   

4. If the data has not changed, the server responds with HTTP 304 Not Modified containing zero response body. The mobile client updates its cache timestamp and keeps its existing parsed data models, saving hundreds of kilobytes over the air and avoiding redundant JSON deserialization on the device's CPU.

Binary Protocols vs. JSON Payload Trimming

JSON is human-readable and universal, but it incurs significant over-the-air overhead for mobile devices:

• Repetitive String Keys: Every array item repeats full key names ("transaction_identifier", "created_at_utc"), inflating payload sizes.
• Textual Numeric Encoding: Storing large numeric IDs or timestamps as ASCII characters takes up to 8–16 bytes per value instead of 4 or 8 bytes in binary format.
• Parsing CPU Overhead: Parsing complex, multi-megabyte JSON trees on mobile processors blocks the main thread or consumes substantial energy in background worker threads.

To reduce over-the-air transfer footprints:

• Sparse Fieldsets: Allow mobile clients to request only the fields necessary for the current view (e.g., /v1/users?fields=id,name,avatar_url).
• Binary Serialization (Protocol Buffers): Adopting Protocol Buffers (Protobuf) or FlatBuffers encodes data into compact binary wire formats with varint compression and integer field tags. Binary payloads routinely achieve 60% to 80% size reductions compared to uncompressed JSON, drastically lowering packet transmission counts and reducing packet-loss exposure on poor cellular links.

---

5. Modern Transport Protocols: HTTP/2 vs. HTTP/3 (QUIC)

The underlying transport layer profoundly impacts mobile networking performance. Understanding the differences between TCP and UDP-based protocols allows mobile engineering teams to make informed infrastructure choices.

Head-of-Line (HoL) Blocking: The Cellular Bottleneck

In HTTP/1.1, browsers and mobile apps opened multiple parallel TCP connections (typically up to 4–6 per host) to overcome the limitation of one request per connection. This created massive socket overhead, connection establishment latency, and radio strain.

HTTP/2 introduced multiplexing, allowing dozens of logical requests and responses to stream concurrently over a single TCP connection. While this was a major advancement for stable fiber desktop connections, it introduced a severe problem for mobile cellular links: Transport-Layer Head-of-Line (HoL) Blocking.

Because TCP guarantees strict, in-order byte stream delivery:

• If an application multiplexes 10 parallel API requests over a single TCP connection, all 10 requests share the same TCP sequence stream.
• If a phone experiences a burst of cellular interference and drops a single packet belonging to Request #1, the operating system's TCP receive buffer freezes all processing.
• Packets belonging to Requests #2 through #10 may arrive at the phone completely intact, but the OS cannot deliver them to the application until the lost packet for Request #1 is acknowledged and retransmitted.
• On a cellular network with 2% to 5% packet loss, HTTP/2 multiplexing can perform significantly worse than HTTP/1.1 because one dropped packet stalls every concurrent transfer across the entire application.

HTTP/2 over TCP:
Packet Stream: [Req 1, Pkt A] [Req 2, Pkt A] [Req 1, Pkt B - LOST] [Req 2, Pkt B]
                                                      │
                       TCP Window Blocks All Streams  ▼
                       [Req 2, Pkt B] HELD IN BUFFER UNTIL REPAIR!

HTTP/3 over QUIC (UDP):
Stream 1 (Req 1): [Pkt A] [Pkt B - LOST] ──> Stream 1 Waits for Retransmission
Stream 2 (Req 2): [Pkt A] [Pkt B - OK]   ──> Stream 2 Delivers to App Immediately!

How HTTP/3 (QUIC) Solves Mobile Transport Fragility

HTTP/3 replaces TCP with QUIC (formalized in RFC 9000), which operates on top of UDP:

1. Independent Per-Stream Loss Recovery: QUIC implements multiplexing directly inside the transport layer. Each stream is an independent data channel. If a packet in Stream #1 is dropped over the cellular radio, only Stream #1 pauses. Stream #2 and Stream #3 continue processing without interruption.
2. 0-RTT and 1-RTT Handshakes: By combining transport negotiation with TLS 1.3 cryptographic handshakes, QUIC establishes encrypted connections in a single round trip (1-RTT) or resumes known sessions with zero round trips (0-RTT), eliminating the sluggish multi-round-trip handshakes characteristic of standard TCP + TLS setups.

Connection Migration: Surviving Wi-Fi to Cellular Handoffs

In standard TCP, an active connection is strictly identified by an immutable network 4-tuple:

$\text{Socket} = (\text{Source IP}, \text{Source Port}, \text{Destination IP}, \text{Destination Port})$

When a user walks out of their house, their phone disassociates from home Wi-Fi and connects to 5G cellular. The device's local IP address immediately changes. Because the source IP has changed, every active TCP socket is instantly invalidated. Any ongoing download, file upload, or WebSocket connection drops immediately, forcing the client to renegotiate complete TCP and TLS handshakes from scratch.

QUIC solves this with Connection Migration:

• In QUIC, connections are identified by a persistent 64-bit Connection ID (CID) that is completely decoupled from the IP address and port.
• When the phone transitions from Wi-Fi to Cellular, the client emits a QUIC packet from its new cellular IP carrying the existing Connection ID.
• The backend server verifies the packet's cryptographic signature, updates its internal routing table to the new IP/port endpoint, and continues streaming data seamlessly without dropping the connection, interrupting active file transfers, or re-running TLS handshakes.

Transport Protocol Comparison

| Protocol Attribute | HTTP/1.1 | HTTP/2 | HTTP/3 (QUIC) | | :--- | :--- | :--- | :--- | | Transport Layer | TCP | TCP | UDP (QUIC) | | Multiplexing | None (Head-of-line blocking per connection) | Yes (Multiplexed streams over single TCP connection) | Yes (Independent streams native to transport layer) | | Head-of-Line Blocking | Application layer (blocks per TCP pipe) | Transport layer (one lost packet stalls all streams) | Eliminated at transport layer (loss isolated to stream) | | Connection Handshake | 2 RTT (TCP Handshake + TLS 1.2/1.3) | 2 RTT (TCP Handshake + TLS 1.3) | 1 RTT (Combined Transport + TLS 1.3) or 0-RTT | | Interface Handoffs | Broken (Sockets drop on IP address change) | Broken (Sockets drop on IP address change) | Seamless Connection Migration via 64-bit Connection IDs |

---

6. Implementation: A Production-Grade Resilient Mobile HTTP Client

The following TypeScript implementation brings these principles together into a self-contained, production-grade mobile HTTP client. It includes:

1. Active Egress & Captive Portal Probing: Distinguishes physical link connection from verified Internet egress using HTTP 204 checks.
2. Singleflight Request Deduplication: Coalesces identical concurrent GET requests in an in-flight map ($O(1)$ average time complexity for key lookups) to prevent redundant radio traffic.
3. Exponential Backoff with Full Jitter: Desynchronizes retries to prevent retry storms.
4. RFC 9110 Retry-After & Circuit Breaking: Protects backends from cascading load and prevents battery exhaustion.
5. Idempotency Key Injection: Guarantees safe retries on mutating methods (POST, PUT, PATCH, DELETE).
6. Stale-While-Revalidate Caching: Implements conditional ETag validation and HTTP 304 processing for instant UI updates.

/**
 * Production-Grade Resilient Mobile HTTP Client
 * Demonstrates: Egress probing, captive portal detection, singleflight deduplication,
 * exponential backoff with full jitter, idempotency keys, and SWR caching.
 */

export interface HttpRequestConfig {
  url: string;
  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
  headers?: Record<string, string>;
  body?: string;
  timeoutMs?: number;
  idempotencyKey?: string;
  skipCache?: boolean;
  maxRetries?: number;
}

export interface HttpResponse<T> {
  status: number;
  headers: Record<string, string>;
  data: T;
  fromCache?: boolean;
  isStale?: boolean;
}

export interface CacheEntry<T> {
  data: T;
  etag?: string;
  timestamp: number;
  maxAgeMs: number;
}

export interface CacheStore {
  get<T>(key: string): Promise<CacheEntry<T> | null>;
  set<T>(key: string, entry: CacheEntry<T>): Promise<void>;
  delete(key: string): Promise<void>;
}

export class NetworkTimeoutError extends Error {
  constructor(url: string, timeoutMs: number) {
    super(`Request to ${url} timed out after ${timeoutMs}ms`);
    this.name = 'NetworkTimeoutError';
  }
}

export class CaptivePortalDetectedError extends Error {
  constructor(probeUrl: string) {
    super(`Captive portal detected at ${probeUrl}; Internet egress is blocked`);
    this.name = 'CaptivePortalDetectedError';
  }
}

export class CircuitBreakerOpenError extends Error {
  constructor(public readonly cooldownRemainingMs: number) {
    super(`Circuit breaker is OPEN. Cooldown remaining: ${cooldownRemainingMs}ms`);
    this.name = 'CircuitBreakerOpenError';
  }
}

/**
 * Calculates exponential backoff with Full Jitter.
 * Formula: random(0, min(maxMs, baseMs * 2^attempt))
 */
export function calculateBackoffWithJitter(
  attempt: number,
  baseMs: number = 500,
  maxMs: number = 30000
): number {
  const exponentialLimit = Math.min(maxMs, baseMs * Math.pow(2, attempt));
  return Math.floor(Math.random() * (exponentialLimit + 1));
}

/**
 * Parses RFC 9110 Retry-After header (either seconds integer or HTTP date string).
 */
export function parseRetryAfterHeader(headerValue: string | null | undefined): number | null {
  if (!headerValue) return null;
  const numericSeconds = Number.parseInt(headerValue.trim(), 10);
  if (!Number.isNaN(numericSeconds) && numericSeconds >= 0) {
    return numericSeconds * 1000;
  }
  const parsedDate = Date.parse(headerValue);
  if (!Number.isNaN(parsedDate)) {
    const delayMs = parsedDate - Date.now();
    return delayMs > 0 ? delayMs : 0;
  }
  return null;
}

/**
 * Coalesces concurrent identical in-flight read requests to prevent redundant radio bursts.
 * Lookup complexity: O(1) average time in hash map.
 */
export class SingleflightGroup {
  private readonly inFlight = new Map<string, Promise<unknown>>();

  public execute<T>(key: string, fn: () => Promise<T>): Promise<T> {
    const existing = this.inFlight.get(key);
    if (existing) {
      return existing as Promise<T>;
    }

    const promise = fn().finally(() => {
      this.inFlight.delete(key);
    });

    this.inFlight.set(key, promise);
    return promise;
  }
}

/**
 * Active network probe verifying transparent Internet egress and detecting captive portals.
 */
export class ActiveConnectivityProber {
  constructor(
    private readonly probeUrl: string = 'https://connectivitycheck.gstatic.com/generate_204',
    private readonly timeoutMs: number = 4000
  ) {}

  public async verifyInternetEgress(): Promise<boolean> {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), this.timeoutMs);

    try {
      const response = await fetch(this.probeUrl, {
        method: 'GET',
        cache: 'no-store',
        signal: controller.signal,
      });

      // HTTP 204 No Content confirms genuine Internet egress
      if (response.status === 204) {
        return true;
      }

      // Captive portal gateways typically intercept and return HTML login portals or redirects
      const contentType = response.headers.get('content-type') ?? '';
      if (contentType.includes('text/html') || response.status === 200 || response.status === 302) {
        return false;
      }

      return response.ok;
    } catch {
      return false;
    } finally {
      clearTimeout(timer);
    }
  }
}

export class MemoryCacheStore implements CacheStore {
  private readonly store = new Map<string, CacheEntry<unknown>>();

  public async get<T>(key: string): Promise<CacheEntry<T> | null> {
    const entry = this.store.get(key);
    if (!entry) return null;
    return entry as CacheEntry<T>;
  }

  public async set<T>(key: string, entry: CacheEntry<T>): Promise<void> {
    this.store.set(key, entry);
  }

  public async delete(key: string): Promise<void> {
    this.store.delete(key);
  }
}

/**
 * Client-Side Circuit Breaker guarding mobile modem and backend services.
 */
export class CircuitBreaker {
  private failureCount = 0;
  private lastFailureTime = 0;
  private state: 'CLOSED' | 'OPEN' | 'HALF_OPEN' = 'CLOSED';

  constructor(
    private readonly failureThreshold: number = 5,
    private readonly resetTimeoutMs: number = 30000
  ) {}

  public checkCallAllowed(): void {
    const now = Date.now();
    if (this.state === 'OPEN') {
      if (now - this.lastFailureTime > this.resetTimeoutMs) {
        this.state = 'HALF_OPEN';
      } else {
        const remaining = this.resetTimeoutMs - (now - this.lastFailureTime);
        throw new CircuitBreakerOpenError(remaining);
      }
    }
  }

  public recordSuccess(): void {
    this.failureCount = 0;
    this.state = 'CLOSED';
  }

  public recordFailure(): void {
    this.failureCount++;
    this.lastFailureTime = Date.now();
    if (this.failureCount >= this.failureThreshold) {
      this.state = 'OPEN';
    }
  }
}

/**
 * Resilient Mobile HTTP Client Coordinating Network Operations.
 */
export class ResilientMobileHttpClient {
  private readonly singleflight = new SingleflightGroup();
  private readonly circuitBreaker = new CircuitBreaker();
  private readonly prober: ActiveConnectivityProber;
  private readonly cacheStore: CacheStore;

  constructor(options?: { prober?: ActiveConnectivityProber; cacheStore?: CacheStore }) {
    this.prober = options?.prober ?? new ActiveConnectivityProber();
    this.cacheStore = options?.cacheStore ?? new MemoryCacheStore();
  }

  /**
   * Dispatches an HTTP request with automatic resilience features.
   */
  public async request<T>(config: HttpRequestConfig): Promise<HttpResponse<T>> {
    const method = config.method ?? 'GET';

    // GET requests run through singleflight deduplication and SWR caching
    if (method === 'GET') {
      return this.singleflight.execute(config.url, () => this.executeGetWithSwr<T>(config));
    }

    // Mutating methods (POST, PUT, PATCH, DELETE) require idempotency and jittered retries
    return this.executeMutatingWithRetry<T>(config);
  }

  private async executeGetWithSwr<T>(config: HttpRequestConfig): Promise<HttpResponse<T>> {
    const cacheKey = `http_cache:${config.url}`;
    const cached = config.skipCache ? null : await this.cacheStore.get<T>(cacheKey);

    // If cache is valid and not expired, return immediately
    if (cached && Date.now() - cached.timestamp < cached.maxAgeMs) {
      return {
        status: 200,
        headers: {},
        data: cached.data,
        fromCache: true,
        isStale: false,
      };
    }

    // Prepare conditional headers if an ETag is present
    const requestHeaders: Record<string, string> = { ...(config.headers ?? {}) };
    if (cached?.etag) {
      requestHeaders['If-None-Match'] = cached.etag;
    }

    try {
      this.circuitBreaker.checkCallAllowed();
      const networkResponse = await this.fetchWithTimeout(config.url, {
        method: 'GET',
        headers: requestHeaders,
        timeoutMs: config.timeoutMs ?? 10000,
      });

      // Handle 304 Not Modified: reuse cached body with 0 bytes transferred over the air
      if (networkResponse.status === 304 && cached) {
        this.circuitBreaker.recordSuccess();
        await this.cacheStore.set(cacheKey, {
          ...cached,
          timestamp: Date.now(),
        });
        return {
          status: 200,
          headers: networkResponse.headers,
          data: cached.data,
          fromCache: true,
          isStale: false,
        };
      }

      if (networkResponse.ok) {
        this.circuitBreaker.recordSuccess();
        const data = (await networkResponse.json()) as T;
        const etag = networkResponse.headers.get('etag') ?? undefined;

        await this.cacheStore.set(cacheKey, {
          data,
          etag,
          timestamp: Date.now(),
          maxAgeMs: 300000, // 5 minutes default
        });

        return {
          status: networkResponse.status,
          headers: this.extractHeaders(networkResponse),
          data,
          fromCache: false,
          isStale: false,
        };
      }

      throw new Error(`HTTP Error ${networkResponse.status}`);
    } catch (error) {
      this.circuitBreaker.recordFailure();

      // Stale-While-Revalidate Fallback: If network fails but stale cache exists, serve it
      if (cached) {
        return {
          status: 200,
          headers: {},
          data: cached.data,
          fromCache: true,
          isStale: true,
        };
      }

      throw error;
    }
  }

  private async executeMutatingWithRetry<T>(config: HttpRequestConfig): Promise<HttpResponse<T>> {
    const maxRetries = config.maxRetries ?? 3;
    const idempotencyKey = config.idempotencyKey ?? crypto.randomUUID();

    const headers: Record<string, string> = {
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey,
      ...(config.headers ?? {}),
    };

    let attempt = 0;

    while (attempt <= maxRetries) {
      this.circuitBreaker.checkCallAllowed();

      try {
        const response = await this.fetchWithTimeout(config.url, {
          method: config.method ?? 'POST',
          headers,
          body: config.body,
          timeoutMs: config.timeoutMs ?? 15000,
        });

        // Mutating success
        if (response.ok) {
          this.circuitBreaker.recordSuccess();
          const data = (await response.json()) as T;
          return {
            status: response.status,
            headers: this.extractHeaders(response),
            data,
            fromCache: false,
          };
        }

        // Handle Rate Limiting (429) and Server Downtime (503)
        if (response.status === 429 || response.status === 503) {
          this.circuitBreaker.recordFailure();
          const retryAfterMs = parseRetryAfterHeader(response.headers.get('Retry-After'));
          const sleepMs = retryAfterMs ?? calculateBackoffWithJitter(attempt);

          if (attempt === maxRetries) {
            throw new Error(`Server overloaded (HTTP ${response.status}). Retries exhausted.`);
          }

          await this.sleep(sleepMs);
          attempt++;
          continue;
        }

        // Client errors (4xx other than 429) should fail fast and NOT retry
        if (response.status >= 400 && response.status < 500) {
          throw new Error(`Client error: HTTP ${response.status}`);
        }

        // Server errors (500, 502, 504) trigger backoff and retry
        this.circuitBreaker.recordFailure();
      } catch (error) {
        this.circuitBreaker.recordFailure();

        if (attempt === maxRetries) {
          throw error;
        }
      }

      // Calculate jittered backoff before subsequent attempt
      const sleepMs = calculateBackoffWithJitter(attempt);
      await this.sleep(sleepMs);
      attempt++;
    }

    throw new Error(`Request to ${config.url} failed after ${maxRetries} retries`);
  }

  private async fetchWithTimeout(
    url: string,
    options: {
      method: string;
      headers: Record<string, string>;
      body?: string;
      timeoutMs: number;
    }
  ): Promise<Response> {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), options.timeoutMs);

    try {
      return await fetch(url, {
        method: options.method,
        headers: options.headers,
        body: options.body,
        signal: controller.signal,
      });
    } catch (error: unknown) {
      if (error instanceof Error && error.name === 'AbortError') {
        throw new NetworkTimeoutError(url, options.timeoutMs);
      }
      throw error;
    } finally {
      clearTimeout(timer);
    }
  }

  private extractHeaders(response: Response): Record<string, string> {
    const result: Record<string, string> = {};
    response.headers.forEach((value, key) => {
      result[key.toLowerCase()] = value;
    });
    return result;
  }

  private sleep(ms: number): Promise<void> {
    return new Promise((resolve) => setTimeout(resolve, ms));
  }
}

---

7. Diagnostic Profiling and Network Simulation

Engineering teams cannot verify mobile networking resilience through passive unit tests running on local localhost servers. Verification requires synthetic network simulation and hardware-level profiling.

Simulating Production Degradation in Development

Before shipping, test client applications under reproducible network degradation profiles using standard tooling:

1. Apple Network Link Conditioner (macOS / iOS):
   • Profile: "Very Bad Network": 10% packet loss, 500 ms upstream latency, 500 ms downstream latency, 56 kbps bandwidth.
   • Profile: "High Latency DNS": Injects 2,000 ms delays on DNS resolution while maintaining standard link bandwidth to verify socket timeout behavior.
2. Android Studio Emulator Cellular Controls:
   • Set network speed to GPRS / EDGE and signal strength to Poor.
   • Toggle the Airplane Mode switch during an active mutation sync to confirm that the local outbox safely recovers after unexpected socket termination.
3. HTTP Proxy Throttling (Charles Proxy / Proxyman / mitmproxy):
   • Configure SSL proxying to inject artificial HTTP 429 responses with Retry-After: 5 headers to verify client backoff adherence.
   • Intercept active file uploads and drop the connection after 50% completion to verify that chunks or idempotency mechanisms function correctly.

┌───────────────────────────────┐
│     Developer Workstation     │
│   (Network Link Conditioner)  │
│   10% Loss / 1000ms RTT       │
└───────────────────────────────┘
                │
                ▼
┌───────────────────────────────┐      Synthetic 429 & 503      ┌───────────────────────────────┐
│     Mobile Device / App       │ <───────────────────────────> │     Debugging HTTP Proxy      │
│   (Resilient HTTP Client)     │                               │  (Charles / Proxyman / mitm)  │
└───────────────────────────────┘                               └───────────────────────────────┘

Metrics to Observe in Production Telemetry

To identify network degradation before users file support tickets, emit structured client-side network metrics:

• Time to First Byte (TTFB): Measures radio channel setup and server processing latency. Spikes in TTFB often indicate cellular bufferbloat or overloaded backend gateways.
• Radio Tail Wakeups: Measure the number of discrete network bursts dispatched per hour. High burst counts with tiny payload volumes indicate chatty telemetry that is degrading user battery life.
• Outbox Dwell Time: Track the duration between an outbox mutation being written locally to disk and its eventual confirmation from the remote server.
• Stale-Serve Ratio: Track what percentage of user screen views were served instantly via SWR stale cache versus forced to wait on remote network responses.

---

8. Production Readiness Checklist

Before approving mobile networking code for production deployment, verify each requirement across the engineering stack:

Radio & Battery Efficiency

• [ ] Request Coalescing: Heartbeats, analytics, and non-urgent telemetry are batched and flushed in scheduled bursts rather than dispatched individually every few seconds.
• [ ] Background Scheduling: Long-running or heavy synchronization tasks utilize platform background schedulers (WorkManager on Android, BGProcessingTask on iOS) that align network wakes with system power states.
• [ ] Aggressive Prefetching: When the radio is active, related screen assets are prefetched in the same burst to maximize utility during the RRC tail state.

Egress & Captive Portal Handling

• [ ] Active Egress Probing: High-priority synchronization workflows verify upstream Internet egress (via HTTP 204 or dedicated ping endpoints) rather than trusting passive Wi-Fi link callbacks.
• [ ] Captive Portal Protection: JSON parsers validate response Content-Type headers before deserialization to prevent crashes on HTML login portal redirects.
• [ ] Connection Timeouts: Sockets enforce explicit application-level read and connect timeouts (typically 5–15 seconds) to avoid hanging indefinitely on half-open elevator sockets.

Outbox & Mutation Idempotency

• [ ] Durable Outbox Persistence: Mutating operations are committed to local disk storage (SQLite) before network dispatch, ensuring survival across process termination.
• [ ] Unique Idempotency Keys: All mutating requests (POST, PUT, PATCH, DELETE) attach a unique Idempotency-Key header (UUID v4).
• [ ] Backend Replay Support: The API backend transactionally stores and replays responses for duplicate idempotency keys without re-executing business logic.

Caching & Payload Optimization

• [ ] Stale-While-Revalidate: UI screens render immediately from local cache while revalidating asynchronously in the background.
• [ ] Conditional Validation: Read endpoints support ETag / If-None-Match and return HTTP 304 Not Modified with zero-byte bodies when data is unchanged.
• [ ] Payload Minimization: Payloads omit unused fields via sparse fieldsets or utilize compact binary encodings (Protobuf) to minimize transmission time on congested cells.

Modern Transport Protocols

• [ ] HTTP/3 (QUIC) Adoption: Core API endpoints support QUIC to eliminate transport-layer Head-of-Line blocking and enable seamless connection migration across Wi-Fi/cellular transitions.
• [ ] Singleflight Deduplication: Concurrent identical GET requests are coalesced into a single in-flight promise to avoid duplicate over-the-air transfers.

---

Conclusion: Architectural Discipline over Bandwidth Optimism

Mobile networking reliability is fundamentally an architectural discipline, not a matter of waiting for faster cellular networks. Even on modern 5G networks, physical radio constraints, carrier-configured RRC tail timers, bufferbloat, and network handovers will disrupt naive client implementations.

Resilient mobile applications are built on deliberate engineering principles:

1. Acknowledge the Radio: Treat the cellular modem as a power-hungry physical instrument. Batch transfers to avoid the tail energy trap, and coalesce requests to protect device batteries.
2. Decouple Mutation from Transport: Store user intent durably in a local outbox with idempotency keys before touching the network stack. Never let a dropped packet destroy user data.
3. Render Instantly, Revalidate in the Background: Use Stale-While-Revalidate and conditional ETags to ensure users never wait on a loading spinner to view cached content.
4. Desynchronize Failures: Implement exponential backoff with full jitter and client-side circuit breakers to prevent thundering herd disasters on your infrastructure.

By designing mobile clients for the hostile reality of cellular radio environments, engineering teams deliver software that feels instant, preserves battery life, and remains dependable in the hands of every user.