Zlib Alternatives for Nginx

PDowney · web-flow · commit 7bdda3e025a7 · 2026-02-26T22:28:12.000-05:00
Since the Cloudflare Zlib fork has been deprecated, we implemented two experimental alternatives for Nginx: Zlib-ng and Zlib-rs. Both alternatives are designed to be drop-in replacements for the original Zlib, potentially providing improved performance and security.

Both should be considered experimental, although they should be stable and performant. We encourage users to test both alternatives and provide feedback on their performance and compatibility with Nginx.
diff --git a/.github/ci-config/enginescript-variables-ci.txt b/.github/ci-config/enginescript-variables-ci.txt
@@ -18,6 +18,8 @@ PHP_VER="8.5"
 PHPMYADMIN_VER="5.2.3"
 PNGOUT_VER="20200115"
 ZLIB_VER="1.3.2"
+ZLIB_NG_VER="2.3.3"
+ZLIB_RS_VER="v0.6.0"
 
 # EngineScript Plugins
 SSE_PLUGIN_VER="1.9.1"
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -2,29 +2,20 @@
 applyTo: '**'
 ---
 
-# CRITICAL BEHAVIORS (Must Follow)
+# BEHAVIOR RULES
 
 ## Complete Code Analysis - No Shortcuts
 
-- Read files completely and thoroughly, minimum 1500 lines per read operation
-- Process entire files: all functions, classes, variables, imports, exports, structures
-- Reference specific sections throughout entire codebase to demonstrate full understanding
+- Read files completely and thoroughly before making changes
 - Understand complete context: how functions interact, variables used across entire file
 
-## Direct Action - No Permission Asking
+## Communication Standards
 
-- Do not ask for confirmation before making changes - proceed automatically
-- Only ask for confirmation when action could affect system stability or security
-- Change summaries should be concise, focusing on specific changes made
-- Never create change summaries as new .md files
-
-## Clear Communication Standards
-
-- Provide clear, concise, actionable information in chat interface only
+- Provide clear, concise, actionable information
 - Use formatting and styling to enhance readability
-- Avoid unnecessary verbosity or complexity in explanations
+- Change summaries should be concise, focusing on specific changes made
 
-# PROJECT CONTEXT & FOCUS
+# PROJECT STANDARDS
 
 ## EngineScript - LEMP Server Automation
 
@@ -44,13 +35,10 @@ applyTo: '**'
 
 ## System Compatibility & Standards
 
-- **Target OS**: Ubuntu 24.04 LTS exclusively
 - **Architecture**: Follow Linux Filesystem Hierarchy Standard (FHS)
 - **Service Management**: systemd for all service configuration
 - **Security**: Production-ready configurations, secure by default, principle of least privilege
 
-# ESSENTIAL STANDARDS
-
 ## Security & Data Handling (Critical)
 
 - **Input Validation**: Sanitize all input/output, especially user-provided configuration data
@@ -61,7 +49,6 @@ applyTo: '**'
 
 - **CHANGELOG.md**: Always document changes when modifying codebase (continuous improvement model)
 - **Key Files**: Keep updated: README.md, script headers, configuration templates
-- **Commit Messages**: Clear, descriptive messages explaining purpose and scope
 - **Breaking Changes**: Document new dependencies, system requirements prominently
 - **Manual Steps**: Document any required manual steps after updates
 
@@ -73,8 +60,5 @@ applyTo: '**'
 - **Clean Code**: Remove unused code automatically, consistent patterns
 - **Separation**: Use configuration files and templates appropriately
 - **Backward Compatibility**: Maintain unless explicitly breaking changes required
-
-## Performance & Reliability
-
 - **Logging**: Actionable errors with appropriate detail levels
 - **Dependencies**: Verify compatibility when introducing new software
diff --git a/.github/workflows/software-version-check.yml b/.github/workflows/software-version-check.yml
@@ -212,6 +212,34 @@ jobs:
             echo "::warning::Failed to fetch Zlib version, keeping current version"
           fi
           
