contract.yml

name: Disposable API contract

on:
  workflow_call:
  workflow_dispatch:
  pull_request:
    branches:
      - main
  schedule:
    - cron: "41 3 * * 0"

permissions:
  contents: read

concurrency:
  group: contract-${{ github.ref }}
  cancel-in-progress: false

jobs:
  gate:
    name: Check Postman secret
    runs-on: ubuntu-latest
    outputs:
      enabled: ${{ steps.check.outputs.enabled }}
      postman_ref: ${{ steps.locked.outputs.postman_ref }}
      stack_ref: ${{ steps.locked.outputs.stack_ref }}
      core_api_ref: ${{ steps.locked.outputs.core_api_ref }}
      fleetops_ref: ${{ steps.locked.outputs.fleetops_ref }}
      fleetops_source_ref: ${{ steps.locked.outputs.fleetops_source_ref }}
    steps:
      - id: check
        env:
          POSTMAN_API_KEY: ${{ secrets.POSTMAN_API_KEY }}
        run: |
          if [ -n "$POSTMAN_API_KEY" ]; then
            echo "enabled=true" >> "$GITHUB_OUTPUT"
          else
            echo "enabled=false" >> "$GITHUB_OUTPUT"
            echo "::warning::POSTMAN_API_KEY is not set; skipping the API contract run."
          fi
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      # These refs used to be copied into this file by hand, which meant a
      # contract sync could update contracts/contract-lock.json and leave CI
      # booting the previous collection against the previous stack. Read them
      # from the lock instead, so there is one place to change.
      - id: locked
        run: |
          set -euo pipefail
          read_lock() {
            jq -er "$1" contracts/contract-lock.json \
              || { echo "::error::contract-lock.json is missing $1"; exit 1; }
          }
          {
            echo "postman_ref=$(read_lock '.sources.postman.commit')"
            echo "stack_ref=$(read_lock '.sources.fleetbase_stack.commit')"
            echo "core_api_ref=$(read_lock '.sources.fleetbase_stack.core_api_submodule')"
            echo "fleetops_ref=$(read_lock '.sources.fleetbase_stack.fleetops_submodule')"
            echo "fleetops_source_ref=$(read_lock '.sources.fleetops.commit')"
          } >> "$GITHUB_OUTPUT"

  contract:
    name: Official Postman and SDK contract
    needs: gate
    if: >-
      needs.gate.outputs.enabled == 'true' &&
      (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)
    runs-on: ubuntu-latest
    timeout-minutes: 55
    env:
      FLEETBASE_STACK_REF: ${{ needs.gate.outputs.stack_ref }}
      FLEETBASE_API_IMAGE: fleetbase/fleetbase-api:latest
      POSTMAN_REF: ${{ needs.gate.outputs.postman_ref }}
      CORE_API_REF: ${{ needs.gate.outputs.core_api_ref }}
      FLEETOPS_REF: ${{ needs.gate.outputs.fleetops_ref }}
      FLEETOPS_SOURCE_REF: ${{ needs.gate.outputs.fleetops_source_ref }}
      SOURCE_TOKEN: ${{ secrets._GITHUB_AUTH_TOKEN || github.token }}
      POSTMAN_API_KEY: ${{ secrets.POSTMAN_API_KEY }}
    steps:
      # This is the same boot path used by fleetbase/fleetbase's reusable
      # api-contract workflow. The remaining SDK-specific steps must share this
      # runner so the Postman base URL can point through the PHP SDK bridge.
      - name: Checkout fleetbase/fleetbase
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          repository: fleetbase/fleetbase
          ref: ${{ env.FLEETBASE_STACK_REF }}
          submodules: recursive
          token: ${{ env.SOURCE_TOKEN }}
      - name: Prove locked package refs
        run: |
          test "$(git -C packages/core-api rev-parse HEAD)" = "$CORE_API_REF"
          test "$(git -C packages/fleetops rev-parse HEAD)" = "$FLEETOPS_REF"
      - name: Pin transitive actions in the locked Fleetbase composite
        run: |
          sed -i 's#actions/checkout@v4#actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1#g' .github/actions/postman-contract/action.yml
          sed -i 's#actions/upload-artifact@v4#actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a#g' .github/actions/postman-contract/action.yml
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
      - name: Pull published API image
        run: |
          docker pull "$FLEETBASE_API_IMAGE"
          {
            echo "### API image under test"
            echo '```'
            docker image inspect "$FLEETBASE_API_IMAGE" --format 'requested: fleetbase/fleetbase-api:latest{{"\n"}}tags:      {{join .RepoTags ", "}}{{"\n"}}digest:    {{join .RepoDigests ", "}}{{"\n"}}created:   {{.Created}}'
            echo '```'
          } | tee -a "$GITHUB_STEP_SUMMARY"
      - name: Ensure clean database volume
        run: |
          sudo rm -rf docker/database/mysql
          mkdir -p docker/database/mysql
      - name: Run non-interactive installer
        env:
          GOOGLE_MAPS_API_KEY: ${{ secrets.GOOGLE_MAPS_API_KEY }}
        run: |
          [ -f api/.env ] || cp api/.env.example api/.env 2>/dev/null || touch api/.env
          set_env() {
            if grep -q "^$1=" api/.env; then
              sed -i "s|^$1=.*|$1=$2|" api/.env
            else
              echo "$1=$2" >> api/.env
            fi
          }
          set_env THROTTLE_ENABLED false
          if [ -n "${GOOGLE_MAPS_API_KEY:-}" ]; then
            set_env GOOGLE_MAPS_API_KEY "$GOOGLE_MAPS_API_KEY"
            echo "Geocoding enabled for address-string contract fixtures."
          else
            echo "::notice::GOOGLE_MAPS_API_KEY not set; coordinate and GeoJSON place fixtures remain available."
          fi
          set_env STOREFRONT_BYPASS_VERIFICATION_CODE 000000
          set_env STOREFRONT_REVIEW_ACCOUNTS '+15555550123'
          set_env MAIL_MAILER log
          set_env MAIL_FROM_ADDRESS ci-contract@fleetbase.local
          bash scripts/docker-install.sh --non-interactive
      - name: Wait for API health
        run: |
          set -uo pipefail
          for attempt in $(seq 1 30); do
            if curl --fail --silent --max-time 5 http://localhost:8000/health | grep -q '"status"'; then
              echo "API is healthy (attempt $attempt)."
              exit 0
            fi
            sleep 5
          done
          echo "::error::API did not become healthy."
          exit 1
      # Mirror the canonical api-contract.yml overlay sequence before seeding:
      # replace package, rebuild classmap, migrate, clear caches, reload Octane.
      - name: Checkout locked Fleet-Ops source for overlay
        if: env.FLEETOPS_SOURCE_REF != env.FLEETOPS_REF
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          repository: fleetbase/fleetops
          ref: ${{ env.FLEETOPS_SOURCE_REF }}
          path: .fleetops-overlay
          persist-credentials: false
      - name: Overlay locked Fleet-Ops implementation
        if: env.FLEETOPS_SOURCE_REF != env.FLEETOPS_REF
        run: |
          set -euo pipefail
          test "$(git -C .fleetops-overlay rev-parse HEAD)" = "$FLEETOPS_SOURCE_REF"
          test -f .fleetops-overlay/composer.json
          # The target is one package inside this runner's disposable container.
          docker compose exec -T application sh -c 'rm -rf /fleetbase/api/vendor/fleetbase/fleetops-api && mkdir -p /fleetbase/api/vendor/fleetbase/fleetops-api'
          tar --exclude=.git -C .fleetops-overlay -cf - . | docker compose exec -T application sh -c 'tar -C /fleetbase/api/vendor/fleetbase/fleetops-api -xf -'
          docker compose exec -T application chown -R www-data:www-data /fleetbase/api/vendor/fleetbase/fleetops-api
          docker compose exec -T application su www-data -s /bin/sh -c 'cd /fleetbase/api && composer dump-autoload --optimize --no-scripts'
          docker compose exec -T application su www-data -s /bin/sh -c 'cd /fleetbase/api && php artisan optimize:clear && php artisan migrate --force && php artisan octane:reload'
          echo "Fleet-Ops source under test: $FLEETOPS_SOURCE_REF" >> "$GITHUB_STEP_SUMMARY"
          for attempt in $(seq 1 20); do
            if curl --fail --silent --max-time 5 http://localhost:8000/health | grep -q '"status"'; then
              echo "API healthy after overlay (attempt $attempt)."
              exit 0
            fi
            sleep 3
          done
          echo "::error::API did not recover after the locked Fleet-Ops overlay."
          exit 1
      - name: Mint a fresh SDK smoke credential
        env:
          CI_CUSTOMER_IDENTITY: ci-customer@fleetbase.local
          CI_CUSTOMER_PHONE: '+15555550123'
          CI_CUSTOMER_PASSWORD: CiCustomerPassw0rd!
          CI_CUSTOMER_VERIFICATION_CODE: '000000'
          CI_DRIVER_IDENTITY: ci-driver@fleetbase.local
          CI_DRIVER_PHONE: '+15555550124'
          CI_DRIVER_PASSWORD: CiDriverPassw0rd!
        run: |
          code="$(base64 scripts/ci/mint-api-key.php | tr -d '\n')"
          output="$(docker compose exec -T \
            -e "CI_CUSTOMER_IDENTITY=$CI_CUSTOMER_IDENTITY" \
            -e "CI_CUSTOMER_PHONE=$CI_CUSTOMER_PHONE" \
            -e "CI_CUSTOMER_PASSWORD=$CI_CUSTOMER_PASSWORD" \
            -e "CI_CUSTOMER_VERIFICATION_CODE=$CI_CUSTOMER_VERIFICATION_CODE" \
            -e "CI_DRIVER_IDENTITY=$CI_DRIVER_IDENTITY" \
            -e "CI_DRIVER_PHONE=$CI_DRIVER_PHONE" \
            -e "CI_DRIVER_PASSWORD=$CI_DRIVER_PASSWORD" \
            application php artisan tinker --execute="eval(base64_decode('${code}'));" 2>&1)"
          if printf '%s\n' "$output" | grep -q 'MINT_ERROR'; then
            printf '%s\n' "$output" | grep -A 2 'MINT_ERROR'
            exit 1
          fi
          key="$(printf '%s\n' "$output" | grep -oE 'flb_(live|test)_[A-Za-z0-9_-]+' | tail -1)"
          if [ -z "$key" ]; then
            echo "Unable to mint the disposable SDK credential." >&2
            exit 1
          fi
          echo "::add-mask::$key"
          echo "FLEETBASE_CONTRACT_API_KEY=$key" >> "$GITHUB_ENV"
      - name: Check out the SDK under test
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          path: .sdk
      - name: Set up PHP for SDK smoke cases
        uses: shivammathur/setup-php@db91e1a0e48e84637d325a7ee4d2677e146ceec4 # 2.36.0
        with:
          php-version: "8.2"
          coverage: none
          tools: composer:v2
      - name: Install SDK dependencies
        run: composer install --working-dir=.sdk --no-interaction --prefer-dist
      - name: Start the PHP SDK contract bridge
        run: |
          mkdir -p .sdk/build/live-contract
          FLEETBASE_CONTRACT_TARGET_URL=http://127.0.0.1:8000 \
          FLEETBASE_CONTRACT_NAMESPACE=v1 \
          FLEETBASE_CONTRACT_STATE="$GITHUB_WORKSPACE/.sdk/build/live-contract/state.json" \
            php -S 127.0.0.1:9000 .sdk/tools/live-sdk-contract-router.php \
            > .sdk/build/live-contract/bridge.log 2>&1 &
          echo $! > .sdk/build/live-contract/bridge.pid
          for attempt in $(seq 1 20); do
            if curl --fail --silent http://127.0.0.1:9000/__sdk_contract_health | grep -q '"status":"ok"'; then
              echo "SDK bridge is healthy (attempt $attempt)."
              exit 0
            fi
            sleep 1
          done
          echo "The PHP SDK contract bridge did not start." >&2
          exit 1
      - name: Run both official Postman collections through the SDK
        uses: ./.github/actions/postman-contract
        with:
          collections: |
            Fleetbase API
            Fleetbase Core API
          base-url: http://127.0.0.1:9000
          postman-ref: ${{ env.POSTMAN_REF }}
          postman-api-key: ${{ env.POSTMAN_API_KEY }}
          github-token: ${{ env.SOURCE_TOKEN }}
          # Test-mode keys only; the action deliberately ignores live keys.
          stripe-publishable-key: ${{ secrets.STRIPE_TEST_KEY }}
          stripe-secret-key: ${{ secrets.STRIPE_TEST_SECRET }}
      - name: Prove every locked request invoked its SDK method
        if: always()
        run: php .sdk/tools/check-live-sdk-contract.php --state=.sdk/build/live-contract/state.json
      - name: Run SDK cases against the same stack
        run: php .sdk/tools/run-live-contract-smoke.php
        env:
          FLEETBASE_CONTRACT_BASE_URL: http://localhost:8000
      - name: Upload SDK live-contract evidence
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: php-sdk-live-contract
          path: .sdk/build/live-contract/
          if-no-files-found: error
          retention-days: 30
      - name: Dump stack logs on failure
        if: failure()
        run: |
          docker compose ps || true
          docker compose logs --no-color --tail=300 || true
      - name: Tear down disposable stack
        if: always()
        run: docker compose down --volumes || true