Migrating the WebSocket Transport

 

Author: Eike Stepper

Net4j WS 2 separates WebSocket protocol integration from the implementation that performs WebSocket I/O. This article explains how to migrate existing WS and WSS deployments, clients, and Jetty servers to that design. It also identifies the parts that remain compatible so that operators can limit changes to the installations that need them.

Table of Contents

1 Migration Overview
2 Dependencies and Deployment
3 Migrating WebSocket Clients
4 Migrating WebSocket Servers
5 Migrating Security and Proxy Configuration
6 Migration Checklist
7 Troubleshooting

1  Migration Overview

Issue #226 replaces a Jetty-specific transport implementation in the provider-neutral WS bundle with a Net4j framing layer and message-connection providers. The built-in provider uses the JDK WebSocket client. A separate optional bundle adapts Jetty 12 servers. This keeps Jetty server dependencies out of the core client transport and lets applications supply clients with their own TLS, proxy, and authentication policy.

Migrate an installation when it uses the removed Jetty client classes, subclasses or configures the old Net4jWebSocketServlet, depends on implicit Eclipse proxy discovery, or packages the old Jetty client dependencies as part of Net4j WS. A server without a Jetty host can keep using the WS acceptor API with its own provider integration. The WS/WSS URI schemes, named acceptor routing, Net4j channels, and WS/WSS acceptor configuration model remain. Connector descriptions continue to identify the service endpoint and acceptor route; current descriptions can additionally select a provider and carry handshake cookies.

The operator-facing before/after differences are:

Continue with server deployment, client configuration, TLS setup, and operations and troubleshooting.

2  Dependencies and Deployment

Deploy the org.eclipse.net4j.ws feature (or its org.eclipse.net4j.ws bundle) for WS and WSS connectors and acceptors. It contributes the WS and WSS factories and registers the JDK message-connection provider under type jdk. A managed container created with ContainerUtil.createInitializedContainer() receives these contributions through bundle initialization.

Remove the old Jetty EE8 WebSocket client and server dependencies that were required only by the former core WS bundle. Do not remove Jetty modules that the application independently needs. For a Jetty-hosted endpoint, add the optional org.eclipse.net4j.ws.jetty.server bundle and compatible Jetty 12 server and WebSocket modules. The org.eclipse.net4j.ws.jetty.server feature includes both the core WS feature and server adapter. That adapter bundle requires Jetty 12; it is not a replacement client dependency.

The embedding application now owns the Jetty Server, its connectors and TLS configuration, handler tree, startup and shutdown. It also owns custom JDK HttpClient instances passed to provider factories. Net4j owns the connectors and acceptors registered in its managed container.

There is no new XML setting for creating custom JDK clients or embedding the Jetty upgrade handler. Those are Java object configuration tasks; keep XML acceptor declarations where they continue to describe the acceptor. This valid WS acceptor declaration uses the same configuration mechanism as the CDO server configuration:

ws‑acceptor.xml      
<?xml version="1.0" encoding="UTF-8"?>
<cdoServer>
  
<acceptor type="ws" name="production" />
</cdoServer>

3  Migrating WebSocket Clients

The JDK provider is selected by default, so a normal WS or WSS connector needs no provider token. Use the utility methods to construct connector descriptions rather than assembling route paths by hand. A description targets the named acceptor at the service URI; optional arguments include provider selection and cookie:name=value handshake cookies. The cookie argument is configuration data, so do not put credentials or session secrets in a persistent or logged connector description.

The following example creates its own container and connects one WS connector through the default JDK provider. It closes that connector individually, then deactivates the container it created. For WSS, use the WSS connector factory through WSSUtil together with a wss URI; changing the URI scheme alone does not select the secure connector factory.

DefaultJDKClient.java      
IManagedContainer container = ContainerUtil.createInitializedContainer();
IWSConnector ws = null;

try
{
  ws = WSUtil.getConnector(container, URI.create("ws://gateway.example.net/net4j"), "production");
  ws.connect(5_000);
  // Use the connected WS connector here.
}
finally
{
  try
  {
    if (ws != null)
    {
      ws.close();
    }
  }
  finally
  {
    LifecycleUtil.deactivate(container);
  }
}

For a custom TLS trust configuration or proxy policy, register a provider factory configured with a caller-owned HttpClient in the same container. The example connects a WSS endpoint with the corporate provider, a bounded timeout, and a handshake cookie, then closes the connector and its privately owned container. It uses the JDK default trust context; substitute the application's configured trust context when required. The provider and connector do not close the HttpClient; the application must retain it while any connector can use it. Java 11's client has no close method; on Java 21 and later, close it only after its connectors stop. The example marks that version-specific cleanup without making this Java 11 source depend on the newer method.