+          # zlib-ng
+          echo "::debug::Fetching zlib-ng version..."
+          ZLIB_NG_API_RESPONSE=$(curl -s https://api.github.com/repos/zlib-ng/zlib-ng/releases/latest)
+          echo "::debug::zlib-ng API Response: $ZLIB_NG_API_RESPONSE"
+          
+          LATEST_ZLIB_NG=$(echo "$ZLIB_NG_API_RESPONSE" | jq -r '.tag_name // empty')
+          echo "::debug::Parsed zlib-ng version: '$LATEST_ZLIB_NG'"
+          
+          if [[ -n "$LATEST_ZLIB_NG" && "$LATEST_ZLIB_NG" != "null" ]]; then
+            check_version "ZLIB_NG_VER" "$LATEST_ZLIB_NG"
+          else
+            echo "::warning::Failed to fetch zlib-ng version, keeping current version"
+          fi
+          
+          # zlib-rs
+          echo "::debug::Fetching zlib-rs version..."
+          ZLIB_RS_API_RESPONSE=$(curl -s https://api.github.com/repos/trifectatechfoundation/zlib-rs/releases/latest)
+          echo "::debug::zlib-rs API Response: $ZLIB_RS_API_RESPONSE"
+          
+          LATEST_ZLIB_RS=$(echo "$ZLIB_RS_API_RESPONSE" | jq -r '.tag_name // empty')
+          echo "::debug::Parsed zlib-rs version: '$LATEST_ZLIB_RS'"
+          
+          if [[ -n "$LATEST_ZLIB_RS" && "$LATEST_ZLIB_RS" != "null" ]]; then
+            check_version "ZLIB_RS_VER" "$LATEST_ZLIB_RS"
+          else
+            echo "::warning::Failed to fetch zlib-rs version, keeping current version"
+          fi
+          
           # liburing
           echo "::debug::Fetching liburing version..."
           LIBURING_API_RESPONSE=$(curl -s https://api.github.com/repos/axboe/liburing/tags)
@@ -367,6 +395,8 @@ jobs:
                 -e "s/^PHP_VER=\"[^\"]*\"/PHP_VER=\"$(get_current_version PHP_VER)\"/" \
                 -e "s/^PHPMYADMIN_VER=\"[^\"]*\"/PHPMYADMIN_VER=\"$(get_current_version PHPMYADMIN_VER)\"/" \
                 -e "s/^ZLIB_VER=\"[^\"]*\"/ZLIB_VER=\"$(get_current_version ZLIB_VER)\"/" \
+                -e "s/^ZLIB_NG_VER=\"[^\"]*\"/ZLIB_NG_VER=\"$(get_current_version ZLIB_NG_VER)\"/" \
+                -e "s/^ZLIB_RS_VER=\"[^\"]*\"/ZLIB_RS_VER=\"$(get_current_version ZLIB_RS_VER)\"/" \
                 -e "s/^SSE_PLUGIN_VER=\"[^\"]*\"/SSE_PLUGIN_VER=\"$(get_current_version SSE_PLUGIN_VER)\"/" \
                 -e "s/^SWPO_PLUGIN_VER=\"[^\"]*\"/SWPO_PLUGIN_VER=\"$(get_current_version SWPO_PLUGIN_VER)\"/" \
                 .github/ci-config/enginescript-variables-ci.txt
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,18 @@ All notable changes to EngineScript will be documented in this file.
 
 Changes are organized by date, with the most recent changes listed first.
 
+## 2026-02-26
+
+### ⚗️ EXPERIMENTAL ZLIB ALTERNATIVES FOR NGINX
+
+- **Added `ZLIB_IMPLEMENTATION` option** to `config/home/enginescript-install-options.txt`:
+  - `""` (empty/default) = standard zlib (no change from current behavior)
+  - `"zlib-ng"` = zlib-ng, a high-performance C drop-in replacement using `--zlib-compat` mode
+  - `"zlib-rs"` = zlib-rs, a Rust-based implementation (requires cargo/rustc on the server)
+- **Added `ZLIB_NG_VER` and `ZLIB_RS_VER`** to `enginescript-variables.txt` for centralized version management.
+- **Updated `scripts/install/zlib/zlib-install.sh`**: Now prepares the selected zlib alternative alongside the standard zlib download. Handles zlib-ng configure wrapper, stub Makefile (for nginx distclean compatibility), and zlib-rs cargo build + prefix install.
+- **Updated `scripts/install/nginx/nginx-compile.sh`**: Dynamically sets `--with-zlib` flags or include/link paths based on `ZLIB_IMPLEMENTATION`. Appends a build tag (`-zlibng` or `-zlibrs`) to the nginx `--build` string for identification.
+
 ## 2026-02-25
 
 ### �️ CLOUDFLARE ZLIB REMOVAL
diff --git a/config/home/enginescript-install-options.txt b/config/home/enginescript-install-options.txt
@@ -92,6 +92,19 @@ SHOW_ENGINESCRIPT_HEADER=0
 # Disable if you need to access these files through the web (not recommended for security)
 NGINX_BLOCK_UNSAFE_FILES=0
 
+## Experimental: zlib Alternative for Nginx (Optional) ##
+# Select an alternative zlib implementation for Nginx compilation.
+# This replaces the standard zlib with a higher-performance drop-in replacement.
+# Leave empty or set to "standard" to use official zlib (default, stable).
+#
+# Options:
+#   ""         = Standard zlib (default)
+#   "zlib-ng"  = zlib-ng (C, high-performance drop-in with --zlib-compat mode)
+#   "zlib-rs"  = zlib-rs (Rust-based, requires cargo/rustc toolchain on the server)
+#
+# WARNING: These are experimental options. If Nginx fails to compile, set back to "".
+ZLIB_IMPLEMENTATION=""
+
 ## DigitalOcean Remote Console ##
 # Install DigitalOcean's Droplet Agent for remote console access
 # This enables the Recovery Console feature in the DigitalOcean control panel
diff --git a/enginescript-variables.txt b/enginescript-variables.txt
@@ -18,6 +18,8 @@ PHP_VER="8.5"
 PHPMYADMIN_VER="5.2.3"
 PNGOUT_VER="20200115"
 ZLIB_VER="1.3.2"
+ZLIB_NG_VER="2.3.3"
+ZLIB_RS_VER="v0.6.0"
 
 # EngineScript Plugins
 SSE_PLUGIN_VER="1.9.1"
diff --git a/scripts/install/nginx/nginx-compile.sh b/scripts/install/nginx/nginx-compile.sh
@@ -103,6 +103,45 @@ fi
 
 OPENSSL_OPT_FLAGS="enable-ec_nistp_64_gcc_128 enable-ktls no-deprecated no-psk no-srp no-ssl3-method no-tls1-method no-tls1_1-method no-weak-ssl-ciphers $OPENSSL_TESTS_FLAG"
 
+# Determine zlib implementation flags for nginx configure
+ZLIB_CC_EXTRA=""
+ZLIB_LD_EXTRA=""
+ZLIB_CONFIGURE_FLAGS=()
+ZLIB_BUILD_TAG=""
+
+case "${ZLIB_IMPLEMENTATION}" in
+  zlib-ng)
+    ZLIB_CONFIGURE_FLAGS=(
+      --with-zlib="/usr/src/zlib-ng-${ZLIB_NG_VER}"
+      --with-zlib-opt=-fPIC
+    )
+    ZLIB_BUILD_TAG="-zlibng"
+    echo "Using zlib-ng ${ZLIB_NG_VER} for Nginx compilation"
+    ;;
+  zlib-rs)
+    ZLIB_RS_PREFIX="/opt/zlib-rs"
+    ZLIB_CC_EXTRA="-I${ZLIB_RS_PREFIX}/include"
+    ZLIB_LD_EXTRA="-L${ZLIB_RS_PREFIX}/lib"
+    ZLIB_BUILD_TAG="-zlibrs"
+    echo "Using zlib-rs ${ZLIB_RS_VER} for Nginx compilation"
+    ;;
+  *)
+    ZLIB_CONFIGURE_FLAGS=(
+      --with-zlib="/usr/src/zlib-${ZLIB_VER}"
+      --with-zlib-opt=-fPIC
+    )
+    echo "Using standard zlib ${ZLIB_VER} for Nginx compilation"
+    ;;
+esac
+
+# Append zlib extras to compiler/linker flags
+if [[ -n "$ZLIB_CC_EXTRA" ]]; then
+  CC_OPT_FLAGS="$CC_OPT_FLAGS $ZLIB_CC_EXTRA"
+fi
+if [[ -n "$ZLIB_LD_EXTRA" ]]; then
+  LD_OPT_FLAGS="$LD_OPT_FLAGS $ZLIB_LD_EXTRA"
+fi
+
 if [[ "${INSTALL_HTTP3}" == "1" ]];
   then
     # HTTP3
