Health check endpoints

首先定位 MeshHook 现有的 API server 基础设施，以及当前用于检查 Postgres、Supabase 和 worker 状态的机制。定义并实现未经身份验证的 GET /health endpoint，然后添加单元测试和集成测试并更新 API 文档；完成的标准是 response 包含组件详情、版本、整体状态以及指定的失败行为。

📋 Product Requirements Document

PRD: Health check endpoints

Issue: #196
Milestone: Phase 9: Deployment & Operations
Labels: production-readiness, hacktoberfest

---

PRD: Health Check Endpoints for MeshHook

Issue: #196
Milestone: Phase 9: Deployment & Operations
Labels: production-readiness, hacktoberfest

Overview

The implementation of health check endpoints is a critical step towards ensuring MeshHook’s production readiness. This task aims to provide real-time insights into the operational status of MeshHook’s components, including webhook triggers, visual DAG builder, event sourcing, live logs, and multi-tenant security mechanisms. The health check endpoints will serve as a foundational tool for monitoring and diagnosing issues, aligning with MeshHook’s goals of reliability, durability, and ease of maintenance.

Requirements

Functional Requirements

1. Endpoint Implementation: A dedicated /health API endpoint must be implemented to report the health status of MeshHook’s various components.
2. Component Health Checks: The endpoint must perform health checks for critical components including:
   • The Postgres database
   • External services like Supabase Realtime
   • Worker processes for task orchestration and execution
3. Health Response Structure: The /health endpoint must return a structured JSON response detailing the health status of each component and the overall system health.
4. Version Reporting: Include MeshHook’s current version in the health check response to aid in troubleshooting and system monitoring.

Non-Functional Requirements

• Performance: The health check endpoint must be optimized for speed, with a target response time of under 200ms to ensure it does not impact system performance.
• Reliability: The health check must accurately reflect the system’s operational status to enable effective monitoring and timely issue resolution.
• Security: While the endpoint will be publicly accessible, it must not expose any sensitive information or system internals.
• Maintainability: The implementation of the health check feature should be modular, allowing for easy extension as new components are added to MeshHook.

Technical Specifications

Architecture Context

MeshHook is built on a modern tech stack that includes SvelteKit/Svelte 5 for the front end and workflow management, Supabase for backend services, and a microservices architecture for task orchestration and execution. The health check endpoints need to seamlessly integrate into this setup, ensuring compatibility and minimal overhead.

Implementation Approach

1. Analysis: Begin by identifying all critical system components that require health monitoring.
2. Design: Design a JSON response format that effectively communicates the health status of each component and the system as a whole.
3. Implementation:
   • Develop the /health API endpoint within MeshHook’s existing API server infrastructure.
   • For the Postgres database, execute a simple SELECT 1 query as a health check.
   • Utilize Supabase’s health endpoints or equivalent for external services.
   • Implement a heartbeat or status reporting mechanism for worker processes.
4. Integration: Ensure the health check endpoint is properly registered and accessible without authentication.
5. Testing: Create a suite of unit and integration tests to cover the health check functionality.
6. Documentation: Update the project’s API documentation to include the new health check endpoint, specifying the request method, expected response, and any potential error responses.

Data Model

No changes to the existing data model are required for the implementation of health check endpoints.

API Endpoints

GET /health

• Response:

  {
    "status": "healthy",
    "version": "1.0.0",
    "details": {
      "database": "healthy",
      "supabase": "healthy",
      "workers": "healthy"
    }
  }
  

• Error Responses:
  • 500 Internal Server Error: Returned if any critical component is found to be unhealthy.

Acceptance Criteria

• The /health endpoint is implemented and responds to GET requests.
• The endpoint returns a JSON response within 200ms, detailing the health status of critical components and the overall system.
• Unit and integration tests confirm the endpoint’s functionality and reliability.
• Documentation is updated to include the health check endpoint details.

Dependencies

Technical Dependencies

• Existing API infrastructure for integration.
• Access to Supabase and other external services for health status checks.
• Testing frameworks for unit and integration tests.

Prerequisite Tasks

• Ensure all critical components have internal health check mechanisms or endpoints.

Implementation Notes

Development Guidelines

• Adhere to MeshHook’s coding standards and best practices.
• Favor asynchronous operations to enhance endpoint performance.
• Ensure new code is well-commented, documented, and tested.

Testing Strategy

• Develop unit tests for each component health check.
• Create integration tests that simulate various health statuses (healthy, degraded, unhealthy) and verify the endpoint’s response accuracy.

Security Considerations

• Confirm that the health check endpoint does not disclose sensitive information or system internals.
• Regularly review endpoint access logs for unusual patterns that might indicate probing or attack attempts.

Monitoring & Observability

• Integrate endpoint monitoring to track response times and error rates.
• Set up alerts based on health check failures to enable rapid response to emerging issues.

By following these guidelines, MeshHook can ensure its health check endpoints are robust, performant, and secure, providing a solid foundation for system monitoring and operational excellence.

---

This PRD was AI-generated using gpt-4-turbo-preview from GitHub issue #196
Generated: 2025-10-10

📎 Generated Documentation

• 📄 PRD Document: 196-health-check-endpoints.md
• 🎨 PlantUML Diagram: 196-health-check-endpoints.puml
• 🖼️ Diagram Image: 196-health-check-endpoints.png

---

This issue body was auto-generated from the PRD. Original issue content is preserved in the PRD document.
Last updated: 2025-10-10