{"id":15984512,"url":"https://github.com/metcoder95/fastify-ip","last_synced_at":"2025-03-16T07:32:01.750Z","repository":{"id":65321565,"uuid":"585872769","full_name":"metcoder95/fastify-ip","owner":"metcoder95","description":"Infer the Request IP (or IPs if behind a proxy) based on custom headers","archived":false,"fork":false,"pushed_at":"2024-10-22T20:02:30.000Z","size":219,"stargazers_count":8,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-27T05:49:33.270Z","etag":null,"topics":["fastify","fastify-plugin","ip","proxy"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/metcoder95.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-06T10:05:06.000Z","updated_at":"2024-10-22T20:02:33.000Z","dependencies_parsed_at":"2024-01-01T23:40:37.420Z","dependency_job_id":"1fcbf2e3-596b-4895-8717-93fe8b67e9b8","html_url":"https://github.com/metcoder95/fastify-ip","commit_stats":{"total_commits":43,"total_committers":3,"mean_commits":"14.333333333333334","dds":0.4651162790697675,"last_synced_commit":"9a1a9d5f9d1599dfde4ada6dfcb69de5a644ce22"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":"metcoder95/lib_template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metcoder95%2Ffastify-ip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metcoder95%2Ffastify-ip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metcoder95%2Ffastify-ip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metcoder95%2Ffastify-ip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/metcoder95","download_url":"https://codeload.github.com/metcoder95/fastify-ip/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243806045,"owners_count":20350775,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastify","fastify-plugin","ip","proxy"],"created_at":"2024-10-08T02:09:16.874Z","updated_at":"2025-03-16T07:32:01.191Z","avatar_url":"https://github.com/metcoder95.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fastify-ip\n![NPM](https://img.shields.io/npm/l/fastify-ip)\n[![npm](https://badge.fury.io/js/fastify-ip.svg)](https://badge.fury.io/js/fastify-ip)\n[![CI](https://github.com/metcoder95/fastify-ip/actions/workflows/ci.yml/badge.svg)](https://github.com/metcoder95/fastify-ip/actions/workflows/ci.yml)\n\n---\n\n`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.\n\n## How it works?\n\nThe plugin will make a best-effort to infer the request's IP based on a subset of well-known headers, which looks as follows:\n```\n'x-client-ip' // Most common\n'x-forwarded-for' // Mostly used by proxies\n'cf-connecting-ip' // Cloudflare\n'Cf-Pseudo-IPv4' // Cloudflare\n'fastly-client-ip'\n'true-client-ip' // Akamai and Cloudflare\n'x-real-ip' // Nginx\n'x-cluser-client-ip' // Rackspace LB\n'forwarded-for'\n'x-forwarded'\n'forwarded'\n'x-appengine-user-ip' // GCP App Engine\n```\n\nThe 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.\n\n\u003eNote: It is important to remark that this does not alters the `Request#ips` behavior for inferring IPs when setting the `FastifyOptions#trustProxy` to `true`. It rather allows you to infer the IP of a given request by headers out of the common spec or standard. However, the `ip` decorator may be updated by fastify-ip, depending on the order of priority in which the above-mentioned headers are processed.\n\n## Setup\n\nInstall by running `npm install fastify-ip`.\n\nThen register the plugin to your fastify instance:\n\n```js\nconst fastify = require('fastify')({\n  logger: true\n})\n\nfastify.register(require('fastify-ip'), {\n    order: ['x-my-ip-header'],\n    strict: false,\n    isAWS: false,\n})\n```\n\n### Options\n\n- `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.\n\n- `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`.\n\n- `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`.\n\n\n### API\n\nThe plugin will decorate the Request object with a set of utils that can be handy for managing IPs.\n\n- `isIP(pseudo: string): boolean` - It will return `true` if a given string is a valid IPv4 or IPv6, or `false` otherwise.\n- `isIPv4(pseudo: string): boolean` - Similar to `isIP` but will validate of the given string is a valid `IPv4`.\n- `isIPv6(pseudo: string): boolean` - Similar to `isIP` but will validate of the given string is a valid `IPv6`.\n- `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.\n\n## How to use it?\n\n**JavaScript**\n\n```js\napp.get('/', (req, reply) =\u003e {\n    req.log.info({ ip: req.ip }, 'my ip!')\n    req.log.info({ isValid: req.isIP('hello!') } /* false */)\n    req.log.info({ isIPv4: req.isIPv4('127.0.0.1') })\n    req.log.info({ isIPv6: req.isIPv6('::1') })\n    req.log.info({ version: req.inferIPVersion('127.0.0.1') /* 4 */ })\n    req.log.info({ version: req.inferIPVersion('::1') /* 6 */ })\n    req.log.info({ version: req.inferIPVersion('asd') /* 0 */ })\n\n    reply.send(req.ip)\n})\n```\n\n**TypeScript**\n\n```ts\napp.post('/', (request: FastifyRequest, reply: FastifyReply) =\u003e {\n    req.log.info({ ip: req.ip }, 'my ip!')\n    req.log.info({ isValid: req.isIP('hello!') } /* false */)\n    req.log.info({ isIPv4: req.isIPv4('127.0.0.1') })\n    req.log.info({ isIPv6: req.isIPv6('::1') })\n    req.log.info({ version: req.inferIPVersion('127.0.0.1') /* 4 */ })\n    req.log.info({ version: req.inferIPVersion('::1') /* 6 */ })\n    req.log.info({ version: req.inferIPVersion('asd') /* 0 */ })\n\n    reply.send(req.ip)\n});\n```\n\n## Type Definitions\n\n```ts\nexport interface FastifyIPOptions {\n  order?: string[] | string;\n  strict?: boolean;\n  isAWS?: boolean;\n}\n\ndeclare module 'fastify' {\n  interface FastifyRequest {\n    isIP(pseudo: string): boolean;\n    isIPv4(pseudo: string): boolean;\n    isIPv6(pseudo: string): boolean;\n    inferIPVersion(pseudo: string): 0 | 4 | 6;\n  }\n}\n```\n\n\n\u003e See [test](test/index.test.js) for more examples.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetcoder95%2Ffastify-ip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetcoder95%2Ffastify-ip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetcoder95%2Ffastify-ip/lists"}