@@ -120,7 +159,7 @@ if [[ "${INSTALL_HTTP3}" == "1" ]];
       --modules-path=/etc/nginx/modules \
       --pid-path=/run/nginx.pid \
       --sbin-path=/usr/sbin/nginx \
-      --build="nginx-${NGINX_VER}-${DT}-enginescript" \
+      --build="nginx-${NGINX_VER}-${DT}-enginescript${ZLIB_BUILD_TAG}" \
       --builddir="nginx-${NGINX_VER}" \
       --with-cc-opt="$CC_OPT_FLAGS" \
       --with-ld-opt="$LD_OPT_FLAGS" \
@@ -131,8 +170,7 @@ if [[ "${INSTALL_HTTP3}" == "1" ]];
       --with-threads \
       --with-pcre="/usr/src/pcre2-${PCRE2_VER}" \
       --with-pcre-jit \
-      --with-zlib="/usr/src/zlib-${ZLIB_VER}" \
-      --with-zlib-opt=-fPIC \
+      "${ZLIB_CONFIGURE_FLAGS[@]}" \
       --with-http_ssl_module \
       --with-http_v2_module \
       --with-http_v3_module \
@@ -167,7 +205,7 @@ if [[ "${INSTALL_HTTP3}" == "1" ]];
       --modules-path=/etc/nginx/modules \
       --pid-path=/run/nginx.pid \
       --sbin-path=/usr/sbin/nginx \
