undici 7.29.0: request, stream, Client

# CSX Sample Notes: undici core request, streaming, connection pooling & MockAgent isolation

## 1. Search Result
`search_known_solution` identified existing sample `sha256:58c13cc15f12e5f7e9c8dab8a50ff21446e25ffae7a78a5b505a95eae5b06e5e` covering fetch body consumption and cross-realm Request brand check traps for `undici@7.29.0`. This sample extends coverage to core Undici dispatcher architectures: high-performance `undici.request`, stream handling via `undici.stream`, connection pooling with `undici.Pool` / `undici.Client`, and offline testing isolation using `undici.MockAgent`.

## 2. What a Model Would Have Written
A naive model would:
1. Pass a custom object with `{ write, end, abort }` methods to `undici.stream`'s factory callback instead of returning an actual `stream.Writable` instance.
2. Treat `undici.request` response `body` as a standard Node stream without utilizing built-in async methods like `body.json()` or `body.text()`.
3. Omit `mockAgent.disableNetConnect()` during mock testing, risking silent real network fallback or hangs when interceptors fail to match query/headers.
4. Assume `assertNoPendingInterceptors` returns a boolean instead of throwing an error when unconsumed interceptors remain.
5. Fail to clean up `Pool` and `MockAgent` instances, leaving event loops or timers unclosed.

## 3. How the Wrong Version Fails
1. Returning a plain object instead of a `stream.Writable` from `undici.stream` factory throws `InvalidReturnValueError: expected Writable` (`code: 'UND_ERR_INVALID_RETURN_VALUE'`).
2. Mismatched query parameters (e.g. forgetting query string objects or headers in `.intercept()`) with `disableNetConnect()` causes `MockNotMatchedError: Mock not matched: GET http://api.example.com/v1/users` instead of returning mock responses.
3. Checking `if (!mockAgent.assertNoPendingInterceptors())` never detects pending interceptors because `assertNoPendingInterceptors()` throws an `UndiciError` on failure rather than returning `false`.
4. Unclosed pools or clients retain open sockets preventing test processes from terminating cleanly.

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:npm/undici@7.29.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/undici@7.29.0
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:1e8e0a125bd7d7560415f2738e9a4aa16745bf60de3cda0a4c16ce69883b55ae","constraints":{"executionContext":"node"},"contract":["undici.request executes HTTP requests with method, headers, and json body and reads response JSON","undici.stream processes streaming HTTP response data with custom factory callback","undici.Pool and undici.Client manage connection pool lifecycle and execute dispatches","undici.MockAgent intercepts HTTP requests with headers and query matching and rejects unmocked requests when net connect is disabled","undici.MockAgent.assertNoPendingInterceptors verifies all registered interceptors are fulfilled and throws on pending interceptors"],"goal":"verify pkg:npm/undici@7.29.0","kind":"HOW","packages":["pkg:npm/undici@7.29.0"],"schemaVersion":1,"symbols":["request","stream","Client","Pool","MockAgent","setGlobalDispatcher","errors.MockNotMatchedError"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/undici@7.29.0"],"schemaVersion":1,"subject":"pkg:npm/undici@7.29.0","symbols":["request","stream","Client","Pool","MockAgent","setGlobalDispatcher","errors.MockNotMatchedError"],"verifierAdapter":"node-typescript@1"}

{
  "name": "csx-sample-undici-core",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "csx-sample-undici-core",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "undici": "7.29.0"
      }
    },
    "node_modules/undici": {
      "version": "7.29.0",
      "resolved": "https://registry.npmjs.org/undici/-/undici-7.29.0.tgz",
      "integrity": "sha512-IDxfleLmmbSskfWSUATiN1nfn2rDuvnMOqb5CWR92iIfojA0Ud+ulOAAEQ57LPr9rWmsreUyf5lwyao+7GNNVw==",
      "license": "MIT",
      "engines": {
        "node": ">=20.18.1"
      }
    }
  }
}

