Fix for issue #4960 PM2 cluster mode ECONNREFUSED errors

[bram-atmire]

References

• Fixes PM2 fails in cluster mode for localhost because it defaults to IPv6 over IPv4 #4960

Description

Node.js 17+ changed DNS resolution to prefer IPv6 over IPv4. When running in PM2 cluster mode, this causes "ECONNREFUSED ::1:8080" errors if the backend only listens on IPv4 (127.0.0.1).

This fix sets dns.setDefaultResultOrder('ipv4first') at the very start of the SSR bootstrap to ensure localhost resolves to IPv4.

See: nodejs/node#40537

Instructions for Reviewers

List of changes in this PR:

• Added dns.setDefaultResultOrder('ipv4first') at the top of src/main.server.ts before any other imports
• This ensures Node.js resolves "localhost" to IPv4 (127.0.0.1) instead of IPv6 (::1)

How to test:

1. Build the production app: npm run build:prod
2. Start with PM2 in cluster mode: pm2 start dspace-ui.json (ensure exec_mode: "cluster" in config)
3. Access http://localhost:4000/ - should return HTTP 200
4. Without this fix, you would see "ECONNREFUSED ::1:8080" errors in the PM2 logs and HTTP 500 responses

Note: This issue only occurs when:

• Running Node.js 17+ (which prefers IPv6 for DNS resolution)
• Using PM2 cluster mode (fork mode is unaffected)
• The backend (Tomcat) only listens on IPv4

Checklist

• My PR is created against the main branch of code (unless it is a backport or is fixing an issue specific to an older branch).
• My PR is small in size (e.g. less than 1,000 lines of code, not including comments & specs/tests), or I have provided reasons as to why that's not possible.
• My PR passes ESLint validation using npm run lint
• My PR doesn't introduce circular dependencies (verified via npm run check-circ-deps)
• My PR includes TypeDoc comments for all new (or modified) public methods and classes. It also includes TypeDoc for large or complex private methods.
• My PR passes all specs/tests and includes new/updated specs or tests based on the Code Testing Guide.
• My PR aligns with Accessibility guidelines if it makes changes to the user interface. (N/A - no UI changes)
• My PR uses i18n (internationalization) keys instead of hardcoded English text, to allow for translations. (N/A - no user-facing text)
• My PR includes details on how to test it. I've provided clear instructions to reviewers on how to successfully test this fix or feature.
• If my PR includes new libraries/dependencies (in package.json), I've made sure their licenses align with the DSpace BSD License based on the Licensing of Contributions documentation. (N/A - uses built-in Node.js dns module)
• If my PR includes new features or configurations, I've provided basic technical documentation in the PR itself.
• If my PR fixes an issue ticket, I've linked them together.

[jesielviana]

Good fix!
Would it be better to make the DNS resolution order configurable through config.yml (e.g. something like defaultDnsResultOrder: ipv4first)?
That way, we could easily change the preference between IPv4 and IPv6 without needing to update the code.

[bram-atmire]

@jesielviana Thanks for the suggestion! I'm curious: are there scenarios where you'd want to configure this differently? I'm trying to think through when ipv6first (or other values) would be beneficial.

My (limited!!!) understanding is that most backend deployments use dual-stack (both IPv4 and IPv6), so ipv4first should work regardless of whether the backend supports IPv6. Even if the backend has IPv6 support, trying IPv4 first just means it falls back to IPv6 if IPv4 fails.

The issue we're fixing is specifically that Node.js 17+ changed to prefer IPv6, which causes connection failures in PM2 cluster mode when the Node process tries to connect via ::1 instead of 127.0.0.1. This happens even when the backend supports both protocols.

That said, I might be missing something! If there's a deployment scenario where configurable DNS resolution order would be helpful, I'd be happy to add that. Do you have a specific use case in mind?

[jesielviana]

@bram-atmire I don’t have much experience in this area either, but I was thinking that in a dual-stack setup, some users might want to prioritize IPv6 over IPv4, depending on their infrastructure or network preferences.

That said, I agree that ipv4first is a sensible default since it should work reliably in most environments.

[tdonohue]

@bram-atmire : Thanks for this small PR. While I haven't tested it myself it seems logical to me. However, I do have a small suggestion regarding the inline comments below...I think we need to remove the header you've added to this file. Beyond that, it looks good. (Regarding the discussion above, I don't think we need to make this configurable until there's a good reason to do so. That can always be a future enhancement if there's not a good reason at this time.)

[tdonohue]

@bram-atmire : Can we remove this comment from the header of the file, as this comment doesn't apply to the entire file. Instead, you can move some of these details down next to the new setDefaultResultOlder() call.. maybe say something like this:

// Apply DNS resolution order fix for Node.js 17+ by preferring IPv4 over IPv6.
// This fixes "ECONNREFUSED ::1:8080" errors in PM2 cluster mode the backend only listens on IPv4
// See https://github.com/DSpace/dspace-angular/issues/4960
setDefaultResultOrder('ipv4first');

[bram-atmire]

@tdonohue done!