Hands-on lab — Day 27: Rate Limits, Pagination, and Error Handling

#!/usr/bin/env bash
# Day 027 lab — Resilient API client (completed reference implementation).
#
# Demonstrates the three habits of consuming a real API robustly, against two
# free public test servers (no account or API key needed):
#   * https://httpbin.org           — returns any status you ask for
#   * https://jsonplaceholder.typicode.com — a paginated posts API
#
#   1. backoff_retry — retries a 429 / 5xx / network failure with an
#      exponential, jittered delay, up to a hard cap, then GIVES UP GRACEFULLY
#      (it never loops forever), honoring a Retry-After header when present.
#   2. decide        — reads a 500 and a 404 and decides which to retry
#      (retry 5xx server errors; do NOT retry 4xx client errors).
#   3. paginate      — walks two pages of posts with _page/_limit and collects
#      the results across pages.
#
# Run from the lab directory:  bash examples/resilient_client.sh
# Offline it degrades to a self-test of the backoff logic and still exits 0.
#
# Tunable via environment (used by the tests to run fast):
#   MAX_ATTEMPTS (default 5)  BASE_DELAY (default 1)  DELAY_CAP (default 8)
set -u

HTTPBIN="https://httpbin.org"
JSONPH="https://jsonplaceholder.typicode.com"
PROBE="https://example.com"

: "${MAX_ATTEMPTS:=5}"
: "${BASE_DELAY:=1}"
: "${DELAY_CAP:=8}"
: "${CURL_MAX_TIME:=15}"   # per-request timeout (a hung request must not stall us)
: "${STABLE_TRIES:=6}"     # how many times decide() rides through transient 5xx

# Set to non-empty by the offline self-test to simulate a failing server
# without any network call at all.
: "${STUB_STATUS:=}"

RETRIES_MADE=0   # set by backoff_retry so callers can report it

have_network() { curl -s -o /dev/null --max-time 12 "${PROBE}" 2>/dev/null; }

# Print the response class for a numeric status code.
classify_status() {
  case "$1" in
    2*)   echo "success" ;;
    429)  echo "rate-limited — back off and retry" ;;
    4*)   echo "client error — fix the request, do not retry" ;;
    5*)   echo "server error — retry with backoff" ;;
    *)    echo "no response — network failure or timeout" ;;
  esac
}

# Echo "CODE RETRY_AFTER" for a URL. If STUB_STATUS is set, return it without
# touching the network (used offline to prove the retry loop terminates).
fetch_status() {
  local url="$1"
  if [ -n "${STUB_STATUS}" ]; then
    echo "${STUB_STATUS} ${STUB_RETRY_AFTER:-}"
    return 0
  fi
  local tmp code ra
  tmp="$(mktemp)"
  code="$(curl -s -o /dev/null -D "${tmp}" -w '%{http_code}' --max-time "${CURL_MAX_TIME}" "${url}" 2>/dev/null)" || code="000"
  ra="$(grep -i '^retry-after:' "${tmp}" 2>/dev/null | head -1 | sed 's/[^0-9]//g')"
  rm -f "${tmp}"
  echo "${code:-000} ${ra}"
}

# Retry 429 / 5xx / network failures with exponential backoff + jitter, capped
# at MAX_ATTEMPTS. ALWAYS terminates: attempt increments every pass and the cap
# check returns. Honors Retry-After when the server sends it.
backoff_retry() {
  local url="$1" label="${2:-request}"
  local attempt=1 delay="${BASE_DELAY}" code ra wait
  RETRIES_MADE=0
  echo "  [${label}] up to ${MAX_ATTEMPTS} attempts, base ${BASE_DELAY}s, cap ${DELAY_CAP}s"
  while : ; do
    read -r code ra <<< "$(fetch_status "${url}")"
    echo "  attempt ${attempt}: HTTP ${code} ($(classify_status "${code}"))"

    case "${code}" in
      2*) echo "  -> success on attempt ${attempt}"; return 0 ;;
      429) : ;;                                   # retryable, fall through
      4*) echo "  -> client error; NOT retrying (fix the request)"; return 0 ;;
      5*|000) : ;;                                # retryable, fall through
    esac

    if [ "${attempt}" -ge "${MAX_ATTEMPTS}" ]; then
      echo "  -> reached the retry cap of ${MAX_ATTEMPTS}; giving up gracefully"
      return 0
    fi

    if [ -n "${ra}" ]; then
      wait="${ra}"
      echo "     obeying Retry-After: ${wait}s"
    else
      wait="$(awk -v d="${delay}" 'BEGIN { srand(); printf "%.2f", d + rand() }')"
      echo "     backoff: ~${delay}s (jittered to ${wait}s)"
    fi
    sleep "${wait}"

    RETRIES_MADE=$((RETRIES_MADE + 1))
    attempt=$((attempt + 1))
    delay=$((delay * 2))
    [ "${delay}" -gt "${DELAY_CAP}" ] && delay="${DELAY_CAP}"
  done
}

