Implementation:Spotify Luigi URI Library

Knowledge Sources	Spotify_Luigi
Domains	Web_Visualiser, URI_Parsing
Last Updated	2026-02-10 08:00 GMT

Overview

URI.js is a vendored third-party JavaScript library (version 1.18.2) included in the Luigi web visualiser for parsing, constructing, manipulating, and resolving URIs and URLs in the browser.

Description

URI.js is an open-source JavaScript library authored by Rodney Rehm that provides a comprehensive, jQuery-style API for working with URIs. It is vendored (bundled directly) within the Luigi repository to support the Luigi web visualiser's URL manipulation needs without requiring external CDN dependencies.

The library provides the following capabilities:

• URI parsing and construction -- Parses URI strings into their component parts (protocol, hostname, port, path, query, fragment, username, password) and can reconstruct them. Supports RFC 3986 compliant parsing.
• URI mutation -- Provides a fluent, chainable API to modify any component of a URI (e.g., .hostname(), .port(), .path(), .query()). Each accessor method acts as both getter and setter depending on whether arguments are provided.
• Query string manipulation -- Methods for adding, removing, and modifying individual query parameters via addQuery(), removeQuery(), setQuery(), and hasQuery(). Supports array parameters and nested objects.
• Path operations -- Methods for normalizing, resolving relative paths, getting directory and filename components, and manipulating path segments via segment().
• URI normalization -- Normalizes URIs by resolving dots in paths, decoding unnecessary percent-encoding, lowercasing the scheme and hostname, removing default ports, and other RFC-compliant normalization steps.
• Internationalized Domain Names (IDN) -- Support via bundled Punycode and IPv6 libraries for handling international domain names and IPv6 addresses.
• Module support -- Compatible with CommonJS (Node.js), AMD (RequireJS), and browser global patterns via a UMD wrapper.

Within the Luigi visualiser, URI.js is used to parse and manipulate the URLs displayed in the task graph interface, handle navigation between different views, and construct API request URLs to the Luigi scheduler.

External Documentation: URI.js Official Documentation

Usage

This library is used internally by the Luigi web visualiser and is not intended to be imported or used directly by Luigi pipeline authors. It is loaded by the visualiser's HTML pages and used by the visualiser JavaScript code for URL manipulation when rendering the task dependency graph, handling browser navigation, and making AJAX requests to the Luigi scheduler API. The library is vendored to ensure consistent behavior regardless of network availability or CDN changes.

Code Reference

Source Location

• Repository: Spotify_Luigi
• File: luigi/static/visualiser/lib/URI/1.18.2/URI.js
• Lines: 1-2218

Signature

// Constructor
function URI(url, base) { ... }

// Static methods
URI.parse = function(string, parts) { ... }
URI.build = function(parts) { ... }
URI.parseAuthority = function(string, parts) { ... }
URI.buildAuthority = function(parts) { ... }
URI.parseHost = function(string, parts) { ... }
URI.buildHost = function(parts) { ... }
URI.parseQuery = function(string) { ... }
URI.buildQuery = function(data, duplicateQueryParameters, escapeQuerySpace) { ... }
URI.addQuery = function(data, name, value) { ... }
URI.removeQuery = function(data, name, value) { ... }
URI.hasQuery = function(data, name, value, withinArray) { ... }
URI.encode = function(string) { ... }
URI.decode = function(string) { ... }
URI.iso8859 = function() { ... }
URI.unicode = function() { ... }

// Instance methods (chainable)
URI.prototype.protocol = function(v, build) { ... }
URI.prototype.hostname = function(v, build) { ... }
URI.prototype.port = function(v, build) { ... }
URI.prototype.path = function(v, build) { ... }
URI.prototype.query = function(v, build) { ... }
URI.prototype.fragment = function(v, build) { ... }
URI.prototype.username = function(v, build) { ... }
URI.prototype.password = function(v, build) { ... }
URI.prototype.segment = function(segment, v) { ... }
URI.prototype.normalize = function() { ... }
URI.prototype.resolve = function(base) { ... }
URI.prototype.relativeTo = function(base) { ... }
URI.prototype.toString = function() { ... }
URI.prototype.href = function(url) { ... }

Import

// Browser global (used by Luigi visualiser)
var uri = new URI(window.location.href);

// CommonJS / Node.js
var URI = require('./URI');

// AMD / RequireJS
define(['./URI'], function(URI) { ... });

I/O Contract

Inputs

Name	Type	Required	Description
url	string	No	A URI string to parse; if omitted, uses the current page URL (browser) or creates an empty URI
base	string or URI	No	A base URI for resolving relative URIs

Outputs

Name	Type	Description
URI instance	object	A mutable URI object with chainable accessor/mutator methods for all URI components
toString()	string	The serialized URI string representation
URI.parse()	object	A plain object with parsed URI parts: protocol, username, password, hostname, port, path, query, fragment

Usage Examples

Basic Usage

// Parse and manipulate a URI
var uri = new URI("http://localhost:8082/static/visualiser/index.html#tab=graph");

// Read components
uri.protocol();   // "http"
uri.hostname();   // "localhost"
uri.port();       // "8082"
uri.path();       // "/static/visualiser/index.html"
uri.fragment();   // "tab=graph"

// Modify components (chainable)
uri.hostname('scheduler.example.com')
   .port('443')
   .protocol('https');

uri.toString();
// "https://scheduler.example.com:443/static/visualiser/index.html#tab=graph"

Query String Manipulation

var uri = new URI("/api/task_list");

// Add query parameters
uri.addQuery("status", "RUNNING");
uri.addQuery("worker", "host01");
uri.toString();  // "/api/task_list?status=RUNNING&worker=host01"

// Parse existing query
var params = URI.parseQuery("?status=RUNNING&limit=100");
// { status: "RUNNING", limit: "100" }

// Remove a parameter
uri.removeQuery("worker");
uri.toString();  // "/api/task_list?status=RUNNING"

Related Pages

• Principle:Spotify_Luigi_Web_Visualiser_Monitoring