docs: document the /healthcheck endpoint - #493
Merged
Merged
Conversation
Add docs/API_HEALTHCHECK.md covering the endpoint contract: supported methods, exact-path matching, unauthenticated access, the 200/503 status codes, the JSON response fields, and example bodies for healthy, non-writable, and unreachable MongoDB. Include HEAD behavior, curl examples, the hello/isMaster fallback, and multi-instance probing guidance. Link the new doc from the README API surface table and the operations Healthcheck section.
Contributor
There was a problem hiding this comment.
Pull request overview
Documents the existing /healthcheck endpoint and links the reference from the README.
Changes:
- Added comprehensive healthcheck endpoint documentation.
- Updated README API and operations links.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
README.md |
Links to the healthcheck documentation. |
docs/API_HEALTHCHECK.md |
Documents endpoint behavior, responses, probes, and deployment guidance. |
Suppressed comments (2)
docs/API_HEALTHCHECK.md:45
- This guarantee needs to be scoped to requests handled by this endpoint. Unsupported methods and sub-paths call
next()inserver/main.js, so they can receive the normal application's status codes and content types rather than the200/503JSON contract described here.
There are no other status codes. Every response carries the
`Content-Type: application/json` header, including `HEAD` responses.
docs/API_HEALTHCHECK.md:8
- Because this check returns
503for MongoDB outages and read-only nodes, using it as a liveness probe can cause an orchestrator to restart otherwise healthy application containers during a database incident. Please describe it as a readiness/load-balancer probe or explicitly warn against using it for process liveness.
The `/healthcheck` endpoint reports whether the application can reach MongoDB
and whether the connected node accepts writes. It is intended for load-balancer
health probes, container orchestrator liveness/readiness checks, and uptime
monitoring.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+22
to
+24
| The path must match exactly. Sub-paths such as `/healthcheck/db` are not handled | ||
| and fall through to the normal application routes. Query strings are ignored, so | ||
| `/healthcheck?probe=lb` behaves identically to `/healthcheck`. |
Comment on lines
+32
to
+34
| It exposes no user data, no configuration values, and no database contents. The | ||
| only information returned is MongoDB reachability, writability, and a driver | ||
| error message when a check fails. |
Comment on lines
+147
to
+150
| - Writability is detected with the `hello` command, which requires MongoDB 4.4 | ||
| or newer. On older servers the check falls back to the legacy `isMaster` | ||
| command so that a reachable node is not misreported as disconnected. The | ||
| writable flag is read from `isWritablePrimary`, falling back to `ismaster`. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds documentation for the
/healthcheckendpoint, which was implemented but only briefly described in the README (status codes, no response schema).Changes
docs/API_HEALTHCHECK.md— full endpoint reference following the style of the existingdocs/API_INVITES.md:GET,HEAD), exact-path matching, query strings ignored200healthy,503for not-writable and for unreachableHEADbehavior (empty body per RFC 9110 §9.3.2)curlexamples for body, status-code-only, and script-failure probeshellowith legacyisMasterfallback for MongoDB < 4.4README.md— links the new doc from the API surface section and from the Operations → Healthcheck section.Notes
Documentation only. No source or test changes. Content was derived from
server/healthcheck.js,server/main.js, andtests/healthcheck.js.Based on
development.