1.8.0 • Published 1 week ago

@arcjet/transport

Licence

Apache-2.0

Version

1.8.0

Deps

Size

44 kB

Vulns

Weekly

Stars

674

Summary Dependency Versions

`@arcjet/transport`

Transport mechanisms for the Arcjet protocol.

What is this?

This package provides a way to talk to our protocol.

When should I use this?

This is an internal Arcjet package not designed for public use. See our Get started guide for how to use Arcjet in your application.

Install

This package is ESM only. Install with npm in Node.js:

npm install @arcjet/transport

This package requires >=22.21.0 <23 || >=24.5.0. Proxy support relies on the built-in proxy support of the Node.js HTTP agent, which is only available on Node.js >=22.21.0 and, on the 24 line, >=24.5.0. Node.js 20 is end-of-life and Node.js 23 is not supported. Anyone tracking an active LTS release is unaffected.

Because every Arcjet SDK depends on this package, the same requirement applies across the Arcjet SDKs.

Use

import { createTransport } from "@arcjet/transport";

const transport = createTransport("https://decide.arcjet.com");
// This can now be passed to `createClient` from `@arcjet/protocol`.

API

This package exports the identifier createTransport. There is no default export.

This package exports the TypeScript types ProxyEnvironment, TransportLogger, and TransportOptions.

`createTransport(baseUrl[, options])`

Creates a transport that talks to the Arcjet API. On Node.js it uses @connectrpc/connect-node over HTTP/2; separate entry points for Bun, Deno, Edge Light, and workerd use @connectrpc/connect-web instead. This is a thin wrapper around createConnectTransport.

Proxy support

The standard proxy environment variables (HTTP_PROXY and HTTPS_PROXY, while respecting NO_PROXY) are auto-detected, making it possible to connect to the Arcjet API through a proxy such as Squid. When a proxy is in use, a line is logged at startup at info level (so set ARCJET_LOG_LEVEL=info to see it). The proxy URL itself is not logged, since it can contain credentials. How the request is actually proxied depends on the runtime, using each runtime's built-in proxy support:

Node.js — requests are routed through the proxy over HTTP/1.1 using the built-in proxy support of the Node.js HTTP agent; otherwise they are made directly over HTTP/2. Set proxyHttpVersion: "2" to instead keep HTTP/2 while proxying (see HTTP/2 through a proxy below).
Bun and Deno — the runtime's fetch performs the proxying natively.
Edge Light and workerd — these edge runtimes don't support outbound proxy environment variables, so no proxy is used.

NO_PROXY accepts a comma- or space-separated list of host suffixes, each with an optional leading . or *. and an optional :port, plus * to bypass the proxy for every host. Entries are matched as host names; IP/CIDR ranges (such as 10.0.0.0/8) are not supported, the same as curl. On Bun and Deno the runtime's fetch applies NO_PROXY itself, so its exact semantics are the runtime's.

HTTP/2 through a proxy

By default, proxying on Node.js downgrades the connection from HTTP/2 to HTTP/1.1, because Node's built-in agent proxy support only works over HTTP/1.1. For a latency-sensitive API this is unfortunate: it gives up HTTP/2's multiplexing, so a burst of concurrent requests opens a new proxy connection each instead of sharing one.

Setting proxyHttpVersion: "2" keeps HTTP/2 end-to-end. The transport opens an HTTP CONNECT tunnel to the proxy and then performs the TLS handshake — and the ALPN negotiation that selects h2 — directly with the origin. The proxy only blindly forwards the tunnel, so it never sees, and cannot downgrade, the negotiated protocol.

This comes with caveats:

Node.js only. Bun and Deno don't implement the agent option this builds on; they proxy through their fetch (over HTTP/1.1) regardless of this setting, and the edge runtimes don't proxy at all.
Requires a tunneling (CONNECT) proxy — the common kind for HTTPS egress, including Squid. A proxy that terminates TLS and re-originates an HTTP/1.1 connection to the origin (a TLS-intercepting / "MITM" proxy) cannot preserve HTTP/2 no matter what this option is set to.
The proxy must not buffer the tunnel. HTTP/2 sends many small, dependent frames. The transport disables Nagle's algorithm (TCP_NODELAY) on its side of the tunnel, but if the proxy buffers tunneled bytes (or leaves Nagle enabled on its upstream socket) the interaction with delayed ACKs can add roughly 40 ms of latency per round trip, erasing the benefit. Tunneling proxies such as Squid set TCP_NODELAY on CONNECT tunnels by default; verify this if you use a different proxy.

When no proxy applies, this option has no effect — direct connections always use HTTP/2.

Parameters

baseUrl (string, example: https://example.com/my-api) — the base URL for all HTTP requests
options (TransportOptions, optional) — configuration

log (TransportLogger, optional) — logger used to print a line at startup when a proxy is detected; defaults to a logger configured from the ARCJET_LOG_LEVEL environment variable
proxyEnv (ProxyEnvironment or false, optional) — environment variables used to detect an outbound proxy; defaults to process.env so standard proxy environment variables are auto-detected; pass false to ignore proxy environment variables
proxyHttpVersion ("1.1" or "2", optional, default "1.1") — HTTP version to use when a proxy is in use on Node.js; "1.1" routes through the proxy using the Node.js HTTP agent, while "2" keeps HTTP/2 by tunneling through the proxy with CONNECT; has no effect without a proxy, or on Bun, Deno, and the edge runtimes (see HTTP/2 through a proxy)