feat: parse and expose URIs in extension API

The enhanced sourcegraph.URI class (and its implementation, which is shared by the client and extension) is a full URI parser. Previously it only wrapped a string.

Author: sqs

src/extension/extensionHost.ts

@@ -156,7 +156,7 @@ function createExtensionHandle(initData: InitData, connection: Connection): type
         internal: {
             sync,
             updateContext: updates => context.updateContext(updates),
-            sourcegraphURL: new URI(initData.sourcegraphURL),
+            sourcegraphURL: URI.parse(initData.sourcegraphURL),
             clientApplication: initData.clientApplication,
         },
     }

src/extension/types/location.test.ts

@@ -6,12 +6,12 @@ import { Range } from './range'
 
 describe('Location', () => {
     it('toJSON', () => {
-        assertToJSON(new Location(URI.file('u.ts'), new Position(3, 4)), {
-            uri: URI.parse('file://u.ts').toJSON(),
+        assertToJSON(new Location(URI.parse('file:///u.ts'), new Position(3, 4)), {
+            uri: URI.parse('file:///u.ts').toJSON(),
             range: { start: { line: 3, character: 4 }, end: { line: 3, character: 4 } },
         })
-        assertToJSON(new Location(URI.file('u.ts'), new Range(1, 2, 3, 4)), {
-            uri: URI.parse('file://u.ts').toJSON(),
+        assertToJSON(new Location(URI.parse('file:///u.ts'), new Range(1, 2, 3, 4)), {
+            uri: URI.parse('file:///u.ts').toJSON(),
             range: { start: { line: 1, character: 2 }, end: { line: 3, character: 4 } },
         })
     })

src/integration-test/languageFeatures.test.ts

@@ -31,7 +31,7 @@ describe('LanguageFeatures (integration)', () => {
         extensionHost => extensionHost.languages.registerDefinitionProvider,
         label =>
             ({
-                provideDefinition: (doc, pos) => [{ uri: new URI(`file:///${label}`) }],
+                provideDefinition: (doc, pos) => [{ uri: URI.parse(`file:///${label}`) }],
             } as sourcegraph.DefinitionProvider),
         labeledDefinitionResults,
         run => ({ provideDefinition: run } as sourcegraph.DefinitionProvider),
@@ -46,7 +46,7 @@ describe('LanguageFeatures (integration)', () => {
         extensionHost => extensionHost.languages.registerTypeDefinitionProvider,
         label =>
             ({
-                provideTypeDefinition: (doc, pos) => [{ uri: new URI(`file:///${label}`) }],
+                provideTypeDefinition: (doc, pos) => [{ uri: URI.parse(`file:///${label}`) }],
             } as sourcegraph.TypeDefinitionProvider),
         labeledDefinitionResults,
         run => ({ provideTypeDefinition: run } as sourcegraph.TypeDefinitionProvider),
@@ -61,7 +61,7 @@ describe('LanguageFeatures (integration)', () => {
         extensionHost => extensionHost.languages.registerImplementationProvider,
         label =>
             ({
-                provideImplementation: (doc, pos) => [{ uri: new URI(`file:///${label}`) }],
+                provideImplementation: (doc, pos) => [{ uri: URI.parse(`file:///${label}`) }],
             } as sourcegraph.ImplementationProvider),
         labeledDefinitionResults,
         run => ({ provideImplementation: run } as sourcegraph.ImplementationProvider),
@@ -76,7 +76,7 @@ describe('LanguageFeatures (integration)', () => {
         extensionHost => extensionHost.languages.registerReferenceProvider,
         label =>
             ({
-                provideReferences: (doc, pos, context) => [{ uri: new URI(`file:///${label}`) }],
+                provideReferences: (doc, pos, context) => [{ uri: URI.parse(`file:///${label}`) }],
             } as sourcegraph.ReferenceProvider),
         labels => labels.map(label => ({ uri: `file:///${label}`, range: undefined })),
         run => ({ provideReferences: run } as sourcegraph.ReferenceProvider),

src/shared/uri.test.ts

@@ -0,0 +1,68 @@
+import assert from 'assert'
+import { URI, URIComponents } from './uri'
+
+function assertParsedURI(uriStr: string, expected: Partial<URIComponents>, expectedStr = uriStr): void {
+    expected.scheme = expected.scheme || ''
+    expected.authority = expected.authority || ''
+    expected.path = expected.path || ''
+    expected.query = expected.query || ''
+    expected.fragment = expected.fragment || ''
+
+    const uri = URI.parse(uriStr)
+    assert.deepStrictEqual(uri.toJSON(), expected, `URI.parse(${JSON.stringify(uriStr)})`)
+
+    assert.strictEqual(uri.toString(), expectedStr, `URI#toString ${JSON.stringify(uri.toJSON())}`)
+}
+
+describe('URI', () => {
+    it('parses and produces string representation', () => {
+        // A '/' is automatically added to the path for special schemes by Node's "url" package. This is
+        // undesirable but harmless.
+        assertParsedURI(
+            'https://example.com',
+            {
+                scheme: 'https',
+                authority: 'example.com',
+                path: '/',
+            },
+            'https://example.com/'
+        )
+        assertParsedURI(
+            'foo://example.com',
+            {
+                scheme: 'foo',
+                authority: 'example.com',
+            },
+            'foo://example.com'
+        )
+        assertParsedURI('https://example.com/a', {
+            scheme: 'https',
+            authority: 'example.com',
+            path: '/a',
+        })
+        assertParsedURI('foo://example.com/a', {
+            scheme: 'foo',
+            authority: 'example.com',
+            path: '/a',
+        })
+        assertParsedURI('https://u:[email protected]:1234/a/b?c=d#e', {
+            scheme: 'https',
+            authority: 'u:[email protected]:1234',
+            path: '/a/b',
+            query: 'c=d',
+            fragment: 'e',
+        })
+        assertParsedURI('file:///a', {
+            scheme: 'file',
+            path: '/a',
+        })
+    })
+
+    it('with', () =>
+        assert.strictEqual(
+            URI.parse('https://example.com/a')
+                .with({ path: '/b', query: 'c' })
+                .toString(),
+            'https://example.com/b?c'
+        ))
+})

src/shared/uri.ts

@@ -1,25 +1,141 @@
 import * as sourcegraph from 'sourcegraph'
+import { URL } from 'url'
 
-export class URI implements sourcegraph.URI {
+/**
+ * A serialized representation of a {@link URI} produced by {@link URI#toJSON} and that can be deserialized with
+ * {@link URI.fromJSON}.
+ */
+export interface URIComponents {
+    scheme: string
+    authority: string
+    path: string
+    query: string
+    fragment: string
+}
+
+/**
+ * A uniform resource identifier (URI), as defined in [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3).
+ *
+ * This URI class should be used instead of WHATWG URL or Node's "url" package because it parses all URI schemes in
+ * the same way on all platforms. The WHATWG URL spec requires "non-special schemes" (anything other than http,
+ * https, and a few other common schemes; see https://url.spec.whatwg.org/#special-scheme) to be parsed differently
+ * in a way that is not desirable. For example:
+ *
+ * With WHATWG URL:
+ *
+ *   new URL("https://foo/bar").pathname === "/bar"
+ *
+ *   new URL("git://foo/bar").pathname === "//foo/bar" // UNDESIRABLE
+ *
+ * With Node's "url" package:
+ *
+ *   new URL("https://foo/bar").pathname === "/bar"
+ *
+ *   new URL("git://foo/bar").pathname === "/bar"
+ *
+ * Sourcegraph extensions generally intend to treat all URI schemes identically (as in the second example). This
+ * class implements that behavior.
+ */
+export class URI implements sourcegraph.URI, URIComponents {
     public static parse(uri: string): sourcegraph.URI {
-        return new URI(uri)
+        // Use Node's "url" package to parse the URI. When running in the browser, we assume the bundler (if any)
+        // does the right thing and actually uses the Node "url" package instead of the browser WHATWG URL
+        // implementation.
+        const url = new URL(uri)
+        return new URI({
+            scheme: url.protocol.slice(0, -1), // omit trailing ':'
+            authority: makeAuthority(url),
+            path: url.pathname,
+            query: url.search.slice(1), // omit leading '?'
+            fragment: url.hash.slice(1), // omit leading '#'
+        })
     }
 
-    public static file(path: string): sourcegraph.URI {
-        return new URI(`file://${path}`)
+    public static isURI(value: any): value is sourcegraph.URI {
+        return (
+            value instanceof URI ||
+            (value &&
+                (typeof value.scheme === 'string' &&
+                    typeof value.authority === 'string' &&
+                    typeof value.path === 'string' &&
+                    typeof value.query === 'string' &&
+                    typeof value.fragment === 'string'))
+        )
     }
 
-    public static isURI(value: any): value is sourcegraph.URI {
-        return value instanceof URI || typeof value === 'string'
+    private constructor(components: URIComponents) {
+        this.scheme = components.scheme
+        this.authority = components.authority
+        this.path = components.path
+        this.query = components.query
+        this.fragment = components.fragment
     }
 
-    constructor(private value: string) {}
+    public readonly scheme: string
+
+    public readonly authority: string
+
+    public readonly path: string
+
+    public readonly query: string
+
+    public readonly fragment: string
+
+    public with(change: Partial<URIComponents>): URI {
+        return new URI({ ...this.toJSON(), ...change })
+    }
 
     public toString(): string {
-        return this.value
+        let s = ''
+        if (this.scheme) {
+            s += this.scheme
+            s += ':'
+        }
+        if (this.authority || this.scheme === 'file') {
+            s += '//'
+        }
+        if (this.authority) {
+            s += this.authority
+        }
+        if (this.path) {
+            s += this.path
+        }
+        if (this.query) {
+            s += '?'
+            s += this.query
+        }
+        if (this.fragment) {
+            s += '#'
+            s += this.fragment
+        }
+        return s
+    }
+
+    public toJSON(): URIComponents {
+        return {
+            scheme: this.scheme,
+            authority: this.authority,
+            path: this.path,
+            query: this.query,
+            fragment: this.fragment,
+        }
+    }
+
+    public static fromJSON(value: URIComponents): sourcegraph.URI {
+        return new URI(value)
     }
+}
 
-    public toJSON(): any {
-        return this.value
+function makeAuthority(url: URL): string {
+    let s = ''
+    if (url.username) {
+        s += url.username
+    }
+    if (url.password) {
+        s += `:${url.password}`
+    }
+    if (url.username || url.password) {
+        s += '@'
     }
+    return s + url.host
 }

src/sourcegraph.d.ts

@@ -10,20 +10,88 @@ declare module 'sourcegraph' {
         unsubscribe(): void
     }
 
+    /**
+     * A uniform resource identifier (URI), as defined in [RFC
+     * 3986](https://tools.ietf.org/html/rfc3986#section-3).
+     *
+     * This URI implementation is preferred because the browser URL class implements the WHATWG URL spec, which
+     * requires special treatment for certain URI schemes (such as http and https). That special treatment is
+     * undesirable for Sourcegraph extensions, which need to treat URIs from any scheme in the same way.
+     */
     export class URI {
+        /**
+         * Parses a URI from its string representation.
+         */
         static parse(value: string): URI
-        static file(path: string): URI
 
-        constructor(value: string)
+        /**
+         * Use {@link URI.parse} or {@link URI.fromJSON} to create {@link URI} instances.
+         */
+        private constructor(args: never)
+
+        /**
+         * The scheme component of the URI.
+         *
+         * @summary `https` in `https://example.com`
+         * @see [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3)
+         */
+        readonly scheme: string
+
+        /**
+         * The authority component of the URI.
+         *
+         * @summary `example.com:1234` in `https://example.com:1234/a/b`
+         * @see [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3)
+         */
+        readonly authority: string
+
+        /**
+         * The path component of the URI.
+         *
+         * @summary `/a/b` in `https://example.com/a/b`
+         * @see [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3)
+         */
+        readonly path: string
+
+        /**
+         * The query component of the URI.
+         *
+         * @summary `b=c&d=e` in `https://example.com/a?b=c&d=e`
+         * @see [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3)
+         */
+        readonly query: string
+
+        /**
+         * The fragment component of the URI.
+         *
+         * @summary `g` in `https://example.com/a#g`
+         * @see [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3)
+         */
+        readonly fragment: string
+
+        /**
+         * Derives a new URI from this URI.
+         *
+         * @returns A copy of the URI with the changed components.
+         */
+        with(change: { scheme?: string; authority?: string; path?: string; query?: string; fragment?: string }): URI
 
+        /**
+         * Returns the string representation of this URI.
+         */
         toString(): string
 
         /**
-         * Returns a JSON representation of this Uri.
+         * Returns a JSON representation of this URI.
          *
          * @return An object.
          */
         toJSON(): any
+
+        /**
+         * Revives the URI from its JSON representation that was produced with {@link URI#toJSON}.
+         */
+        static fromJSON(value: any): URI
     }
 
     export class Position {