# Read a status, retrying ONLY on transient infrastructure failures — a
# no-response (000) or a gateway error (502/503/504) — to ride through the free
# test server's hiccups and reach its real, deliberate status. It does NOT
# retry a genuine 500, 4xx, or 2xx — that is the answer we came to read. (A 500
# is the origin's deliberate error; 502/503/504 are proxy/gateway errors that
# are usually transient.)
fetch_status_stable() {
  local url="$1" tries="${STABLE_TRIES}" i=1 code ra
  while [ "${i}" -le "${tries}" ]; do
    read -r code ra <<< "$(fetch_status "${url}")"
    case "${code}" in
      000|502|503|504) sleep 1 ;;               # transient — try again
      *) echo "${code} ${ra}"; return 0 ;;      # a real answer — take it
    esac
    i=$((i + 1))
  done
  echo "${code} ${ra}"
}

# Read one status and state the retry decision without acting on it.
decide() {
  local url="$1" code ra
  read -r code ra <<< "$(fetch_status_stable "${url}")"
  case "${code}" in
    5*) echo "  ${url}: HTTP ${code} — SERVER error -> RETRY with backoff" ;;
    429) echo "  ${url}: HTTP ${code} — rate-limited -> RETRY after waiting" ;;
    4*) echo "  ${url}: HTTP ${code} — CLIENT error -> do NOT retry" ;;
    2*) echo "  ${url}: HTTP ${code} — success -> nothing to retry" ;;
    *)  echo "  ${url}: no response -> network failure (retry only if idempotent)" ;;
  esac
}

# Walk two pages of posts with _page/_limit and collect the count across pages.
paginate() {
  local total=0 page body count
  for page in 1 2; do
    body="$(curl -s --max-time "${CURL_MAX_TIME}" "${JSONPH}/posts?_page=${page}&_limit=5" 2>/dev/null)" || body=""
    if [ -z "${body}" ]; then
      echo "  page ${page}: (could not fetch — transient error; try again)"
      continue
    fi
    count="$(printf '%s' "${body}" | python3 -c 'import sys, json; print(len(json.load(sys.stdin)))' 2>/dev/null)" || count=0
    echo "  page ${page}: ${count} items"
    total=$((total + count))
  done
  echo "  collected ${total} posts across 2 pages"
}

run_offline_selftest() {
  echo "Self-test: backoff against a stubbed always-503 server (no network)."
  STUB_STATUS=503 MAX_ATTEMPTS=3 BASE_DELAY=0 DELAY_CAP=0 backoff_retry "stub:always-fails" "selftest"
  echo "Self-test complete: the loop terminated after ${RETRIES_MADE} retries."
}

main() {
  echo "Day 027 — Resilient API client"
  echo "Test servers: ${HTTPBIN} and ${JSONPH}"

  if [ "${1:-}" = "--selftest" ]; then
    run_offline_selftest
    exit 0
  fi

  if ! have_network; then
    echo
    echo "OFFLINE: cannot reach ${PROBE}. Running the offline backoff self-test instead."
    run_offline_selftest
    echo "Reconnect to the internet and re-run for the live 429, error, and pagination demos."
    exit 0
  fi

  echo
  echo "== 1. Backoff against an endpoint that ALWAYS returns 429 =="
  backoff_retry "${HTTPBIN}/status/429" "429-demo"
  echo "   made ${RETRIES_MADE} retries before giving up"

  echo
  echo "== 2. Read a 500 and a 404 — decide whether to retry =="
  decide "${HTTPBIN}/status/500"
  decide "${HTTPBIN}/status/404"
  echo "   (a transient 502/503 in place of 500 is still a 5xx — same decision)"

  echo
  echo "== 3. Paginate posts with _page and _limit =="
  paginate

  echo
  echo "Done. Backoff terminated, errors were classified, and pages were collected."
}

