reachable-url

reachable-url

Given an URL, it resolves as fast as possible, performing a GET without downloading the body.

Install

$ npm install reachable-url --save

Usage

const reachableUrl = require('reachable-url')

reachableUrl.isReachable(await reachableUrl('https://google.com')) // => true

API

reachableUrl(input, [options])

url

Required
Type: string

The target URL to be resolved.

options

Same as got#options, plus:

maxBody

Type: number
Default: 0

How many bytes of the body to keep when the download would otherwise be cancelled. A non-negative integer or Infinity; anything else throws.

The default answers reachability from the status and headers alone, never reading a body. Ask for more when the bytes themselves decide something:

// one byte is enough to tell an image from an HTML error page served as one
const response = await reachableUrl('https://example.com/favicon.png', { maxBody: 1 })
response.body[0] === 60 // => `<`, so the server answered with markup

Asking for more than one byte drops the Range header, since a server that honors it would answer with just that byte. Infinity is the extreme of that, and keeps the whole entity:

const response = await reachableUrl('https://example.com/favicon.svg', { maxBody: Infinity })
response.body // => the whole entity

Passing cache keeps the whole body too, since a cache entry is only written once the body has been read in full:

const cache = new Map()
const response = await reachableUrl('https://example.com/video.mp4', { cache })
response.body // => the whole entity, so it can be cached

cache needs @kikobeats/cacheable-request: upstream cacheable-request never settles when the origin keeps the connection alive, and no timeout recovers from it. @kikobeats/got depends on the fork since 11.8.9, so it works without any configuration. If something in your dependency tree still resolves the upstream package, passing cache throws instead of hanging.

returns

The got response, plus requestUrl, redirectUrls, redirectStatusCodes and the followRedirect in effect.

By default the request asks for a single byte (Range: bytes=0-0, which maxBody drops when it wants more). When a server ignores that and starts sending the whole entity, the download is cancelled: the status and headers already say whether the URL is reachable, so body is undefined on those responses unless maxBody asked for some of it.

A 206 that did answer the range is reported as the 200 it stands for, with content-length taken from a numeric content-range total. An unknown total (bytes 0-0/*) is left as a 206.

reachableUrl.isReachable(response)

response

Required
Type: object

The response returned by reachableUrl, which echoes back followRedirect so it can be handed straight over.

A URL is reachable when the response is a final 2xx.

A redirect status is the final answer only when redirects were not being followed:

const response = await reachableUrl('https://example.com', { followRedirect: false })
reachableUrl.isReachable(response) // => true, the 3xx is the destination

With redirect following on (the default), a 3xx is the hop the follow stopped at (a beforeRedirect hook threw, maxRedirects ran out), meaning the URL was never reached:

const response = await reachableUrl('https://example.com', {
  hooks: { beforeRedirect: [() => { throw new Error('refused') }] }
})
reachableUrl.isReachable(response) // => false

A partial object missing followRedirect is judged as if redirects were being followed, so a bare { statusCode: 302 } is unreachable.

License

reachable-url Kiko Beats, released under the MIT License.
Authored and maintained by Kiko Beats with help from contributors.

kikobeats.com · GitHub Kiko Beats · X @Kikobeats