ConfiguredJDKClient.java      
IManagedContainer container = ContainerUtil.createInitializedContainer();
IWSConnector connector = null;
HttpClient httpClient = null;

try
{
  SSLContext sslContext = SSLContext.getDefault();
  httpClient = HttpClient.newBuilder().sslContext(sslContext).proxy(ProxySelector.of(new InetSocketAddress("proxy.example.net", 8080)))
      .connectTimeout(Duration.ofSeconds(10)).build();

  IFactory provider = JDKWSUtil.createMessageConnectionFactory("corporate", httpClient, Duration.ofSeconds(10));
  container.registerFactory(provider);

  String description = WSSUtil.getConnectorDescription(URI.create("wss://gateway.example.net/net4j"), "production", "provider:corporate",
      "cookie:tenant=example");
  connector = WSSUtil.getConnector(container, description);
  connector.connect(5_000);
  // Use the connected WSS connector here.
}
catch (NoSuchAlgorithmException ex)
{
  throw new IllegalStateException(ex);
}
finally
{
  try
  {
    if (connector != null)
    {
      connector.close();
    }
  }
  finally
  {
    LifecycleUtil.deactivate(container);
  }
  // On Java 21+, close httpClient here after the connector and container have stopped.
}

A connector can be closed without deactivating a shared container. Deactivate a container only when its owner is shutting down the container and all products it manages.

Retain the complete factory description. IConnector.getURL() reports the transport endpoint; for WS/WSS it omits provider selection and handshake cookies. Reconstructing an equivalent connector from that URL may silently select the default jdk provider, losing a custom WSS trust configuration. Retain the original description passed to WSUtil/WSSUtil, or ask the registered connector factory for its description with IFactory.getDescriptionFor(Object). For example, use the factory for ConnectorFactory.PRODUCT_GROUP and the WS or WSS factory type selected from the connector's scheme.

CompleteConnectorDescription.java      
IManagedContainer container = ContainerUtil.createInitializedContainer();
try
{
  HttpClient httpClient = HttpClient.newBuilder().build();
  IFactory provider = JDKWSUtil.createMessageConnectionFactory("corporate", httpClient, Duration.ofSeconds(10));
  container.registerFactory(provider);

  IWSConnector connector = WSSUtil.getConnector(container, URI.create("wss://gateway.example.net/net4j"), "production", "provider:corporate",
      "cookie:tenant=example");
  IFactory factory = container.getFactory(ConnectorFactory.PRODUCT_GROUP, WSSUtil.FACTORY_TYPE);
  String completeDescription = factory.getDescriptionFor(connector);
  Properties connectorSettings = new Properties();
  connectorSettings.setProperty("wss.connector", completeDescription);

  // Hand connectorSettings to protected application storage; the description may contain sensitive cookies.
}
finally
{
  LifecycleUtil.deactivate(container);
}

4  Migrating WebSocket Servers

