Move Netty to Separate Module (#3551)

This PR implements sub-issue #3551 as part of the artifact modularization effort described in #3470.

The goal of this change is to separate the Netty implementation from the main zio-http artifact so that transport-specific code is modular and can evolve independently.


Summary

A new zio-http-netty module has been introduced to host all Netty-based server and client implementations. Previously, these sources lived inside the zio-http/jvm project.

By moving Netty into its own artifact, we reduce coupling between core HTTP abstractions and the Netty transport layer, making the project easier to maintain and extend.


Changes

1. New zio-http-netty sbt project

  • Introduced a new module:

    • zio-http-netty
  • This module now contains all Netty-related implementations.

2. Source migrations

All sources under:

zio-http/jvm/src/main/scala/zio/http/netty

were moved to:

zio-http-netty/src/main/scala/zio/http/netty

This includes all Netty server, client, model, and socket related code (25+ files).

3. Public API additions

New API objects were introduced in the zio.http package to provide access to Netty implementations.

NettyServer

  • NettyServer.live
  • NettyServer.customized
  • NettyServer.default
  • NettyServer.defaultWithPort()

NettyClient

  • NettyClient.live
  • NettyClient.customized
  • NettyClient.default
  • NettyClient.configured()

These APIs provide a clear entry point for using the Netty driver while keeping the core module transport-agnostic.

4. Platform-specific stubs

The following platform-specific components were updated:

  • ServerPlatformSpecific
  • DriverPlatformSpecific
  • ZClientPlatformSpecific

These now throw UnsupportedOperationException when used without the Netty module.

They were implemented as def instead of val to avoid class initialization failures during JVM startup.

Additionally:

  • Server.default was changed to a lazy val to prevent premature initialization.

5. Test migrations

All Netty integration tests were moved to the new module:

zio-http-netty/src/test

This ensures that Netty-specific functionality is tested only within the Netty module.


Test Results

All existing tests were executed after the refactor.

zioHttpJVM/test
1191 passed
0 failed
zioHttpNetty/test
552 passed

A few failures were observed in NettyConnectionPoolSpec timeout tests. These failures appear to be pre-existing flaky tests, as they also occur on the original branch before this refactor.


Outcome

This change:

  • Decouples Netty transport implementation from the core HTTP abstractions
  • Establishes the zio-http-netty module as the Netty driver implementation
  • Maintains backward compatibility through the new NettyServer and NettyClient APIs
  • Keeps the project aligned with the broader modularization goals of #3470

Next Steps

This PR focuses only on the Netty module extraction. Future steps in the modularization effort may include:

  • moving the endpoint DSL to a separate module
  • continuing refactoring of encoding implementations
  • further refining module boundaries /claim #3472

Claim

Total prize pool $250
Total paid $0
Status Pending
Submitted March 14, 2026
Last updated March 14, 2026

Contributors

HA

Harsh Singh

@singhharsh1708

100%

Sponsors

ZI

ZIO

@ZIO

$250