sobekurl

README

sobek-webapi-url

A WHATWG-style URL and URLSearchParams Web API implementation for the Sobek JavaScript runtime (used by k6).

This package lets JavaScript running inside Sobek use the standard URL and URLSearchParams globals, and is validated against a large subset of the upstream Web Platform Tests for the URL standard.

Installation

go get github.com/oleiade/sobek-webapi-url

Usage

Register the URL Web API in your Sobek runtime and then use it from JavaScript:

package main

import (
	"github.com/grafana/sobek"
	sobekurl "github.com/oleiade/sobek-webapi-url"
)

func main() {
	rt := sobek.New()

	// Register URL and URLSearchParams globally
	if err := sobekurl.RegisterGlobally(rt); err != nil {
		panic(err)
	}

	// Now you can use URL and URLSearchParams in JavaScript
	rt.RunString(`
        const url = new URL('https://example.com/path?foo=bar#hash');
        console.log(url.hostname);  // "example.com"
        console.log(url.searchParams.get('foo'));  // "bar"

        url.searchParams.set('baz', 'qux');
        console.log(url.href);  // "https://example.com/path?foo=bar&baz=qux#hash"
    `)
}

Once registered, any JavaScript code executed in the runtime can construct and manipulate URLs using the familiar browser-style API.

Supported Features

URL

• Constructor: new URL(url, base?)
• Static methods: URL.canParse(url, base?), URL.parse(url, base?)
• Properties (read/write):
  • href, protocol, username, password
  • host, hostname, port, pathname
  • search, hash
• Properties (read-only):
  • origin, searchParams
• Methods: toString(), toJSON()

URLSearchParams

• Constructor: new URLSearchParams(init?)
  • Accepts: string, URLSearchParams, array of pairs, or object
• Methods:
  • append(name, value)
  • delete(name, value?)
  • get(name) / getAll(name)
  • has(name, value?)
  • set(name, value)
  • sort()
  • toString()
  • forEach(callback, thisArg?)
  • entries() / keys() / values()
• Properties: size
• Iterable: supports for...of loops

Known Limitations

This implementation uses Go's net/url package under the hood, which has some differences from the WHATWG URL Standard:

1. Base URL validation: Go's URL parser is more lenient than WHATWG. For example, aaa:b is considered a valid absolute URL in Go but not in WHATWG (which requires a path separator after non-special schemes).

2. Opaque paths: Data URLs and other URLs with opaque paths may not be fully supported.

3. Live iterators: The URLSearchParams iterator does not reflect mutations made during iteration (the WHATWG spec requires live iterators).

4. Punycode/IDNA: International domain name handling may differ from browser implementations.

Testing

This implementation is validated against Web Platform Tests (WPT) for the URL and URLSearchParams APIs.

go test -v ./url/...

Test Status

Test Suite	Status
URLSearchParams.append	✅ Pass
URLSearchParams.delete	⚠️ Partial (data: URL edge cases)
URLSearchParams.get	✅ Pass
URLSearchParams.getAll	✅ Pass
URLSearchParams.has	✅ Pass
URLSearchParams.set	✅ Pass
URLSearchParams.sort	✅ Pass
URLSearchParams.size	✅ Pass
URLSearchParams.stringifier	✅ Pass
URLSearchParams.forEach	⚠️ Partial (live iterator edge cases)
URLSearchParams constructor	⚠️ Partial (DOMException branding)
URL.searchParams integration	✅ Pass
URL.canParse	⚠️ Partial (WHATWG spec differences)
URL.parse	⚠️ Partial (WHATWG spec differences)
URL.toJSON	✅ Pass

WPT test files and wptsync

The WPT test files are vendored in the wpt/ directory. The wpt.json file specifies which tests are included, the upstream WPT commit, and any patches applied.

The test set is managed with a small helper tool called wptsync, which reads wpt.json and (re)populates the wpt/ directory from the upstream WPT repository. To change which tests are synced, edit wpt.json and then use wptsync to refresh the local copy (see the wptsync documentation for installation and usage details).

License

This project is licensed under the same terms as the Sobek project.

Documentation

Overview

Package sobekurl registers the URL Web API with Sobek runtimes.

This package provides WHATWG-style URL and URLSearchParams globals for use in Sobek JavaScript runtimes (as used by k6). It supports the common subset of the URL standard including HTTP(S), WS(S), FTP, and file schemes with standard parsing, serialization, and manipulation.

Usage

rt := sobek.New()
if err := sobekurl.RegisterGlobally(rt); err != nil {
    log.Fatal(err)
}
// URL and URLSearchParams are now available in the runtime

After registration, JavaScript code can use the standard URL API:

const url = new URL('https://example.com/path?query=value#hash');
console.log(url.hostname);  // "example.com"
console.log(url.searchParams.get('query'));  // "value"

const params = new URLSearchParams('foo=1&bar=2');
params.append('baz', '3');
console.log(params.toString());  // "foo=1&bar=2&baz=3"

Supported Features

• URL constructor with optional base URL
• URL.canParse() and URL.parse() static methods
• All standard URL properties (href, protocol, host, hostname, port, pathname, search, hash, origin, username, password, searchParams)
• URLSearchParams with append, delete, get, getAll, has, set, sort, forEach, entries, keys, values, and size
• Proper bidirectional synchronization between URL.search and URL.searchParams

Known Limitations

• Blob URLs are not supported
• Some WHATWG edge cases may differ (uses Go's net/url internally)
• Data URLs with opaque paths may not be fully supported

For more details, see the url subpackage documentation.

Index

• Variables
• func RegisterGlobally(rt *sobek.Runtime) error
• type URL

Variables

var (
	// ExtractURL extracts a url.URL from a Sobek Value.
	//nolint:gochecknoglobals // Re-exported for convenience
	ExtractURL = url.ExtractURL
	// ParseURLArgument parses a URL argument from a Sobek Value.
	//nolint:gochecknoglobals // Re-exported for convenience
	ParseURLArgument = url.ParseURLArgument
)

Functions

func RegisterGlobally

func RegisterGlobally(rt *sobek.Runtime) error

RegisterGlobally exposes the URL and URLSearchParams constructors in the provided sobek runtime.

Types

type URL

type URL = url.URL

URL is a re-export of url.URL for consumers such as k6 modules.