HttpAgent

Defined in: packages/net-http/src/client/http-agent.ts:170

Sends requests to any origin, opening, pooling and reusing connections per origin (scheme, host and port).

Over HTTP/1.1 a connection carries one exchange at a time, so concurrent requests to one origin use up to maxConnectionsPerOrigin connections and queue beyond that; a connection is reused once its previous response body was read to the end. With the http2 option, https: connections offer h2 through ALPN; once a server accepted it, every request to that origin shares the one connection, as concurrent streams. Requests made while that first connection is still being negotiated wait for it rather than open others.

With the http3 option, an https: origin whose responses advertise an HTTP/3 alternative on its own host (Alt-Svc: h3=":443") gets its next new connection over QUIC, raced against TCP with a head start: the first to connect serves the origin, and an alternative whose QUIC connection failed is passed over for five minutes. Connections already open are kept.

Nothing is retried — a request whose body is a stream could not be.

Example

  const agent = new HttpAgent({
    connector: connectTcp,
    maxHeadSize: 16 * 1024,
    maxConnectionsPerOrigin: 6,
    idleTimeoutMs: 30_000,
  });
  const response = await agent.request({
    method: "GET",
    url: new URL("http://127.0.0.1:8080/"),
  });
  const text = await new Response(response.body).text();
  ```;

## Constructors

### Constructor

> **new HttpAgent**(`options`): `HttpAgent`

Defined in: packages/net-http/src/client/http-agent.ts:177

#### Parameters

##### options

[`HttpAgentOptions`](../type-aliases/HttpAgentOptions.md)

#### Returns

`HttpAgent`

## Methods

### \[asyncDispose\]()

> **\[asyncDispose\]**(): `Promise`\<`void`\>

Defined in: packages/net-http/src/client/http-agent.ts:239

Closes the agent, so it can be used with `await using`.

#### Returns

`Promise`\<`void`\>

***

### close()

> **close**(): `Promise`\<`void`\>

Defined in: packages/net-http/src/client/http-agent.ts:224

Refuse new requests, fail the waiting ones, and close every connection once
its exchanges in progress completed.

#### Returns

`Promise`\<`void`\>

***

### request()

> **request**(`request`, `options?`): `Promise`\<[`HttpIncomingResponse`](../type-aliases/HttpIncomingResponse.md)\>

Defined in: packages/net-http/src/client/http-agent.ts:193

Send a request and resolve with its response head; the body follows as the
response's stream, and must be read to the end or cancelled.

A protocol switch (`request.protocol`) to an HTTP/2 origin whose server
does not accept extended `CONNECT` goes over a new HTTP/1.1 connection, as
an `Upgrade`.

#### Parameters

##### request

[`HttpOutgoingRequest`](../type-aliases/HttpOutgoingRequest.md)

##### options?

[`HttpRequestOptions`](../type-aliases/HttpRequestOptions.md)

#### Returns

`Promise`\<[`HttpIncomingResponse`](../type-aliases/HttpIncomingResponse.md)\>

#### Throws

When the URL scheme is neither `http:` nor `https:`.

#### Throws

When the agent is closed, the connection
  closed before the response head arrived, or such a switch finds the
  origin's connections all open.

#### Throws

When connecting fails, or `options.signal` aborts first.