WebUI search returns no results when localhost resolves to IPv6

[junhaoliao]

(issue originally reported by @haiqi96 ; @davemarco helped investigated)

Bug

Search queries through the WebUI consistently return no results. When investigating the network traffic, the search endpoint returns the React app's index.html content instead of the expected socket.io responses. This issue appears to be related to localhost resolving to IPv6 addresses on affected systems.

CLP version

3520895

Environment

Windows 11 + Windows Docker Engine
The package was running in WSL Ubuntu Jammy

Reproduction steps

1. Start the package with default settings and compress sample logs.
2. Navigate to http://localhost:4000/search in a web browser
3. Perform a search using any query string (e.g., "*")
4. Observe that no search results are returned
5. Open browser developer tools and check the Network tab
6. Notice that the search request returns index.html content instead of socket.io responses
7. Verify that this occurs on systems where localhost resolves to IPv6 addresses

[davemarco]

Not sure this is relevant but i also saw this on fastify cli github, where they recommend 0.0.0.0 when running in container

[junhaoliao]

Not sure this is relevant but i also saw this on fastify cli github, where they recommend 0.0.0.0 when running in container

Precisely the issue indeed has to do with which address (addresses) the Fastify & the socket.io listen on, but listening on all IPv4 interface will not help in this specific case. Please see below analysis that i'm about to post

[junhaoliao]

update: i deleted the previous response since some facts listed were fundamentally incorrect. i'll post another response tomorrow

[junhaoliao]

RCA and recommended actions

Root Cause

This issue stems from IPv4/IPv6 dual-stack networking complications in WSL environments, specifically affecting how Socket.IO integrates with Fastify.

Environment-Specific Problems

WSL Limitations

1. No IPv4-IPv6 dual stack support: Unlike standard Linux systems where binding to :: (IPv6 wildcard) also binds to 0.0.0.0 (IPv4 wildcard), WSL does not support this dual-stack behavior.
2. Incomplete /etc/hosts configuration inside the WSL container: WSL doesn't include ::1 localhost mapping by default:

   127.0.0.1    localhost
   # Missing: ::1    localhost
   

Windows behavior

• Windows resolves localhost to ::1 first, then falls back to 127.0.0.1

Docker Desktop on Windows behavior

• Docker Desktop on Windows generates a different /etc/hosts configuration in containers, where an entry like ::1 localhost is included:

  junhao@GIGABYTE:~/workspace/clp/build/clp-package/sbin$ docker exec -it clp-webui-f439 cat /etc/hosts
  127.0.0.1       localhost
  ::1     localhost ip6-localhost ip6-loopback
  fe00::0 ip6-localnet
  ff00::0 ip6-mcastprefix
  ff02::1 ip6-allnodes
  

  However, the host file is different when the docker is installed in native WSL environments:

  # Show the `/etc/hosts` file inside the WebUI container
  junhao@GIGABYTE:~/workspace$ docker exec -it clp-webui-f439 cat /etc/hosts
  # This file was automatically generated by WSL. To stop automatic generation of this file, add the following entry to /etc/wsl.conf:
  # [network]
  # generateHosts = false
  127.0.0.1       localhost
  127.0.1.1       GIGABYTE.       GIGABYTE
  
  # The following lines are desirable for IPv6 capable hosts
  ::1     ip6-localhost ip6-loopback
  fe00::0 ip6-localnet
  ff00::0 ip6-mcastprefix
  ff02::1 ip6-allnodes
  ff02::2 ip6-allrouters
  

  (in fact, the above looks identical to the one in the WSL environment.)

Technical Analysis

Fastify Server Creation Issues

Fastify has special handling for localhost in its server creation logic. When the host is "localhost", it creates a secondary http.Server for the alternate address family (Fastify source), but this secondary server instance is never exposed through the main Fastify instance's .server property (source).

Socket.IO Integration Problems

Our current implementation creates the Socket.IO server using fastify.server (line 79):

this.#io = new Server<
    ClientToServerEvents,
    ServerToClientEvents,
    InterServerEvents,
    SocketData
>(fastify.server);

This creates two points of failure:

1. Primary failure: Since Fastify only exposes the main server (listening on 127.0.0.1), requests to localhost:4000 from Windows browsers (which resolve to [::1]:4000 via Docker Desktop's /etc/hosts configuration) reach the server but don't match Socket.IO's request interception logic. Fastify handles these requests and returns the React index.html instead of Socket.IO responses.

2. Secondary failure: Even if both IPv4 and IPv6 addresses were properly configured in /etc/hosts inside the WSL container, Socket.IO can only register listeners on the single mainServer instance. Requests to the secondary server would still bypass Socket.IO entirely.

Recommended Solutions

Option 1: Documentation and Environment Requirements

Approach: Clearly document Docker Desktop + WSL incompatibility

Implementation:

• Add prominent warning in documentation about Docker Desktop on Windows + WSL Ubuntu incompatibility
• Recommend installing Docker Engine directly inside WSL container (Docker Engine Ubuntu installation)

Pros:

• No code changes required
• Mitigate root cause by eliminating problematic environment

Cons:

• Limits deployment flexibility
• May inconvenience Windows + WSL + Docker Desktop on Windows users
• Doesn't solve the underlying issue

Option 2: Separate Socket.IO Server

Approach: Run Socket.IO server on dedicated port

Implementation:

• Configure Socket.IO server to listen on separate port (e.g., 4001)
• Update React client to connect using absolute URLs
• Update clp-config.yml to include Socket.IO port configuration

Pros:

• Eliminates dual-stack and server integration issues
• Works across all environments
• Cleaner separation of concerns
• More predictable networking behavior

Cons:

• Requires additional port management
• Slightly more complex configuration
• May require CORS / firewall rule updates

Option 3: Force IPv4 in Configuration

Approach: Update default configuration to use 127.0.0.1 instead of localhost

Implementation:

• Update clp-config.yml defaults:

  webui:
    host: "127.0.0.1"  # Changed from "localhost"
    port: 4000

Pros:

• Minimal configuration change
• Explicit IPv4 specification
• Maintains current architecture

Cons:

• Doesn't address underlying dual-stack issues

Option 4: Override localhost in Fastify Server (Recommended)

Approach: Modify Fastify server initialization to automatically convert localhost to 127.0.0.1

Implementation:

• Update Fastify server creation logic to detect when host is set to localhost and override it to 127.0.0.1.
• This prevents Fastify from creating dual-stack servers.

Pros:

• Transparent to users - no configuration changes required
• Eliminates dual-stack complications automatically
• Maintains existing configuration interface
• Prevents Socket.IO integration issues

Cons:

• May mask underlying networking issues
• Could be unexpected behavior for users who specifically want IPv6 / dual-stack

Recommendation

Option 4 (override localhost in Fastify server) is the most elegant solution as it addresses the root cause transparently without requiring configuration changes from users. This approach prevents Fastify from creating dual-stack servers when localhost is specified, eliminating the Socket.IO integration issues entirely.

Option 3 (force IPv4 in configuration) remains a viable alternative for a quick fix that resolves the problem with minimal changes to the default configuration.

For a more comprehensive long-term solution, Option 2 could be considered in future releases to eliminate the architectural coupling between Fastify and Socket.IO.

[junhaoliao]

The fastify-websocket plugin also had a similar issue - fastify/fastify-websocket#207
The maintainers decided to close the issue as finished because a fix that only works for fastify-websocket was applied into Fastify. If they could consider redesigning the listening flow / expose the servers, we would not have this problem with Socket.io today.

---

Option 5: HTTP Proxy for Socket.IO Routes

Approach: Use fastify-http-proxy to proxy Socket.IO requests to the appropriate address family

Implementation:

• Register a proxy for Socket.IO routes that forwards requests to the correct upstream address
• Use dns.lookup() to resolve the configured host and proxy to the appropriate address family
• Example implementation:

  fastify.register(fastifyHttpProxy, {
      // the upstream address should come from dns.lookup(listenOptions.host)
      upstream: "http://[::1]:3000/socket.io/",
      prefix: "/socket.io/",
  });

Pros:

• Leverages existing proxy infrastructure
• Maintains dual-stack capability while ensuring Socket.IO accessibility
• Flexible routing based on DNS resolution
• Can handle both IPv4 and IPv6 scenarios dynamically

Cons:

• Adds proxy layer complexity
• Requires additional dependency (fastify-http-proxy)
• May introduce latency overhead
• More complex debugging and monitoring

---

Option 5 is now recommended instead.

[junhaoliao]

Follow up: WebSocket vs Socket.IO Transport Analysis

WebSocket connections work, but Socket.IO HTTP long polling fails

WebSocket connections between the client and the server have always been working because even when the WebSocket UPGRADE request is received on the secondary server, the fix in fastify/fastify#4190 forwards the upgrade request to the main server, where the Socket.IO server intercepts and acts as a WebSocket server.

Transport Protocol Differences

Pure WebSocket Connection (ws://host:port)

1. Client sends HTTP request to WebSocket server (which must also be HTTP-capable)
2. HTTP handler responds with "upgrade permitted" message
3. Both sides switch to WebSocket-only communication

Socket.IO Connection with ["polling", "websocket"] transports

1. Client sends HTTP request to Socket.IO server indicating WebSocket capability
2. If the Socket.IO server supports WebSocket: the Socket.IO server responds with "upgrade permitted" -> client tries ws://host:port -> follows WebSocket flow above
3. If server doesn't support WebSocket: continues handling HTTP requests → client falls back to HTTP long polling

The proposed Option 5 proxy fix addresses steps 1 and 3 - ensuring Socket.IO's HTTP endpoints are accessible regardless of address family.

Reference: Experiment Results

Modifications are based on 6815890

Test 1: WebSocket-only transport works

// Client configuration
transports: ["websocket"]

• Search functionality works correctly
• Confirms WebSocket transport is unaffected by dual-stack issues

Test 2: Long polling fails without proxy

// Client configuration  
transports: ["polling"]

• Search requests hang indefinitely
• Confirms HTTP long polling requires the proxy fix

Recommended Solution: Option 5 + Transport Reordering

1. Implement HTTP proxy for Socket.IO routes (Option 5)

Ensures HTTP long polling works across all network configurations.

2. Change client transport order

sharedSocket = io(
    window.location.host,
    {
        transports: [
            "websocket",    // Try WebSocket first
            "polling",      // Fallback to HTTP long polling
        ],
    }
);

Rationale:

• WebSocket connections work reliably (unaffected by dual-stack issues)
• Avoids Socket.IO's HTTP upgrade negotiation in the common case because CLP package users typically have direct server access without WebSocket-blocking firewalls
• Maintains fallback capability for restricted environments

This approach optimizes for the common case while preserving Socket.IO's transport flexibility. If deployment assumptions change or we need to add a configuration option to disable WebSocket, we can revisit the transport priority.

[davemarco]

My own thoughts are slightly different - I think we should implement option 5 or Transport Reordering.

Option 5 does fix, but it is a bit inelegant and adds another dependency.

Transport Reording does fix for most cases, but will break if long polling fallback is used and browser sends a ipv6 and server is ipv4 (likely a rare case). It will fix @haiqi96 since server will likely support websocket

I dont think we should do both