fix(apisix): use req_headers for active health checks

[xiaocanglan1]

Description

Apache APISIX defines custom request headers for active upstream health checks as checks.active.req_headers, but ADC currently defines the field as http_request_headers in both its configuration schema and APISIX standalone typing.

Because these schemas use z.strictObject, a valid APISIX configuration containing req_headers is rejected by adc lint, adc sync, and other commands that run the local lint stage. Conversely, the ADC-only field name cannot be accepted by the APISIX upstream schema.

The canonical APISIX field is defined in apisix/schema_def.lua and documented as upstream.checks.active.req_headers.

Environment

• Affected ADC image: ghcr.io/api7/adc:0.27.1
• Image digest: sha256:f65f53dd966827ff485471d00b9ce8ca146f7aba187519817b7453e476a274b8
• ADC base commit tested before the fix: 99142525450f
• Host: macOS 26.5.1, arm64
• Docker client/server: 29.5.2 / 28.4.0
• Node.js: 22.22.3
• pnpm: 11.17.0

The reproduction only uses adc lint, so it does not require a running APISIX instance.

Why this update is needed

APISIX has used req_headers for active health-check request headers across its supported upstream schema. ADC's http_request_headers name does not match the Admin API/standalone configuration contract.

This mismatch currently requires downstream users to patch the compiled /main.cjs bundle with sed. Fixing the source schemas removes that image-level workaround and keeps ADC configuration validation aligned with APISIX.

How to reproduce

Create adc.yaml:

services:
  - name: health-check-service
    upstream:
      nodes:
        - host: 127.0.0.1
          port: 8080
          weight: 1
      checks:
        active:
          type: http
          http_path: /health
          req_headers:
            - "User-Agent: adc-health-check"

Run ADC 0.27.1:

docker run --rm \
  -v "$PWD/adc.yaml:/work/adc.yaml:ro" \
  ghcr.io/api7/adc:0.27.1 \
  lint -f /work/adc.yaml

Actual result before this change (exit status 1):

The following errors were found in configuration:
✖ Unrecognized key: "req_headers"
  → at services[0].upstream.checks.active

Expected result:

All is well, see you next time!

The locally built CLI with this change returns exit status 0 for the same file.

Changes

• Rename http_request_headers to req_headers in the SDK upstream schema.
• Rename the field in APISIX standalone upstream typing.
• Regenerate schema.json so both inline and referenced upstream definitions expose req_headers.
• Add a CLI linter regression test that validates an active health check with req_headers.

Verification

pnpm exec vitest run apps/cli/src/linter/specs/upstream.spec.ts \
  --config apps/cli/vitest.config.ts
pnpm exec nx run cli:test --skip-nx-cache
pnpm exec nx run sdk:test --skip-nx-cache
pnpm exec nx run-many --target=typecheck --all --skip-nx-cache
pnpm exec nx run-many --target=lint --all --skip-nx-cache
pnpm exec nx run cli:build --configuration=production --skip-nx-cache

Results:

• Targeted upstream linter tests: 8 passed.
• CLI unit tests: 29 passed.
• SDK unit tests: 11 passed.
• Type checking: all 7 projects passed.
• Lint: all targets passed with pre-existing warnings only and no errors.
• Production CLI build: passed.
• Built dist/apps/cli/main.cjs: 2 occurrences of req_headers: and 0 occurrences of http_request_headers:.
• ADC 0.27.1 reproduction: failed as expected with exit status 1.
• Fixed local build: passed the same configuration with exit status 0.

Compatibility

This intentionally replaces the incorrect ADC-only field name. Configurations using http_request_headers must rename it to req_headers; the old name is not valid in the APISIX upstream schema and cannot be synchronized successfully to APISIX.

Checklist

• I have explained the need for this PR and the problem it solves
• I have explained the changes or the new features added to this PR
• I have added tests corresponding to this change
• I have updated the generated schema documentation to reflect this change
• I have verified that this change is backward compatible (see compatibility note above)

Summary by CodeRabbit

• New Features

  • Added support for configuring request headers on HTTPS active health checks using the req_headers setting.

• Bug Fixes

  • Updated configuration validation to consistently recognize req_headers for services and upstreams.
  • Added validation coverage to ensure valid request-header configurations pass linting.

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: aa508d58-99a6-412a-9fed-79fafade9c72

📥 Commits

Reviewing files that changed from the base of the PR and between 23e730c and 93cc764.

📒 Files selected for processing (4)

• apps/cli/src/linter/specs/upstream.spec.ts
• libs/backend-apisix-standalone/src/typing.ts
• libs/sdk/src/core/schema.ts
• schema.json

🚧 Files skipped from review as they are similar to previous changes (4)

• libs/sdk/src/core/schema.ts
• libs/backend-apisix-standalone/src/typing.ts
• apps/cli/src/linter/specs/upstream.spec.ts
• schema.json

---

📝 Walkthrough

Walkthrough

The active health-check request header property is renamed from http_request_headers to req_headers in TypeScript and JSON schemas. A linter test covers HTTPS upstream configurations using the new property.

Changes

Upstream header configuration

Layer / File(s)	Summary
Update active health-check schemas libs/backend-apisix-standalone/src/typing.ts, libs/sdk/src/core/schema.ts, schema.json	The active health-check schemas now define the optional request-header array as req_headers.
Validate req_headers configuration apps/cli/src/linter/specs/upstream.spec.ts	Adds linter coverage confirming that req_headers is accepted for an HTTPS active health check.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: bzp2010

🚥 Pre-merge checks | ✅ 5 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
E2e Test Quality Review	⚠️ Warning	The new case is a unit test: upstream.spec.ts calls check() directly; it does not exercise adc lint or configuration loading, so the blocking E2E criterion is unmet.	Add an E2E test under apps/cli/e2e that supplies YAML to the lint command and asserts success; also cover rejection of http_request_headers and empty req_headers.

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the rename of the active health-check request header field to req_headers.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Security Check	✅ Passed	PASS: The diff only renames an upstream health-check schema field, updates generated schema, and adds a harmless test; it adds no logging, storage, authorization, TLS, isolation, or secret-resoluti...

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}