Documentation Index
Fetch the complete documentation index at: https://mintlify.com/visible/cruel/llms.txt
Use this file to discover all available pages before exploring further.
HTTP Chaos
HTTP chaos methods simulate HTTP-specific failures including status codes, rate limiting, and common server errors.
status
Returns specific HTTP status codes.
cruel.http.status(fn, code, rate)
The function to wrap with HTTP status errors
code
number | number[]
required
HTTP status code or array of codes to randomly select from
Probability of returning the status code (0 to 1). Default is 1 (100%)
Example
import { cruel } from 'cruel'
const fetchUser = async (id: string) => {
return fetch(`/api/users/${id}`).then(r => r.json())
}
// Always return 404
const notFoundFetch = cruel.http.status(fetchUser, 404)
try {
await notFoundFetch('123')
} catch (error) {
// CruelHttpError with status 404
console.error('Status:', error.status) // 404
}
rateLimit
Simulates HTTP 429 rate limiting errors.
cruel.http.rateLimit(fn, options)
The function to wrap with rate limiting
options
number | object
default:"0.1"
Rate limit probability (number) or configuration object:
rate: Probability of rate limit (0 to 1)retryAfter: Retry-After header value in seconds
Example
import { cruel } from 'cruel'
const apiCall = async (endpoint: string) => {
return fetch(`/api${endpoint}`).then(r => r.json())
}
// 10% chance of rate limiting
const rateLimitedAPI = cruel.http.rateLimit(apiCall, 0.1)
try {
await rateLimitedAPI('/data')
} catch (error) {
// CruelRateLimitError
console.error('Rate limited!')
}
serverError
Randomly returns 5xx server errors.
cruel.http.serverError(fn, rate)
The function to wrap with server errors
Probability of server error (0 to 1). Default is 0.1 (10%)
Behavior
Randomly returns one of:
500 Internal Server Error502 Bad Gateway503 Service Unavailable504 Gateway Timeout
Example
import { cruel } from 'cruel'
const submitForm = async (data: FormData) => {
return fetch('/api/submit', {
method: 'POST',
body: data
})
}
// 20% chance of server error
const flakySubmit = cruel.http.serverError(submitForm, 0.2)
try {
await flakySubmit(formData)
} catch (error) {
// CruelHttpError with status 500, 502, 503, or 504
console.error('Server error:', error.status)
}
clientError
Randomly returns 4xx client errors.
cruel.http.clientError(fn, rate)
The function to wrap with client errors
Probability of client error (0 to 1). Default is 0.1 (10%)
Behavior
Randomly returns one of:
400 Bad Request401 Unauthorized403 Forbidden404 Not Found
Example
import { cruel } from 'cruel'
const deleteResource = async (id: string) => {
return fetch(`/api/resources/${id}`, { method: 'DELETE' })
}
// 15% chance of client error
const flakyDelete = cruel.http.clientError(deleteResource, 0.15)
try {
await flakyDelete('123')
} catch (error) {
// CruelHttpError with status 400, 401, 403, or 404
if (error.status === 404) {
console.log('Resource not found')
}
}
badGateway
Returns HTTP 502 Bad Gateway errors.
cruel.http.badGateway(fn, rate)
Probability of 502 error (0 to 1). Default is 0.1 (10%)
Example
import { cruel } from 'cruel'
const proxyRequest = async (url: string) => {
return fetch(`/proxy?url=${url}`)
}
// 5% chance of bad gateway
const flakyProxy = cruel.http.badGateway(proxyRequest, 0.05)
try {
await flakyProxy('https://api.example.com')
} catch (error) {
// CruelHttpError with status 502
console.error('Bad gateway:', error.status)
}
serviceUnavailable
Returns HTTP 503 Service Unavailable errors.
cruel.http.serviceUnavailable(fn, rate)
Probability of 503 error (0 to 1). Default is 0.1 (10%)
Example
import { cruel } from 'cruel'
const healthCheck = async () => {
return fetch('/api/health')
}
// 8% chance service is unavailable
const flakyHealth = cruel.http.serviceUnavailable(healthCheck, 0.08)
try {
await flakyHealth()
} catch (error) {
// CruelHttpError with status 503
console.error('Service unavailable')
}
gatewayTimeout
Returns HTTP 504 Gateway Timeout errors.
cruel.http.gatewayTimeout(fn, rate)
Probability of 504 error (0 to 1). Default is 0.1 (10%)
Example
import { cruel } from 'cruel'
const longRunningQuery = async (query: string) => {
return fetch('/api/query', {
method: 'POST',
body: JSON.stringify({ query })
})
}
// 12% chance of gateway timeout
const timeoutQuery = cruel.http.gatewayTimeout(longRunningQuery, 0.12)
try {
await timeoutQuery('SELECT * FROM huge_table')
} catch (error) {
// CruelHttpError with status 504
console.error('Gateway timeout')
}
Combining HTTP Chaos
You can layer multiple HTTP chaos methods:
import { cruel } from 'cruel'
const apiCall = async () => { /* ... */ }
// Combine rate limiting + server errors
let chaotic = apiCall
chaotic = cruel.http.rateLimit(chaotic, 0.05)
chaotic = cruel.http.serverError(chaotic, 0.1)
chaotic = cruel.http.gatewayTimeout(chaotic, 0.08)
await chaotic()
Real-World Scenarios
Overloaded API
Flaky Gateway
Authentication Issues
// Simulate overloaded service
const overloadedAPI = cruel.http.serviceUnavailable(
cruel.http.rateLimit(apiCall, 0.2),
0.15
)
// Proxy with occasional gateway issues
const flakyGateway = cruel.http.badGateway(
cruel.http.gatewayTimeout(proxyCall, 0.1),
0.08
)
// Random auth failures
const authAPI = cruel.http.status(
apiCall,
[401, 403],
0.05
)
Error Objects
HTTP chaos methods throw specific error types:
try {
await flakyAPI()
} catch (error) {
if (error.name === 'CruelHttpError') {
console.log('HTTP status:', error.status)
console.log('Error code:', error.code) // 'CRUEL_HTTP'
}
if (error.name === 'CruelRateLimitError') {
console.log('Rate limited')
console.log('Retry after:', error.retryAfter, 'seconds')
}
}
Source Reference
HTTP methods are defined in index.ts:385-427.