Skip to content

feat(ipv6): support literal IPv6 addresses in 'target' and 'forward' options#1206

Merged
chimurai merged 1 commit intomasterfrom
literal_ipv6_address
Apr 19, 2026
Merged

feat(ipv6): support literal IPv6 addresses in 'target' and 'forward' options#1206
chimurai merged 1 commit intomasterfrom
literal_ipv6_address

Conversation

@chimurai
Copy link
Copy Markdown
Owner

@chimurai chimurai commented Apr 18, 2026

Add support for literal IPv6 target URLs (with port)

createProxyMiddleware({
  changeOrigin: true,
  target: `http://[::1]:8000`,
});

Reference: https://www.ietf.org/rfc/rfc2732.txt

Summary by CodeRabbit

  • New Features

    • Support literal IPv6 addresses in proxy target and forward options using bracketed notation (e.g., http://[::1]:8000), preserving paths and query strings.
  • Tests

    • Added unit and end-to-end tests validating IPv6 proxying, query preservation, forwarding, router resolution, base-path handling, and auth forwarding.
  • Documentation

    • Updated changelog with an entry documenting IPv6 literal address support.

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Apr 18, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1982143d-9e64-4816-8b81-27f5501e74e5

📥 Commits

Reviewing files that changed from the base of the PR and between fd2840e and 1cd6b56.

📒 Files selected for processing (5)
  • CHANGELOG.md
  • src/http-proxy-middleware.ts
  • src/utils/ipv6.ts
  • test/e2e/ipv6.spec.ts
  • test/unit/utils/ipv6.spec.ts
✅ Files skipped from review due to trivial changes (4)
  • CHANGELOG.md
  • src/http-proxy-middleware.ts
  • test/unit/utils/ipv6.spec.ts
  • test/e2e/ipv6.spec.ts
🚧 Files skipped from review as they are similar to previous changes (1)
  • src/utils/ipv6.ts

📝 Walkthrough

Walkthrough

Adds normalization for bracketed IPv6 literal addresses in target and forward, invokes it during proxy request preparation after router resolution and before path rewrite, and includes unit and e2e tests plus a changelog entry.

Changes

Cohort / File(s) Summary
Changelog
CHANGELOG.md
Added feat(ipv6) entry documenting bracketed IPv6 literal support for target and forward.
Core Implementation
src/http-proxy-middleware.ts, src/utils/ipv6.ts
Added normalizeIPv6LiteralTargets() to normalize bracketed IPv6 string/URL target and forward into host-object shapes; called in prepareProxyRequest immediately after router resolution and before path rewrite.
Tests
test/e2e/ipv6.spec.ts, test/unit/utils/ipv6.spec.ts
Added e2e tests for proxying to bracketed IPv6 targets (ports, queries, router/forward, auth/base path) and unit tests validating normalization behavior and edge cases.

Sequence Diagram(s)

sequenceDiagram
  participant Client as Client
  participant Proxy as ProxyMiddleware
  participant Router as Router
  participant IPv6 as normalizeIPv6LiteralTargets
  participant Path as applyPathRewrite
  participant Upstream as UpstreamServer

  Client->>Proxy: incoming HTTP request
  Proxy->>Router: applyRouter(req, options)
  Router-->>Proxy: resolved target (string/URL/object)
  Proxy->>IPv6: normalizeIPv6LiteralTargets(options)
  IPv6-->>Proxy: normalized target/forward (host object)
  Proxy->>Path: applyPathRewrite(req, options)
  Path-->>Proxy: rewritten req.url
  Proxy->>Upstream: forward request to normalized target
  Upstream-->>Proxy: response
  Proxy-->>Client: proxied response
Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

Poem

🐰 I hop through brackets, colons bright,
I strip the wraps and set host right,
Router calls and paths align,
Upstream greets the tunneled line,
A rabbit nods — proxies hum tonight. 🥕

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (2 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and accurately summarizes the main change: adding support for literal IPv6 addresses in 'target' and 'forward' options, which is the primary focus of all modifications across the codebase.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch literal_ipv6_address

Comment @coderabbitai help to get the list of available commands and usage tips.

@chimurai chimurai added this to the v4 milestone Apr 18, 2026
@pkg-pr-new
Copy link
Copy Markdown

pkg-pr-new Bot commented Apr 18, 2026

npm i https://pkg.pr.new/http-proxy-middleware@1206

commit: 1cd6b56

@coveralls
Copy link
Copy Markdown

coveralls commented Apr 18, 2026

Coverage Status

coverage: 93.956% (+0.9%) from 93.103% — literal_ipv6_address into master

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
test/unit/utils/ipv6.spec.ts (1)

17-105: Add credentialed IPv6 URL cases to lock auth behavior.

Coverage is good overall, but a user:pass@[::1] case is missing and would protect against credential loss regressions.

🧪 Suggested test addition
+  it('should preserve auth when normalizing bracketed IPv6 target string', () => {
+    const options = {
+      target: 'http://user:pass@[::1]:8888/api',
+    };
+
+    normalizeIPv6LiteralTargets(options);
+
+    expect(options.target).toMatchObject({
+      hostname: '::1',
+      pathname: '/api',
+      port: '8888',
+      protocol: 'http:',
+      search: '',
+      auth: 'user:pass',
+    });
+  });
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@test/unit/utils/ipv6.spec.ts` around lines 17 - 105, Add tests to lock auth
behavior around normalizeIPv6LiteralTargets: include a credentialed IPv6 URL
string (e.g. 'http://user:pass@[::1]:8888/api?foo=bar') as options.target and
assert the function does not strip credentials (expect options.target to remain
that exact string), and add a credentialed URL object case (const target = new
URL('http://user:pass@[::1]:8888/'); options.target = target) and assert
normalizeIPv6LiteralTargets leaves the object identity intact (expect
options.target toBe(target)); optionally add the same credentialed-string check
for options.forward to cover both entry points.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/utils/ipv6.ts`:
- Around line 39-45: normalizeIPv6LiteralTargets() currently returns a target
object with an added auth field (which is wrong); instead, when parsing a string
target (e.g., via new URL(...)) detect embedded credentials using
targetUrl.username and targetUrl.password and set the top-level options.auth =
`${targetUrl.username}:${targetUrl.password}` (omit the colon/password part if
password is empty) before returning the normalized target object; do not add
auth to the returned target object—keep hostname (using stripBrackets),
pathname, port, protocol, and search unchanged and only surface credentials via
options.auth.

---

Nitpick comments:
In `@test/unit/utils/ipv6.spec.ts`:
- Around line 17-105: Add tests to lock auth behavior around
normalizeIPv6LiteralTargets: include a credentialed IPv6 URL string (e.g.
'http://user:pass@[::1]:8888/api?foo=bar') as options.target and assert the
function does not strip credentials (expect options.target to remain that exact
string), and add a credentialed URL object case (const target = new
URL('http://user:pass@[::1]:8888/'); options.target = target) and assert
normalizeIPv6LiteralTargets leaves the object identity intact (expect
options.target toBe(target)); optionally add the same credentialed-string check
for options.forward to cover both entry points.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 19679e61-4659-4f64-923b-bb89c0b0751f

📥 Commits

Reviewing files that changed from the base of the PR and between 0665b8c and f57c426.

📒 Files selected for processing (5)
  • CHANGELOG.md
  • src/http-proxy-middleware.ts
  • src/utils/ipv6.ts
  • test/e2e/ipv6.spec.ts
  • test/unit/utils/ipv6.spec.ts

Comment thread src/utils/ipv6.ts
@chimurai chimurai force-pushed the literal_ipv6_address branch 3 times, most recently from a729809 to fd2840e Compare April 18, 2026 15:14
@chimurai chimurai force-pushed the literal_ipv6_address branch from fd2840e to 1cd6b56 Compare April 18, 2026 18:45
@chimurai chimurai merged commit 0934d02 into master Apr 19, 2026
21 checks passed
@chimurai chimurai deleted the literal_ipv6_address branch April 19, 2026 12:12
@chimurai chimurai mentioned this pull request Apr 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants