fastify-ip
is a plugin which allows to infer the incoming request's IP based on a custom subset of well known headers used by different providers or technologies that possible sits in-front of your fastify application.
The plugin will make a best-effort to infer the request's IP based on a subset of well-known headers, which looks as follows:
'x-client-ip' // Most common
'x-forwarded-for' // Mostly used by proxies
'cf-connecting-ip' // Cloudflare
'Cf-Pseudo-IPv4' // Cloudflare
'fastly-client-ip'
'true-client-ip' // Akamai and Cloudflare
'x-real-ip' // Nginx
'x-cluser-client-ip' // Rackspace LB
'forwarded-for'
'x-forwarded'
'forwarded'
'x-appengine-user-ip' // GCP App Engine
The plugin will use a FIFO strategy to infer the right IP. This can be customised by passing a custom order property that includes your custom headers.
Note: It is important to remark that this does not alters the
Request#ips
behaviour for inferring IPs when setting theFastifyOptions#trustProxy
totrue
. It rather allows you to infer the IP of a given request by headers out of the common spec or standard.
Install by running npm install fastify-ip
.
Then register the plugin to your fastify instance:
const fastify = require('fastify')({
logger: true
})
fastify.register(require('fastify-ip'), {
order: ['x-my-ip-header'],
strict: false,
isAWS: false,
})
order
- string[] | string
- optional: Array of custom headers or single custom header to be appended to the prior list of well-known headers. The headers passed will be prepend to the default headers list. It can also be used to alter the order of the list as deduplication of header names is made while loading the plugin.
strict
- boolean
- optional: Indicates whether to override the default list of well-known headers and replace it with the header(s) passed through the order
option. If set to true
without order
or isAWS
properties provided, it will lead to throwing an exception. Default false
.
isAWS
- boolean
- optional: Indicates wether the plugin should explicitly try to infer the IP from the decorations made at the native Node.js HTTP Request object included in the Fastify Request. If set to true
the plugin will treat this approach as a first option. Otherwise it will use it just as a fallback. Default false
.
The plugin will decorate the Request object with a set of utils that can be handy for managing IPs.
isIP(pseudo: string): boolean
- It will return true
if a given string is a valid IPv4 or IPv6, or false
otherwise.isIPv4(pseudo: string): boolean
- Similar to isIP
but will validate of the given string is a valid IPv4
.isIPv6(pseudo: string): boolean
- Similar to isIP
but will validate of the given string is a valid IPv6
.inferIPVersion(pseudo: string): 0 | 4 | 6
- It will try to infer the IPv of a given IP, returning 4
for IPv4
and 6
for IPv6
, will return 0
if the given string does not match any of the IPv.JavaScript
app.get('/', (req, reply) => {
req.log.info({ ip: req.ip }, 'my ip!')
req.log.info({ isValid: req.isIP('hello!') } /* false */)
req.log.info({ isIPv4: req.isIPv4('127.0.0.1') })
req.log.info({ isIPv6: req.isIPv6('::1') })
req.log.info({ version: req.inferIPVersion('127.0.0.1') /* 4 */ })
req.log.info({ version: req.inferIPVersion('::1') /* 6 */ })
req.log.info({ version: req.inferIPVersion('asd') /* 0 */ })
reply.send(req.ip)
})
TypeScript
app.post('/', (request: FastifyRequest, reply: FastifyReply) => {
req.log.info({ ip: req.ip }, 'my ip!')
req.log.info({ isValid: req.isIP('hello!') } /* false */)
req.log.info({ isIPv4: req.isIPv4('127.0.0.1') })
req.log.info({ isIPv6: req.isIPv6('::1') })
req.log.info({ version: req.inferIPVersion('127.0.0.1') /* 4 */ })
req.log.info({ version: req.inferIPVersion('::1') /* 6 */ })
req.log.info({ version: req.inferIPVersion('asd') /* 0 */ })
reply.send(req.ip)
});
export interface FastifyIPOptions {
order?: string[] | string;
strict?: boolean;
isAWS?: boolean;
}
declare module 'fastify' {
interface FastifyRequest {
isIP(pseudo: string): boolean;
isIPv4(pseudo: string): boolean;
isIPv6(pseudo: string): boolean;
inferIPVersion(pseudo: string): 0 | 4 | 6;
}
}
See test for more examples.