-      --build="nginx-${NGINX_VER}-${DT}-enginescript" \
+      --build="nginx-${NGINX_VER}-${DT}-enginescript${ZLIB_BUILD_TAG}" \
       --builddir="nginx-${NGINX_VER}" \
       --with-cc-opt="$CC_OPT_FLAGS" \
       --with-ld-opt="$LD_OPT_FLAGS" \
@@ -178,8 +216,7 @@ if [[ "${INSTALL_HTTP3}" == "1" ]];
       --with-threads \
       --with-pcre="/usr/src/pcre2-${PCRE2_VER}" \
       --with-pcre-jit \
-      --with-zlib="/usr/src/zlib-${ZLIB_VER}" \
-      --with-zlib-opt=-fPIC \
+      "${ZLIB_CONFIGURE_FLAGS[@]}" \
       --with-http_ssl_module \
       --with-http_v2_module \
       --with-http_realip_module \
diff --git a/scripts/install/zlib/zlib-install.sh b/scripts/install/zlib/zlib-install.sh
@@ -21,14 +21,103 @@ source /usr/local/bin/enginescript/scripts/functions/shared/enginescript-common.
 # Return to /usr/src
 cd /usr/src
 
-# Official zlib Download
-# Remove existing official zlib source directory and tarball if they exist
+# Always download standard zlib (used as fallback and needed by default)
 clean_directory "/usr/src/zlib-${ZLIB_VER}"
 if [[ -f "/usr/src/zlib-${ZLIB_VER}.tar.gz" ]]; then
   rm -f "/usr/src/zlib-${ZLIB_VER}.tar.gz"
 fi
-
 download_and_extract "https://github.com/madler/zlib/archive/refs/tags/v${ZLIB_VER}.tar.gz" "/usr/src/zlib-${ZLIB_VER}.tar.gz"
 
