fix(health): rename public liveness route to /livez by moonming · Pull Request #257 · api7/aisix

moonming · 2026-05-12T04:02:13Z

Summary

rename the unauthenticated public liveness route from /health to /livez on both proxy and standalone admin listeners
keep /admin/v1/health unchanged for authenticated operator health, and update OpenAPI, docs, and e2e coverage to match
wire the shared livez state into shutdown so the liveness response can fail during graceful termination

Summary by CodeRabbit

New Features
- Added an unauthenticated liveness endpoint at /livez (plain-text "ok" by default) with optional verbose output and shutdown detection; liveness state is shared across components.
Bug Fixes
- Removed the previous public /health route (now returns 404).
Documentation
- Updated API and testing docs to reference /livez for probes.
Tests
- Added/updated unit and E2E tests for /livez; test harness can forward signals to the spawned app.

coderabbitai · 2026-05-12T04:02:20Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: d3578329-d0af-4f83-80e9-c7060eaa4211

📥 Commits

Reviewing files that changed from the base of the PR and between 48967d6 and 0b138cd.

📒 Files selected for processing (1)

tests/e2e/src/harness/app.ts

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

tests/e2e/src/harness/app.ts

📝 Walkthrough

Walkthrough

This PR replaces the unauthenticated /health endpoint with a minimal /livez liveness probe. LivezState tracks shutdown and generates plain-text HTTP responses with security headers. The proxy and admin services both expose /livez backed by shared state, server initialization threads this state through shutdown coordination, and documentation and tests are updated accordingly.

Changes

Liveness endpoint migration from /health to /livez

Layer / File(s)	Summary
LivezState and livez_response implementation `crates/aisix-proxy/src/health.rs`	`LivezState` tracks process shutdown via `AtomicBool`. `livez_response(livez, verbose)` returns `200 OK` with plain-text `"ok"` body or `500 INTERNAL_SERVER_ERROR` with `"livez check failed"` when shutdown is detected. Response includes security headers `Content-Type: text/plain; charset=utf-8` and `X-Content-Type-Options: nosniff`. Tests validate terse success, verbose success with ping/shutdown/pass markers, and 500 shutdown failure behavior.
Proxy service livez wiring `crates/aisix-proxy/src/state.rs`, `crates/aisix-proxy/src/lib.rs`	`ProxyState` gains exported `livez: Arc<LivezState>` field, initialized in all constructors. Router mounts `GET /livez` handler that reads optional `verbose` query parameter and delegates to `livez_response`. `LivezState` added to public re-exports alongside `HealthTracker`. Tests validate `/livez` returns plain `"ok"` by default, rejects non-GET with `405`, and `/health` is not found.
Admin service livez wiring `crates/aisix-admin/src/state.rs`, `crates/aisix-admin/src/lib.rs`, `crates/aisix-admin/src/openapi.rs`	`AdminState` gains exported `livez_state: Arc<LivezState>` field with builder `with_livez_state()` to enable sharing proxy's shutdown state. Router mounts `GET /livez` handler backed by `livez_response`. OpenAPI documents `/livez` as a public GET endpoint with optional `verbose` query and `200`/`500` `text/plain` string responses (no `enum` constraint). Admin tests validate `/livez` returns `200/"ok"`, rejects non-GET, and `/health` returns `404`.
Server initialization and shutdown coordination `crates/aisix-server/src/main.rs`	Clones `livez_state` from `proxy_state`, shares it with admin via `.with_livez_state()` in standalone mode, and passes `livez_state` into `wait_for_signal`. On SIGINT/SIGTERM the code calls `livez_state.mark_shutting_down()` then waits briefly before sending the global cancellation signal.
Documentation and e2e test coverage `crates/aisix-etcd/src/supervisor.rs`, `docs/api-admin.md`, `docs/testing.md`, `tests/e2e/src/harness/app.ts`, `tests/e2e/src/cases/health-minimal-e2e.test.ts`	Supervisor comments updated to reference `/admin/v1/health`. Admin API docs and testing docs updated to mention `/livez`. E2E harness readiness probe changed to `/livez` for the proxy; `SpawnedApp` gains `signal()` method. New minimal e2e test asserts proxy and admin `/livez` return `200/"ok"` and `/health` returns `404`.

🎯 3 (Moderate) | ⏱️ ~20 minutes

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

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

Copilot

Pull request overview

Renames the public unauthenticated liveness endpoint from /health to /livez across the proxy and standalone admin listeners, while keeping the authenticated operator health endpoint at /admin/v1/health. It also shares a common liveness state so /livez can fail during graceful shutdown, and updates docs and tests to match.

Changes:

Replace public /health with /livez on proxy and admin listeners; add coverage that /health is now absent.
Introduce shared LivezState and mark it shutting down on SIGINT/SIGTERM so liveness can fail during termination.
Update e2e harness readiness checks, docs, and admin OpenAPI to reflect /livez and retain /admin/v1/health.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/e2e/src/harness/app.ts	Updates readiness probe from proxy `/health` to `/livez` while keeping admin readiness on `/admin/v1/health`.
tests/e2e/src/cases/health-minimal-e2e.test.ts	Adds e2e regression test asserting `/livez` works and `/health` returns 404 on both listeners.
docs/testing.md	Updates testing doc to reference `/livez` as the minimal public probe.
docs/api-admin.md	Updates admin API docs to list `/livez` as the unauthenticated liveness probe.
crates/aisix-server/src/main.rs	Threads shared `LivezState` into shutdown signal handling and into AdminState in standalone mode.
crates/aisix-proxy/src/state.rs	Adds `livez: Arc<LivezState>` to `ProxyState` and initializes it in constructors.
crates/aisix-proxy/src/lib.rs	Replaces router mount `/health` with `/livez` and routes to `livez_response`; adds unit tests for `/livez` and `/health` absence.
crates/aisix-proxy/src/health.rs	Introduces `LivezState` + `livez_response` (plain text “ok”, verbose mode, and shutdown-failure behavior).
crates/aisix-etcd/src/supervisor.rs	Updates comments to reference `/admin/v1/health` instead of `/health`.
crates/aisix-admin/src/state.rs	Adds `livez_state` to admin state and a builder method to share it with the proxy.
crates/aisix-admin/src/openapi.rs	Renames documented public route from `/health` to `/livez` and adds schema for plain “ok” response.
crates/aisix-admin/src/lib.rs	Replaces router mount `/health` with `/livez` (using shared `livez_response`) and updates tests accordingly.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "enum": ["ok"]
+                }
+              }
+            }


+pub fn livez_response(livez: &LivezState, verbose: bool) -> Response {
+    let mut body = String::new();
+    let mut failed = false;
+
+    body.push_str("[+]ping ok\n");
+    match livez.shutdown_check() {
+        Ok(()) => body.push_str("[+]shutdown ok\n"),
+        Err(_) => {
+            failed = true;
+            body.push_str("[-]shutdown failed: reason withheld\n");
+        }
+    }


Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

+pub fn livez_response(livez: &LivezState, verbose: bool) -> Response {
+    let mut body = String::new();
+    let mut failed = false;
+
+    body.push_str("[+]ping ok\n");
+    match livez.shutdown_check() {
+        Ok(()) => body.push_str("[+]shutdown ok\n"),
+        Err(_) => {
+            failed = true;
+            body.push_str("[-]shutdown failed: reason withheld\n");


+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "enum": ["ok"]
+                }
+              }
+            }


Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

+    app.signal("SIGTERM");
+
+    const deadline = Date.now() + 3000;
+    let observedUnhealthy = false;
+    while (Date.now() < deadline) {
+      try {
+        const res = await harnessRequest(`${app.proxyUrl}/livez`, { method: "GET" });
+        if (res.statusCode !== 200) {
+          observedUnhealthy = true;
+          await res.body.dump();
+          break;
+        }
+        await res.body.dump();
+      } catch {
+        observedUnhealthy = true;
+        break;
+      }
+      await new Promise((r) => setTimeout(r, 50));
+    }
+
+    expect(observedUnhealthy).toBe(true);
+    app = undefined;


    }

