fix older oses precompiled support (#649)

* fix older oses precompiled support

* remarks

Author: mensfeld

.github/workflows/ci_linux_x86_64_gnu.yml

@@ -1,3 +1,37 @@
+# CI Strategy: Comprehensive Testing of Build and Precompiled Flows
+#
+# This workflow tests both compilation-from-source and precompiled binary distribution
+# strategies across multiple Ubuntu and Ruby versions to ensure broad compatibility and
+# reliability.
+#
+# WHY WE TEST BOTH UBUNTU 22.04 AND 24.04:
+# - Different system library versions (OpenSSL, zlib, libsasl2, libzstd, etc.)
+# - Different GCC compiler versions that affect native extension compilation
+# - Different glibc versions that can impact binary compatibility
+# - Real-world deployment scenarios where users run on various Ubuntu LTS versions
+# - Different Ruby versions
+#
+# COMPILATION FLOW (build_install + specs_install):
+# - Tests that librdkafka compiles correctly from source on each Ubuntu version
+# - Validates that mini_portile2 can successfully build native dependencies
+# - Ensures Ruby native extensions link properly with system libraries
+# - Verifies that the same codebase works across different toolchain versions
+#
+# PRECOMPILED FLOW (build_precompiled + specs_precompiled):
+# - Tests our precompiled static libraries work on different Ubuntu versions
+# - Validates that statically-linked binaries are truly portable across environments
+# - Ensures precompiled libraries don't have unexpected system dependencies
+# - Verifies that removing build tools doesn't break precompiled binary usage
+#
+# ARTIFACT ISOLATION:
+# - Each Ubuntu version gets separate artifacts (rdkafka-built-gem-22.04, etc.)
+# - Prevents cross-contamination of OS-specific compiled extensions
+# - Ensures test accuracy by matching build and test environments
+#
+# This comprehensive approach catches issues that single-platform testing would miss,
+# such as system library incompatibilities, compiler-specific bugs, or static linking
+# problems that only manifest on specific Ubuntu versions.
+
 name: CI Linux x86_64 GNU
 
 concurrency:
@@ -20,41 +54,8 @@ env:
   BUNDLE_JOBS: 4
 
 jobs:
-  build_install:
-    timeout-minutes: 30
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          fetch-depth: 0
-      - name: Install package dependencies
-        run: "[ -e $APT_DEPS ] || sudo apt-get install -y --no-install-recommends $APT_DEPS"
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@a4effe49ee8ee5b8b5091268c473a4628afb5651 # v1.245.0
-        with:
-          ruby-version: '3.4'  # Use one Ruby version for building
-          bundler-cache: false
-      - name: Build gem with mini_portile
-        run: |
-          set -e
-          bundle install
-          cd ext && bundle exec rake
-          cd ..
-      - name: Upload built gem and bundle
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
-        with:
-          name: rdkafka-built-gem
-          path: |
-            vendor/bundle/
-            .bundle/
-            ext/
-            lib/
-          retention-days: 1
-
   specs_install:
     timeout-minutes: 30
-    runs-on: ubuntu-latest
-    needs: build_install
     strategy:
       fail-fast: false
       matrix:
@@ -65,20 +66,17 @@ jobs:
           - '3.2'
           - '3.1'
           - 'jruby-10.0'
+        ubuntu-version: ['22.04', '24.04']
         include:
           - ruby: '3.4'
             coverage: 'true'
           - ruby: 'jruby-10.0'
             continue-on-error: true
+    runs-on: ubuntu-${{ matrix.ubuntu-version }}
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
           fetch-depth: 0
-      - name: Download built gem
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
-        with:
-          name: rdkafka-built-gem
-          path: ./
       - name: Set up Ruby
         uses: ruby/setup-ruby@a4effe49ee8ee5b8b5091268c473a4628afb5651 # v1.245.0
         with:
@@ -108,12 +106,17 @@ jobs:
             echo "Sleeping 2 seconds..."
             sleep 2
           done
-      - name: Install remaining dependencies
+      - name: Install dependencies
         env:
           RDKAFKA_EXT_PATH: ${{ github.workspace }}/ext
         run: |
           # Only install gems that aren't Ruby-version specific
           bundle install
+      - name: Build gem with mini_portile
+        run: |
+          set -e
+          cd ext && bundle exec rake
+          cd ..
       - name: Run all specs
         env:
           GITHUB_COVERAGE: ${{matrix.coverage}}
@@ -124,7 +127,10 @@ jobs:
 
   build_precompiled:
     timeout-minutes: 30
-    runs-on: ubuntu-latest
+    # We precompile on older Ubuntu and check compatibility by running specs since we aim to
+    # release only one precompiled version for all supported Ubuntu versions
+    # This is why we do not want Renovate to update it automatically
+    runs-on: ubuntu-22.04 # renovate: ignore
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
@@ -135,15 +141,29 @@ jobs:
           sudo apt-get install -y --no-install-recommends \
             build-essential \
             gcc \
+            g++ \
             make \
-            patch \
             tar \
+            gzip \
             wget \
+            curl \
+            file \
+            pkg-config \
+            autoconf \
+            automake \
+            libtool \
+            python3 \
+            git \
             ca-certificates \
+            patch \
             libsasl2-dev \
             libssl-dev \
             zlib1g-dev \
-            libzstd-dev
+            libzstd-dev \
+            bison \
+            flex \
+            perl \
+            binutils-dev
       - name: Cache build-tmp directory
         uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
         with:
@@ -162,7 +182,6 @@ jobs:
 
   specs_precompiled:
     timeout-minutes: 30
-    runs-on: ubuntu-latest
     needs: build_precompiled
     strategy:
       fail-fast: false
@@ -173,9 +192,13 @@ jobs:
           - '3.3'
           - '3.2'
           - '3.1'
+        ubuntu-version: ['22.04', '24.04']
         include:
           - ruby: '3.4'
+            ubuntu-version: '24.04'
             coverage: 'true'
+
+    runs-on: ubuntu-${{ matrix.ubuntu-version }}
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
@@ -199,7 +222,6 @@ jobs:
 
           echo "=== Container status ==="
           docker compose ps kafka
-
           for i in {1..30}; do
             echo "=== Attempt $i/30 ==="
 

.github/workflows/ci_linux_x86_64_musl.yml

@@ -1,3 +1,26 @@
+# Why We Build and Run Without Caching Native Extensions
+#
+# We intentionally compile the native librdkafka library fresh in each test job
+# rather than caching or pre-building it for several reasons:
+#
+# 1. Architecture Compatibility
+#    - Pre-built native libraries (.so files) are architecture-specific
+#    - Can cause "Exec format error" when build/runtime environments differ
+#    - Building in the same container guarantees compatibility
+#
+# 2. Container Image Variations
+#    - Different Ruby Alpine images may have subtle differences in:
+#      * Base system libraries, compiler toolchains, musl libc versions
+#    - These differences can cause pre-built libraries to fail at runtime
+#
+# 3. Simplicity and Reliability
+#    - Single source of truth: everything builds and runs in same environment
+#    - No artifact management complexity or potential upload/download failures
+#    - Easier debugging when issues are contained in one job
+#
+# Trade-offs: Slightly longer CI times (~2-3 min per job) but much more reliable
+# than dealing with architecture mismatches and artifact corruption issues.
+
 name: CI Linux x86_64 musl
 
 concurrency:
@@ -20,110 +43,76 @@ env:
   BUNDLE_JOBS: 4
 
 jobs:
-  build_install:
-    timeout-minutes: 30
-    runs-on: ubuntu-latest
-    container:
-      image: alpine:3.22@sha256:4bcff63911fcb4448bd4fdacec207030997caf25e9bea4045fa6c8c44de311d1
-    steps:
-      - name: Install dependencies
-        run: |
-          apk add --no-cache git curl ca-certificates build-base linux-headers \
-            pkgconf perl autoconf automake libtool bison flex file \
-            ruby ruby-dev ruby-bundler bash zstd-dev zlib zlib-dev openssl-dev cyrus-sasl-dev
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          fetch-depth: 0
-      - name: Configure git safe directory
-        run: git config --global --add safe.directory /__w/karafka-rdkafka/karafka-rdkafka
-      - name: Build gem with mini_portile
-        run: |
-          set -e
-          bundle config set --local path 'vendor/bundle'
-          bundle install
-          cd ext && bundle exec rake
-          cd ..
-      - name: Upload built gem and bundle
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
-        with:
-          name: rdkafka-built-gem-musl
-          path: |
-            vendor/bundle/
-            .bundle/
-            ext/
-            lib/
-          retention-days: 1
-
   specs_install:
     timeout-minutes: 30
     runs-on: ubuntu-latest
-    needs: build_install
     strategy:
       fail-fast: false
       matrix:
-        ruby:
-          - '3.4'
-          - '3.3'
-          - '3.2'
-          - '3.1'
         include:
+          - ruby: '3.1'
+            alpine_version: '3.21'
+          - ruby: '3.2'
+            alpine_version: '3.21'
+          - ruby: '3.2'
+            alpine_version: '3.22'
+          - ruby: '3.3'
+            alpine_version: '3.21'
+          - ruby: '3.3'
+            alpine_version: '3.22'
+          - ruby: '3.4'
+            alpine_version: '3.21'
+            coverage: 'true'
           - ruby: '3.4'
+            alpine_version: '3.22'
             coverage: 'true'
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
           fetch-depth: 0
-      - name: Download built gem
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
-        with:
-          name: rdkafka-built-gem-musl
-          path: ./
+
       - name: Start Kafka with Docker Compose
         run: |
           docker compose up -d
           echo "Waiting for Kafka to be ready..."
           sleep 10
-
           for i in {1..30}; do
             if docker compose exec -T kafka kafka-topics --bootstrap-server localhost:9092 --list >/dev/null 2>&1; then
               echo "Kafka topics command succeeded!"
               break
             fi
             sleep 2
           done
+
       - name: Run all specs
         env:
           GITHUB_COVERAGE: ${{ matrix.coverage }}
-          RDKAFKA_EXT_PATH: ${{ github.workspace }}/ext
         run: |
           docker run --rm \
             --network host \
             -v "${{ github.workspace }}:/workspace" \
             -w /workspace \
             -e "GITHUB_COVERAGE=${{ matrix.coverage }}" \
-            -e "RDKAFKA_EXT_PATH=/workspace/ext" \
-            ruby:${{ matrix.ruby }}-alpine \
-            sh -c 'apk add --no-cache git build-base linux-headers bash \
-              cyrus-sasl \
-              cyrus-sasl-login \
-              cyrus-sasl-crammd5 \
-              cyrus-sasl-digestmd5 \
-              cyrus-sasl-gssapiv2 \
-              cyrus-sasl-scram \
-              krb5-libs \
-              openssl \
-              zlib \
-              zlib-dev \
-              zstd-libs && \
+            ruby:${{ matrix.ruby }}-alpine${{ matrix.alpine_version }} \
+            sh -c 'apk add --no-cache git curl ca-certificates build-base linux-headers \
+              pkgconf perl autoconf automake libtool bison flex file \
+              ruby-dev ruby-bundler bash zstd-dev zlib zlib-dev openssl-dev \
+              cyrus-sasl-dev cyrus-sasl cyrus-sasl-login \
+              cyrus-sasl-crammd5 cyrus-sasl-digestmd5 cyrus-sasl-gssapiv2 cyrus-sasl-scram \
+              krb5-libs openssl zlib zstd-libs && \
               git config --global --add safe.directory /workspace && \
               bundle config set --local path vendor/bundle && \
               bundle install && \
+              cd ext && bundle exec rake && \
+              cd .. && \
               bundle exec ruby -S rspec'
+
   build_precompiled:
     timeout-minutes: 45
     runs-on: ubuntu-latest
     container:
-      image: alpine:3.22@sha256:4bcff63911fcb4448bd4fdacec207030997caf25e9bea4045fa6c8c44de311d1
+      # Similar to GNU, we build on the oldest for ABI compatibility
+      image: alpine:3.18@sha256:de0eb0b3f2a47ba1eb89389859a9bd88b28e82f5826b6969ad604979713c2d4f # renovate: ignore
     steps:
       - name: Install dependencies
         run: |