fs: allow WHATWG URL and file: URLs as paths

Updates the fs module APIs to allow 'file://' URL objects
to be passed as the path.

For example:

```js
const URL = require('url').URL;
const myURL = new URL('file:///C:/path/to/file');
fs.readFile(myURL, (err, data) => {});
```

On Windows, file: URLs with a hostname convert to UNC paths,
while file: URLs with drive letters convert to local absolute
paths:

```
file://hostname/a/b/c => \\hostname\a\b\c
file:///c:/a/b/c => c:\a\b\c
```

On all other platforms, file: URLs with a hostname are unsupported
and will result in a throw:

```
file://hostname/a/b/c => throw!
file:///a/b/c => /a/b/c
```

The documentation for the fs API is intentionally not updated in
this commit because the URL API is still considered experimental
and is not officially documented *at this time*

Note that file: URLs are *required* by spec to always be absolute
paths from the file system root.

This is a semver-major commit because it changes error handling
on the fs APIs.

PR-URL: https://github.com/nodejs/node/pull/10739
Ref: https://github.com/nodejs/node/issues/10703
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>

1 files changed, 70 insertions, 0 deletions

diff --git a/test/parallel/test-fs-whatwg-url.js b/test/parallel/test-fs-whatwg-url.js
new file mode 100644
index 0000000000..7a94fd68d7
--- /dev/null
+++ b/test/parallel/test-fs-whatwg-url.js
@@ -0,0 +1,70 @@
+'use strict';
+
+const common = require('../common');
+const assert = require('assert');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const URL = require('url').URL;
+const Buffer = require('buffer').Buffer;
+
+function pathToFileURL(p) {
+  if (!path.isAbsolute(p))
+    throw new Error('Path must be absolute');
+  if (common.isWindows && p.startsWith('\\\\'))
+    p = p.slice(2);
+  return new URL(`file://${p}`);
+}
+
+const p = path.resolve(common.fixturesDir, 'a.js');
+const url = pathToFileURL(p);
+
+assert(url instanceof URL);
+
+// Check that we can pass in a URL object successfully
+fs.readFile(url, common.mustCall((err, data) => {
+  assert.ifError(err);
+  assert(Buffer.isBuffer(data));
+}));
+
+// Check that using a non file:// URL reports an error
+const httpUrl = new URL('http://example.org');
+fs.readFile(httpUrl, common.mustCall((err) => {
+  assert(err);
+  assert.strictEqual(err.message,
+                     'Only `file:` URLs are supported');
+}));
+
+// pct-encoded characters in the path will be decoded and checked
+fs.readFile(new URL('file:///c:/tmp/%00test'), common.mustCall((err) => {
+  assert(err);
+  assert.strictEqual(err.message,
+                     'Path must be a string without null bytes');
+}));
+
+if (common.isWindows) {
+  // encoded back and forward slashes are not permitted on windows
+  ['%2f', '%2F', '%5c', '%5C'].forEach((i) => {
+    fs.readFile(new URL(`file:///c:/tmp/${i}`), common.mustCall((err) => {
+      assert(err);
+      assert.strictEqual(err.message,
+                         'Path must not include encoded \\ or / characters');
+    }));
+  });
+} else {
+  // encoded forward slashes are not permitted on other platforms
+  ['%2f', '%2F'].forEach((i) => {
+    fs.readFile(new URL(`file:///c:/tmp/${i}`), common.mustCall((err) => {
+      assert(err);
+      assert.strictEqual(err.message,
+                         'Path must not include encoded / characters');
+    }));
+  });
+
+  fs.readFile(new URL('file://hostname/a/b/c'), common.mustCall((err) => {
+    assert(err);
+    assert.strictEqual(err.message,
+                       `File URLs on ${os.platform()} must use ` +
+                       'hostname \'localhost\' or not specify any hostname');
+  }));
+}