main "$@"

lesson_id: D027
day: 27
kind: api-example
languages: [bash]
setup_commands:
  - cd labs/sections/computing-foundations/day-027-rate-limits-pagination-and-error-handling
run_commands:
  - bash examples/resilient_client.sh
  - bash starter/resilient_client.sh
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - 'git checkout -- starter/resilient_client.sh  # optional: reset your work'
requires_network: true
requires_api_key: false
estimated_minutes: 30
last_executed: '2026-07-12'
executed_on: 'macOS (curl 8.7.1, python3), online, bash tests/run_tests.sh → 17 checks, 0 failure(s), 0 skip(s)'

# Requirements — Day 027 lab

This lab needs only tools that ship with, or install in one step on, macOS and
Linux. There is **no API key and no account** — the test servers are free and
public.

## Required

- **bash** 3.2 or newer — preinstalled on macOS and Linux.
- **curl** — the HTTP client used for every request. Preinstalled on macOS and
  almost every Linux distribution. Check with `curl --version`.
- **python3** — used only to count the items in a JSON array (the pagination
  step). Check with `python3 --version`.
  - macOS: preinstalled, or `brew install python`.
  - Debian/Ubuntu: `sudo apt install python3`.
  - Fedora: `sudo dnf install python3`.
- Standard utilities `awk`, `sed`, `grep`, `mktemp` — all preinstalled.

## Network

- **Internet access** is required for the live parts (the 429/500/404 demos and
  pagination). The two public test servers are:
  - `https://httpbin.org` — returns any HTTP status you ask for.
  - `https://jsonplaceholder.typicode.com` — a free paginated posts API.
- **Offline is supported**: with no network, the script and the tests degrade
  to a self-test of the backoff logic (using a stubbed failing server, no
  network calls) and still exit 0. You lose only the live demonstrations.

## Windows

Use **WSL** (Windows Subsystem for Linux) and follow the Linux instructions, or
any environment providing `bash`, `curl`, and `python3`.

# Resilience worksheet — Day 027

Fill this in from a real run of your completed `starter/resilient_client.sh`
(or the reference `examples/resilient_client.sh`). The point is to prove your
client is genuinely resilient — that it terminates, classifies, and paginates —
not merely optimistic.

## 1. Backoff terminates (it does NOT loop forever)

- Retry cap you set (`MAX_ATTEMPTS`): ______
- Base delay you set (`BASE_DELAY`, seconds): ______
- How many **retries** did the backoff function make before giving up? ______
  (Read the `made N retries before giving up` line.)
- Status code the `/status/429` endpoint returned on your attempts: ______
  (It may show `503`/`504` if the shared test server's gateway was busy — the
  client treats those the same as `429`. Note whichever you saw.)

## 2. Classify: retry vs do not retry

- `/status/500` was classified as: ______________________  (retry? yes / no)
- `/status/404` was classified as: ______________________  (retry? yes / no)
- In one sentence, why is the 404 decision different from the 500 decision?

  ________________________________________________________________________

## 3. Pagination

- Items on page 1: ______
- Items on page 2: ______
- **Total posts collected across the 2 pages:** ______

## 4. Short reflection (4–6 sentences)

Explain, in your own words, why your backoff loop is **guaranteed to
terminate**, and what would go wrong if you removed the `MAX_ATTEMPTS` cap.
Mention what role jitter plays when many clients hit the same limit at once.

________________________________________________________________________

________________________________________________________________________

________________________________________________________________________

________________________________________________________________________

#!/usr/bin/env bash
# Day 027 lab — Resilient API client (STARTER).
#
# Your job: complete the four numbered exercises below, then run this file:
#     bash starter/resilient_client.sh
# Compare it against the finished reference in ../examples/resilient_client.sh
# only after you have tried each exercise yourself.
#
# The helper functions are provided. You fill in the four decisions that make a
# client resilient: the retry cap, the jitter, the retry decision, and the
# pagination URL. Each exercise ships with a safe placeholder so the file runs,
# marked with the sentinel FILL_ME so the tests can see what is unfinished.
set -u

HTTPBIN="https://httpbin.org"
JSONPH="https://jsonplaceholder.typicode.com"
PROBE="https://example.com"

