build.yml

name: Build

# Every build output here is a pure function of its inputs. Naming those inputs
# is what decides how many times the pipeline has to compute it:
#
#   rust output = f(source, crate set, cargo profile, target triple)
#   apk         = g(source, variant, CI_BUILD_TYPE) + the .so files
#
# There are exactly three Rust identities in this repository:
#
#   host-dev        dev      x86_64-unknown-linux-gnu   fmt/clippy/test, bindgen
#   host-release    release  x86_64-unknown-linux-gnu   Gradle unit tests (JNA)
#   android-release release  3x *-linux-android         the .so files in the APKs
#
# Each is built by exactly one job below and named as its own cache key, so a
# job that needs an identity another job already produced restores it instead
# of recompiling it. The keys are the identities; they are not job names, and
# they are not per-crate. Two jobs wanting the same identity must spell it the
# same way or the memoisation silently misses — which is what used to happen
# between the test job and the MASQUE smoke test.
#
# Note what is *not* an argument to `f`: `CI_BUILD_TYPE`. The native libraries
# for a release tag are byte-identical to those for the commit it points at.
# Only the APK differs, because versionName and versionCode are derived from
# the build type. So `release.yml` calls this workflow to reassemble the APK
# with `release` stamping, and the cross-compile behind it is a cache hit.
#
# The Android cross-compile and the Gradle assembly are separate jobs joined by
# the `letterbox-jnilibs` artifact. That split is what lets `apks` run with no
# Rust toolchain, no NDK and no cargo-ndk at all, and lets the UI-test workflow
# consume the same libraries without rebuilding them.

on:
  push:
    # Tags deliberately absent. A tag push used to run this *and* then
    # `release.yml` rebuilt the identical release APK from scratch. The release
    # is now the single occasion on which a release-stamped APK is assembled.
    branches: ["main", "copilot/**"]
  pull_request:
    branches: ["main"]
  workflow_call:
    inputs:
      build_type:
        description: >-
          Overrides the build type derived from the trigger. The APK's
          versionName and versionCode are a function of it, so a caller that
          needs release stamping must say so.
        required: false
        type: string
        default: ""
    outputs:
      staging-debug-artifact:
        description: Unsigned staging debug APK.
        value: ${{ jobs.apks.outputs.staging-debug }}
      prod-release-artifact:
        description: Unsigned prod release APK.
        value: ${{ jobs.apks.outputs.prod-release }}
      jnilibs-artifact:
        description: Android native libraries shared by every downstream job.
        value: ${{ jobs.apks.outputs.jnilibs }}

# Supersede a pull request's earlier runs; never cancel a run on a trusted ref,
# because `pre-release.yml` and `release.yml` consume its artifacts.
concurrency:
  group: build-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

# Default deny at the workflow level; each job grants itself the minimum it
# needs. A job added later then starts with no token scopes rather than
# silently inheriting whatever the workflow happened to declare.
permissions: {}

