hapi-geo-locate
    TypeScript icon, indicating that this package has built-in type declarations

    4.1.1 • Public • Published
    hapi-geo-locate logo

    A hapi plugin to geo-locate requests


    Installation · Usage · Plugin Options · Proxies and Headers



    Build Status Known Vulnerabilities Latest Version Total Downloads

    Follow @marcuspoehls for updates!


    Development of this hapi plugin is supported by Future Studio University 🚀
    Join the Future Studio University and Skyrocket in Node.js


    Introduction

    A hapi plugin to geo locate requests by IP and provide request.location in your route handlers. The plugin uses ipinfo.io for the IP geo location.

    Requirements

    hapi v19 (or later) and Node.js v12 (or newer)

    This plugin requires hapi v19 (or later) and Node.js v12 or newer.

    Compatibility

    Major Release hapi.js version Node.js version
    v4 >=17 hapi >=12
    v3 >=17 hapi >=8
    v2 <=16 hapi >=8

    Installation

    Add hapi-geo-locate as a dependency to your project:

    npm i hapi-geo-locate

    Using hapi v17 or v18?

    Use the 3.x release line:

    npm i hapi-geo-locate@3

    Do you use hapi v16 (or lower)?

    Use the 2.x release of hapi-geo-locate with hapi v16 support. Later versions are only compatible with hapi v17 and v18.

    npm i hapi-geo-locate@2

    Usage

    The most straight forward way to register the hapi-geo-locate plugin:

    await server.register({
        plugin: require('hapi-geo-locate')
    })
     
    // went smooth like dark chocolate :)
     
    // Within your route handler functions, you can access the location like this
    server.route({
        method: 'GET',
        path: '/',
        handler: (request, h) => {
            const location = request.location
     
            // use client location
     
            return location
        }
    })

    Plugin Registration Options

    The following plugin options allow you to customize the default behavior of hapi-geo-locate:

    • enabledByDefault: (boolean), default: true — by default, the plugin geo locates the request by IP on every request
    • authToken: (string), no default — the API token to authenticate requests against the IPinfo API
    await server.register({
      plugin: require('hapi-geo-locate'),
      options: {
        enabledByDefault: false
        authToken: 'your-ipinfo-api-token'
      }
    })
     
    // Within your route handler functions, you can access the location like this
    server.route({
      method: 'GET',
      path: '/',
      handler: (request, h) => {
        const location = request.location // will be undefined
     
        return h.response(location)
      }
    })

    Route Handler Options

    The following plugin options on individual route handlers allow you to customize the behavior of hapi-geo-locate:

    • enabled: (boolean) — tells the plugin to enable (true) or disable (false) geo location for the request by IP
    • fakeIP: (string) — tells the plugin to use the defined IP address to geo locate the request (by this IP)

    The plugin configuration can be customized for single routes using the hapi-geo-locate key:

    server.register({
      plugin: require('hapi-geo-locate') // enabled by default
    })
     
    // Within your route handler functions, you can access the location like this
    server.route({
      method: 'GET',
      path: '/',
      handler: (request, h) => {
        const location = request.location
        // use the location
     
        return location
      },
      config: {
        plugins: {
          'hapi-geo-locate': {
            enabled: true,
            fakeIP: '8.8.8.8'
          }
        }
      }
    })

    Supported Proxies and Proxy Headers

    hapi-geo-locate supports all proxies that request-ip does:

    • X-Client-IP
    • X-Forwarded-For, picking the first, client IP if the request went through multiple proxies.
    • X-Forwarded, Forwarded-For and Forwarded as variations of X-Forwarded-For
    • CF-Connecting-IP
    • True-Client-Ip
    • X-Real-IP
    • X-Cluster-Client-IP
    • and all the request.[connection|socket|info].remoteAddress variations.

    If the IP address cannot be found, null is returned.

    Running your application behind a (reverse) proxy like nginx, the client’s IP address gets reset to localhost. You can grab the actual request IP to your app using an HTTP header.

    hapi-geo-locate uses the request-ip package to determine the external IP address. This package supports all common HTTP headers and ways to get the request’s IP. Awesome!

    You should be safe in any way :)

    Feature Requests

    Do you miss a feature? Please don’t hesitate to create an issue with a short description of your desired addition to this plugin.

    Links & Resources

    Contributing

    1. Create a fork
    2. Create your feature branch: git checkout -b my-feature
    3. Commit your changes: git commit -am 'Add some feature'
    4. Push to the branch: git push origin my-new-feature
    5. Submit a pull request 🚀

    License

    MIT © Future Studio


    futurestud.io  ·  GitHub @futurestudio  ·  Twitter @futurestud_io

    Install

    npm i hapi-geo-locate

    DownloadsWeekly Downloads

    210

    Version

    4.1.1

    License

    MIT

    Unpacked Size

    42.2 kB

    Total Files

    16

    Last publish

    Collaborators

    • celsiusf
    • futurestud.io
    • marcuspoehls
    • peitek