Ninja Power Manifesto

    hosts-so-easy

    1.2.9 • Public • Published

    hosts-so-easy

    Safe, parallel API for manipulating /etc/hosts

    npm Circle CI Coverage Status MIT License Known Vulnerabilities dependencies Commitizen friendly semantic-release

    Copyright (c) 2017 by Gadi Cohen. Released under the MIT license.

    Note: we support and run tests against latest Node, and Node v10 LTS (as of 2021-01-10).

    Features

    • [X] Built for safe and concurrent / parallel use.
    • [X] Add/remove funcs are (optionally) "use and forget" - no callbacks required.
    • [X] Preserves formatting (comments & whitespace choices) - see sample below.
    • [X] Changes are batched, atomic write is debounced 500ms (by default).
    • [X] Optionally keeps new entries in a separate "header" block.

    Usage

    import Hosts from 'hosts-so-easy';
    const hosts = new Hosts();
    
    // hosts file is written once at the end
    hosts.add('192.168.0.1', 'www');
    hosts.add('192.168.1.1', [ 'mongo', 'db' ]);
    
    // this is completely safe, only one write occurs at the end.
    for (let i = 2; i < 10; i++)
      hosts.add('192.168.0.'+i, 'host'+i);
    
    // can remove individual hosts, all hosts for an IP, or a host from any IP
    hosts.remove('192.168.2.1', '*');
    hosts.remove('192.168.3.1', 'vhost20');
    hosts.remove('192.168.4.1', [ 'mongo', 'db' ]);
    hosts.remove('*', 'unwantedHost');
    hosts.remove('*', [ 'unwantedHost1', 'unwantedHost2' ]);
    
    // callback/promise after all changes synced in a single write
    await hosts.updateFinish();
    hosts.updateFinish().then(function() { ... }).catch(function(err) { ... });
    hosts.updateFinish(callback);
    hosts.on('updateFinish', callback);
    hosts.once('updateFinish', callback);

    Options

    const hosts = new Hosts({
    
      // Write the new contents to a temporary file first and rename afterwards
      // instantly to avoid conflicts with other writers.  You'll know if you
      // need to turn this off (special filesystems, etc).  Either way, we always
      // check to avoid concurrent writes within the library.
      atomicWrites: false, // default: true
    
      // How long to wait after *last* add/remove before writing the file,
      // to write the file once even after performing many operations.
      // Even with a small value, we'll check to avoid concurrent writes.
      debounceTime: 500, // in ms, default: 500ms
    
      // Maintain a header block and insert new entries there.  See sample output
      // further down the README for an example.
      header: 'Docker hosts', // default: false
    
      // Linux/Mac default:  /etc/hosts
      // Windows default:    C:/Windows/System32/drivers/etc/hosts
      hostsFile: '/some/weird/location/hosts',
    
    });

    API

    Methods

    • hosts.add(ip, host || [host1,host2])

      For the given IP, add a single host or an array of hosts.

    • hosts.clearQueue()

      If you had a change of heart, and call this in time, nothing will happen :)

    • hosts.on(event, callback)

      hosts.once(event, callback)

      Run the given callback on every event occurrence, or just once when the event next occurs. See EVENTS, below.

    • hosts.remove(ip || '*', host || [host1,host2] || '*')

      For the given IP, remove the given host or all the hosts in the array. Alternatively, give a "host" of * to remove the entire line, or an "ip" of * to remove the given host(s) from any IP.

    • hosts.removeHost(host)

      Remove all references of host, regardless of which IP it resolves to. This has the same effect as hosts.remove('*', host).

    • hosts.updateFinish([callback])

      If a callback is given, it's called at the end of the update sequence (see events, below). If an error occurred, it's provided as the first argument.

      If no callback is given, a Promise is returned. It resolves after a successful write, or rejects on failure.

    Events

    • updateStart - fires at the beginning of update sequence. Hosts file will be stat'd, read and rewritten.

    • updateFinish - fires at the end of the above sequence. On failure, the error will be provided as the first argument (file not found, permission denied, etc).

    Sample output (formatting preserved)

    const hosts = new Hosts({ header: 'optional header' });
    #
    # /etc/hosts: static lookup table for host names
    #
    
    #<ip-address>   <hostname.domain.org>   <hostname>
    127.0.0.1       localhost.localdomain   localhost
    ::1             localhost.localdomain   localhost
    
    # optional header
    172.20.0.2 host2
    172.20.0.3 host3
    
    192.168.0.2     server2
    

    TODO

    • [X] Ability to turn off atomic writes
    • [X] Maintain a header block (put hosts in same section)
    • [X] EventEmitter for writes
    • [X] Validate arguments, throw on invalid

    Wishlist

    • [ ] Callback / promise when particular host entry added. Can't think of any use-case where the 'write' event would not be sufficient, but I'll add this if you give me a good reason.

    • [ ] Mimic preceding whitespace pattern for new entry insertion.

    • [X] Better caching for those doing A LOT of work on the file.

    Install

    npm i hosts-so-easy

    DownloadsWeekly Downloads

    11

    Version

    1.2.9

    License

    MIT

    Unpacked Size

    47.5 kB

    Total Files

    14

    Last publish

    Collaborators

    • gadicc