+    livez_state.mark_shutting_down();
+    tokio::time::sleep(std::time::Duration::from_secs(1)).await;


- quickstart/self-hosted: document the /livez liveness route and plain-text body (per #257); add Cleanup - quickstart/openai-sdk: switch to .mjs so \`node\` runs the example without a TypeScript loader - quickstart/first-model-first-key-first-request: add production-credentials warning, 401/403 verification step using the real proxy error envelope, Cleanup, and a per-provider api_base callout - integration/openai-compatible-api: add mermaid diagram of the request path; route list reflects the /livez rename - integration/errors-and-retries: replace placeholder error.type strings with the real ProxyError mapping; add 413 RequestTooLarge row; note the admin {error_msg} envelope distinction - configuration/provider-keys: warn about plaintext secret storage; replace the inaccurate OpenAI api_base normalization claim with a per-provider truth table (refs #270) - operations/health-checks: rewrite for the /livez liveness contract plus the /admin/v1/health per-model shape (per #256 + #257) - reference/proxy-api-reference: /livez instead of /health in the route list - tutorials/build-a-virtual-model-with-failover: rewrite end-to-end against routing-strategies-e2e (deliberately break primary, observe cooldown) - tutorials/enable-response-caching: rewrite against cache-policy-e2e (x-aisix-cache miss then hit, different prompt misses again) - tutorials/add-keyword-guardrails: rewrite against guardrail-keyword-e2e (422 content_filter; no-leak message contract per #203) - tutorials/openai-client-to-anthropic-upstream: rewrite against anthropic-upstream-e2e; document bare-host api_base for Anthropic Every command, field, header, and error code was cross-checked against the relevant crate or e2e test on this branch. No mock data; nothing speculative.

moonming added 7 commits May 12, 2026 10:08

fix(admin): minimize unauthenticated health response

b81b633

test(admin): cover invalid method on health route

d2ce185

fix(proxy): minimize unauthenticated health response

cd300eb

test(health): pin minimal public health contract

780a806

test(health): cover public route method constraints

59672fb

style(health): apply rustfmt to health changes

7936101

fix(health): rename public liveness route to /livez

9c37788

Copilot AI review requested due to automatic review settings May 12, 2026 04:02

Copilot started reviewing on behalf of moonming May 12, 2026 04:02 View session

Copilot AI reviewed May 12, 2026

View reviewed changes

moonming added 2 commits May 12, 2026 12:24

docs(health): note /livez probe migration

4acf3ca

docs(health): remove livez migration note

1edff8c

Copilot AI review requested due to automatic review settings May 12, 2026 06:59

Copilot started reviewing on behalf of moonming May 12, 2026 07:00 View session

Copilot AI reviewed May 12, 2026

View reviewed changes

moonming added 3 commits May 12, 2026 15:40

test(health): cover shutdown livez behavior

48967d6

fix(health): rename public liveness route to /livez

0649741

merge: refresh /livez branch onto latest main

0b138cd

Copilot AI review requested due to automatic review settings May 12, 2026 08:13

Copilot started reviewing on behalf of moonming May 12, 2026 08:13 View session

Copilot AI reviewed May 12, 2026

View reviewed changes

moonming merged commit 2884ff4 into main May 12, 2026
11 checks passed

moonming mentioned this pull request May 12, 2026

Rename hardened /health endpoint to /livez #253

Closed

This was referenced May 15, 2026

docs: replace GET /health references with /livez and /admin/v1/health across configuration, reference, and operations docs #293

Closed

docs: replace stale GET /health references with /livez and /admin/v1/health #294

Merged

jarvis9443 deleted the fix/issue-253-rename-health-to-livez branch June 25, 2026 06:26

Navigation Menu

Uh oh!

fix(health): rename public liveness route to /livez - #257

fix(health): rename public liveness route to /livez#257
moonming merged 12 commits into
mainfrom
fix/issue-253-rename-health-to-livez

moonming commented May 12, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented May 12, 2026 •

edited

Loading

Reviews paused

Walkthrough

Changes

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

moonming commented May 12, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

moonming commented May 12, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented May 12, 2026 •

edited

Loading