fix: IPv6 host support #4367

hrishikesh-nalawade · 2025-10-29T12:18:35Z

Description

Code changes to support IPv6 address

Linked to #4318

Type of change

Please delete options that are not relevant.

fix: Bug fix (non-breaking change which fixes an issue)

Checklist:

My code follows the style guidelines of this project
PR title conforms to commit message guideline ## Commit Message Structure Guideline
I have commented my code, particularly in hard-to-understand areas. In JS I did provide JSDoc
I have made corresponding changes to the documentation
My changes generate no new warnings
I have added tests that prove my fix is effective or that my feature works
New and existing unit tests pass locally with my changes
The java tests in the area I was working on leverage @nested annotations
Any dependent changes have been merged and published in downstream modules

Signed-off-by: hrishikesh-nalawade <[email protected]>

Copilot

Pull Request Overview

This PR implements IPv6 host support across the APIML codebase by replacing manual URL string formatting with a centralized utility class to properly handle IPv6 addresses. IPv6 addresses require square brackets in URLs to be RFC-compliant.

Added UrlUtils utility class with methods to format IPv6 addresses correctly
Updated URL construction throughout the codebase to use the new utility methods
Added proper IPv6 address handling in route definitions and service registrations

Reviewed Changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
common-service-core/src/main/java/org/zowe/apiml/util/UrlUtils.java	New utility class with IPv6-aware URL formatting methods
zaas-service/src/main/java/org/zowe/apiml/zaas/cache/CachingServiceClient.java	Replaced manual URL formatting with UrlUtils.getUrl()
security-service-client-spring/src/main/java/org/zowe/apiml/security/client/service/GatewaySecurityService.java	Updated login, query, and OIDC validation endpoints to use UrlUtils
gateway-service/src/main/java/org/zowe/apiml/gateway/services/ServicesInfoService.java	Updated base URL construction for service info
gateway-service/src/main/java/org/zowe/apiml/gateway/service/routing/RouteDefinitionProducer.java	Added comprehensive IPv6 handling for route definitions and external URLs
gateway-service/src/main/java/org/zowe/apiml/gateway/service/GatewayIndexService.java	Updated WebClient base URL construction
gateway-service/src/main/java/org/zowe/apiml/gateway/filters/ZaasSchemeTransformRest.java	Added hostname formatting for ZAAS requests
gateway-service/src/main/java/org/zowe/apiml/gateway/config/RegistryConfig.java	Updated gateway service address configuration for IPv6
gateway-service/src/main/java/org/zowe/apiml/gateway/caching/CachingServiceClientRest.java	Updated caching service URL construction
api-catalog-services/src/main/java/org/zowe/apiml/apicatalog/swagger/api/ApiDocV3Service.java	Updated OpenAPI server URL formatting
api-catalog-services/src/main/java/org/zowe/apiml/apicatalog/swagger/ApiDocRetrievalServiceLocal.java	Updated SpringDoc server URL construction

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

...ay-service/src/main/java/org/zowe/apiml/gateway/service/routing/RouteDefinitionProducer.java

common-service-core/src/main/java/org/zowe/apiml/util/UrlUtils.java

…tting

achmelo · 2025-10-30T09:57:41Z

api-catalog-services/src/main/java/org/zowe/apiml/apicatalog/swagger/api/ApiDocV3Service.java

            openAPI.getServers()
                .forEach(server -> server.setUrl(
-                    String.format("%s://%s/%s", scheme, getHostname(), server.getUrl())));
+                    UrlUtils.getUrl(scheme, UrlUtils.formatHostnameForUrl(getHostname())) + "/" + server.getUrl()));


getHostname() returns host+port, which contains ":" even if there is no IPv6 address. This will probably create an incorrect URL

I've considered the possibility that getHostname() might be returning the host along with the port, and I've added handling for that here. But, I suspect the issue might be related to the formatHostnameForUrl() method. I'll take a closer look to better understand what's going wrong.

achmelo · 2025-10-30T09:58:27Z

common-service-core/src/main/java/org/zowe/apiml/util/UrlUtils.java