# ---------------------------------------------------------------------------
# Exercise 1 — Give the retry loop a HARD CAP and a starting delay.
#   A retry loop with no cap becomes an infinite loop the moment a failure is
#   permanent. Set:
#     MAX_ATTEMPTS to 5   (stop after 5 tries)
#     BASE_DELAY   to 1   (first backoff wait, in seconds)
#     DELAY_CAP    to 8   (never wait longer than this)
#   Replace each 0 below.
# ---------------------------------------------------------------------------
MAX_ATTEMPTS=0   # FILL_ME (Exercise 1): set to 5
BASE_DELAY=0     # FILL_ME (Exercise 1): set to 1
DELAY_CAP=0      # FILL_ME (Exercise 1): set to 8

: "${STUB_STATUS:=}"
RETRIES_MADE=0

have_network() { curl -s -o /dev/null --max-time 12 "${PROBE}" 2>/dev/null; }

classify_status() {
  case "$1" in
    2*)  echo "success" ;;
    429) echo "rate-limited — back off and retry" ;;
    4*)  echo "client error — fix the request, do not retry" ;;
    5*)  echo "server error — retry with backoff" ;;
    *)   echo "no response — network failure or timeout" ;;
  esac
}

fetch_status() {
  local url="$1"
  if [ -n "${STUB_STATUS}" ]; then echo "${STUB_STATUS} ${STUB_RETRY_AFTER:-}"; return 0; fi
  local tmp code ra
  tmp="$(mktemp)"
  code="$(curl -s -o /dev/null -D "${tmp}" -w '%{http_code}' --max-time 15 "${url}" 2>/dev/null)" || code="000"
  ra="$(grep -i '^retry-after:' "${tmp}" 2>/dev/null | head -1 | sed 's/[^0-9]//g')"
  rm -f "${tmp}"
  echo "${code:-000} ${ra}"
}

backoff_retry() {
  local url="$1" label="${2:-request}"
  local attempt=1 delay="${BASE_DELAY}" code ra wait
  RETRIES_MADE=0
  echo "  [${label}] up to ${MAX_ATTEMPTS} attempts, base ${BASE_DELAY}s, cap ${DELAY_CAP}s"
  while : ; do
    read -r code ra <<< "$(fetch_status "${url}")"
    echo "  attempt ${attempt}: HTTP ${code} ($(classify_status "${code}"))"

    case "${code}" in
      2*) echo "  -> success on attempt ${attempt}"; return 0 ;;
      429) : ;;
      4*) echo "  -> client error; NOT retrying (fix the request)"; return 0 ;;
      5*|000) : ;;
    esac

    if [ "${attempt}" -ge "${MAX_ATTEMPTS}" ]; then
      echo "  -> reached the retry cap of ${MAX_ATTEMPTS}; giving up gracefully"
      return 0
    fi

    if [ -n "${ra}" ]; then
      wait="${ra}"
      echo "     obeying Retry-After: ${wait}s"
    else
      # -----------------------------------------------------------------------
      # Exercise 2 — Add JITTER to the backoff wait.
      #   A fixed wait makes a crowd of clients retry in lockstep and stampede
      #   the server again. Replace the line below so `wait` becomes the delay
      #   PLUS a small random fraction of a second, e.g.:
      #     wait="$(awk -v d="${delay}" 'BEGIN { srand(); printf "%.2f", d + rand() }')"
      # -----------------------------------------------------------------------
      wait="${delay}"   # FILL_ME (Exercise 2): add jitter to this delay
      echo "     backoff: ~${delay}s (waiting ${wait}s)"
    fi
    sleep "${wait}"

    RETRIES_MADE=$((RETRIES_MADE + 1))
    attempt=$((attempt + 1))
    delay=$((delay * 2))
    [ "${delay}" -gt "${DELAY_CAP}" ] && delay="${DELAY_CAP}"
  done
}

fetch_status_stable() {
  local url="$1" tries=6 i=1 code ra
  while [ "${i}" -le "${tries}" ]; do
    read -r code ra <<< "$(fetch_status "${url}")"
    case "${code}" in
      000|502|503|504) sleep 1 ;;
      *) echo "${code} ${ra}"; return 0 ;;
    esac
    i=$((i + 1))
  done
  echo "${code} ${ra}"
}

decide() {
  local url="$1" code ra
  read -r code ra <<< "$(fetch_status_stable "${url}")"
  # ---------------------------------------------------------------------------
  # Exercise 3 — Classify the status and state the retry DECISION.
  #   Fill the two branches marked FILL_ME so that:
  #     a 5xx  -> "SERVER error -> RETRY with backoff"
  #     a 4xx  -> "CLIENT error -> do NOT retry"
  # ---------------------------------------------------------------------------
  case "${code}" in
    5*) echo "  ${url}: HTTP ${code} — FILL_ME (Exercise 3): SERVER error -> RETRY with backoff" ;;
    429) echo "  ${url}: HTTP ${code} — rate-limited -> RETRY after waiting" ;;
    4*) echo "  ${url}: HTTP ${code} — FILL_ME (Exercise 3): CLIENT error -> do NOT retry" ;;
    2*) echo "  ${url}: HTTP ${code} — success -> nothing to retry" ;;
    *)  echo "  ${url}: no response -> network failure (retry only if idempotent)" ;;
  esac
}

paginate() {
  local total=0 page body count
  for page in 1 2; do
    # -------------------------------------------------------------------------
    # Exercise 4 — Build the PAGINATED URL and collect across pages.
    #   Replace the URL below so it requests page ${page} with 5 items:
    #     "${JSONPH}/posts?_page=${page}&_limit=5"
    #   (The starter fetches only page 1 with no limit, so it does not paginate.)
    # -------------------------------------------------------------------------
    body="$(curl -s --max-time 15 "${JSONPH}/posts?_limit=5" 2>/dev/null)" || body=""   # FILL_ME (Exercise 4): add _page=${page}
    if [ -z "${body}" ]; then echo "  page ${page}: (could not fetch)"; continue; fi
    count="$(printf '%s' "${body}" | python3 -c 'import sys, json; print(len(json.load(sys.stdin)))' 2>/dev/null)" || count=0
    echo "  page ${page}: ${count} items"
    total=$((total + count))
  done
  echo "  collected ${total} posts across 2 pages"
}

run_offline_selftest() {
  echo "Self-test: backoff against a stubbed always-503 server (no network)."
  STUB_STATUS=503 backoff_retry "stub:always-fails" "selftest"
  echo "Self-test complete: the loop terminated after ${RETRIES_MADE} retries."
}

main() {
  echo "Day 027 — Resilient API client (starter)"
  if [ "${1:-}" = "--selftest" ]; then run_offline_selftest; exit 0; fi
  if ! have_network; then
    echo "OFFLINE: cannot reach ${PROBE}. Running the offline backoff self-test instead."
    run_offline_selftest
    exit 0
  fi
  echo; echo "== 1. Backoff against an endpoint that ALWAYS returns 429 =="
  backoff_retry "${HTTPBIN}/status/429" "429-demo"
  echo "   made ${RETRIES_MADE} retries before giving up"
  echo; echo "== 2. Read a 500 and a 404 — decide whether to retry =="
  decide "${HTTPBIN}/status/500"
  decide "${HTTPBIN}/status/404"
  echo; echo "== 3. Paginate posts with _page and _limit =="
  paginate
  echo; echo "Done."
}

main "$@"

#!/usr/bin/env bash
# Tests for the Day 027 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# Two kinds of checks:
#   * Structure checks always run and must pass (files present, both scripts
#     parse, the example defines the resilient pieces, the starter names its
#     four exercises).
#   * Behavior checks. OFFLINE, the network is SKIPPED, but the backoff logic
#     is still verified to TERMINATE via a stubbed always-failing call (the
#     --selftest path uses no network). ONLINE, the example is run fast and its
#     backoff must give up (not loop forever) and its pagination must collect
#     the expected count.
#
# Every script run is wrapped in a watchdog: if it does not finish within the
# time limit it is killed and the check FAILS — this is how we prove the retry
# loop can never spin forever. The script exits 0 when no check failed.
set -u

lab_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
example="${lab_dir}/examples/resilient_client.sh"
starter="${lab_dir}/starter/resilient_client.sh"
worksheet="${lab_dir}/starter/resilience-worksheet.md"
PROBE="https://example.com"

failures=0
checks=0
skips=0
pass() { checks=$((checks + 1)); echo "  ok:   $1"; }
fail() { checks=$((checks + 1)); failures=$((failures + 1)); echo "  FAIL: $1"; }
skip() { skips=$((skips + 1)); echo "  skip: $1"; }

