link-check

Checks whether a hyperlink is alive (200 OK) or dead.

Installation

npm install --save link-check

Specification

A link is said to be 'alive' if an HTTP HEAD or HTTP GET for the given URL eventually ends in a 200 OK response. To minimize bandwidth, an HTTP HEAD is performed. If that fails (e.g. with a 405 Method Not Allowed), an HTTP GET is performed. Redirects are followed.

In the case of mailto: links, this module validates the e-mail address using node-email-verifier.

API

linkCheck(link, [opts,] callback)

Given a link and a callback, attempt an HTTP HEAD and possibly an HTTP GET.

Parameters:

• url string containing a URL.
• opts optional options object containing any of the following optional fields:
  • anchors array of anchor strings (e.g. [ "#foo", "#bar" ]) for checking anchor links (e.g. <a href="#foo">Foo</a>).
  • baseUrl the base URL for relative links.
  • timeout timeout in zeit/ms format. (e.g. "2000ms", 20s, 1m). Default 10s.
  • user_agent the user-agent string. Default ${name}/${version} (e.g. link-check/4.5.5)
  • aliveStatusCodes an array of numeric HTTP Response codes which indicate that the link is alive. Entries in this array may also be regular expressions. Example: [ 200, /^[45][0-9]{2}$/ ]. Default [ 200 ].
  • headers a string based attribute value object to send custom HTTP headers. Example: { 'Authorization' : 'Basic Zm9vOmJhcg==' }.
  • retryOn429 a boolean indicating whether to retry on a 429 (Too Many Requests) response. When true, if the response has a 429 HTTP code and includes an optional retry-after header, a retry will be attempted after the delay indicated in the retry-after header. If no retry-after header is present in the response or the retry-after header value is not valid according to RFC7231 (value must be in seconds), a default retry delay of 60 seconds will apply. This default can be overriden by the fallbackRetryDelay parameter.
  • retryCount the number of retries to be made on a 429 response. Default 2.
  • fallbackRetryDelay the delay in zeit/ms format. (e.g. "2000ms", 20s, 1m) for retries on a 429 response when no retry-after header is returned or when it has an invalid value. Default is 60s.
• callback function which accepts (err, result).
  • err an Error object when the operation cannot be completed, otherwise null.
  • result an object with the following properties:
    • link the link provided as input
    • status a string set to either alive or dead.
    • statusCode the HTTP status code. Set to 0 if no HTTP status code was returned (e.g. when the server is down).
    • err any connection error that occurred, otherwise null.

Examples

'use strict';

import linkCheck from 'link-check';

linkCheck('http://example.com', function (err, result) {
    if (err) {
        console.error(err);
        return;
    }
    console.log(`${result.link} is ${result.status}`);
});

With basic authentication:

'use strict';

import linkCheck from 'link-check';

linkCheck('http://example.com', { headers: { 'Authorization': 'Basic Zm9vOmJhcg==' } }, function (err, result) {
    if (err) {
        console.error(err);
        return;
    }
    console.log(`${result.link} is ${result.status}`);
});

Testing

npm test

License

See LICENSE.md

Changes

Version 5.4.0

• Defer protocol imports #89 @mondeja
• Decrease package size #90 @mondeja
• ci: use current node.js versions in matrix build #93 @MikeMcC399
• Replace isemail to fix deprecation warning #94 @rkitover
• Fix #79, keep HTTP method when following #80 @MrThanlon
• fix test badge on README #74 @dklimpel
• upgrade dependencies

Version 5.3.0

• fix failing github action with IPv6 @dklimpel
• Add http proxy support @dklimpel
• docs: Format with Markdownlint @nschonni
• upgrade dependencies

Version 5.2.0

Changes:

• add open_timeout option @Colin-Whelan #51
• don't parse HTTP response @sadra-barikbin #57
• upgrade dependencies

Version 5.1.0

Changes:

• support for hash links

Version 5.0.3

Changes:

• upgrade dependencies

Version 5.0.2

Changes:

• upgrade dependencies

Version 5.0.1

Changes:

• 49 upgrade dependencies

Version 5.0.0

This release contains the following potentially breaking changes:

• bad/expired/unauthorized HTTPS certificate errors are no longer ignored.
  • sites with bad certs are no longer considered alive
• User-Agent header no longer impersonates Firefox.
  • defaults to link-check/5.0.0 (override via opts.user_agent).

Changes:

• 46 provide accurate user-agent string

• 44 update to use WHATWG URL API

• 40 use a broader URL encoding function

• 30 reject unauthorized TLS connections (i.e. don't allow bad certs)

• 29 replace Request deprecated dependency by Needle

Version 4.5.4

• 35 fix encode by adding decode first

Version 4.5.3

• 76 encode urls to prevent unicode chars to fail

Version 4.5.2

• 25 fixes 429 "Too Many Requests" retries that don't follow standard (@NicolasMassart)

• 22 Add support for retry count on 429 response codes (@andreizet)

Version 4.5.1

• update dependencies

Version 4.5.0

• update dependencies
• add an option to automatically retry on a 429 response (PR #19)

Version 4.4.7

• update dependencies.
• fix markdown formatting in README.md (PR #18)

Version 4.4.6

• update dependencies.

Version 4.4.5

• update dependencies.
• add CHANGELOG.md (Issue #17)