chore: pull the shared API contract

.github/workflows/ci.yml

@@ -70,3 +70,13 @@ jobs:
           python -m pip install build==1.6.1 twine==7.0.0
           python -m build
           twine check --strict dist/*
+
+  contract:
+    name: Shared contract files match the lock
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          persist-credentials: false
+      - name: Contract files match .shieldlabs-contract.lock
+        run: python3 scripts/sync_contract.py --check

.github/workflows/contract-sync.yml

@@ -0,0 +1,180 @@
+name: Contract sync
+
+# Takes the shared API contract (test fixtures, see contract-sync.json) from the newest
+# shieldlabs-openapi release, or from the release given by hand or by a contract-release
+# dispatch. When files change, it runs the full test suite and opens a pull request with the
+# result. Pull requests opened with GITHUB_TOKEN start no other workflow, so the tests run here.
+
+on:
+  schedule:
+    - cron: '17 6 * * *'
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Contract release: 'latest' or a tag such as v1.0.1"
+        required: false
+        default: latest
+        type: string
+  repository_dispatch:
+    types: [contract-release]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: contract-sync-${{ github.repository }}
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    name: Sync the shared contract
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          persist-credentials: false
+
+      - name: Sync the contract files
+        id: sync
+        env:
+          INPUT_REF: ${{ inputs.ref }}
+          DISPATCH_REF: ${{ github.event.client_payload.ref }}
+          # Only raises the GitHub API rate limit when resolving 'latest'.
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          ref="${DISPATCH_REF:-${INPUT_REF:-latest}}"
+          if ! [[ "$ref" =~ ^(latest|v[0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
+            echo "::error::Invalid contract ref: use latest or a tag such as v1.0.1."
+            exit 1
+          fi
+          python3 scripts/sync_contract.py --ref "$ref"
+          resolved="$(python3 -c 'import json; print(json.load(open(".shieldlabs-contract.lock"))["ref"])')"
+          if ! [[ "$resolved" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::Unexpected ref in .shieldlabs-contract.lock."
+            exit 1
+          fi
+          mapfile -t files < <(python3 -c 'import json; print("\n".join(json.load(open("contract-sync.json"))["files"].values()))')
+          if [ -n "$(git status --porcelain -- "${files[@]}")" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            # Same bytes under a newer tag: keep the lock as it is, no pull request.
+            git checkout -- .shieldlabs-contract.lock
+            echo "Contract files are already those of $resolved."
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+          echo "ref=$resolved" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        if: steps.sync.outputs.changed == 'true'
+        with:
+          python-version: '3.12'
+
+      - name: Run the full test suite
+        id: tests
+        if: steps.sync.outputs.changed == 'true'
+        continue-on-error: true
+        shell: bash
+        run: |
+          {
+            python -m pip install --upgrade pip
+            python -m pip install -e ".[dev]" -r examples/requirements.txt
+            ruff check .
+            ruff format --check .
+            mypy --strict src
+            pytest -q --cov=shieldlabs --cov-report=term-missing
+            python -m pip install build==1.6.1 twine==7.0.0
+            python -m build
+            twine check --strict dist/*
+          } 2>&1 | tee "$RUNNER_TEMP/contract-tests.log"
+
+      - name: Push the branch and open or update the pull request
+        if: steps.sync.outputs.changed == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          CONTRACT_REF: ${{ steps.sync.outputs.ref }}
+          TESTS: ${{ steps.tests.outcome }}
+        run: |
+          set -euo pipefail
+          if ! [[ "$CONTRACT_REF" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::Unexpected contract ref."
+            exit 1
+          fi
+          export GH_REPO="$GITHUB_REPOSITORY"
+          base="$GITHUB_REF_NAME"
+          branch="contract-sync/$CONTRACT_REF"
+          label="contract-change-needs-code"
+          version="$(python3 -c 'import json; print(json.load(open(".shieldlabs-contract.lock"))["contract_version"])')"
+          mapfile -t files < <(python3 -c 'import json; print("\n".join(json.load(open("contract-sync.json"))["files"].values()))')
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git switch -c "$branch"
+          git add -- "${files[@]}" .shieldlabs-contract.lock
+          changes="$(git diff --cached --name-status)"
+          git commit -q -m "chore: sync the shared contract $CONTRACT_REF"
+
+          remote_sha="$(gh api "repos/$GITHUB_REPOSITORY/git/ref/heads/$branch" --jq .object.sha 2>/dev/null || true)"
+          remote_tree=""
+          if [[ "$remote_sha" =~ ^[0-9a-f]{40}$ ]]; then
+            remote_tree="$(gh api "repos/$GITHUB_REPOSITORY/git/commits/$remote_sha" --jq .tree.sha)"
+          fi
+          if [ "$remote_tree" = "$(git rev-parse 'HEAD^{tree}')" ]; then
+            echo "$branch already holds these changes."
+          else
+            git push --force "https://x-access-token:$GH_TOKEN@${GITHUB_SERVER_URL#https://}/$GITHUB_REPOSITORY.git" "HEAD:refs/heads/$branch"
+          fi
+
+          body="$RUNNER_TEMP/contract-pr.md"
+          {
+            echo "Syncs the shared API contract to [$CONTRACT_REF](https://github.com/ShieldLabs-ai/shieldlabs-openapi/releases/tag/$CONTRACT_REF) of shieldlabs-openapi (contract_version $version)."
+            echo
+            echo "Changed files:"
+            echo
+            echo '```'
+            echo "$changes"
+            echo '```'
+            echo
+            if [ "$TESTS" = "success" ]; then
+              echo "Tests: the full test suite passes with these files."
+            else
+              echo "Tests: **the full test suite fails with these files** ($TESTS). The SDK must change before it can take this contract; push the fixes to this branch."
+              echo
+              echo "<details><summary>Last lines of the test log</summary>"
+              echo
+              echo '```'
+              tail -n 80 "$RUNNER_TEMP/contract-tests.log" 2>/dev/null | cut -c1-300 || true
+              echo '```'
+              echo
+              echo "</details>"
+            fi
+            echo
+            echo "Run: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+            echo
+            echo "Pull requests opened by this workflow start no other workflow. Close and reopen this pull request (or push to its branch) to run the usual checks."
+          } > "$body"
+
+          number="$(gh pr list --head "$branch" --base "$base" --state open --json number --jq '.[0].number // empty')"
+          if [ -n "$number" ]; then
+            gh pr edit "$number" --body-file "$body"
+          elif ! gh pr create --base "$base" --head "$branch" --title "chore: sync the shared contract $CONTRACT_REF" --body-file "$body"; then
+            echo "::error::Could not open the pull request. Enable 'Allow GitHub Actions to create and approve pull requests' for this repository, or open it by hand: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/compare/$base...$branch"
+            exit 1
+          fi
+
+          if [ "$TESTS" = "success" ]; then
+            gh pr edit "$branch" --remove-label "$label" >/dev/null 2>&1 || true
+          else
+            gh label create "$label" --force --color D93F0B --description "A contract sync whose tests fail: the SDK must change first" \
+              || echo "::warning::Could not create the $label label."
+            gh pr edit "$branch" --add-label "$label"
+          fi
+
+      - name: Fail when the new contract breaks the tests
+        if: steps.tests.outcome == 'failure'
+        run: |
+          echo "::error::The test suite fails with the new contract files. See the pull request labeled contract-change-needs-code."
+          exit 1

.shieldlabs-contract.lock

@@ -0,0 +1,21 @@
+{
+  "ref": "v1.0.1",
+  "contract_version": "1.0.1",
+  "files": {
+    "error-responses.json": "2be02da69063dcbbf40643559ac6eb6250ae22f5b41562f79810e97e9e3915e0",
+    "history-empty.json": "5616a1180d8234908daca7a08a05afa49a2d0ce06426cc97ebaf7971ba05b339",
+    "history-page.json": "50abc4a9622f800154043b2c67c0479f7e445d01ea46e882e973b217f32f7c9e",
+    "management-profile-expected.json": "5069ddc195bd0a11f5f53c8c964a6096bb54c116c0797fd3a6dd5d26149bc6f9",
+    "management-profile.json": "a02126112d37f0e5857f71d51cbfa201e876217001433af4f41ff27c31e488e6",
+    "normalization-cases.json": "66f1dae0293c26bf55370e713dc54a801b81d433e892022eede22ab592c5bcbe",
+    "risk-band-cases.json": "c9b168f5df1738faccffd69cea23bfdc8d299329ac2a129206ddf7cf9891c20c",
+    "signal-slug-cases.json": "8a79760a89503d48eb11c1e5e5d9b7dbe6756734092fc5a0a93f110f46228365",
+    "webhook-identification-scored.json": "be64dd698516acd46c773c62000bacf5e152ff54b7845c3b1819a563b948ffb2",
+    "webhook-identification-scored.raw.txt": "4cfa0fd3fe0fcfed1de1172d2b7d94c17246c0d6f27c2125909f03d05c71b029",
+    "webhook-ping.json": "90569a442e10c0af00393fcc455e5347d88b1e60624749056815b09ca267a471",
+    "webhook-ping.raw.txt": "5d0fde10a301d142970dc184d2a61cbb03ee58394481abb2e316065a390d4f77",
+    "webhook-rate-limited.json": "4985e08b2b306187d4ad3a78dc9e9d6ecf3bfcbd5fb781921bc02bb9f8a90ccd",
+    "webhook-signature-vectors.json": "33daee0c2823bb9b86b63a688b3065e9cfde3b8ecec14f9a988dfbdd5552fe89",
+    "webhook-test-delivery.json": "7678d32cf757ec604adb35b5b1dbe2a226530cec25266756ed96268f81c6d16d"
+  }
+}

CONTRIBUTING.md

@@ -38,6 +38,11 @@ They are identical in every SDK and compared byte for byte (the `.raw.txt` files
 webhook bodies without a trailing newline), so do not edit them in a pull request. If a fixture
 looks wrong, open an issue.
 
+They come from `contract/` in shieldlabs-openapi. `contract-sync.json` maps each file,
+`.shieldlabs-contract.lock` records the release they come from, and CI runs
+`python3 scripts/sync_contract.py --check`. The `contract-sync.yml` workflow checks for a new
+release every day and opens a pull request, with the test result, when it changes the files.
+
 ## Writing style
 
 Docs, docstrings and comments use plain technical English and the terms used in the README.

contract-sync.json

@@ -0,0 +1,20 @@
+{
+  "source": "shieldlabs-openapi",
+  "files": {
+    "error-responses.json": "tests/data/error-responses.json",
+    "history-empty.json": "tests/data/history-empty.json",
+    "history-page.json": "tests/data/history-page.json",
+    "management-profile-expected.json": "tests/data/management-profile-expected.json",
+    "management-profile.json": "tests/data/management-profile.json",
+    "normalization-cases.json": "tests/data/normalization-cases.json",
+    "risk-band-cases.json": "tests/data/risk-band-cases.json",
+    "signal-slug-cases.json": "tests/data/signal-slug-cases.json",
+    "webhook-identification-scored.json": "tests/data/webhook-identification-scored.json",
+    "webhook-identification-scored.raw.txt": "tests/data/webhook-identification-scored.raw.txt",
+    "webhook-ping.json": "tests/data/webhook-ping.json",
+    "webhook-ping.raw.txt": "tests/data/webhook-ping.raw.txt",
+    "webhook-rate-limited.json": "tests/data/webhook-rate-limited.json",
+    "webhook-signature-vectors.json": "tests/data/webhook-signature-vectors.json",
+    "webhook-test-delivery.json": "tests/data/webhook-test-delivery.json"
+  }
+}