Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nodejs/undici/llms.txt

Use this file to discover all available pages before exploring further.

undici creates its underlying sockets through a connector function. In most cases this happens automatically, but buildConnector lets you intercept the socket creation process — useful for custom TLS verification, certificate pinning, Unix domain socket connections, or injecting custom socket logic.

​
buildConnector(options)

Creates a connector function with the given TLS and socket options. 
import { buildConnector } from 'undici'

const connector = buildConnector(options)

​
BuildOptions

All Node.js TLS options are supported, plus:
​
socketPath
string | null
An IPC endpoint — Unix domain socket path or Windows named pipe. Default: null.
​
maxCachedSessions
number | null
Maximum number of TLS sessions to cache for reuse. Set to 0 to disable TLS session caching. Default: 100.
​
timeout
number | null
Connection timeout in milliseconds. Default: 10000 (10 seconds).
​
servername
string | null
Override the TLS SNI server name.
​
rejectUnauthorized
boolean
If false, disables TLS certificate validation. Useful for self-signed certificates in development. Default: true.

​
Connector function parameters

The returned connector function accepts:
​
hostname
string
required
The target hostname.
​
host
string
The target host (may differ from hostname).
​
protocol
string
required
The protocol (http: or https:).
​
port
string
required
The target port.
​
servername
string
Override the TLS SNI server name for this connection.
​
localAddress
string | null
The local network address the socket should bind to.
​
httpSocket
Socket
Establish a secure TLS connection over an existing socket (TLS upgrade only).

​
Basic example

Use buildConnector to add custom post-connection logic:
Basic custom connector
import { Client, buildConnector } from 'undici'

const connector = buildConnector({ rejectUnauthorized: false })

const client = new Client('https://localhost:3000', {
  connect(opts, cb) {
    connector(opts, (err, socket) => {
      if (err) {
        cb(err)
      } else if (!isValidSocket(socket)) {
        socket.destroy()
        cb(new Error('Socket validation failed'))
      } else {
        cb(null, socket)
      }
    })
  }
})

​
Certificate fingerprint pinning

Verify the server’s certificate fingerprint to prevent MITM attacks:
Certificate fingerprint validation
import { Client, buildConnector } from 'undici'

const EXPECTED_FINGERPRINT = 'AA:BB:CC:DD:EE:FF:...' // SHA-256 fingerprint
const connector = buildConnector({ rejectUnauthorized: false })

const client = new Client('https://api.example.com', {
  connect(opts, cb) {
    connector(opts, (err, socket) => {
      if (err) {
        cb(err)
        return
      }

      const cert = getIssuerCertificate(socket)
      if (!cert || cert.fingerprint256 !== EXPECTED_FINGERPRINT) {
        socket.destroy()
        cb(new Error('Certificate fingerprint does not match'))
        return
      }

      cb(null, socket)
    })
  }
})

// Traverse the certificate chain to find the issuer certificate
function getIssuerCertificate(socket) {
  let cert = socket.getPeerCertificate(true)
  while (cert && Object.keys(cert).length > 0) {
    if (cert.issuerCertificate == null) return null
    // Root certificate (possibly self-signed)
    if (cert.fingerprint256 === cert.issuerCertificate.fingerprint256) break
    cert = cert.issuerCertificate
  }
  return cert
}

const { body } = await client.request({ path: '/', method: 'GET' })
await body.dump()
client.close()

​
Using the connect option on Agent

Pass a connect option (either a ConnectOptions object or a custom connector function) directly to Client, Pool, or Agent:
Custom TLS on Agent
import { Agent, setGlobalDispatcher, buildConnector } from 'undici'

const connector = buildConnector({
  rejectUnauthorized: true,
  ca: fs.readFileSync('./ca.crt'),
  maxCachedSessions: 50
})

setGlobalDispatcher(new Agent({
  connect: connector
}))

​
Unix domain sockets

Connect to a server over a Unix socket instead of TCP:
Unix socket connection
import { Client, buildConnector } from 'undici'

const connector = buildConnector({ socketPath: '/var/run/myapp.sock' })

const client = new Client('http://localhost', {
  connect: connector
})

const { body } = await client.request({ path: '/health', method: 'GET' })
console.log(await body.text())
For most use cases involving client certificates or custom TLS, you can pass TLS options directly to the connect option of Client, Pool, or Agent without needing buildConnector:
import { Client } from 'undici'
import fs from 'node:fs'

const client = new Client('https://api.example.com', {
  connect: {
    cert: fs.readFileSync('./client.crt'),
    key: fs.readFileSync('./client.key'),
    ca: fs.readFileSync('./ca.crt')
  }
})

Build docs developers (and LLMs) love

Get started for freeTalk to us