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: the version got pulls in never settles when the origin keeps the connection alive, and no timeout recovers from it. Declare the override, otherwise passing cache throws:

# pnpm-workspace.yaml
overrides:
  got>cacheable-request: npm:@kikobeats/cacheable-request

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