{"id":16163,"library":"original-url","title":"Reconstruct Original HTTP Request URL","description":"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.","status":"maintenance","version":"1.2.3","language":"javascript","source_language":"en","source_url":"https://github.com/watson/original-url","tags":["javascript","http","https","url","original","resolve","parse","reconstruct","forward"],"install":[{"cmd":"npm install original-url","lang":"bash","label":"npm"},{"cmd":"yarn add original-url","lang":"bash","label":"yarn"},{"cmd":"pnpm add original-url","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily exports a single function. For ESM, it's a default import. CommonJS `require` also treats it as the main export.","wrong":"import { originalUrl } from 'original-url';","symbol":"originalUrl","correct":"import originalUrl from 'original-url';"},{"note":"This is the documented and most common way to import in CommonJS environments, which was prevalent when the package was last updated.","symbol":"originalUrl (CommonJS)","correct":"const originalUrl = require('original-url');"},{"note":"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.","wrong":"const url = originalUrl(req).url; // 'url' property might not exist, use 'full'","symbol":"URL Object Structure","correct":"const url = originalUrl(req); console.log(url.protocol, url.host, url.pathname, url.query, url.full);"}],"quickstart":{"code":"import http from 'http';\nimport originalUrl from 'original-url';\n\nconst server = http.createServer(function (req, res) {\n  const url = originalUrl(req);\n  if (url.full) {\n    res.writeHead(200, { 'Content-Type': 'text/plain' });\n    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`);\n  } else {\n    res.writeHead(400, { 'Content-Type': 'text/plain' });\n    res.end('Original URL could not be determined. Check request headers.\\n');\n  }\n});\n\nserver.listen(1337, () => {\n  console.log('Server listening on http://localhost:1337');\n  console.log('Try with: curl localhost:1337');\n  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\");\n});","lang":"javascript","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"gotcha","affected_versions":"<=1.2.3"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`).","message":"In 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Change the import statement to `import originalUrl from 'original-url';` for ES modules, or `const originalUrl = require('original-url');` for CommonJS.","cause":"Attempting to use `import { originalUrl } from 'original-url'` in an ES module environment when the package primarily provides a default export.","error":"TypeError: originalUrl is not a function"},{"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.","cause":"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.","error":"Original URL could not be determined"},{"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.","cause":"Attempting to use `const originalUrl = require('original-url');` in an ES module (`.mjs` file or `type: \"module\"` in `package.json`) in Node.js.","error":"ReferenceError: require is not defined in ES module scope"}],"ecosystem":"npm"}