Registry / http-networking / original-url

original-url

library1.2.3jsnpmunverified

The `original-url` package provides a utility function to reconstruct the full, original URL of an HTTP request by intelligently parsing various standard and de-facto standard HTTP headers. It accounts for potential modifications made by proxies, load balancers, and other intermediaries by examining headers like `Host`, `Forwarded`, `X-Forwarded-Proto`, `X-Forwarded-Host`, `X-Forwarded-Port`, and others. If the protocol cannot be determined from headers, it leverages the TLS connection's `encrypted` flag. The module returns a URL object compatible with Node.js's native `url.parse` output, including a `full` property for the complete URL string. The current stable version is 1.2.3, published over 6 years ago, indicating a very mature or slow-moving project that is likely in maintenance mode rather than active development. Its primary differentiator is its comprehensive handling of various proxy-related headers to accurately determine the client-facing URL.

http-networking web-framework

npm install original-url

github ↗package ↗

INSTALL

IMPORT

SIG · ORIGINAL-URL

original-url

http-networkingjavascriptv1.2.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

originalUrl

✓ import originalUrl from 'original-url';

✗ import { originalUrl } from 'original-url';

The library primarily exports a single function. For ESM, it's a default import. CommonJS `require` also treats it as the main export.

originalUrl (CommonJS)

✓ const originalUrl = require('original-url');

This is the documented and most common way to import in CommonJS environments, which was prevalent when the package was last updated.

URL Object Structure

✓ const url = originalUrl(req); console.log(url.protocol, url.host, url.pathname, url.query, url.full);

✗ const url = originalUrl(req).url; // 'url' property might not exist, use 'full'

The function returns an object directly, not an object with a nested `url` property. The `full` property contains the complete URL string, while other properties like `protocol`, `host`, `pathname` mirror Node.js `url.parse` output.

This example sets up a simple Node.js HTTP server that uses `original-url` to determine and display the original URL of incoming requests, including detailed URL components parsed from various proxy headers.

import http from 'http'; import originalUrl from 'original-url'; const server = http.createServer(function (req, res) { const url = originalUrl(req); if (url.full) { res.writeHead(200, { 'Content-Type': 'text/plain' }); res.end(`Original URL: ${url.full}\nProtocol: ${url.protocol}\nHost: ${url.host || 'N/A'}\nPath: ${url.pathname || 'N/A'}\nQuery: ${url.query || 'N/A'}\n`); } else { res.writeHead(400, { 'Content-Type': 'text/plain' }); res.end('Original URL could not be determined. Check request headers.\n'); } }); server.listen(1337, () => { console.log('Server listening on http://localhost:1337'); console.log('Try with: curl localhost:1337'); console.log("Or with proxy headers: curl -H 'Forwarded: proto=https; host=example.com; for="10.0.0.1:1234"' localhost:1337/sub/path?key=value"); });

Debug

Known issues

gotchaThe package's latest version (1.2.3) was published over 6 years ago. While its core functionality remains relevant for parsing common proxy headers, it may not incorporate newer HTTP standards, header variations, or security considerations related to URL parsing and proxy handling. Always validate the output, especially in security-sensitive contexts.

fix

Manually inspect the parsed URL properties and consider additional sanitization or validation logic if the application processes sensitive information or relies on strict URL format compliance. For critical applications, evaluate newer, actively maintained alternatives for URL parsing from proxy headers.

affects: <=1.2.3

gotchaThe library relies on `http.IncomingMessage` objects, common in Node.js server environments (e.g., `http`, `express`). It is not intended for client-side (browser) environments or environments where the `req` object is not a standard Node.js `IncomingMessage` instance.

fix

Ensure `original-url` is only used on the server-side within a Node.js HTTP server context where a standard `http.IncomingMessage` object is available. For other contexts, manually parse headers or use context-appropriate URL utilities.

affects: >=1.0.0

gotchaIn serverless or containerized environments (e.g., AWS Lambda, Kubernetes behind a load balancer), the request object might already be pre-processed or wrapped by the platform's runtime. This can alter how headers are presented or which ones are available, potentially leading to `original-url` not accurately determining the URL.

fix

Test thoroughly in your specific deployment environment. If issues arise, inspect the raw `req.headers` object within your serverless function or container to understand the format and availability of proxy headers. You may need to manually extract and reconstruct the URL based on your platform's specific header conventions (e.g., `x-forwarded-host`, `x-real-ip`).

affects: >=1.0.0

gotchaThe `Forwarded` header (RFC 7239) can contain complex syntax, including multiple fields and quoted strings. While `original-url` attempts to parse it, malformed or non-standard `Forwarded` headers could lead to incorrect URL reconstruction. Similarly, `X-Forwarded-Host` and other `X-` headers might be spoofed by malicious clients if not properly secured by upstream proxies.

fix

Always use `original-url` behind a trusted proxy that correctly sets `Forwarded` headers or cleans potentially spoofed `X-` headers. Implement application-level validation to ensure the reconstructed URL is within expected domains or formats, especially when using it for redirects or security-sensitive operations.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: originalUrl is not a function

Attempting to use `import { originalUrl } from 'original-url'` in an ES module environment when the package primarily provides a default export.

fix

Change the import statement to `import originalUrl from 'original-url';` for ES modules, or `const originalUrl = require('original-url');` for CommonJS.

Original URL could not be determined

The request object (`req`) passed to `originalUrl` does not contain sufficient headers (e.g., `Host`, `Forwarded`, `X-Forwarded-*`) or an `encrypted` flag to reconstruct a full URL. This often happens for basic `localhost` requests without explicit headers or for requests where proxy headers are missing or malformed.

fix

Ensure that the incoming HTTP request includes at least a `Host` header. If behind a proxy, confirm that the proxy correctly forwards or sets `Forwarded` or `X-Forwarded-*` headers. For HTTPS, verify that the TLS connection sets the `req.socket.encrypted` flag correctly or `X-Forwarded-Proto: https` is present.

ReferenceError: require is not defined in ES module scope

Attempting to use `const originalUrl = require('original-url');` in an ES module (`.mjs` file or `type: "module"` in `package.json`) in Node.js.

fix

Switch to ES module import syntax: `import originalUrl from 'original-url';`. If you need to use CommonJS modules within an ES module, consider dynamic `import()` or review Node.js's interoperability documentation.

Upgrade

Version history

1.2.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/watson/original-url ↗

packagehttps://www.npmjs.com/package/original-url ↗