[PR #6842] [management, proxy] Support multiple L4 port mappings per reverse-proxy domain #29950

Open
opened 2026-08-05 08:09:30 -04:00 by saavagebueno · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/netbirdio/netbird/pull/6842
Author: @heywander
Created: 7/21/2026
Status: 🔄 Open

Base: mainHead: codex/multiport-pr


📝 Commits (7)

  • b698c41 api: add reverse-proxy port mappings
  • de62f9d management: persist and validate multiple port mappings
  • 5dc84b3 proxy: generate listeners for multi-port services
  • 85fcc38 management: allow compatible services to share a domain
  • ee3fc62 proxy: preserve shared-domain service ownership
  • 9549dc8 refactor: address multi-port quality gate
  • 54ca8e1 fix: address multi-port review feedback

📊 Changes

51 files changed (+6036 additions, -1262 deletions)

View changed files

📝 management/internals/modules/agentnetwork/synthesizer.go (+37 -20)
📝 management/internals/modules/agentnetwork/synthesizer_test.go (+27 -0)
📝 management/internals/modules/reverseproxy/proxy/proxy.go (+3 -0)
📝 management/internals/modules/reverseproxy/service/interface.go (+1 -0)
📝 management/internals/modules/reverseproxy/service/interface_mock.go (+15 -0)
📝 management/internals/modules/reverseproxy/service/manager/l4_port_test.go (+200 -1)
📝 management/internals/modules/reverseproxy/service/manager/manager.go (+222 -37)
📝 management/internals/modules/reverseproxy/service/manager/manager_test.go (+72 -106)
management/internals/modules/reverseproxy/service/multiport_test.go (+249 -0)
📝 management/internals/modules/reverseproxy/service/service.go (+302 -295)
management/internals/modules/reverseproxy/service/service_api.go (+422 -0)
📝 management/internals/modules/reverseproxy/service/service_test.go (+42 -0)
📝 management/internals/shared/grpc/expose_service.go (+13 -5)
📝 management/internals/shared/grpc/proxy.go (+52 -35)
📝 management/internals/shared/grpc/proxy_group_access_test.go (+42 -1)
📝 management/internals/shared/grpc/proxy_test.go (+50 -0)
📝 management/internals/shared/grpc/validate_session_test.go (+16 -0)
📝 management/server/http/handlers/proxy/auth_callback_integration_test.go (+55 -0)
management/server/migration/reverse_proxy_port_mappings.go (+81 -0)
management/server/migration/reverse_proxy_port_mappings_test.go (+90 -0)

...and 31 more files

📄 Description

Describe your changes

This draft implements the multi-port L4 reverse-proxy design requested in #5821 and is being opened for maintainer confirmation of the API/model and hostname-conflict behavior.

  • Add multiple TCP and UDP listener-to-target port mappings to one reverse-proxy service.
  • Support individual ports, contiguous ranges, and listener-to-target translation with matching range sizes.
  • Permit TCP and UDP to reuse the same numeric port.
  • Reject invalid ports, reversed or mismatched ranges, same-protocol overlaps, and conflicting listener ownership across services.
  • Migrate existing single-port services into one-element mapping collections while preserving service IDs and configuration.
  • Generate and distribute every mapping through management, ACL, and proxy-runtime configuration.
  • Allow compatible HTTPS and raw TCP/UDP services to share a hostname when their listeners do not conflict.
  • Preserve HTTP/HTTPS behavior and keep TLS passthrough hostname-exclusive.
  • Preserve legacy single-port API fields for existing clients while exposing the new mapping collection.

Validation

  • Focused management, migration, store, API, ACL, TCP, UDP, and proxy-runtime tests.
  • SQLite, PostgreSQL, and MySQL migration coverage.
  • Race testing on changed management and proxy packages.
  • Go vet and golangci-lint on changed packages.
  • OpenAPI/protobuf generated-output verification.
  • Dashboard production build and coordinated local/VPS Docker smoke testing were completed in the companion fork.

Closes #5821

Stack

  • Dashboard companion PR: netbirdio/dashboard#723
  • Documentation PR: netbirdio/docs#867
  • Opening as a draft so the NetBird team can confirm the public model and compatibility decisions before it is marked ready.

Checklist

  • Is it a bug fix
  • Is a typo/documentation fix
  • Is a feature enhancement
  • It is a refactor
  • Created tests that fail without the change (if possible)
  • This change does not modify the public API, gRPC protocols, functionality behavior, CLI / service flags, or introduce a new feature — OR I have discussed it with the NetBird team beforehand (link the issue / Slack thread in the description). See CONTRIBUTING.md.

The design discussion is continuing in #5821 and this draft. This checkbox will be updated after maintainer confirmation.

By submitting this pull request, you confirm that you have read and agree to the terms of the Contributor License Agreement.

Documentation

Select exactly one:

  • I added/updated documentation for this change
  • Documentation is not needed for this change (explain why)

Docs PR URL (required if "docs added" is checked)

https://github.com/netbirdio/docs/pull/867

Summary by CodeRabbit

  • New Features

    • Added ordered multi-port L4 support for reverse-proxy services via port_mappings, plus capability reporting (supports_port_mappings) and HTTP-domain aware service lookup.
    • Added HTTP-domain scoped service lookup and ephemeral resolution by peer+domain for OIDC/session flows.
  • Bug Fixes

    • Canonicalized domains/hosts end-to-end (service resolution, auth, SNI routing, and OIDC redirects) to prevent mismatches and ownership edge cases.
    • Strengthened port conflict handling, deterministic port assignment, and multi-port update validation.
  • Migration

    • Added migrations to canonicalize shared domains, backfill legacy services into port_mappings, and update ownership/overlap safety checks.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/netbirdio/netbird/pull/6842 **Author:** [@heywander](https://github.com/heywander) **Created:** 7/21/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `codex/multiport-pr` --- ### 📝 Commits (7) - [`b698c41`](https://github.com/netbirdio/netbird/commit/b698c416415ba3bc7d0eb9c2006a50f5c113408f) api: add reverse-proxy port mappings - [`de62f9d`](https://github.com/netbirdio/netbird/commit/de62f9d2dfeecaccbe13301aa9e6f2fa6f8dc6e9) management: persist and validate multiple port mappings - [`5dc84b3`](https://github.com/netbirdio/netbird/commit/5dc84b311f1f89c01a82282f9169d9f0145695ef) proxy: generate listeners for multi-port services - [`85fcc38`](https://github.com/netbirdio/netbird/commit/85fcc385876457a9fcc1875a74a0dabc69117b85) management: allow compatible services to share a domain - [`ee3fc62`](https://github.com/netbirdio/netbird/commit/ee3fc6298f04ed84ca7b9d3f6df6f2bed628f4d0) proxy: preserve shared-domain service ownership - [`9549dc8`](https://github.com/netbirdio/netbird/commit/9549dc8b99dff0074b2c37eb21c01f5ba9cc240a) refactor: address multi-port quality gate - [`54ca8e1`](https://github.com/netbirdio/netbird/commit/54ca8e198022b441c0b12265133b865f38001da4) fix: address multi-port review feedback ### 📊 Changes **51 files changed** (+6036 additions, -1262 deletions) <details> <summary>View changed files</summary> 📝 `management/internals/modules/agentnetwork/synthesizer.go` (+37 -20) 📝 `management/internals/modules/agentnetwork/synthesizer_test.go` (+27 -0) 📝 `management/internals/modules/reverseproxy/proxy/proxy.go` (+3 -0) 📝 `management/internals/modules/reverseproxy/service/interface.go` (+1 -0) 📝 `management/internals/modules/reverseproxy/service/interface_mock.go` (+15 -0) 📝 `management/internals/modules/reverseproxy/service/manager/l4_port_test.go` (+200 -1) 📝 `management/internals/modules/reverseproxy/service/manager/manager.go` (+222 -37) 📝 `management/internals/modules/reverseproxy/service/manager/manager_test.go` (+72 -106) ➕ `management/internals/modules/reverseproxy/service/multiport_test.go` (+249 -0) 📝 `management/internals/modules/reverseproxy/service/service.go` (+302 -295) ➕ `management/internals/modules/reverseproxy/service/service_api.go` (+422 -0) 📝 `management/internals/modules/reverseproxy/service/service_test.go` (+42 -0) 📝 `management/internals/shared/grpc/expose_service.go` (+13 -5) 📝 `management/internals/shared/grpc/proxy.go` (+52 -35) 📝 `management/internals/shared/grpc/proxy_group_access_test.go` (+42 -1) 📝 `management/internals/shared/grpc/proxy_test.go` (+50 -0) 📝 `management/internals/shared/grpc/validate_session_test.go` (+16 -0) 📝 `management/server/http/handlers/proxy/auth_callback_integration_test.go` (+55 -0) ➕ `management/server/migration/reverse_proxy_port_mappings.go` (+81 -0) ➕ `management/server/migration/reverse_proxy_port_mappings_test.go` (+90 -0) _...and 31 more files_ </details> ### 📄 Description ## Describe your changes This draft implements the multi-port L4 reverse-proxy design requested in #5821 and is being opened for maintainer confirmation of the API/model and hostname-conflict behavior. - Add multiple TCP and UDP listener-to-target port mappings to one reverse-proxy service. - Support individual ports, contiguous ranges, and listener-to-target translation with matching range sizes. - Permit TCP and UDP to reuse the same numeric port. - Reject invalid ports, reversed or mismatched ranges, same-protocol overlaps, and conflicting listener ownership across services. - Migrate existing single-port services into one-element mapping collections while preserving service IDs and configuration. - Generate and distribute every mapping through management, ACL, and proxy-runtime configuration. - Allow compatible HTTPS and raw TCP/UDP services to share a hostname when their listeners do not conflict. - Preserve HTTP/HTTPS behavior and keep TLS passthrough hostname-exclusive. - Preserve legacy single-port API fields for existing clients while exposing the new mapping collection. ### Validation - Focused management, migration, store, API, ACL, TCP, UDP, and proxy-runtime tests. - SQLite, PostgreSQL, and MySQL migration coverage. - Race testing on changed management and proxy packages. - Go vet and golangci-lint on changed packages. - OpenAPI/protobuf generated-output verification. - Dashboard production build and coordinated local/VPS Docker smoke testing were completed in the companion fork. ## Issue ticket number and link Closes #5821 ## Stack <!-- branch-stack --> - Dashboard companion PR: netbirdio/dashboard#723 - Documentation PR: netbirdio/docs#867 - Opening as a draft so the NetBird team can confirm the public model and compatibility decisions before it is marked ready. ### Checklist - [ ] Is it a bug fix - [ ] Is a typo/documentation fix - [x] Is a feature enhancement - [ ] It is a refactor - [x] Created tests that fail without the change (if possible) - [ ] This change does **not** modify the public API, gRPC protocols, functionality behavior, CLI / service flags, or introduce a new feature — **OR** I have discussed it with the NetBird team beforehand (link the issue / Slack thread in the description). See [CONTRIBUTING.md](https://github.com/netbirdio/netbird/blob/main/CONTRIBUTING.md#discuss-changes-with-the-netbird-team-first). The design discussion is continuing in #5821 and this draft. This checkbox will be updated after maintainer confirmation. > By submitting this pull request, you confirm that you have read and agree to the terms of the [Contributor License Agreement](https://github.com/netbirdio/netbird/blob/main/CONTRIBUTOR_LICENSE_AGREEMENT.md). ## Documentation Select exactly one: - [x] I added/updated documentation for this change - [ ] Documentation is **not needed** for this change (explain why) ### Docs PR URL (required if "docs added" is checked) https://github.com/netbirdio/docs/pull/867 <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added ordered multi-port L4 support for reverse-proxy services via `port_mappings`, plus capability reporting (`supports_port_mappings`) and HTTP-domain aware service lookup. * Added HTTP-domain scoped service lookup and ephemeral resolution by peer+domain for OIDC/session flows. * **Bug Fixes** * Canonicalized domains/hosts end-to-end (service resolution, auth, SNI routing, and OIDC redirects) to prevent mismatches and ownership edge cases. * Strengthened port conflict handling, deterministic port assignment, and multi-port update validation. * **Migration** * Added migrations to canonicalize shared domains, backfill legacy services into `port_mappings`, and update ownership/overlap safety checks. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
saavagebueno added the pull-request label 2026-08-05 08:09:30 -04:00
Sign in to join this conversation.
No Label pull-request
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: DYNR/netbird#29950