{
  "name": "csx-sample-undici-core",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "undici": "7.29.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/undici@7.29.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/undici@7.29.0"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

import { request, stream, Client, Pool, MockAgent, errors } from 'undici';
import { Writable } from 'node:stream';

/**
 * Executes an HTTP JSON request using undici.request.
 * @param {string|URL} url
 * @param {object} options
 * @param {object} [dispatcher]
 * @returns {Promise<{ statusCode: number, headers: object, data: any }>}
 */
export async function executeJsonRequest(url, options = {}, dispatcher = undefined) {
  const reqOptions = {
    method: options.method || 'GET',
    headers: {
      'content-type': 'application/json',
      ...(options.headers || {})
    },
    dispatcher
  };

  if (options.body !== undefined) {
    reqOptions.body = typeof options.body === 'string' ? options.body : JSON.stringify(options.body);
  }

  const response = await request(url, reqOptions);
  const data = await response.body.json();

  return {
    statusCode: response.statusCode,
    headers: response.headers,
    data
  };
}

/**
 * Streams HTTP response data into a concatenated buffer/string using undici.stream.
 * @param {string|URL} url
 * @param {object} options
 * @param {object} [dispatcher]
 * @returns {Promise<{ statusCode: number, text: string }>}
 */
export async function streamResponseToText(url, options = {}, dispatcher = undefined) {
  let capturedStatusCode = 0;
  const chunks = [];
  const writable = new Writable({
    write(chunk, encoding, callback) {
      chunks.push(chunk);
      callback();
    }
  });

  const reqOptions = {
    method: options.method || 'GET',
    headers: options.headers || {},
    dispatcher,
    opaque: { target: 'stream-test' }
  };

  await stream(
    url,
    reqOptions,
    ({ statusCode, headers }) => {
      capturedStatusCode = statusCode;
      return writable;
    }
  );

  return {
    statusCode: capturedStatusCode,
    text: Buffer.concat(chunks).toString('utf8')
  };
}

/**
 * Creates an offline-isolated MockAgent with network disabled.
 * @returns {MockAgent}
 */
export function createIsolatedMockAgent() {
  const agent = new MockAgent();
  agent.disableNetConnect();
  return agent;
}

/**
 * Dispatches requests with connection pooling using undici.Pool.
 * @param {string|URL} origin
 * @param {number} connections
 * @returns {Pool}
 */
export function createConnectionPool(origin, connections = 2) {
  return new Pool(origin, {
    connections,
    keepAliveTimeout: 1000
  });
}

import http from 'node:http';
import { strict as assert } from 'node:assert';
import { request, stream, Client, Pool, MockAgent, errors } from 'undici';
import {
  executeJsonRequest,
  streamResponseToText,
  createIsolatedMockAgent,
  createConnectionPool
} from '../src/index.mjs';

// --- Part 1: Local HTTP server for request, stream, Pool, and Client testing ---
const server = http.createServer((req, res) => {
  let body = '';
  req.on('data', (chunk) => { body += chunk; });
  req.on('end', () => {
    if (req.url === '/echo' && req.method === 'POST') {
      res.writeHead(200, { 'content-type': 'application/json' });
      res.end(JSON.stringify({ ok: true, received: JSON.parse(body) }));
      return;
    }

    if (req.url === '/stream') {
      res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' });
      res.write('part1-');
      res.write('part2-');
      res.end('part3');
      return;
    }

    if (req.url === '/ping') {
      res.writeHead(200, { 'content-type': 'application/json' });
      res.end(JSON.stringify({ pong: true }));
      return;
    }

    res.writeHead(404, { 'content-type': 'text/plain' });
    res.end('Not Found');
  });
});

await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
const port = server.address().port;
const baseUrl = `http://127.0.0.1:${port}`;

try {
  // --- Part 2: undici.request JSON payload and parsing ---
  const payload = { action: 'test', count: 123 };
  const jsonResult = await executeJsonRequest(`${baseUrl}/echo`, {
    method: 'POST',
    body: payload
  });
  assert.equal(jsonResult.statusCode, 200, 'undici.request must return status 200');
  assert.deepEqual(jsonResult.data, { ok: true, received: payload }, 'Response data must match parsed JSON');

  // Direct undici.request response inspection
  const directRes = await request(`${baseUrl}/echo`, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ direct: true })
  });
  assert.equal(directRes.statusCode, 200);
  const directData = await directRes.body.json();
  assert.deepEqual(directData, { ok: true, received: { direct: true } });

  // --- Part 3: undici.stream streaming response processing ---
  const streamResult = await streamResponseToText(`${baseUrl}/stream`);
  assert.equal(streamResult.statusCode, 200, 'undici.stream must return status 200');
  assert.equal(streamResult.text, 'part1-part2-part3', 'Streamed chunks must match assembled text');

  // --- Part 4: undici.Pool and undici.Client lifecycle & dispatch ---
  const pool = createConnectionPool(baseUrl, 2);
  const [resA, resB] = await Promise.all([
    pool.request({ path: '/ping', method: 'GET' }),
    pool.request({ path: '/ping', method: 'GET' })
  ]);
  assert.equal(resA.statusCode, 200);
  assert.equal(resB.statusCode, 200);
  const dataA = await resA.body.json();
  const dataB = await resB.body.json();
  assert.deepEqual(dataA, { pong: true });
  assert.deepEqual(dataB, { pong: true });
  await pool.close();

  const client = new Client(baseUrl);
  const clientRes = await client.request({ path: '/ping', method: 'GET' });
  assert.equal(clientRes.statusCode, 200);
  const clientData = await clientRes.body.json();
  assert.deepEqual(clientData, { pong: true });
  await client.close();

  // --- Part 5: MockAgent with query/header matching and offline isolation ---
  const mockAgent = createIsolatedMockAgent();
  const mockClient = mockAgent.get('http://api.example.com');

  mockClient
    .intercept({
      path: '/v1/users',
      method: 'GET',
      query: { active: 'true', limit: '10' },
      headers: { authorization: 'Bearer token-123' }
    })
    .reply(200, { users: [{ id: 1, name: 'Alice' }] }, {
      headers: { 'content-type': 'application/json' }
    });

  // Dispatched mock request matching query and headers
  const mockRes = await request('http://api.example.com/v1/users?active=true&limit=10', {
    method: 'GET',
    headers: { authorization: 'Bearer token-123' },
    dispatcher: mockAgent
  });
  assert.equal(mockRes.statusCode, 200, 'MockAgent must return 200 for matching interceptor');
  const mockData = await mockRes.body.json();
  assert.deepEqual(mockData, { users: [{ id: 1, name: 'Alice' }] });

  // assertNoPendingInterceptors succeeds when all interceptors have been dispatched
  assert.doesNotThrow(() => {
    mockAgent.assertNoPendingInterceptors();
  }, 'assertNoPendingInterceptors must not throw after interceptor fulfilled');

  // Register an unused interceptor and verify assertNoPendingInterceptors throws
  mockClient
    .intercept({ path: '/unused', method: 'GET' })
    .reply(200, { ok: false });

  assert.throws(
    () => { mockAgent.assertNoPendingInterceptors(); },
    (err) => {
      assert(err instanceof Error, 'Pending interceptor check must throw');
      return true;
    },
    'assertNoPendingInterceptors must throw when pending interceptor remains'
  );

  // Clear or consume remaining interceptors by closing
  await mockAgent.close();

  // Test disableNetConnect throws MockNotMatchedError on unintercepted host
  const freshMockAgent = createIsolatedMockAgent();
  await assert.rejects(
    async () => {
      await request('http://unmocked.example.com/data', {
        method: 'GET',
        dispatcher: freshMockAgent
      });
    },
    (err) => {
      assert(err.name === 'MockNotMatchedError' || err instanceof errors.MockNotMatchedError || err.code === 'UND_ERR_MOCK_NOT_MATCHED',
        `Expected MockNotMatchedError, got ${err.name} (${err.message})`);
      return true;
    },
    'Unintercepted requests with disableNetConnect must throw MockNotMatchedError'
  );
  await freshMockAgent.close();

  console.log('CONTRACT PASS: undici request, stream, Pool, Client, and MockAgent semantics verified');
} finally {
  server.close();
}