Talkback HTTP Proxy

4.2.0 verified Thu Apr 23 auth: no javascript

Talkback is a Node.js HTTP proxy library that records and plays back HTTP requests, effectively acting as a 'VCR for HTTP'. It is currently at version 4.2.0 and appears to be actively maintained, with recent updates and continuous integration setup on GitHub. This tool is designed to accelerate integration tests by allowing applications to run against mocked servers, eliminating the need for live external service calls during development or CI/CD pipelines. A key differentiator is its flexibility: it can be run as a standalone HTTP server in its own process or integrated directly into an application as a request handler. It automatically records new requests when no matching tape is found and then serves those recorded 'tapes' for subsequent, identical requests, providing consistent and fast responses for testing and development environments.

Common errors

error Error: listen EADDRINUSE: address already in use :::5544 ↓

cause The specified port (e.g., 5544) for the Talkback server is already being used by another process.

fix

Change the port option in your Talkback configuration to an available port, or ensure no other process is running on the desired port before starting Talkback. You can find and kill processes using lsof -i :<port> (macOS/Linux) or netstat -ano | findstr :<port> (Windows).

error TypeError: talkback is not a function ↓

cause This error often occurs when attempting to call `talkback()` as a function after a CommonJS `require()` when the package might be primarily designed for ESM, or vice-versa, or if the import path is incorrect.

fix

Ensure you are using the correct import syntax for your project's module system. If using ESM (type: "module" in package.json), use import talkback from 'talkback';. If using CommonJS, use const talkback = require('talkback');. The provided example uses require but modern Node.js setups may prefer import.

error Error: ENOTDIR: not a directory, open './my-tapes/...' or Error: ENOENT: no such file or directory, stat './my-tapes/' ↓

cause Talkback's `path` option points to a directory that does not exist or is inaccessible for reading/writing tapes.

fix

Ensure the directory specified in the path option (./my-tapes in the example) exists and that the Node.js process has appropriate read/write permissions for that directory. You might need to create the directory programmatically or manually before starting Talkback, e.g., fs.mkdirSync(tapesPath, { recursive: true });

Warnings

gotcha Carefully configure `record` and `fallbackMode` options. If `record` is disabled (e.g., `RecordMode.DISABLED`) and `fallbackMode` is set to `FallbackMode.NOT_FOUND`, any unmatched requests will result in a 404. This is intentional for strict testing but can cause unexpected failures if tapes are incomplete or request matching is too strict. ↓

fix Review the documentation for `RecordMode` and `FallbackMode`. For development, `RecordMode.NEW` is often a good starting point to automatically create tapes. For CI, consider `FallbackMode.ERROR` for strict failure on missing tapes.

gotcha Incorrect configuration of `allowHeaders` or `ignoreHeaders` can lead to tapes not being matched correctly. Headers are crucial for request uniqueness, and misconfigured lists can either ignore important headers (leading to false positives) or include volatile headers (leading to false negatives). ↓

fix Start with default `ignoreHeaders` and incrementally add specific headers to `allowHeaders` only if they are truly part of the request's unique identifier. Ensure `content-type` and `content-encoding` are considered if body decoding is necessary.

gotcha Proxying HTTPS traffic (i.e., when the `host` is `https://...`) requires proper handling of SSL certificates. Self-signed certificates or specific corporate proxy setups might cause `DEPTH_ZERO_SELF_SIGNED_CERT` or similar errors if Node.js does not trust the upstream certificate. ↓

fix If encountering certificate errors, configure the `https` option in Talkback to provide custom CA certificates (`ca`), client certificates (`cert`, `key`), or disable strict SSL verification (`rejectUnauthorized: false` for testing, but use with caution in production-like environments). Refer to Node.js `https` module documentation for details.

breaking Talkback version 4.x requires Node.js version 18 or higher. Older Node.js versions (e.g., 16.x) are no longer supported due to updates in underlying dependencies or language features. ↓

fix Upgrade your Node.js environment to version 18 or newer. Use a Node.js version manager like `nvm` to easily switch and manage Node.js versions.

Install

npm install talkback

yarn add talkback

pnpm add talkback

Imports

talkback
wrong
```
const talkback = require('talkback');
```
correct
```
import talkback from 'talkback';
```
While CommonJS `require` is shown in the README, `import` is the recommended pattern for modern Node.js (`>=18`) and TypeScript projects. Talkback supports both.

talkback.Options.RecordMode

wrong

import { Options } from 'talkback';
const recordMode = Options.RecordMode.NEW;

correct

import talkback from 'talkback';
const recordMode = talkback.Options.RecordMode.NEW;

Enums like `RecordMode` are exposed as properties of the main `talkback` export, not as top-level named exports.

talkback.requestHandler

wrong

import { requestHandler } from 'talkback';

correct

import talkback from 'talkback';
const handler = await talkback.requestHandler(opts);

`requestHandler` is a method on the default `talkback` export, not a direct named export.

Quickstart

Sets up and starts a Talkback HTTP proxy server, configuring it to record new requests and save tapes to a specified directory.

import talkback from 'talkback';
import path from 'path';

const tapesPath = path.resolve(process.cwd(), './my-tapes');

const opts = {
  host: 'https://api.myapp.com/foo',
  record: talkback.Options.RecordMode.NEW,
  port: 5544,
  path: tapesPath,
  // Optional: customize http client for proxying
  httpClient: {
    timeout: 30000 // 30 seconds
  }
};

const server = talkback(opts);

server.start(() => {
  console.log('Talkback server started on port 5544, proxying to https://api.myapp.com/foo');
  console.log(`Tapes will be stored in: ${tapesPath}`);
});

// Example of how to close the server (e.g., in tests)
process.on('SIGINT', () => {
  server.close(() => {
    console.log('Talkback server closed.');
    process.exit(0);
  });
});