+        }
+
+        // Check if this is an IPv6 address (contains multiple colons)
+        if (hostname.contains(":") && !hostname.startsWith("[")) {


is it safe to assume that any address containing ":" is IPv6? Isn't there a better validation?

Yes, that’s a valid point. I also feel that relying solely on ":" for validation might not be sufficient. I’ll explore better alternatives and see what could work more reliably.

Signed-off-by: hrishikesh-nalawade <[email protected]>

…host-formatting' into hrishikesh-nalawade/GH4318/IPv6-host-formatting

Signed-off-by: hrishikesh-nalawade <[email protected]>

…tting

Signed-off-by: hrishikesh-nalawade <[email protected]>

…tting

Signed-off-by: hrishikesh-nalawade <[email protected]>

…host-formatting' into hrishikesh-nalawade/GH4318/IPv6-host-formatting

Signed-off-by: hrishikesh-nalawade <[email protected]>

…tting

achmelo · 2025-11-10T09:38:00Z

common-service-core/src/main/java/org/zowe/apiml/util/UrlUtils.java

+
+        // Check for hostname:port format
+        int lastColonIndex = hostname.lastIndexOf(':');
+        if (lastColonIndex > -1) {
+            String possibleHost = hostname.substring(0, lastColonIndex);
+            String possiblePort = hostname.substring(lastColonIndex + 1);
+
+            // Check if what follows the last colon is a valid port number
+            if (isValidPort(possiblePort)) {
+                // If we have a port, check if the host part is IPv6
+                if (isIPv6Address(possibleHost)) {
+                    return "[" + possibleHost + "]:" + possiblePort;
+                }
+                // If the full string is NOT IPv6, return as-is
+                if (!isIPv6Address(hostname)) {
+                    return hostname; // Regular hostname:port or IPv4:port
+                }
+                // Otherwise, fall through to check if full hostname is IPv6
+            }
+        }
+
+        // No port number, check if it's a plain IPv6 address
+        if (isIPv6Address(hostname)) {
+            return "[" + hostname + "]";
+        }
+


Suggested change

// Check for hostname:port format

int lastColonIndex = hostname.lastIndexOf(':');

if (lastColonIndex > -1) {

String possibleHost = hostname.substring(0, lastColonIndex);

String possiblePort = hostname.substring(lastColonIndex + 1);

// Check if what follows the last colon is a valid port number

if (isValidPort(possiblePort)) {

// If we have a port, check if the host part is IPv6

if (isIPv6Address(possibleHost)) {

return "[" + possibleHost + "]:" + possiblePort;

}

// If the full string is NOT IPv6, return as-is

if (!isIPv6Address(hostname)) {

return hostname; // Regular hostname:port or IPv4:port

}

// Otherwise, fall through to check if full hostname is IPv6

}

}

// No port number, check if it's a plain IPv6 address

if (isIPv6Address(hostname)) {

return "[" + hostname + "]";

}

// SECURITY: Check if the entire string is a valid IPv6 address first

// This prevents incorrectly splitting IPv6 addresses that might have

// numeric suffixes that look like ports

if (isIPv6Address(hostname)) {

return "[" + hostname + "]";

}

// Check for hostname:port format

// Only split if we're sure it's not an IPv6 address

int lastColonIndex = hostname.lastIndexOf(':');

if (lastColonIndex > -1) {

String possibleHost = hostname.substring(0, lastColonIndex);

String possiblePort = hostname.substring(lastColonIndex + 1);

// Check if what follows the last colon is a valid port number

if (isValidPort(possiblePort)) {

// SECURITY: Verify the host part is NOT an IPv6 address

// If it is, we need to bracket just the IPv6 part, not the entire string

if (isIPv6Address(possibleHost)) {

// This is an unbracketed IPv6 address with port - format correctly

return "[" + possibleHost + "]:" + possiblePort;

}

// If the host part is not IPv6, it's safe to treat as hostname:port

return hostname; // Regular hostname:port or IPv4:port

}

}

It is better to check for IPv6 address before looking for port number

Hello @achmelo ,
The problem with checking the entire string as IPv6 before is that, in case where port is present with host (example: - 2001:db8::1:8080), The InetAddress verifies this as a IPv6 address and will return true. Hence resulting into incorrect formatting of complete string [2001:db8::1:8080].
Though your concern "This prevents incorrectly splitting IPv6 addresses that might have numeric suffixes that look like ports" is very much valid and I have handled these scenarios where I have made sure that IPv6 string is returned properly.

achmelo · 2025-11-10T11:54:57Z

common-service-core/src/main/java/org/zowe/apiml/util/UrlUtils.java

+        }   
+
+        // Remove any existing scheme if present
+        String cleanHostWithPort = hostWithPort.replaceFirst("^\\w+://", "");