# run_guarded <seconds> <outfile> <command...>  -> returns command's exit code,
# or 137 if the watchdog had to kill it (i.e. it did not terminate in time).
run_guarded() {
  local secs="$1" outf="$2"; shift 2
  "$@" > "${outf}" 2>&1 &
  local pid=$!
  ( sleep "${secs}"; kill -9 "${pid}" 2>/dev/null ) &
  local watchdog=$!
  wait "${pid}" 2>/dev/null; local rc=$?
  kill "${watchdog}" 2>/dev/null; wait "${watchdog}" 2>/dev/null
  return "${rc}"
}

echo "== Structure checks =="
[ -f "${example}" ] && pass "example script exists" || fail "example script missing"
[ -f "${starter}" ] && pass "starter script exists" || fail "starter script missing"
[ -f "${worksheet}" ] && pass "resilience worksheet exists" || fail "worksheet missing"

for needle in "backoff_retry" "MAX_ATTEMPTS" "Retry-After" "giving up gracefully" "_page=" "_limit="; do
  if grep -q -- "${needle}" "${example}"; then pass "example uses '${needle}'"; else fail "example missing '${needle}'"; fi
done

ex_count="$(grep -cE 'Exercise [1-4]' "${starter}" 2>/dev/null || true)"
if [ "${ex_count:-0}" -ge 4 ]; then pass "starter names its four exercises"; else fail "starter should name 4 exercises (found ${ex_count:-0})"; fi

bash -n "${example}" 2>/dev/null && pass "example has valid bash syntax" || fail "example has a syntax error"
bash -n "${starter}" 2>/dev/null && pass "starter has valid bash syntax" || fail "starter has a syntax error"

echo
echo "== Backoff termination (always, no network needed) =="
# The offline self-test drives the retry loop with a stubbed always-503 server
# and MUST terminate on its own well within the watchdog window.
out="$(mktemp)"
run_guarded 30 "${out}" bash "${example}" --selftest
rc=$?
if [ "${rc}" -eq 137 ]; then
  fail "backoff self-test did NOT terminate (watchdog had to kill it — infinite loop!)"
elif grep -q "giving up gracefully" "${out}" && grep -q "loop terminated" "${out}"; then
  pass "backoff self-test terminates and gives up gracefully (no network)"
else
  fail "backoff self-test did not report a graceful give-up"
  sed 's/^/    /' "${out}"
fi
rm -f "${out}"

echo
echo "== Live behavior checks =="
if ! curl -s -o /dev/null --max-time 12 "${PROBE}" 2>/dev/null; then
  skip "no network access — skipping live 429/pagination checks (expected offline)"
else
  pass "network reachable (${PROBE} responded)"
  out="$(mktemp)"
  # Run fast: tiny delays so the capped backoff finishes quickly. The watchdog
  # still guarantees termination even if the test server is slow.
  # Short per-request timeout + few stable-retries keeps the run bounded even
  # when the shared test server is slow, so the watchdog only ever fires on a
  # genuine non-terminating loop (not on a slow network).
  MAX_ATTEMPTS=3 BASE_DELAY=0 DELAY_CAP=0 CURL_MAX_TIME=4 STABLE_TRIES=2 \
    run_guarded 90 "${out}" bash "${example}"
  rc=$?
  if [ "${rc}" -eq 137 ]; then
    fail "example did NOT terminate within 90s (watchdog killed it)"
    sed 's/^/    /' "${out}"
  else
    pass "example run terminated on its own"
    grep -q "giving up gracefully" "${out}" \
      && pass "backoff gave up gracefully after its cap" \
      || fail "expected a 'giving up gracefully' line"
    collected="$(sed -n 's/.*collected \([0-9]\{1,\}\) posts across 2 pages/\1/p' "${out}" | head -1)"
    case "${collected}" in
      10) pass "pagination collected 10 posts across 2 pages" ;;
      '' ) skip "pagination count not found — test server (jsonplaceholder) may be transiently down" ;;
      *) fail "pagination should collect 10 posts (got '${collected}')" ;;
    esac
  fi
  rm -f "${out}"
fi

echo
echo "${checks} checks, ${failures} failure(s), ${skips} skip(s)."
[ "${failures}" -eq 0 ]