agents.md

Agents

The agents registry maps a service path or hostname to an Undici dispatcher. Register an agent once, then use either a short service path such as /catalog/items or the service's absolute URL in request(), its HTTP verb aliases, stream(), and pipeline().

interface CustomHttpAgent {
  customPath: string;
  origin: string;
  agent: Agent | ProxyAgent | MockAgent;
  limit?: InlineCallbackAction;
}

const agents: Set<CustomHttpAgent>;

Register an agent

import {
  Agent,
  agents,
  get,
  type CustomHttpAgent
} from "@openally/httpie";

const catalog: CustomHttpAgent = {
  customPath: "catalog",
  origin: "https://catalog.example.com",
  agent: new Agent({
    connections: 30
  })
};

agents.add(catalog);

const { data } = await get("/catalog/items");

The request path /catalog/items becomes https://catalog.example.com/items and uses catalog.agent as its Undici dispatcher.

agents is a standard JavaScript Set. Keep a reference to an entry if it may need to be removed later:

agents.delete(catalog);

Matching rules

A string URI is resolved in this order:

1. Httpie checks each registered customPath in insertion order. Both /catalog/items and catalog/items match customPath: "catalog".
2. If no path matches, Httpie parses the string as an absolute URL and looks for an agent whose origin has the same hostname.

A WHATWG URL is matched by hostname. Path aliases apply only to string URIs.

The first matching entry wins. Use distinct path prefixes when several agents are registered.

const internalApi: CustomHttpAgent = {
  customPath: "internal",
  origin: "https://api.example.com",
  agent: new Agent()
};

agents.add(internalApi);

await get("/internal/users");
await get("https://api.example.com/users");

Both requests use internalApi.agent.

Per-request overrides

The agent option on a request takes precedence over the dispatcher selected from the registry:

import {
  ProxyAgent,
  get
} from "@openally/httpie";

const proxy = new ProxyAgent("http://proxy.example.com:8080");

const response = await get("/catalog/items", {
  agent: proxy
});

An agent entry may also provide a limit callback. A request-level limit overrides the registered one.

const catalog: CustomHttpAgent = {
  customPath: "catalog",
  origin: "https://catalog.example.com",
  agent: new Agent(),
  limit: async(callback) => callback()
};

See Request options for the callback signature.

computeURI()

computeURI() exposes the resolution used internally by requests and streams.

computeURI(
  uri: string | URL
): {
  url: URL;
  agent: Agent | ProxyAgent | MockAgent | null;
  limit?: InlineCallbackAction;
}

import { computeURI } from "@openally/httpie";

const resolved = computeURI("/catalog/items");

console.log(resolved.url.href);
// https://catalog.example.com/items

URI resolutions are cached by input string. The cache holds up to 100 entries for 120 minutes. Register agents before sending requests or calling computeURI(), because changing the agents set does not invalidate entries already in the cache.

The returned URL can be changed by the caller without modifying the cached URL.

Undici dispatchers

Httpie re-exports the dispatcher classes used by the registry, including Agent, ProxyAgent, and MockAgent. It also re-exports Client, interceptors, global dispatcher helpers, and Undici's mocking utilities. Configuration and lifecycle behavior for those exports follows the Undici documentation.