+
+#----------------------------------------------------------------------------------
+# Experimental: zlib-ng preparation
+
+if [[ "${ZLIB_IMPLEMENTATION}" == "zlib-ng" ]]; then
+  echo "============================================================="
+  echo "  Preparing zlib-ng ${ZLIB_NG_VER} (experimental)"
+  echo "============================================================="
+
+  cd /usr/src
+
+  clean_directory "/usr/src/zlib-ng-${ZLIB_NG_VER}"
+  if [[ -f "/usr/src/zlib-ng-${ZLIB_NG_VER}.tar.gz" ]]; then
+    rm -f "/usr/src/zlib-ng-${ZLIB_NG_VER}.tar.gz"
+  fi
+
+  download_and_extract "https://github.com/zlib-ng/zlib-ng/archive/refs/tags/${ZLIB_NG_VER}.tar.gz" "/usr/src/zlib-ng-${ZLIB_NG_VER}.tar.gz"
+
+  # Create a configure wrapper
+  #
+  # Nginx's build system calls ./configure with NO arguments in the zlib
+  # source dir. zlib-ng REQUIRES --zlib-compat to produce a standard
+  # zlib-compatible API (libz.a with standard symbol names).
+  # Without it, zlib-ng produces libz-ng.a with zng_ prefixed symbols.
+  #
+  # Solution: rename the real configure and create a wrapper that always
+  # passes --zlib-compat.
+  cd "/usr/src/zlib-ng-${ZLIB_NG_VER}"
+  mv configure configure.zlib-ng
+  cat > configure << 'WRAPPER'
+#!/bin/sh
+exec "$(dirname "$0")/configure.zlib-ng" --zlib-compat "$@"
+WRAPPER
+  chmod +x configure
+
+  # Stub Makefile so nginx's "make distclean" succeeds before configure runs.
+  # Overwritten when ./configure generates the real Makefile.
+  cat > Makefile << 'STUBMAKE'
+.PHONY: distclean clean
+distclean clean:
+	@echo "stub: no-op (pre-configure)"
+STUBMAKE
+
+  echo "zlib-ng ${ZLIB_NG_VER} prepared for Nginx compilation"
+fi
+
+
+#----------------------------------------------------------------------------------
+# Experimental: zlib-rs preparation
+
+if [[ "${ZLIB_IMPLEMENTATION}" == "zlib-rs" ]]; then
+  echo "============================================================="
+  echo "  Preparing zlib-rs ${ZLIB_RS_VER} (experimental)"
+  echo "============================================================="
+
+  ZLIB_RS_PREFIX="/opt/zlib-rs"
+
+  # Install Rust toolchain if not present
+  if ! command -v cargo >/dev/null 2>&1; then
+    echo "Installing Rust toolchain (required for zlib-rs)..."
+    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+    source "$HOME/.cargo/env"
+  fi
+
+  echo "Rust version: $(rustc --version)"
+  echo "Cargo version: $(cargo --version)"
+
+  cd /usr/src
+
+  clean_directory "/usr/src/zlib-rs"
+  git clone --branch "${ZLIB_RS_VER}" --depth 1 https://github.com/trifectatechfoundation/zlib-rs.git /usr/src/zlib-rs
+
+  cd /usr/src/zlib-rs/libz-rs-sys-cdylib
+
+  # Build with native CPU optimizations for best performance
+  RUSTFLAGS="-Ctarget-cpu=native -Cllvm-args=-enable-dfa-jump-thread" \
+    cargo build --release --features c-allocator
+
+  echo "zlib-rs library built successfully"
+
+  # Install to a local prefix mimicking a standard zlib install
+  rm -rf "${ZLIB_RS_PREFIX}"
+  mkdir -p "${ZLIB_RS_PREFIX}/lib" "${ZLIB_RS_PREFIX}/include"
+
+  cp /usr/src/zlib-rs/target/release/libz_rs.a "${ZLIB_RS_PREFIX}/lib/libz.a"
+  cp /usr/src/zlib-rs/libz-rs-sys-cdylib/include/zlib.h "${ZLIB_RS_PREFIX}/include/"
+  cp /usr/src/zlib-rs/libz-rs-sys-cdylib/include/zconf.h "${ZLIB_RS_PREFIX}/include/"
+
+  echo "zlib-rs ${ZLIB_RS_VER} installed to ${ZLIB_RS_PREFIX}"
+fi
+
 # Return to /usr/src
 cd /usr/src