Suggested change

String cleanHostWithPort = hostWithPort.replaceFirst("^\\w+://", "");

String cleanHostWithPort = hostWithPort.replaceFirst("^[a-zA-Z][a-zA-Z0-9+.-]*://", "");

is probably more accurate according to the RFC 3986

Thank You, I have applied your suggestion.

achmelo · 2025-11-10T11:57:26Z

gateway-service/src/main/java/org/zowe/apiml/gateway/config/RegistryConfig.java

+            // Handle IPv6 address format using UrlUtils
+            if (host != null) {
+                host = UrlUtils.formatHostnameForUrl(host);
+            }


if host == null, is it ok to continue? it will probably throw some error in the builder

Thank you for pointing that out, I have corrected the above

achmelo · 2025-11-10T11:59:13Z

...ay-service/src/main/java/org/zowe/apiml/gateway/service/routing/RouteDefinitionProducer.java

+                        output = newUri.toString();
+                    }
+                } catch (URISyntaxException e) {
+                    // If there's an error parsing the URI, keeping the original URL


some debug log would be good here

added, Thank You

achmelo · 2025-11-10T11:59:37Z

...ay-service/src/main/java/org/zowe/apiml/gateway/service/routing/RouteDefinitionProducer.java

+                        ).toString();
+                    }
+                } catch (URISyntaxException e) {
+                    // Keep original if URI parsing fails


debug log would be good

added, Thank You

achmelo · 2025-11-10T12:25:13Z

common-service-core/src/main/java/org/zowe/apiml/util/UrlUtils.java

+        throw new IllegalArgumentException("Host cannot be null or empty");
+        }   
+
+        // Remove any existing scheme if present


is it possible that there will be scheme if the parameter is called hostWithPort?

I have added this just to safeguard us if any caller passes value which may contain scheme, also as it's a single regex check hence, computationally cheap for us and makes sure correct host/host+port is sent.

...og-services/src/main/java/org/zowe/apiml/apicatalog/swagger/ApiDocRetrievalServiceLocal.java

gateway-service/src/main/java/org/zowe/apiml/gateway/services/ServicesInfoService.java

Signed-off-by: hrishikesh-nalawade <[email protected]>

…tting

Signed-off-by: hrishikesh-nalawade <[email protected]>

…tting

Signed-off-by: hrishikesh-nalawade <[email protected]>

…host-formatting' into hrishikesh-nalawade/GH4318/IPv6-host-formatting

Signed-off-by: hrishikesh-nalawade <[email protected]>

sonarqubecloud · 2025-11-27T19:21:12Z

Quality Gate failed

Failed conditions
35.2% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

IPv6 host support

c702446

Signed-off-by: hrishikesh-nalawade <[email protected]>

github-project-automation bot added this to API Mediation Layer Backlog Management Oct 29, 2025

github-project-automation bot moved this to New in API Mediation Layer Backlog Management Oct 29, 2025

pull-request-size bot added the size/L label Oct 29, 2025

github-actions bot added the Sensitive Sensitive change that requires peer review label Oct 29, 2025

hrishikesh-nalawade requested a review from Copilot October 29, 2025 12:18

Copilot AI reviewed Oct 29, 2025

View reviewed changes

hrishikesh-nalawade requested review from achmelo and pablocarle October 29, 2025 12:20

hrishikesh-nalawade changed the title ~~IPv6 host support~~ fix: IPv6 host support Oct 29, 2025

EvaJavornicka moved this from New to In Progress in API Mediation Layer Backlog Management Oct 29, 2025

Merge branch 'v3.x.x' into hrishikesh-nalawade/GH4318/IPv6-host-forma…

623960f

…tting

achmelo reviewed Oct 30, 2025

View reviewed changes

hrishikesh-nalawade and others added 4 commits November 5, 2025 17:08

