diff --git a/backend/Cargo.toml b/backend/Cargo.toml index 02c4707..15b4575 100644 --- a/backend/Cargo.toml +++ b/backend/Cargo.toml @@ -2,6 +2,8 @@ name = "predifi-backend" version = "0.1.0" edition = "2021" +description = "Axum HTTP backend for the PrediFi platform" +readme = "README.md" [[bin]] name = "predifi-backend" diff --git a/backend/README.md b/backend/README.md index 12ed5a1..4ce9cbc 100644 --- a/backend/README.md +++ b/backend/README.md @@ -49,7 +49,7 @@ Verify it is running: ```bash curl http://localhost:3000/ # 200 — welcome message -curl http://localhost:3000/health # 200 — {"status":"ok"} +curl http://localhost:3000/health # 200 — {"status":"ok","service":"predifi-backend","version":"0.1.0"} curl http://localhost:3000/missing # 404 — unknown route ``` diff --git a/backend/src/main.rs b/backend/src/main.rs index 1f4daf8..fee2465 100644 --- a/backend/src/main.rs +++ b/backend/src/main.rs @@ -25,9 +25,18 @@ use axum::{routing::get, Json, Router}; use request_logger::LoggingLayer; use serde_json::json; -/// Simple health-check handler — returns `{ "status": "ok" }`. +/// Health-check handler. +/// +/// Returns HTTP 200 with basic system info: +/// - `status`: always `"ok"` when the server is running +/// - `service`: name of the service +/// - `version`: current package version from Cargo.toml async fn health() -> Json { - Json(json!({ "status": "ok" })) + Json(json!({ + "status": "ok", + "service": "predifi-backend", + "version": env!("CARGO_PKG_VERSION") + })) } /// Root handler — returns a welcome message. diff --git a/backend/src/tests.rs b/backend/src/tests.rs index b4bccc0..c33f6b7 100644 --- a/backend/src/tests.rs +++ b/backend/src/tests.rs @@ -1,4 +1,3 @@ - #[cfg(test)] mod tests { use axum::http::{Request, StatusCode}; @@ -66,9 +65,7 @@ mod tests { assert_eq!(response.status(), StatusCode::NOT_FOUND); } - /// Verify the middleware does not alter the status code of a 200 response. - /// The middleware is purely observational — it must be transparent to callers. #[tokio::test] async fn middleware_does_not_alter_200_status() { let response = build_router() @@ -84,7 +81,6 @@ mod tests { } /// Verify the middleware does not alter the status code of a 404 response. - /// Same transparency guarantee, but for error responses. #[tokio::test] async fn middleware_does_not_alter_404_status() { let response = build_router() @@ -122,4 +118,29 @@ mod tests { ); } } -} \ No newline at end of file + + /// GET /health must return basic system info including service and version. + #[tokio::test] + async fn health_returns_system_info() { + let response = build_router() + .oneshot(get("/health")) + .await + .expect("request failed"); + + assert_eq!(response.status(), StatusCode::OK); + + let body = body_string(response.into_body()).await; + assert!( + body.contains("\"service\""), + "body should contain a service field, got: {body}" + ); + assert!( + body.contains("\"version\""), + "body should contain a version field, got: {body}" + ); + assert!( + body.contains("predifi-backend"), + "body should contain the service name, got: {body}" + ); + } +} diff --git a/docs/health-check-endpoint.md b/docs/health-check-endpoint.md new file mode 100644 index 0000000..485a356 --- /dev/null +++ b/docs/health-check-endpoint.md @@ -0,0 +1,62 @@ +# Health Check Endpoint + +## Overview + +This document describes the health check endpoint implemented in +`predifi-backend`. It provides a simple way for load balancers, +orchestrators, and developers to verify the service is running. + +--- + +## Endpoint +``` +GET /health +``` + +### Response +```json +{ + "status": "ok", + "service": "predifi-backend", + "version": "0.1.0" +} +``` + +- `status` — always `"ok"` when the server is running +- `service` — name of the service +- `version` — current version from Cargo.toml + +--- + +## Implementation + +**File:** `src/main.rs` + +### `health()` handler +An async Axum handler that returns HTTP 200 with basic system info. +The version is read at compile time from `Cargo.toml` using +`env!("CARGO_PKG_VERSION")` — no runtime overhead. + +--- + +## Test Coverage + +**File:** `src/tests.rs` + +| Test | What it verifies | +|------|-----------------| +| `health_returns_200_with_ok_body` | Returns HTTP 200 with status field | +| `health_returns_system_info` | Returns service name and version | +| `middleware_does_not_alter_200_status` | Middleware doesn't change 200 response | + +--- + +## Example Usage +```bash +curl http://localhost:3000/health +``` + +Expected response: +```json +{"status":"ok","service":"predifi-backend","version":"0.1.0"} +``` \ No newline at end of file diff --git a/docs/initialize-backend-cargo-workspace.md b/docs/initialize-backend-cargo-workspace.md new file mode 100644 index 0000000..e69de29