The previous Net4jWebSocketServlet and Jetty socket endpoint were removed from the core WS bundle. With Jetty 12, create an application-owned Server and ContextHandler, then install the returned upgrade handler before starting the server. Use a mapping such as /net4j/*; the client appends /@<acceptor-name> to that path. The utility wraps the context's existing application handler and routes only to the active acceptors passed to it. Both the decoded path suffix and the Net4jAcceptor handshake header must identify the same route.

The following example creates an initialized Net4j container and named WS acceptor, installs the adapter in an application-owned Jetty server/context, starts the server, and connects a bounded-timeout client. The adapter only creates the upgrade handler; the application starts and stops Jetty. It closes the individual client connector, stops Jetty, then deactivates the acceptor and the privately owned container. A host with a shared container should close the connector and acceptor as appropriate but leave container shutdown to its owner. WSS uses the same integration with a WSS acceptor, a WSS connector, and an application-configured HTTPS server connector.

Jetty12UpgradeHandler.java      
IManagedContainer container = ContainerUtil.createInitializedContainer();
IWSAcceptor acceptor = WSUtil.getAcceptor(container, "production");

Server server = new Server();
ServerConnector serverConnector = new ServerConnector(server);
serverConnector.setHost("127.0.0.1");
serverConnector.setPort(0);
server.addConnector(serverConnector);

ContextHandler context = new ContextHandler("/");
IWSConnector clientConnector = null;

try
{
  LifecycleUtil.activate(acceptor);

  WebSocketUpgradeHandler upgradeHandler = JettyWSUtil.createUpgradeHandler(server, context, "/net4j/*", acceptor);
  context.setHandler(upgradeHandler);
  server.setHandler(context);
  server.start();

  URI serviceURI = URI.create("ws://127.0.0.1:" + serverConnector.getLocalPort() + "/net4j");
  clientConnector = WSUtil.getConnector(container, serviceURI, "production");
  clientConnector.connect(5_000);
  // Exchange Net4j channels while the server and connector remain active.
}
catch (Exception ex)
{
  throw new IllegalStateException("Unable to start the WebSocket endpoint", ex);
}
finally
{
  try
  {
    if (clientConnector != null)
    {
      clientConnector.close();
    }
  }
  finally
  {
    try
    {
      server.stop();
    }
    catch (Exception ex)
    {
      throw new IllegalStateException("Unable to stop the application-owned Jetty server", ex);
    }
    finally
    {
      try
      {
        LifecycleUtil.deactivate(acceptor);
      }
      finally
      {
        LifecycleUtil.deactivate(container);
      }
    }
  }
}

5  Migrating Security and Proxy Configuration

Configure TLS at the layer that owns the connection. A WSS client can use the default JDK TLS context, or a custom SSLContext configured with the application's trust material. The JDK provider keeps normal certificate chain and hostname verification enabled. Never work around trust failures by disabling verification. A Jetty-hosted WSS endpoint uses the TLS configuration of the application's HTTPS server connector; the Net4j adapter does not create or own TLS connectors.

HTTP origin authentication and proxy authentication belong in the caller-configured HttpClient, typically through its Authenticator, ProxySelector, and TLS settings. WS transport no longer discovers Eclipse IProxyService implicitly. Applications that relied on Eclipse proxy preferences must translate the required policy into JDK client configuration and register a provider factory with that client.

For an HTTP CONNECT proxy, configure a proxy selector and an authenticator for proxy credentials. The JDK normally disables Basic authentication for HTTP CONNECT tunneling. Enabling it with -Djdk.http.auth.tunneling.disabledSchemes= changes JVM-wide behavior and can expose credentials to untrusted proxies; use it only after reviewing the security consequences and the proxy trust boundary. Prefer a proxy authentication scheme supported by the JDK without that override.

6  Migration Checklist

Work through this sequence for each client or server installation:

  1. Inventory the WS/WSS bundles, Jetty modules, servlet mappings, client factories, TLS settings, proxy policy, and connector descriptions in the deployed product.
  2. Deploy the provider-neutral org.eclipse.net4j.ws bundle. Remove Jetty EE8 client dependencies that existed only for the former Net4j WS implementation.
  3. For clients, replace direct Jetty WebSocket client use with Net4j WS/WSS connectors. Add a custom JDK provider only when the application requires client-specific TLS, proxy, or authentication settings.
  4. For Jetty servers, deploy the optional Jetty 12 adapter, replace the old servlet integration with JettyWSUtil.createUpgradeHandler, and ensure each route matches the URI scheme and TLS state.
  5. Move proxy, TLS trust, HTTP origin credentials, and proxy credentials into application-owned client/server configuration. Review any Basic CONNECT JVM property with security owners.
  6. Verify route names, cookies, container startup, and ownership of custom clients and servers. Exercise both WS and WSS endpoints through the production routing and shutdown path.
  7. Remove obsolete servlet classes, old Jetty client configuration, and bundle requirements only after every application consumer has migrated.

7  Troubleshooting

Missing provider factory: check that the org.eclipse.net4j.ws bundle is resolved and its factories are initialized in the same managed container that creates the connector. For a custom provider, register its factory before connector creation and ensure the provider: token exactly matches the registered type.

HTTP upgrade or routing rejection: verify the path mapping covers the service path and appended /@name route, the acceptor is active and registered under that name, and the handshake header and route agree. A request rejected with 404 commonly indicates a missing or mismatched route; 403 commonly indicates that the request's secure state does not match the WS/WSS acceptor.

TLS certificate validation failure: check the server certificate chain, the hostname in the service URI, and the trust material used by the client provider. Keep hostname and certificate verification enabled.

Authenticated proxy failure: ensure the caller-configured client actually selects the proxy and its authenticator supplies credentials for that proxy. If the proxy requires Basic CONNECT authentication, account for the JDK's disabled-by-default behavior and assess the JVM-wide property before enabling it.

Leaked or prematurely closed connections: the Net4j container owns connectors and acceptors, while the application owns custom HttpClient and Jetty server lifecycles. Stop connectors before closing a shared client, deactivate the container during shutdown, and stop the Jetty server through the application's lifecycle.