IPv6 host support enhancements

99e1065

Signed-off-by: hrishikesh-nalawade <[email protected]>

Merge remote-tracking branch 'origin/hrishikesh-nalawade/GH4318/IPv6-…

93d577c

…host-formatting' into hrishikesh-nalawade/GH4318/IPv6-host-formatting

corrections

0ca2efa

Signed-off-by: hrishikesh-nalawade <[email protected]>

Merge branch 'v3.x.x' into hrishikesh-nalawade/GH4318/IPv6-host-forma…

b1307ad

…tting

hrishikesh-nalawade requested a review from achmelo November 5, 2025 13:45

hrishikesh-nalawade and others added 5 commits November 7, 2025 16:14

test modifications

170d4e5

Signed-off-by: hrishikesh-nalawade <[email protected]>

Merge branch 'v3.x.x' into hrishikesh-nalawade/GH4318/IPv6-host-forma…

a473483

…tting

test modifications

cb213d6

Signed-off-by: hrishikesh-nalawade <[email protected]>

Merge remote-tracking branch 'origin/hrishikesh-nalawade/GH4318/IPv6-…

a3279b3

…host-formatting' into hrishikesh-nalawade/GH4318/IPv6-host-formatting

temporarily removing test

f739842

Signed-off-by: hrishikesh-nalawade <[email protected]>

pull-request-size bot added size/XXL and removed size/L labels Nov 7, 2025

hrishikesh-nalawade added 2 commits November 7, 2025 17:12

temporarily removing test

2907323

Signed-off-by: hrishikesh-nalawade <[email protected]>

reverting test changes

7ffa42f

Signed-off-by: hrishikesh-nalawade <[email protected]>

pull-request-size bot added size/L and removed size/XXL labels Nov 7, 2025

Merge branch 'v3.x.x' into hrishikesh-nalawade/GH4318/IPv6-host-forma…

c01baff

…tting

achmelo requested changes Nov 10, 2025

View reviewed changes

hrishikesh-nalawade and others added 11 commits November 17, 2025 16:07

code changes

a0dc139

Signed-off-by: hrishikesh-nalawade <[email protected]>

added debug logs

2a5ef3b

Signed-off-by: hrishikesh-nalawade <[email protected]>

Merge branch 'v3.x.x' into hrishikesh-nalawade/GH4318/IPv6-host-forma…

f4ad343

…tting

Merge branch 'v3.x.x' into hrishikesh-nalawade/GH4318/IPv6-host-forma…

83d1253

…tting

Merge branch 'v3.x.x' into hrishikesh-nalawade/GH4318/IPv6-host-forma…

a378cb8

…tting

Test Changes

52580af

Signed-off-by: hrishikesh-nalawade <[email protected]>

Merge branch 'v3.x.x' into hrishikesh-nalawade/GH4318/IPv6-host-forma…

c253933

…tting

Removing deprecated code from test

fe7c7b9

Signed-off-by: hrishikesh-nalawade <[email protected]>

Merge remote-tracking branch 'origin/hrishikesh-nalawade/GH4318/IPv6-…

f480f23

…host-formatting' into hrishikesh-nalawade/GH4318/IPv6-host-formatting

test fix

a00a7df

Signed-off-by: hrishikesh-nalawade <[email protected]>

Removing strict validation which is causing starUpCheck failure

98d6b2c

Signed-off-by: hrishikesh-nalawade <[email protected]>

hrishikesh-nalawade mentioned this pull request Nov 30, 2025

Snapshot for testing IPv6 support zowe/zowe-install-packaging#4612

Open

4 tasks

	String cleanHostWithPort = hostWithPort.replaceFirst("^\\w+://", "");
	String cleanHostWithPort = hostWithPort.replaceFirst("^[a-zA-Z][a-zA-Z0-9+.-]*://", "");

fix: IPv6 host support #4367

Are you sure you want to change the base?

fix: IPv6 host support #4367

Uh oh!

Conversation

hrishikesh-nalawade commented Oct 29, 2025

Description

Type of change

Checklist:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hrishikesh-nalawade Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

sonarqubecloud bot commented Nov 27, 2025

Quality Gate failed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

hrishikesh-nalawade Nov 17, 2025 •

edited

Loading