env:
  # Who may *write* to a shared cache. Restoring is unrestricted — GitHub
  # already scopes reads to the current branch and the default branch — but a
  # pull request runs untrusted code, so it must not be able to place an object
  # that a later release build would link against.
  #
  # Derived from the ref rather than the event: pushing a tag or to `main`
  # requires write access and is therefore already trusted, while a pull
  # request's ref is `refs/pull/N/merge` and a feature branch is neither.
  CACHE_WRITE: ${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v') }}

  # Pinned, and pinned to the version the ubuntu-24.04 image already carries so
  # nothing is downloaded. Still an explicit version rather than "whatever the
  # image has": if the image moves, this fetches r27.3 and the build stays
  # reproducible, only slower for that one run.
  NDK_VERSION: "27.3.13750724"
  ANDROID_BUILD_TOOLS: "37.0.0"
  # API 37 ships only as minor releases: Google's index has no plain
  # `platforms;android-37`, only `37.0` and `37.1`, which is why AGP's own
  # error text suggests "37.1". `37.0` is the base release for API 37 — the
  # role `android-36` played for API 36 — so it is what `compileSdk = 37`
  # resolves to, and it is the only one installed.
  #
  # Installing several would be the same mistake as leaving ANDROID_NDK_HOME
  # and ANDROID_NDK_ROOT disagreeing: what the app compiles against would
  # depend on which minor happened to be present rather than on what the build
  # file says, and adding a `37.2` to the image later could move it silently.
  # If AGP wants something else it names the platform it cannot find, at
  # configuration time, in one line.
  ANDROID_PLATFORMS: "platforms;android-37.0"

  JNILIBS_ARTIFACT: letterbox-jnilibs
  STAGING_DEBUG_ARTIFACT: letterbox-staging-apk
  PROD_RELEASE_ARTIFACT: letterbox-prod-release-unsigned-apk

jobs:
  # ---------------------------------------------------------------- host-dev
  rust:
    name: Rust checks
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@v7
        with:
          # No Gradle here, so no version resolution from git history, so no
          # reason to pay for the full history.
          # This job runs project build code (build.rs, proc macros). The token
          # is not left in `.git/config` for that code to find.
          persist-credentials: false

      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@stable
        with:
          components: clippy, rustfmt

      - name: Cache Rust (host-dev)
        uses: Swatinem/rust-cache@v2
        with:
          shared-key: host-dev
          save-if: ${{ env.CACHE_WRITE == 'true' }}

      # One workspace invocation each. The three crates are members of the root
      # workspace and share one `target/`, so per-crate invocations were three
      # resolutions and three link passes over one dependency graph.
      - name: Format
        run: cargo fmt --all -- --check

      # Absent from CI until now, though it gates the code under review.
      # `--all-targets` covers tests and benches, not just the libraries.
      # Features are left at their defaults on purpose: `--all-features` would
      # enable letterbox-proxy's `mock`, which is a different program.
      - name: Clippy
        run: cargo clippy --workspace --all-targets -- -D warnings

      - name: Test
        run: cargo test --workspace

  # --------------------------------------------------------- android-release
  native-libs:
    name: Native libraries
    runs-on: ubuntu-24.04
    timeout-minutes: 60
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@v7
        with:
          persist-credentials: false

      # The Android NDK ships only a linux-x86_64 host toolchain, so this
      # cross-compile must run on an amd64 runner; an arm64 runner cannot
      # execute the NDK clang.
      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: aarch64-linux-android,armv7-linux-androideabi,x86_64-linux-android

      - name: Cache Rust (android-release)
        uses: Swatinem/rust-cache@v2
        with:
          shared-key: android-release
          save-if: ${{ env.CACHE_WRITE == 'true' }}

      # No JDK step: `sdkmanager` runs on the runner image's preinstalled Java.
      - name: Set up Android SDK
        uses: android-actions/setup-android@v4

      - name: Install NDK
        run: |
          set -euo pipefail
          # Bounded input rather than `yes |`. sdkmanager stops reading once
          # every licence is accepted, and the SIGPIPE that then kills `yes`
          # is a pipeline failure under `pipefail`. 200 bytes fits the pipe
          # buffer, so nothing is ever left writing to a closed pipe.
          printf 'y\n%.0s' {1..100} | sdkmanager --licenses > /dev/null
          sdkmanager --install "ndk;${NDK_VERSION}"
          # Both variables, deliberately. cargo-ndk reads ANDROID_NDK_HOME and
          # cmake's Android toolchain file reads ANDROID_NDK_ROOT, so setting
          # only one leaves the two halves of this build free to resolve
          # different NDKs — and the half that reads ANDROID_NDK_ROOT is the one
          # that compiles quiche's vendored BoringSSL.
          {
            echo "ANDROID_NDK_HOME=$ANDROID_SDK_ROOT/ndk/${NDK_VERSION}"
            echo "ANDROID_NDK_ROOT=$ANDROID_SDK_ROOT/ndk/${NDK_VERSION}"
          } >> "$GITHUB_ENV"

      - name: Install cargo-ndk
        run: |
          set -euo pipefail
          # rust-cache restores ~/.cargo/bin, so this is usually a no-op. The
          # previous form ended in `|| true`, which turned a failed install
          # into a confusing failure two steps later.
          if ! command -v cargo-ndk > /dev/null 2>&1; then
            cargo install cargo-ndk --locked
          fi

      # One workspace invocation builds letterbox-core, letterbox-proxy and
      # usque-core for all three ABIs, reusing one compile of the shared
      # dependency graph.
      #
      # `--lib` is load-bearing: without it this also cross-compiled the two
      # `uniffi-bindgen` *binaries* for every ABI — six links of a host-only
      # developer tool that never enters an APK.
      #
      # usque-core pulls in quiche with vendored BoringSSL, so this also
      # cross-compiles C via cmake. A failure for one ABI only points at
      # BoringSSL's toolchain detection rather than at the Rust.
      - name: Cross-compile for Android
        run: |
          cargo ndk -t arm64-v8a -t armeabi-v7a -t x86_64 \
            -o "${{ github.workspace }}/app/src/main/jniLibs" \
            build --release --workspace --lib

      # Exhaustive, unlike the `find ... | head -1 || (echo ERROR; exit 1)`
      # this replaces: `find` exits 0 when it matches nothing, so that `||`
      # never fired and a missing library passed the check.
      - name: Verify every ABI carries every library
        run: |
          set -euo pipefail
          missing=0
          for abi in arm64-v8a armeabi-v7a x86_64; do
            for lib in letterbox_core letterbox_proxy; do
              path="app/src/main/jniLibs/$abi/lib$lib.so"
              if [[ -f "$path" ]]; then
                printf '  ok  %s (%s bytes)\n' "$path" "$(stat -c%s "$path")"
              else
                echo "::error::missing $path"
                missing=1
              fi
            done
          done
          exit "$missing"

      - name: Upload native libraries
        uses: actions/upload-artifact@v7
        with:
          name: ${{ env.JNILIBS_ARTIFACT }}
          path: app/src/main/jniLibs
          retention-days: 7
          if-no-files-found: error

  # ------------------------------------------------------------ host-release
  android-checks:
    name: Android lint and unit tests
    runs-on: ubuntu-24.04
    timeout-minutes: 45
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@v7
        with:
          # Gradle resolves the version from git during configuration.
          fetch-depth: 0
          fetch-tags: true
          persist-credentials: false

      - name: Set up JDK
        uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: "21"

      - name: Set up Android SDK
        uses: android-actions/setup-android@v4

      - name: Install Android components
        run: |
          set -euo pipefail
          # Unquoted on purpose: ANDROID_PLATFORMS is a list of packages.
          # shellcheck disable=SC2086
          sdkmanager "platform-tools" $ANDROID_PLATFORMS "build-tools;${ANDROID_BUILD_TOOLS}"
          # Bounded input rather than `yes |`. sdkmanager stops reading once
          # every licence is accepted, and the SIGPIPE that then kills `yes`
          # is a pipeline failure under `pipefail`. 200 bytes fits the pipe
          # buffer, so nothing is ever left writing to a closed pipe.
          printf 'y\n%.0s' {1..100} | sdkmanager --licenses > /dev/null

      # Host toolchain only. Gradle's `cargoHostBuild` builds the libraries the
      # JVM tests load through JNA; it needs no NDK and no Android targets.
      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@stable

      # A distinct identity from host-dev — `cargoHostBuild` runs
      # `cargo build --release`, which populates `target/release` rather than
      # `target/debug`. Sharing one key between the two would make each job
      # cache the other's outputs on every run.
      - name: Cache Rust (host-release)
        uses: Swatinem/rust-cache@v2
        with:
          shared-key: host-release
          save-if: ${{ env.CACHE_WRITE == 'true' }}

      - name: Set up Gradle
        uses: gradle/actions/setup-gradle@v6
        with:
          cache-read-only: ${{ env.CACHE_WRITE != 'true' }}

      # `test` runs the suite once per variant: prodDebug, prodRelease,
      # stagingDebug, stagingRelease — four Kotlin compiles and four JVM runs of
      # assertions that are identical, because nothing under `app/src/test`
      # references BuildConfig, applicationId, a flavour resource or FLAVOR.
      # One variant is the whole suite.
      #
      # `--continue` so a lint failure still reports the test results, instead
      # of hiding them behind the first failure.
      - name: Lint and unit tests
        run: ./gradlew lint testProdDebugUnitTest --continue --no-daemon

      - name: Upload reports
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: android-check-reports
          path: app/build/reports
          retention-days: 7
          if-no-files-found: ignore

  # -------------------------------------------------------------------- APKs
  apks:
    name: Assemble APKs
    runs-on: ubuntu-24.04
    timeout-minutes: 45
    # Only the native libraries. Assembly does not depend on lint or on the
    # test suites, and gating it behind them would put their runtime on the
    # critical path of every build for no added signal — each job already
    # reports its own failure, and downstream signing keys off the whole
    # workflow's conclusion.
    needs: native-libs
    permissions:
      contents: read
    outputs:
      staging-debug: ${{ steps.names.outputs.staging-debug }}
      prod-release: ${{ steps.names.outputs.prod-release }}
      jnilibs: ${{ steps.names.outputs.jnilibs }}
    env:
      # The one parameter that distinguishes otherwise identical APKs, and the
      # only job that consumes it. It was previously recomputed by a nine-line
      # shell conditional in two jobs, neither of which used the result; that
      # shell also wrote to $GITHUB_ENV and then echoed the variable, which is
      # empty in the step that set it.
      CI_BUILD_TYPE: >-
        ${{ inputs.build_type != '' && inputs.build_type
         || startsWith(github.ref, 'refs/tags/v') && 'release'
         || github.event_name == 'pull_request' && 'test'
         || github.ref == 'refs/heads/main' && 'prerelease'
         || 'local' }}
    steps:
      - name: Checkout
        uses: actions/checkout@v7
        with:
          fetch-depth: 0
          fetch-tags: true
          persist-credentials: false

      - name: Set up JDK
        uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: "21"

      - name: Set up Android SDK
        uses: android-actions/setup-android@v4

      - name: Install Android components
        run: |
          set -euo pipefail
          # Unquoted on purpose: ANDROID_PLATFORMS is a list of packages.
          # shellcheck disable=SC2086
          sdkmanager "platform-tools" $ANDROID_PLATFORMS "build-tools;${ANDROID_BUILD_TOOLS}"
          # Bounded input rather than `yes |`. sdkmanager stops reading once
          # every licence is accepted, and the SIGPIPE that then kills `yes`
          # is a pipeline failure under `pipefail`. 200 bytes fits the pipe
          # buffer, so nothing is ever left writing to a closed pipe.
          printf 'y\n%.0s' {1..100} | sdkmanager --licenses > /dev/null

      # No Rust toolchain, no NDK, no cargo-ndk: `cargoNdkBuild` is gated on
      # `-PrustBuild=true` and stays skipped, and `assemble` pulls in no task
      # that shells out to cargo. The libraries arrive as an artifact instead.
      - name: Download native libraries
        uses: actions/download-artifact@v8
        with:
          name: ${{ env.JNILIBS_ARTIFACT }}
          path: app/src/main/jniLibs

      - name: Set up Gradle
        uses: gradle/actions/setup-gradle@v6
        with:
          cache-read-only: ${{ env.CACHE_WRITE != 'true' }}

      # Both variants in one invocation. They share configuration, the
      # dependency graph and every task whose inputs do not differ by variant.
      #
      # `assembleStagingDebugAndroidTest` is here to compile the instrumented
      # sources, not to run them. Nothing in this workflow compiled
      # `app/src/androidTest` before, so a change to an FFI record could delete a
      # field an instrumented test still read and every job here would stay
      # green: the break surfaced only in Android UI Tests, which runs on a
      # separate trigger, minutes later — and never at all for a pull request,
      # since that workflow filters to `main` and `copilot/**`. Compiling here
      # costs one dex-less variant compile and moves the failure to the job that
      # caused it. (This is what the old androidTest artifact upload appeared to
      # cover; it had `if-no-files-found: ignore` and uploaded nothing, because
      # `assembleStagingDebug` does not build androidTest.)
      - name: Assemble
        run: |
          ./gradlew assembleStagingDebug assembleProdRelease \
            assembleStagingDebugAndroidTest --no-daemon

      - name: Verify the APKs carry every ABI
        run: |
          set -euo pipefail
          missing=0
          for apk in \
            app/build/outputs/apk/staging/debug/*.apk \
            app/build/outputs/apk/prod/release/*.apk
          do
            for abi in arm64-v8a armeabi-v7a x86_64; do
              for lib in letterbox_core letterbox_proxy; do
                if unzip -l "$apk" "lib/$abi/lib$lib.so" > /dev/null 2>&1; then
                  printf '  ok  %s :: lib/%s/lib%s.so\n' "$(basename "$apk")" "$abi" "$lib"
                else
                  echo "::error::$apk is missing lib/$abi/lib$lib.so"
                  missing=1
                fi
              done
            done
          done
          exit "$missing"

      - name: Publish artifact names
        id: names
        run: |
          set -euo pipefail
          {
            echo "staging-debug=$STAGING_DEBUG_ARTIFACT"
            echo "prod-release=$PROD_RELEASE_ARTIFACT"
            echo "jnilibs=$JNILIBS_ARTIFACT"
          } >> "$GITHUB_OUTPUT"

      - name: Upload staging debug APK
        uses: actions/upload-artifact@v7
        with:
          name: ${{ env.STAGING_DEBUG_ARTIFACT }}
          path: app/build/outputs/apk/staging/debug/*.apk
          retention-days: 30
          if-no-files-found: error

      - name: Upload prod release APK
        uses: actions/upload-artifact@v7
        with:
          name: ${{ env.PROD_RELEASE_ARTIFACT }}
          path: app/build/outputs/apk/prod/release/*.apk
          retention-days: 30
          if-no-files-found: error

  # --------------------------------------------------- host-dev, network-gated
  warp-smoke-test:
    name: Real MASQUE smoke test
    runs-on: ubuntu-24.04
    timeout-minutes: 15
    permissions:
      contents: read
    # The full privacy path (provision a real WARP device -> MASQUE CONNECT-IP
    # -> DoH -> TLS -> HTTP image fetch -> delete device) is exercised against
    # live Cloudflare. It is inherently flaky (network, rate limits, anycast
    # routing), so a failure is surfaced as a warning and never gates the build.
    steps:
      - name: Checkout
        uses: actions/checkout@v7
        with:
          persist-credentials: false

      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@stable

      # Same identity as the `rust` job: the same crates, the same dev profile,
      # the same host triple. It used `shared-key: warp`, so it never saw what
      # that job had already built — and it passed `workspaces:
      # rust/letterbox-proxy`, which is a *member* of the root workspace, so
      # cargo writes to `<repo>/target` and that path does not exist. The cache
      # was empty on both ends, and every run recompiled quiche with vendored
      # BoringSSL from scratch.
      - name: Cache Rust (host-dev)
        uses: Swatinem/rust-cache@v2
        with:
          shared-key: host-dev
          save-if: ${{ env.CACHE_WRITE == 'true' }}

      # Non-blocking: the step may fail without failing the job.
      #
      # The MASQUE path has one dependency nothing local can check: that
      # Cloudflare keeps accepting `api.cloudflare.com` as the tunnel SNI. That
      # is a server-side policy we do not control and could lose without
      # notice, so it is worth a standing check rather than a user-reported
      # outage.
      - name: Run real Cloudflare MASQUE end-to-end test
        id: masque
        continue-on-error: true
        working-directory: rust/letterbox-proxy
        run: cargo test --test masque_real -- --ignored --nocapture --test-threads=1

      - name: Report MASQUE test outcome
        if: always()
        env:
          OUTCOME: ${{ steps.masque.outcome }}
        run: |
          if [[ "$OUTCOME" == "success" ]]; then
            echo "Real Cloudflare MASQUE end-to-end test passed (SNI api.cloudflare.com accepted)."
          else
            echo "::warning title=Real MASQUE test failed::The live Cloudflare MASQUE end-to-end test did not pass (outcome: ${OUTCOME}). Non-blocking. If it fails repeatedly, check whether the substituted SNI (tunnel::masque::MASQUE_SNI) is still accepted before suspecting the tunnel; masque_real has a separate case that isolates exactly that."
          fi