Network Chaos

Simulate network failures, latency, packet loss, and connectivity issues

Network Chaos

Network chaos methods simulate real-world network conditions including latency, packet loss, disconnections, and DNS failures.

latency

Adds network latency to function execution.

cruel.network.latency(fn, ms)

fn · function · required

The function to wrap with network latency

ms · number | [number, number] · required

Latency in milliseconds. Can be fixed or a range [min, max]

Example

Fixed Latency

import { cruel } from 'cruel'

const fetchData = async () => {
  return fetch('/api/data').then(r => r.json())
}

// Add 200ms network latency
const slowFetch = cruel.network.latency(fetchData, 200)

await slowFetch() // Takes at least 200ms

---

packetLoss

Simulates network packet loss.

cruel.network.packetLoss(fn, rate)

fn · function · required

The function to wrap with packet loss simulation

rate · number · default: "0.1"

Probability of packet loss (0 to 1). Default is 0.1 (10%)

Example

import { cruel } from 'cruel'

const sendMessage = async (msg: string) => {
  return websocket.send(msg)
}

// 5% packet loss rate
const lossyConnection = cruel.network.packetLoss(sendMessage, 0.05)

try {
  await lossyConnection('Hello')
} catch (error) {
  // CruelNetworkError: network packet_loss
  console.error('Packet lost:', error)
}

---

disconnect

Simulates random network disconnections.

cruel.network.disconnect(fn, rate)

fn · function · required

The function to wrap with disconnect simulation

rate · number · default: "0.05"

Probability of disconnection (0 to 1). Default is 0.05 (5%)

Example

import { cruel } from 'cruel'

const syncData = async () => {
  return api.sync()
}

// 10% chance of disconnect
const unreliableSync = cruel.network.disconnect(syncData, 0.1)

try {
  await unreliableSync()
} catch (error) {
  // CruelNetworkError: network disconnect
  if (error.code === 'CRUEL_NETWORK_DISCONNECT') {
    console.log('Connection lost, retrying...')
  }
}

---

dns

Simulates DNS resolution failures.

cruel.network.dns(fn, rate)

fn · function · required

The function to wrap with DNS failure simulation

rate · number · default: "0.02"

Probability of DNS failure (0 to 1). Default is 0.02 (2%)

Example

import { cruel } from 'cruel'

const lookupService = async (hostname: string) => {
  return fetch(`https://${hostname}/api`)
}

// 3% DNS failure rate
const flakyLookup = cruel.network.dns(lookupService, 0.03)

try {
  await flakyLookup('api.example.com')
} catch (error) {
  // CruelNetworkError: network dns_failure
  console.error('DNS resolution failed:', error)
}

---

bandwidth

Simulates bandwidth throttling based on data size.

cruel.network.bandwidth(fn, kbps)

fn · AsyncFn<string> · required

Function that returns a string response

kbps · number · default: "256"

Bandwidth limit in kilobits per second. Default is 256 kbps

Example

Slow Connection

import { cruel } from 'cruel'

const downloadFile = async (url: string): Promise<string> => {
  const response = await fetch(url)
  return response.text()
}

// Simulate 56k modem (56 kbps)
const dialupDownload = cruel.network.bandwidth(downloadFile, 56)

const content = await dialupDownload('/large-file.txt')
// Delay calculated based on content size

The delay is calculated as: (bytes × 8 × 1000) / (kbps × 1024) milliseconds

---

slow

Simulates a slow network with random high latency.

cruel.network.slow(fn)

fn · function · required

The function to wrap with slow network simulation

Behavior

Applies:

• 1000-5000ms delay
• Up to 2000ms jitter

Example

import { cruel } from 'cruel'

const loadPage = async (url: string) => {
  return fetch(url).then(r => r.text())
}

// Simulate very slow network
const slowLoad = cruel.network.slow(loadPage)

await slowLoad('/page') // Takes 1-7 seconds

---

unstable

Simulates an unstable network with random disconnects, packet loss, and variable latency.

cruel.network.unstable(fn)

fn · function · required

The function to wrap with unstable network simulation

Behavior

Applies:

• 10% disconnect rate
• 5% packet loss rate
• 100-2000ms random delay

Example

import { cruel } from 'cruel'

const makeRequest = async (endpoint: string) => {
  return fetch(endpoint).then(r => r.json())
}

// Simulate unstable WiFi/mobile connection
const unstableRequest = cruel.network.unstable(makeRequest)

try {
  const data = await unstableRequest('/api/users')
  console.log('Success:', data)
} catch (error) {
  // May disconnect or lose packets
  console.error('Network error:', error)
}

---

offline

Simulates complete network offline state.

cruel.network.offline(fn)

fn · function · required

The function to wrap (will always fail)

Example

import { cruel } from 'cruel'

const checkConnection = async () => {
  return fetch('/api/ping')
}

// Always throws network offline error
const offlineCheck = cruel.network.offline(checkConnection)

try {
  await offlineCheck()
} catch (error) {
  // CruelNetworkError: network offline
  console.log('No network connection')
}

offline always throws a network error. Use this to test offline-first features and error handling.

---

Combining Network Chaos

You can chain multiple network chaos methods:

import { cruel } from 'cruel'

const apiCall = async () => { /* ... */ }

// Combine latency + packet loss + disconnect
let chaotic = apiCall
chaotic = cruel.network.latency(chaotic, [100, 300])
chaotic = cruel.network.packetLoss(chaotic, 0.05)
chaotic = cruel.network.disconnect(chaotic, 0.02)

await chaotic()

Real-World Scenarios

Mobile Network

// Simulate poor mobile connection
const mobileFetch = cruel.network.unstable(
  cruel.network.bandwidth(fetchData, 128)
)

Satellite Connection

// High latency satellite link
const satelliteFetch = cruel.network.latency(
  cruel.network.packetLoss(fetchData, 0.03),
  [500, 800]
)

Flaky WiFi

// Unstable WiFi with occasional disconnects
const wifiFetch = cruel.network.unstable(fetchData)

Source Reference

Network methods are defined in index.ts:326-383.