Skip to main content

Class: NetUtils

Defined in: service-core/src/NetUtils.ts:20

Provides common utilities and functions for working with networking related problems.

Constructors​

Constructor​

new NetUtils(): NetUtils

Returns​

NetUtils

Methods​

getClientIP()​

static getClientIP(req, trustedProxies?): string | undefined

Defined in: service-core/src/NetUtils.ts:244

Returns the IP address of the client that made the given request, in canonical form (see normalizeIP()). This is the address that should be used for rate limiting, audit logs and any other per-client keying.

The result is determined as follows:

  1. If the socket's remote address is not a valid IP, it is returned as-is (or undefined if empty) and no header is consulted.
  2. If trustedProxies is empty or the remote address is not a trusted proxy, the remote address is returned. Forwarding headers are ignored, so an untrusted client cannot choose its own address.
  3. Otherwise X-Forwarded-For is walked from right to left (every X-Forwarded-For value is taken into account). Addresses of trusted proxies are skipped and the first address that is not a trusted proxy is returned. If an entry is not a valid IP address, the walk stops and the last trusted hop is returned, since nothing left of it can be trusted. If every entry is a trusted proxy, the left-most entry is returned.
  4. If there is no X-Forwarded-For header, a valid X-Real-IP header is returned, else the remote address.

X-Original-Forwarded-For is never consulted.

Parameters​

req​

HttpRequest

The HTTP request to extract the client address from.

trustedProxies?​

TrustedProxies

The addresses and/or CIDR ranges of reverse proxies whose forwarding headers are trusted, as an array or a comma-separated string.

Returns​

string | undefined

The client's canonical IP address, or undefined if the request has no remote address.

getIPAddress()​

static getIPAddress(urlOrRequest, trustedProxies?): string | undefined

Defined in: service-core/src/NetUtils.ts:291

Extracts the IP address from a given url or HTTP request.

For an HTTP request this is identical to getClientIP(): forwarding headers are only trusted when the direct connection's remote address is one of trustedProxies, and the result is normalized.

Parameters​

urlOrRequest​

string | HttpRequest

The url or HTTP request to extract the IP from.

trustedProxies?​

TrustedProxies

Optional list of proxy IP addresses and/or CIDR ranges whose forwarding headers should be trusted.

Returns​

string | undefined

A string containing the IP address if found, otherwise undefined.

isTrustedProxy()​

static isTrustedProxy(address, trustedProxies?): boolean

Defined in: service-core/src/NetUtils.ts:213

Returns true if address matches an entry of trustedProxies. Both sides are normalized first (see normalizeIP()), so e.g. ::ffff:10.0.0.1 matches a 10.0.0.1 entry, and CIDR range entries are supported.

Parameters​

address​

string | undefined

The address to check.

trustedProxies?​

TrustedProxies

The trusted proxy addresses and/or CIDR ranges, as an array or a comma-separated string.

Returns​

boolean

lookupIPAddress()​

static lookupIPAddress(url, family?): Promise<string | undefined>

Defined in: service-core/src/NetUtils.ts:31

Performs DNS lookup of the IP address from a given url.

Parameters​

url​

string

The url to lookup the IP from.

family?​

number = 4

ip family used for dns lookup

Returns​

Promise<string | undefined>

A string containing the IP address if found, otherwise undefined.

normalizeIP()​

static normalizeIP(value): string | undefined

Defined in: service-core/src/NetUtils.ts:74

Parses and canonicalizes a single IP address so that two spellings of the same address always compare equal. Accepts an optional port (1.2.3.4:80, [::1]:80), brackets and an IPv6 zone id, all of which are removed.

  • IPv4 addresses are returned unchanged (e.g. 10.0.0.1).
  • IPv4-mapped IPv6 addresses are unmapped to plain IPv4, in either spelling: ::ffff:127.0.0.1 and uWS's fully expanded 0000:0000:0000:0000:0000:ffff:7f00:0001 both become 127.0.0.1.
  • Other IPv6 addresses are returned in RFC 5952 form: lowercase, no leading zeros, and the longest run of two or more zero groups compressed to :: (e.g. 2001:0DB8:0:0:0:0:0:1 becomes 2001:db8::1).

Parameters​

value​

string | null | undefined

The address to normalize.

Returns​

string | undefined

The canonical address, or undefined if value is not a valid IPv4/IPv6 address.